docs: website-branch session handoff (website-1)
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.
This commit is contained in:
claude@clouddev1
@@ -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 <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.
|
||||||
Reference in New Issue
Block a user