From 1fad29c0f9a0574a0f48c73678be98c2bae20e42 Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Fri, 5 Jun 2026 08:13:36 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20ADR-0042=20=E2=80=94=20public=20website?= =?UTF-8?q?=20+=20documentation=20site=20plan?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Planning artifacts for the first public website, recorded before any code is written. - ADR-0042: the decisions — Astro 5 + Starlight + Tailwind v4 (over SvelteKit); asciinema .cast demos reusable in docs (scripted-input driver, not history.log replay); in-page WASM playground deferred behind a stable demo seam, with the portable-core vs native-edge boundary recorded for a future ADR; portable static hosting (Vercel target); monorepo (website/); website is the canonical docs home; full-feature-set docs with "planned" callouts; user-facing copy uses no engine name and no "DSL"; install via prebuilt binaries + package managers. - docs/plans/20260604-adr-0042-website.md: implementation plan with the grounded documentation inventory and phases A–E. - website/STYLE.md: living documentation style guide + open-decisions log. - docs/adr/README.md: index updated for ADR-0042 (numerical order). --- ...2-public-website-and-documentation-site.md | 124 +++++++++++++ docs/adr/README.md | 1 + docs/plans/20260604-adr-0042-website.md | 172 ++++++++++++++++++ website/STYLE.md | 100 ++++++++++ 4 files changed, 397 insertions(+) create mode 100644 docs/adr/0042-public-website-and-documentation-site.md create mode 100644 docs/plans/20260604-adr-0042-website.md create mode 100644 website/STYLE.md diff --git a/docs/adr/0042-public-website-and-documentation-site.md b/docs/adr/0042-public-website-and-documentation-site.md new file mode 100644 index 0000000..3bd3e23 --- /dev/null +++ b/docs/adr/0042-public-website-and-documentation-site.md @@ -0,0 +1,124 @@ +# ADR-0042: Public website and documentation site + +## Status + +Accepted (2026-06-04). Implementation plan: +[`docs/plans/20260604-adr-0042-website.md`](../plans/20260604-adr-0042-website.md). + +## Context + +RDBMS Playground is nearing its first public release and needs a public +website that does two jobs: **attract** — a landing page that shows the +playground in action — and **document** — a thorough, canonical reference +for everything the playground can do. + +The documentation-heavy surface is already implemented and verified (full +simple- and advanced-mode command set, the ten-type vocabulary, +relationships, constraints, indexes, EXPLAIN, undo/history/replay, projects, +export/import, the teaching echo, clipboard, friendly errors, tab completion +and syntax highlighting; 2151 tests passing at the time of writing). The +site is therefore largely a presentation-and-writing effort, not a +wait-for-features one. A grounded inventory of what is shippable now lives +in the implementation plan. + +Several choices here had no canonical default; they were settled during a +planning + `/runda` pass with the user and are recorded below. + +## Decision + +1. **Stack — Astro 5 + Starlight + Tailwind v4.** Astro's content-first, + zero-JS-by-default model with the Starlight docs theme fits a + marketing-landing-plus-heavy-docs site better than the alternative + considered, SvelteKit + Tailwind (the usual go-to here). Interactive + pieces are added as Astro islands (Svelte or vanilla), so Svelte is still + available where it earns its place. Tailwind v4 is wired via the official + `@tailwindcss/vite` plugin; the `@astrojs/starlight-tailwind` plugin + bridges Tailwind with Starlight's theming. + +2. **Demo medium — asciinema.** Showcase sequences are recorded as + asciinema `.cast` files (text-based, small, faithful to the full + alternate-screen render) and embedded with `asciinema-player`. The same + casts are reused inline in the docs — one recording format serves both + the landing page and documentation enrichment. Recordings are produced by + a **scripted-input driver** that types commands into a real PTY with + viewer-friendly pacing; the app's own `history.log` **replay** (ADR-0034) + re-executes commands without typing animation or pacing and is therefore + suitable only for state-deterministic docs snippets, not the hero demo. + +3. **In-page WASM playground — deferred** (OOS: **deferred**, not rejected). + A live, type-it-yourself playground compiled from the Rust app to + WebAssembly is desirable but is a multi-week sub-project, so it does not + block the site. The demo section is designed with a stable seam (a single + `Demo` component contract) so a WASM playground island can replace the + asciinema player later with no change to call sites. Recorded boundary + for that future work: + - **Portable core (runs on `wasm32-unknown-unknown` largely as-is):** + `src/dsl/*` (parser, types, grammar, walker), the pure `App::update()`, + `ui.rs`, `theme.rs`, `friendly/*`, output rendering; an in-memory DB + path already exists (`Connection::open_in_memory()`). `rusqlite` + compiles to the browser target via its `ffi-sqlite-wasm-rs` feature. + - **Native edge needing `cfg`-gated browser replacements:** the + multi-thread Tokio runtime + the dedicated DB **worker thread** + (ADR-0010) → current-thread/in-line async; `crossterm` terminal + + event-stream → a browser backend (e.g. Ratzilla's DOM/Canvas) + DOM + events; `arboard`, `zip`, file persistence (ADR-0015), file logging; + and the rusqlite **backup-API** undo (ADR-0006) → a SQL dump/restore. + When taken up, this becomes its own ADR + iteration plan. + +4. **Hosting — portable static build; Vercel is the likely target.** Astro 5 + builds to static HTML/CSS with no adapter, so the output deploys equally + to Vercel, Cloudflare Pages, Netlify, or GitHub Pages. We avoid coupling + to any one host. **No CI yet** — the site is tested locally (`pnpm dev` / + `pnpm build`) until the repo reaches its public home. + +5. **Repo topology — monorepo.** The site lives under `website/` in the + playground repo; the crate stays at the repo root. The repo as a whole + moves to its public home later; site and crate travel together. + +6. **Canonical docs home — the website.** User-facing documentation lives on + the site. In-repo `docs/` keeps ADRs, handoffs, and development notes; + `docs/simple-mode-limitations.md` (requirement DOC1) was a development aid + and now *feeds* the site's content rather than competing with it. The + sharing recipes promised by requirement E2 become a docs page. + +7. **Documentation scope and conventions.** Document the **full supported + feature set**. Any capability not yet fully implemented (a small minority + — e.g. multi-line input, query cancellation, `seed`, `m:n` convenience, + ER-diagram export, the `show tables`/`relationships`/`indexes` family) is + either omitted or carries a clear **"planned / not yet available"** + callout — never presented as shipped. Two wording rules bind all + user-facing copy: + - **No engine name** (SQLite/STRICT/rusqlite/PRAGMA) — continues the + user-facing posture of ADR-0002; copy says "the database"/"the engine". + - **No "DSL"** — it is internal jargon. The two input modes are **simple + mode** (the playground's keyword command language) and **advanced + mode** (SQL). + +8. **Install documentation — two mechanisms.** The install page documents + **prebuilt release binaries** (self-hosted download — not GitHub + Releases, since the repo will move) and **package managers**. Both can be + written now against the planned mechanisms; concrete download URLs slot in + at release. (Distribution items D1–D3 in `requirements.md` remain the + tracking home for the release tooling itself.) + +## Consequences + +- The site can ship on the strength of already-implemented features; it is + gated on writing and recording, not on finishing the app. +- One recording format (asciinema `.cast`) serves both marketing and docs, + and is reusable as the app evolves (re-run the script, re-record). +- The WASM playground is preserved as a real future option without holding + up launch; the demo seam keeps the upgrade cheap. +- A single canonical docs home removes the divergence risk of maintaining + user docs in two places. +- Website build choices (Decisions 1, 2, 4, 5) are recorded here for + traceability but do not, by themselves, warrant further ADRs; only + app-architecture decisions (notably the future WASM port) will. + +## Out of scope + +- **In-page WASM playground** — *deferred* (see Decision 3); revisit as its + own ADR + iteration plan. +- **Hosted/SaaS playground or a server-backed doc CMS** — *rejected*: a + static site fully satisfies the need, consistent with ADR-0007's + no-hosted-publishing stance. Revisit only if real demand emerges. diff --git a/docs/adr/README.md b/docs/adr/README.md index 13bc423..f4200a2 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -47,3 +47,4 @@ This directory contains the project's ADRs, recorded per - [ADR-0039 — EXPLAIN over advanced-mode SQL queries](0039-explain-over-advanced-sql.md) — **Accepted** (2026-05-27), **implemented 2026-05-30 (issue #7)**, **supersedes ADR-0030 §13 OOS-2**. Lets `explain` wrap the advanced SQL commands (`Select`/`SqlInsert`/`SqlUpdate`/`SqlDelete`, plus `with`/CTE which builds a `Select`) in addition to the DSL `ShowData`/`Update`/`Delete` it already covers (ADR-0028), running `EXPLAIN QUERY PLAN` over the validated SQL text through the existing ADR-0028 span-styled plan tree (advanced mode only; DSL `explain` unchanged in both modes). Implemented via a second `Advanced` `explain` CommandNode (`EXPLAIN_SQL`) registered under the shared `explain` entry word — reusing the established `insert`/`update`/`delete` shared-word dispatch (`decide`: SQL-first / DSL-fallback), so `explain show data …` and DSL-only `--all-rows` still reach the DSL node; rejected a `DynamicSubgrammar` mode-gate (its resolution cache key omits `mode`). `build_explain_sql` slices the inner SQL off the source (excludes `explain`) and reuses the existing SQL builders; `do_explain_plan` runs the carried text verbatim, no params. Advanced `explain update`/`delete` now route through SQL (identical plan, full SQL syntax); DSL-explain tests pinned to simple mode. Reframed OOS-2 as a *deferred* exclusion (per ADR-0000's out-of-scope discipline), not a rejection. OOS (deferred): EXPLAIN of DDL (no query plan exists) - [ADR-0040 — A per-command completion marker (✓/✗) replaces the `[ok]` summary line](0040-completion-marker-replaces-ok-summary.md) — **Accepted 2026-05-30 (issue #9)**, amends ADR-0014 / ADR-0028 / ADR-0019 output conventions, builds on ADR-0037's mode-tagged echo. An audit of the whole command surface found the `[ok] ` summary line duplicates the echo line above it (verb+subject) everywhere; its only unique contribution is the success-vs-error signal (and `explain select` even rendered `[ok] explain` with an empty subject post-ADR-0039). Decision: drop the `[ok]` line and the symmetric `"…" failed:` prefix; the echo line gains a trailing inline **✓** (green, success) / **✗** (red, failure) — `running:` becomes a pending state that resolves to ` ✓/✗` on completion (status set via the existing `rfind(Echo)` lookup). Content (row counts, structure, data, plan tree, teaching echo) unchanged. Scoped to the DSL/data/SQL family that has the redundant echo+`[ok]` pair; app-command `[ok]` lines (`rebuild`/`export`/`now editing`) are payload-bearing, have no echo to mark, and stay as-is. `ok.summary` retired; `dsl.failed` reduced to the rendered reason. Broad but mechanical snapshot churn. OOS: app-command `[ok]` lines, the `[WRN]` validity indicator, and the tag colours (issue #10) - [ADR-0041 — Copy the output panel to the system clipboard](0041-copy-output-to-clipboard.md) — **Accepted 2026-06-02 (issue #11)**, amends ADR-0003's app-command registry (adds **`copy`** / `copy all` / `copy last`). The friction it removes: filing a bug report meant terminal-selecting the output panel and fighting wrapping/borders. New **app-level command** (sigil-free, both modes): `copy` / `copy all` copy the whole panel; `copy last` copies from the most recent echo line to the end. **Mechanism — OSC 52 *and* native (`arboard`), always both**, because OSC 52 acceptance is undetectable (no terminal ack), so a true "fall back when unsupported" can't be built: emit the OSC 52 escape (no new dep — `base64`+`crossterm`; works over SSH; tmux-passthrough-wrapped via `$TMUX`), then a best-effort native write whose failure is ignored (headless host — OSC 52 carried it); the two carry identical content. **Format — plain text verbatim as rendered** (tags, `✓`/`✗`, box-drawing) joined by `\n`, without viewport padding/wrapping; a drift-lock test pins `OutputLine::plain_text` to `render_output_line`. `arboard` added **`--no-default-features`** (drops the `image` crate; X11-only on Linux — `wayland-data-control` deliberately omitted as it ~doubles the dep tree and OSC 52 covers native-Wayland). Security: write-only, scans clean for arboard's tree (cargo audit / osv-scanner / grype), 1Password-maintained, minimal surface. OOS: Markdown export, selection/range, a keybinding, OSC 52 read, `screen` passthrough +- [ADR-0042 — Public website and documentation site](0042-public-website-and-documentation-site.md) — **Accepted 2026-06-04**. The first public website: a marketing landing page plus the **canonical** user docs. Stack **Astro 5 + Starlight + Tailwind v4** (chosen over SvelteKit + Tailwind for a docs-heavy + marketing site; interactive bits as Astro islands). Showcase demos are **asciinema** `.cast` recordings (scripted-input driver for paced, re-recordable sessions — *not* `history.log` replay), reused inline in docs. The **in-page WASM playground is deferred** (OOS: deferred) behind a stable `Demo` seam, with the portable-core (`dsl`/`app`/`ui`, in-memory `rusqlite` via `ffi-sqlite-wasm-rs`) vs native-edge (Tokio/worker-thread/`crossterm`/persistence/backup-API) boundary recorded for a future ADR + iteration plan. Portable **static build** (Vercel target, but host-agnostic); **no CI yet**; **monorepo** (`website/`). Docs cover the **full supported feature set** with "planned" callouts for the unshipped minority; two wording rules bind user-facing copy — **no engine name** (continues ADR-0002) and **no "DSL"** ("simple mode" / "advanced mode"). Install docs cover **prebuilt binaries + package managers** (D1–D3 track the release tooling). Plan: `docs/plans/20260604-adr-0042-website.md` diff --git a/docs/plans/20260604-adr-0042-website.md b/docs/plans/20260604-adr-0042-website.md new file mode 100644 index 0000000..bcabc35 --- /dev/null +++ b/docs/plans/20260604-adr-0042-website.md @@ -0,0 +1,172 @@ +# Plan: public website and documentation site + +**Date:** 2026-06-04 · **Status:** ready to build + +Decisions for this work are recorded in +[ADR-0042](../adr/0042-public-website-and-documentation-site.md): Astro 5 + +Starlight + Tailwind v4; asciinema demos reusable in docs; the in-page WASM +playground deferred behind a stable demo seam; portable static hosting +(Vercel target); monorepo (`website/`); website is the canonical docs home; +full-feature-set docs with "planned" callouts; install docs cover prebuilt +binaries + package managers. This plan is the *how*. + +## Repository layout + +The site lives under `website/` in this repo; the crate stays at the root. + +``` +website/ +├── package.json # pnpm; astro, @astrojs/starlight, tailwind v4 +├── astro.config.mjs # Starlight integration + sidebar nav +├── src/ +│ ├── pages/index.astro # marketing landing (custom, not Starlight) +│ ├── components/ +│ │ ├── Demo.astro # demo SLOT — the WASM-playground seam +│ │ └── Cast.astro # asciinema-player island wrapper +│ ├── content/docs/ # Starlight MDX docs (the bulk of the work) +│ └── styles/ # shared Tailwind + Starlight theme tokens +├── public/casts/ # recorded *.cast asciinema files +├── README.md # local dev + recording recipe +└── STYLE.md # living documentation style guide +``` + +Root `.gitignore` gains `website/node_modules`, `website/dist`, +`website/.astro`. + +## Documentation inventory (grounded — drives Phase D scope) + +Built from `docs/handoff/55–57`, `docs/adr/*`, the command REGISTRY +(`src/dsl/grammar/mod.rs:603`, which also auto-assembles in-app `help`), the +`Command` enum (`src/dsl/command.rs:149`), and +`src/friendly/strings/en-US.yaml` — **not** the coarse `requirements.md` +checkboxes. Test state at survey time: **2151 passing, 0 failing, 1 ignored.** + +**SHIPPED — document as-is (the doc core):** +- Input modes: simple, advanced (SQL), `:` one-shot escape, `mode` command, + per-project mode restore (ADR-0003/0015/0037). +- Full simple-mode command surface: create/drop table; add/drop/rename/ + change column; add/drop 1:n relationship (named, ON DELETE/UPDATE + CASCADE/SET NULL/RESTRICT, `--create-fk`); add/drop index; insert/update/ + delete (required WHERE + `--all-rows`; complex WHERE: AND/OR/NOT, LIKE, + IS NULL, IN, BETWEEN); show table/data (where/limit); add/drop constraint; + explain (ADR-0009/0013/0014/0025/0026/0028/0029). +- Full advanced-mode SQL: CREATE/DROP/ALTER TABLE (cols, constraints, inline + + table FKs, rename, alter-column-type), CREATE [UNIQUE]/DROP INDEX; SELECT + (joins, GROUP BY/HAVING, ORDER BY, LIMIT/OFFSET, UNION/INTERSECT/EXCEPT, + WITH [RECURSIVE] CTEs); INSERT (multi-row, ON CONFLICT, RETURNING)/UPDATE/ + DELETE; full expression grammar incl. CASE, CAST, curated functions; + EXPLAIN over SQL (ADR-0030–0039). +- Types: all ten, advanced-mode SQL aliases, serial/shortid auto-fill + (ADR-0005/0011/0017/0018). Constraints: PK incl. compound, NOT NULL, + UNIQUE, CHECK, DEFAULT, FK (ADR-0029/0013/0035). +- Undo/redo, history.log journal, replay, `--resume`, `--no-undo` + (ADR-0006/0034). Projects & storage: project.yaml + CSV + history.log, + save/save as/load/new/rebuild, temp projects, `--data-dir` + (ADR-0004/0015). Export/import (zip), clipboard copy/copy all/copy last + (ADR-0007/0041). +- Friendly errors (all five categories) + validity indicator + (ADR-0019/0027), DSL→SQL teaching echo (ADR-0038), EXPLAIN plan tree + (ADR-0028), box-drawing tables (ADR-0016), tab completion + syntax + highlighting + in-line editing (ADR-0022). + +**DOCUMENT WITH CAVEAT:** `add unique index` is advanced-only; simple-mode +table rename is intentionally absent (rename is `ALTER TABLE … RENAME TO`); +FK references target single-column PKs only (compound-PK FK refs pending); +`help ` detail and richer `hint` (H2/H3) still partial. + +**OMIT or MARK "planned":** multi-line input (I1), readline shortcuts (I1b), +in-flight cancellation / query timeout (I5/B3), `seed` (SD1), `m:n` (C4), +one-step modify relationship (C3a), `show tables`/`relationships`/`indexes` +(V5), ER-diagram view/export (V1/V3), session-log + Markdown export (V4). + +**Mine verbatim for docs:** `en-US.yaml` `help.app.*`, `help.ddl.*`, +`help.data.*`, `help.types_reference`, `parse.usage.*` (one-line syntax +templates), `hint.*` — keeps docs and in-app help consistent. + +## Phases + +### A — Scaffold +`pnpm create astro@latest` (Starlight template) in `website/`; `astro add +tailwind` (Tailwind v4 via `@tailwindcss/vite`); add +`@astrojs/starlight-tailwind`. Confirm `pnpm dev` serves and `pnpm build` +emits a static `dist/`. Echo build steps for traceability. + +### B — Landing page +Custom `src/pages/index.astro` (Starlight owns `/docs/*`). Hero + value prop +("learn relational databases by doing"), feature highlights from the +inventory, an embedded demo cast above the fold. Use the `frontend-design` +skill to avoid generic AI aesthetics; honour NFR-4/5/7 (distinctive design, +meaningful colour, light/dark). + +### C — asciinema recording workflow +Record real `rdbms-playground` sessions to `public/casts/*.cast` using a +**scripted-input driver** (e.g. `asciinema-automation`/autocast, or an +expect/doitlive script) for paced, re-recordable demos. Record at a fixed +sensible cols×rows; provide light + dark player themes. `Cast.astro` wraps +`asciinema-player` as a `client:visible` island; the same component embeds +casts inline in docs. Document the recipe in `website/README.md`. +(`asciinema` 2.4.0 is installed.) + +### D — Documentation (the bulk) +Starlight sidebar, scoped from the inventory; built in priority order: +- **Getting started** — install (prebuilt binaries + package managers), + first project, simple vs. advanced mode. +- **Concepts** — projects & storage; undo, history & replay. +- **Simple-mode command reference** — full surface; syntax conventions; + simple-command → SQL teaching echo. +- **Advanced (SQL) mode** — full SQL DDL/DML/SELECT surface. +- **Types**, **Relationships**, **Constraints**, **Indexes**, **Query plans + / EXPLAIN**. +- **Working with the editor** — completion, highlighting, validity + indicator, in-line editing. +- **Errors explained** — the friendly error layer. +- **Export / import & sharing** (E2 recipes), **clipboard**. + +Build order: Tier 1 simple-mode reference + types + constraints + input +modes + mined help/usage strings → Tier 2 advanced SQL + relationships + +project lifecycle + undo/history → Tier 3 teaching echo + EXPLAIN + errors + +completion/highlighting → Tier 4 clipboard + hints + editing. + +Conventions live in the **living style guide** `website/STYLE.md` (binding +rules from ADR-0042 §7 — no engine name, **no "DSL"**, "planned" callouts — +plus finer conventions and an open-decisions log for depth/splitting/example +dataset/etc. as they settle). Sources to mine: `src/dsl/command.rs`, +`src/dsl/grammar/*`, the REGISTRY, `en-US.yaml`, `docs/adr/*`, +`docs/simple-mode-limitations.md`. + +### E — Hosting & portability +Keep the default static build (no adapter); `dist/` deploys to Vercel or any +static host. `website/README.md` notes the Vercel preset (root dir +`website/`) and the one-line `@astrojs/vercel` switch if SSR is ever needed. + +## Demo seam (WASM hook) + +`Demo.astro` exposes a stable contract (`{ src, title, height, autoplay }`). +At launch it renders `Cast.astro`; later a `Playground.astro` WASM island +swaps in behind the same props on the landing page and in docs, with zero +call-site changes. Boundary details are in ADR-0042 §3. + +## Verification + +- `pnpm dev` renders landing + docs; `pnpm build` emits a clean static + `dist/` with no errors/warnings. +- Landing shows at least one playing `.cast`; the same component renders a + cast inline in a docs page (proves reuse). +- Starlight link-check passes (broken internal links fail the build). +- Docs grep clean of forbidden terms: **no "DSL"**, no engine name. +- A `dist/` static deploy works on Vercel (manual import) — confirms + portability. (No CI gate yet, per ADR-0042 §4.) + +## Notes / recommendations (non-blocking) + +- **Doc drift:** consider generating the command reference from source (the + `help` REGISTRY / `en-US.yaml`) rather than hand-writing all of it. +- **Accessibility/SEO:** pair each hero `.cast` with a text transcript or the + equivalent docs snippet. +- **Branding/domain & analytics** unspecified — assume none until decided; + no third-party trackers without consent. +- Tailwind v4 + Starlight have occasional theme-token friction; the + `@astrojs/starlight-tailwind` plugin is the supported bridge. +- Starlight ships local search (Pagefind) by default. +- No `README.md` exists at the repo root yet — wanted for the destination + repo; out of this plan's core scope but flagged. diff --git a/website/STYLE.md b/website/STYLE.md new file mode 100644 index 0000000..8d3ee7a --- /dev/null +++ b/website/STYLE.md @@ -0,0 +1,100 @@ +# Documentation style guide (living) + +This is the **living** home for documentation authoring conventions for the +RDBMS Playground website. It grows as we write. + +- **Binding rules** come from + [ADR-0042 §7](../docs/adr/0042-public-website-and-documentation-site.md); + this guide must not contradict them. If a convention is significant, + durable, or contested, it is decided in an **ADR** (new or amended), and + this guide references it. Finer, settled conventions live here directly. +- **Open decisions** (not yet settled) are tracked at the bottom so we + decide them deliberately rather than re-deciding per page. When one + settles, move it up into the body (and to an ADR if it's significant). + +Status tags used below: **[DECIDED]** (binding or settled) · +**[OPEN]** (to be decided — see the log). + +--- + +## Terminology & wording [DECIDED — ADR-0042 §7] + +- **No "DSL".** It is internal jargon. Use **simple mode** (the playground's + keyword command language) and **advanced mode** (SQL). +- **No engine name.** Never name SQLite / STRICT / rusqlite / PRAGMA in + user-facing copy. Say **"the database"** or **"the engine"**. (Continues + the user-facing posture of ADR-0002.) +- Preferred terms (extend as we go): "command", "project", "table", + "column", "relationship" (the user-facing word for a declared foreign-key + link), "constraint", "index". +- Add new banned/preferred terms here as they come up, with a one-line + reason. + +## Voice & tone [DECIDED, refine as needed] + +- **Teaching-first.** Pedagogy wins ties (CLAUDE.md). Explain the *why*, not + just the *how*; the audience spans beginners through learners ready for + raw SQL. +- Second person ("you"), present tense. Imperative mood for step + instructions ("Create a table…"). +- Prefer short sentences and concrete examples over abstract prose. + +## "Planned / not yet available" callouts [DECIDED — ADR-0042 §7] + +Any capability that is not yet fully implemented is **omitted** or carries a +clear **"planned / not yet available"** callout — never presented as +shipped. Use a Starlight aside (`:::caution` or a custom badge). **[OPEN]**: +exact component + wording (see log). + +## Examples & code [OPEN] + +Direction (to confirm in the log): +- A single **standard example schema/dataset** reused across pages so + readers build familiarity (candidate: a small, recognisable domain). +- Where both modes apply, show the **simple-mode** form and its + **advanced-mode (SQL)** equivalent — the in-app teaching echo already + pairs these, so docs can mirror it. +- Code blocks for input/output; reserve casts for motion/flow (see below). + +## asciinema casts [DECIDED, details OPEN] + +- Casts show *flow/motion*; static code blocks show *exact input/output*. + Prefer a code block when a still example suffices. +- Pair a hero/landing cast with a text transcript or the equivalent docs + snippet (accessibility + SEO). +- Recorded via a scripted-input driver for paced, re-recordable sessions + (ADR-0042 §2; recipe in `README.md`). **[OPEN]**: cast file naming, + fixed terminal size, light/dark theme handling. + +## Formatting [DECIDED, refine] + +- Starlight asides for notes/tips/cautions; tables for reference matrices + (types, constraints, referential actions). +- Keyboard keys rendered consistently (e.g. Ctrl+Z). +- Cross-link related pages; never expose ADR numbers or internal jargon to + the reader (ADRs are for us, not the docs audience). + +--- + +## Open decisions log + +Decide these as we write; record the outcome (and escalate to an ADR if +significant). + +1. **Depth / organising spine.** Adopt **Diátaxis** (tutorial / how-to / + reference / explanation) as the structure, or a lighter + getting-started + reference + concepts split? Affects the whole sidebar. +2. **Page granularity & splitting.** One page per command, per + command-family, or per task? When does a page split? +3. **Standard example schema/dataset.** What domain + tables do all examples + share? +4. **Simple-vs-advanced pairing.** Always show both forms, or only where + instructive? How to present the pairing visually. +5. **"Planned" callout component & wording.** Exact Starlight component and + standard sentence. +6. **Reference generation vs hand-writing.** Generate the command reference + from source (the `help` REGISTRY / `en-US.yaml`) to avoid drift, or + author by hand? (Flagged in the plan's notes.) +7. **Versioning.** Do docs need version selectors at/after v1, or is + single-version fine for launch? +8. **SEO/meta conventions.** Title/description patterns, Open Graph.