From 936d9254c0dcb7e42f6a92a353e979a66670430f Mon Sep 17 00:00:00 2001 From: "claude@clouddev1" Date: Wed, 10 Jun 2026 10:40:07 +0000 Subject: [PATCH] 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 | 34 ++++++++---- website/STYLE.md | 8 ++- website/astro.config.mjs | 1 + .../docs/concepts/projects-and-storage.md | 4 +- .../docs/getting-started/first-project.md | 5 +- website/src/content/docs/index.mdx | 4 ++ website/src/content/docs/reference/columns.md | 29 ++++++++++ .../src/content/docs/reference/constraints.md | 30 +++++++++++ website/src/content/docs/reference/indexes.md | 25 +++++++++ .../reference/inserting-and-editing-data.md | 26 +++++++++ .../docs/reference/querying-and-inspecting.md | 43 +++++++++++++++ .../content/docs/reference/relationships.md | 38 +++++++++++++ website/src/content/docs/reference/tables.md | 7 +-- website/src/content/docs/reference/types.md | 4 +- .../command-line-options.md | 44 +++++++++++++++ .../using-the-playground/copy-to-clipboard.md | 22 ++++++++ .../using-the-playground/export-and-import.md | 42 +++++++++++++++ .../docs/using-the-playground/getting-help.md | 33 ++++++++++++ .../docs/using-the-playground/projects.md | 40 ++++++++++++++ .../the-assistive-editor.md | 54 +++++++++++++++++++ .../using-the-playground/the-output-pane.md | 22 ++++++++ .../using-the-playground/undo-and-history.md | 39 ++++++++++++++ 22 files changed, 534 insertions(+), 20 deletions(-) create mode 100644 website/src/content/docs/reference/columns.md create mode 100644 website/src/content/docs/reference/constraints.md create mode 100644 website/src/content/docs/reference/indexes.md create mode 100644 website/src/content/docs/reference/inserting-and-editing-data.md create mode 100644 website/src/content/docs/reference/querying-and-inspecting.md create mode 100644 website/src/content/docs/reference/relationships.md create mode 100644 website/src/content/docs/using-the-playground/command-line-options.md create mode 100644 website/src/content/docs/using-the-playground/copy-to-clipboard.md create mode 100644 website/src/content/docs/using-the-playground/export-and-import.md create mode 100644 website/src/content/docs/using-the-playground/getting-help.md create mode 100644 website/src/content/docs/using-the-playground/projects.md create mode 100644 website/src/content/docs/using-the-playground/the-assistive-editor.md create mode 100644 website/src/content/docs/using-the-playground/the-output-pane.md create mode 100644 website/src/content/docs/using-the-playground/undo-and-history.md diff --git a/docs/plans/20260604-adr-0044-website.md b/docs/plans/20260604-adr-0044-website.md index e146144..36747e1 100644 --- a/docs/plans/20260604-adr-0044-website.md +++ b/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. -- **Concepts** — projects & storage; undo, history & replay. -- **Simple-mode command reference** — full surface; syntax conventions; + first project, simple vs. advanced mode, the example library. +- **Using the playground** — command-line options; the assistive editor + (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 ` / `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. -- **Types**, **Relationships**, **Constraints**, **Indexes**, **Query plans - / EXPLAIN**. -- **Working with the editor** — completion, highlighting, validity - indicator, in-line editing. -- **Errors explained** — the friendly error layer. -- **Export / import & sharing** (E2 recipes), **clipboard**. +- **Concepts** — the *why*: projects & storage model, the derived database, + how undo works. + +**Surface the assistive editor prominently** — it is a differentiator and +most helps beginners: a landing-page card + a Getting-started mention, both +linking into *Using the playground*. It is prime asciinema-cast material +(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 + diff --git a/website/STYLE.md b/website/STYLE.md index 8d02ecb..a68b6d7 100644 --- a/website/STYLE.md +++ b/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 diff --git a/website/astro.config.mjs b/website/astro.config.mjs index 9ac3880..312b2b6 100644 --- a/website/astro.config.mjs +++ b/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' } }] }, diff --git a/website/src/content/docs/concepts/projects-and-storage.md b/website/src/content/docs/concepts/projects-and-storage.md index daefb8f..14db1d7 100644 --- a/website/src/content/docs/concepts/projects-and-storage.md +++ b/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 -importing has its own reference page. +and the playground rebuilds the database for them. [Exporting and +importing](/using-the-playground/export-and-import/) has its own page. diff --git a/website/src/content/docs/getting-started/first-project.md b/website/src/content/docs/getting-started/first-project.md index e2e05ec..f738c87 100644 --- a/website/src/content/docs/getting-started/first-project.md +++ b/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 Enter to run them. +and press Enter to run them. As you type, the field completes +commands with Tab 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/). diff --git a/website/src/content/docs/index.mdx b/website/src/content/docs/index.mdx index a25ac87..3fd8352 100644 --- a/website/src/content/docs/index.mdx +++ b/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. + + The input field completes commands with Tab, highlights + syntax, flags mistakes before you run them, and hints what comes next. + ## Start here diff --git a/website/src/content/docs/reference/columns.md b/website/src/content/docs/reference/columns.md new file mode 100644 index 0000000..77f2906 --- /dev/null +++ b/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] : () +rename column [in] [table]
: to +change column [in] [table]
: () [--force-conversion | --dont-convert] +drop column [from] [table]
: [--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/). diff --git a/website/src/content/docs/reference/constraints.md b/website/src/content/docs/reference/constraints.md new file mode 100644 index 0000000..5989932 --- /dev/null +++ b/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
.+add constraint unique to
.+add constraint default to
.+add constraint check () to
.+drop constraint (not null | unique | default | check) from
.+``` + +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/)). diff --git a/website/src/content/docs/reference/indexes.md b/website/src/content/docs/reference/indexes.md new file mode 100644 index 0000000..1246acd --- /dev/null +++ b/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 ] on
([, ...]) +drop index +drop index on
([, ...]) +``` + +In advanced mode, `CREATE [UNIQUE] INDEX … ON
(…)` 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/). diff --git a/website/src/content/docs/reference/inserting-and-editing-data.md b/website/src/content/docs/reference/inserting-and-editing-data.md new file mode 100644 index 0000000..bcba77b --- /dev/null +++ b/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
[([, ...])] [values] ([, ...]) +update
set =[, ...] (where = | --all-rows) +delete from
(where = | --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/). diff --git a/website/src/content/docs/reference/querying-and-inspecting.md b/website/src/content/docs/reference/querying-and-inspecting.md new file mode 100644 index 0000000..7dde7c4 --- /dev/null +++ b/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
[where ] [limit ] +show table
+show tables +show relationships +show indexes +show relationship +show index +``` + +## Querying (advanced mode) + +Advanced mode runs full SQL `select`, including joins, `group by`, `order +by`, set operations, and `with` (CTEs): + +```rdbms-syntax +select (* | [as ][, ...]) from
[where ] [order by [asc|desc][, ...]] [limit ] +``` + +## 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
[where ] +explain