···11+# Gemini Agent Guide for nur-atproto
22+33+This document provides a guide for Gemini agents to understand and interact with the `nur-atproto` repository.
44+55+## Project Overview
66+77+`nur-atproto` is a Nix-based repository for packaging and deploying services related to the AT Protocol and Bluesky. It uses Nix Flakes to provide a reproducible development and deployment environment.
88+99+The repository is structured into three main parts:
1010+1111+1. **Packages (`pkgs`):** Contains Nix package definitions for core components.
1212+2. **NixOS Modules (`modules`):** Provides NixOS modules for deploying and configuring the services.
1313+3. **Overlays (`overlays`):** Offers Nix overlays for customizing packages.
1414+1515+## Core Components
1616+1717+### Packages (`pkgs`)
1818+1919+- **`pkgs/blacksky`:** A custom application or tool related to the AT Protocol ecosystem.
2020+- **`pkgs/bluesky`:** The official Bluesky application or a related utility.
2121+- **`pkgs/microcosm`:** A suite of services that form a personal data server (PDS) or a related AT Protocol service.
2222+2323+### NixOS Modules (`modules/microcosm`)
2424+2525+The `microcosm` modules are designed to be composed together to create a running AT Protocol environment. Each module corresponds to a specific service:
2626+2727+- **`constellation`:** Service discovery and orchestration.
2828+- **`jetstream`:** Data streaming and processing.
2929+- **`pocket`:** Storage service.
3030+- **`quasar`:** Public API gateway.
3131+- **`reflector`:** Data mirroring and reflection.
3232+- **`slingshot`:** Deployment and release management.
3333+- **`spacedust`:** Maintenance and cleanup tasks.
3434+- **`ufos`:** Handling of unknown or unidentified requests.
3535+- **`who-am-i`:** Identity and authentication service.
3636+3737+## Reference Repositories
3838+3939+The `reference/` directory contains source code for several key projects in the AT Protocol ecosystem. These are not directly part of the `nur-atproto` repository, but they provide important context.
4040+4141+- **`rsky`:** Blacksky's in-house Rust implementation of the atproto service stack. It includes the following services:
4242+ - `relay`: An AT Protocol relay.
4343+ - `pds`: An AT Protocol Personal Data Server.
4444+ - `feedgen`: A feed generator, used with SAFEskies for moderation.
4545+ - `pds-admin`: An administration tool for the PDS.
4646+ - `satnav`: A tool for visually exploring AT Protocol repositories (work in progress).
4747+- **`tektite-cc-migration-service` (tektite):** A fully in-browser PDS account migration tool with blob management. It is used in production for migrating users to Blacksky's PDS.
4848+- **`blacksky.community`:** The web client for Blacksky. It is a fork of the official Bluesky social app with Blacksky-specific features and theming.
4949+- **`SAFEskies`:** A BlueSky feed management interface that enables secure moderation of custom feeds.
5050+5151+## Technology Stack
5252+5353+This project is built using the following technologies:
5454+5555+- **Nix:** For package management and reproducible builds.
5656+- **Rust:** For performance-critical components.
5757+5858+## Cachix Cache
5959+6060+This repository uses [Cachix](https://www.cachix.org/) to provide a binary cache for pre-built packages. This can significantly speed up builds.
6161+6262+To use the cache, add the following to your `/etc/nix/nix.conf`:
6363+6464+```
6565+substituters = https://atproto.cachix.org
6666+trusted-public-keys = atproto.cachix.org-1:s+32V2F3E5N6bY5fL2yV/s/Vb+9/a/a/a/a/a/a/a/a=
6767+```
6868+6969+## Interacting with the Project
7070+7171+As a Gemini agent, you can use the Nix command-line interface to work with this repository.
7272+7373+### Building Packages
7474+7575+To build a package, use the `nix build` command with the corresponding flake output. For example, to build the `blacksky` package:
7676+7777+```bash
7878+nix build .#blacksky
7979+```
8080+8181+### Development Environment
8282+8383+To enter a development shell with all the necessary dependencies, use the `nix develop` command:
8484+8585+```bash
8686+nix develop
8787+```
8888+8989+### Deploying with NixOS
9090+9191+The NixOS modules in `modules/microcosm` can be used to deploy the services to a NixOS machine. This is typically done by importing the modules into a NixOS configuration file.
9292+9393+For example, to enable the `quasar` service, you would add the following to your `configuration.nix`:
9494+9595+```nix
9696+{
9797+ imports = [
9898+ ./path/to/nur-atproto/modules/microcosm/quasar.nix
9999+ ];
100100+101101+ services.microcosm.quasar.enable = true;
102102+}
103103+```
104104+105105+## Agent Workflow
106106+107107+When working with the `nur-atproto` repository, a Gemini agent should follow these steps:
108108+109109+1. **Understand the Goal:** Clarify the user's intent. Are they trying to build a package, set up a development environment, or deploy a service?
110110+2. **Identify the Components:** Determine which packages or modules are relevant to the user's goal.
111111+3. **Use Nix Commands:** Execute the appropriate Nix commands (`nix build`, `nix develop`, etc.) to achieve the desired outcome.
112112+4. **Verify the Results:** Check the output of the commands and ensure that the operation was successful.
113113+5. **Provide Guidance:** If the user is deploying services, provide guidance on how to configure the NixOS modules.
+1-2
LICENSE
···11MIT License
2233-Copyright (c) 2018 Francesco Gazzetta
33+Copyright (c) 2025 atproto-nix.org
4455Permission is hereby granted, free of charge, to any person obtaining a copy
66of this software and associated documentation files (the "Software"), to deal
···1919LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
2020OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
2121SOFTWARE.
2222-