PkRelay docs consolidation: 17 pages to 7, verified by a reviewer agent

What they did

The owner asked for simpler docs, so the author rewrote README.md and docs/ from scratch rather than editing the old pages. Before: 17 files, 1,756 lines. After the first pass: 7 files, 621 lines (-65%); after review fixes, 520 lines. The new set is README.md, docs/setup.md, docs/collaboration.md, docs/discovery.md, docs/monitoring.md, docs/architecture.md and docs/verification.md. Merges were deliberate: host.md + adapter.md became setup.md; collaboration.md absorbed collaboration, dependencies, attention, standing, orders, search and the hub-side rules from wake.md; discovery.md absorbed discovery and wake; monitoring.md absorbed dashboard, activity and analytics; verification.md absorbed verification and dashboard-verification. architecture.md went from 352 lines to 57, dropping the whole Phase-1 design essay, which stays in docs/superpowers as design history. The page was named collaboration.md rather than coordination.md only because the dated retrospective links collaboration.md and had to stay unchanged. docs/superpowers/ and the retrospective were left untouched. Code changes were doc-link comments only: Program.cs and Build-PkRelay.ps1 now point at monitoring.md instead of analytics.md, ApplicationPorts.cs and SqliteStore.Activity.cs point activity.md to monitoring.md, SqliteStore.Standing.cs points standing.md to collaboration.md. No test, .csproj or setup output references a doc, and no test reads doc text. Accuracy was checked against source, not against the old docs: script flags, hub settings and defaults in RelayHostBuilderExtensions, RelayAuthentication, HubNetwork, DiscoveryEndpoints, AnalyticsSnapshotService, AttentionOptions, OrderOptions and RelayLimits; routes in RelayEndpoints and DashboardEndpoints; adapter environment variables and CLI flags; every tool name and admin flag in RelayToolCatalog; domain rules in TaskWorkflow, StandingOrders, AttentionSources and Views.sql; project references, grain keys and SQLite tables. A script checked every Markdown link and anchor. A separate reviewer agent then checked about 30 claims against the source. Its findings landed in commit 1c21adb: a must-fix migration section in setup.md (schema 2 upgrade, pre-migration backup file, older hubs refusing a newer database, the FTS5 requirement), a REST envelope and status-mapping line, an untrusted-input warning in collaboration.md, a variables table in discovery.md, and collaboration.md cut from 198 lines to 102.

How it went

Build clean with 0 warnings and 0 errors. Tests: 594/605 then 595/605, with only the 10 Windows-only SetupTests failing plus one known flake in code the PR does not touch; Core tests 100/100. All Markdown links and anchors resolve, including the retrospective's collaboration.md. The reviewer agent's findings were all fixed in a second commit, and the final in-scope total is 520 lines from 1,756.

Worth knowing

The 10 SetupTests failures are a pre-existing Windows-only baseline, not caused by this change, and the NodeTests waiter flake is known from earlier steps. docs/superpowers/ still mentions old page names in prose and was intentionally left as design history, so it is now stale relative to the new docs. The reviewer agent checked about 30 claims, not every sentence, so defaults and limits outside that set are unverified. The PR is stacked on #12 and depends on that branch.

Wiring

Order matters: inventory and merge plan first, then rewrite from source, then fix code doc-links, then link-check, then build and test, then a reviewer pass with fixes in a second commit.

Config touched: none functionally. Doc-link comments in Program.cs, ApplicationPorts.cs, SqliteStore.Activity.cs, SqliteStore.Standing.cs and Build-PkRelay.ps1 were repointed to the new page names. AdapterOptions.cs kept docs/discovery.md because that page still exists.

Verification commands: dotnet build PkRelay.slnx -c Release; dotnet test PkRelay.slnx -c Release --no-build; dotnet test tests/PkRelay.Core.Tests -c Release. A small script walked README.md and docs/*.md for links and anchors.

Source of truth for the rewrite: RelayHostBuilderExtensions, RelayAuthentication, HubNetwork, DiscoveryEndpoints, AnalyticsSnapshotService, AnalyticsOptions, AttentionOptions, OrderOptions, RelayLimits, RelayEndpoints, DashboardEndpoints, RelayToolCatalog, ToolSchemas, TaskWorkflow, OrderKinds, StandingOrders, AttentionSources, AttentionWeights, Views.sql, ApplicationPorts, CoordinationStateMachine, DiscoveryStateMachine, AnomalyMonitor, DueWorkDispatcher, SqliteStore.Initialize, SetupCommand and the .csproj files.

Try it yourself

Simplify the docs in this repo the way a maintainer would after an owner request.

1. Inventory README.md and docs/*.md: file count, line count per page, and which pages overlap.
2. Propose a merged page set (aim for roughly 7 pages) and show a before/after table of old pages to new pages with line counts. Keep any filename that other files link to, even if the new name would be better.
3. Rewrite each page from the source code, not from the old docs. For every setting, default, CLI flag, route, tool name and domain rule you document, cite the file and symbol you read it from.
4. Update doc-link comments in code and build scripts to the new paths. Do not touch tests, .csproj files or generated output.
5. Run a script that checks every Markdown link and anchor in README.md and docs/*.md resolves.
6. Build and test. Report failures and say which are pre-existing.
7. Then run a second pass as a reviewer: check about 30 factual claims against source, list each finding, and fix them in a follow-up commit. Prioritise anything that would break a user on upgrade (schema migrations, required modules, rollback paths).