rdbms-playground/docs/website/plans/20260604-website-implementation-plan.md

Plan: public website and documentation site

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

Decisions for this work are recorded in ADR-website-001: 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.