3fbe1252db
* fix(webapp): say that a read count includes your own views (BEA-61) "14 human reads" counted the author's own browsing, and no surface said so. Snow's call was to keep counting them — so this is disclosure, not ingest: recordRead and /heat are untouched. One HEAT_DISCLOSURE constant beside heatText in lib/heat.ts, consumed by all four surfaces that print a count. The file header carries it as hover text plus an .sr-only span rather than visible text — #meta is nowrap + ellipsis, so anything appended there is the first thing a narrow window truncates away. The folder page says it once out loud, covering the summary and every row, and the heat dot keeps it in title and aria-label for a row met on its own. The Dashboard folds it into the caption already there, both scope branches. A unit test pins the constant as the only copy of the sentence in src/ — "defined once" is the acceptance criterion no browser test can see. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> * docs(architecture): note HEAT_DISCLOSURE in the frontend lib diagram (BEA-61) The diagram enumerates heat.ts's exports, so a new one belongs in it — and the note says why the constant sits beside the arithmetic instead of in the four components that print it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Architecture diagrams
Mermaid diagrams of the current implementation, kept next to the code so PRs can update them alongside the change.
Convention: when a PR changes the structure drawn here (new/removed types, new seams, changed relationships), update the affected diagram in the same PR and add an "Architecture changes" section to the PR description that, per changed diagram:
- names exactly which types/relationships changed and how (one sentence);
- shows a Before and an After mermaid block — each an excerpt of only the affected classes and their immediate relationships, never the full diagram (Before comes from the diagram at the merge base).
The committed diagram file stays the full current state; the before/after
excerpts exist only in the PR description so reviewers see the structural
delta at a glance. A pre-PR hook (.claude/hooks/check-arch-diagrams.sh)
reminds Claude Code sessions when server code changed but no diagram did.
Together these cover every application package in the repo — every code change lands inside exactly one detail diagram's scope (plus the overview when the package map or cross-piece wiring changes):
- overview.md — system diagram: every package and surface on one page, and how they connect
- cli-sync.md — class diagram of the CLI and sync engine (
cmd/bdrive+internal/{syncer,store,journal,config,daemon,agenthooks,autostart}) - webapp-server.md — class diagram of the
bdrive serveserver (internal/webapp+ itsinternal/remoteseam) - webapp-frontend.md — module diagram of the hub's React SPA (
internal/webapp/frontend/src)
Not covered on purpose: web/docs (content site, no application code) and
cloud/ (private nested repo — its architecture lives there).