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>
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