svelte-kit-vice/docs/process/PLAN-arts-docs-reconciliation.md

# 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 |

## Decisions (locked by the user, 2026-07-03)

1. **Arts structure** → **E5-in-place-reconciled + `active-app` promoted to an
   architecture chapter.** The 22 arts stay next to the code (drift-fixed,
   ES→EN, indexed); only active-app becomes `docs/architecture/active-app.md`
   (B1). Same call F7 made for the peripheral READMEs.
2. **orca** → **E5-reconciled for now** (fix the 6 phantom fields + ES→EN);
   NOT an architecture chapter. Revisit only if it grows a consumer-facing
   surface.
3. **DESIGN docs** → **move to `docs/decisions/`** as `design-*` siblings of the
   RFCs (stubs at old paths keep the `§N` provenance citations resolving).
   `DESIGN_TIMR.md` (Spanish, 1400 L): translate, OR keep verbatim-historical
   with a `status: historical` header (the F7 chronicle rule) — decide at B2
   based on how much of it is normative-vs-narrative.

These lock B1/B2. A1/A2 are unaffected (drift + language are needed regardless).

## 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.