rdbms-playground/docs/handoff/20260611-website-handoff-2.md

Website-branch handoff — 2026-06-11 (website-2)

Second handoff for the website work (separate sequence from main's YYYYMMDD-handoff-NN.md). Read website-1 (2026-06-10) first for the original scaffolding context; this note covers everything since.

State

• Branch: website. HEAD e782a28. Working tree clean. Pushed through an earlier point; currently ahead of origin/website (push is the user's step — never push).
• The website lives in website/ (monorepo; the playground crate is at the repo root). Living style guide + binding conventions: website/STYLE.md (read first). Website decisions: docs/website/adr/20260604-adr-website-001.md (the website ADR namespace — see below). Plan: docs/website/plans/20260604-website-implementation-plan.md.

What changed since website-1 (commit highlights, newest first)

e782a28 feat(website): projects cast (vi-nav load picker) + --demo on all casts
927e6b2 Merge branch 'main' (m:n, logging, UI nav, demo overlays, vi-nav)
52860c3 feat(website): casts for first-project/modes/undo-redo; quit via Ctrl-C
ce153bd docs(website): add SQL queries reference page (advanced query surface)
302329d docs(website): record the cast-placement policy in STYLE.md
bb7887e feat(website): relationship-diagram cast on the relationships page
65a48fa feat(website): joins cast on the querying-with-joins guide
c0cc92a docs(website): rewrite Build the library + add Querying with joins guide
10655e4 docs(website): fill the six Reference stubs with worked examples + output
a8f84c9 feat(website): refine casts — trim shell, autoplay+loop landing, cap size
…       (cast pipeline, the astro/starlight upgrade, the ADR-namespace move)

ADR namespace (important — avoids the recurring collision)

Website decision records live in their own namespace: docs/website/adr/ (<date>-adr-website-<NNN>.md, id ADR-website-NNN), indexed by docs/website/adr/README.md. They do not draw from main's global ADR integer pool, so a main ADR and a website ADR can never collide again (this is why the latest merge of main's ADR-0045/0046/0047 was conflict-free). Recorded in ADR-0000 "Numbering discipline". The main docs/adr/README.md intro carries a pointer to the website namespace.

Content status

Done & verified (build clean, grounded in source, forbidden-terms clean):

• Getting started — installation, first-project, modes, example-library.
• Using the playground — command-line-options, the-assistive-editor, the-output-pane, projects, undo-and-history, export-and-import, copy-to-clipboard, getting-help.
• Guides — build-the-library (full 4-table build, 1:n + m:n bridge), querying-with-joins.
• Reference — types, tables, columns, relationships, indexes, constraints, inserting-and-editing-data, querying-and-inspecting, sql-queries (the advanced SELECT surface: DISTINCT, GROUP BY/HAVING, set ops, subqueries, CTEs, CASE/CAST/functions, with a "supported subset" boundary note).
• Concepts — projects-and-storage.
• Landing index.mdx splash with the quickstart cast.

26 pages build clean. Only expected warning: sitemap needs site (Phase B).

asciinema casts — the pipeline + the 7 casts

Pipeline (STYLE.md "asciinema casts", ADR-website-001 §2):

• Driver: autocast (chosen by spike; asciinema-automation can't drive a full-screen TUI). Sources in website/casts-src/casts.mjs; pnpm casts runs casts-src/generate.mjs → autocast YAML → public/casts/<name>.cast. Command-lists are the durable source; .cast files are regenerable — re-run pnpm casts (needs a cargo build binary at ../target/debug).
• Components: Cast.astro (asciinema-player island) wrapped by Demo.astro (the WASM-swap seam, ADR-website-001 §3). Embed via <Demo src="/casts/NAME.cast" … /> in an .mdx page (md can't import).
• Generator features: trims each cast to the in-app region (drops shell launch + the return-to-shell); ends casts with Ctrl-C ({ key: 'CtrlC' }) not a typed quit (invisible, so the cast ends on the last content frame); per-cast holdEnd, dataDir (isolated data root, wiped per run), and --demo is default-on (opt out with demo:false).
• The 7 casts: quickstart (landing, autoplay+loop), assistive-editor, relationship-diagram, joins, modes, undo-redo, projects (the new one: save as → new → load via the picker, navigated with j).

--demo (#22 / ADR-0047) is on for ALL casts

The demonstration overlay shows a badge for special keystrokes ([ENTER], [TAB], arrows, etc.) — plain characters are NOT badged. This makes e.g. the assistive-editor's Tab completion visible ([TAB]), and the projects cast's j/k picker navigation stays unsurfaced (plain chars) by design. Captions exist too (a stealth Ctrl+]-delimited banner) — usable in casts for neutral "point something out" labels, not yet used.

⚠️ Cast tooling limits (don't rediscover these)

• autocast can only send single characters, ASCII control codes (^X), and waits — NO arrows / PageUp/PageDown / Home/End / function keys (those are escape sequences; the per-key delay makes the terminal read a lone Esc — verified). So any interaction we want to demo must be reachable via typeable keys. This is why #24 (vi j/k in the picker) was needed for the projects cast, and why output-pane scrolling has no cast (needs PgUp/PgDn).
• Ctrl+] (caption toggle) and Ctrl-C (quit) ARE sendable (^], ^C).

⚠️ No-advertising constraint (user, 2026-06-11)

The docs must NOT advertise that the load picker supports vi keys, nor that Ctrl+] is the caption/banner trigger. The --demo flag itself MAY be documented lightly as "a teaching helper that shows special keystrokes" — and nothing more. Casts may use vi-nav and captions (the viewer sees only the result/banner, not the keystroke), but cast captions must not name j/k or Ctrl+].

