@nac3/forge-cli 1.0.50 → 1.0.52

package/README.md

@@ -1,390 +1,466 @@
-# Yujin Forge
-
-**A voice-first NAC-3 development framework + build tool.** Forge
-gives a developer (or an institution like ADIP teaching kids to
-code) a single CLI + chat panel that covers the full app-creation
-loop: read design specs by voice, generate code scaffolds from
-those specs, decorate vanilla HTML into NAC-3, drive existing apps
-via voice + chat.
-
-> Status: **v0.2.0-alpha.59z.92** (2026-06-04). **100% manifest
-> verb coverage**: every one of the 72 declared NAC-3 verbs has
-> at least one fake-scripted scenario asserting it gets invoked
-> (or refuses to) in the right intent. Brain matrix QA harness
-> at 168 scenarios (+68 since z.61); 22 new verbs in the arc
-> (8 misc + git.status/branch-list + office.excel.append-sheet
-> + 12 others); 8 helper CLIs under `yf qa` (run, scenarios
-> list/show/validate/stats, verbs coverage/sample,
-> brain-matrix-compare); 5 ops docs (SECURITY, CONTRIBUTING,
-> TESTING_GUIDE, DEPLOYMENT, CI_PIPELINE); 2 new doctrines
-> (verb-composition, explain-results); 2 new invariant kinds
-> (min_text_length, verb_invoked_in_order) + structural
-> fixture validator + lefthook pre-commit gate. F101 MCP
-> bridge backend complete (slice 3 panel UI pending); F106
-> office.* + F107 a11y.* verbs shipped; HITO 5 agent
-> orchestrator design draft awaiting Pablo clarification.
->
-> **HITO 0 -- credentials vault.** AES-256-GCM at-rest encryption
-> with machine fingerprint binding, atomic writes (0o600), one-shot
-> reveal, vault modal in chat panel. Slots: anthropic / openai /
-> google_voice / elevenlabs / github_token.
->
-> **HITO 1 -- voice + reader + spec ingest.** Bidirectional voice
-> (Whisper + Google STT, ElevenLabs + Google + Yujin Cloud TTS) with
-> chunked pipelined playback (~600 ms first audio on long sections).
-> Voiceprint enrolment + 5-layer trust model + liveness challenge on
-> irreversible ops. Document reader for **txt / md / source / html /
-> rtf / csv / epub / pdf / docx / xlsx** (10 formats) with voice-
-> driven navigation (open / next / search / bookmark / recap). Spec
-> drag-drop: drop a PDF/DOCX/etc into chat -> Forge parses ->
-> Claude extracts requirements/entities/endpoints/components ->
-> generates a file plan -> writes the scaffold after explicit
-> approval -> rollback on demand.
->
-> **Fase F -- 10-language i18n + manuals.** Panel UI + voice intent
-> matcher + HTML user manuals all available in
-> **es / en / pt / fr / ja / zh / hi / ar / de / it**. Globe button
-> in the chat panel swaps the active language; the new
-> `forge.manual.open` tool routes "abrime el manual" / "open the
-> manual" / "マニュアルを開いて" / etc to the right HTML manual
-> served through the reader pipeline. Catalog-lint refuses to
-> publish if any locale is missing keys.
->
-> Earlier work still shipping: G1 (AST migrator robustness) + G2
-> (LLM retry loop) + G3 (multi-page HTML) + G4 (--dry-run for ai
-> modes) + G5 (SPEC sync) + G6 (Figma scaffolder alpha) + the v0.3.0
-> chat tool-use loop (`forge.read_manifest`,
-> `forge.consult_nac_spec`, plus the V1.11..V1.13 github/git/
-> lifecycle tools and the V1.28 + V1.32 reader tools).
->
-> **988 vitest cases green** across 63 suites (Linux + macOS +
-> Windows CI). AI decorator validated on calc fixture (15/15
-> dispatch tasks OK) + Conduit-NAC3 (178/180 cross-lang at N=3).
-> See [yujin.app/nac-spec/migration/](https://yujin.app/nac-spec/migration/)
-> for the migration paper, `docs/HITO_1_ARCHITECTURE.md` for the
-> voice+reader internals, and `docs/EVOLUTION_PLAN.md` for what is
-> next.
-
-## What it is
-
-Four things in one:
-
-1. **An AI-powered NAC-3 decorator.** `yf migrate <dir> --ai-silent`
-   calls Claude Sonnet 4.6 with the HTML + JS source, gets back a
-   fully-decorated HTML + JSON manifest, post-processes the output to
-   bake in the NAC3 runtime + contract bridge + inline `NAC.register`.
-   Takes ~25 s and ~$0.05 per app.
-
-2. **A Pilot installer.** `yf pilot install <dir>` injects the
-   embedded chat + voice + multi-model bundle into any
-   Forge-decorated app. The same UI works against any NAC-3-compliant
-   page, regardless of how it was decorated.
-
-3. **A React/AST migration scaffold (planned).** `yf migrate
-   <existing-react-repo>` audits the codebase, proposes the migration
-   path screen-by-screen, executes the diff. The audit + apply flow
-   is in place; the React-specific AST migrator is in flight.
-
-4. **A voice-first developer assistant (HITO 1).** `yf chat`
-   launches a local panel with bidirectional voice, a 10-format
-   document reader, and drag-drop spec ingest. Drop a PDF / DOCX /
-   HTML spec into chat -> Forge extracts requirements via Claude ->
-   generates a file scaffold plan -> writes the project after you
-   approve. Reverse the scaffold with one click. Aimed at solo
-   developers + institutional teams (ADIP) who want the full
-   "read spec out loud, then write the code" cycle without leaving
-   the keyboard or the headset. See "Voice cockpit + spec ingest"
-   below.
-
-## Quick start
-
-```bash
-# Install
-npm install -g @nac3/forge-cli@latest
-
-# Guided first run: activates your license (auto-synced) + sets your
-# AI key (BYOK). One command, it walks you through the rest.
-yf onboard
-
-# Decorate a vanilla HTML app (one shot, no human input)
-yf migrate ./my-app --ai-silent --ai-out ./my-app-decorated
-
-# Same, but include Yujin Pilot (the embedded chat + voice cockpit)
-yf migrate ./my-app --ai-silent --with-pilot --ai-out ./my-app-decorated
-
-# Install Pilot into an already-decorated app
-yf pilot install ./my-app-decorated
-
-# Open it
-xdg-open ./my-app-decorated/index.html
-```
-
-The decorated output is **drop-in NAC3-ready**: no CDN dependencies
-at runtime, the manifest is registered inline at boot, every action
-button is wired through `NAC.bindAction`, the floating Pilot button
-appears bottom-right. Click it, paste an API key (Anthropic / OpenAI
-/ Google / DeepSeek / Groq), and drive the page by voice or text.
-
-## Commands
-
-| Command | What it does |
-|---|---|
-| `yf new <slug>` | Bootstrap a new Yujin Forge React app from `templates/react-app/`. |
-| `yf migrate <repo>` | Default mode: audit a project for NAC migration without writing. |
-| `yf migrate <repo> --apply` | Execute the proposed React/AST migration on `.tsx`/`.jsx`. |
-| `yf migrate <repo> --html` | Silent HTML walker -- auto-apply on `.html` files (rule-based, no LLM). |
-| `yf migrate <repo> --assisted` | HTML walker with CLI prompts for ambiguous elements (rule-based, no LLM). |
-| `yf migrate <repo> --ai-silent` | **AI-powered.** Claude one-shot decoration of an HTML file (paid seat). |
-| `yf migrate <repo> --ai-assisted` | AI-powered with ambiguity-resolution round. |
-| `yf migrate <repo> --with-pilot` | Inject Yujin Pilot bundle into the decorated output. |
-| `yf pilot install <dir>` | Inject Pilot into an already-decorated NAC-3 app. |
-| `yf chat` | Launch the embedded Claude Code voice+text panel hooked to the current project. |
-| `yf test` | Run the auto-generated test corpus + mocks + report coverage by NAC pipeline stage. |
-| `yf ship` | Gate: tests green + NAC-3 validate clean + LLM review pass + license valid -> deploy hook. |
-| `yf doctor` | Diagnose the local Forge install + license + dependencies. |
-| `yf validate` | Validate a NAC manifest against the spec schema. |
-| `yf license` | Manage license tokens. |
-
-See [docs/USAGE.md](docs/USAGE.md) for every flag and worked examples.
-
-## How decoration works
-
-A vanilla HTML/JS app starts like:
-
-```html
-<button onclick="digit('7')">7</button>
-```
-
-After `yf migrate --ai-silent`:
-
-```html
-<body data-nac-plugin="calc">
-  ...
-  <button onclick="digit('7')"
-          data-nac-id="calc.action.digit_7"
-          data-nac-role="action"
-          data-nac-action="digit_7">7</button>
-  ...
-  <script src="nac.browser.js"></script>
-  <script src="calc.js"></script>
-  <script src="nac-bridge.js"></script>
-  <script>
-    (function () {
-      var manifest = { "plugin_slug": "calc", ... };
-      window.NAC.register(manifest);
-    })();
-  </script>
-</body>
-```
-
-Any LLM driver can now call:
-
-```js
-await NAC.click_by_verb('calc', 'digit_7');
-```
-
-and the host's existing `digit('7')` handler runs **plus** the
-`nac:action:succeeded` contract event fires (because `nac-bridge.js`
-re-wired the inline onclick via `NAC.bindAction`).
-
-## How Pilot works
-
-Pilot is a single-file IIFE bundle + companion stylesheet that lives
-in `yujin-pilot/dist/`. `yf pilot install` (or `yf migrate
---with-pilot`) copies both into the target directory and inserts the
-script tags before `</body>`.
-
-At runtime, Pilot mounts a floating sumi-e branch button at
-bottom-right. Click it: chat panel opens. Click again: switches to
-the "pizarra" mode (chat + voice + action trace). Configure: paste
-API keys for any subset of {Anthropic, OpenAI, Google, DeepSeek,
-Groq}. Each provider supports all the models the
-[NAC3 v2.3 benchmark](https://yujin.app/nac-spec/benchmark/) exercised.
-
-Pilot reads `window.NAC.list_registered_plugins()` to get the active
-manifest, sends it to the selected LLM with the user's utterance,
-parses the JSON action chain, dispatches each via
-`NAC.click_by_verb`, reads back any configured status probe, then
-speaks the result via Web Speech / ElevenLabs / Google Cloud TTS.
-
-Config persists in `localStorage` under `yujin_pilot.config`. Keys
-never leave the browser. (Production deployments belong behind a
-server proxy.)
-
-See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full
-internal architecture.
-
-## Voice cockpit + spec ingest (HITO 1)
-
-`yf chat` opens a local panel with three views (globito / mini /
-full). The full view has a chat stream on the left and a "pizarra"
-trace on the right that shows every tool the system invoked to
-answer.
-
-What it covers end-to-end:
-
-- **Vault** -- modal accessible via the Keys button. Slots for
-  `anthropic`, `openai`, `google_voice`, `elevenlabs`,
-  `github_token`. Values are encrypted at rest with the machine
-  fingerprint; shown once on entry, never again.
-
-- **Voice in / voice out.** Press the mic, speak; the panel
-  records via `MediaRecorder`, ships the audio to the configured
-  STT provider, and either dispatches a recognised reader command
-  directly or feeds the transcript to the chat loop. Replies are
-  spoken back via the configured TTS provider with chunked
-  prefetch (first audio in ~600 ms even on long answers).
-
-- **Voiceprint trust.** Enroll your voice once -- subsequent voice
-  commands are gated by a 5-layer trust model
-  (unknown / heard / recognised / trusted / authorised). Irreversible
-  actions (force push, branch delete, deploy) ALWAYS require a
-  liveness challenge regardless of trust level: a random Spanish/
-  English phrase plus a random number you have to read back.
-
-- **Document reader.** Open any file in the project root and
-  navigate by voice: "abrime el readme", "siguiente", "buscar
-  pricing", "marcame aqui como inicio", "volver a marca inicio",
-  "recap". Supports **10 formats**: txt, md, source code (.ts / .py
-  / .rs / 80+ extensions), HTML, RTF, CSV/TSV, EPUB, **PDF**
-  (via pdfjs-dist), **DOCX** (via mammoth), **XLSX** (via sheetjs).
-  All format detection happens automatically.
-
-- **Spec drag-drop.** Drag a spec file onto the chat panel; an
-  overlay appears + the file uploads. Forge parses it through the
-  same reader pipeline, then a Claude call extracts structured
-  requirements, entities, endpoints, and UI components. A second
-  Claude call turns the extraction into a concrete file scaffold
-  plan (which files to create + where + what kind + which
-  requirement each serves + open questions for clarification).
-  Nothing is written until you POST `{approve: true}`. On approve,
-  the scaffolder writes the planned files with hand-rolled
-  templates per kind (model / api / component / test / doc) and
-  records a rollback log -- one click undoes the whole scaffold.
-
-- **Reader recap modes.** Default `literal` mode joins recent
-  spoken blocks into a TTS-friendly narrative for "que dijiste".
-  Optional `summary` mode calls Claude for a 1-2 sentence
-  compression; gated by env var `YF_ENABLE_CLAUDE_RECAP=1` so it
-  cannot fire by accident and charge tokens. Cost model in
-  `docs/RECAP_CLAUDE_COSTS.md`.
-
-### ADIP voice-first demo loop
-
-```
-User: (mic) "abrime el plan.md"
-  -> reader.open    -> TTS "El Plan"
-User: (mic) "siguiente"
-  -> reader.next    -> TTS "Primer paso"
-User: (mic) "buscar pricing"
-  -> reader.search  -> TTS top snippet
-```
-
-Drag a spec PDF onto the panel:
-
-```
-panel             -> spec ingested. Title: ADIP Spec. 4 sections.
-                     First lines:
-                     - The system MUST register patients.
-                     - ...
-panel (via Claude)-> extraction: 1 requirement, 1 entity (Paciente),
-                     1 endpoint (POST /patients), 1 component
-                     (PatientCard).
-panel (via Claude)-> plan: src/models/Paciente.ts +
-                     src/api/patients.ts +
-                     src/components/PatientCard.tsx + README.md.
-                     Open question: authentication unspecified.
-user clicks       -> approve.
-scaffolder        -> 4 files written, rollback log captured.
-```
-
-If anything looks off: one `POST /api/forge/ingest/rollback` and
-the project is back to its prior state.
-
-### Architecture pointer
-
-The full step-by-step voice loop, reader pipeline, voiceprint
-state machine, and "how to add a parser / intent / trust class"
-recipes live in [docs/HITO_1_ARCHITECTURE.md](docs/HITO_1_ARCHITECTURE.md).
-
-## Why a separate product
-
-NAC (the spec) is Apache-2.0 free forever. The reference runtime
-`nac-spec` on npm is Apache-2.0 free forever. **Yujin Forge is the
-commercial build layer:**
-
-- The AI decorator (`--ai-silent` / `--ai-assisted`) burns Anthropic
-  tokens on your behalf; the seat license is what funds that.
-- The chat panel, React scaffolder, test corpus generator, and mock
-  generator are all license-gated.
-- The static-rule HTML walker (`--html`, `--assisted`) is open and
-  works offline.
-
-The Apache spec attracts the ecosystem; Forge monetises the delivery
-experience for teams that want to skip the per-app plumbing.
-
-## What Forge gives an app (under the hood)
-
-Every decorated output ships:
-
-1. `index.html` -- decorated, drop-in NAC3-ready
-2. `manifest.json` -- the NAC3 manifest, version-pinnable
-3. `nac.browser.js` -- the NAC3 runtime (copied locally, no CDN dep)
-4. `nac-bridge.js` -- ~50 lines, wires `NAC.bindAction` for every
-   action element so the host's existing handlers stay intact AND the
-   contract events fire
-5. **With `--with-pilot`:** `pilot.bundle.js` + `pilot.css` -- the
-   embedded chat + voice cockpit
-
-After running Forge, your app is ready to be driven by any LLM agent
-that understands NAC-3. Pilot is one such driver; the
-[600-run benchmark](https://yujin.app/nac-spec/benchmark/) was driven
-by a custom harness; the React SDK in
-[`@yujin/nac-react`](https://www.npmjs.com/package/nac-spec) is
-another.
-
-## Where this lives in the Yujin ecosystem
-
-```
-NAC (Apache-2.0)              -- pkuschnirof/rpaforce-crm + yujin.app/nac-spec
-  spec + reference runtime + nac-spec NPM package
-       |
-       | depends on
-       v
-Yujin Forge (closed core)     -- yujinapp/yujin-forge           (build NAC apps)
-  AI decorator, React scaffolder, license gating, this repo
-       |  sibling product
-       v
-Yujin Pilot (closed core)     -- yujinapp/yujin-pilot           (drive NAC apps)
-  Embedded chat + voice + multi-model cockpit
-       |
-       | downstream adopter
-       v
-Customer apps
-```
-
-## Documentation
-
-- [README.md](README.md) -- this file
-- [PROJECT.md](PROJECT.md) -- topology + governance + slice/HITO process (mandatory read before touching code)
-- [docs/SQ.md](docs/SQ.md) -- quality standards + deliverables + pre-development checklist (Spanish, mandatory)
-- [docs/QUICKSTART_ADIP.md](docs/QUICKSTART_ADIP.md) -- step-by-step setup guide for the ADIP institutional rollout (Spanish)
-- [docs/USAGE.md](docs/USAGE.md) -- every command + flag + worked examples
-- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) -- internals of the AI decorator + wiring + Pilot integration
-- [docs/HITO_1_ARCHITECTURE.md](docs/HITO_1_ARCHITECTURE.md) -- HITO 1 voice + reader + spec ingest reference
-- [docs/LANGUAGE_POLICY.md](docs/LANGUAGE_POLICY.md) -- the 10-canonical-languages rule + catalog-lint mechanism
-- [docs/manuals/manual.es.html](docs/manuals/manual.es.html) -- end-user manual (10 languages: es/en/pt/fr/ja/zh/hi/ar/de/it)
-- [docs/RECAP_CLAUDE_COSTS.md](docs/RECAP_CLAUDE_COSTS.md) -- cost model + lock mechanism for the Claude recap mode
-- [docs/ROADMAP_VOICE_FORGE_2026_05_23.md](docs/ROADMAP_VOICE_FORGE_2026_05_23.md) -- HITO 0/1/2/3 roadmap with decisions taken
-- [docs/TECHNICAL_MANUAL.md](docs/TECHNICAL_MANUAL.md) -- living manual updated at each slice close
-- [docs/SPEC.md](docs/SPEC.md) -- the contract Forge makes with adopting teams
-- [docs/COMMERCIAL_PLAN.md](docs/COMMERCIAL_PLAN.md) -- pricing + licensing model
-- [docs/SESSION_HANDOFF_2026_05_23_AT_DOCTOR.md](docs/SESSION_HANDOFF_2026_05_23_AT_DOCTOR.md) -- state at last session boundary
-
-## See also
-
-- [NAC spec](https://yujin.app/nac-spec/SPEC.html)
-- [NAC3 v2.3 benchmark](https://yujin.app/nac-spec/benchmark/) -- 600 runs across 5 models + 3 protocols
-- [Migration paper](https://yujin.app/nac-spec/migration/) -- Forge silent vs assisted vs Sumi manual on a calculator
-- [Yujin Pilot](https://github.com/yujinapp/yujin-pilot) -- the sibling driver product
-- [Yujin CRM](https://github.com/pkuschnirof/rpaforce-crm) -- the first adopter of the full stack
+# Yujin Forge
+
+**A voice-first NAC-3 development framework + build tool.** Forge
+gives a developer (or an institution like ADIP teaching kids to
+code) a single CLI + chat panel that covers the full app-creation
+loop: read design specs by voice, generate code scaffolds from
+those specs, decorate vanilla HTML into NAC-3, drive existing apps
+via voice + chat.
+
+> Status: **v1.0.51** (2026-06-28). Published on npm as
+> `@nac3/forge-cli` (tag `latest`). **100% manifest verb
+> coverage**: every one of the **119 declared NAC-3 verbs** has
+> at least one fake-scripted scenario asserting it gets invoked
+> (or refuses to) in the right intent. **56 top-level CLI
+> commands** (see the full list below). Brain matrix QA harness +
+> 8 helper CLIs under `yf qa`; ops docs (SECURITY, CONTRIBUTING,
+> TESTING_GUIDE, DEPLOYMENT, CI_PIPELINE); structural fixture
+> validator + pre-commit gate. The MCP bridge config + office.* +
+> a11y.* verbs shipped; brain federation (parent/child) shipped;
+> the agent orchestrator surface (`yf agent`) shipped; multi-agent
+> session orchestration (`yujin.session.*`, opt-in, default OFF)
+> shipped 2026-06-28.
+>
+> **HITO 0 -- credentials vault.** AES-256-GCM at-rest encryption
+> with machine fingerprint binding, atomic writes (0o600), one-shot
+> reveal, vault modal in chat panel. Slots: anthropic / openai /
+> google_voice / elevenlabs / github_token.
+>
+> **HITO 1 -- voice + reader + spec ingest.** Bidirectional voice
+> (Whisper + Google STT, ElevenLabs + Google TTS) with
+> chunked pipelined playback (~600 ms first audio on long sections).
+> Voiceprint enrolment + 5-layer trust model + liveness challenge on
+> irreversible ops. Document reader for **txt / md / source / html /
+> rtf / csv / epub / pdf / docx / xlsx** (10 formats) with voice-
+> driven navigation (open / next / search / bookmark / recap). Spec
+> drag-drop: drop a PDF/DOCX/etc into chat -> Forge parses ->
+> Claude extracts requirements/entities/endpoints/components ->
+> generates a file plan -> writes the scaffold after explicit
+> approval -> rollback on demand.
+>
+> **Fase F -- 10-language i18n + manuals.** Panel UI + voice intent
+> matcher + HTML user manuals all available in
+> **es / en / pt / fr / ja / zh / hi / ar / de / it**. Globe button
+> in the chat panel swaps the active language; the new
+> `forge.manual.open` tool routes "abrime el manual" / "open the
+> manual" / "マニュアルを開いて" / etc to the right HTML manual
+> served through the reader pipeline. Catalog-lint refuses to
+> publish if any locale is missing keys.
+>
+> Earlier work still shipping: G1 (AST migrator robustness) + G2
+> (LLM retry loop) + G3 (multi-page HTML) + G4 (--dry-run for ai
+> modes) + G5 (SPEC sync) + G6 (Figma scaffolder alpha) + the v0.3.0
+> chat tool-use loop (`forge.read_manifest`,
+> `forge.consult_nac_spec`, plus the V1.11..V1.13 github/git/
+> lifecycle tools and the V1.28 + V1.32 reader tools).
+>
+> **Full vitest suite green** (~3800 cases across ~350 suites,
+> Linux + macOS + Windows CI). AI decorator validated on calc
+> fixture (15/15 dispatch tasks OK) + Conduit-NAC3 (178/180
+> cross-lang at N=3).
+> See [yujin.app/nac-spec/migration/](https://yujin.app/nac-spec/migration/)
+> for the migration paper, `docs/HITO_1_ARCHITECTURE.md` for the
+> voice+reader internals, and `docs/EVOLUTION_PLAN.md` for what is
+> next.
+
+## What it is
+
+Four things in one:
+
+1. **An AI-powered NAC-3 decorator.** `yf migrate <dir> --ai-silent`
+   calls Claude Sonnet 4.6 with the HTML + JS source, gets back a
+   fully-decorated HTML + JSON manifest, post-processes the output to
+   bake in the NAC3 runtime + contract bridge + inline `NAC.register`.
+   Takes ~25 s and ~$0.05 per app.
+
+2. **A Pilot installer.** `yf pilot install <dir>` injects the
+   embedded chat + voice + multi-model bundle into any
+   Forge-decorated app. The same UI works against any NAC-3-compliant
+   page, regardless of how it was decorated.
+
+3. **A React/AST migration scaffold (planned).** `yf migrate
+   <existing-react-repo>` audits the codebase, proposes the migration
+   path screen-by-screen, executes the diff. The audit + apply flow
+   is in place; the React-specific AST migrator is in flight.
+
+4. **A voice-first developer assistant (HITO 1).** `yf chat`
+   launches a local panel with bidirectional voice, a 10-format
+   document reader, and drag-drop spec ingest. Drop a PDF / DOCX /
+   HTML spec into chat -> Forge extracts requirements via Claude ->
+   generates a file scaffold plan -> writes the project after you
+   approve. Reverse the scaffold with one click. Aimed at solo
+   developers + institutional teams (ADIP) who want the full
+   "read spec out loud, then write the code" cycle without leaving
+   the keyboard or the headset. See "Voice cockpit + spec ingest"
+   below.
+
+## Quick start
+
+```bash
+# Install
+npm install -g @nac3/forge-cli@latest
+
+# Guided first run: activates your license (auto-synced) + sets your
+# AI key (BYOK). One command, it walks you through the rest.
+yf onboard
+
+# Decorate a vanilla HTML app (one shot, no human input)
+yf migrate ./my-app --ai-silent --ai-out ./my-app-decorated
+
+# Same, but include Yujin Pilot (needs the separate Pilot bundle --
+# see "How Pilot works"; not shipped in this repo or the npm package)
+yf migrate ./my-app --ai-silent --with-pilot --ai-out ./my-app-decorated
+
+# Install Pilot into an already-decorated app (needs the Pilot bundle)
+yf pilot install ./my-app-decorated
+
+# Open it
+xdg-open ./my-app-decorated/index.html
+```
+
+The decorated output is **drop-in NAC3-ready**: no CDN dependencies
+at runtime, the manifest is registered inline at boot, every action
+button is wired through `NAC.bindAction`, the floating Pilot button
+appears bottom-right. Click it, paste an API key, and drive the page
+by voice or text.
+
+> NAC-3 version: Forge tracks NAC-3. The canonical version lives in
+> the `nac-spec` repo (stable v2.5, latest alpha.5 at the time of
+> writing); see [yujin.app/nac-spec/SPEC.html](https://yujin.app/nac-spec/SPEC.html)
+> for the exact current value.
+
+The chat-panel brain is BYOK and provider-agnostic. Forge wires
+these brain providers: **Anthropic, OpenAI, Google (Gemini),
+DeepSeek, xAI (Grok), Mistral, Cohere, Qwen (Alibaba DashScope),
+and Zhipu GLM (z.ai)** via their own API keys, plus a **local**
+brain via **Ollama** (or any OpenAI-compatible local server, no key
+required). Two virtual providers complete the set: `yujin_managed`
+(routes inference to the HITO 4 worker by plan/tier) and
+`federation` (routes to a remote parent Forge's brain). See
+`yf brain` + `yf federation`.
+
+## Commands
+
+Forge ships **56 top-level commands**. The core lifecycle:
+
+| Command | What it does |
+|---|---|
+| `yf new <slug>` | Bootstrap a new Yujin Forge React app from `templates/react-app/`. |
+| `yf migrate <repo>` | Audit (default) or apply a NAC-3 migration on a React or HTML project. See the migrate flags below. |
+| `yf pilot install <dir>` | Inject the Pilot bundle into an already-decorated NAC-3 app (separate bundle required -- see "How Pilot works"). |
+| `yf chat` | Launch the embedded voice+text panel hooked to the current project. |
+| `yf test` | Run the project test corpus. |
+| `yf ship` | Deploy gate: validate + license + tests + build -> `dist/`. |
+| `yf doctor` | Diagnose the local Forge install + license + vault + voice + reader deps. |
+| `yf validate [path]` | Statically check that a directory is a valid Yujin Forge project. |
+| `yf license` | Activate, inspect, or revoke a license. |
+| `yf onboard` | Guided first run: license (auto-synced) + BYOK key. |
+| `yf upgrade` | Self-update (npm-global in place, or point at the desktop installer). |
+
+`yf migrate` flags: `--apply` (React/AST), `--html` / `--assisted`
+(rule-based HTML walker, offline), `--ai-silent` / `--ai-assisted`
+(AI-powered decoration, paid seat), `--with-pilot` (also inject the
+Pilot bundle).
+
+The rest of the surface, by area:
+
+- **Brain + keys + cost:** `brain`, `keys`, `federation`, `limits`,
+  `vault`.
+- **Workflow + project state:** `workflow`, `pending`, `wiring`,
+  `projects`, `graph`, `triage`, `discover`, `clarify`, `spec`,
+  `approve`, `bootstrap`, `block`, `coverage`, `operate`, `legacy`.
+- **Voice + accessibility:** `voice`.
+- **NAC-3 + doctrine + MCP:** `manifest`, `nac3`, `doctrine`,
+  `doctrines`, `lessons`, `mcp`, `agent`.
+- **Testing + QA:** `gen-tests`, `gen-flow-tests`, `scenarios:emit`,
+  `review-screens`, `review-status`, `qa`, `test-agent`.
+- **Design + scaffolding:** `figma`.
+- **Deploy + ops + infra:** `deploy`, `tunnel`, `publish`, `repo`,
+  `app`, `support`, `log`, `provision-link`.
+- **Mobile:** `mobile`.
+
+Run `yf --help` for the authoritative list and
+[docs/USAGE.md](docs/USAGE.md) for every flag and worked examples.
+
+## How decoration works
+
+A vanilla HTML/JS app starts like:
+
+```html
+<button onclick="digit('7')">7</button>
+```
+
+After `yf migrate --ai-silent`:
+
+```html
+<body data-nac-plugin="calc">
+  ...
+  <button onclick="digit('7')"
+          data-nac-id="calc.action.digit_7"
+          data-nac-role="action"
+          data-nac-action="digit_7">7</button>
+  ...
+  <script src="nac.browser.js"></script>
+  <script src="calc.js"></script>
+  <script src="nac-bridge.js"></script>
+  <script>
+    (function () {
+      var manifest = { "plugin_slug": "calc", ... };
+      window.NAC.register(manifest);
+    })();
+  </script>
+</body>
+```
+
+Any LLM driver can now call:
+
+```js
+await NAC.click_by_verb('calc', 'digit_7');
+```
+
+and the host's existing `digit('7')` handler runs **plus** the
+`nac:action:succeeded` contract event fires (because `nac-bridge.js`
+re-wired the inline onclick via `NAC.bindAction`).
+
+## How Pilot works
+
+Pilot is a single-file IIFE bundle + companion stylesheet
+(`pilot.bundle.js` + `pilot.css`). `yf pilot install` (or
+`yf migrate --with-pilot`) copies both into the target directory and
+inserts the script tags before `</body>`.
+
+> **The Pilot bundle ships separately.** It is NOT included in this
+> repository nor in the published `@nac3/forge-cli` npm package. To
+> use `yf pilot install` / `yf migrate --with-pilot` you must supply
+> the bundle yourself. `yf pilot install` looks for it (in order) at:
+>
+> 1. `--source <dir>` (an explicit path you pass), then
+> 2. `../yujin-pilot/dist/` (a sibling checkout of the Pilot repo), then
+> 3. `node_modules/@yujin/pilot/dist/` (if `@yujin/pilot` is installed).
+>
+> If none contain `pilot.bundle.js`, the command stops with a clear
+> error listing exactly where it looked and how to point it at the
+> bundle. Obtain the bundle from the
+> [Yujin Pilot repo](https://github.com/yujinapp/yujin-pilot) (build
+> its `dist/`), or pass `--source` at a path that already has it.
+
+At runtime, Pilot mounts a floating sumi-e branch button at
+bottom-right. Click it: chat panel opens. Click again: switches to
+the "pizarra" mode (chat + voice + action trace). Configure: paste
+an API key for any supported provider. Each provider supports all the
+models the
+[NAC3 benchmark](https://yujin.app/nac-spec/benchmark/) exercised.
+
+Pilot reads `window.NAC.list_registered_plugins()` to get the active
+manifest, sends it to the selected LLM with the user's utterance,
+parses the JSON action chain, dispatches each via
+`NAC.click_by_verb`, reads back any configured status probe, then
+speaks the result via Web Speech / ElevenLabs / Google Cloud TTS.
+
+Config persists in `localStorage` under `yujin_pilot.config`. Keys
+never leave the browser. (Production deployments belong behind a
+server proxy.)
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the full
+internal architecture.
+
+## Voice cockpit + spec ingest (HITO 1)
+
+`yf chat` opens a local panel with three views (globito / mini /
+full). The full view has a chat stream on the left and a "pizarra"
+trace on the right that shows every tool the system invoked to
+answer.
+
+What it covers end-to-end:
+
+- **Vault** -- modal accessible via the Keys button. Slots for
+  `anthropic`, `openai`, `google_voice`, `elevenlabs`,
+  `github_token`. Values are encrypted at rest with the machine
+  fingerprint; shown once on entry, never again.
+
+- **Voice in / voice out.** Press the mic, speak; the panel
+  records via `MediaRecorder`, ships the audio to the configured
+  STT provider, and either dispatches a recognised reader command
+  directly or feeds the transcript to the chat loop. Replies are
+  spoken back via the configured TTS provider with chunked
+  prefetch (first audio in ~600 ms even on long answers).
+
+- **Voiceprint trust.** Enroll your voice once -- subsequent voice
+  commands are gated by a 5-layer trust model
+  (unknown / heard / recognised / trusted / authorised). Irreversible
+  actions (force push, branch delete, deploy) ALWAYS require a
+  liveness challenge regardless of trust level: a random Spanish/
+  English phrase plus a random number you have to read back.
+
+- **Document reader.** Open any file in the project root and
+  navigate by voice: "abrime el readme", "siguiente", "buscar
+  pricing", "marcame aqui como inicio", "volver a marca inicio",
+  "recap". Supports **10 formats**: txt, md, source code (.ts / .py
+  / .rs / 80+ extensions), HTML, RTF, CSV/TSV, EPUB, **PDF**
+  (via pdfjs-dist), **DOCX** (via mammoth), **XLSX** (via sheetjs).
+  All format detection happens automatically.
+
+- **Spec drag-drop.** Drag a spec file onto the chat panel; an
+  overlay appears + the file uploads. Forge parses it through the
+  same reader pipeline, then a Claude call extracts structured
+  requirements, entities, endpoints, and UI components. A second
+  Claude call turns the extraction into a concrete file scaffold
+  plan (which files to create + where + what kind + which
+  requirement each serves + open questions for clarification).
+  Nothing is written until you POST `{approve: true}`. On approve,
+  the scaffolder writes the planned files with hand-rolled
+  templates per kind (model / api / component / test / doc) and
+  records a rollback log -- one click undoes the whole scaffold.
+
+- **Reader recap modes.** Default `literal` mode joins recent
+  spoken blocks into a TTS-friendly narrative for "que dijiste".
+  Optional `summary` mode calls Claude for a 1-2 sentence
+  compression; gated by env var `YF_ENABLE_CLAUDE_RECAP=1` so it
+  cannot fire by accident and charge tokens. Cost model in
+  `docs/RECAP_CLAUDE_COSTS.md`.
+
+### ADIP voice-first demo loop
+
+```
+User: (mic) "abrime el plan.md"
+  -> reader.open    -> TTS "El Plan"
+User: (mic) "siguiente"
+  -> reader.next    -> TTS "Primer paso"
+User: (mic) "buscar pricing"
+  -> reader.search  -> TTS top snippet
+```
+
+Drag a spec PDF onto the panel:
+
+```
+panel             -> spec ingested. Title: ADIP Spec. 4 sections.
+                     First lines:
+                     - The system MUST register patients.
+                     - ...
+panel (via Claude)-> extraction: 1 requirement, 1 entity (Paciente),
+                     1 endpoint (POST /patients), 1 component
+                     (PatientCard).
+panel (via Claude)-> plan: src/models/Paciente.ts +
+                     src/api/patients.ts +
+                     src/components/PatientCard.tsx + README.md.
+                     Open question: authentication unspecified.
+user clicks       -> approve.
+scaffolder        -> 4 files written, rollback log captured.
+```
+
+If anything looks off: one `POST /api/forge/ingest/rollback` and
+the project is back to its prior state.
+
+### Architecture pointer
+
+The full step-by-step voice loop, reader pipeline, voiceprint
+state machine, and "how to add a parser / intent / trust class"
+recipes live in [docs/HITO_1_ARCHITECTURE.md](docs/HITO_1_ARCHITECTURE.md).
+
+## Multi-agent session orchestration (opt-in, default OFF)
+
+The single chat session can spawn **bounded headless sub-sessions**
+to do orthogonal, well-scoped work in parallel and collect the
+results over the coordination bridge. This is the `yujin.session.*`
+verb family (`spawn` / `collect` / `list` / `stop`).
+
+- **Default OFF.** The whole capability is gated by
+  `multiagent.enabled` in the limits config (Ajustes > Limites).
+  While off, the `yujin.session.*` verbs are hidden from the
+  manifest, the doctrine is not injected, and the handlers refuse.
+  Turn it on explicitly to use it.
+- **Orthogonal + parallel only.** A sub-session boots a whole
+  headless server and spends BYOK tokens, so it is reserved for
+  independent work (wide reads, research, analysis over a different
+  subsystem) that does not need the live conversation. The user
+  approves each spawn; set `budget_tokens` to bound the spend.
+- **Restricted child scope (enforced).** A sub-session can read /
+  search / write files in its project root, run safe shell, and
+  query the graph / pendings / reader. It CANNOT push / commit, do
+  destructive or irreversible actions, mutate workflow / pending /
+  keys, or spawn its own sub-sessions (no grandchildren). Anything
+  outward stays with the parent, where the user can approve it.
+
+Full rules: [docs/doctrine/session-orchestration.md](docs/doctrine/session-orchestration.md).
+
+## Why a separate product
+
+NAC (the spec) is Apache-2.0 free forever. The reference runtime
+`nac-spec` on npm is Apache-2.0 free forever. **Yujin Forge is the
+commercial build layer:**
+
+- The AI decorator (`--ai-silent` / `--ai-assisted`) burns Anthropic
+  tokens on your behalf; the seat license is what funds that.
+- The chat panel, React scaffolder, test corpus generator, and mock
+  generator are all license-gated.
+- The static-rule HTML walker (`--html`, `--assisted`) is open and
+  works offline.
+
+The Apache spec attracts the ecosystem; Forge monetises the delivery
+experience for teams that want to skip the per-app plumbing.
+
+## What Forge gives an app (under the hood)
+
+Every decorated output ships:
+
+1. `index.html` -- decorated, drop-in NAC3-ready
+2. `manifest.json` -- the NAC3 manifest, version-pinnable
+3. `nac.browser.js` -- the NAC3 runtime (copied locally, no CDN dep)
+4. `nac-bridge.js` -- ~50 lines, wires `NAC.bindAction` for every
+   action element so the host's existing handlers stay intact AND the
+   contract events fire
+5. **With `--with-pilot`:** `pilot.bundle.js` + `pilot.css` -- the
+   embedded chat + voice cockpit
+
+After running Forge, your app is ready to be driven by any LLM agent
+that understands NAC-3. Pilot is one such driver; the
+[600-run benchmark](https://yujin.app/nac-spec/benchmark/) was driven
+by a custom harness; the React SDK in
+[`@yujin/nac-react`](https://www.npmjs.com/package/nac-spec) is
+another.
+
+## Where this lives in the Yujin ecosystem
+
+```
+NAC (Apache-2.0)              -- pkuschnirof/rpaforce-crm + yujin.app/nac-spec
+  spec + reference runtime + nac-spec NPM package
+       |
+       | depends on
+       v
+Yujin Forge (closed core)     -- yujinapp/yujin-forge           (build NAC apps)
+  AI decorator, React scaffolder, license gating, this repo
+       |  sibling product
+       v
+Yujin Pilot (closed core)     -- yujinapp/yujin-pilot           (drive NAC apps)
+  Embedded chat + voice + multi-model cockpit
+       |
+       | downstream adopter
+       v
+Customer apps
+```
+
+## Documentation
+
+- [README.md](README.md) -- this file
+- [PROJECT.md](PROJECT.md) -- topology + governance + slice/HITO process (mandatory read before touching code)
+- [docs/SQ.md](docs/SQ.md) -- quality standards + deliverables + pre-development checklist (Spanish, mandatory)
+- [docs/QUICKSTART_ADIP.md](docs/QUICKSTART_ADIP.md) -- step-by-step setup guide for the ADIP institutional rollout (Spanish)
+- [docs/USAGE.md](docs/USAGE.md) -- every command + flag + worked examples
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) -- internals of the AI decorator + wiring + Pilot integration
+- [docs/HITO_1_ARCHITECTURE.md](docs/HITO_1_ARCHITECTURE.md) -- HITO 1 voice + reader + spec ingest reference
+- [docs/LANGUAGE_POLICY.md](docs/LANGUAGE_POLICY.md) -- the 10-canonical-languages rule + catalog-lint mechanism
+- [docs/manuals/manual.es.html](docs/manuals/manual.es.html) -- end-user manual (10 languages: es/en/pt/fr/ja/zh/hi/ar/de/it)
+- [docs/RECAP_CLAUDE_COSTS.md](docs/RECAP_CLAUDE_COSTS.md) -- cost model + lock mechanism for the Claude recap mode
+- [docs/ROADMAP_VOICE_FORGE_2026_05_23.md](docs/ROADMAP_VOICE_FORGE_2026_05_23.md) -- HITO 0/1/2/3 roadmap with decisions taken
+- [docs/TECHNICAL_MANUAL.md](docs/TECHNICAL_MANUAL.md) -- living manual updated at each slice close
+- [docs/SPEC.md](docs/SPEC.md) -- the contract Forge makes with adopting teams
+- [docs/COMMERCIAL_PLAN.md](docs/COMMERCIAL_PLAN.md) -- pricing + licensing model
+- [docs/SESSION_HANDOFF_2026_05_23_AT_DOCTOR.md](docs/SESSION_HANDOFF_2026_05_23_AT_DOCTOR.md) -- state at last session boundary
+
+## See also
+
+- [NAC spec](https://yujin.app/nac-spec/SPEC.html)
+- [NAC3 v2.3 benchmark](https://yujin.app/nac-spec/benchmark/) -- 600 runs across 5 models + 3 protocols
+- [Migration paper](https://yujin.app/nac-spec/migration/) -- Forge silent vs assisted vs Sumi manual on a calculator
+- [Yujin Pilot](https://github.com/yujinapp/yujin-pilot) -- the sibling driver product
+- [Yujin CRM](https://github.com/pkuschnirof/rpaforce-crm) -- the first adopter of the full stack