Docs: record the spec-follows-code regime across the working docs

AGENTS.md

@@ -11,9 +11,10 @@ a local library of **snippets** (saved Vega-Lite specs), edits each as JSON with
 validation and a live chart preview, and reuses **datasets** across many snippets. Fully
 local, offline-capable, no account.
 
-It is a **spec-driven rebuild** on an architecture adapted from its sibling project Syto.
-The authoritative behavioral contract is **`docs/spec/`** (sections 00–10). Implement _to
-the spec_; do not port legacy code.
+It is a rebuild on an architecture adapted from its sibling project Syto. **`docs/spec/`**
+(sections 00–10) is the behavioral record: the code leads and the spec is kept rewritten
+to match — a user-facing change isn't done until its spec section describes it. Do not
+port legacy code.
 
 ### Technical Stack
 
@@ -74,7 +75,7 @@ src/
 │   └── infrastructure/  # IndexedDB, localStorage, Monaco, settings adapters
 styles/              # Global CSS (tokens, base)
 docs/
-├── spec/            # Authoritative behavioral specification (00–10) — the WHAT
+├── spec/            # Behavioral specification (00–10) — the WHAT (record; code leads)
 ├── architecture/    # Architecture playbook (00–11) — the HOW (self-contained)
 │   └── visual-specimen.html  # Standalone token sandbox + reusable-primitive catalog
 ├── exploration/     # Point-in-time records (research, reviews, scope memos) — not maintained
@@ -116,8 +117,10 @@ npm run format     # Prettier
     trimming IBM Plex to the latin subsets dropped Cyrillic — capability for an
     internationally-usable app. We ship every script subset and precache them for offline;
     `unicode-range` means the browser only downloads what a glyph needs anyway.)
-- **Spec is the contract** — when in doubt, read `docs/spec/`. If the spec is wrong or
-  silent, raise it; change the spec deliberately rather than drifting from it.
+- **Spec follows code** — `docs/spec/` is the descriptive record of behavior; the code
+  leads. When in doubt about existing behavior, read the spec. When you ship user-facing
+  behavior, update the matching spec section in the same session; if spec and app
+  disagree, the spec is stale — rewrite it deliberately, never drift silently.
 - **Core-first** — for each feature, build the pure `src/core/` logic with tests before UI.
 - **Session wrap-up** — when the user signals the session is wrapping, run the review
   pass before any commit: `/doc-update` in-session first (flush unrecorded rationale),