mirror of
https://github.com/Monkopedia/rouse-context.git
synced 2026-11-22 05:16:11 +00:00
Closes #654 `docs/test-coverage-audit.md` is split into a verified inventory and a fenced 2026-04-06 snapshot. The inventory half is re-derived against `61c84b93`: per-module counts with the command that reproduces them (288 Kotlin test classes, 21 Rust integration test files), every named class confirmed to resolve, and a new **Subject ships?** column separating "this test is green" from "its subject runs in production". The row that motivated the issue is `TokenStoreTest` — accurate in every word, and still supporting a false inference, because it exercises `InMemoryTokenStore` while production binds `RoomTokenStore`. `RoomTokenStoreTest`, which covers the shipped path, had never been listed. That row is the one a reader could not have caught from the date on the file. The other bad rows failed differently, and review corrected the diagnosis: they were stale, not fictional. `NotificationAdapter` and its test, the `:integration-tests` module, the `:health` module, and the relay wake-endpoint test were all real when the audit named them, and were deleted or moved by a cleanup wave in April 2026. Each removed row now states that the subject is absent at `61c84b93` and names the commit that removed it, rather than asserting it never existed. Exactly one row was ever fictional — `TunnelConnectionStateMachineTest` — and it keeps its own distinct grounds. Note the count chain this document has been through, since it is the argument for the shape: the bridge section read "2 test classes" when there were five; #684 corrected it to "1 test class" when there were four; it is now four, printed from a command rather than maintained by hand. A hand-maintained inventory drifts, and it drifts again in the act of being corrected. `docs/audit.md` records the file as repaired rather than deleted, and carries the same stale-not-fictional framing. Docs only. No code, no behaviour change. `docs/workflow.md:317` is deliberately left alone; it belongs to the separate annotate-don't-rewrite case. Reviewed-by: monkopedia-reviewer
16 KiB
16 KiB
Documentation audit — 2026-04-14
Scope: every .md under docs/, plus top-level README.md and BLOCKERS.md.
Also audited HTML files under docs/ since the issue called them out.
Out of scope: .claude/ rules, KDoc in source, inline code comments.
Totals: 24 markdown files inventoried (23 under docs/ or repo root) + 3 HTML
indexes + icon/screenshot PNGs.
- Current: 8
- Partially stale / needs update: 8
- Rewrite (either for docs/user/ or fresh engineering doc): 2
- Delete / archive: 4
- Not docs (HTML/images in
docs/): 2 directories (plus one HTML sitting directly underdocs/notifications/)
Module-level README.md / BLOCKERS.md files: none exist inside modules.
Top-level BLOCKERS.md is the only one.
Per-doc findings
README.md (repo root)
- Length: 93 lines
- Audience: contributor / user (top-level landing)
- Accuracy: current. Module table lists
:core:bridge, outreach, usage, notifications — all present in the tree. Integration list matches what's shipped. URL formbrave-falcon.abc123.rousecontext.com/health/mcpis the legacy format, not the per-integration form shipped invalid_secrets. Minor stale detail. - User-facing content?: Yes, partially. It's the main marketing/what-is-it surface.
- Recommendation: update. Fix the URL example to match the shipped
per-integration-hostname scheme (
brave-health.cool-penguin...). Otherwise keep as-is. Consider splitting "marketing intro" intodocs/user/index.mdonce the user docs tree exists.
BLOCKERS.md (repo root)
- Length: 190 lines
- Audience: historical
- Accuracy: stale. References T-12 scaffolding blockers (no
:apimodule, no ktlint plugin), an April 2026 FCM-wake flow that "couldn't connect because ACME is stubbed" — all long since resolved (relay uses a real ACME client,:apimodule exists, ktlint/detekt are configured). - User-facing content?: No.
- Recommendation: delete. This was a handoff note between agents during early implementation; everything described here is fixed or superseded by GitHub Issues now.
docs/workflow.md
- Length: 704 lines
- Audience: historical
- Accuracy: stale. Declares "the relay does not exist yet" and lays out
phases 0–6 as a DAG. All phases are shipped. Talks about
mcp-core,mcp-health,tunnelflat modules that were renamed long ago. - User-facing content?: No.
- Recommendation: delete. This was the original implementation roadmap.
GitHub Issues is now the tracking system (per project memory). If a
historical record is wanted, preserve by tagging the last commit that
contains it and then delete from
main.
docs/test-coverage-audit.md
- Length: ~1230 lines
- Audience: engineering
- Accuracy: split, deliberately. Repaired under #654 on 2026-09-02.
The inventory half was rebuilt and verified against
61c84b93— every count is reproducible from a printed command and every named test class was confirmed to exist. Everything from "Gap Analysis" onward is now explicitly fenced as the 2026-04-06 snapshot, with inline annotations where a gap has since been closed. - User-facing content?: No.
- Recommendation: keep, in its current split shape. The earlier
recommendation was to delete, on the grounds that a hand-maintained
inventory drifts. That is still true of an exhaustive one, which is why
the repair replaced the per-class enumeration with per-module counts plus
the command that reproduces them, and names only the classes the document
itself cites. #654 also added a Subject ships? column: a
✓used to mean only that a test existed and passed, which credited production with coverage of a class that never runs. Note that most of the bad rows were ordinary staleness of exactly the kind this entry already described: the April 2026 cleanup wave (#124, #125, #303, and the removal of the orphaned:integration-testsmodule) deleted the code they named, and nobody updated the audit. Only theTokenStorerow failed the other way, staying accurate while supporting a false inference. That one is what #654 is actually about, and it is the one a reader could not have caught from the date on the file.
docs/security.md
- Length: 237 lines
- Audience: user (despite being described as "engineering-focused" in the issue — the prose reads as a user-facing trust explanation: "Your phone's data never touches our servers", trust model, what-you-trust lists). Some sections (certificate architecture, renewal windows) are implementation detail.
- Accuracy: mostly current. Describes per-integration hostnames,
ACME DNS-01, mTLS, OAuth 2.1 with PKCE — all shipped. References
docs/security-audit-2026-04-07.mdanddocs/security-decisions.md. - User-facing content?: Yes, strongly.
- Recommendation: rewrite for
docs/user/security.mdper #119. Keep the implementation-detail parts (certificate architecture, renewal windows, rate limit tables) in a separate engineering doc (docs/engineering/security.mdor keep atdocs/security.md). Trust model + what-you-trust should go user-facing.
docs/security-audit-2026-04-07.md
- Length: 39 lines
- Audience: engineering / historical
- Accuracy: partially stale. Lists 23 findings. Many criticals (redirect URI validation, PKCE format, encrypted storage) were scheduled for "Week 1" and should be verified as addressed.
- User-facing content?: No.
- Recommendation: keep, but update. Annotate each finding with its
resolution status (fixed / accepted per
security-decisions.md/ still open). Without status, it misleads readers into thinking all 23 are still unmitigated.
docs/security-decisions.md
- Length: 40 lines
- Audience: engineering
- Accuracy: current. Companion to
security-audit-2026-04-07.md— records which findings were accepted as risk. Cross-references are valid. - User-facing content?: No.
- Recommendation: keep as-is. Extend as new decisions are made.
docs/self-hosting.md
- Length: 234 lines
- Audience: contributor (users forking and running their own deployment)
- Accuracy: current. Describes Cloudflare DNS, Firebase setup,
keystore generation,
-Pdomain=parameterization, relay systemd unit. Checked:relay_hostname+base_domainfields exist inrelay/src/config.rs; keystore guidance aligns with project rules. - User-facing content?: Partial — "sophisticated user/contributor" not "end user".
- Recommendation: keep, with a minor pass. Candidate to move into
docs/user/self-hosting.mdordocs/contributor/self-hosting.mdwhen that tree exists.
docs/design/overall.md
- Length: 737 lines
- Audience: engineering
- Accuracy: mostly current but long. Early sections (system
architecture, identity model, Firestore schema, end-to-end flows) match
shipped behavior. Later parts are a massive test-case list (items
165–274) that overlaps
test-coverage-audit.mdand the actual test files — that part has drifted. - User-facing content?: No — design detail.
- Recommendation: update. Keep the architecture/flow prose. Cut the embedded test-case enumeration (lines ~590–730) — it's not authoritative since the real tests diverge. Add a pointer to test classes instead.
docs/design/android-app.md
- Length: 377 lines
- Audience: engineering
- Accuracy: partially stale. Module map is missing
:core:bridge,:outreach,:usage— all shipped modules.McpIntegrationinterface sketch matches what exists in:api. - User-facing content?: No.
- Recommendation: update. Reconcile module list with the actual project structure. Low effort.
docs/design/relay.md
- Length: 336 lines
- Audience: engineering
- Accuracy: mostly current. Mux frame format, SNI routing, ACME bootstrap match the code.
- User-facing content?: No.
- Recommendation: keep, minor update pass. Verify subdomain-lookup caching behavior still matches implementation (skim only; flagged as "may have drifted; needs deeper review").
docs/design/relay-api.md
- Length: 769 lines
- Audience: engineering (API reference)
- Accuracy: mostly current. Endpoints
/register,/renew,/wake/:subdomain,/rotate-secret,/ws,/statusall exist underrelay/src/api/. No/request_subdomainmention though — that endpoint does exist in code. Likely minor drift. - User-facing content?: No (API doc for integrators / contributors).
- Recommendation: update. Add
/request-subdomain, cross-check field names against current request/response structs, confirm error code table is accurate. May have drifted; needs deeper review.
docs/design/tunnel-client.md
- Length: 264 lines
- Audience: engineering
- Accuracy: mostly current. KMP structure, mux client responsibilities, FCM dispatch (wake vs renew), state machine all match shipped code. Claim "No reconnect during active streams" may conflict with auto-reconnect-with-backoff behavior added later — flagged as possible drift.
- User-facing content?: No.
- Recommendation: update. Minor reconciliation on reconnect behavior.
docs/design/ui.md
- Length: 633 lines
- Audience: engineering
- Accuracy: partially stale. Screen enumeration (Welcome, Dashboard, etc.) and state model are mostly right. Some screens (e.g. Onboarding as banner vs full screen) evolved per issues like #5 and the overnight plan's non-blocking-onboarding goal. May have drifted; needs a deeper review against current AppNavigation + Screen composables.
- User-facing content?: No.
- Recommendation: update. Could be worth a sweep that cross-checks against actual nav graph and Screen files (per the "verify rendered path" memory rule).
docs/design/per-integration-hostnames.md
- Status: deleted (post-ship proposal). Shipped behavior is
documented in
docs/design/relay-api.mdanddocs/design/overall.md § Per-integration hostnames.
docs/design/secret-prefix-bot-rejection.md
- Status: deleted. Superseded by per-integration-hostnames; the
shipped routing-key design lives in
docs/design/relay-api.mdanddocs/design/overall.md.
docs/design/notifications-integration.md
- Length: 70 lines
- Audience: engineering
- Accuracy: current (short design doc for the notifications module).
Tools listed (
list_active_notifications,search_notification_history, etc.) match what the integration exposes. - User-facing content?: No.
- Recommendation: keep.
docs/design/outreach-integration.md
- Length: 72 lines
- Audience: engineering
- Accuracy: current. Matches the
:outreachmodule (launch_app, open_link, copy_to_clipboard, DND tools). - User-facing content?: No.
- Recommendation: keep.
docs/design/usage-integration.md
- Length: 51 lines
- Audience: engineering
- Accuracy: current. Matches
:usagemodule tools. - User-facing content?: No.
- Recommendation: keep.
docs/design/health-connect-expansion.md
- Length: 59 lines
- Audience: engineering (proposal/expansion)
- Accuracy: partially current.
RecordTypeRegistryexists in:health. Verify shipped tool names againstHealthConnectMcpServer(may still expose the oldget_stepsalongside generic query, or may have fully migrated). - User-facing content?: No.
- Recommendation: update. Quick pass to mark shipped vs still-planned record types.
Non-markdown under docs/
docs/notifications/index.html (+ icon_*.png)
- What it is: A standalone HTML notification catalog / design gallery (renders all notification variants for review), using local icon PNGs.
- Accuracy: Unknown in terms of whether the icons still match shipped notification channels. Not referenced from any markdown/code under the repo.
- Recommendation: move out of
docs/intodesign-assets/ortools/notification-preview/.docs/should not contain loose HTML design tools — they won't make sense when the docs tree is published.
docs/auth-pages/*.html
- What it is: Rendered gallery of OAuth auth-page states
(approved / denied / expired / waiting / index). Built by
AuthPageGalleryTestpertest-coverage-audit.md. - Recommendation: keep, or move to
app/src/test/resources/since it's test-generated output, not a doc.
docs/screenshots/index.html
- What it is: Gallery of the current
app/screenshots/*.pngroborazzi outputs (dark/light pairs across the whole UI). Live and useful. - Recommendation: keep. The four standalone
docs/screenshot_*.pngfiles that paired withdevice-test-report.mdwere deleted on 2026-04-25 along with the report;docs/screenshots/index.htmlis a separate artifact and referencesapp/screenshots/*instead.
Summary punch list
- Delete:
BLOCKERS.md,docs/workflow.md.docs/test-coverage-audit.mdwas struck from this list on 2026-09-02: repaired and re-verified under #654 rather than deleted. Done 2026-04-25:docs/overnight-plan-2.md,docs/e2e-status.md,docs/device-test-report.md, and the fourdocs/screenshot_*.pngfiles paired with that report. Done (post-ship):docs/design/secret-prefix-bot-rejection.md,docs/design/per-integration-hostnames.md— superseded bydocs/design/relay-api.md+docs/design/overall.md.docs/screenshots/index.htmlis kept (it indexesapp/screenshots/*, not the deleted PNGs). - Rewrite for docs/user/:
docs/security.md→ split intodocs/user/security.md(trust model, what-you-trust, what-ai-can't-do) and keep the implementation-detail parts underdocs/engineering/security.md(or keep current path). - Move out of docs/ tree:
docs/notifications/index.html+ itsicon_*.pngfiles (they're a design asset, not docs). Optionally movedocs/auth-pages/*.htmlto test resources. - Update:
README.md— fix the URL example to the shipped per-integration hostname format.docs/security-audit-2026-04-07.md— annotate each of the 23 findings with current status.docs/design/overall.md— drop the embedded test-case list (items 165–274) in favor of a pointer to test classes; keep architecture prose.docs/design/android-app.md— reconcile module map with:core:bridge,:outreach,:usage.docs/design/relay-api.md— add/request-subdomain, verify field names and error codes match code. Needs deeper review.docs/design/tunnel-client.md— reconcile reconnect behavior with auto-reconnect implementation.docs/design/ui.md— deeper review against current nav graph and Screen composables; mark any dead-code screens.docs/design/health-connect-expansion.md— mark shipped record types.
- Keep as-is:
docs/self-hosting.md(candidate fordocs/contributor/move).docs/security-decisions.md.docs/design/relay.md(minor review recommended).docs/design/notifications-integration.md.docs/design/outreach-integration.md.docs/design/usage-integration.md.
Gaps (user-facing content that should exist but doesn't)
- No
docs/user/tree at all yet (gated on #119). - No user-facing getting-started / install guide (today lives implicitly
in
README.mdstatus line). - No user-facing "how to enable an integration" walkthrough.
- No user-facing FAQ on data retention, audit review, revoking access.
- No user-facing explanation of subdomain rotation and its cooldown.
These would populate the docs/user/ tree alongside the security rewrite.