docs: visual user-flow documentation (docs/flows/) — Mermaid flow map + e2e-anchored sequence diagrams

[mdorman]

Context

The app's user-facing "flows" — the interaction patterns implied by the client and
server components (unauthenticated reading, invitation → registration, email
verification, password reset, the post lifecycle, …) — exist only implicitly,
spread across three enumerable surfaces:

• 24 client routes in web/src/pages/mod.rs (one <Router>, CSR shell;
  access enforced by per-page gates + server-fn auth, with explicit redirect
  logic only on /app and the password-reset pages)
• ~50 #[server] fns grouped by vertical (web/src/<vertical>/api.rs)
• the Playwright suite (end2end/tests/*.spec.ts), which already names
  the canonical journeys ("invite link registration completes end-to-end", the
  full password-reset flow, the authed-flash /app bounce, …)

No document lets a reader see these patterns. docs/ARCHITECTURE.md has one
component-overview Mermaid graph; there are no journey or sequence diagrams
anywhere in docs/.

Proposal

Create docs/flows/, in Mermaid (renders natively on GitHub, text-diffable and
PR-reviewable, precedent already in ARCHITECTURE.md):

1. docs/flows/README.md — a flow index plus one page-level flow map
   (Mermaid graph TD): routes as nodes; edges for navigations and redirects,
   dashed edges for emailed links (invite, verify-email, reset-password).
   Regions of the graph surface the flow families: anon reading, authed
   authoring, token-in-URL journeys, admin.
2. Per-flow files (docs/flows/<flow>.md) — for each substantive flow, short
   prose plus a Mermaid sequenceDiagram: browser/page ↔ #[server] fn ↔
   storage/mailer. Simple CRUD pages don't warrant one.
3. Spec anchoring — every flow doc declares the e2e spec(s) that pin it
   ("Pinned by: end2end/tests/invite.spec.ts"). The spec is the drift alarm:
   the flow can't change without its spec changing, and the doc rides along in
   the same review.
4. xtask reference-check — ships with the docs, per the house rule that a
   convention gets an enforcement gate: verify every route path and #[server]
   endpoint named in docs/flows/*.md exists in the source, and report routes
   appearing in no flow doc (advisory at first). Parallels the existing
   registrar guard (test-infra: guard that every #[server] fn is present in the test registrar (stop the hand-list from rotting) #426).

Full diagram generation from code is explicitly out of scope: the transitions
(redirects inside components, emailed links, conditional gates) are not
statically enumerable from Leptos code. Generate/validate the inventories;
hand-author the arrows.

Candidate flow inventory (~15)

anonymous reading (/, /:username, permalinks, tag pages, feeds) · login /
logout / authed-flash /app gate · invitation → registration · email
verification · password reset · post lifecycle (draft → publish → edit w/ slug
freeze → unpublish/delete) · audiences + subscriptions + visibility · media
upload · sessions / app-passwords → AtomPub publishing · profile · admin: site
settings · admin: backups

Relationship to #310

The per-flow "Pinned by" anchors are #310's feature → e2e-spec traceability
matrix rows, organized flow-wise instead of feature-wise. Landing this gives
#310 a substrate — its matrix could be generated from (or simply be) the
flow-doc anchors. No hard dependency in either direction, but the two should
converge on one mapping, not two parallel ones.

Acceptance

• docs/flows/README.md with the flow index and the page-level Mermaid map
• Per-flow docs with sequence diagrams for at least: invitation →
  registration, email verification, password reset, login/authed-flash,
  post lifecycle, visibility/audiences
• Every flow doc names ≥1 pinning e2e spec
• xtask check: routes/endpoints referenced in docs/flows/ exist; unmapped
  routes reported
• docs/ARCHITECTURE.md links to docs/flows/

Refs

• web/src/pages/mod.rs (route table), web/src/*/api.rs (#[server] fns)
• end2end/tests/*.spec.ts
• Maintain a CSR feature to e2e-spec traceability matrix #310 (traceability matrix), test-infra: guard that every #[server] fn is present in the test registrar (stop the hand-list from rotting) #426 (registrar guard pattern), ADR-0050 (why CSR
  coverage is exempt — flow docs + specs are the honest substitute)