Merge feature/v0.19.0-docs-sessions-browser

CHANGELOG: normalize 0.19.0 header (drop 'v' prefix to match surrounding style)
Release v0.19.0: /docs nav + on-site sessions browser
2026-05-28 09:14:56 -07:00 · 2026-05-28 09:11:58 -07:00 · 2026-05-28 09:07:27 -07:00 · 2026-05-28 09:07:20 -07:00 · 2026-05-28 09:07:01 -07:00 · 2026-05-28 08:29:41 -07:00
18 changed files with 2608 additions and 57 deletions
@@ -23,6 +23,18 @@ skip versions are the composition of each intervening adjacent
 release's steps in order — no A-to-B path is pre-computed beyond
 that.
 ## 0.19.0 — 2026-05-28
 Roadmap item #30: docs nav with on-site sessions browser. Adds a left-side flyout nav on `/docs/*` and three new public surfaces — `/docs/sessions/about` (renders the session-history README), `/docs/sessions/<NNNN>` (per-session index), `/docs/sessions/<NNNN>/<filename>` (per-transcript view). Backend mediates the fetch from `wiggleverse/ohm-session-history` over gitea raw URLs with a small in-process TTL cache (60 s manifest, 5 min content; both env-tunable). Existing `/docs` content moves to `/docs/user-guide`; bare `/docs` redirects.
 Upgrade steps:
 MAY: `flotilla overlay set ohm-rfc-app OHM_SESSION_HISTORY_RAW_BASE=<url>` if the deployment points at a non-OHM transcript repo. Default in code matches OHM's `wiggleverse/ohm-session-history`.
 MAY: `flotilla overlay set ohm-rfc-app OHM_DOCS_SESSIONS_MANIFEST_TTL_SEC=60` and `OHM_DOCS_SESSIONS_CONTENT_TTL_SEC=300` to tune cache TTLs.
 Note: this release depends on the parallel restructure of `wiggleverse/ohm-session-history` into per-session `NNNN/` folders + `README.md` + `sessions.json` (driver session 0017.0, subsession 0017.2). If the repo is still flat at deploy time, `/docs/sessions/about` and the per-session pages return 404 and the route tree degrades to "About not yet published" — no JS crashes; the User Guide remains fully functional.
 ## 0.18.0 — 2026-05-28
 **Minor — schema migration required; one env var now mandatory; no
