CLAUDE.md

Conventions for working in this repo. These are the ones an agent gets wrong without being told; everything else, read from the code.

Comments

Write a comment only when the information is not obtainable from reading the code. Then keep it concise.

Earns its place:

• A constraint with no syntax — a construction order one factory depends on, why an unused await is not dead code, why a magic number in an assertion is 3.
• A domain fact the file cannot show — a single-account server answering RepoNotFound for any other DID.
• A current bug or quirk an assertion would otherwise look wrong against.

Delete otherwise:

• Restating the signature, the type, or the next line.
• Announcing what a well-named function does.
• Boilerplate repeated across sibling files.
• Justifying the design decision that produced the code. That belongs in the commit message.
• Meta-framing: "documents a bug rather than endorsing it", "note that…".

Phrase what stays plainly. Four rules, taken from ASD-STE100 — the parts of it that transfer to code. This is a house style, not a compliance claim; the standard's approved-word list is not applied.

• One idea per sentence. Twenty words maximum.
• Active voice. Keep the articles. Not "Only guards this isolate" but "This flag applies to one isolate".
• No metaphorical verbs. A catch receives an error; it does not swallow it. Code does not sit, live, bail, wrap, punt, or massage.
• The same word for the same thing, every time. Not handler in one line and endpoint in the next.

The third rule is the one that earns its place. A metaphorical verb is the most common way a comment reads well and means two things.

Describe the present, never the previous arrangement. No "previously X", "used to be Y", "the old 24h cap". In a refactor the tell is usually one small word rather than an explicit "previously":

Don't	Do
"this delegation stays because…"	"the scheduler is reachable here because…"
"accountApi is still bound off the class"	"accountApi binds off the class"
"the handlers that remain methods"	"the handlers that are methods"
"warms the cache the same as before the move"	"the call warms the DID cache"
"handlers extracted out of pds.js get an entry"	"each handler module gets an entry"

Each of those only parses if the reader knows the prior arrangement. Commit messages and changesets are exactly where "what changed relative to before" belongs — that distinction is the point.

Types

No any in JSDoc annotations in library or adapter code. Define real typedefs for row and record shapes, or use the core port types (import('@pdsjs/core/ports').SessionRecord). For genuinely dynamic values, type as unknown and cast at the use site: /** @type {SomeType} */ (value).

Test mocks are the exception — casting a mock storage to /** @type {any} */ on the way into a typed constructor is the established pattern across this suite.

Prefer structural types for a handler module's context over indexing off the class (PersonalDataServer['accountApi']). An indexed annotation breaks as soon as the method it names moves.

User-facing copy

No em dashes in anything a user sees — UI strings, banners, notices. Split the clauses into separate sentences instead.

Handler modules

The route handlers live in core/src/handlers/*.js, following the shape @pdsjs/spaces uses: a createXHandlers(ctx) factory taking an explicit context and returning a route table fragment, merged into this.routes in the PersonalDataServer constructor alongside spaceRoutes. The class keeps dispatch, authentication, and the commit and blob machinery.

docs/pds-decomposition.md is the record of how the handlers got there and the mistakes that cost time. Read it before moving code out of pds.js.

• Name helpers for what they know (crypto, mst, scope), handlers for what they serve (xrpc-sync, account-api). The handlers/ prefix avoids colliding with the same-named helper modules in core/src/.
• Handler modules stay out of the package export map.
• Never mix a move with a logic change in one commit. This touches DPoP, client auth and grants; bisectability is the safety net.
• Before moving a cluster, check inbound references from elsewhere in the same file, not just other packages. handleApiOverview called this.backupsAvailable() from 1,500 lines away and broke three tests.

Account interface

Two route tables describe /account, and they do not match. The React routes are in packages/account-ui/src/app.jsx. The SECTIONS array in core/src/account-ui.js feeds the server-rendered shell, and it names paths the React router does not have. A request for a SECTIONS-only path renders the same page as /account, with no error. Take the routes from app.jsx.

Checks

npm run ci is the gate CI runs: build:ui, biome, tsc --noEmit, then test:coverage. CI enforces it on every push, so run the targeted steps below while iterating and the full gate before committing.

• pnpm install, not npm install. The workspace dependencies use the workspace:* protocol and npm exits with EUNSUPPORTEDPROTOCOL. CI installs with pnpm install --frozen-lockfile. The npm run scripts work either way.
• npm run build:ui first on a fresh clone. @pdsjs/account-ui exports a gitignored bundle, and without it the node and cloudflare entrypoints fail to resolve.
• Two typecheck projects, both run by npm run typecheck. tsconfig.json covers the server packages against Workers and node types. tsconfig.ui.json covers the browser packages' src/lib against the DOM, because the Workers types override it and make a Uint8Array unassignable to BodyInit. types/vite-env.d.ts declares the two import.meta.env values, since vite/client resolves only inside a package that depends on vite.
• The .jsx files are in neither project. A component's destructured props read as required, so every call site omitting an optional one is an error: 1738 of them, against 136 for the lib modules. Typing the props is the work that would let them in. Until then noUndeclaredVariables is what catches a missing import there, which is the failure that reaches the browser.
• Coverage floors live in vitest.config.js, per area rather than global. A glob key aggregates every file it matches, so give each module its own entry rather than letting a well-covered one carry a bare one.
• A minor changeset on a package outside the fixed group in .changeset/config.json escalates the whole group to a major release. The mechanism: @pdsjs/node lists the feature packages in peerDependencies, and changesets major-bumps a dependent when a peer moves by minor. version-packages.js rejects the escalation, but only at release time. Mark such packages patch and give the group its own bump line. A new package's first release needs no changeset at all: set its version directly and changeset publish picks up anything not yet on npm.
• Changesets may not mix @pdsjs/account-ui with public packages: it is private and unversioned, and changeset version rejects the mix. Leave it out of frontmatter; describe interface work under the packages that embed the built bundle.
• The e2e suite is not part of the gate; it needs docker-compose. Run it with PLATFORM=node USE_LOCAL_INFRA=false npx vitest run test/e2e.test.js. Three PLC tests fail without the local infra, which is expected. It binds port 2471, so a just dev stack in another workspace will block it.