# 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 *un*surfaced (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".
- Optional: add neutral step **captions** (via the demo overlay) to specific
  casts to label moments — text must not name keys (constraint above).
- 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
```sh
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.