docs: refresh AGENTS.md structure, single-test runbook, pubkey guard

[yhc007]

Summary

Refreshes AGENTS.md (symlinked as CLAUDE.md) in four places where it had drifted from the tree or was silent on something an agent will get wrong:

• Repo Structure was stale. Seven crates were missing — buzz-deletion, buzz-relay-mesh, buzz-push-gateway, buzz-voice, buzz-backend-kubernetes, buzz-conformance, buzz-datastore-tracing — along with five top-level directories: admin-web/, benchmarks/, examples/, deploy/, docs/.

• New "Running a single test" section. The doc had no per-stack single-test invocation at all, and these aren't guessable: desktop unit tests are node:test over src/**/*.test.mjs behind a custom type-stripping loader (not vitest), admin-web is vitest, and web/ has Playwright only. The section also records that nothing runs cargo test --workspace — just test-unit enumerates packages explicitly (Justfile:313), so a new crate gets clippy and check from workspace membership but zero executed tests until it's added to that list. The Justfile comments say this repeatedly; AGENTS.md never did.

• check:pubkey-truncation documented next to the existing check:px-text rule. Same shape (path:line allowlist), and the rationale is non-obvious: truncated pubkey prefixes are forgeable by vanity grinding, so display truncation must go through truncatePubkey / <PubKey>.

• Protocol docs linked. Key Patterns and See Also pointed only at the upstream nostr-protocol repo, not at docs/nips/, docs/spec/MultiTenantRelay.tla, or NOSTR.md.

Docs only — no code, no behavior change.

Related issue

None found.

Testing

just file-size-check passes.

Every claim was checked against the tree rather than asserted:

• Crate and directory names read from crates/, Cargo.toml description fields, and each crate's lib.rs header.

• Test-runner claims read from Justfile:313 (test-unit) and the scripts blocks of desktop/, web/, and admin-web/ package.json.

• The documented desktop invocation was executed after installing workspace deps:

  $ cd desktop && node --import ./test-loader.mjs --experimental-strip-types \
      --test src/app/RootErrorBoundary.test.mjs
  ✔ ThemeProvider renders defaults when localStorage reads are denied (2470ms)
  ✔ root boundary shows recovery UI without exposing error details (83ms)
  ℹ tests 2  ℹ pass 2  ℹ fail 0
  

• Referenced spec files confirmed present: docs/nips/NIP-AA.md, NIP-PL.md, NIP-MP.md, the NIP-FI* family, and docs/spec/MultiTenantRelay.tla. An earlier draft cited "NIP-AB" as a docs/nips/ example — that crate exists but the spec file does not, so the examples were corrected.

Not run on this machine: the Rust, Playwright, and Flutter invocations in the new section are standard forms I did not execute. just setup fails here before installing anything (no Docker; the Hermit-pinned pnpm also can't start — missing libatomic.so.1), so the full suite and integration lanes were out of reach. Both are local environment limits, unrelated to this change.

🤖 Generated with Claude Code