NEXT WORK — priority order

1. Document the features the main merge brought (the biggest gap)

The merge (927e6b2) added app features that are not yet documented:

• m:n convenience command — create m:n relationship … (C4, ADR-0045). The relationships page currently models m:n only via the manual loans-bridge. Document the convenience command (it auto-generates the junction table). Ground in ADR-0045 + tests/it/m2n.rs + tests/typing_surface/create_m2n.rs for exact syntax. Likely a new section on the relationships reference page and/or a mention in the build-the-library guide.
• --demo flag — document on command-line-options as a teaching helper that "shows special keystrokes" (per the no-advertising constraint above — do NOT mention badges-for-vi or captions/Ctrl+]).
• ADR-0046 UI — the schema sidebar (auto-shows on wide terminals, Ctrl-O navigation mode to peek/expand), responsive two-row input + horizontal scroll, and the geometry-fixed hint panel. Decide where in Using the playground (a new "the schema sidebar" page, or fold into the-output-pane / the-assistive-editor). Ground in ADR-0046.
• FK-message fixes + the X1 logging sweep: no user-doc impact (note only).

Whenever output changed because of the merge, re-verify any affected static output blocks (capture-harness recipe below).

2. Consider a final cast re-record sweep + optional captions

• All casts re-record with pnpm casts once the app is "final".
• Chase up two pacing/clarity guidelines across the existing casts (added to STYLE.md "Cast pacing & clarity" 2026-06-11; the projects cast already follows them):
  1. Don't submit a command too fast — a typed-and-Entered-in-one-instant command vanishes before the viewer reads it. Re-review each cast for type-then-instant-Enter (especially modal confirms / short commands) and add a pause before Enter (split type and key:'Enter' steps).
  2. Show state where the sidebar would — at 90 cols the schema sidebar is hidden (ADR-0046), so insert show tables / show table / show data where state changes, so the viewer can follow what happened.
• Review whether caption banners would improve the existing casts. The demo overlay can show a neutral step caption (the stealth Ctrl+] banner) to label or narrate a moment — e.g. marking the phases of the build-the-library/projects casts, or calling out the relationship diagram / the teaching echo in the modes cast. Go cast-by-cast and decide where a caption adds clarity vs. adds noise. Constraint: caption text must not name keys (no j/k, no Ctrl+]); it narrates what is happening, not how it was typed. (Captions are wired but not yet used in any cast.)
• Output-pane scrolling cast remains blocked (PgUp/PgDn unsendable). If desired later, it needs an app-side typeable scroll key (file an enhancement like #24) — otherwise leave it to static docs.

3. Phase B — landing/site polish

• Set Starlight site (production URL) → clears the sitemap warning, enables sitemap + canonical/OG. Then SEO/meta conventions (STYLE #8).
• Logo + favicon; branding palette (staying on Starlight).
• Light/dark player theme: the asciinema player theme is currently fixed (asciinema); sync it to the Starlight theme toggle (folded into STYLE #8).
• Use the frontend-design skill.

4. Open STYLE.md decisions

• #7 Versioning (leaning single-version for launch).
• #8 SEO/meta + the player light/dark theme.

Capture-harness recipe (how to get accurate static output for new pages)

Output blocks must be captured from the real app, never hand-drawn (STYLE.md). Pattern used throughout:

• For pub render fns (render_data_table, render_explain_plan) + the DB worker API: a throwaway external test tests/doc_capture.rs that builds the library schema via Database and prints rendered output; run cargo test --test doc_capture -- --nocapture --ignored; paste verbatim (trim trailing spaces); delete the file.
• For pub(crate) fns (render_structure_with_diagrams, render_relationship_diagram): an in-crate #[ignore] test in src/output_render.rs's test module instead.
• Verify box-drawing integrity after pasting (top ┬ count == bottom ┴, equal line lengths) — a mis-paste truncated a CTE border once and the check caught it.

Verify-after-changes checklist

cd website && pnpm build            # clean; 26 pages; only the `site` warning
# from repo root — forbidden terms must be empty:
grep -rniE '\b(DSL|SQLite|STRICT|rusqlite|PRAGMA)\b' website/src/content/
# internal links + heading anchors: spot-check in dist/ (no link validator installed)
cd website && pnpm casts            # regenerate all casts (needs target/debug binary)

Dev server + tunnel for visual checks (player playback, sizing, badges): cd website && pnpm dev (binds 127.0.0.1:4321) then ssh -L 4321:127.0.0.1:4321 <host>. Visual playback of all 7 casts (now with --demo badges) is still pending a tunnel check by the user.

Process pins

• Commits: user-confirmed (show the message first), no AI attribution, append-only (no amend/rebase/force-push). Push is the user's step.
• Ground every page in source (src/dsl/*, en-US.yaml, the ADRs) — not requirements.md markers. No engine name, no "DSL" in user-facing copy.
• Issues via tea (repo oli/rdbms-playground on git.lazyeval.net; append < /dev/null + timeout 30). Open/related: #22 (demo overlay, implemented), #24 (vi picker nav, implemented). Both merged via 927e6b2.
• Escalate genuine forks; declare epistemic status; write down the /runda DA pass on non-trivial plans.