Roadmap item #32 (session/transcript page polish) plus the /docs
surfaces' share of #31, for rfc-app v0.21.0.
- DocsSessionIndex: the session root (/docs/sessions/:nnnn) no longer
renders a dead-end "N transcript(s) — select from the nav"
placeholder. It now renders a transcript INLINE: the lone transcript
for single-transcript sessions, or the `.0` driver transcript (falling
back to first-by-sort) for multi-transcript sessions, with the
remaining siblings listed/linked above the body. URL stays stable to
the session number — inline render, no 301.
- DocsSessionTranscript: adds a compact metadata header above the body
(title; started/ended parsed from the filename's ISO segments,
human-readable; derived duration; optional TL;DR from the manifest's
`tldr` string field, graceful-degrade when absent; external
"View source on git.wiggleverse.org" link). The parse/header helpers
are exported so the inline-collapse view reuses identical rendering.
- Docs.css (new): token-based styling for the new metadata-header +
sibling-list elements only; existing docs classes stay owned by
App.css to avoid racing the #31 sweep.
- DocsUserGuide: loading/error states brought onto the shared
.docs-empty/.docs-error convention with a retry button.
No backend change: /api/docs/sessions/manifest already passes the full
sessions.json entry through, so a `tldr` field on an entry reaches the
frontend with no docs_sessions.py change.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Wave 9 follow-up to roadmap item #30 (Session 0017.0 shipped #30 as v0.19.0;
v0.20.0 lands the operator-feedback follow-ups on top).
1. Specs on /docs/specs/<name> (backend docs_specs.py + frontend DocsSpec.jsx
+ DocsSpecsIndex.jsx). Configured via OHM_DOCS_SPECS; framework default
carries OHM's two specs (rfc-app/SPEC.md + flotilla SPEC.md). Runtime
fetch from gitea raw with 5-min TTL cache, mirroring docs_sessions.py.
2. Nested flyout nav hierarchy (DocsLayout.jsx). Sessions render as a tree
with transcripts nested under each session row (labeled by .N ordinal).
New Specs section between User Guide and Sessions.
3. /docs/sessions/<NNNN> body-list removed (DocsSessionIndex.jsx). Body
becomes a session-overview card; navigation lives in the left nav.
19 new pytest cases for docs_specs (332 backend total green). Frontend
build clean. Sync frontend/package-lock.json version drift (0.15.0 → 0.20.0)
alongside the VERSION + package.json bump.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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>
Ben Stull