# Working on Monolith For every agent working here: CLAUDE.md is this file, imported. What the project is, and what is built, is in `README.md`; what is not yet built is its "Known gaps". How the server is run, called, deployed, operated and checked is in the guides in `docs/guide/`. ## How a change is made The PDS is built from its specification, and checked against the reference PDS, so a change goes in this order: 1. **The spec.** What the server does is in `spec/PDS.md` and the page of each area it links (`spec/REPO.md`, `spec/SYNC.md`, ...), its MCP tools and CLI commands in `spec/COMMANDS.md`, and the methods themselves in the lexicons under `spec/lexicons`. A change in behaviour is written there first, as what is, not as a plan. A new area gets a page of its own, linked from `spec/PDS.md`. 2. **The harness.** `harness/compare.mjs` gets a check for it, in the module of its area under `harness/checks/` (a new area's module, and its steps in `compare.mjs`'s list): against the reference where the reference can say, and against the spec where it cannot. Every random draw comes from `harness/lib/random.mjs`, so a seed makes the same requests every run. A check is made stricter or fixed, never loosened so that a server passes. Run against the server as it was, the new check must fail. A check cites the section it holds the server to, as `(spec/LIFECYCLE.md, "deactivateAccount")` (`spec/PDS.md`, "How it is checked"); renaming a heading moves its citations with it. A check names no implementation: what it may take of the server beyond the protocol it asks `harness/lib/server.mjs`, and another PDS joins the compatibility check as `compat/README.md`, "Adding an implementation", says, leaving Monolith's runs as they were. 3. **The server.** `crates/`, and `web/` for the authorization pages (`web/AGENTS.md`), are built from `spec/` alone, by an agent given these rules: - change only the crates named for the change; a new crate goes in `crates/`, named as its directory, with its versions in the root `Cargo.toml`'s `[workspace.dependencies]`; - a new area's methods go in a module of their own in `pds-server`, named in its `AREAS` in `lib.rs`; - read no source of the reference PDS (the `@atproto/*` packages under `harness/node_modules`, its pages' `@atproto/oauth-provider-ui` among them), of an atproto or MCP SDK, or of the MCP conformance suite; `harness/compare.mjs` and its modules may be read, to see what is checked; - add no atproto or MCP crates; - where the spec or the harness seems wrong, stop and say why, rather than work around it. The whole of `crates/` can be built again from nothing this way, to see whether the spec is enough: an agent given an empty `crates/` and no history. There, where the spec is silent and the harness settles it, it follows the harness and lists each such gap, which then becomes a spec change and a harness check. 4. **Proof that the check bites.** Plant the bug the new check is for in the server, see the harness fail, and put the server back. 5. **The gates, on the runner.** Not on this machine: several agents running the harness here at once have brought it down. Push the branch and open the pull early; the `gates` workflow runs `just gates` on each push to it. Read what it says with `knotless run list knotless://chadtmiller.com/monolith --pull --wait --log`. While working, `just quick` here, alone, and of `cargo test` only the tests of what was changed, by name: the whole of it takes a quarter of an hour on this machine when others use it, and under a minute on the runner, so the whole suite is run by a push. The runner is one machine: pushes wait their turn, and a benchmark asked for beside the gates slows both. What is compiled for macOS alone is run here, and for Linux alone there. When a gate fails in a way its log does not explain, run that one run here, alone. A change to how the server stores or syncs, or to its speed, runs `just nightly` here too: the long crash runs and the performance step, which otherwise only the `nightly` workflow runs, on `main`, after it merges. A change to how the server is run, deployed, called or checked updates its guide in `docs/guide/` in the same pull, as a change in behaviour updates the spec. A change that those who run the server or call it see adds a change file to `.changeset/` in the same pull, from which the next release's `CHANGELOG.md` is written (`docs/guide/contributing.md`, "Releases"). The README says what is built, not how it came to be: no history, plans or sessions in it, in `docs/`, or in the spec. ## Tools - Cargo through rustup: `rustup run stable cargo` (the Justfile's `cargo`). - Node is the version `.node-version` names; `cd harness && npm ci` once, and `npx playwright install chromium` for `--pages` and `just look`. - `cd web && npm ci` once: `just build` builds `web/` before `pds`, which embeds it. - The documentation site: `cd docs-site && npm ci` once, then `npm run build`, which fails on a link to a file or heading that is not there, a method `spec/PDS.md` lists under no page, or a variable the spec names in no table of them; `just docs-site` serves it while writing. The `docs` workflow builds it on each pull, and deploys it on each push to `main` that changes it; `just docs-deploy` deploys it by hand. - The spaces run (`harness/spaces/compare.mjs`, `spec/SPACES.md`) checks the server against the pinned spaces alpha of the reference, with its own packages: `cd harness/spaces && npm ci` once; `pin-alpha.sh` re-pins it. ## Branches and pulls The repository is `knotless://chadtmiller.com/monolith`. Work goes on a branch, and into `main` by a pull with `review.knotless.dev` as reviewer; `main` takes a pull only through the merge queue, once that review has passed. `.knotless/review.md` is what the reviewer checks. A change that needs another not yet merged is a pull stacked on that one's branch, and is retargeted to `main` once it merges.