docs: ADR-0042 — public website + documentation site plan

Planning artifacts for the first public website, recorded before any
code is written.

- ADR-0042: the decisions — Astro 5 + Starlight + Tailwind v4 (over
  SvelteKit); asciinema .cast demos reusable in docs (scripted-input
  driver, not history.log replay); in-page WASM playground deferred
  behind a stable demo seam, with the portable-core vs native-edge
  boundary recorded for a future ADR; portable static hosting (Vercel
  target); monorepo (website/); website is the canonical docs home;
  full-feature-set docs with "planned" callouts; user-facing copy uses
  no engine name and no "DSL"; install via prebuilt binaries + package
  managers.
- docs/plans/20260604-adr-0042-website.md: implementation plan with the
  grounded documentation inventory and phases A–E.
- website/STYLE.md: living documentation style guide + open-decisions log.
- docs/adr/README.md: index updated for ADR-0042 (numerical order).

docs/adr/0042-public-website-and-documentation-site.md

@@ -0,0 +1,124 @@
+# ADR-0042: Public website and documentation site
+
+## Status
+
+Accepted (2026-06-04). Implementation plan:
+[`docs/plans/20260604-adr-0042-website.md`](../plans/20260604-adr-0042-website.md).
+
+## Context
+
+RDBMS Playground is nearing its first public release and needs a public
+website that does two jobs: **attract** — a landing page that shows the
+playground in action — and **document** — a thorough, canonical reference
+for everything the playground can do.
+
+The documentation-heavy surface is already implemented and verified (full
+simple- and advanced-mode command set, the ten-type vocabulary,
+relationships, constraints, indexes, EXPLAIN, undo/history/replay, projects,
+export/import, the teaching echo, clipboard, friendly errors, tab completion
+and syntax highlighting; 2151 tests passing at the time of writing). The
+site is therefore largely a presentation-and-writing effort, not a
+wait-for-features one. A grounded inventory of what is shippable now lives
+in the implementation plan.
+
+Several choices here had no canonical default; they were settled during a
+planning + `/runda` pass with the user and are recorded below.
+
+## Decision
+
+1. **Stack — Astro 5 + Starlight + Tailwind v4.** Astro's content-first,
+   zero-JS-by-default model with the Starlight docs theme fits a
+   marketing-landing-plus-heavy-docs site better than the alternative
+   considered, SvelteKit + Tailwind (the usual go-to here). Interactive
+   pieces are added as Astro islands (Svelte or vanilla), so Svelte is still
+   available where it earns its place. Tailwind v4 is wired via the official
+   `@tailwindcss/vite` plugin; the `@astrojs/starlight-tailwind` plugin
+   bridges Tailwind with Starlight's theming.
+
+2. **Demo medium — asciinema.** Showcase sequences are recorded as
+   asciinema `.cast` files (text-based, small, faithful to the full
+   alternate-screen render) and embedded with `asciinema-player`. The same
+   casts are reused inline in the docs — one recording format serves both
+   the landing page and documentation enrichment. Recordings are produced by
+   a **scripted-input driver** that types commands into a real PTY with
+   viewer-friendly pacing; the app's own `history.log` **replay** (ADR-0034)
+   re-executes commands without typing animation or pacing and is therefore
+   suitable only for state-deterministic docs snippets, not the hero demo.
+
+3. **In-page WASM playground — deferred** (OOS: **deferred**, not rejected).
+   A live, type-it-yourself playground compiled from the Rust app to
+   WebAssembly is desirable but is a multi-week sub-project, so it does not
+   block the site. The demo section is designed with a stable seam (a single
+   `Demo` component contract) so a WASM playground island can replace the
+   asciinema player later with no change to call sites. Recorded boundary
+   for that future work:
+   - **Portable core (runs on `wasm32-unknown-unknown` largely as-is):**
+     `src/dsl/*` (parser, types, grammar, walker), the pure `App::update()`,
+     `ui.rs`, `theme.rs`, `friendly/*`, output rendering; an in-memory DB
+     path already exists (`Connection::open_in_memory()`). `rusqlite`
+     compiles to the browser target via its `ffi-sqlite-wasm-rs` feature.
+   - **Native edge needing `cfg`-gated browser replacements:** the
+     multi-thread Tokio runtime + the dedicated DB **worker thread**
+     (ADR-0010) → current-thread/in-line async; `crossterm` terminal +
+     event-stream → a browser backend (e.g. Ratzilla's DOM/Canvas) + DOM
+     events; `arboard`, `zip`, file persistence (ADR-0015), file logging;
+     and the rusqlite **backup-API** undo (ADR-0006) → a SQL dump/restore.
+   When taken up, this becomes its own ADR + iteration plan.
+
+4. **Hosting — portable static build; Vercel is the likely target.** Astro 5
+   builds to static HTML/CSS with no adapter, so the output deploys equally
+   to Vercel, Cloudflare Pages, Netlify, or GitHub Pages. We avoid coupling
+   to any one host. **No CI yet** — the site is tested locally (`pnpm dev` /
+   `pnpm build`) until the repo reaches its public home.
+
+5. **Repo topology — monorepo.** The site lives under `website/` in the
+   playground repo; the crate stays at the repo root. The repo as a whole
+   moves to its public home later; site and crate travel together.
+
+6. **Canonical docs home — the website.** User-facing documentation lives on
+   the site. In-repo `docs/` keeps ADRs, handoffs, and development notes;
+   `docs/simple-mode-limitations.md` (requirement DOC1) was a development aid
+   and now *feeds* the site's content rather than competing with it. The
+   sharing recipes promised by requirement E2 become a docs page.
+
+7. **Documentation scope and conventions.** Document the **full supported
+   feature set**. Any capability not yet fully implemented (a small minority
+   — e.g. multi-line input, query cancellation, `seed`, `m:n` convenience,
+   ER-diagram export, the `show tables`/`relationships`/`indexes` family) is
+   either omitted or carries a clear **"planned / not yet available"**
+   callout — never presented as shipped. Two wording rules bind all
+   user-facing copy:
+   - **No engine name** (SQLite/STRICT/rusqlite/PRAGMA) — continues the
+     user-facing posture of ADR-0002; copy says "the database"/"the engine".
+   - **No "DSL"** — it is internal jargon. The two input modes are **simple
+     mode** (the playground's keyword command language) and **advanced
+     mode** (SQL).
+
+8. **Install documentation — two mechanisms.** The install page documents
+   **prebuilt release binaries** (self-hosted download — not GitHub
+   Releases, since the repo will move) and **package managers**. Both can be
+   written now against the planned mechanisms; concrete download URLs slot in
+   at release. (Distribution items D1–D3 in `requirements.md` remain the
+   tracking home for the release tooling itself.)
+
+## Consequences
+
+- The site can ship on the strength of already-implemented features; it is
+  gated on writing and recording, not on finishing the app.
+- One recording format (asciinema `.cast`) serves both marketing and docs,
+  and is reusable as the app evolves (re-run the script, re-record).
+- The WASM playground is preserved as a real future option without holding
+  up launch; the demo seam keeps the upgrade cheap.
+- A single canonical docs home removes the divergence risk of maintaining
+  user docs in two places.
+- Website build choices (Decisions 1, 2, 4, 5) are recorded here for
+  traceability but do not, by themselves, warrant further ADRs; only
+  app-architecture decisions (notably the future WASM port) will.
+
+## Out of scope
+
+- **In-page WASM playground** — *deferred* (see Decision 3); revisit as its
+  own ADR + iteration plan.
+- **Hosted/SaaS playground or a server-backed doc CMS** — *rejected*: a
+  static site fully satisfies the need, consistent with ADR-0007's
+  no-hosted-publishing stance. Revisit only if real demand emerges.