# 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

```sh
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 <zip> [as <t>] / undo / redo / replay <path> / mode / help
  [<command>] / 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.