feat: add "Using the playground" section + Reference skeleton

Restructure the docs into five top-level sections, splitting the
application you drive from the database language you build with.

- New "Using the playground" section: command-line options; the assistive
  editor (completion, highlighting, [ERR]/[WRN] indicator, hints, in-line
  editing); the output pane (scrolling); projects (save/load/new/rebuild);
  undo/redo & history; export & import; clipboard; getting help. Grounded in
  the in-app help/usage and ADR-0003/0022/0027.
- Reference: seed the remaining topic pages (Columns, Relationships,
  Indexes, Constraints, Inserting & editing data, Querying & inspecting)
  with real syntax synopses; worked examples to follow.
- Surface the assistive editor on the landing page and in Getting started;
  restore cross-links now that targets exist.

Plan + STYLE updated to the five-section structure. 24 pages, build green,
links resolve, content clean; planned features carry "planned" callouts.

docs/plans/20260604-adr-0044-website.md

@@ -122,19 +122,31 @@ casts inline in docs. Document the recipe in `website/README.md`.
 (`asciinema` 2.4.0 is installed.)
 
 ### D — Documentation (the bulk)
-Starlight sidebar, scoped from the inventory; built in priority order:
+**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.
+  first project, simple vs. advanced mode, the example library.
-- **Concepts** — projects & storage; undo, history & replay.
+- **Using the playground** — command-line options; the assistive editor
-- **Simple-mode command reference** — full surface; syntax conventions;
+  (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.
-- **Advanced (SQL) mode** — full SQL DDL/DML/SELECT surface.
+- **Concepts** — the *why*: projects & storage model, the derived database,
-- **Types**, **Relationships**, **Constraints**, **Indexes**, **Query plans
+  how undo works.
-  / EXPLAIN**.
+
-- **Working with the editor** — completion, highlighting, validity
+**Surface the assistive editor prominently** — it is a differentiator and
-  indicator, in-line editing.
+most helps beginners: a landing-page card + a Getting-started mention, both
-- **Errors explained** — the friendly error layer.
+linking into *Using the playground*. It is prime asciinema-cast material
-- **Export / import & sharing** (E2 recipes), **clipboard**.
+(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 +

website/STYLE.md

@@ -41,11 +41,17 @@ Status tags used below: **[DECIDED]** (binding or settled) ·
 
 ## Structure  [DECIDED]
 
-Pragmatic, Diátaxis-influenced split (four top-level sidebar sections,
+Pragmatic, Diátaxis-influenced split (five top-level sidebar sections,
 autogenerated per directory under `src/content/docs/`):
 
 - **Getting started** — install, first project, simple vs. advanced, the
   example database.
+- **Using the playground** — *the application you drive*, kept distinct from
+  the database-language Reference: command-line options, the assistive editor
+  (completion / highlighting / `[ERR]`/`[WRN]` indicator / hints / in-line
+  editing), the output pane (scrolling), projects (save/load/new/rebuild),
+  undo & history, export & import, clipboard, getting help. (ADR-0003's
+  "app-level commands" + ADR-0022/0027 typing assistance + the CLI.)
 - **Guides** — task-oriented how-tos. *These are the most important didactic
   content and will be iterated for teaching quality before publication.*
 - **Reference** — the exhaustive command/SQL/type surface. **Page

website/astro.config.mjs

@@ -33,6 +33,7 @@ export default defineConfig({
 			// frontmatter.
 			sidebar: [
 				{ label: 'Getting started', items: [{ autogenerate: { directory: 'getting-started' } }] },
+				{ label: 'Using the playground', items: [{ autogenerate: { directory: 'using-the-playground' } }] },
 				{ label: 'Guides', items: [{ autogenerate: { directory: 'guides' } }] },
 				{ label: 'Reference', items: [{ autogenerate: { directory: 'reference' } }] },
 				{ label: 'Concepts', items: [{ autogenerate: { directory: 'concepts' } }] },

website/src/content/docs/concepts/projects-and-storage.md

@@ -69,5 +69,5 @@ export
 
 The zip contains the readable files (`project.yaml` and `data/`) but **not**
 the derived database or your private `history.log`. The recipient opens it
-and the playground rebuilds the database for them. Exporting and
+and the playground rebuilds the database for them. [Exporting and
-importing has its own reference page.
+importing](/using-the-playground/export-and-import/) has its own page.

website/src/content/docs/getting-started/first-project.md

@@ -11,7 +11,9 @@ playground starts.
 
 When you launch `rdbms-playground` with no arguments, it opens a fresh
 temporary project for you. Type commands into the input field at the bottom
-and press <kbd>Enter</kbd> to run them.
+and press <kbd>Enter</kbd> to run them. As you type, the field completes
+commands with <kbd>Tab</kbd> and flags mistakes before you run — see
+[The assistive editor](/using-the-playground/the-assistive-editor/).
 
 ## Create a table
 
@@ -57,4 +59,5 @@ That is the whole loop: **create → add columns → insert → show**. From her
 
 - Build the full example database in [Build the library](/guides/build-the-library/).
 - Learn how [simple and advanced modes](/getting-started/modes/) differ.
+- Let the editor help you: [completion, highlighting, and live error flags](/using-the-playground/the-assistive-editor/).
 - Look up any command in the [Reference](/reference/types/).

website/src/content/docs/index.mdx

@@ -38,6 +38,10 @@ SQL.
 		Ask the playground to explain any query and it renders the database's
 		plan as an annotated tree — so indexes and scans stop being a mystery.
 	</Card>
+	<Card title="Helpful as you type" icon="pencil">
+		The input field completes commands with <kbd>Tab</kbd>, highlights
+		syntax, flags mistakes before you run them, and hints what comes next.
+	</Card>
 </CardGrid>
 
 ## Start here

website/src/content/docs/reference/columns.md

@@ -0,0 +1,29 @@
+---
+title: Columns
+description: Add, remove, rename, and change the type of a table's columns.
+sidebar:
+  order: 3
+---
+
+:::note[In progress]
+The syntax below is complete and accurate; worked examples on the library
+schema are being added.
+:::
+
+After a table exists, you add and change its columns. In simple mode:
+
+```rdbms-syntax
+add column [to] [table] <Table>: <Name> (<Type>)
+rename column [in] [table] <Table>: <Old> to <New>
+change column [in] [table] <Table>: <Name> (<Type>) [--force-conversion | --dont-convert]
+drop column [from] [table] <Table>: <Name> [--cascade]
+```
+
+Changing a column to `serial` or `shortid` fills existing rows with generated
+values. A primary-key column, or one involved in a relationship, is refused
+until you remove the relationship first.
+
+In advanced mode the same operations are `ALTER TABLE … ADD/DROP/RENAME
+COLUMN` and `ALTER TABLE … ALTER COLUMN … TYPE`.
+
+See also [Types](/reference/types/) and [Constraints](/reference/constraints/).

website/src/content/docs/reference/constraints.md

@@ -0,0 +1,30 @@
+---
+title: Constraints
+description: NOT NULL, UNIQUE, DEFAULT, and CHECK constraints on columns.
+sidebar:
+  order: 6
+---
+
+:::note[In progress]
+The syntax below is complete and accurate; worked examples on the library
+schema are being added.
+:::
+
+Constraints keep your data valid. Declare them in the column spec at
+`create table` / `add column` time, or change them on an existing column:
+
+```rdbms-syntax
+add constraint not null to <Table>.<col>
+add constraint unique to <Table>.<col>
+add constraint default <value> to <Table>.<col>
+add constraint check (<expr>) to <Table>.<col>
+drop constraint (not null | unique | default | check) from <Table>.<col>
+```
+
+Adding a constraint to a column that already has rows is checked first — if
+existing data would violate it, the change is refused and the offending rows
+are shown.
+
+In advanced mode these are the standard column- and table-level constraints
+in `CREATE TABLE` / `ALTER TABLE`. The primary key is fixed at creation (see
+[Tables](/reference/tables/)).

website/src/content/docs/reference/indexes.md

@@ -0,0 +1,25 @@
+---
+title: Indexes
+description: Create and drop indexes to speed up lookups.
+sidebar:
+  order: 5
+---
+
+:::note[In progress]
+The syntax below is complete and accurate; worked examples on the library
+schema are being added.
+:::
+
+An index speeds up lookups on one or more columns. In simple mode:
+
+```rdbms-syntax
+add index [as <Name>] on <Table> (<col>[, ...])
+drop index <Name>
+drop index on <Table> (<col>[, ...])
+```
+
+In advanced mode, `CREATE [UNIQUE] INDEX … ON <Table> (…)` and `DROP INDEX`.
+Unique indexes are available on the advanced surface.
+
+To see how an index changes the way a query runs, use
+[Query plans](/reference/querying-and-inspecting/).

website/src/content/docs/reference/inserting-and-editing-data.md

@@ -0,0 +1,26 @@
+---
+title: Inserting & editing data
+description: Add, change, and remove rows.
+sidebar:
+  order: 7
+---
+
+:::note[In progress]
+The syntax below is complete and accurate; worked examples on the library
+schema are being added.
+:::
+
+```rdbms-syntax
+insert into <Table> [(<col>[, ...])] [values] (<value>[, ...])
+update <Table> set <col>=<value>[, ...] (where <col>=<value> | --all-rows)
+delete from <Table> (where <col>=<value> | --all-rows)
+```
+
+`update` and `delete` require a `where` clause; to act on every row you must
+opt in explicitly with `--all-rows`. Auto-generated columns (`serial`,
+`shortid`) fill themselves in, so you can leave them out of an `insert`. After
+a write, the affected rows are shown automatically.
+
+`where` accepts more than simple equality — `and` / `or` / `not`,
+comparisons, `like`, `is null`, `in`, and `between`. See
+[Querying & inspecting](/reference/querying-and-inspecting/).

website/src/content/docs/reference/querying-and-inspecting.md

@@ -0,0 +1,43 @@
+---
+title: Querying & inspecting
+description: View rows and schema, run SQL queries, and explain how a query runs.
+sidebar:
+  order: 8
+---
+
+:::note[In progress]
+The syntax below is complete and accurate; worked examples on the library
+schema are being added.
+:::
+
+## Viewing rows and schema (simple mode)
+
+```rdbms-syntax
+show data <Table> [where <expr>] [limit <n>]
+show table <Table>
+show tables
+show relationships
+show indexes
+show relationship <Name>
+show index <Name>
+```
+
+## Querying (advanced mode)
+
+Advanced mode runs full SQL `select`, including joins, `group by`, `order
+by`, set operations, and `with` (CTEs):
+
+```rdbms-syntax
+select (* | <expr> [as <alias>][, ...]) from <Table> [where <expr>] [order by <expr> [asc|desc][, ...]] [limit <n>]
+```
+
+## Query plans
+
+Prefix a query with `explain` to see how the database would run it, rendered
+as an annotated tree — without running it (so it is safe even over `update`
+or `delete`):
+
+```rdbms-syntax
+explain show data <Table> [where <expr>]
+explain <select | with | insert | update | delete …>   (advanced mode)
+```

website/src/content/docs/reference/relationships.md

@@ -0,0 +1,38 @@
+---
+title: Relationships
+description: Declare and remove foreign-key relationships between tables.
+sidebar:
+  order: 4
+---
+
+:::note[In progress]
+The syntax below is complete and accurate; worked examples on the library
+schema are being added.
+:::
+
+A relationship is a foreign key from a child table to a parent's primary
+key. In simple mode:
+
+```rdbms-syntax
+add 1:n relationship [as <Name>]
+  from <Parent>.<col> to <Child>.<col>
+  [on delete <action>] [on update <action>]
+  [--create-fk]
+drop relationship <Name>
+```
+
+`<action>` is `cascade`, `set null`, or `restrict`. `--create-fk` adds the
+child column if it doesn't exist yet.
+
+**Compound keys.** To reference a parent's compound primary key, list the
+columns on each side, matched in order:
+
+```rdbms-syntax
+add 1:n relationship from <Parent>.(<a>, <b>) to <Child>.(<x>, <y>)
+```
+
+In advanced mode, relationships are declared with `FOREIGN KEY … REFERENCES`
+in `CREATE TABLE` or `ALTER TABLE`.
+
+See also [Indexes](/reference/indexes/) and [Types](/reference/types/) (why a
+foreign-key column's type can differ from the key it references).

website/src/content/docs/reference/tables.md

@@ -6,8 +6,8 @@ sidebar:
 ---
 
 A table is the core building block. This page covers creating and removing
-tables; changing a table's columns after it exists is covered under Columns
+tables; changing a table's columns after it exists is covered in
-in the Reference.
+[Columns](/reference/columns/).
 
 ## Create a table (simple mode)
 
@@ -62,7 +62,8 @@ create table authors (
 ```
 
 The advanced form also accepts table-level constraints and inline foreign
-keys — see the Constraints and Relationships references.
+keys — see [Constraints](/reference/constraints/) and
+[Relationships](/reference/relationships/).
 
 **Syntax**
 

website/src/content/docs/reference/types.md

@@ -59,8 +59,8 @@ filled with freshly generated values in the same step.
 A foreign key stores a plain looked-up value, not a new generated one. So a
 column that references a `serial` primary key is itself an `int`, and one
 that references a `shortid` is a `text`. The playground handles this for you
-when you declare a relationship; it is worth knowing why the child column's
+when you declare a [relationship](/reference/relationships/); it is worth
-type differs from the parent key's.
+knowing why the child column's type differs from the parent key's.
 
 ## Type names in advanced mode
 

website/src/content/docs/using-the-playground/command-line-options.md

@@ -0,0 +1,44 @@
+---
+title: Command-line options
+description: How to start the playground, open a project, and the flags you can pass.
+sidebar:
+  order: 1
+---
+
+Start the playground with no arguments and it opens a fresh, automatically
+named temporary project so you can begin straight away:
+
+```sh
+rdbms-playground
+```
+
+To open an existing project, give its path:
+
+```sh
+rdbms-playground path/to/project
+```
+
+## Options
+
+| Option | Effect |
+|---|---|
+| `--resume` | Reopen the most recently used project. Errors if there is none; cannot be combined with a project path. |
+| `--data-dir <PATH>` | Use `PATH` as the data root instead of the OS-standard location for this run. |
+| `--mode <simple\|advanced>` | Start in this input mode, overriding the project's stored mode (precedence: `--mode` > stored > simple). |
+| `--theme <light\|dark>` | Force a theme instead of auto-detecting from the terminal. |
+| `--no-undo` | Disable the undo machinery for this run — no snapshot is taken before each change (see [Undo, redo & history](/using-the-playground/undo-and-history/)). |
+| `--log-file <PATH>` | Write diagnostic logging to `PATH`. |
+| `-h`, `--help` | Print the usage banner and exit. |
+
+## Examples
+
+```sh
+# Reopen wherever you left off, in advanced mode
+rdbms-playground --resume --mode advanced
+
+# Keep a course's projects in one folder
+rdbms-playground --data-dir ~/db-course
+```
+
+Where projects are stored, and what a project contains, is covered in
+[Projects and storage](/concepts/projects-and-storage/).

website/src/content/docs/using-the-playground/copy-to-clipboard.md

@@ -0,0 +1,22 @@
+---
+title: Copy to clipboard
+description: Copy the output panel to your system clipboard.
+sidebar:
+  order: 7
+---
+
+Copy what's in the output pane to your system clipboard — handy for pasting a
+result or an error into a question or a note.
+
+```rdbms
+copy
+```
+Copy the whole output pane. (`copy all` does the same.)
+
+```rdbms
+copy last
+```
+Copy just the most recent command's output.
+
+The text is copied exactly as shown in the pane. Copying works over SSH as
+well as locally.

website/src/content/docs/using-the-playground/export-and-import.md

@@ -0,0 +1,42 @@
+---
+title: Export & import
+description: Package a project to share it, and unpack one you've received.
+sidebar:
+  order: 6
+---
+
+## Export
+
+```rdbms
+export
+```
+
+Packages the project as a single zip. The zip contains the readable files
+(`project.yaml` and `data/`) but **not** the working database (the recipient
+rebuilds it on open) or your private `history.log`. Pass a path to choose
+where it goes:
+
+```rdbms
+export path/to/exercise.zip
+```
+
+## Import
+
+```rdbms
+import path/to/exercise.zip
+```
+
+Unpacks a zip into a new project and switches to it; the database is rebuilt
+from the readable files. Add `as <name>` to choose the target name:
+
+```rdbms
+import path/to/exercise.zip as my-copy
+```
+
+## Sharing recipes
+
+Because a project is plain text plus CSV, sharing it is easy:
+
+- **Git** — each project includes a `.gitignore` that excludes the working
+  database, so a project commits cleanly and diffs sensibly.
+- **Email / file transfer** — send the exported zip; the recipient imports it.

website/src/content/docs/using-the-playground/getting-help.md

@@ -0,0 +1,33 @@
+---
+title: Getting help
+description: Built-in help — a command list, per-command detail, and the type reference.
+sidebar:
+  order: 8
+---
+
+The playground has help built in, so you rarely need to leave it.
+
+```rdbms
+help
+```
+Lists the supported commands, with the grammar reference and the type list.
+
+```rdbms
+help insert
+```
+`help <command>` shows detail for one command (every command sharing that
+entry word). Try `help create`, `help add`, `help show`, and so on.
+
+```rdbms
+help types
+```
+Shows the type reference on its own.
+
+Outside the app, run `rdbms-playground --help` for the
+[command-line options](/using-the-playground/command-line-options/).
+
+:::note[Planned]
+A `hint` command for contextual help on the current input or the last error
+is planned and not yet available — but the input already shows hints as you
+type (see [The assistive editor](/using-the-playground/the-assistive-editor/)).
+:::

website/src/content/docs/using-the-playground/projects.md

@@ -0,0 +1,40 @@
+---
+title: Projects — save, load, new, rebuild
+description: The app-level commands for managing projects.
+sidebar:
+  order: 4
+---
+
+A project is where your work lives. The playground saves it continuously as
+you go (see [Projects and storage](/concepts/projects-and-storage/) for the
+model), so these commands are about *switching* and *managing* projects, not
+a manual "save your changes" step.
+
+```rdbms
+save
+```
+Give the current temporary project a permanent name. (On a project that is
+already named, `save` reports that it is already auto-saved — use `save as`.)
+
+```rdbms
+save as
+```
+Copy the current project to a new name or location and switch to it.
+
+```rdbms
+new
+```
+Close the current project and start a fresh temporary one.
+
+```rdbms
+load
+```
+Open the project picker — a list of your projects, newest first, with
+`[TEMP]` markers; you can also browse to a path.
+
+```rdbms
+rebuild
+```
+Rebuild the working database from the readable files (`project.yaml` +
+`data/`), after a confirmation. Useful if the database is ever missing or out
+of date.

website/src/content/docs/using-the-playground/the-assistive-editor.md

@@ -0,0 +1,54 @@
+---
+title: The assistive editor
+description: The input field helps as you type — completion, highlighting, a validity indicator, and hints.
+sidebar:
+  order: 2
+---
+
+You type commands into the input field at the bottom of the screen, and it
+helps you as you go. None of this gets in your way — it is all advisory.
+
+## Completion
+
+Press <kbd>Tab</kbd> to complete what you are typing. Completion knows about
+the commands, the keywords for the current position, your **table, column,
+index, and relationship names**, and — in advanced mode — common SQL
+function names. It is the fastest way to discover what is available without
+leaving the keyboard.
+
+## Syntax highlighting
+
+As you type, the input is coloured live: keywords, identifiers, column
+**types**, and SQL function names each get their own colour, so a command's
+shape is visible before you run it.
+
+## The validity indicator
+
+A small marker appears at the right-hand edge of the input line and tells
+you, *before you submit*, whether the command would run:
+
+- **`[ERR]`** — the command will fail as written (for example, an unknown
+  table or column, or a value that doesn't match a column's type).
+- **`[WRN]`** — the command will run, but something looks suspect (for
+  example, comparing a number column with a text pattern).
+
+It is purely advisory — it never blocks you from submitting.
+
+## Hints
+
+A hint line below the input offers contextual guidance — the next token that
+would fit, the type expected at the current position, and help with the most
+recent error. When the input is empty it reminds you that <kbd>Tab</kbd>
+lists options and `help` lists commands.
+
+## Editing the line
+
+Move and edit within the line with the usual keys: <kbd>←</kbd>/<kbd>→</kbd>
+by character, <kbd>Home</kbd>/<kbd>End</kbd> to the ends, and
+<kbd>Delete</kbd>/<kbd>Backspace</kbd> to remove characters. Your
+project-scoped command history is available with <kbd>↑</kbd>/<kbd>↓</kbd>.
+
+:::note[Planned]
+Multi-line entry and extra readline-style shortcuts (Ctrl-A/E/W/K/U) are
+planned and not yet available.
+:::

website/src/content/docs/using-the-playground/the-output-pane.md

@@ -0,0 +1,22 @@
+---
+title: The output pane
+description: Where results appear, and how to scroll back through them.
+sidebar:
+  order: 3
+---
+
+Results appear in the output pane: the structure of a table after you change
+it, the rows from `show data` and after writes (as aligned, box-drawn
+tables), query plans, and command outcomes marked with a ✓ or ✗.
+
+## Scrolling
+
+Use <kbd>PageUp</kbd> and <kbd>PageDown</kbd> to scroll back through earlier
+output. New output snaps the view back to the most recent entry, so you never
+lose your place when you run something.
+
+:::note[Planned]
+A fuller session journal — a scrollable, richly rendered log of the whole
+session that you can save as Markdown — and multiple result tabs are planned
+and not yet available.
+:::

website/src/content/docs/using-the-playground/undo-and-history.md

@@ -0,0 +1,39 @@
+---
+title: Undo, redo & history
+description: Step back from any change, and replay a recorded session.
+sidebar:
+  order: 5
+---
+
+Every change you make is safe to undo — the playground snapshots the whole
+project before each one.
+
+## Undo and redo
+
+```rdbms
+undo
+```
+
+```rdbms
+redo
+```
+
+Each asks you to confirm, naming the exact command being undone or
+re-applied. Redo is available until you make a new change. (How snapshots
+work is explained in [Concepts](/concepts/projects-and-storage/).)
+
+Starting with `--no-undo` turns this off for the session — no snapshot is
+taken before each change, and `undo`/`redo` report that undo is off.
+
+## History and replay
+
+Every command you run is recorded, in order, in the project's `history.log`.
+You can re-run a saved sequence of commands from a file:
+
+```rdbms
+replay path/to/commands
+```
+
+Replay runs each non-blank, non-`#`-comment line, stopping at the first error
+(relative paths resolve under the project directory). It re-applies the
+schema- and data-changing commands and skips app-level ones.