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 — the test-unit recipe enumerates packages explicitly, 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

Rebased onto current main and every claim re-verified against that tree, not asserted:

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

• Test-runner claims read from the test-unit recipe in the Justfile and the scripts blocks of desktop/, web/, and admin-web/ package.json. An earlier revision of this PR cited that recipe as Justfile:313; line numbers rot, and it has since moved — the text now names the recipe instead.

• Both documented single-test invocations that this machine can run were executed:

  $ cargo test -p buzz-core event::tests::tampered_signature_fails_verify
  test event::tests::tampered_signature_fails_verify ... ok
  test result: ok. 1 passed; 0 failed; 254 filtered out
  
  $ cd desktop && node --import ./test-loader.mjs --experimental-strip-types \
      --test src/features/agents/agentReuse.test.mjs
  ℹ tests 39  ℹ pass 39  ℹ fail 0
  

  Both examples name real tests: an earlier revision cited event::tests::verifies_sig and a placeholder features/foo/bar.test.mjs, neither of which exists. A reader copying those lines would have hit a filter that matches nothing.

• just file-size-check passes, and the pre-push lanes ran clean on the push.

• 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 cargo nextest, Tauri, Playwright, and Flutter invocations in the new section are standard forms I did not execute (cargo-nextest isn't installed here). just setup fails on this host 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

[github-actions]

🔐 Codex Security Review

Status: review required for the current range.

The current range is 1c8321cd08feb597f8bcff5195c21148fb3e98ed...f3f7a969ea0bcefdde69b7cbbc01a13b171bc7ef.
A new review must complete for this exact range. When manual authorization
is required, a Block organization member must comment exactly
@buzz-security-review f3f7a969ea0bcefdde69b7cbbc01a13b171bc7ef to authorize a new review.
Any previous review applies only to its recorded range.

[yhc007]

@wesbillman — could I get a review on this, or a pointer to whoever on the buzz-oss-team should take it? You've been the most frequent editor of AGENTS.md (#6049, #6187, #6485), so you seemed like the natural person to ask.

Docs-only, no code. Freshly rebased onto main, checks are green, and it's MERGEABLE — just blocked on REVIEW_REQUIRED. I can't add a reviewer myself since this is from a fork.