Initial scaffold: spec, architecture playbook, and M0 skeleton

.claude/skills/doc-update/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: doc-update
+description: Update project documentation based on knowledge gaps discovered during the current session
+disable-model-invocation: false
+---
+
+# Documentation Update from Session Context
+
+Review the current session to identify knowledge gaps that caused suboptimal codebase
+navigation, then update the relevant documentation.
+
+## The quality bar
+
+Every addition must pass this test: **"Would this save a future session at least 5 minutes
+of exploration?"**
+
+Documentation serves two purposes — know **where to look** and know **what to do**. Both
+are valuable, but at different levels of detail:
+
+- **Navigation map** (good): "Preview flow: `LivePreview.tsx` → `prepareSpecForRender()` (core) → `vega-embed`" — lists the files and their roles so you don't read a dozen files to find the right four.
+- **Decision rule** (good): "The fit-mode/reference-resolution transform runs on a *copy* of the spec — never mutate the stored spec" — captures a non-obvious convention.
+- **Code walkthrough** (bad): "SnippetStore.updateDraft sets draftSpec, which a startup subscriber watches, debounces, then calls snippetStore.put… " — restates the code, goes stale on any rename.
+
+**Navigation maps** use file/module names (stable) to show flow direction. **Decision
+rules** capture "when/why" constraints. **Code walkthroughs** restate implementation
+details — that's what reading the code is for.
+
+For documentation organization, see **[CLAUDE.md](../../../CLAUDE.md)** and the doc index in
+**[AGENTS.md](../../../AGENTS.md)**.
+
+## The three documentation layers (know which one a gap belongs to)
+
+- **`docs/spec/`** — the *what*: behavioral contract (what the app does, acceptance points).
+  This is a **contract**. Only change it when product behavior genuinely changes, and do so
+  deliberately — never as a casual "fill a doc gap" edit. A how-detail does NOT belong here.
+- **`docs/architecture/`** — the *how*: the patterns behind each layer (state, persistence,
+  modals, routing, rendering, inference, relationships). Most navigation maps and decision
+  rules land here.
+- **`docs/IMPLEMENTATION-PLAN.md`** — the *when*: milestone sequence and scope.
+
+## Process
+
+### 1. Analyze the session
+
+Look back through the conversation and identify:
+
+- **Missing navigation maps**: Where did you read many files to discover which 3–4 files a
+  flow actually involves? A one-line map of file roles would have saved that.
+- **Missing rules**: What conventions or constraints were discovered that a new session
+  would violate or re-discover?
+- **Non-obvious "when/why" knowledge**: What decisions require understanding intent, not
+  just implementation?
+
+Produce a brief list of gaps before proceeding. For each, state what's needed in one
+sentence — a navigation map ("X flow: file → file → file") or a decision rule ("X must/must
+not do Y"). If you can't state it concisely, it may be too implementation-specific to document.
+
+### 2. Categorize and target
+
+Map each gap to the right document:
+
+| Gap type | Target document |
+| --- | --- |
+| Product behavior, capabilities, acceptance points | `docs/spec/` (the relevant 00–10 section) — **contract; change deliberately** |
+| State / Zustand stores | `docs/architecture/01-state-and-stores.md` |
+| Persistence, IndexedDB, localStorage, migrations | `docs/architecture/02-persistence.md` |
+| Modals, dialog lifecycle | `docs/architecture/03-modal-system.md` |
+| URL routing, keyboard/events | `docs/architecture/04-routing-and-events.md` |
+| Rendering, theming, vega-embed, preview | `docs/architecture/05-rendering-theming-preview.md` |
+| Type inference, dataset profiling | `docs/architecture/06-type-inference.md` |
+| Names, snippet↔dataset links, rename propagation | `docs/architecture/07-naming-and-relationships.md` |
+| Milestone scope, build order | `docs/IMPLEMENTATION-PLAN.md` |
+| Project philosophy / identity | `SOUL.md` |
+| Onboarding, conventions, stack | `AGENTS.md` / `CLAUDE.md` |
+
+If a gap fits no existing document, consider a new section in the closest one; prefer
+extending over creating. A brand-new architecture topic can become `docs/architecture/08-*.md`
+(add it to `docs/architecture/00-overview.md`).
+
+### 3. Read, locate, and check for bloat
+
+For each target document:
+
+- Confirm the gap isn't already covered (if partially covered, extend rather than duplicate).
+- Find the right insertion point.
+- **Check section length**: if a section is already long (>50 lines), tighten or consolidate
+  before adding. Documentation that only grows becomes noise.
+
+### 4. Apply updates
+
+- **Rules and constraints over descriptions**: "X must do Y because Z" beats "X works by A, B, C".
+- **Stability over specifics**: no line numbers, no file counts, no volatile details.
+- **Proportional**: a missing sentence doesn't need a new section; a missing concept does.
+- **Match existing style**: follow surrounding formatting, heading levels, tone.
+- **Self-contained**: never add a pointer that requires an external repository to follow.
+- **Consolidate while adding**: net size increase should be minimal.
+
+### 5. Update index (if needed)
+
+Only update `CLAUDE.md` (or `docs/architecture/00-overview.md`) if a new document was created
+or a major new section was added that should be discoverable. Not for minor additions.
+
+## What NOT to document
+
+- **Code walkthroughs**: prose that restates the code; goes stale on any rename. (Navigation
+  maps that list file roles are fine.)
+- **Obvious-from-code patterns**: if reading the file makes it clear, don't add docs.
+- **Session-specific context**: current task details, debugging steps taken.
+- **Speculative patterns**: only document conventions confirmed across multiple instances.
+- **Implementation details that change with refactoring**: if renaming a variable would
+  invalidate the doc, it's too specific.