# 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
