docs: prepare project documentation for public release

[delkc]

Why

Prepare Buzz's checked-in project documentation for public open-source release. The current docs mix durable public guidance with private infrastructure references, internal decision history, unsupported security claims, and product-direction language that can read as already shipped.

This focused pass makes the repository more useful and trustworthy for external contributors without rewriting current release operations.

What

• Remove private repository inventories and internal contributor links from AGENTS.md and CONTRIBUTING.md.
• Replace the nonexistent conduct@buzz-relay.org address with the Block Open Source Governance Committee contact.
• Correct SECURITY.md claims about authorization boundaries and audit-log guarantees while preserving the team's current buzz@block.xyz vulnerability-reporting process.
• Establish community as the product boundary while retaining workspace as descriptive language and relay for the infrastructure underneath it.
• Add explicit shipped, active-development, and long-term-direction framing across the vision documents.
• Generalize examples and implementation notes that referenced private hosts, identities, internal research files, or personal planning notes.
• Remove a branch-specific onboarding debugging diary containing names, dates, production context, and internal implementation history.
• Require BUZZ_RELAY_URL for just staging instead of silently targeting a private corporate relay.

Scope decisions

Kept

• Architecture, testing, Nostr, deployment, migration, formal-spec, and crate-level documentation that remains code-grounded and useful externally.
• Vision documents that explain meaningful product direction, now with status framing so planned work is not mistaken for shipped behavior.
• Current team guidance in RELEASING.md, the release workflow, and the vulnerability-reporting contact.

Revised

• Contributor, governance, security-design, agent, and vision documentation.
• Specialized docs, examples, and adjacent source comments that exposed private infrastructure or internal context.
• The remote-relay development recipe so the target relay must be selected explicitly.

Removed

• docs/welcome-kickoff-silent-failures.md: an internal debugging diary whose durable implementation behavior is represented in the code and git history.
• docs/moderation/PLAN.md was identified for the same treatment during this audit, then independently removed by cleanup old AI doc #2227 before this branch was pushed.

Risk assessment

Low. Most changes are documentation-only. The one functional adjustment makes just staging require an explicit BUZZ_RELAY_URL; release workflows and application behavior are otherwise unchanged.

Validation

• Rebased onto current main.
• git diff --check.
• Changed-Markdown local-link and code-fence validation.
• Justfile parsing with just --list.
• Biome checks for the two touched TypeScript comment files.
• Repository pre-commit hooks.

References

• README public-release refresh: docs(readme): refresh public project overview #2222
• Public PyPI lockfile follow-up: Regenerate Harbor uv.lock files against public PyPI #2226
• Independently landed moderation-plan cleanup: cleanup old AI doc #2227

Update: July 24, 2026

After recent release and security changes landed on main, this PR was narrowed for review:

• Dropped all changes to RELEASING.md and the release auto-tag workflow.
• Preserved the team's buzz@block.xyz vulnerability-reporting process.
• Dropped the cosmetic ownership edit in ARCHITECTURE.md.
• Retained only the public-reference scrub, governance fixes, security-accuracy corrections, vision status framing, and removal of internal debugging material.

Generated with Codex