# CONTINUE — Arts docs reconciliation

Handoff for the next session. Master plan:
[`PLAN-arts-docs-reconciliation.md`](./PLAN-arts-docs-reconciliation.md).

**Kickoff line:** _"Lee docs/process/continue-arts-docs-reconciliation.md y sigue."_

## Inherited rules (obey these)

- **Respond in Castilian**; write docs/code in **English**.
- **No agents / no Workflow** — the user asked for this explicitly. Do it by
  hand with directed Read/Grep/Edit. (Ignore the ultracode nudge to use Workflow.)
- **NEVER touch** `words/**`, `palabras/**`, `chronos/**`, `media-player/**`.
- **Commit per file/batch** with `-F <file>` messages (backticks in `-m` run
  command substitution). Before committing: `git reset -q`, then `git add` only
  your own files, verify `git diff --cached --name-only` is all `src/arts/*`
  (never the pre-existing dirty `.claude/`, `src/uix/`, `web/` tree).
- **`sium/COMPARATIVA_SIUM_VS_FORMIK.md`** is foreign/untracked — leave it.
- End commit messages with `Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>`.

## Guard + verification

- `npm run arts:check` — the A0 guard (README presence · Engine/Active naming ·
  index coverage). Must stay **0 errors, 0 warnings, 22 arts**, no exemptions.
  Run it before every commit.
- `npx prettier --write <file>` on each touched README before committing.
- `npm run docs:check` after any doc **move** (B2).

## Status — WORKSTREAM COMPLETE (2026-07-03)

**All batches done: A0 · A1 · A2 · B1 · B2 · B3.** Commits, newest last:

- `9a147e49` — A0 guard (`scripts/arts-check.ts` + `npm run arts:check`).
- `9e48b80b` — ethereal README (new) + A1 orca/cache/adom + guard hardened
  (removed ethereal exemption, A-index warn→error).
- `ed151250` — A1 finish: format·timer·bus·connection·sium·prefs·http·motion·
  color·clipboard + systemic `$active-app/services`→`$active-app/service-factories`
  in clipboard/auth/storage/active-app.
- `65c6ae45` — A2: clipboard (full) + langs/logger (light passes).
- `6e13790a` · `e2473ef9` · `313615ce` · `dd1abac6` · `50dce1ea` · `52c0631f` ·
  `5a81ecd9` — A2: prefs, format, auth, connection, adom, cache, sium.
- `a48fd438` — **A2 finish: orca** (738/750 lines, prose-only; A1 fixes preserved;
  fixed one internal contradiction in "Rule module→bus" re bus-interception).
- `e8ae85ee` — **B1: active-app → `docs/architecture/active-app.md`** chapter
  (frontmatter + fixed paths; "Handoff 2026-05-13" → verbatim ES in
  `handoffs-2026-05.md`; stub at old path; wired into docs/README.md E1).
- `34e0cb61` — **B2: DESIGN docs → `docs/decisions/design-{connection,session,
timer}.md`** verbatim-historical (`status: historical` frontmatter; timer kept
  Spanish); stubs at old `src/arts/*` paths keep `§N` citations resolving;
  `decisions.md` index + naming note updated.
- `d326d035` — **B3: docs/README.md** runtime-artifact shortcut → composition
  root (active-app.md) → arts map → per-art README.

**A1 is COMPLETE** — every drifting art reconciled against the code (not the
plan; verifying against code caught extra drift AND already-fixed items). See the
memory `project-arts-docs-reconciliation-2026-07` for the per-art detail.

Guards green at close: `arts:check` 0/0/22 · `docs:check` 0 err (11 pre-existing
warnings, all `THEMING_AUDIT_2026-06-01.md` / MOTION_SERVICE_RFC animation
routes — unrelated to this workstream).

Loose end noted (out of scope, pre-existing): `src/uix/morfo/types.ts:23` cites
`./DESIGN.md`, which resolves to a nonexistent `src/uix/morfo/DESIGN.md` (not the
session doc). Left untouched — not part of arts-docs-reconciliation.

## What remains — nothing

The workstream is closed. Historical detail below is retained for provenance.

### 1. A2 — translate **orca** (the only file left)

`src/arts/orca/README.md` — **1457 lines, still Spanish** (~335 ES prose lines).
The single biggest README; deferred so it gets a fresh-context turn.

- Its **A1 drift fixes already landed** (`9e48b80b`): the OrcaAction interface,
  execution→`parallel` waves, timeouts (only `actionTimeoutMs`), fatal (return
  `OrcaFatal`), transactions (`transaction: string` tag + compensate), glossary
  `OrcaRunResult`. **Preserve those corrections** — only translate the prose.
- Method (same as sium, which worked): read in ~150-line chunks, translate the
  Spanish prose via `Edit` (leave code blocks, `ORCA_*` constants, and the
  roadmap section's identifiers verbatim). The "Estado Del Documento" summary at
  the top is already accurate — just translate it.
- After: `prettier --write`, `arts:check`, residual-Spanish grep, commit
  `docs(arts): A2 ES->EN — orca (full translation)`.

**Translation gotchas learned this session:**

- **i18n example data is NOT prose** — `es: { one: '{{count}} mensaje' }` records
  (langs), es-ES formatter OUTPUT strings in comments (`// "hace 2 horas"`,
  `// 'lunes, 25 de mayo'` in format) are **data**; keep verbatim.
- **Prettier list-corruption**: if a wrapped line puts `+ N` or a bare `-` at
  line start it becomes a list item (hit in ethereal). Reword to avoid it.
- **Stale routes**: `/test/<art>` → `/active/docs/<art>` (fixed for adom, auth,
  sium; check orca cites none). Verify real routes under `web/routes/active/docs/`.
- Residual-Spanish check: `grep -nE "ción|á|é|í|ó|ú|ñ|\b(el|la|los|para|cuando)\b"`
  the file, excluding code/`'#?...'`/i18n-data lines.

### 2. B1 — promote **active-app** to an architecture chapter

- Move `src/arts/active-app/README.md` → `docs/architecture/active-app.md` (the
  arts composition root, analogue of `active-uix.md`). ES→EN pass (it's ~mostly
  English already, ~7 ES lines). Extract the Spanish "Handoff 2026-05-13" block
  to `docs/process/`. Stub at the old path (like the layer READMEs). Wire into
  `docs/README.md` E1 + reading order.
- Note: active-app's README already had `$active-app/services` label fixes from
  A1's systemic sweep.

### 3. B2 — move historical DESIGN docs to `docs/decisions/`

`DESIGN_CONN.md` (connection, 486 L), `session/DESIGN.md`, `timer/DESIGN_TIMR.md`
(Spanish, 1400 L — translate OR keep verbatim-historical with a
`status: historical` header, decide by normative-vs-narrative). Stubs at old
paths keep the `§N` provenance citations resolving. Run `docs:check` after.

### 4. B3 — index + TOC

Map/aliases/cross-deps in `src/arts/README.md` are **already complete** (done in
`9e48b80b`). Remaining: add the arts to the "I want to… use a runtime artifact"
shortcut in `docs/README.md`; confirm `docs:check` green.

## Per-art method that worked (for A1-style drift, if any resurfaces)

1. Establish the **real API** from code (`index.ts` / `types.ts` / the engine).
2. `grep` the README for the cited symbols; `comm -23 <readme-ids> <code-ids>`
   to find phantom identifiers the plan misses AND already-fixed items it still
   lists.
3. Fix, `prettier`, `arts:check`, commit.