rdbms-playground/docs/handoff/20260610-website-handoff-1.md

Website-branch handoff — 2026-06-10 (website-1)

First handoff for the website work. This is a separate sequence from main's YYYYMMDD-handoff-NN.md files — branch-scoped name on purpose, so the two don't collide. Continue numbering these …-website-handoff-N.md.

State

• Branch: website. HEAD 936d925. Not pushed (push is the user's step). Working tree clean.
• The website lives in website/ (monorepo; the playground crate is at the repo root). Decisions: ADR-0044 (docs/adr/0044-public-website-and-documentation-site.md). Implementation plan: docs/plans/20260604-adr-0044-website.md. Living style guide: website/STYLE.md (read this first — it has the binding conventions and an open-decisions log).

Stack & layout

• Astro 6 + Starlight + Tailwind v4, all under website/.
• website/astro.config.mjs — Starlight config (title, 5-section sidebar, Expressive Code langs, server.host: '127.0.0.1').
• website/src/grammars/rdbms.mjs — custom Shiki grammar, two language ids: rdbms (real commands) and rdbms-syntax (abstract templates).
• website/src/styles/global.css — Starlight↔Tailwind bridge + the > command prompt + copy-button hiding (CSS :has()).
• website/src/content/docs/ — the five sections.

Commands

cd website
pnpm install      # node_modules is gitignored — reinstall on a fresh checkout
pnpm dev          # serves http://127.0.0.1:4321  (see dev-server gotcha below)
pnpm build        # static dist/, 24 pages, Pagefind search index

Dev-server gotcha (already fixed, don't re-break): Astro/Vite's default localhost bind resolves to IPv6 ::1 here, which breaks SSH -L 4321:127.0.0.1:4321 tunnels. server.host: '127.0.0.1' in the config pins IPv4. Tunnel with ssh -L 4321:127.0.0.1:4321 <host>.

Verify after changes: pnpm build clean; then from the repo root grep -rniE '\b(DSL|SQLite|STRICT|rusqlite|PRAGMA)\b' website/src/content/ must be empty; internal links should resolve (build doesn't fail on broken links — no validator installed — so sanity-check by hand or with a small script).

Documentation structure (5 sections, autogenerated per directory)

1. Getting started — install, first-project, modes, example-library. (real)
2. Using the playground — command-line-options, the-assistive-editor, the-output-pane, projects, undo-and-history, export-and-import, copy-to-clipboard, getting-help. (real, grounded) This is "the app you drive", distinct from the database-language Reference.
3. Guides — build-the-library (DRAFT — marked; to be iterated for teaching quality before publication).
4. Reference — types (real), tables (real); columns, relationships, indexes, constraints, inserting-and-editing-data, querying-and-inspecting (STUBS — real syntax synopsis + an "In progress" note; THEY NEED WORKED EXAMPLES — this is the main remaining bulk).
5. Concepts — projects-and-storage (real).

• Landing: index.mdx splash (feature cards incl. the assistive editor + start-here links).

Binding conventions (STYLE.md / ADR-0044 §7)

• No "DSL" in user-facing copy → "simple mode" / "advanced mode".
• No engine name (SQLite/STRICT/rusqlite/PRAGMA) → "the database" / "the engine".
• Code fences: simple-mode commands → ```rdbms (highlighted; gets a decorative copy-safe > prompt via CSS). Abstract syntax templates → ```rdbms-syntax (highlighted, no prompt, no copy button). Advanced SQL → ```sql. Shell → ```sh.
• One command per line in rdbms blocks. A multi-line single statement (advanced CREATE TABLE) goes in ```sql.
• Copy button is hidden on multi-line rdbms blocks and on rdbms-syntax (the app input is single-line — a multi-command paste isn't runnable); kept on single-command rdbms, and all sql/sh.
• Unshipped features → :::caution[Planned] aside; never presented as shipped.
• Ground every page in source — parse.usage.* / help.* in src/friendly/strings/en-US.yaml, src/dsl/command.rs, src/dsl/types.rs, the ADRs. Do not trust requirements.md markers (handoff-59 found ~46% mis-marked; it now uses a [/] partial legend) — verify against code.

Canonical example database (use in every example)

A small library: authors(author_id serial pk, name text, birth_year int) · books(book_id serial pk, title text, author_id int→authors, published int, isbn text unique) · members(member_id serial pk, name text, joined date) · loans(loan_id serial pk, book_id int→books, member_id int→members, loaned_on date, returned_on date). 1:n author→books; m:n books↔members via loans. Simplest examples lead with bare with pk (a default id key); the library build uses named keys (author_id, …) so relationships read clearly.

Verified syntax cheat-sheet (don't re-derive)

• Simple create: create table <T> with pk [<col>(<type>)[, ...]] (bare = default id); add column [to] [table] <T>: <name> (<type>); rename column [in] [table] <T>: <old> to <new>; change column … (<type>) [--force-conversion|--dont-convert]; drop column [from] [table] <T>: <col> [--cascade].
• Advanced create: create table T (id serial primary key, …, col int references parent(col)) (verified against tests/it/sql_create_table.rs).
• Relationship: add 1:n relationship [as <name>] from <P>.<col> to <C>.<col> [on delete <action>] [on update <action>] [--create-fk]; compound: from <P>.(a, b) to <C>.(x, y); drop by name or by endpoints.
• Data: insert into T [(cols)] [values] (vals); update T set … (where … | --all-rows); delete from T (where … | --all-rows).
• Inspect: show data <T> [where …] [limit n], show table <T>, show tables|relationships|indexes, show relationship|index <name>.
• explain <…> (query plan; safe — never executes). Advanced select ….
• 10 types: text int real decimal bool date datetime blob serial shortid; advanced-mode SQL aliases (integer/varchar/timestamp/numeric/…).
• App commands: save / save as / new / load / rebuild / export [path] / import [as ] / undo / redo / replay / mode / help [] / help types / copy [all|last] / quit. (hint and seed are NOT implemented — mark planned/omit.)

Next work (priority order)

1. Fill the 6 Reference stubs with worked examples on the library schema (the remaining bulk). Each has a syntax synopsis + an "In progress" note — expand to full content: worked example(s), both simple + advanced forms where both apply, cross-links. This is the biggest chunk.
2. Iterate the Guides for teaching quality; add guides (model a 1:n / m:n, querying with joins). The user flagged guides as the most important didactic content, to be polished before publication.
3. Phase B — landing polish: use the frontend-design skill; set Starlight site (production URL) once the domain is known (enables sitemap
   • OG/SEO); add a logo + favicon (small Starlight config). Branding palette when the user wants it (staying on Starlight; community themes were surveyed — see ADR-0044 / chat).
4. asciinema casts — DEFERRED until the app is final (ADR-0044 §2). When starting, settle STYLE.md open-decision #9: scripted-input driver (asciinema-automation vs autocast — prove with a throwaway test run), .cast script format + repo location, terminal geometry, light/dark player theme, file naming. The assistive editor is prime cast material (completion / [ERR]/[WRN] indicator are motion a still block can't show) — earmark a cast for it on the landing + the assistive-editor page.
5. Remaining STYLE.md open decisions: versioning (leaning single-version for launch) and SEO/meta (settle with Phase B + the site URL).

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.
• ADR numbering: assigned at merge-to-main (ADR-0000 "Numbering discipline", added this branch). The website ADR is 0044 — renumbered from 0042 on the main merge, because main had independently used 0042 (H1a) and 0043 (compound-FK).
• Issues: Gitea via tea (repo oli/rdbms-playground on git.lazyeval.net); append < /dev/null + timeout 30; never raw API.
• Escalate genuine forks, declare epistemic status, write down the DA pass (/runda) on non-trivial plans.

Commit history on this branch (newest first)

936d925 feat: add "Using the playground" section + Reference skeleton
44390e7 feat: simple-mode code-block highlighting, prompt, and copy rules
995c0ba docs: reconcile website doc inventory with merged main scope
c72c624 chore: bind website dev/preview server to IPv4 loopback (127.0.0.1)
9e774b2 docs: ADR numbering discipline — assign numbers at merge-to-main
40de389 Merge branch 'main' into website (Gitea migration + ADR renumber)
0fcb7b1 docs: website docs structure + first content pages
cea99e8 chore: scaffold website (Astro 6 + Starlight + Tailwind v4)
1fad29c docs: ADR-0042 — public website + documentation site plan   (now ADR-0044)

Review status (what the user has signed off)

Highlighting / > prompt / copy behavior — good. Voice, altitude, terminology — good. Responsive layout (checked in Polypane) — good. Locked decisions: bare with pk leads the simplest examples; copy hidden on multi-command blocks (not per-command copy); the 5-section structure with "Using the playground" near the top; assistive editor surfaced on landing + Getting started. The 6 Reference stubs have not been reviewed for content — only their syntax synopses exist.