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 |

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