4f04b78c71
A doc's YAML frontmatter rendered as a table pinned to the top of the reading column, so on anything with more than two or three keys the document itself started below the fold. It is a panel beside the prose now — a sticky rail on a wide window, a closed disclosure above the body on anything narrower — and the reading column starts with the document. The table was built on the server and handed to the client inside one HTML string, so this is not a CSS change: markdown.go splits the parse (frontmatterPairs) from the markup, /api/render gains an ordered `frontmatter` field, and the viewer switches to RenderMarkdownPairs. RenderMarkdown keeps its exact output — it is the public share page, and every /s/ link ever minted serves it. shares_test now pins that, because nothing else would have failed if a later cleanup moved shares.go onto the pairs path. Values cross the wire as literal text plus a `code` flag rather than pre-escaped HTML, so the panel is ordinary React text nodes and never touches dangerouslySetInnerHTML: "a value containing markup renders as text" holds by construction. The rail's breakpoint is 1400px, not the 1180px the plan named — 768 of prose + 28 + 240 of rail needs 1036px of column, and at 1280 the reading measure lost 110px, which is the squeeze the panel exists to avoid. 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).