From 39e97ac3f953c93181bc83642bd635eb6ebc37be Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Wed, 10 Jun 2026 10:41:45 +0000 Subject: [PATCH] docs: website-branch session handoff (website-1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit First handoff for the website work, on a branch-scoped name sequence (…-website-handoff-N.md) to avoid colliding with main's handoff-NN files. Captures stack/layout, the five-section structure, binding conventions (no DSL / no engine name / fence + prompt + copy rules), the canonical library schema, a verified-syntax cheat-sheet, the dev-server IPv4 gotcha, next-work priorities (fill the 6 Reference stubs, iterate guides, Phase B landing, deferred casts), and process pins. --- docs/handoff/20260610-website-handoff-1.md | 181 +++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/handoff/20260610-website-handoff-1.md diff --git a/docs/handoff/20260610-website-handoff-1.md b/docs/handoff/20260610-website-handoff-1.md new file mode 100644 index 0000000..c82e74d --- /dev/null +++ b/docs/handoff/20260610-website-handoff-1.md @@ -0,0 +1,181 @@ +# 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 `. + +**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 with pk [()[, ...]]` (bare = + default `id`); `add column [to] [table] : ()`; + `rename column [in] [table] : to `; `change column … () + [--force-conversion|--dont-convert]`; `drop column [from] [table] : + [--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 ] from

. to . + [on delete ] [on update ] [--create-fk]`; + compound: `from

.(a, b) to .(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 [where …] [limit n]`, `show table `, `show + tables|relationships|indexes`, `show relationship|index `. +- `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.