From cfd16deb77ca0496827765e4c2e73bf8f003b0b4 Mon Sep 17 00:00:00 2001
From: npub19zza5yyr075j4vvlg2drsh2xe0xy3dqxhfchlgtw8vryglrry3gq8q7tzk
 <2885da10837fa92ab19f429a385d46cbcc48b406ba717fa16e3b06447c632450@sprout-oss.stage.blox.sqprod.co>
Date: Tue, 7 Jul 2026 11:48:10 -0700
Subject: [PATCH] docs: scaffold documentation information architecture (Phase
 1)

Add the docs/ skeleton for the full docs implementation: getting-started,
architecture, guides, reference, and vision sections, with a nav/TOC home
page. Every page is a stub carrying its heading outline and pointers to the
source material to be migrated in Phase 2 (content).

docs/nips/, docs/spec/, and the loose design docs stay at their current
paths (55 references from code, tests, and migrations outside docs/);
reference/nips.md and reference/design-docs.md index them instead.

Root GitHub-convention files are untouched. ARCHITECTURE/NOSTR/TESTING/
RELEASING/VISION* remain in place this phase and will become pointer files
in Phase 2.

Co-authored-by: npub19zza5yyr075j4vvlg2drsh2xe0xy3dqxhfchlgtw8vryglrry3gq8q7tzk <2885da10837fa92ab19f429a385d46cbcc48b406ba717fa16e3b06447c632450@sprout-oss.stage.blox.sqprod.co>
Signed-off-by: npub19zza5yyr075j4vvlg2drsh2xe0xy3dqxhfchlgtw8vryglrry3gq8q7tzk <2885da10837fa92ab19f429a385d46cbcc48b406ba717fa16e3b06447c632450@sprout-oss.stage.blox.sqprod.co>
---
 docs/README.md                            | 60 +++++++++++++++++++++++
 docs/architecture/connection-lifecycle.md | 17 +++++++
 docs/architecture/crates.md               | 19 +++++++
 docs/architecture/event-pipeline.md       | 17 +++++++
 docs/architecture/infrastructure.md       | 18 +++++++
 docs/architecture/overview.md             | 17 +++++++
 docs/architecture/protocol.md             | 19 +++++++
 docs/architecture/security-model.md       | 19 +++++++
 docs/architecture/subscriptions.md        | 16 ++++++
 docs/getting-started/installation.md      | 20 ++++++++
 docs/getting-started/local-relay.md       | 17 +++++++
 docs/getting-started/quickstart.md        | 20 ++++++++
 docs/guides/adding-api-endpoints.md       | 17 +++++++
 docs/guides/adding-event-kinds.md         | 16 ++++++
 docs/guides/agents.md                     | 22 +++++++++
 docs/guides/development.md                | 19 +++++++
 docs/guides/nostr-clients.md              | 17 +++++++
 docs/guides/releasing.md                  | 18 +++++++
 docs/guides/self-hosting.md               | 23 +++++++++
 docs/guides/testing.md                    | 20 ++++++++
 docs/guides/workflows.md                  | 19 +++++++
 docs/reference/cli.md                     | 16 ++++++
 docs/reference/configuration.md           | 18 +++++++
 docs/reference/design-docs.md             | 19 +++++++
 docs/reference/known-limitations.md       | 18 +++++++
 docs/reference/nips.md                    | 14 ++++++
 docs/vision/README.md                     | 15 ++++++
 docs/vision/activity.md                   | 13 +++++
 docs/vision/agent.md                      | 13 +++++
 docs/vision/mesh.md                       | 13 +++++
 docs/vision/projects.md                   | 13 +++++
 docs/vision/sovereign.md                  | 13 +++++
 32 files changed, 595 insertions(+)
 create mode 100644 docs/README.md
 create mode 100644 docs/architecture/connection-lifecycle.md
 create mode 100644 docs/architecture/crates.md
 create mode 100644 docs/architecture/event-pipeline.md
 create mode 100644 docs/architecture/infrastructure.md
 create mode 100644 docs/architecture/overview.md
 create mode 100644 docs/architecture/protocol.md
 create mode 100644 docs/architecture/security-model.md
 create mode 100644 docs/architecture/subscriptions.md
 create mode 100644 docs/getting-started/installation.md
 create mode 100644 docs/getting-started/local-relay.md
 create mode 100644 docs/getting-started/quickstart.md
 create mode 100644 docs/guides/adding-api-endpoints.md
 create mode 100644 docs/guides/adding-event-kinds.md
 create mode 100644 docs/guides/agents.md
 create mode 100644 docs/guides/development.md
 create mode 100644 docs/guides/nostr-clients.md
 create mode 100644 docs/guides/releasing.md
 create mode 100644 docs/guides/self-hosting.md
 create mode 100644 docs/guides/testing.md
 create mode 100644 docs/guides/workflows.md
 create mode 100644 docs/reference/cli.md
 create mode 100644 docs/reference/configuration.md
 create mode 100644 docs/reference/design-docs.md
 create mode 100644 docs/reference/known-limitations.md
 create mode 100644 docs/reference/nips.md
 create mode 100644 docs/vision/README.md
 create mode 100644 docs/vision/activity.md
 create mode 100644 docs/vision/agent.md
 create mode 100644 docs/vision/mesh.md
 create mode 100644 docs/vision/projects.md
 create mode 100644 docs/vision/sovereign.md

diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 000000000..25d8f6646
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,60 @@
+# Buzz Documentation
+
+> **Status: skeleton — Phase 1 (structure).** Stub pages carry per-page outlines and
+> source-material pointers; content lands in Phase 2.
+
+## Getting Started
+
+- [Installation](getting-started/installation.md)
+- [Quickstart](getting-started/quickstart.md)
+- [Running a Local Relay](getting-started/local-relay.md)
+
+## Architecture
+
+- [Overview](architecture/overview.md)
+- [Protocol](architecture/protocol.md)
+- [Connection Lifecycle](architecture/connection-lifecycle.md)
+- [Event Pipeline](architecture/event-pipeline.md)
+- [Subscription System](architecture/subscriptions.md)
+- [Crate Reference](architecture/crates.md)
+- [Security Model](architecture/security-model.md)
+- [Infrastructure](architecture/infrastructure.md)
+
+## Guides
+
+- [Development](guides/development.md)
+- [Testing](guides/testing.md)
+- [Working with Agents](guides/agents.md)
+- [Workflows](guides/workflows.md)
+- [Self-Hosting](guides/self-hosting.md)
+- [Using Third-Party Nostr Clients](guides/nostr-clients.md)
+- [Adding a New Event Kind](guides/adding-event-kinds.md)
+- [Adding a New API Endpoint](guides/adding-api-endpoints.md)
+- [Releasing](guides/releasing.md)
+
+## Reference
+
+- [CLI Reference](reference/cli.md)
+- [Configuration](reference/configuration.md)
+- [Known Limitations](reference/known-limitations.md)
+- [Buzz NIPs Index](reference/nips.md) → [`nips/`](nips/)
+- [Design Documents Index](reference/design-docs.md) → loose docs + [`spec/`](spec/)
+
+## Vision
+
+- [Vision](vision/README.md) — aspirational direction, **not** current behavior
+
+## Root-Level Docs (stay at repository root)
+
+GitHub-convention files remain at the root: `README.md`, `CONTRIBUTING.md`, `SECURITY.md`,
+`GOVERNANCE.md`, `CODE_OF_CONDUCT.md`, `CHANGELOG.md`, `AGENTS.md`/`CLAUDE.md`.
+
+`ARCHITECTURE.md`, `NOSTR.md`, `TESTING.md`, `RELEASING.md`, and `VISION*.md` are being
+migrated into this tree. In Phase 2 they will be reduced to pointer files once their
+content has moved; they are untouched in Phase 1.
+
+## Note on file locations
+
+`docs/nips/`, `docs/spec/`, and the loose design docs (`docs/*.md`) are referenced by
+code, tests, and migrations (55 references outside `docs/`). They stay at their current
+paths; the `reference/` index pages link to them instead.
diff --git a/docs/architecture/connection-lifecycle.md b/docs/architecture/connection-lifecycle.md
new file mode 100644
index 000000000..16a796c3f
--- /dev/null
+++ b/docs/architecture/connection-lifecycle.md
@@ -0,0 +1,17 @@
+# Connection Lifecycle
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** How clients connect, authenticate, and stay connected to the relay.
+
+## Outline
+
+- WebSocket connect + auth handshake
+- Session state
+- Reconnection/backoff
+- Disconnect handling
+
+## Source material
+
+- `ARCHITECTURE.md` §3 Connection Lifecycle
+- `crates/buzz-ws-client`, `crates/buzz-relay`
diff --git a/docs/architecture/crates.md b/docs/architecture/crates.md
new file mode 100644
index 000000000..f698b80c9
--- /dev/null
+++ b/docs/architecture/crates.md
@@ -0,0 +1,19 @@
+# Crate Reference
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** One-paragraph-per-crate map of the Rust workspace (24 crates).
+
+## Outline
+
+- Workspace layout
+- Relay-side crates
+- Client/SDK crates
+- Agent crates (buzz-acp, buzz-agent, buzz-dev-mcp, buzz-persona)
+- Tooling crates (git-credential-nostr, git-sign-nostr, sprig, ...)
+
+## Source material
+
+- `ARCHITECTURE.md` §6 Crate Reference
+- `Cargo.toml` workspace members
+- per-crate `README.md`s (note: `crates/buzz-cli/README.md` has known drift — verify against code)
diff --git a/docs/architecture/event-pipeline.md b/docs/architecture/event-pipeline.md
new file mode 100644
index 000000000..2979517d4
--- /dev/null
+++ b/docs/architecture/event-pipeline.md
@@ -0,0 +1,17 @@
+# Event Pipeline
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** The path of an event through the relay: ingest, validation, persistence, fan-out.
+
+## Outline
+
+- Ingest and validation
+- Persistence (buzz-db)
+- Fan-out / pubsub
+- Error handling and rejection
+
+## Source material
+
+- `ARCHITECTURE.md` §4 Event Pipeline
+- `crates/buzz-relay/src/handlers/`, `crates/buzz-pubsub`, `crates/buzz-db`
diff --git a/docs/architecture/infrastructure.md b/docs/architecture/infrastructure.md
new file mode 100644
index 000000000..d8d9d30f0
--- /dev/null
+++ b/docs/architecture/infrastructure.md
@@ -0,0 +1,18 @@
+# Infrastructure
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Runtime infrastructure: storage, search, media, metrics, deployment topology.
+
+## Outline
+
+- Storage (DB, object storage)
+- Search (buzz-search)
+- Media (buzz-media)
+- Metrics/observability (prometheus)
+- Deployment topology
+
+## Source material
+
+- `ARCHITECTURE.md` §8 Infrastructure
+- `prometheus.yml`, `deploy/`, `docker-compose*.yml`
diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md
new file mode 100644
index 000000000..c652fc208
--- /dev/null
+++ b/docs/architecture/overview.md
@@ -0,0 +1,17 @@
+# Architecture Overview
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Executive summary of the Buzz system: what it is, the relay-centric model, major components and how they fit.
+
+## Outline
+
+- What Buzz is
+- System diagram: relay, clients (desktop/web/mobile/CLI), agents
+- Design principles
+- Component map
+
+## Source material
+
+- `ARCHITECTURE.md` §1 Executive Summary
+- `README.md` intro
diff --git a/docs/architecture/protocol.md b/docs/architecture/protocol.md
new file mode 100644
index 000000000..6bef209b6
--- /dev/null
+++ b/docs/architecture/protocol.md
@@ -0,0 +1,19 @@
+# Protocol
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** The Buzz protocol: Nostr foundation, event kinds, Buzz-specific extensions (NIPs). Protocol semantics only — client-interop how-to lives in guides/nostr-clients.md.
+
+## Outline
+
+- Nostr foundation (events, kinds, tags, signatures)
+- Buzz event kinds
+- Buzz NIP extensions (index + one-liners, links to reference)
+- Auth model (NIP-42/NIP-43/NIP-98 as applicable)
+
+## Source material
+
+- `ARCHITECTURE.md` §2 The Protocol
+- `NOSTR.md` (protocol-semantics half only — see split note)
+- `docs/nips/` (linked, not duplicated)
+- `crates/buzz-core/src/kind.rs`
diff --git a/docs/architecture/security-model.md b/docs/architecture/security-model.md
new file mode 100644
index 000000000..172325c50
--- /dev/null
+++ b/docs/architecture/security-model.md
@@ -0,0 +1,19 @@
+# Security Model
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Trust boundaries, authentication, authorization, and known security properties. Vulnerability reporting stays in root SECURITY.md.
+
+## Outline
+
+- Trust model and boundaries
+- Identity and key handling
+- AuthN/AuthZ (channel membership, admin)
+- Multi-tenant isolation (links to formal specs)
+- Reporting vulnerabilities → ../../SECURITY.md
+
+## Source material
+
+- `ARCHITECTURE.md` §7 Security Model
+- `SECURITY.md` (stays at root; link only)
+- `docs/multi-tenant-relay.md`, `docs/spec/` (linked)
diff --git a/docs/architecture/subscriptions.md b/docs/architecture/subscriptions.md
new file mode 100644
index 000000000..d6ed34d6c
--- /dev/null
+++ b/docs/architecture/subscriptions.md
@@ -0,0 +1,16 @@
+# Subscription System
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** How subscriptions and filters work; live query delivery to clients.
+
+## Outline
+
+- Subscription model and filters
+- Live delivery
+- Limits and performance considerations
+
+## Source material
+
+- `ARCHITECTURE.md` §5 Subscription System
+- `crates/buzz-pubsub`
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
new file mode 100644
index 000000000..870787fda
--- /dev/null
+++ b/docs/getting-started/installation.md
@@ -0,0 +1,20 @@
+# Installation
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** How to install Buzz on each platform (desktop app, relay binary, CLI, mobile). New content.
+
+## Outline
+
+- Supported platforms
+- Desktop app (macOS/Windows/Linux)
+- Relay (binary, Docker)
+- CLI (`buzz`)
+- Mobile (iOS/Android status)
+- Verifying the install
+
+## Source material
+
+- `README.md` (intro, install pointers)
+- `RELEASING.md` §Platform Support, §What Gets Published
+- `Dockerfile`, `docker-compose.yml`
diff --git a/docs/getting-started/local-relay.md b/docs/getting-started/local-relay.md
new file mode 100644
index 000000000..b17df7f68
--- /dev/null
+++ b/docs/getting-started/local-relay.md
@@ -0,0 +1,17 @@
+# Running a Local Relay
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Full local-relay workflow for development: build, run, smoke-test with the CLI.
+
+## Outline
+
+- Build and run options (cargo, just recipes)
+- Debug vs release gotchas
+- Smoke-testing with `buzz` CLI (keypair, channel, messages, threads)
+- Troubleshooting
+
+## Source material
+
+- `TESTING.md` §Live Local Relay, §Troubleshooting
+- `Justfile` relay recipes
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
new file mode 100644
index 000000000..b54eea158
--- /dev/null
+++ b/docs/getting-started/quickstart.md
@@ -0,0 +1,20 @@
+# Quickstart
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Zero-to-first-message: start a relay, create a channel, send a message, mention an agent. New content synthesized from README + TESTING.
+
+## Outline
+
+- Prerequisites
+- Start a local relay
+- Create your identity and a channel
+- Send and read messages
+- Add an agent and @mention it
+- Where to go next
+
+## Source material
+
+- `README.md`
+- `TESTING.md` §Live Local Relay (steps 1–4), §ACP Harness
+- `examples/countdown-bot`, `examples/meadow-core` (pointer)
diff --git a/docs/guides/adding-api-endpoints.md b/docs/guides/adding-api-endpoints.md
new file mode 100644
index 000000000..790ba7464
--- /dev/null
+++ b/docs/guides/adding-api-endpoints.md
@@ -0,0 +1,17 @@
+# Adding a New API Endpoint
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Step-by-step recipe for adding an HTTP/RPC endpoint to the relay.
+
+## Outline
+
+- Routing and handler placement
+- Auth requirements
+- Persistence and errors
+- Tests
+
+## Source material
+
+- `CONTRIBUTING.md` §How to Add a New API Endpoint
+- `crates/buzz-relay/src/api/`
diff --git a/docs/guides/adding-event-kinds.md b/docs/guides/adding-event-kinds.md
new file mode 100644
index 000000000..704ea6ab3
--- /dev/null
+++ b/docs/guides/adding-event-kinds.md
@@ -0,0 +1,16 @@
+# Adding a New Event Kind
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Step-by-step recipe for introducing a new event kind end-to-end (core → relay → clients).
+
+## Outline
+
+- When to add a kind vs reuse
+- Step-by-step (kind.rs, validation, persistence, client handling, tests)
+- Conformance/NIP documentation expectations
+
+## Source material
+
+- `CONTRIBUTING.md` §How to Add a New Event Kind
+- `crates/buzz-core/src/kind.rs`
diff --git a/docs/guides/agents.md b/docs/guides/agents.md
new file mode 100644
index 000000000..476378e66
--- /dev/null
+++ b/docs/guides/agents.md
@@ -0,0 +1,22 @@
+# Working with Agents
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Running agents against a relay: the ACP harness, agent identity, memory, personas, and example agents.
+
+## Outline
+
+- Agent model overview (buzz-acp harness, buzz-agent)
+- Minting an agent identity + channel membership (sharp edges called out)
+- Running buzz-acp (env, ws:// vs http://)
+- Core memory / NIP-AE prompt injection
+- Personas (buzz-persona)
+- Examples: countdown-bot, meadow-core
+- Troubleshooting (idle agent, quiet stdout)
+
+## Source material
+
+- `TESTING.md` §ACP Harness
+- `crates/buzz-acp`, `crates/buzz-agent/README.md`, `crates/buzz-persona`
+- `examples/countdown-bot`, `examples/meadow-core`
+- `docs/MCP_DRIVEN_HOOKS.md` (linked)
diff --git a/docs/guides/development.md b/docs/guides/development.md
new file mode 100644
index 000000000..74df3fe8a
--- /dev/null
+++ b/docs/guides/development.md
@@ -0,0 +1,19 @@
+# Development Guide
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Setting up a dev environment, code style, and PR workflow. Root CONTRIBUTING.md remains the canonical entry point and will link here.
+
+## Outline
+
+- Environment setup (clone, Hermit, bootstrap, hooks)
+- Repo layout tour
+- Code style (Rust, TS/biome)
+- Running checks locally (Justfile)
+- PR workflow and review expectations
+- License/CLA pointer
+
+## Source material
+
+- `CONTRIBUTING.md` §Setting Up, §Code Style, §Making a Pull Request, §License and CLA
+- `Justfile`, `lefthook.yml`, `biome.json`
diff --git a/docs/guides/nostr-clients.md b/docs/guides/nostr-clients.md
new file mode 100644
index 000000000..492e3b2b8
--- /dev/null
+++ b/docs/guides/nostr-clients.md
@@ -0,0 +1,17 @@
+# Using Third-Party Nostr Clients
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Operational how-to for connecting standard Nostr clients to a Buzz relay: setup, allowlisting, debugging with nak.
+
+## Outline
+
+- Compatibility overview
+- Client setup
+- Allowlisting users
+- Debugging with `nak` (recipes)
+- Troubleshooting interop
+
+## Source material
+
+- `NOSTR.md` (operational half: client setup, allowlist, nak recipes, troubleshooting)
diff --git a/docs/guides/releasing.md b/docs/guides/releasing.md
new file mode 100644
index 000000000..4b9280242
--- /dev/null
+++ b/docs/guides/releasing.md
@@ -0,0 +1,18 @@
+# Release Guide
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Cutting desktop, relay, and mobile releases. Root RELEASING.md will be migrated here and left as a pointer.
+
+## Outline
+
+- Quick start (desktop/relay/mobile)
+- How the release automation works
+- Release types + version files
+- Manual fallback
+- Internal releases
+- Prerequisites + troubleshooting
+
+## Source material
+
+- `RELEASING.md` (full migration)
diff --git a/docs/guides/self-hosting.md b/docs/guides/self-hosting.md
new file mode 100644
index 000000000..4928b3fcf
--- /dev/null
+++ b/docs/guides/self-hosting.md
@@ -0,0 +1,23 @@
+# Self-Hosting Buzz
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Deploying and operating your own relay: Docker Compose VPS bundle, Helm chart, TLS, membership administration, multi-tenancy.
+
+## Outline
+
+- Deployment options overview
+- Docker Compose bundle (run.sh, Caddy TLS)
+- Kubernetes (Helm chart)
+- Relay configuration (env vars)
+- Membership + admin (buzz-admin, NIP-43 allowlist)
+- Multi-tenant operation (links to design docs/specs)
+- Upgrades and backups
+
+## Source material
+
+- `deploy/compose/README.md`, `deploy/charts/buzz/README.md`
+- `Dockerfile`, `docker-compose.yml`
+- `NOSTR.md` (allowlist/admin operational half)
+- `docs/multi-tenant-relay.md`, `docs/multi-tenant-conformance.md` (linked)
+- `crates/buzz-admin`
diff --git a/docs/guides/testing.md b/docs/guides/testing.md
new file mode 100644
index 000000000..a3f18935c
--- /dev/null
+++ b/docs/guides/testing.md
@@ -0,0 +1,20 @@
+# Testing Guide
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Running and writing tests: unit, e2e, desktop, conformance.
+
+## Outline
+
+- Test suites overview
+- Unit tests (cargo)
+- E2E tests (buzz-test-client)
+- Desktop tests (playwright)
+- Conformance (buzz-conformance)
+- CLI smoke-testing against a live relay
+
+## Source material
+
+- `TESTING.md` §Automated Tests + CLI smoke sections
+- `CONTRIBUTING.md` §Running Tests
+- `desktop/playwright.config.ts`, `crates/buzz-conformance`
diff --git a/docs/guides/workflows.md b/docs/guides/workflows.md
new file mode 100644
index 000000000..f4805dfc5
--- /dev/null
+++ b/docs/guides/workflows.md
@@ -0,0 +1,19 @@
+# Workflows
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** YAML workflow automation: triggers, actions, templates, approval gates.
+
+## Outline
+
+- Workflow model
+- Triggers (4)
+- Actions (7)
+- Templates and variables
+- Approval gates
+- Known limitations (WF-07/WF-08 stubbed actions — be explicit)
+
+## Source material
+
+- `crates/buzz-workflow`
+- fable01's survey: `RESEARCH/BUZZ_DOCS_CONTENT_NOTES_2026_07_07.md` (workspace, not repo)
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
new file mode 100644
index 000000000..1ccc9ed90
--- /dev/null
+++ b/docs/reference/cli.md
@@ -0,0 +1,16 @@
+# CLI Reference
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Command-by-command reference for the `buzz` CLI, derived from --help output and verified against `crates/buzz-cli` source (README has known drift).
+
+## Outline
+
+- Global flags, env vars (BUZZ_RELAY_URL, BUZZ_PRIVATE_KEY, BUZZ_AUTH_TAG), exit codes
+- Command groups: messages, channels, canvas, reactions, dms, users, workflows, feed, social, repos, upload, mem
+- Examples per group
+
+## Source material
+
+- `buzz --help` and per-group `--help` (primary)
+- `crates/buzz-cli/src/` (verify — do not trust `crates/buzz-cli/README.md`)
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
new file mode 100644
index 000000000..7eccd009a
--- /dev/null
+++ b/docs/reference/configuration.md
@@ -0,0 +1,18 @@
+# Configuration Reference
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** All environment variables and config knobs for relay, CLI, and agent harness.
+
+## Outline
+
+- Relay configuration
+- CLI configuration
+- Agent harness (buzz-acp) configuration incl. BUZZ_ACP_NO_MEMORY
+- Desktop app settings (pointer)
+
+## Source material
+
+- `TESTING.md` §Configuration reference
+- `deploy/compose/README.md` env tables
+- crate sources for env var reads
diff --git a/docs/reference/design-docs.md b/docs/reference/design-docs.md
new file mode 100644
index 000000000..1bec4465c
--- /dev/null
+++ b/docs/reference/design-docs.md
@@ -0,0 +1,19 @@
+# Design Documents Index
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Index of the loose design docs and formal specs (kept at their current paths — referenced by code/tests; do not move).
+
+## Outline
+
+- `docs/MCP_DRIVEN_HOOKS.md` — MCP-driven lifecycle hooks
+- `docs/bridge-channel-window.md` — bridge /query channel window (defers to NIP-CW)
+- `docs/git-on-object-storage.md` — git refs over object storage (formal spec, pairs with docs/spec/GitOnObjectStore.tla)
+- `docs/mesh-llm-local-build.md` — mesh LLM local build prereqs
+- `docs/multi-tenant-relay.md` — multi-tenant relay formal spec (pairs with docs/spec/MultiTenantRelay.tla, MultiTenantAuth.spthy)
+- `docs/multi-tenant-conformance.md` — multi-tenant conformance checklist
+
+## Source material
+
+- `docs/*.md` loose files
+- `docs/spec/` TLA+/Tamarin models
diff --git a/docs/reference/known-limitations.md b/docs/reference/known-limitations.md
new file mode 100644
index 000000000..0237ecab2
--- /dev/null
+++ b/docs/reference/known-limitations.md
@@ -0,0 +1,18 @@
+# Known Limitations
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Honest list of current gaps and stubbed features. Goal: no surprises for operators or contributors.
+
+## Outline
+
+- Relay limitations (e.g. rate limiting unenforced)
+- Workflow stubs (WF-07/WF-08)
+- Client/platform gaps
+- Docs debt (empty GOVERNANCE.md pointer file, buzz-cli README drift)
+
+## Source material
+
+- `ARCHITECTURE.md` §9 Known Limitations
+- `crates/buzz-conformance/LIMITS.md`
+- fable01's discrepancy list (survey)
diff --git a/docs/reference/nips.md b/docs/reference/nips.md
new file mode 100644
index 000000000..a819c9473
--- /dev/null
+++ b/docs/reference/nips.md
@@ -0,0 +1,14 @@
+# Buzz NIPs Index
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Index of the 13 Buzz protocol extensions in ../nips/ (kept at docs/nips/ — referenced by code and tests; do not move). One-line summary + status per NIP. NIP-CW is normative for channel-window behavior (bridge-channel-window.md defers to it).
+
+## Outline
+
+- Table: NIP id → title → one-line summary → status
+- Reading order / dependency notes
+
+## Source material
+
+- `docs/nips/NIP-*.md` (13 files)
diff --git a/docs/vision/README.md b/docs/vision/README.md
new file mode 100644
index 000000000..3f416638a
--- /dev/null
+++ b/docs/vision/README.md
@@ -0,0 +1,15 @@
+# Vision
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Aspirational direction — NOT current behavior. Quarantined from the rest of the docs so vision statements are never mistaken for shipped features.
+
+## Outline
+
+- The relay is the workspace (core vision)
+- Index of sub-visions: activity, agent, mesh, projects, sovereign
+
+## Source material
+
+- `VISION.md` (full migration)
+- `VISION_*.md` (5 files → sibling pages)
diff --git a/docs/vision/activity.md b/docs/vision/activity.md
new file mode 100644
index 000000000..80381fdc8
--- /dev/null
+++ b/docs/vision/activity.md
@@ -0,0 +1,13 @@
+# Vision: Activity
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Aspirational — not current behavior. Full migration of root VISION_ACTIVITY.md.
+
+## Outline
+
+- Migrate VISION_ACTIVITY.md content as-is, edited only for docs-tree link consistency
+
+## Source material
+
+- `VISION_ACTIVITY.md`
diff --git a/docs/vision/agent.md b/docs/vision/agent.md
new file mode 100644
index 000000000..a3e51abe1
--- /dev/null
+++ b/docs/vision/agent.md
@@ -0,0 +1,13 @@
+# Vision: Agent
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Aspirational — not current behavior. Full migration of root VISION_AGENT.md.
+
+## Outline
+
+- Migrate VISION_AGENT.md content as-is, edited only for docs-tree link consistency
+
+## Source material
+
+- `VISION_AGENT.md`
diff --git a/docs/vision/mesh.md b/docs/vision/mesh.md
new file mode 100644
index 000000000..4e3fe36b3
--- /dev/null
+++ b/docs/vision/mesh.md
@@ -0,0 +1,13 @@
+# Vision: Mesh
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Aspirational — not current behavior. Full migration of root VISION_MESH.md.
+
+## Outline
+
+- Migrate VISION_MESH.md content as-is, edited only for docs-tree link consistency
+
+## Source material
+
+- `VISION_MESH.md`
diff --git a/docs/vision/projects.md b/docs/vision/projects.md
new file mode 100644
index 000000000..84cd8f11e
--- /dev/null
+++ b/docs/vision/projects.md
@@ -0,0 +1,13 @@
+# Vision: Projects
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Aspirational — not current behavior. Full migration of root VISION_PROJECTS.md.
+
+## Outline
+
+- Migrate VISION_PROJECTS.md content as-is, edited only for docs-tree link consistency
+
+## Source material
+
+- `VISION_PROJECTS.md`
diff --git a/docs/vision/sovereign.md b/docs/vision/sovereign.md
new file mode 100644
index 000000000..05866553e
--- /dev/null
+++ b/docs/vision/sovereign.md
@@ -0,0 +1,13 @@
+# Vision: Sovereign
+
+> **Status: stub — Phase 1 (structure).** Content to be written in Phase 2.
+>
+> **Scope:** Aspirational — not current behavior. Full migration of root VISION_SOVEREIGN.md.
+
+## Outline
+
+- Migrate VISION_SOVEREIGN.md content as-is, edited only for docs-tree link consistency
+
+## Source material
+
+- `VISION_SOVEREIGN.md`