docs(process): arts docs reconciliation plan (the active-app ecosystem)

The docs reconciliation (F6 drift-fix + F7 corpus-libro) covered
active-uix (morfo/soma/sema/eidos) but left the active-app side — the 22
arts/ runtime artifacts — as E5-in-place, un-reconciled. This plan does
for arts what F6+F7 did for the UIX layers, grounded in a 22-agent
per-art audit (every drift verified against the code): ~40 doc-vs-code
mismatches across 15 arts, 12 READMEs needing ES->EN, ethereal missing a
README, 3 historical DESIGN docs, dead route/demo cross-refs. Batches
A0 (guard) / A1 (drift sweep) / A2 (ES->EN) / A3 (ethereal README) / B1
(active-app -> architecture chapter, the missing analogue of
active-uix) / B2 (DESIGN docs -> decisions/) / B3 (index+TOC). Three
structural open questions for the user (arts E5 vs book; orca chapter;
DESIGN docs move) mirror F7's corpus-shape decision.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs/process/PLAN-arts-docs-reconciliation.md

@@ -0,0 +1,91 @@
+# PLAN — Arts docs reconciliation (the `active-app` ecosystem)
+
+> **Why this exists**: the docs reconciliation (Phase 6 drift-fix + Phase 7
+> corpus-libro) covered the **active-uix** ecosystem (morfo · soma · sema ·
+> eidos → the `docs/architecture/*` chapters). The **active-app** side — the
+> `arts/` runtime artifacts that `ActiveApp` composes — was left as E5-in-place
+> and never got the same pass. This plan does for arts what F6+F7 did for the
+> UIX layers. Grounded in a 22-agent per-art audit (2026-07-03) — every drift
+> below was verified against the code.
+
+> **Kickoff for a new session**: *"Lee docs/process/PLAN-arts-docs-reconciliation.md
+> y ejecuta la tanda que toque."* Rules (inherited): respond in Castilian, docs
+> in English; NEVER touch `words/` `palabras/` `chronos/` `media-player`; commit
+> per batch (`-F file` messages — backticks in `-m` run command substitution);
+> `git reset -q` + stage only your own files; each systemic fix ships a guard.
+
+## The ecosystem (22 arts)
+
+`src/arts/` = the runtime building blocks `ActiveApp` composes (the
+`active-app/README.md` composition root is the analogue of `active-uix`). Naming
+canon: `Engine*` (stateless, pure factory) / `Active*` (reactive `$state`,
+`.svelte.ts`). The shared `ActiveEngine<TSnapshot,TError>` contract + the index
+live in [`src/arts/README.md`](../../src/arts/README.md).
+
+## Audit findings (2026-07-03, evidence-based)
+
+| Art | Lang | Drift | Extra docs | Disposition |
+|---|---|---|---|---|
+| **active-app** | mixed | 3 (missing `defineEngineMotion` in services table; 3/7 presets shown; incomplete FS layout) | — | **→ architecture chapter** (composition root; has a Spanish "Handoff 2026-05-13" to extract) |
+| **orca** | spanish | **6** (phantom `OrcaAction.priority`/`tokenTimeoutMs`/`onFatal`/`execution`+`ORCA_EXEC_*`) | — | **book-chapter candidate** (orchestration kernel; highest drift; ES→EN, high effort) |
+| adom | spanish | 3 (missing `prefersReducedMotion`/`writeProperty`/`removeProperty`; `listen()` 4 overloads; 9 undoc rune helpers) | docs page (ok) | E5-reconciled + ES→EN; stale `/test/adom` ref |
+| bus | english | 4 (layer diagram says `arts/bus` but files in `libs/bus`; stale preset names post-refactor; `COLLECT` error mode undoc) | — | E5-reconciled (agent said book-chapter) |
+| cache | mixed | 4 (wrong `createActiveApp({cache})` sig → `services:{cache:defineActiveCache()}`; undoc `clearError`/`snapshot`/`onChange`; demo URL placeholder) | — | E5-reconciled (agent said book-chapter) |
+| format | spanish | 4 (`unts/`→`units/` typo; undoc `currency.convertAs/formatAs`, `units.convertToDefault`) | `currency/README.md` (keep) | E5-reconciled + ES→EN |
+| timer | english | 4 (FS diagram 11→20 files; "50 tests"→47; `reschedule` behavior/errors drift vs DESIGN) | `DESIGN_TIMR.md` (1400 L, **Spanish**, normative) | E5-reconciled; **DESIGN doc → decisions/ (translate)** |
+| color | english | 3 (JSDoc `setCssVariables`→`applyColorScheme`; "Phase 0 not consumed" stale; bare THEMING ref) | — | E5-reconciled |
+| connection | spanish | 2 (`createEngineConnections()` needs `{timers}`; 6 missing `Active` props) | `DESIGN_CONN.md` (486 L, historical) | E5-reconciled + ES→EN; **DESIGN → decisions/**; stale `/active`+`conn-chat` refs |
+| sium | spanish | 3 (18 codes listed, 8 omitted; undoc `cssLength`/`CSS_LENGTH_REGEX`) | `COMPARATIVA_*` (foreign/untracked), `_examples/README` | E5-reconciled + ES→EN |
+| prefs | spanish | 2 (wrong `createPrefsStorageBridge`/`applyBrowserEnvironment` param names) | — | E5-reconciled + ES→EN |
+| clipboard | spanish | 1 (`$active-app/services`→`/service-factories`) | — | E5-reconciled + ES→EN (small) |
+| motion | english | 2 (missing `resolve/has/list/exit`; `JsDriver` `svelte` unimplemented) | — | E5-reconciled |
+| http | english | 1 (`DEFAULT_*`→`HTTP_DEFAULT_*` names) | — | E5-reconciled |
+| **ethereal** | english | 0 | `PERF.md` only | **needs-readme** (no README at all) |
+| session | english | 0 | `DESIGN.md` (historical) | E5 clean; **DESIGN → decisions/** |
+| perm | english | 0 | — | E5 clean; stale `/test/perm` ref |
+| perf | english | 0 | — | E5 clean |
+| auth | spanish | 0 | — | E5 clean + ES→EN only |
+| langs | mixed | 0 | — | E5-reconciled (light EN pass) |
+| logger | mixed | 0 | — | E5-reconciled (light EN pass) |
+| storage | english | 0 | — | E5 clean |
+
+**Rollup**: ~40 verified drift findings across 15 arts · **12 READMEs need
+ES→EN** (8 spanish: adom, auth, clipboard, connection, format, orca, prefs,
+sium; 4 mixed: active-app, cache, langs, logger) · **1 missing README**
+(ethereal) · **3 historical DESIGN docs** (connection, session, timer) + 1
+foreign COMPARATIVA (sium) · several **dead route/demo cross-refs**.
+
+## Batches (mirror F6 drift-fix → F7 structure)
+
+| Batch | Content | Effort |
+|---|---|---|
+| **A0** | **Guard first**: extend `docs-check` (or a new `arts:check`) — every `src/arts/{name}/` has a README; the `Engine*/Active*` naming holds; (optional) an I-invariant that the arts index lists every art. Ship it so A1–A3 land against a net. | low |
+| **A1 — drift sweep** | Fix the ~40 doc↔code mismatches, art by art (verify each edit against the code symbol the audit cited). Priority by count: orca(6) · bus/cache/format/timer(4) · active-app/adom/color(3) · connection/prefs/sium(2) · clipboard/http/motion(1). Also the dead cross-refs (adom `/test/adom`, connection `/active`+`conn-chat`, perm `/test/perm`, cache demo URL). | high |
+| **A2 — ES→EN** | Translate the 8 Spanish + 4 mixed READMEs (faithful, mark stale with `<!-- TODO(reconcile) -->`, same rule as F6). Biggest: orca, adom, format, connection, prefs, sium. | high |
+| **A3 — ethereal README** | Author `src/arts/ethereal/README.md` (it only has `PERF.md`). Ethereal is the floating/positioning engine (`$ethereal` = the own floating-UI runtime). Follow the art README shape; link `PERF.md` as its correctness record. | low |
+| **B1 — active-app chapter** | Promote `active-app` to `docs/architecture/active-app.md` — the arts composition root, the missing analogue of `active-uix.md`. Extract the "Handoff 2026-05-13" Spanish block to `docs/process/`; ES→EN; stub at the old path (like the layer READMEs). Wire into `docs/README.md` E1 + the reading order. **This is the "active-app was missing from the book" fix the user pointed at.** | medium |
+| **B2 — DESIGN docs** | Move the historical design docs to `docs/decisions/` like the eidos RFCs (they're already indexed in `docs/decisions.md`): `DESIGN_CONN.md`, `session/DESIGN.md`, `timer/DESIGN_TIMR.md` (Spanish, 1400 L — translate or move verbatim-as-historical per the F7 chronicle rule). Stubs at old paths keep the ~30 `DESIGN_TIMR §12.8`-style provenance citations resolving. `sium/COMPARATIVA` is foreign/untracked — leave unless staged. | medium |
+| **B3 — index + TOC** | Verify `src/arts/README.md` lists all 22 (add any missing); confirm `docs/README.md` E5 pointer + add the arts to the "I want to… use a runtime artifact" shortcut. `docs:check` green. | low |
+
+## Open questions (need the user — like F7's AskUserQuestion)
+
+1. **Arts structure**: keep the 22 arts as **E5-in-place-reconciled** (recommended
+   — they're peripheral runtime services, same call F7 made) with only
+   **active-app** promoted to an architecture chapter? Or move all arts into a
+   new **`docs/arts/` book section**? *Recommendation: E5-reconciled +
+   active-app chapter.*
+2. **orca**: the orchestration kernel is the second architecturally-heavy art
+   (highest drift, book-chapter verdict). Promote it to `docs/architecture/orca.md`
+   too, or keep E5-reconciled? *Recommendation: E5-reconciled for now; revisit if
+   it grows a consumer-facing surface.*
+3. **DESIGN docs**: move to `docs/decisions/` translated (F7 pattern), or keep
+   in-place with stubs (they're historical, Spanish, cited by `§N`)? *Recommendation:
+   move to decisions/ as `rfc-`/`design-` siblings; translate the timer one or
+   keep it verbatim-historical (chronicle rule).*
+
+## Verification (per batch)
+
+`npm run check` (compare to the drifting foreign baseline, not 59) · the art's
+own tests where they exist (`vitest src/arts/{name}`) · `npm run docs:check`
+after any doc move · `arts:check` (A0) green · browser only if an art has a live
+docs page.