@@ -0,0 +1,407 @@
 # Contributing to rfc-app
 `rfc-app` is the framework that hosts RFC-shaped collections of
 documents — one repo per RFC, a meta repo per collection, a web app
 that turns the Git substrate into a writeable surface. The Open
 Human Model (OHM) deployment at `ohm.wiggleverse.org` is one
 instance. The framework is intended to host more.
 This document explains how to propose a change to the framework
 itself — a new endpoint, a schema migration, a UI affordance, a
 spec clarification. For changes to *content* hosted by a specific
 deployment (the OHM RFCs, the OHM roadmap), see that deployment's
 own contribution guide (e.g. [`ohm-rfc/CONTRIBUTING.md`](https://git.wiggleverse.org/wiggleverse/ohm-rfc/src/branch/main/CONTRIBUTING.md)).
 ---
 ## How the project actually evolves
 rfc-app is built in the open in the literal sense: **every build
 session produces a full transcript** at
 [`wiggleverse/ohm-session-history`](https://git.wiggleverse.org/wiggleverse/ohm-session-history)
 on `git.wiggleverse.org`. The transcripts are the authoritative
 record of how the framework got from one release to the next — the
 decisions, the friction, the dead ends, the reasoning. They are not
 curated retrospectives; wrong turns stay in.
 If you are proposing a change to rfc-app, **read at least the most
 recent session transcript before opening a PR.** The transcripts
 show what shape a feature lands in, where the spec gets touched,
 what the operator pushes back on, and how the release rides into
 deployment. A PR that matches that texture is much more likely to
 land cleanly than one shaped by the README alone.
 Worked examples to start with:
 - **Session E** ([transcript](https://git.wiggleverse.org/wiggleverse/ohm-session-history)) —
  a clean small release. Read this for the simplest possible release
  shape: one feature, one version bump, one upgrade-steps block, no
  surprises.
 - **Session I** — recovery from a deploy fault. Read this for how
  the project handles things going wrong mid-deploy, and for the
  honest no-curation discipline.
 - **Session K** — a multi-feature wave with one item paused on an
  operator-provided secret. Read this for the subagent dispatch
  pattern (the model the project uses to ship multiple features in
  parallel), and for the binding rule that the assistant **never**
  asks the operator to paste secret bytes into the conversation.
 - **Session L** — squash-merge integration across three parallel
  features (v0.15.0 / v0.16.0 / v0.17.0), with `#21 Part C`
  identity-lifecycle Amplitude wiring folded inline across all
  three releases. Read this for how cross-cutting concerns (analytics,
  observability) get layered into already-in-flight features
  without scope-creeping any single release.
 The repository where transcripts live —
 [`wiggleverse/ohm-session-history`](https://git.wiggleverse.org/wiggleverse/ohm-session-history) —
 is the canonical history. The `git log` of `rfc-app` is the artifact;
 the transcripts are the story behind it.
 ---
 ## How a contribution flows
 The framework runs on a **subagents push feature branches; operator
 tags and deploys** model. Contributors — whether human or AI agents
 running in a Claude Code subsession — open feature branches and
 submit PRs. The operator (the person running the deployment) is the
 one who merges, tags, bumps `VERSION`, runs `flotilla deploy` (or
 the equivalent for non-OHM deployments), and moves the deployment's
 `.rfc-app-version` pin. The driver session transcripts inherit
 this shape; contributors inherit it from them.
 Concretely:
 1. Read the most recent session transcript. Understand what just
   shipped and what is in flight.
 2. Open an Issue first if your change is exploratory, structural,
   or might overlap with in-flight work. The operator will name
   any collision.
 3. Branch from `main`. Name the branch
   `feature/<short-description>` for additive work, `fix/<short-
   description>` for bug fixes, `docs/<short-description>` for
   documentation-only work. The driver sessions use
   `feature/v<target-version>-<slug>` (e.g.
   `feature/v0.16.0-owner-invite`) — that shape is welcome but not
   required for outside contributors, since contributors do not
   pick the target version.
 4. **Do not bump `VERSION` or `frontend/package.json#version` in
   your PR.** The operator picks the target version at integration
   time; bumping ahead causes cherry-pick conflicts. The same
   applies to the `CHANGELOG.md` entry header — see below.
 5. **Do not tag releases, do not run any deploy gesture, do not
   touch any deployment's `.rfc-app-version` pin.** The operator
   alone owns those gestures. (For OHM specifically: "I'm the only
   one that gets to yolo." See the boundary section in
   `ohm-rfc/CONTRIBUTING.md`.)
 6. Push your branch and open a PR. Describe what you're proposing
   and why, in language the operator can paste into the eventual
   release commit. If the change touches `SPEC.md`, name which
   section(s) and the contract change.
 ---
 ## CHANGELOG convention: strict descending
 `CHANGELOG.md` is ordered **newest-on-top**. The header line for
 the in-progress version goes at the top of the file; older
 releases descend below it. This is the binding convention; the
 operator hand-resolves the conflict when two parallel feature
 branches both insert at the top of the file (the squash-merge
 integration that ships parallel-feature waves keeps the strict-
 descending shape — see Session K for the cherry-pick mechanics and
 Session L for the hand-resolved-with-a-small-script variant).
 A new entry has this shape (read the existing 0.15.0 / 0.16.0 /
 0.17.0 entries for worked examples):
 ```markdown
 ## 0.X.Y — YYYY-MM-DD
 **Minor — schema migration auto-applied; no operator action.** This
 release ships <one or two sentences naming the feature and why>.
 ### Added
 - **<New module/endpoint/component>** — what it does, where it lives,
  why it exists. Include file paths inline so a reader can click through.
 ### Changed
 - **<Existing surface>** — what changed and how a deployment notices.
 ### Migration
 - **`<NNN_name>.sql`** — auto-applied by `db.run_migrations()` on
  backend start. <Describe the schema delta in one sentence.>
 ### Upgrade steps (from 0.(X-1).Y)
 - You **MUST** … (per RFC 2119; see SPEC.md §20.4).
 - You **MUST NOT** …
 - You **SHOULD** …
 - You **MAY** …
 ```
 The header version number is filled in by the operator at merge
 time. Your PR's CHANGELOG diff can leave the version as
 `0.X.Y — YYYY-MM-DD` (literal placeholder), or use a guessed value
 the operator overwrites; either is fine.
 ---
 ## `Upgrade steps:` blocks use RFC 2119 keywords
 If your change requires deployments to do anything when they
 upgrade — set an env var, apply a migration, restart a process,
 flip an overlay value, accept a behavioral change — your CHANGELOG
 entry **must** include an `### Upgrade steps` block, and that
 block **must** use the [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
 / [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174) keywords as
 defined in `SPEC.md` §20.4:
 - **MUST** / **SHALL** / **REQUIRED** — without this step the
  deployment will not function correctly. Skipping is a regression
  the framework does not handle.
 - **MUST NOT** / **SHALL NOT** — previously valid, now no longer
  supported.
 - **SHOULD** / **RECOMMENDED** — the framework's tested path. A
  deployment may deviate when it has a reason.
 - **SHOULD NOT** / **NOT RECOMMENDED** — discouraged without being
  forbidden.
 - **MAY** / **OPTIONAL** — an affordance you can take or skip.
 Cross-version upgrades (jumping more than one minor) are computed by
 the operator composing each intervening release's steps in order.
 Each adjacent step must therefore be locally unambiguous — this is
 the whole reason the keyword discipline is binding. Avoid words
 like "should probably" or "might want to" inside an upgrade step;
 either the framework needs the action or it doesn't.
 If your change touches the env contract, **also update**
 `backend/.env.example` and/or `frontend/.env.example` in the same
 PR so the contract and the documentation land together (§20.4).
 ---
 ## SPEC.md and §19.2 candidates
 `SPEC.md` is the framework's binding spec. It is honest about open
 questions — large sections of it carry "§19.2 candidates," which
 are decisions the project has deliberately deferred rather than
 guessed at.
 The discipline: **architectural or process deferrals get noted as
 §19.2 candidates rather than scope-creeping a release.** When you
 notice that your change opens a question larger than the change
 itself (a different DB shape, a new auth contract, a cross-cutting
 UX rethink), the right move is usually to land the narrow change
 and add a §19.2 candidate naming the larger question. The candidate
 documents what was set aside and why, so a future session can pick
 it up with context.
 Worked examples from recent sessions:
 - v0.11.0 (Session K) shipped device trust and surfaced three new
  §19.2 candidates: cross-device session revocation, password-
  equivalent change invalidating trust, device-trust window
  tunables via env. None of those were in the v0.11.0 scope; they
  were noted in SPEC.md §19.2 so a future session can address them
  on their own terms.
 - v0.15.0 (Session L) shipped the Amplitude wrapper and added
  candidates around session-replay-specific consent category +
  bundle-size measurement, both deferred to the future Part-A audit.
 When you spot a deferred decision in your PR's territory, name it
 in your PR description and add it to `SPEC.md` §19.2 in the same
 diff. Do not silently expand scope to settle it.
 ---
 ## Test-coverage expectations
 The backend has the load-bearing test suite at
 `backend/tests/`. Tests are organized as `*_vertical.py` files,
 each covering one feature end-to-end through the FastAPI app
 (provisioning fixtures, hitting the HTTP surface, asserting on the
 database state). At time of writing, the suite is ~250 tests across
 ~25 files. Examples:
 - `test_admin_create_user_invite_vertical.py` — v0.17.0's
  admin-create user + invite + claim flow, 15 tests covering happy
  path + every refusal shape + the audit-trail row.
 - `test_rfc_invitations_vertical.py` — v0.16.0's per-RFC invite +
  accept flow, 18 tests.
 - `test_device_trust_vertical.py` — v0.11.0's 30-day device trust,
  14 tests including cookie shape, hash-vs-raw-token discipline,
  expired / revoked / forged / cross-user invariants.
 Expected coverage for a new feature:
 - **Backend feature** — one new `test_<feature>_vertical.py` file
  that covers the happy path, every documented refusal/error code,
  and any cross-surface effect (rows the feature writes to existing
  tables, fields it adds to existing endpoints). Reuse fixtures
  from neighboring test files (e.g. `test_propose_vertical.py`'s
  `FakeGitea` is widely reused).
 - **Migration** — verify migrations are reachable from `backend/.venv`
  before pushing: `cd backend && PYTHONPATH=. .venv/bin/pytest -q`
  exercises `db.run_migrations()` through the fixture setup.
 - **Frontend feature** — there is currently no frontend test
  runner. The discipline is: keep the change ships-clean
  (`cd frontend && npm run build` succeeds), and the backend
  vertical test exercises the HTTP contract the frontend
  consumes, which is the meaningful behavioral guarantee.
  Frontend changes that ride along with a backend feature land
  with the backend test as the regression boundary.
 - **Bug fix** — add a regression test in the same vertical file
  that proves the original failure mode and verifies the fix.
 Run the backend suite before pushing. From `backend/`:
 ```bash
 PYTHONPATH=. .venv/bin/pytest -q
 ```
 (The `PYTHONPATH=.` is a known ergonomic gap — see SPEC.md §19.2
 candidate; the suite does not pick up `app/` without it.)
 If your PR doesn't include tests, the operator will ask for them
 before merge unless the change is genuinely test-irrelevant
 (documentation, comments, dev-only tooling).
 ---
 ## Analytics instrumentation checklist
 > *(This section codifies `ohm-rfc/ROADMAP.md` #21 Part B's
 > CONTRIBUTING checklist. It is discipline, not a gate — but the
 > operator will push back on PRs that skip it.)*
 If your PR adds or changes a user-facing feature, walk this
 checklist before opening the PR. The instrumentation conventions
 themselves are specified in `SPEC.md` §21 (Analytics instrumentation
 and identity); this section is the procedural reminder.
 1. **What named event(s) does this feature need?**
   Open `frontend/src/lib/analytics.js` and look at the `EVENTS`
   constant. Does an existing event cover your feature? If not, is
   the new event in the spec's "Subject Verb" Title Case form
   (`Comment Posted`, `Invitation Sent`)? Are the prop families
   consistent with SPEC.md §21's required-prop catalog (opaque
   ids only, no PII, enums lowercased like `'otc'` not `'OTC'`)?
 2. **Do interactive elements have stable text / ARIA labels /
   `data-amp-track-*` so autocapture is meaningful?**
   The frontend ships `autocapture: true`, which instruments
   every click and form interaction. The *value* of those events
   depends on the DOM the SDK sees: a `<button>` with stable
   visible text or an `aria-label` shows up as a meaningful
   dashboard row; an icon-only `<button>` with no label shows up
   as garbage. New components that introduce interactive elements
   should either carry meaningful labels (visible text or ARIA) or
   carry a `data-amp-track-name="<Stable Name>"` attribute. For
   repeated rows (per-RFC lists, comment lists), use a stable
   `data-amp-track-*` identifier so per-row click counts aggregate
   to the row's identity rather than to a generic label.
 3. **Does any new form field need replay masking?**
   Session replay records at `sampleRate: 1` (100% of consented
   sessions). New form inputs that capture passwords, OTC codes,
   tokens, magic-link URLs, or other secret/credential-equivalent
   material **MUST** be masked with Amplitude's masking conventions
   (the `.amp-mask` class or the `data-amp-mask` attribute,
   whichever the wrapper integration expects in this version).
   New inputs that capture arguably-PII (email, real name, free-
   text drafts) **SHOULD** also be masked; if a deliberate
   un-masking decision is taken, document it in the PR description
   and in `SPEC.md` §21.
 4. **Does the PR description name the instrumentation decisions?**
   A one-sentence summary in the PR description — "fires
   `Comment Posted` with `{rfc_slug, comment_id}`; no new form
   fields, no new replay-masking concerns" — is enough. If the
   decision is "we chose not to instrument this," say that too;
   the absence of an event is itself a decision the operator
   wants visible. The relevant SPEC chapter (§21) is the binding
   reference for what shapes are correct.
 If your feature touches an identity-meaningful surface (sign-in,
 sign-out, invite-claim, role change, account state change), also
 walk the **identity lifecycle** contract in SPEC.md §21.6: every
 new claim/sign-in path **MUST** call `identify({ user_id, properties })`
 BEFORE the first `track()` event on that surface, so the Amplitude
 user record is created with the OHM user_id from the very first
 event rather than as an anonymous device that retroactively links.
 v0.16.0's `AcceptInvitation.jsx` and v0.17.0's `InviteClaim.jsx`
 are the worked examples; mirror their shape.
 ---
 ## The operator-only gestures
 Some gestures are operator-only. Contributors do not perform them;
 PRs that perform them get rejected on principle, not on merit:
 - **Tagging a release** (`git tag v0.X.Y` + `git push --tags`).
 - **Pushing to `main`** after merge (the operator merges; the
  framework's `main` branch tracks releases the operator has
  shipped).
 - **Bumping `VERSION` and `frontend/package.json#version` to the
  shipped value.** The operator does this at integration time so
  the version line is consistent across the release commit.
 - **Running `flotilla deploy` or any equivalent deployment gesture**
  in any deployment of rfc-app. Contributors do not deploy.
 - **Moving a deployment's `.rfc-app-version` pin.** That pin lives
  in the deployment's content repo (e.g. `ohm-rfc/.rfc-app-version`)
  and is moved by the deployment's operator. Contributors to that
  deployment do not move it; contributors to the framework
  certainly do not.
 - **Setting secrets** (anywhere — Secret Manager, env files,
  `flotilla secret set`, vendor dashboards, anything). The
  binding rule baked in mid-Session-K is: **the assistant never
  asks the operator to paste secret bytes into a conversation,
  even as one offered option**. The corollary for contributors:
  do not include secret values in PR descriptions, commit
  messages, or issue comments. Reference secrets by their binding
  name (`SMTP_PASSWORD`, `AMPLITUDE_API_KEY`) and let the
  operator handle the bytes.
 If your change requires a new secret or env var, document the
 requirement in the CHANGELOG `### Upgrade steps` block in the
 RFC 2119 form ("operators **MUST** set `<NEW_VAR>` ...") and
 update the `*.env.example` file. The operator will run the
 secret/overlay-set gesture themselves at deploy time.
 ---
 ## When in doubt
 - **Open an Issue first.** Especially for any change that touches
  SPEC.md, the auth/permissions model (§6), the storage shape (§4
  / §5), or the deploy contract (§20). The operator (or a future
  driver session) will name what they want before you write code.
 - **Read the most recent session transcript.** It will tell you
  what shipped last and what's in flight.
 - **Cite SPEC.md sections in your PR description.** "Touches §15.4
  (per-category email toggles) and adds §19.2 candidate around
  per-channel mute granularity" gives the operator a map of where
  to read.
 ---
 ## License
 The framework is released under the MIT License (see
 [`LICENSE`](./LICENSE)). By contributing, you agree your work
 ships under those terms.
 ---
 ## See also
 - [`SPEC.md`](./SPEC.md) — the framework's binding spec. §19.2
  is the deferred-decisions queue; §20 is the versioning + deploy
  contract; §21 is the analytics instrumentation contract.
 - [`CHANGELOG.md`](./CHANGELOG.md) — release history in strict
  descending order. Read recent entries for the shape your PR's
  release-commit will take.
 - [`PHILOSOPHY.md`](./PHILOSOPHY.md) — what the framework is for.
  PRs whose shape conflicts with the philosophy get a longer
  conversation than PRs that fit.
 - [`wiggleverse/ohm-session-history`](https://git.wiggleverse.org/wiggleverse/ohm-session-history)
  — the authoritative record of how the project has actually
  evolved, session by session.
@@ -2284,6 +2284,13 @@ a given signal, the **storage shape** that makes triage tractable, and
 the **out-of-session channels** (email, digest) that let asynchrony
 actually work.
 (The framework's separate **analytics + session-replay** surface —
 Amplitude wiring, event taxonomy, identity lifecycle, consent
 contract — is a peer cross-cutting concern specified in §21.
 Notifications cover in-product signal-of-others-acting-on-your-work;
 analytics covers observability of how the product is used. The two
 surfaces do not overlap.)
 ### 15.1 The signal-surface stack
 Five surfaces, each with one narrow job:
@@ -4300,3 +4307,465 @@ Downstream deployments, in exchange for the contract above, commit to:
  order;
 - supply every required env var the framework documents at the
  version they are running.
 ---
 ## 21. Analytics instrumentation and identity
 The framework ships an Amplitude Analytics + Session Replay wrapper
 in v0.15.0 (`frontend/src/lib/analytics.js`), gated by the v0.13.0
 cookie/privacy consent surface (`frontend/src/lib/consent.js`,
 §14.5). This section codifies the conventions that keep the
 instrumentation **quality** healthy as features land — taxonomy
 shape, autocapture hygiene, replay masking, the consent contract,
 and the identity lifecycle. The conventions are framework-neutral:
 every deployment of rfc-app that turns on the wrapper inherits
 them.
 This chapter is placed semantically after §15 (Notifications) and
 §16 (deliberately deferred) as a peer cross-cutting framework
 concern. It was added after §20 in the chapter sequence to avoid
 renumbering the deferred-decisions surface §19.2, which is a
 load-bearing project noun referenced across CLAUDE.md, transcripts,
 and prior commits.
 ### 21.1 Event-taxonomy conventions
 Events live in the public `EVENTS` constant in
 `frontend/src/lib/analytics.js`. Callers **SHOULD** use one of the
 named constants rather than firing arbitrary event strings — that
 keeps the Amplitude dashboard coherent over time and makes the
 taxonomy reviewable as a single source of truth.
 - **Name form: Title Case, "Subject Verb".** E.g.
  `Comment Posted`, `Invitation Sent`, `RFC Viewed`,
  `User Signed In`, `Admin Permission Decision`. Spaces between
  words, no punctuation, no leading verbs (use `RFC Proposed`,
  not `Propose RFC`). The strings match the Amplitude dashboard
  names exactly.
 - **Stability.** New events **SHOULD** land via a release, not
  ad-hoc — adding an entry to `EVENTS` is a CHANGELOG-worthy
  change because it widens the framework's observable surface
  (§20.3). Renaming an event after it has shipped breaks the
  dashboard's historical continuity; renames **SHOULD** be
  treated as a deprecation cycle (ship both, dashboard-migrate,
  drop the old one).
 - **Opaque ids only in prop values.** Properties **MUST NOT**
  carry PII — no email, no display name, no IP, no free-text
  field bodies (titles, comment text, RFC drafts). Properties
  **SHOULD** be limited to:
  - opaque ids: `rfc_slug`, `rfc_id`, `pr_number`,
    `target_user_id`, `invited_by_admin_id`, `thread_id`,
    `comment_id`;
  - enums (lowercased): `method: 'otc' | 'passcode' |
    'device-trust' | 'admin-invite' | 'rfc-invite'`;
  - booleans: `trust_device`, `needs_passcode`, `passcode_set`;
  - timestamps (ISO 8601);
  - small bounded integers: `custom_message_chars` (coarse-grained
    signal of admin effort, NOT the message text itself).
 - **Casing consistency.** Prop keys use `snake_case` (matches the
  backend's JSON shape). Enum values use lowercase with hyphens
  (`'rfc-invite'`, not `'rfcInvite'` or `'RFC_INVITE'`). Drift
  here ruins dashboard aggregation; the operator-side audit
  (§21.7 / `ohm-rfc/ROADMAP.md` #21 Part A) checks for it.
 The starting taxonomy as of v0.17.0:
 ```
 PAGE_VIEWED:               'Page Viewed'
 RFC_VIEWED:                'RFC Viewed'
 USER_SIGNED_IN:            'User Signed In'
 USER_SIGNED_OUT:           'User Signed Out'
 RFC_PROPOSED:              'RFC Proposed'
 PR_OPENED:                 'PR Opened'
 COMMENT_POSTED:            'Comment Posted'
 BETA_ACCESS_REQUESTED:     'Beta Access Requested'
 ADMIN_PERMISSION_DECISION: 'Admin Permission Decision'
 INVITATION_SENT:           'Invitation Sent'        # v0.16.0 / #12
 INVITATION_ACCEPTED:       'Invitation Accepted'    # v0.16.0 / #12
 USER_INVITED:              'User Invited'           # v0.17.0 / #16
 INVITE_CLAIMED:            'Invite Claimed'         # v0.17.0 / #16
 ```
 ### 21.2 Required prop families per event kind
 Each event family carries a small required prop set. These are
 load-bearing for the dashboard's cohort analysis; releases that
 add a new event in an existing family **SHOULD** carry the
 family's required props.
 - **Navigation events** (`Page Viewed`, `RFC Viewed`): carry
  `path` (string, pathname only — never the query string if it
  could carry a token) for `Page Viewed`; carry `rfc_slug` for
  `RFC Viewed`. `rfc_id` **MAY** be added when the cached row is
  in hand.
 - **Auth-state events** (`User Signed In`, `User Signed Out`):
  `User Signed In` carries `method` (one of `'otc'`,
  `'passcode'`, `'device-trust'`, `'admin-invite'`). `User
  Signed Out` carries no props (the identity binding is cleared
  separately via `anonymize()`).
 - **Authored-action events** (`RFC Proposed`, `PR Opened`,
  `Comment Posted`): carry `rfc_slug`. PRs additionally carry
  `pr_number` once the row exists. Comments additionally carry
  `thread_id`. None carry the body text.
 - **Admin-action events** (`Beta Access Requested`,
  `Admin Permission Decision`): the latter carries `action`
  (lowercase: `'grant'` / `'revoke'`) and `target_user_id`.
 - **Invite-side events** (`Invitation Sent`, `User Invited`): fire
  from the inviter's signed-in session. `Invitation Sent` (per-RFC,
  #12) carries `rfc_slug` + `role_in_rfc`. `User Invited`
  (admin-create, #16) carries `target_user_id` (the OHM user_id of
  the just-provisioned user) + `initial_role` +
  `custom_message_chars` (a bounded integer signal of admin
  effort, never the message text). Per #21 Part C: when the
  invitee is not yet a user (#12 per-RFC invitations to an email
  address that has never signed in), the invite-side event **MAY**
  carry a hashed `target_email` fingerprint (SHA-256 of the
  normalized lower-cased email) so the invite + claim pair can be
  correlated later. Plain-text `target_email` **MUST NOT** be
  carried.
 - **Claim-side events** (`Invitation Accepted`, `Invite Claimed`):
  fire from the invitee's session, immediately after an
  `identify({ user_id, properties })` call binds the OHM user_id
  to the Amplitude record (see §21.6). The events carry the
  invite context (`rfc_slug` + `role_in_rfc` for the per-RFC
  shape; `invited_by_admin_id` + `initial_role` + `needs_passcode`
  + `trust_device` for the admin-create shape).
 When in doubt, the principle: a property is correctly shaped iff
 the operator could publish it in a session transcript without
 hesitation.
 ### 21.3 Autocapture-friendly DOM patterns
 The wrapper initializes Amplitude with `analytics.autocapture: true`,
 which auto-instruments page views, clicks, and form interactions.
 The *value* of those auto-captured events depends entirely on the
 DOM the SDK observes. Releases that add interactive UI **SHOULD**
 follow these patterns so the dashboard rows are readable rather
 than rows like "Click on `<button>` at `:nth-child(7)`".
 - **Stable visible text on interactive elements.** Buttons and
  links **SHOULD** have stable, human-readable text content (the
  same string Amplitude uses to label the row). Avoid generic
  labels like "Read more" / "Click here" that lose context.
 - **`aria-label` on icon-only buttons.** Icon-only buttons (the
  chevron expanders, kebab menus, close `X`s) **MUST** carry a
  meaningful `aria-label`. Default autocapture for an unlabeled
  icon button reads as garbage. The `aria-label` is also an
  accessibility requirement — the two goals align.
 - **`data-amp-track-*` for repeating-list per-row identifiers.**
  When a list renders many rows of the same shape (RFC rows,
  comment rows, PR rows in a listing), per-row interactive elements
  **SHOULD** carry a `data-amp-track-name` attribute that
  identifies the row's *kind* and a `data-amp-track-*` attribute
  carrying the row's stable id. The convention:
  ```html
  <button
    data-amp-track-name="RFC Row Expand"
    data-amp-track-rfc-slug={slug}
  >…</button>
  ```
  This makes per-RFC click counts aggregate to the RFC rather
  than to a generic label, and lets the dashboard answer "which
  RFCs got the most engagement" rather than "how many buttons
  were clicked."
 - **`data-amp-track-suppress` for noise surfaces.** Crowded surfaces
  (the admin user-listing post-v0.9.0, the RFC discussion panel
  during heavy review) **MAY** apply
  `data-amp-track-suppress` (or its current equivalent in the
  SDK version in use) to elements whose clicks would flood the
  dashboard without informing anything. Suppression is a
  deliberate decision; document it inline.
 ### 21.4 Session-replay masking conventions
 The wrapper initializes Amplitude with `sessionReplay.sampleRate: 1`
 (100% of consented sessions are recorded for full-DOM playback —
 vendor-recommended default for new Amplitude deployments). Replay
 has a meaningfully larger privacy footprint than event counters,
 and the masking discipline is binding.
 - **Credentials MUST be masked.** The OTC code input, passcode
  input, any password-type field, the Turnstile widget internals,
  the magic-link-claim token if it survives in the URL bar
  (browser history, screenshot windows) — these **MUST** be masked
  with Amplitude's masking convention (the `.amp-mask` class or the
  `data-amp-mask` attribute, whichever the wrapper's SDK version
  uses; the wrapper's bootstrap comment names the current
  convention). Confirm each masking attribute survives the
  wrapper init by inspecting a recorded session before each
  release that touches an auth input.
 - **PII SHOULD be masked or carefully un-masked.** Email-entry
  fields, real-name capture fields (the v0.8.0 first/last/why
  panel), free-text RFC body drafts, comment-compose text —
  each is arguably PII or near-PII. The per-field decision is
  the release's responsibility; document the choice in `SPEC.md`
  §21 (this section) and in the release CHANGELOG so future
  deployments inherit the call rather than re-deciding.
 - **Privacy-policy alignment.** The recorded data **MUST** match
  what the deployment's privacy / cookies policy claims. If
  reality is broader than the document promises, update the policy
  text in the same release.
 - **Selective redaction.** Amplitude supports field-level mask
  classes that hide value while preserving DOM shape (so the
  session is replayable but the value is not). Prefer this over
  whole-form masking when only a subset is sensitive.
 ### 21.5 Consent-gate contract
 The wrapper is bound to the v0.13.0 cookie/privacy consent surface
 (`frontend/src/lib/consent.js`, §14.5). The binding is **load-
 bearing**: the SDK and the session-replay recorder **MUST NOT**
 load before consent is granted, and any consent revocation **MUST**
 take effect within one tick of the consent flip.
 The wrapper's bootstrap implements this contract; releases that
 touch the analytics surface **MUST** preserve it.
 - **Pre-consent: no init, no network, no recording.** If
  `consent.analytics === true` is not currently true (either
  because the user denied, or because the banner is up and no
  decision has been recorded), the wrapper **MUST NOT** import
  the Amplitude SDK, **MUST NOT** open any network request to
  Amplitude, and **MUST NOT** start any session-replay recording.
  The consent-gated lazy `import('@amplitude/unified')` is the
  binding implementation; preserve it.
 - **Denied → granted: init at the consent moment.** When consent
  flips from denied/undecided to granted, the wrapper **MUST**
  initialize the SDK at that moment (a new `initAll(KEY, …)` call
  through the lazy-import path). Track and identify calls made
  before init resolves **MUST** be queued and drained on init,
  so the first signed-in user's first event is not dropped on
  the cold-load race.
 - **Granted → denied: setOptOut(true) within one tick.** When
  consent flips from granted to denied mid-session, the wrapper
  **MUST** call `amplitude.setOptOut(true)` so subsequent events
  are dropped client-side and session replay stops recording.
  The wrapper cannot unload the script tag (the SDK is already
  in memory), but the SDK's contract for "drop subsequent events"
  is `setOptOut(true)`. This **MUST** happen within one tick of
  the consent flip (i.e. synchronously inside the
  `onConsentChange` handler).
 - **No silent re-grant.** A granted → denied → granted sequence
  **MUST** call `setOptOut(false)` (re-enabling the SDK that was
  paused) rather than firing a second `initAll` (which would
  double-init). The wrapper's bootstrap implements this; releases
  that touch the consent integration **MUST** preserve the
  distinction.
 - **Build-time vs. runtime.** The API key is read from
  `import.meta.env.VITE_AMPLITUDE_API_KEY` at build time. When
  the env var is unset, the wrapper **MUST** log one console
  warning and no-op (every public function becomes a deterministic
  no-op) so dev environments without an Amplitude account keep
  working. The deploy gesture binds the key via the deployment's
  overlay verb (for OHM-shape deployments, `flotilla overlay set`);
  see §21.8 for the secret-vs-public discussion.
 ### 21.6 Identity lifecycle (per #21 Part C)
 Amplitude's identity model has a specific pattern that the
 framework follows verbatim. Every release that touches an
 identity-meaningful surface **MUST** observe this pattern. The
 pattern shipped inline across v0.15.0 / v0.16.0 / v0.17.0
 (Session L's wave); this section codifies the contract so future
 releases inherit it.
 **On sign-in success** (`App.jsx`'s `me.user` resolution):
 - The wrapper's `identify({ user_id, properties })` call **MUST**
  carry both the OHM user_id (`amplitude.setUserId(<id>)`
  internally) AND the user's durable property bag. `setUserId`
  alone is **NOT** sufficient — without properties, the Amplitude
  user record carries only the id, and cohort analysis loses the
  shape (role distribution, sign-in-method distribution, etc.)
  the dashboard depends on.
 - Properties **MUST** be a bag of opaque ids, enums, booleans,
  and timestamps — no PII (no email, no display name, no IP).
 - Properties **MUST** be classified `set` vs `setOnce` deliberately
  (see §21.6.1 below).
 - The same `identify` call **MUST** be re-issued on every sign-in
  (idempotent at Amplitude's side; cheap; corrects any drift in
  the mutable property half).
 **On user-state change mid-session** (role grant/revoke, trust-
 device add, passcode set, beta-permission flip):
 - The wrapper's `setUserProperties(properties)` call **MUST** fire
  so the Amplitude record stays current. Mid-session state changes
  **MUST NOT** wait for the next sign-in to surface — the dashboard
  cohort an admin uses to grant permission is the same dashboard
  that next sees the granted user's behavior; staleness here breaks
  the cohort feedback loop.
 **On sign-out**:
 - The wrapper's `anonymize()` call (internally `amplitude.reset()`)
  **MUST** fire. `reset` clears the device-id linking AND **MUST**
  also clear the property cache so the next anonymous session is a
  fresh slate (the wrapper's `anonymize()` does both — releases
  that touch the wrapper **MUST** preserve this).
 - The `User Signed Out` `track()` call **MUST** fire *before*
  `anonymize()`, so the sign-out event is correctly attributed to
  the signing-out user rather than to the post-reset anonymous
  device.
 **On invite-claim** (the v0.16.0 per-RFC invite + v0.17.0 admin-
 create invite paths):
 - The wrapper's `identify({ user_id, properties })` call **MUST**
  fire BEFORE the first `track()` event on the claim surface, so
  the Amplitude user record is created with the OHM user_id from
  the first event. **MUST NOT** fire `track()` first and `identify`
  later — that creates an anonymous device record that
  retroactively links, and the cohort attribution for
  invite-driven onboarding loses precision.
 - The invite-context properties (`claim_method`,
  `invited_by_admin_id`, `invited_at`, `initial_role`) are
  `setOnce` (immutable user-history markers) — see §21.6.1.
 **Inviter-side identification on invite-send events**:
 - The inviter's `track('Invitation Sent', …)` and
  `track('User Invited', …)` events fire from the inviter's
  signed-in session, so the `user_id` attribution is already
  correct (it's the inviter's id). The event body carries
  `target_user_id` (#16 — admin-create, where the future user is
  provisioned at create-time) or a hashed `target_email`
  fingerprint (#12 — per-RFC invite, where the invitee is not
  yet a user) so the invite + claim pair can be correlated later
  in the dashboard.
 #### 21.6.1 `set` vs `setOnce` taxonomy
 Amplitude distinguishes two property-write semantics:
 - **`set(k, v)`** — overwrites the property on every call. The
  user record reflects the most recent value.
 - **`setOnce(k, v)`** — writes only if the property is not
  already present. Subsequent calls are no-ops. The user record
  reflects the first value ever written.
 The wrapper's `applyProperties` function accepts both: a bare
 value uses `.set()`; a sentinel-wrapped value
 `['__setOnce__', value]` uses `.setOnce()`. Releases that add new
 user properties **MUST** classify each one explicitly, by the
 following rule:
 - A property whose value is **expected to change over the user's
  lifetime** is `set`. Examples: `role` (can flip from
  `contributor` to `owner`), `permission_state` (pending → granted),
  `passcode_set` (false → true), `device_trusted` (changes per
  active device). On each sign-in, the latest value is written;
  the dashboard always sees current state.
 - A property that is an **immutable historical marker** is
  `setOnce`. Examples: `first_sign_in_at` (the timestamp of the
  user's first observed sign-in — never re-write), `account_
  created_at` (the timestamp of provisioning),
  `invited_by_admin_id` (the admin who provisioned this user via
  the v0.17.0 path — preserved even if the user is later
  re-invited or has their role changed), `invited_at` (the
  timestamp at which the invite was sent — distinct from
  `claim_method` which is also setOnce because once claim_method
  is `'admin-invite'`, that's the path this user took).
 The classification is part of the release's contract — flipping a
 property from `set` to `setOnce` (or vice versa) mid-life corrupts
 the user record and **MUST** be avoided. If a property's
 semantics genuinely change, retire the old key and introduce a new
 one (same deprecation discipline as event renames in §21.1).
 ### 21.7 Cohort-shape implications (informative)
 The conventions above are designed so that the Amplitude dashboard
 can answer cohort questions the operator actually asks:
 - *"How many users signed in via the admin-invite path in week N
  vs. organic OTC?"* — uses `claim_method` (setOnce) on the user
  record + `User Signed In` events with `method`.
 - *"Of admin-invited users, what fraction set a passcode within
  their first session?"* — uses `claim_method` + `passcode_set`
  on the user record + `Page Viewed` events to define "session."
 - *"Which RFCs have the most owner-invited contributors?"* — uses
  per-RFC `Invitation Sent` / `Invitation Accepted` correlated
  via `rfc_slug` + `role_in_rfc`.
 - *"What's the gap between invite-send and invite-claim, broken
  out by inviter?"* — uses `Invitation Sent` (inviter's session,
  inviter `user_id`) + `Invitation Accepted` (invitee's session,
  invitee `user_id` after the BEFORE-track identify) joined on
  `rfc_slug` + inviter (the inviter's id is the same id on both
  events because both invite and claim sides observe it).
 The Part-A audit (per `ohm-rfc/ROADMAP.md` #21) confirms these
 shapes against real data once a week of beta traffic is in. The
 audit is a point-in-time pass; this chapter is the standing
 discipline that keeps future work in shape.
 ### 21.8 Secret vs. public — overlay binding
 The Amplitude browser API key (`VITE_AMPLITUDE_API_KEY`) is
 **bundle-embedded by design**: it appears as a literal string in
 the deployment's JavaScript bundle, visible to anyone with browser
 dev tools. The vendor's installation prompt embeds it inline. This
 puts it in the same category as Cloudflare Turnstile's site key
 (`VITE_TURNSTILE_SITE_KEY`, v0.12.0) — public, not secret.
 Deployments **MUST** bind such keys via their overlay verb (for
 OHM-shape deployments, `flotilla overlay set`), not via the secret
 binding. The matching secret half (the Cloudflare Turnstile
 **secret** key, `CLOUDFLARE_TURNSTILE_SECRET`, used server-side
 for siteverify) is a true secret bound via `flotilla secret set`.
 This per-key distinction is the deployment's responsibility; the
 framework's `*.env.example` files name the binding for each.
 The binding rule baked in mid-Session-K is: **the operator's
 secret bytes never enter the conversation with an assistant**,
 even as one offered option. The conversation-layer corollary of
 the build-pipeline §3-invariant-1 rule from
 `ohm-rfc-app-flotilla/SPEC.md` is that sessions publish in full,
 and a secret in a transcript is a leaked secret. The canonical
 secret-set gesture for OHM is `pbpaste | flotilla secret set
 <deployment> <SECRET_NAME>` (the value goes clipboard → stdin →
 Secret Manager without ever appearing in shell history or the
 model context). Non-OHM deployments inherit the same discipline
 through their own deploy tooling.
 ### 21.9 §19.2 candidates surfaced by this chapter
 - **Session-replay-specific consent category.** v0.13.0's cookie
  banner has a single `analytics` toggle that gates both event
  counters and full-DOM session replay. Recording has a larger
  privacy footprint than counters; a separate consent category
  for session replay is the cleaner shape. Captured here and in
  `ohm-rfc/ROADMAP.md` #21 Part A.
 - **Bundle-size budget for the analytics wrapper.** The
  `@amplitude/unified` package adds ~150 KB gzipped (the session-
  replay recorder is the bulk). The consent-gated lazy import
  keeps the cost off the initial bundle for users who haven't
  opted in; the post-consent init path has not been measured
  for jank. Captured in #21 Part A.
 - **Property-shape lint.** The conventions in §21.1 / §21.2 are
  enforced today by review discipline. A small lint (CI grep
  against `track(` / `identify(` callsites with a property-key
  allowlist + a PII-name denylist) is a future affordance that
  catches drift mechanically.
 - **Hashed `target_email` derivation.** §21.2 names SHA-256 of
  the normalized lower-cased email as the hashing function. The
  framework does not currently expose a helper for this — a
  small `frontend/src/lib/hash.js` or `backend/app/hash.py` that
  centralizes the normalization + hash would make the contract
  enforceable. Captured here.
 ### 21.10 Open question
 The wrapper currently uses the Amplitude SDK's autocapture +
 session-replay defaults. The v0.13.0 consent surface has a single
 toggle for "analytics." Splitting the consent into "analytics"
 vs "session replay" is a §19.2 candidate (above) but settling it
 also requires a privacy-policy update and a re-prompt of
 existing consenters. The cleanest moment to do this is the next
 material privacy-policy revision; the conventions in §21.4 hold
 in the interim.
@@ -1 +1 @@
-0.18.0
+0.19.0
@@ -15,6 +15,7 @@ import json
 from typing import Any
 from fastapi import APIRouter, HTTPException, Request
 from fastapi.responses import PlainTextResponse, Response
 from pydantic import BaseModel, Field
 from . import (
@@ -29,6 +30,7 @@ from . import (
    db,
    device_trust as device_trust_mod,
    docs as docs_mod,
    docs_sessions,
    entry as entry_mod,
    cache,
    funder,
@@ -143,6 +145,122 @@ def make_router(
        payload = docs_mod.load()
        return {"body": payload["body"]}
    # ---------------------------------------------------------------
    # v0.19.0 / roadmap item #30 — /api/docs/sessions/*
    #
    # The framework mediates reads against the public
    # `wiggleverse/ohm-session-history` gitea repo so the rendered
    # `/docs/sessions/*` surface inherits the same chrome as the
    # /docs/user-guide route and doesn't require a cross-origin
    # gesture from the frontend. See backend/app/docs_sessions.py
    # for the cache shape and env knobs.
    #
    # The route mapping for the three `status` values returned by
    # the fetchers:
    #
    #   "ok"     → HTTP 200, payload as documented per endpoint
    #   "404"    → HTTP 200/404 depending on the endpoint (the
    #              manifest's empty state is 200 + {} so the
    #              frontend can short-circuit without an error
    #              banner; transcripts/about return 404 so the
    #              frontend can render its own empty-state)
    #   "error"  → HTTP 502, {"error": ..., "detail": ...} so the
    #              frontend retry surface reads as "couldn't reach
    #              the session-history repo" rather than as a
    #              generic 5xx.
    # ---------------------------------------------------------------
    @router.get("/api/docs/sessions/manifest")
    async def get_sessions_manifest() -> dict[str, Any]:
        result = await docs_sessions.fetch_manifest()
        if result["status"] == "ok":
            return result["manifest"]
        if result["status"] == "404":
            # Empty-state contract: render no session rows in the
            # flyout but don't show an error banner. The frontend
            # treats `{}` as "no sessions published yet".
            return {}
        raise HTTPException(
            status_code=502,
            detail={
                "error": "session-history fetch failed",
                "detail": result.get("detail", "unknown"),
            },
        )
    @router.get("/api/docs/sessions/about")
    async def get_sessions_about() -> Response:
        result = await docs_sessions.fetch_about()
        if result["status"] == "ok":
            return PlainTextResponse(
                content=result["body"],
                media_type="text/markdown; charset=utf-8",
            )
        if result["status"] == "404":
            raise HTTPException(
                status_code=404,
                detail="session-history README not yet published",
            )
        raise HTTPException(
            status_code=502,
            detail={
                "error": "session-history fetch failed",
                "detail": result.get("detail", "unknown"),
            },
        )
    @router.get("/api/docs/sessions/{nnnn}/index")
    async def get_sessions_index(nnnn: str) -> dict[str, Any]:
        if not docs_sessions._is_valid_session_dir(nnnn):
            # 400 over 404: the request itself is malformed (the
            # session directory name doesn't match `^\d{4}$`),
            # distinct from "no such session published yet".
            raise HTTPException(status_code=400, detail="invalid session directory")
        result = await docs_sessions.fetch_session_index(nnnn)
        if result["status"] == "ok":
            return {"files": result["files"]}
        if result["status"] == "404":
            raise HTTPException(
                status_code=404,
                detail="no transcripts published for this session",
            )
        raise HTTPException(
            status_code=502,
            detail={
                "error": "session-history fetch failed",
                "detail": result.get("detail", "unknown"),
            },
        )
    @router.get("/api/docs/sessions/{nnnn}/{filename}")
    async def get_sessions_transcript(nnnn: str, filename: str) -> Response:
        # Path-shape validation before any network — refuses anything
        # that would resolve outside the `NNNN/SESSION-...md` layout
        # (e.g. legacy `SESSION-A-TRANSCRIPT.md` at the repo root,
        # `../etc/passwd`, or any non-numeric session dir).
        if not docs_sessions._is_valid_session_dir(nnnn):
            raise HTTPException(status_code=400, detail="invalid session directory")
        if not docs_sessions._is_valid_transcript_filename(filename):
            raise HTTPException(status_code=400, detail="invalid transcript filename")
        result = await docs_sessions.fetch_transcript(nnnn, filename)
        if result["status"] == "ok":
            return PlainTextResponse(
                content=result["body"],
                media_type="text/markdown; charset=utf-8",
            )
        if result["status"] == "404":
            raise HTTPException(
                status_code=404,
                detail="transcript not found",
            )
        raise HTTPException(
            status_code=502,
            detail={
                "error": "session-history fetch failed",
                "detail": result.get("detail", "unknown"),
            },
        )
    # ---------------------------------------------------------------
    # Auth surface — reads role from our users table per §6.
    # ---------------------------------------------------------------
@@ -0,0 +1,358 @@
 """§14 + roadmap item #30 — on-site sessions-history browser source.
 Sibling of `docs.py` / `philosophy.py` but with a different read shape:
 the bodies here live in the **public** `wiggleverse/ohm-session-history`
 gitea repo (transcripts of every OHM build session, published per the
 ohm-infra SESSION-PROTOCOL.md), not on disk. The framework mediates
 the gitea fetch on behalf of the browser so the rendered `/docs/sessions/*`
 surface inherits the same chrome as `/philosophy` and `/docs/user-guide`
 and stays free of any cross-origin gestures from the frontend.
 Three read endpoints, all anonymous-reachable:
  GET /api/docs/sessions/manifest       — sessions.json (title manifest)
  GET /api/docs/sessions/about          — README.md (the about page)
  GET /api/docs/sessions/<NNNN>/<file>  — a transcript body
  GET /api/docs/sessions/<NNNN>/index   — per-session file listing
 All three sit behind a small in-process TTL cache (manifest TTL default
 60 s, content TTL default 300 s). Negative results (404 from gitea) are
 also cached at the content TTL to avoid hammering gitea when a
 deployment hasn't yet been populated with transcripts. The cache key
 is the URL path on the gitea raw base (or the contents API for the
 per-session listing); the cache lives in-process, plain dict +
 `time.monotonic()` check, no external dep.
 Env knobs:
  OHM_SESSION_HISTORY_RAW_BASE
    Override the gitea raw base URL. Default points at OHM's canonical
    transcript repo:
      https://git.wiggleverse.org/wiggleverse/ohm-session-history/raw/branch/main
    The framework-default value is OHM-flavored because OHM is the
    only deployment to date — a deployment running its own
    transcript repo overrides this via flotilla's overlay.
  OHM_SESSION_HISTORY_CONTENTS_BASE
    Override the gitea contents-API base URL (for the per-session
    listing endpoint, which enumerates files inside a `NNNN/` folder).
    Default:
      https://git.wiggleverse.org/api/v1/repos/wiggleverse/ohm-session-history/contents
  OHM_DOCS_SESSIONS_MANIFEST_TTL_SEC
    Cache TTL for the manifest (default 60 s). The manifest is small
    and changes when a new session is added; 60 s strikes a balance
    between freshness and gitea load.
  OHM_DOCS_SESSIONS_CONTENT_TTL_SEC
    Cache TTL for transcript bodies + README + per-session listings
    (default 300 s = 5 minutes). Transcripts are append-only once
    published, so 5 minutes of staleness is harmless.
 §3 invariant 1 is preserved: the framework holds no secret bytes; the
 gitea repo is public, the fetch carries no auth header.
 """
 from __future__ import annotations
 import logging
 import os
 import re
 import threading
 import time
 from typing import Any
 import httpx
 log = logging.getLogger(__name__)
 _DEFAULT_RAW_BASE = (
    "https://git.wiggleverse.org/wiggleverse/ohm-session-history/raw/branch/main"
 )
 _DEFAULT_CONTENTS_BASE = (
    "https://git.wiggleverse.org/api/v1/repos/wiggleverse/ohm-session-history/contents"
 )
 _DEFAULT_MANIFEST_TTL_SEC = 60.0
 _DEFAULT_CONTENT_TTL_SEC = 300.0
 # The transcript filename shape per SESSION-PROTOCOL.md §1. The
 # `<start>--<end>` suffix is optional so legacy renamed-letter
 # transcripts (e.g. `SESSION-0009.0-TRANSCRIPT.md` without timestamps)
 # remain reachable. The `\.\d+(\.\d+)*` after the session number
 # accommodates `0017.0`, `0017.1`, `0017.1.1`, etc.
 _TRANSCRIPT_FILENAME_RE = re.compile(
    r"^SESSION-\d{4}\.\d+(\.\d+)*-TRANSCRIPT"
    r"(-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}--\d{4}-\d{2}-\d{2}T\d{2}-\d{2})?"
    r"\.md$"
 )
 _SESSION_DIR_RE = re.compile(r"^\d{4}$")
 _HTTP_TIMEOUT_SEC = 5.0
 def _env_float(name: str, default: float) -> float:
    raw = os.environ.get(name, "").strip()
    if not raw:
        return default
    try:
        return float(raw)
    except ValueError:
        log.warning("invalid %s=%r — falling back to %s", name, raw, default)
        return default
 def _raw_base() -> str:
    return os.environ.get("OHM_SESSION_HISTORY_RAW_BASE", "").strip() or _DEFAULT_RAW_BASE
 def _contents_base() -> str:
    return (
        os.environ.get("OHM_SESSION_HISTORY_CONTENTS_BASE", "").strip()
        or _DEFAULT_CONTENTS_BASE
    )
 def _manifest_ttl() -> float:
    return _env_float("OHM_DOCS_SESSIONS_MANIFEST_TTL_SEC", _DEFAULT_MANIFEST_TTL_SEC)
 def _content_ttl() -> float:
    return _env_float("OHM_DOCS_SESSIONS_CONTENT_TTL_SEC", _DEFAULT_CONTENT_TTL_SEC)
 # ---------------------------------------------------------------------------
 # In-process TTL cache
 # ---------------------------------------------------------------------------
 #
 # Plain dict + `time.monotonic()` check, no external dep. The cache
 # value is a `(stored_at, payload)` tuple; `payload` may carry an
 # error-shape sentinel for negative caching (404s). Lock guards
 # read-modify-write across worker tasks; entries are immutable once
 # stored so reads under the lock are fast.
 _lock = threading.Lock()
 _cache: dict[str, tuple[float, dict[str, Any]]] = {}
 def _cache_get(key: str, ttl_sec: float) -> dict[str, Any] | None:
    with _lock:
        entry = _cache.get(key)
        if entry is None:
            return None
        stored_at, payload = entry
        if time.monotonic() - stored_at > ttl_sec:
            # Don't evict here; let _cache_put overwrite on next fetch.
            # The stale entry is gated by the TTL check, so it stays
            # invisible to readers regardless.
            return None
        return payload
 def _cache_put(key: str, payload: dict[str, Any]) -> None:
    with _lock:
        _cache[key] = (time.monotonic(), payload)
 def reset_cache() -> None:
    """Drop every cached entry. Test seam — not called in production."""
    with _lock:
        _cache.clear()
 # ---------------------------------------------------------------------------
 # Public fetch surface
 # ---------------------------------------------------------------------------
 #
 # Each fetcher returns a `{status, ...}` dict. `status` is one of:
 #   "ok"     — payload field carries the body
 #   "404"    — gitea returned 404 (or content was missing)
 #   "error"  — gitea returned 5xx, timed out, or returned malformed data
 #
 # The route layer maps these onto HTTP responses; keeping the mapping
 # out of this module makes the cache transparent to the test harness.
 async def _http_get(url: str) -> tuple[int, str]:
    """Perform a single GET against `url`; return (status_code, body).
    On timeout or network error, returns (599, error_message). The 599
    pseudo-status maps to a 502 at the route layer the same way an
    upstream 5xx does — the caller doesn't care which leg of the
    network broke.
    """
    try:
        async with httpx.AsyncClient(timeout=_HTTP_TIMEOUT_SEC) as client:
            r = await client.get(url)
            return r.status_code, r.text
    except httpx.HTTPError as e:
        log.warning("gitea fetch failed for %s: %s", url, e)
        return 599, f"fetch error: {e}"
 def _is_valid_session_dir(nnnn: str) -> bool:
    return bool(_SESSION_DIR_RE.match(nnnn))
 def _is_valid_transcript_filename(filename: str) -> bool:
    return bool(_TRANSCRIPT_FILENAME_RE.match(filename))
 async def fetch_manifest() -> dict[str, Any]:
    """Fetch and parse `sessions.json` from the public repo.
    Returns one of:
      {"status": "ok", "manifest": {...}}        — successful parse
      {"status": "404"}                          — gitea 404 (empty state)
      {"status": "error", "detail": "..."}       — 5xx / timeout / bad JSON
    """
    cache_key = "manifest"
    cached = _cache_get(cache_key, _manifest_ttl())
    if cached is not None:
        return cached
    url = f"{_raw_base()}/sessions.json"
    status, body = await _http_get(url)
    if status == 200:
        try:
            import json
            data = json.loads(body)
        except (json.JSONDecodeError, ValueError) as e:
            payload: dict[str, Any] = {
                "status": "error",
                "detail": f"sessions.json malformed: {e}",
            }
            # Don't cache parse errors — give the upstream a chance to
            # fix the file without waiting for TTL expiry.
            return payload
        if not isinstance(data, dict):
            return {
                "status": "error",
                "detail": "sessions.json is not a JSON object",
            }
        payload = {"status": "ok", "manifest": data}
        _cache_put(cache_key, payload)
        return payload
    if status == 404:
        payload = {"status": "404"}
        _cache_put(cache_key, payload)
        return payload
    return {"status": "error", "detail": f"upstream returned {status}"}
 async def fetch_about() -> dict[str, Any]:
    """Fetch the repo's README.md (rendered as the /docs/sessions/about page).
    Returns one of:
      {"status": "ok", "body": "..."}
      {"status": "404"}
      {"status": "error", "detail": "..."}
    """
    cache_key = "about:README.md"
    cached = _cache_get(cache_key, _content_ttl())
    if cached is not None:
        return cached
    url = f"{_raw_base()}/README.md"
    status, body = await _http_get(url)
    if status == 200:
        payload: dict[str, Any] = {"status": "ok", "body": body}
        _cache_put(cache_key, payload)
        return payload
    if status == 404:
        payload = {"status": "404"}
        _cache_put(cache_key, payload)
        return payload
    return {"status": "error", "detail": f"upstream returned {status}"}
 async def fetch_transcript(nnnn: str, filename: str) -> dict[str, Any]:
    """Fetch a single transcript body from `{nnnn}/{filename}` in the repo.
    The caller is expected to have validated `nnnn` and `filename`
    against `_is_valid_session_dir` / `_is_valid_transcript_filename`
    before calling this — invalid paths shouldn't reach the network.
    """
    cache_key = f"transcript:{nnnn}/{filename}"
    cached = _cache_get(cache_key, _content_ttl())
    if cached is not None:
        return cached
    url = f"{_raw_base()}/{nnnn}/{filename}"
    status, body = await _http_get(url)
    if status == 200:
        payload: dict[str, Any] = {"status": "ok", "body": body}
        _cache_put(cache_key, payload)
        return payload
    if status == 404:
        payload = {"status": "404"}
        _cache_put(cache_key, payload)
        return payload
    return {"status": "error", "detail": f"upstream returned {status}"}
 async def fetch_session_index(nnnn: str) -> dict[str, Any]:
    """List the transcript filenames inside the `{nnnn}/` folder.
    Uses gitea's contents API (one HTTP per session-index page-view per
    cache-TTL) rather than the raw URL — there's no flat way to list a
    folder via the raw mount.
    Returns one of:
      {"status": "ok", "files": ["SESSION-...md", ...]}
      {"status": "404"}
      {"status": "error", "detail": "..."}
    Only filenames that match `_is_valid_transcript_filename` are
    surfaced — sibling files (e.g. an attached `notes.md`) are ignored
    so the /docs/sessions/<NNNN> page never lists a non-transcript
    masquerading as one.
    """
    cache_key = f"index:{nnnn}"
    cached = _cache_get(cache_key, _content_ttl())
    if cached is not None:
        return cached
    url = f"{_contents_base()}/{nnnn}"
    status, body = await _http_get(url)
    if status == 200:
        try:
            import json
            data = json.loads(body)
        except (json.JSONDecodeError, ValueError) as e:
            return {
                "status": "error",
                "detail": f"contents API response malformed: {e}",
            }
        if not isinstance(data, list):
            return {
                "status": "error",
                "detail": "contents API returned non-list",
            }
        files: list[str] = []
        for entry in data:
            if not isinstance(entry, dict):
                continue
            if entry.get("type") != "file":
                continue
            name = entry.get("name")
            if not isinstance(name, str):
                continue
            if _is_valid_transcript_filename(name):
                files.append(name)
        files.sort()
        payload: dict[str, Any] = {"status": "ok", "files": files}
        _cache_put(cache_key, payload)
        return payload
    if status == 404:
        payload = {"status": "404"}
        _cache_put(cache_key, payload)
        return payload
    return {"status": "error", "detail": f"upstream returned {status}"}
@@ -0,0 +1,379 @@
 """v0.19.0 / roadmap item #30 — `/api/docs/sessions/*` endpoints.
 The framework mediates reads against the public
 `wiggleverse/ohm-session-history` gitea repo so the rendered
 `/docs/sessions/*` surface inherits the same chrome as `/docs/user-guide`.
 This test suite covers the four endpoints + the in-process TTL cache,
 mocking the upstream HTTP via `httpx.MockTransport` (the same shape the
 rest of the test suite uses for Gitea).
 The tests do NOT spin up the full FakeGitea — they only need to mock
 the gitea raw URL surface (and the contents API for the session-index
 endpoint). Each test owns its mock transport so we can dial in 200 /
 404 / 5xx / timeout responses per case.
 Path-validation tests intentionally bypass the network — a malformed
 `nnnn` or `filename` MUST be rejected at the route layer before any
 upstream call is made.
 """
 from __future__ import annotations
 import json
 import httpx
 import pytest
 from fastapi.testclient import TestClient
 from app import docs_sessions
 # Reuse the proven app-construction fixtures from the proposal vertical
 # (same shape every test file in this repo uses).
 from test_propose_vertical import (  # noqa: F401
    app_with_fake_gitea,
    tmp_env,
 )
 # ---------------------------------------------------------------------------
 # Test scaffolding
 # ---------------------------------------------------------------------------
 class _UpstreamHandler:
    """Records every URL the docs_sessions module fetched and returns
    canned responses keyed by URL substring. Allows the test to assert
    on call count (for cache verification) without needing a full Gitea
    simulator.
    `calls` tracks only URLs that hit the session-history host (the
    `OHM_SESSION_HISTORY_*` bases) so reconciler/Gitea-side calls — which
    also pass through this handler because `httpx.AsyncClient` is a
    shared attribute the gitea-side fixture also monkeypatches — don't
    inflate the count we use for cache-hit assertions.
    """
    _SESSION_HOST_MARKERS = ("ohm-session-history", "wiggleverse/ohm-session-history")
    def __init__(self, responses: dict[str, tuple[int, str]]):
        self.responses = responses
        self.calls: list[str] = []
    def __call__(self, request: httpx.Request) -> httpx.Response:
        url = str(request.url)
        if any(m in url for m in self._SESSION_HOST_MARKERS):
            self.calls.append(url)
        for key, (status, body) in self.responses.items():
            if key in url:
                return httpx.Response(status, text=body)
        # Default: 404. Lets tests skip declaring "the rest is 404".
        return httpx.Response(404, text="not found")
@pytest.fixture
 def patched_httpx(monkeypatch):
    """Provide a hook the test can call to install a MockTransport.
    Returns a closure: `install(handler)` patches
    `app.docs_sessions.httpx.AsyncClient` so every constructed client
    uses the handler's transport.
    NB: the upstream `app_with_fake_gitea` fixture also patches
    `httpx.AsyncClient` (to route gitea calls to a FakeGitea handler),
    and because `httpx` is a single shared module, that patch mutates
    the *same* `AsyncClient` attribute we're about to overwrite. We
    therefore import the unpatched class directly from the
    `httpx._client` module so our install path can construct a fresh
    real client around our MockTransport without going through the
    FakeGitea wrapper.
    """
    from httpx._client import AsyncClient as RealAsyncClient
    def install(handler):
        def patched(*args, **kwargs):
            kwargs["transport"] = httpx.MockTransport(handler)
            return RealAsyncClient(*args, **kwargs)
        monkeypatch.setattr("app.docs_sessions.httpx.AsyncClient", patched)
        return handler
    yield install
@pytest.fixture
 def app(app_with_fake_gitea):
    """Wrap the shared app fixture, resetting the docs-sessions cache so
    cross-test state can't leak. Returns just the FastAPI app — the
    fake-Gitea handle is irrelevant for the docs-sessions surface.
    """
    docs_sessions.reset_cache()
    fastapi_app, _fake = app_with_fake_gitea
    return fastapi_app
 # ---------------------------------------------------------------------------
 # Manifest endpoint
 # ---------------------------------------------------------------------------
 def test_manifest_happy_path(app, patched_httpx):
    manifest_body = json.dumps(
        {
            "0001": {"title": "Bootstrap"},
            "0014": {"title": "Wave 7 driver"},
        }
    )
    patched_httpx(
        _UpstreamHandler({"sessions.json": (200, manifest_body)})
    )
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/manifest")
        assert r.status_code == 200, r.text
        payload = r.json()
        assert payload == {
            "0001": {"title": "Bootstrap"},
            "0014": {"title": "Wave 7 driver"},
        }
 def test_manifest_empty_state(app, patched_httpx):
    """A 404 from gitea means the manifest hasn't been published yet.
    The endpoint returns HTTP 200 + `{}` so the frontend can render the
    no-sessions-yet state without an error banner.
    """
    patched_httpx(_UpstreamHandler({"sessions.json": (404, "not found")}))
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/manifest")
        assert r.status_code == 200, r.text
        assert r.json() == {}
 def test_manifest_upstream_5xx_returns_502(app, patched_httpx):
    patched_httpx(_UpstreamHandler({"sessions.json": (500, "internal")}))
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/manifest")
        assert r.status_code == 502, r.text
        body = r.json()
        assert body["detail"]["error"] == "session-history fetch failed"
 # ---------------------------------------------------------------------------
 # About endpoint
 # ---------------------------------------------------------------------------
 def test_about_happy_path(app, patched_httpx):
    readme = "# OHM session history\n\nWelcome.\n"
    patched_httpx(_UpstreamHandler({"README.md": (200, readme)}))
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/about")
        assert r.status_code == 200, r.text
        assert "text/markdown" in r.headers["content-type"]
        assert r.text == readme
 def test_about_404(app, patched_httpx):
    patched_httpx(_UpstreamHandler({"README.md": (404, "")}))
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/about")
        assert r.status_code == 404, r.text
 def test_about_upstream_5xx_returns_502(app, patched_httpx):
    patched_httpx(_UpstreamHandler({"README.md": (503, "down")}))
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/about")
        assert r.status_code == 502, r.text
 # ---------------------------------------------------------------------------
 # Transcript endpoint
 # ---------------------------------------------------------------------------
 def test_transcript_happy_path(app, patched_httpx):
    body = "# Session 0017.1 — Transcript\n\nbody.\n"
    fname = "SESSION-0017.1-TRANSCRIPT-2026-05-28T08-50--2026-05-28T11-20.md"
    patched_httpx(_UpstreamHandler({fname: (200, body)}))
    with TestClient(app) as client:
        r = client.get(f"/api/docs/sessions/0017/{fname}")
        assert r.status_code == 200, r.text
        assert "text/markdown" in r.headers["content-type"]
        assert r.text == body
 def test_transcript_404(app, patched_httpx):
    fname = "SESSION-9999.0-TRANSCRIPT-2026-01-01T00-00--2026-01-01T00-01.md"
    patched_httpx(_UpstreamHandler({}))  # everything 404s
    with TestClient(app) as client:
        r = client.get(f"/api/docs/sessions/9999/{fname}")
        assert r.status_code == 404, r.text
 def test_transcript_rejects_invalid_session_dir(app, patched_httpx):
    """`nnnn` must be exactly 4 digits. `abcd` fails before any
    network call.
    """
    handler = _UpstreamHandler({})
    patched_httpx(handler)
    with TestClient(app) as client:
        r = client.get(
            "/api/docs/sessions/abcd/"
            "SESSION-0001.0-TRANSCRIPT-2026-01-01T00-00--2026-01-01T00-01.md"
        )
        assert r.status_code == 400, r.text
    assert handler.calls == [], "rejected path must not hit the network"
 def test_transcript_rejects_path_traversal(app, patched_httpx):
    """A filename that doesn't match the SESSION-NNNN.M-TRANSCRIPT regex
    is rejected. `../etc/passwd` doesn't match; neither does the legacy
    flat-root `SESSION-A-TRANSCRIPT.md`.
    """
    handler = _UpstreamHandler({})
    patched_httpx(handler)
    with TestClient(app) as client:
        # Path traversal — but FastAPI normalizes `..` in the path before
        # routing, so this resolves to /api/docs/sessions/0001/etc/passwd
        # which routes to the same handler with filename=etc/passwd, and
        # gets rejected as an invalid transcript filename. Even if the
        # normalization didn't apply (some intermediary), the regex
        # check rejects anything not matching the SESSION- prefix.
        r = client.get(
            "/api/docs/sessions/0001/etc%2Fpasswd"
        )
        # 400 (filename validation) or 404 (path didn't match the
        # route); both reject before any network call. Either is
        # acceptable — what matters is that we never fetched it.
        assert r.status_code in (400, 404), r.text
    assert handler.calls == [], "rejected path must not hit the network"
 def test_transcript_rejects_legacy_flat_filename(app, patched_httpx):
    """Legacy `SESSION-A-TRANSCRIPT.md` (letter form) doesn't match the
    numeric regex — by design, since post-#23 transcripts live in
    `NNNN/` folders with numeric names. Reject 400.
    """
    handler = _UpstreamHandler({})
    patched_httpx(handler)
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/0001/SESSION-A-TRANSCRIPT.md")
        assert r.status_code == 400, r.text
    assert handler.calls == [], "rejected path must not hit the network"
 def test_transcript_upstream_5xx_returns_502(app, patched_httpx):
    fname = "SESSION-0001.0-TRANSCRIPT-2026-01-01T00-00--2026-01-01T00-01.md"
    patched_httpx(_UpstreamHandler({fname: (502, "bad gateway")}))
    with TestClient(app) as client:
        r = client.get(f"/api/docs/sessions/0001/{fname}")
        assert r.status_code == 502, r.text
 # ---------------------------------------------------------------------------
 # Session-index endpoint
 # ---------------------------------------------------------------------------
 def test_session_index_happy_path(app, patched_httpx):
    """The contents API returns a JSON list of file entries. The
    endpoint filters to entries that match the transcript regex and
    sorts them.
    """
    # Two transcripts (driver + subagent) + a non-transcript sibling
    # that must be filtered out.
    listing = json.dumps(
        [
            {
                "name": "SESSION-0017.0-TRANSCRIPT-"
                "2026-05-28T08-30--2026-05-28T12-00.md",
                "type": "file",
            },
            {
                "name": "SESSION-0017.1-TRANSCRIPT-"
                "2026-05-28T08-50--2026-05-28T11-20.md",
                "type": "file",
            },
            {"name": "notes.md", "type": "file"},  # not a transcript
            {"name": "attached-dir", "type": "dir"},  # not a file
        ]
    )
    patched_httpx(_UpstreamHandler({"/contents/0017": (200, listing)}))
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/0017/index")
        assert r.status_code == 200, r.text
        files = r.json()["files"]
        assert files == [
            "SESSION-0017.0-TRANSCRIPT-2026-05-28T08-30--2026-05-28T12-00.md",
            "SESSION-0017.1-TRANSCRIPT-2026-05-28T08-50--2026-05-28T11-20.md",
        ]
 def test_session_index_404(app, patched_httpx):
    patched_httpx(_UpstreamHandler({}))  # everything 404s
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/9999/index")
        assert r.status_code == 404, r.text
 def test_session_index_rejects_invalid_session_dir(app, patched_httpx):
    handler = _UpstreamHandler({})
    patched_httpx(handler)
    with TestClient(app) as client:
        r = client.get("/api/docs/sessions/abc/index")
        assert r.status_code == 400, r.text
    assert handler.calls == [], "rejected path must not hit the network"
 # ---------------------------------------------------------------------------
 # Cache behavior
 # ---------------------------------------------------------------------------
 def test_manifest_cache_hits_within_ttl(app, patched_httpx, monkeypatch):
    """Two consecutive manifest calls within the TTL window should
    issue exactly one HTTP request to gitea.
    """
    # Generous TTL so the test never races.
    monkeypatch.setenv("OHM_DOCS_SESSIONS_MANIFEST_TTL_SEC", "60")
    handler = _UpstreamHandler(
        {"sessions.json": (200, json.dumps({"0001": {"title": "x"}}))}
    )
    patched_httpx(handler)
    with TestClient(app) as client:
        r1 = client.get("/api/docs/sessions/manifest")
        r2 = client.get("/api/docs/sessions/manifest")
    assert r1.status_code == 200
    assert r2.status_code == 200
    assert len(handler.calls) == 1, (
        f"expected one upstream call, got {handler.calls}"
    )
 def test_transcript_cache_hits_within_ttl(app, patched_httpx, monkeypatch):
    monkeypatch.setenv("OHM_DOCS_SESSIONS_CONTENT_TTL_SEC", "300")
    fname = "SESSION-0001.0-TRANSCRIPT-2026-01-01T00-00--2026-01-01T00-01.md"
    handler = _UpstreamHandler({fname: (200, "# body\n")})
    patched_httpx(handler)
    with TestClient(app) as client:
        r1 = client.get(f"/api/docs/sessions/0001/{fname}")
        r2 = client.get(f"/api/docs/sessions/0001/{fname}")
    assert r1.status_code == 200
    assert r2.status_code == 200
    assert len(handler.calls) == 1
 def test_transcript_404_is_cached(app, patched_httpx, monkeypatch):
    """Negative caching: a 404 result is cached at the content TTL so a
    deployment with no published transcripts doesn't hammer gitea on
    every navigation. Documented in `docs_sessions.fetch_transcript`.
    """
    monkeypatch.setenv("OHM_DOCS_SESSIONS_CONTENT_TTL_SEC", "300")
    fname = "SESSION-9999.0-TRANSCRIPT-2026-01-01T00-00--2026-01-01T00-01.md"
    handler = _UpstreamHandler({})  # everything 404s
    patched_httpx(handler)
    with TestClient(app) as client:
        r1 = client.get(f"/api/docs/sessions/9999/{fname}")
        r2 = client.get(f"/api/docs/sessions/9999/{fname}")
    assert r1.status_code == 404
    assert r2.status_code == 404
    assert len(handler.calls) == 1, "negative caching should suppress the 2nd call"
@@ -1,7 +1,7 @@
 {
  "name": "rfc-app-frontend",
  "private": true,
-  "version": "0.18.0",
+  "version": "0.19.0",
  "type": "module",
  "scripts": {
    "dev": "vite",
@@ -2193,3 +2193,199 @@
  font-size: 11px; text-transform: uppercase;
  color: #6b7280; letter-spacing: 0.05em; font-weight: 600;
 }
 /* ──────────────────────────────────────────────────────────────────
   v0.19.0 / roadmap item #30 — /docs/* flyout + sessions browser.
   The shell is `.docs-layout` (header + body). The body is a flex
   row: `.docs-nav` is the persistent left sidebar on desktop and a
   slide-out drawer on mobile (toggled by the `.docs-drawer-toggle`
   icon in `.docs-header`). The content area `.docs-content` mounts
   the sub-route via React Router's <Outlet/>.
   The article body inside each sub-route reuses `.philosophy-body`
   (defined above) for the markdown rendering — same `marked` lib,
   same typography. The new classes here just handle the chrome
   (sidebar + drawer + header).
   ────────────────────────────────────────────────────────────────── */
 .docs-layout {
  height: 100%;
  display: flex; flex-direction: column;
 }
 .docs-header {
  display: flex; align-items: center; gap: 12px;
  padding: 12px 24px 12px 16px;
  border-bottom: 1px solid #f0f0ee;
  flex-shrink: 0;
 }
 .docs-back, .docs-drawer-toggle {
  border: none; background: none; cursor: pointer;
  color: #4b5563; font-size: 13px;
  padding: 4px 8px; border-radius: 4px;
 }
 .docs-back:hover, .docs-drawer-toggle:hover {
  background: #f3f4f6; color: #111;
 }
 .docs-drawer-toggle {
  display: none;
  font-size: 18px;
  line-height: 1;
 }
 .docs-title {
  font-size: 13px; color: #6b7280;
  text-transform: uppercase; letter-spacing: 0.08em;
 }
 .docs-signin {
  margin-left: auto;
  font-size: 13px; color: #4b5563; text-decoration: none;
 }
 .docs-signin:hover { color: #111; text-decoration: underline; }
 .docs-body {
  flex: 1; min-height: 0;
  display: flex; flex-direction: row;
  position: relative;
 }
 .docs-nav {
  flex-shrink: 0;
  width: 260px;
  border-right: 1px solid #f0f0ee;
  padding: 24px 20px;
  overflow-y: auto;
  background: #fafaf9;
 }
 .docs-nav-inner { display: flex; flex-direction: column; gap: 24px; }
 .docs-nav-section { display: flex; flex-direction: column; gap: 8px; }
 .docs-nav-section-label {
  font-size: 11px; font-weight: 600;
  text-transform: uppercase; letter-spacing: 0.08em;
  color: #6b7280;
 }
 .docs-nav-list {
  list-style: none; padding: 0; margin: 0;
  display: flex; flex-direction: column; gap: 2px;
 }
 .docs-nav-list a {
  display: block;
  padding: 6px 10px; border-radius: 4px;
  color: #1f2937; text-decoration: none;
  font-size: 14px; line-height: 1.4;
  word-break: break-word;
 }
 .docs-nav-list a:hover { background: #f0f0ee; }
 .docs-nav-list a.active {
  background: #e7e5e4; color: #111; font-weight: 600;
 }
 .docs-nav-skeleton .skeleton-row {
  display: block;
  height: 14px; margin: 8px 10px;
  background: linear-gradient(90deg, #f0f0ee 25%, #e7e5e4 50%, #f0f0ee 75%);
  background-size: 200% 100%;
  border-radius: 4px;
  animation: docs-skeleton-shimmer 1.2s ease-in-out infinite;
 }
@keyframes docs-skeleton-shimmer {
  0%   { background-position: 200% 0; }
  100% { background-position: -200% 0; }
 }
 .docs-nav-error {
  padding: 8px 10px;
  font-size: 13px; color: #9a3412;
  background: #fff7ed; border: 1px solid #fed7aa; border-radius: 4px;
  display: flex; flex-direction: column; gap: 6px;
 }
 .docs-nav-error button {
  align-self: flex-start;
  background: #fff; border: 1px solid #fed7aa;
  color: #9a3412; font-size: 12px;
  padding: 4px 8px; border-radius: 4px; cursor: pointer;
 }
 .docs-nav-error button:hover { background: #fff7ed; }
 .docs-content {
  flex: 1; min-width: 0;
  overflow-y: auto;
  padding: 24px 32px 64px;
 }
 .docs-article {
  max-width: 760px;
  margin: 0 auto;
 }
 .docs-article-title {
  font-size: 28px; font-weight: 700; margin: 0 0 24px;
  letter-spacing: -0.01em;
  color: #111;
 }
 .docs-breadcrumbs { margin: 0 0 16px; font-size: 13px; }
 .docs-breadcrumbs a {
  color: #4b5563; text-decoration: none;
 }
 .docs-breadcrumbs a:hover { color: #111; text-decoration: underline; }
 .docs-session-files {
  list-style: none; padding: 0; margin: 0;
  display: flex; flex-direction: column; gap: 6px;
 }
 .docs-session-files a {
  display: block;
  padding: 10px 14px; border-radius: 6px;
  background: #fafaf9; border: 1px solid #f0f0ee;
  color: #1f2937; text-decoration: none;
  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
  font-size: 13px; word-break: break-all;
 }
 .docs-session-files a:hover {
  background: #f3f4f6; border-color: #e5e7eb;
 }
 .docs-empty, .docs-error {
  padding: 16px; border-radius: 6px;
  background: #fafaf9; border: 1px solid #f0f0ee;
  font-size: 14px; line-height: 1.6; color: #4b5563;
 }
 .docs-error { background: #fef2f2; border-color: #fecaca; color: #991b1b; }
 .docs-error button {
  margin-top: 10px;
  background: #fff; border: 1px solid #fecaca;
  color: #991b1b; font-size: 13px;
  padding: 6px 12px; border-radius: 4px; cursor: pointer;
 }
 .docs-error button:hover { background: #fef2f2; }
 .docs-drawer-scrim {
  display: none;
  position: absolute;
  inset: 0;
  background: rgba(0,0,0,0.3);
  border: none; padding: 0;
  cursor: pointer;
  z-index: 5;
 }
 /* Mobile: the sidebar becomes a slide-out drawer. */
@media (max-width: 720px) {
  .docs-drawer-toggle { display: inline-block; }
  .docs-nav {
    position: absolute;
    top: 0; bottom: 0; left: 0;
    width: 80%; max-width: 320px;
    z-index: 10;
    transform: translateX(-100%);
    transition: transform 200ms ease-out;
    box-shadow: 2px 0 8px rgba(0,0,0,0.1);
  }
  .docs-body--drawer-open .docs-nav {
    transform: translateX(0);
  }
  .docs-body--drawer-open .docs-drawer-scrim {
    display: block;
  }
  .docs-content { padding: 16px 18px 64px; }
 }
@@ -1,5 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
-import { Routes, Route, Link, useLocation, useNavigate } from 'react-router-dom'
+import { Routes, Route, Link, Navigate, useLocation, useNavigate } from 'react-router-dom'
 import { getMe, subscribeToNotifications } from './api'
 import { anonymize, EVENTS, identify, track } from './lib/analytics'
 import Catalog from './components/Catalog.jsx'
@@ -12,7 +12,11 @@ import Landing from './components/Landing.jsx'
 import Login from './components/Login.jsx'
 import BetaPending from './components/BetaPending.jsx'
 import Philosophy from './components/Philosophy.jsx'
-import Docs from './components/Docs.jsx'
+import DocsLayout from './components/DocsLayout.jsx'
 import DocsUserGuide from './components/DocsUserGuide.jsx'
 import DocsSessionsAbout from './components/DocsSessionsAbout.jsx'
 import DocsSessionIndex from './components/DocsSessionIndex.jsx'
 import DocsSessionTranscript from './components/DocsSessionTranscript.jsx'
 import NotificationSettings from './components/NotificationSettings.jsx'
 import Admin from './components/Admin.jsx'
 import AcceptInvitation from './components/AcceptInvitation.jsx'
@@ -233,7 +237,13 @@ export default function App() {
              itself establishes the session on success. */}
          <Route path="/invites/claim" element={<InviteClaim />} />
          <Route path="/philosophy" element={<PhilosophyWithSidebar viewer={viewer} />} />
-          <Route path="/docs" element={<DocsWithSidebar viewer={viewer} />} />
+          {/* v0.19.0 / roadmap item #30 — /docs/* is a hub with sub-nav.
              The bare /docs path redirects to the user guide; sessions
              browser lives at /docs/sessions/*. See DocsLayout.jsx
              for the flyout shape and CHANGELOG v0.19.0 for the
              upgrade path. */}
          <Route path="/docs" element={<Navigate to="/docs/user-guide" replace />} />
          <Route path="/docs/*" element={<DocsWithSidebar viewer={viewer} />} />
          {/* §14.5 / §14.6: cookie-consent companions to /philosophy.
              Available to anonymous and authenticated viewers alike. */}
          <Route path="/privacy" element={<PolicyShell><Privacy /></PolicyShell>} />
@@ -303,9 +313,24 @@ function PhilosophyWithSidebar({ viewer }) {
 }
 function DocsWithSidebar({ viewer }) {
  // v0.19.0 / roadmap item #30 — the `/docs/*` surface is a flyout
  // shell with sub-routes. The shell (sidebar + content area) is the
  // DocsLayout outlet host; the sub-routes mount their respective
  // pages into the outlet. Bare `/docs/sessions` redirects to the
  // sessions about page so deep-linkers and the flyout's "Sessions"
  // header both land somewhere coherent.
  return (
    <main className="chrome-pane">
-      <Docs authenticated={!!viewer} />
+      <Routes>
        <Route element={<DocsLayout authenticated={!!viewer} />}>
          <Route index element={<Navigate to="user-guide" replace />} />
          <Route path="user-guide" element={<DocsUserGuide />} />
          <Route path="sessions" element={<Navigate to="about" replace />} />
          <Route path="sessions/about" element={<DocsSessionsAbout />} />
          <Route path="sessions/:nnnn" element={<DocsSessionIndex />} />
          <Route path="sessions/:nnnn/:filename" element={<DocsSessionTranscript />} />
        </Route>
      </Routes>
    </main>
  )
 }
@@ -720,6 +720,60 @@ export async function getDocs() {
  return jsonOrThrow(await fetch('/api/docs'))
 }
 // ---------------------------------------------------------------------------
 // v0.19.0 / roadmap item #30 — /api/docs/sessions/* surface
 // ---------------------------------------------------------------------------
 //
 // The framework mediates reads against the public
 // `wiggleverse/ohm-session-history` gitea repo so the rendered
 // `/docs/sessions/*` surface inherits the same chrome as
 // `/docs/user-guide`. Three text-bearing endpoints return markdown
 // (Content-Type: text/markdown) and the manifest returns JSON. We
 // wrap each into a small helper.
 //
 // 404 from `getSessionAbout` / `getSessionTranscript` / `getSessionIndex`
 // throws an Error with `.status === 404` so the UI can render its own
 // empty-state. 502 (gitea unreachable) throws `.status === 502` so
 // the UI can offer a retry button.
 export async function getSessionsManifest() {
  // Manifest 404 is mapped server-side to HTTP 200 + `{}` so this
  // helper never throws on the empty-state path.
  return jsonOrThrow(await fetch('/api/docs/sessions/manifest'))
 }
 async function _textOrThrow(res) {
  if (!res.ok) {
    let detail = ''
    try {
      const body = await res.json()
      detail = body.detail || JSON.stringify(body)
    } catch {
      detail = await res.text()
    }
    const error = new Error(detail || `HTTP ${res.status}`)
    error.status = res.status
    throw error
  }
  return res.text()
 }
 export async function getSessionsAbout() {
  return _textOrThrow(await fetch('/api/docs/sessions/about'))
 }
 export async function getSessionTranscript(nnnn, filename) {
  return _textOrThrow(await fetch(
    `/api/docs/sessions/${encodeURIComponent(nnnn)}/${encodeURIComponent(filename)}`
  ))
 }
 export async function getSessionIndex(nnnn) {
  return jsonOrThrow(await fetch(
    `/api/docs/sessions/${encodeURIComponent(nnnn)}/index`
  ))
 }
 // ---------------------------------------------------------------------------
 // Slice 7: admin neighborhood (§17 admin/* + user search for the §15.8 mute
 // typeahead).
@@ -1,51 +0,0 @@
 // `/docs` — the user-facing guide.
 //
 // Sibling of Philosophy.jsx: same chrome, same data path, different
 // source file. Renders DOCS.md verbatim with light chrome around it.
 // Reachable anonymously, same as `/philosophy`, so a visitor can read
 // the guide before deciding to sign in.
 import { useEffect, useState } from 'react'
 import { Link, useNavigate } from 'react-router-dom'
 import MarkdownPreview from './MarkdownPreview.jsx'
 import { getDocs } from '../api.js'
 export default function Docs({ authenticated }) {
  const [body, setBody] = useState('')
  const [error, setError] = useState(null)
  const [loading, setLoading] = useState(true)
  const navigate = useNavigate()
  useEffect(() => {
    let active = true
    getDocs()
      .then(r => { if (active) setBody(r.body || '') })
      .catch(e => { if (active) setError(e.message || String(e)) })
      .finally(() => { if (active) setLoading(false) })
    return () => { active = false }
  }, [])
  return (
    <div className="philosophy-page">
      <header className="philosophy-header">
        <button
          className="philosophy-back"
          onClick={() => (history.length > 1 ? navigate(-1) : navigate('/'))}
        >
          ← Back
        </button>
        <span className="philosophy-title">User guide</span>
        {!authenticated && (
          <Link className="philosophy-signin" to="/">Home</Link>
        )}
      </header>
      <article className="philosophy-body">
        {loading && <p className="muted">Loading…</p>}
        {error && <p className="error">Could not load the guide: {error}</p>}
        {!loading && !error && (
          <MarkdownPreview content={body} />
        )}
      </article>
    </div>
  )
 }
@@ -0,0 +1,211 @@
 // DocsLayout.jsx — v0.19.0 / roadmap item #30.
 //
 // Left-side flyout nav + content area for the `/docs/*` route tree:
 //
 //   /docs                       → redirect to /docs/user-guide
 //   /docs/user-guide            → DOCS.md (existing v0.14.0 content)
 //   /docs/sessions              → redirect to /docs/sessions/about
 //   /docs/sessions/about        → README.md from the sessions repo
 //   /docs/sessions/:nnnn        → per-session index page
 //   /docs/sessions/:nnnn/:file  → per-transcript view
 //
 // The flyout is a persistent left sidebar on desktop and a slide-out
 // drawer on mobile (toggled by the icon button in the docs header).
 // The session list is driven by the `/api/docs/sessions/manifest`
 // fetch:
 //   - loading        → skeleton in the nav (three placeholder rows)
 //   - manifest 502   → error banner in the nav with "Try again"
 //   - empty manifest → only "About" under Sessions; no NNNN rows
 //
 // Amplitude analytics (per SPEC §21):
 //   - track('Doc Viewed', { section: '...' }) on each sub-route mount;
 //     the sub-route component owns the fire (it knows the section).
 //   - flyout buttons + links carry `aria-label` + `data-amp-track-name`
 //     so autocapture rows are readable rather than ":nth-child(7)".
 import { useEffect, useState, useCallback } from 'react'
 import { Link, useNavigate, useLocation, Outlet } from 'react-router-dom'
 import { getSessionsManifest } from '../api.js'
 export default function DocsLayout({ authenticated }) {
  const [manifest, setManifest] = useState(null)
  const [manifestState, setManifestState] = useState('loading') // loading | ok | error
  const [drawerOpen, setDrawerOpen] = useState(false)
  const [reloadTick, setReloadTick] = useState(0)
  const navigate = useNavigate()
  const location = useLocation()
  useEffect(() => {
    let active = true
    setManifestState('loading')
    getSessionsManifest()
      .then(payload => {
        if (!active) return
        setManifest(payload || {})
        setManifestState('ok')
      })
      .catch(() => {
        if (!active) return
        setManifest({})
        setManifestState('error')
      })
    return () => { active = false }
  }, [reloadTick])
  // Close the mobile drawer on every navigation so a click in the nav
  // doesn't strand the user on a drawer-open view.
  useEffect(() => {
    setDrawerOpen(false)
  }, [location.pathname])
  const retryManifest = useCallback(() => {
    setReloadTick(t => t + 1)
  }, [])
  return (
    <div className="docs-layout">
      <header className="docs-header">
        <button
          className="docs-back"
          onClick={() => (history.length > 1 ? navigate(-1) : navigate('/'))}
          aria-label="Back to previous page"
          data-amp-track-name="Docs Back"
        >
          ← Back
        </button>
        <button
          className="docs-drawer-toggle"
          onClick={() => setDrawerOpen(o => !o)}
          aria-label="Toggle docs navigation"
          aria-expanded={drawerOpen}
          data-amp-track-name="Docs Drawer Toggle"
        >
          <span aria-hidden>☰</span>
        </button>
        <span className="docs-title">Docs</span>
        {!authenticated && (
          <Link
            className="docs-signin"
            to="/"
            aria-label="Home"
            data-amp-track-name="Docs Home"
          >
            Home
          </Link>
        )}
      </header>
      <div className={'docs-body' + (drawerOpen ? ' docs-body--drawer-open' : '')}>
        <aside className="docs-nav" aria-label="Docs navigation">
          <DocsNav
            manifest={manifest}
            manifestState={manifestState}
            onRetry={retryManifest}
            currentPath={location.pathname}
          />
        </aside>
        <main className="docs-content">
          <Outlet />
        </main>
      </div>
      {drawerOpen && (
        <button
          className="docs-drawer-scrim"
          aria-label="Close drawer"
          onClick={() => setDrawerOpen(false)}
          data-amp-track-name="Docs Drawer Close"
        />
      )}
    </div>
  )
 }
 function DocsNav({ manifest, manifestState, onRetry, currentPath }) {
  const isActive = (path) => currentPath === path || currentPath.startsWith(path + '/')
  // Sort session keys ascending (newest sessions render last). The
  // manifest's keys are zero-padded 4-digit strings so lexicographic
  // order is the same as numeric.
  const sessionKeys = Object.keys(manifest || {}).sort()
  return (
    <nav className="docs-nav-inner">
      <div className="docs-nav-section">
        <div className="docs-nav-section-label">Docs</div>
        <ul className="docs-nav-list">
          <li>
            <Link
              to="/docs/user-guide"
              className={isActive('/docs/user-guide') ? 'active' : ''}
              aria-label="User Guide"
              data-amp-track-name="Docs Nav User Guide"
            >
              User Guide
            </Link>
          </li>
        </ul>
      </div>
      <div className="docs-nav-section">
        <div className="docs-nav-section-label">Sessions</div>
        <ul className="docs-nav-list">
          <li>
            <Link
              to="/docs/sessions/about"
              className={currentPath === '/docs/sessions/about' ? 'active' : ''}
              aria-label="About sessions"
              data-amp-track-name="Docs Nav Sessions About"
            >
              About
            </Link>
          </li>
        </ul>
        {manifestState === 'loading' && (
          <ul className="docs-nav-list docs-nav-skeleton" aria-hidden>
            <li><span className="skeleton-row" /></li>
            <li><span className="skeleton-row" /></li>
            <li><span className="skeleton-row" /></li>
          </ul>
        )}
        {manifestState === 'error' && (
          <div className="docs-nav-error" role="alert">
            <span>Couldn't load session list.</span>
            <button
              type="button"
              onClick={onRetry}
              aria-label="Retry session list"
              data-amp-track-name="Docs Nav Sessions Retry"
            >
              Try again
            </button>
          </div>
        )}
        {manifestState === 'ok' && sessionKeys.length > 0 && (
          <ul className="docs-nav-list">
            {sessionKeys.map(nnnn => {
              const entry = manifest[nnnn] || {}
              const title = entry.title || ''
              const label = title ? `${nnnn} — ${title}` : nnnn
              const to = `/docs/sessions/${nnnn}`
              return (
                <li key={nnnn}>
                  <Link
                    to={to}
                    className={isActive(to) ? 'active' : ''}
                    aria-label={`Session ${nnnn}${title ? ': ' + title : ''}`}
                    data-amp-track-name="Docs Nav Session"
                    data-amp-track-session={nnnn}
                  >
                    {label}
                  </Link>
                </li>
              )
            })}
          </ul>
        )}
      </div>
    </nav>
  )
 }
@@ -0,0 +1,126 @@
 // DocsSessionIndex.jsx — v0.19.0 / roadmap item #30.
 //
 // Per-session index page at `/docs/sessions/:nnnn`. Lists every
 // transcript published under the session's NNNN/ folder, linked to
 // the per-transcript view.
 //
 // The transcript list comes from `/api/docs/sessions/:nnnn/index`,
 // which the framework derives via the gitea contents API (see
 // backend/app/docs_sessions.fetch_session_index). We also read the
 // session's `title` from the manifest fetch so the page header
 // matches the flyout nav entry.
 import { useEffect, useState, useCallback } from 'react'
 import { Link, useParams } from 'react-router-dom'
 import { getSessionsManifest, getSessionIndex } from '../api.js'
 import { EVENTS, track } from '../lib/analytics'
 export default function DocsSessionIndex() {
  const { nnnn } = useParams()
  const [title, setTitle] = useState('')
  const [files, setFiles] = useState([])
  const [status, setStatus] = useState('loading') // loading | ok | notfound | error
  const [reloadTick, setReloadTick] = useState(0)
  useEffect(() => {
    track(EVENTS.DOC_VIEWED, { section: `sessions/${nnnn}` })
  }, [nnnn])
  // Title from manifest — cheap, manifest is cached server-side.
  useEffect(() => {
    let active = true
    getSessionsManifest()
      .then(payload => {
        if (!active) return
        const entry = payload && payload[nnnn]
        setTitle((entry && entry.title) || '')
      })
      .catch(() => {
        // Title is decorative; failure to load just leaves the header
        // showing the bare NNNN. The transcript list fetch below is
        // the load-bearing one.
      })
    return () => { active = false }
  }, [nnnn])
  // File list from the per-session index endpoint.
  useEffect(() => {
    let active = true
    setStatus('loading')
    getSessionIndex(nnnn)
      .then(payload => {
        if (!active) return
        setFiles((payload && payload.files) || [])
        setStatus('ok')
      })
      .catch(e => {
        if (!active) return
        if (e.status === 404) {
          setStatus('notfound')
        } else {
          setStatus('error')
        }
      })
    return () => { active = false }
  }, [nnnn, reloadTick])
  const retry = useCallback(() => setReloadTick(t => t + 1), [])
  const header = title ? `${nnnn} — ${title}` : `Session ${nnnn}`
  return (
    <article className="docs-article">
      <h1 className="docs-article-title">{header}</h1>
      {status === 'loading' && <p className="muted">Loading…</p>}
      {status === 'notfound' && (
        <div className="docs-empty">
          <p>
            No transcripts have been published for this session yet.{' '}
            <Link
              to="/docs/sessions/about"
              aria-label="About sessions"
              data-amp-track-name="Docs Session Empty About Link"
            >
              About sessions
            </Link>
          </p>
        </div>
      )}
      {status === 'error' && (
        <div className="docs-error" role="alert">
          <p>Couldn't reach the session-history repo.</p>
          <button
            type="button"
            onClick={retry}
            aria-label="Retry"
            data-amp-track-name="Docs Session Index Retry"
          >
            Try again
          </button>
        </div>
      )}
      {status === 'ok' && files.length === 0 && (
        <div className="docs-empty">
          <p>This session has no transcripts published.</p>
        </div>
      )}
      {status === 'ok' && files.length > 0 && (
        <ul className="docs-session-files">
          {files.map(f => (
            <li key={f}>
              <Link
                to={`/docs/sessions/${nnnn}/${f}`}
                aria-label={`Open transcript ${f}`}
                data-amp-track-name="Docs Session Transcript Open"
                data-amp-track-session={nnnn}
                data-amp-track-filename={f}
              >
                {f}
              </Link>
            </li>
          ))}
        </ul>
      )}
    </article>
  )
 }
@@ -0,0 +1,96 @@
 // DocsSessionTranscript.jsx — v0.19.0 / roadmap item #30.
 //
 // Per-transcript view at `/docs/sessions/:nnnn/:filename`. Fetches the
 // transcript body via the backend mediator and renders it through the
 // shared MarkdownPreview.
 //
 // Empty-state contract:
 //   404 → "This transcript isn't published yet" with a link back to
 //         the parent session index
 //   502 → "Couldn't reach the session-history repo" + retry button
 import { useEffect, useState, useCallback } from 'react'
 import { Link, useParams } from 'react-router-dom'
 import MarkdownPreview from './MarkdownPreview.jsx'
 import { getSessionTranscript } from '../api.js'
 import { EVENTS, track } from '../lib/analytics'
 export default function DocsSessionTranscript() {
  const { nnnn, filename } = useParams()
  const [body, setBody] = useState('')
  const [status, setStatus] = useState('loading') // loading | ok | notfound | error
  const [reloadTick, setReloadTick] = useState(0)
  useEffect(() => {
    track(EVENTS.DOC_VIEWED, { section: `sessions/${nnnn}/${filename}` })
  }, [nnnn, filename])
  useEffect(() => {
    let active = true
    setStatus('loading')
    getSessionTranscript(nnnn, filename)
      .then(text => {
        if (!active) return
        setBody(text || '')
        setStatus('ok')
      })
      .catch(e => {
        if (!active) return
        if (e.status === 404) {
          setStatus('notfound')
        } else {
          setStatus('error')
        }
      })
    return () => { active = false }
  }, [nnnn, filename, reloadTick])
  const retry = useCallback(() => setReloadTick(t => t + 1), [])
  return (
    <article className="docs-article">
      <div className="docs-breadcrumbs">
        <Link
          to={`/docs/sessions/${nnnn}`}
          aria-label={`Back to session ${nnnn} index`}
          data-amp-track-name="Docs Transcript Back To Index"
        >
          ← Session {nnnn}
        </Link>
      </div>
      {status === 'loading' && <p className="muted">Loading…</p>}
      {status === 'notfound' && (
        <div className="docs-empty">
          <p>This transcript isn't published yet.</p>
          <p>
            <Link
              to={`/docs/sessions/${nnnn}`}
              aria-label={`Back to session ${nnnn}`}
              data-amp-track-name="Docs Transcript Back To Session"
            >
              ← Back to session {nnnn}
            </Link>
          </p>
        </div>
      )}
      {status === 'error' && (
        <div className="docs-error" role="alert">
          <p>Couldn't reach the session-history repo.</p>
          <button
            type="button"
            onClick={retry}
            aria-label="Retry"
            data-amp-track-name="Docs Transcript Retry"
          >
            Try again
          </button>
        </div>
      )}
      {status === 'ok' && (
        <div className="philosophy-body">
          <MarkdownPreview content={body} />
        </div>
      )}
    </article>
  )
 }
@@ -0,0 +1,99 @@
 // DocsSessionsAbout.jsx — v0.19.0 / roadmap item #30.
 //
 // Renders the README.md of the public `wiggleverse/ohm-session-history`
 // repo at `/docs/sessions/about`. The framework backend mediates the
 // gitea fetch (see backend/app/docs_sessions.py); this component
 // handles three response paths:
 //
 //   200 → render the markdown via MarkdownPreview
 //   404 → "About not yet published" empty-state (the upstream README
 //         doesn't exist yet — happens when a deployment hasn't
 //         restructured its session-history repo yet, expected at
 //         v0.19.0 deploy time per the CHANGELOG)
 //   502 → "Couldn't reach the session-history repo" with a retry
 //         button. The retry just re-invokes the fetch — no extra
 //         backoff because the backend cache already smoothes
 //         repeated 502s.
 import { useEffect, useState, useCallback } from 'react'
 import MarkdownPreview from './MarkdownPreview.jsx'
 import { getSessionsAbout } from '../api.js'
 import { EVENTS, track } from '../lib/analytics'
 export default function DocsSessionsAbout() {
  const [body, setBody] = useState('')
  const [status, setStatus] = useState('loading') // loading | ok | notfound | error
  const [reloadTick, setReloadTick] = useState(0)
  useEffect(() => {
    track(EVENTS.DOC_VIEWED, { section: 'sessions/about' })
  }, [])
  useEffect(() => {
    let active = true
    setStatus('loading')
    getSessionsAbout()
      .then(text => {
        if (!active) return
        setBody(text || '')
        setStatus('ok')
      })
      .catch(e => {
        if (!active) return
        if (e.status === 404) {
          setStatus('notfound')
        } else {
          setStatus('error')
        }
      })
    return () => { active = false }
  }, [reloadTick])
  const retry = useCallback(() => setReloadTick(t => t + 1), [])
  return (
    <article className="docs-article">
      <h1 className="docs-article-title">About sessions</h1>
      {status === 'loading' && <p className="muted">Loading…</p>}
      {status === 'notfound' && (
        <div className="docs-empty">
          <p>
            The session-history About page isn't published yet. Sessions
            are still authored — once a few have shipped, this page will
            render the canonical introduction.
          </p>
          <p>
            In the meantime, browse the source repo directly at{' '}
            <a
              href="https://git.wiggleverse.org/wiggleverse/ohm-session-history"
              target="_blank"
              rel="noopener noreferrer"
              aria-label="Open session-history repo on gitea"
              data-amp-track-name="Docs Sessions About Repo Link"
            >
              wiggleverse/ohm-session-history
            </a>.
          </p>
        </div>
      )}
      {status === 'error' && (
        <div className="docs-error" role="alert">
          <p>Couldn't reach the session-history repo.</p>
          <button
            type="button"
            onClick={retry}
            aria-label="Retry"
            data-amp-track-name="Docs Sessions About Retry"
          >
            Try again
          </button>
        </div>
      )}
      {status === 'ok' && (
        <div className="philosophy-body">
          <MarkdownPreview content={body} />
        </div>
      )}
    </article>
  )
 }
@@ -0,0 +1,45 @@
 // DocsUserGuide.jsx — v0.19.0 / roadmap item #30.
 //
 // Renders DOCS.md at `/docs/user-guide`. Was `/docs` before v0.19.0
 // (the v0.14.0 single-route Docs.jsx surface, now superseded). The
 // content path is unchanged: backend reads `DOCS.md` from disk and
 // serves it at `/api/docs`. The body is rendered via the existing
 // `MarkdownPreview` (the same component the `/philosophy` route uses,
 // so we don't introduce a second markdown library).
 import { useEffect, useState } from 'react'
 import MarkdownPreview from './MarkdownPreview.jsx'
 import { getDocs } from '../api.js'
 import { EVENTS, track } from '../lib/analytics'
 export default function DocsUserGuide() {
  const [body, setBody] = useState('')
  const [error, setError] = useState(null)
  const [loading, setLoading] = useState(true)
  useEffect(() => {
    track(EVENTS.DOC_VIEWED, { section: 'user-guide' })
  }, [])
  useEffect(() => {
    let active = true
    getDocs()
      .then(r => { if (active) setBody(r.body || '') })
      .catch(e => { if (active) setError(e.message || String(e)) })
      .finally(() => { if (active) setLoading(false) })
    return () => { active = false }
  }, [])
  return (
    <article className="docs-article">
      <h1 className="docs-article-title">User guide</h1>
      {loading && <p className="muted">Loading…</p>}
      {error && <p className="error">Could not load the guide: {error}</p>}
      {!loading && !error && (
        <div className="philosophy-body">
          <MarkdownPreview content={body} />
        </div>
      )}
    </article>
  )
 }
@@ -97,6 +97,13 @@ export const EVENTS = Object.freeze({
  // v0.17.0 / item #16 — admin-create user + invite email.
  USER_INVITED: 'User Invited',
  INVITE_CLAIMED: 'Invite Claimed',
  // v0.19.0 / item #30 — `/docs/*` flyout + sessions browser. Carries
  // `section`: 'user-guide' | 'sessions/about' | 'sessions/<NNNN>' |
  // 'sessions/<NNNN>/<filename>' so the dashboard can answer which
  // docs surfaces get read most. The transcript-section value includes
  // the filename so an aggregator can group by `sessions/<NNNN>` or by
  // exact transcript.
  DOC_VIEWED: 'Doc Viewed',
 })
 // Internal state.
Author	SHA1	Message	Date
Ben Stull	69a166a6f2	Merge feature/v0.19.0-docs-sessions-browser	2026-05-28 09:14:56 -07:00
Ben Stull	bb5137f176	CHANGELOG: normalize 0.19.0 header (drop 'v' prefix to match surrounding style)	2026-05-28 09:11:58 -07:00
Ben Stull	477f496cbf	Release v0.19.0: /docs nav + on-site sessions browser VERSION + CHANGELOG bump for roadmap item #30. The frontend package.json was bumped alongside the frontend slice; this commit finalizes the canonical VERSION at 0.19.0 and prepends the v0.19.0 CHANGELOG entry with the operator upgrade-steps block (OHM_SESSION_HISTORY_RAW_BASE + the two TTL knobs; all MAY) and the note about graceful degradation when the session-history repo is still flat at deploy time (subsession 0017.2 ships the restructure in parallel). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-28 09:07:27 -07:00
Ben Stull	822f4266f6	v0.19.0 frontend: /docs/* route tree + flyout nav + sessions browser Reorganizes the /docs surface from a single DOCS.md route into a hub with a left-side flyout nav and three new sub-routes for the on-site sessions browser (roadmap item #30): /docs → redirect to /docs/user-guide /docs/user-guide → existing DOCS.md content /docs/sessions → redirect to /docs/sessions/about /docs/sessions/about → README.md of ohm-session-history /docs/sessions/<NNNN> → per-session transcript index /docs/sessions/<NNNN>/<f> → per-transcript view The flyout is a persistent left sidebar on desktop and a slide-out drawer on mobile (toggled by a ☰ button in the docs header). Its session list is driven by the /api/docs/sessions/manifest fetch — loading shows a skeleton; 502 shows an inline retry; empty manifest shows only the "About" row. Each sub-route owns its own empty-state / error handling: - 404 transcripts render "This transcript isn't published yet" with a link back to the parent session index, no JS crash. - 502 (gitea unreachable) renders a retry button. - Manifest 404 is mapped to {} server-side so the flyout renders cleanly with no error banner when no sessions are published yet. Analytics (per SPEC §21): - new EVENTS.DOC_VIEWED ("Doc Viewed") fires on each sub-route mount with `section`: 'user-guide' \| 'sessions/about' \| 'sessions/<NNNN>' \| 'sessions/<NNNN>/<filename>'. - every interactive nav element carries aria-label + data-amp-track-name so autocapture rows are readable. The existing v0.14.0 Docs.jsx component is dropped — its content moved verbatim into DocsUserGuide.jsx; the new layout subsumes the back-button + signed-out home affordances it used to carry. All four new sub-routes reuse the existing MarkdownPreview renderer (marked + mermaid lazy-load) so no second markdown library lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-28 09:07:20 -07:00
Ben Stull	39e57706d9	v0.19.0 backend: /api/docs/sessions/* endpoints + TTL cache Adds the four read endpoints the v0.19.0 /docs/sessions/* surface mounts on top of: - GET /api/docs/sessions/manifest → sessions.json (title map) - GET /api/docs/sessions/about → README.md - GET /api/docs/sessions/<NNNN>/index → per-session transcript list - GET /api/docs/sessions/<NNNN>/<file> → transcript body The framework mediates the gitea fetch so the rendered surface inherits the same chrome as the v0.14.0 /docs route and the browser makes no cross-origin call. Reads are aggressively cached in-process (60s for the manifest, 5min for content) so the framework doesn't hammer git.wiggleverse.org under normal traffic. Negative results (gitea 404) are also cached at the content TTL to absorb the expected empty-state at deploy-time (the parallel ohm-session-history repo restructure ships in driver subsession 0017.2). All four endpoints are anonymous-reachable, sibling to /api/philosophy and /api/docs. Path validation gates the network: only /^\d{4}$/ session dirs and the full SESSION-NNNN.M-TRANSCRIPT-...md filename shape pass to the upstream. Legacy flat-root names (e.g. SESSION-A-TRANSCRIPT.md) and path-traversal attempts are rejected 400 before any fetch. 18 new tests cover the happy paths, 404 empty-states, 502 upstream errors, path-validation rejections, and the cache-hit-within-TTL contract. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-28 09:07:01 -07:00
Ben Stull	ac3513a686	Merge: CONTRIBUTING.md + SPEC.md §21 analytics chapter (Session 0013.1) Docs-only merge from feature/contributing-and-spec-analytics @ `213f686`: - CONTRIBUTING.md (407 lines, new) — how to contribute to rfc-app: branch naming, CHANGELOG strict-descending, RFC 2119 upgrade-steps, SPEC.md §19.2 candidate hygiene, test-coverage expectations, analytics instrumentation checklist (rides #21 Part B), operator- only gestures (including the 'never ask for secret bytes' rule). Cites Sessions E/I/K/L (= 0005.0/0009.0/0011.0/0012.0) as worked examples. - SPEC.md §21 (469 lines, new) — Analytics instrumentation and identity. Ten subsections covering event taxonomy, required prop families, autocapture-friendly DOM patterns, replay masking, consent-gate contract, identity lifecycle (Part C), set vs setOnce taxonomy, cohort implications, overlay-binding rule for VITE_AMPLITUDE_API_KEY, §19.2 candidates from this chapter. No code change, no version bump. Authored by subsession M.1 (= 0013.1) of Session M (= 0013.0); reviewed in Session 0014.0; merged in Session 0014.0 per operator delegation.	2026-05-28 08:29:41 -07:00
Ben Stull	31913b1e53	Merge feature/v0.18.0-email-webhook-hygiene v0.18.0 — email + webhook hygiene per the proposal at ~/git/ohm-infra/RFC-APP-EMAIL-HYGIENE-PROPOSAL.md. All five slices ship; 295 tests passing.	2026-05-28 07:39:39 -07:00
Ben Stull	213f6862d5	docs: CONTRIBUTING.md + SPEC.md §21 analytics chapter Lands roadmap item #19 (CONTRIBUTING + transcript-linked onboarding) and #21 Part B (standing analytics instrumentation discipline) as a single docs commit. No code change, no version bump — these ride a future release or land as a no-bump docs commit at the operator's discretion. CONTRIBUTING.md (new): - Project-evolution framing pointing at wiggleverse/ohm-session-history as the authoritative how-we-got-here record. - Worked-example links into Sessions E (clean small release), I (recovery from deploy fault), K (multi-feature wave with operator-secret pause), L (squash-merge across three parallel features + #21 Part C identity-lifecycle wiring). - PR-shape contract: subagents push feature branches; operator tags + deploys (the pattern driver sessions use). - CHANGELOG strict-descending convention. - RFC 2119 keyword discipline for Upgrade-steps blocks (per §20.4). - §19.2 candidate discipline — architectural deferrals get noted rather than scope-creeping a release. - Test-coverage expectations characterized from the actual ~250-test backend pytest surface (no frontend test runner today; the discipline is build-clean + backend HTTP contract coverage). - Operator-only gestures explicitly enumerated (no tagging, no deploying, no pin moves, no secret bytes in conversation). - Analytics instrumentation checklist (#21 Part B's CONTRIBUTING artifact): named events, autocapture-friendly DOM, replay masking, PR description discipline. SPEC.md §21 (new chapter — Analytics instrumentation and identity): - Placed AFTER §20 versioning rather than between §15 and §16, to avoid renumbering §19.2 / §19.3 — those numbers are load-bearing project nouns referenced from CLAUDE.md, transcripts, and prior commits. §15 carries a new forward-pointer naming §21 as the peer chapter. - §21.1 event-taxonomy conventions (Title Case "Subject Verb", snake_case props, no PII). - §21.2 required prop families per event kind, including the hashed-target_email convention for invite-side events that target a not-yet-user (#12). - §21.3 autocapture-friendly DOM patterns (stable text, aria-label on icon-only buttons, data-amp-track-* on repeated rows, data-amp-track-suppress for noise surfaces). - §21.4 session-replay masking — credentials MUST be masked, PII SHOULD be masked, privacy policy MUST match reality. - §21.5 consent-gate contract — pre-consent no init / no network / no recording; granted→denied → setOptOut(true) within one tick. - §21.6 identity lifecycle (per #21 Part C) — identify with user_id + properties on sign-in; setUserProperties on mid-session change; anonymize on sign-out (after the User Signed Out track); identify-BEFORE-track on invite-claim paths. §21.6.1 set vs setOnce taxonomy with explicit classification rule. - §21.7 cohort-shape implications (informative — what the Amplitude dashboard can actually answer with the conventions). - §21.8 secret-vs-public framing for the overlay binding — Amplitude browser key is public (bundle-embedded), Turnstile secret half is real-secret; canonical pbpaste-pipe gesture for the operator. - §21.9 new §19.2 candidates surfaced (session-replay-specific consent category, bundle-size budget measurement, property- shape CI lint, centralized email-hash helper). - §21.10 open question (consent-category split timing). Grounded in real code: the SPEC chapter cites frontend/src/lib/analytics.js v0.15.0 + the v0.16.0 (AcceptInvitation) + v0.17.0 (InviteClaim) inline #21 Part C wiring as worked examples. RFC 2119 keywords used precisely throughout.	2026-05-28 05:39:46 -07:00