# Plan: public website and documentation site

**Date:** 2026-06-04 · **Status:** ready to build

Decisions for this work are recorded in
[ADR-website-001](../adr/20260604-adr-website-001.md): Astro 6 +
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–59`, `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 (handoff-59 found those ~46% mis-marked; they now use a `[/]`
"partial" legend — trust the code, not the marker). Refreshed **2026-06-09
after merging `main`**, which added the show-list/detail, `help <command>`,
and compound-PK FK surface (see the dedicated bullet below). Test state:
**2193 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).
- **Added by the `main` merge (2026-06-09):** schema-inspection commands
  `show tables` / `show relationships` / `show indexes` and the singular
  `show relationship <name>` / `show index <name>` detail views (V5/V5a);
  `help [<command>]` per-command detail + `help types` + general reference
  (H3); **compound-primary-key foreign-key references** — DSL
  `from <P>.(a, b) to <C>.(x, y)` and SQL `FOREIGN KEY (a, b) REFERENCES
  P(x, y)` (single-column form unchanged) (ADR-0043, T3); friendlier
  parse-error near-miss messaging (H1a, ADR-0042). These need coverage: a
  schema-inspection page (the `show` family) and compound-FK examples on the
  Relationships page.

**DOCUMENT WITH CAVEAT:** `add unique index` is advanced-only; simple-mode
table rename is intentionally absent (rename is `ALTER TABLE … RENAME TO`);
`hint` (H2) is still partial; a compound-FK *violation* message names only
the first column pair (enforcement is correct — a messaging-only residual).

**OMIT or MARK "planned":** multi-line input (I1), readline shortcuts (I1b),
in-flight cancellation / query timeout (I5/B3), `seed` (SD1), `m:n`
convenience (C4), one-step modify relationship (C3a), relationship line-art
(V1), ER-diagram export (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)
**Five** top-level sidebar sections (autogenerated per directory). The key
split: *Using the playground* = the application you drive; *Reference* = the
database language you build with.
- **Getting started** — install (prebuilt binaries + package managers),
  first project, simple vs. advanced mode, the example library.
- **Using the playground** — command-line options; the assistive editor
  (completion, syntax highlighting, the `[ERR]`/`[WRN]` validity indicator,
  hints, in-line editing); the output pane (PageUp/PageDown scrolling — the
  fuller V4 session-log / Markdown export is *planned*, mark it); projects
  (save / load / new / rebuild); undo, redo & history (+ replay); export &
  import (E2 recipes); copy to clipboard; getting help (`help` /
  `help <command>` / `hint`). (ADR-0003 "app-level commands" + ADR-0022/0027
  typing assistance + the CLI.)
- **Guides** — task walkthroughs.
- **Reference** — the database language: Tables, Columns, Relationships,
  Indexes, Constraints, Inserting & editing data, Querying & inspecting
  (`show` / `select`), Types, Query plans (EXPLAIN), Errors explained, the
  simple-command → SQL teaching echo.
- **Concepts** — the *why*: projects & storage model, the derived database,
  how undo works.

**Surface the assistive editor prominently** — it is a differentiator and
most helps beginners: a landing-page card + a Getting-started mention, both
linking into *Using the playground*. It is prime asciinema-cast material
(completion / validity indicator are motion a still code block can't show).

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-website-001 §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-website-001 §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-website-001 §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.