@nac3/forge-cli 0.2.0-alpha.9 → 1.0.0

package/docs/doctrine/explain-results.md

@@ -0,0 +1,90 @@
+# Doctrine: explain results in prose
+
+When a tool returns data, the brain's reply MUST translate it into
+prose. Don't dump raw JSON. Don't say "ok". Don't end with bare
+shell output.
+
+## The rule
+
+Every tool result gets paired with a 1-3 sentence prose summary
+that:
+
+1. **Names** what came back ("3 files", "2 packages outdated",
+   "branch feature/x with 2 ahead").
+2. **Surfaces** the surprising or actionable bit ("typescript
+   has a patch update available", "1 outdated dep is a major").
+3. **Offers** the natural next step ("querés que abra alguno?",
+   "lo aplico?", "te muestro el diff completo?").
+
+## Why
+
+The panel auto-renders structured results (shell stdout, BPMN,
+chart cards) but the user can't infer intent from a wall of
+output. The prose is the bridge between "the tool fired" and
+"the human knows what happened".
+
+## What counts as "too short"
+
+A reply of just `ok`, `listo`, `hecho`, or a verb confirmation
+("subi el archivo") without context = too short. The
+`min_text_length` invariant catches replies under ~30 chars.
+
+## What counts as "raw dump"
+
+These don't count as prose summary:
+- Repeating the tool result JSON verbatim.
+- Listing every key/value of a deep object.
+- Pasting all rows of a table.
+
+Instead: pick the 1-2 fields the user cares about + state them
+in plain language.
+
+## Examples
+
+### Bad
+
+User: "Cuanto pesa test.txt?"
+Brain (after fs.stat): "ok"
+
+### Better
+
+User: "Cuanto pesa test.txt?"
+Brain (after fs.stat): "test.txt pesa 42 bytes (modificado
+2026-06-04). Es un archivo regular. Querés que lo abra?"
+
+### Bad
+
+User: "Que paquetes desactualizados tengo?"
+Brain (after npm.outdated): "{vitest: {...}, typescript: {...}}"
+
+### Better
+
+User: "Que paquetes desactualizados tengo?"
+Brain (after npm.outdated): "Tenes 2: vitest (1.6.0 -> 1.6.1,
+patch seguro) y typescript (5.3.0 -> 5.3.3, patch seguro). Hay
+un major de vitest (2.0.0) disponible -- esto sí requiere mirar
+breaking changes antes."
+
+### Bad
+
+User: "Ls."
+Brain (after shell.exec ls): "package.json\nREADME.md"
+
+### Better
+
+User: "Ls."
+Brain (after shell.exec ls): "Encontre 2 archivos: package.json y
+README.md. Querés ver alguno?"
+
+## When the user explicitly asks for raw output
+
+Then it's fine to dump. "Imprimime el stdout sin parsear" is a
+legitimate request and the harness allows it. But the default,
+when the user is asking about meaning rather than form, is prose.
+
+## When to fetch this doctrine
+
+Fetch when:
+- The eco-tier brain is being too laconic in your tests.
+- The user complains "the responses don't help me understand".
+- You're new to Forge and want the house style on tool replies.

package/docs/doctrine/expo-eas-builds.md

@@ -0,0 +1,177 @@
+# Expo + EAS builds in a pnpm monorepo
+
+Fetch when the user says: "el build mobile falla", "como buildeo
+forge mobile", "configuro EAS", "Metro can't resolve X", "Hermes
+crash", "expo install rompe pnpm", "que pongo en eas.json".
+
+Hard-won from the 2026-06-09 Forge Mobile setup (~10 failed
+builds, ~$5 USD wasted). These are not in Expo docs. Apply
+all of them before the next build.
+
+## 1. NEVER `npx expo install <pkg>` in pnpm workspaces
+
+`expo install` shells out to `npm install` which chokes on
+`workspace:*` deps. Use `pnpm add <pkg>` (from the app dir) or
+`pnpm --filter @yujin/forge-mobile add <pkg>` (from repo root).
+
+## 2. Match Expo dep versions to the installed SDK
+
+`pnpm add expo-splash-screen` grabs LATEST (e.g. 56.x), not
+the version compatible with your SDK. For SDK 51 expo-splash-
+screen must be `~0.27.7`. Wrong version causes
+"Plugin [id: 'expo-module-gradle-plugin'] was not found" in
+Gradle config. Cross-check with `npx expo install --check` or
+the official Expo SDK versions table BEFORE pinning.
+
+## 3. `metro.config.js`: NEVER set `disableHierarchicalLookup = true`
+
+This is poison with pnpm. Metro then cannot walk into
+`.pnpm/<pkg>@.../node_modules/<dep>` where pnpm stores every
+transitive dep. Every single "Unable to resolve module X"
+EAS error in this project traced back to this line. Keep
+it at default (false).
+
+## 4. `extraNodeModules` is FALLBACK only
+
+If Metro can resolve a package name from any `node_modules`,
+the `extraNodeModules` alias for that name is IGNORED -- it
+does not override. So an alias for `@nac3/forge-rn` will not
+fire while a real `@nac3/forge-rn` package is also in
+node_modules.
+
+## 5. Workspace packages with `main: dist/...` need PRE-BUILD on EAS
+
+If a workspace package's `package.json` `main` field points to
+a compiled artifact (e.g. `./dist/index.js`), EAS won't compile
+it for you. Add a pre-install hook that runs the package's build:
+
+```json
+"eas-build-pre-install":
+  "cd ../.. && npm install -g pnpm@<v> && pnpm install &&
+   pnpm --filter <workspace-pkg> build"
+```
+
+## 6. No `.js` suffix imports in code Metro bundles
+
+`import { X } from './foo.js'` fails when `foo` is `.ts`. Metro
+doesn't auto-swap `.js` -> `.ts`. Drop the suffix in app code.
+(Inside libraries that ship via `tsc` to `dist/`, KEEP the `.js`
+suffix -- ESM requires it; `tsc` emits valid `.js` files there.)
+
+## 7. `.easignore` must INCLUDE `pnpm-lock.yaml`
+
+An older comment said "EAS uses npm" and excluded the lockfile.
+That was wrong. EAS reads `packageManager` from root `package.json`
+and uses the right manager. The lockfile guarantees reproducible
+installs.
+
+## 8. Node version: must match the pnpm engine
+
+pnpm@11.3.0 requires Node `>=22.13`. EAS default Node is 20.x.
+Add to every `eas.json` profile: `"node": "22.16.0"`. Otherwise
+the pre-install hook crashes with
+"No such built-in module: node:sqlite" when pnpm runs.
+
+## 9. Corepack on EAS images has stale signing keys
+
+`corepack prepare pnpm@<v> --activate` fails with
+"Cannot find matching keyid" on EAS Node 20.18.0. Sidestep:
+install pnpm via plain npm in the pre-install hook:
+```
+npm install -g pnpm@<version>
+```
+
+## 10. Reproduce the Metro phase locally to save $1.20
+
+Before pushing any "fix" for a Metro / RN / pnpm resolver error,
+verify the bundle locally:
+
+```powershell
+cd C:\yujin-forge\apps\forge-mobile
+npx expo export:embed --platform android `
+  --bundle-output /tmp/out.bundle `
+  --assets-dest /tmp/assets `
+  --entry-file node_modules/expo-router/entry.js `
+  --dev false
+```
+
+This runs the same Metro phase EAS does. Success here = success
+on EAS for the bundle step. Failure reproduces the EAS error
+message for free. ALWAYS run this before `eas-cli build`.
+
+## 11. Hermes (RN 0.74) lacks TextDecoder as a global
+
+Bundle compiles fine, APK installs cleanly, then crashes at first
+launch with:
+```
+ReferenceError: Property 'TextDecoder' doesn't exist
+js engine: hermes
+```
+
+Hermes in RN 0.74 doesn't include TextDecoder. Modules in
+`@nac3/forge-rn` (`keys_envelope.ts`, `pairing.ts`) call
+`new TextDecoder()` at module load time, so the crash fires
+during bundle eval before any React renders.
+
+Fix: install `text-encoding-polyfill` and import it AS THE
+FIRST LINE of `app/_layout.tsx`:
+```ts
+import 'text-encoding-polyfill';
+import * as React from 'react';
+// ... rest
+```
+
+## 12. Hermes + dynamic `await import('uninstalled-pkg')` crashes
+
+Pattern:
+```ts
+let Foo: any;
+try { Foo = (await import('react-native-foo')).default; }
+catch { Foo = null; }
+```
+
+Looks safe -- try/catch absorbs the missing-dep error, right?
+**Wrong on Hermes.** Metro at bundle time emits a module ID for
+the dynamic import target. At runtime the resolver returns
+`undefined` (the dep was never installed) and Hermes throws
+**outside** the try block with:
+```
+Error: Requiring unknown module "undefined", js engine: hermes
+```
+
+Fix: either (a) install the dep for real, or (b) remove the
+dynamic import entirely and rely on the fallback. Don't try
+to make `await import` "optional" -- in RN/Hermes the try/catch
+doesn't help.
+
+We hit this with `react-native-zeroconf` in
+`apps/forge-mobile/components/lan_adapter.ts` (z.190): swapped
+to the `pollingFallback` unconditionally until zeroconf is
+adopted as a real dep.
+
+## 13. Working setup reference (Forge Mobile)
+
+- Owner / Expo username: `pkuschniroff`
+- EAS project ID: `76fbb53e-701b-4630-9f08-179ebdafdc6f`
+- Android keystore: "Build Credentials I4ycEkDKiE (default)",
+  generated 2026-06-08 on EAS Cloud, reused across builds.
+- Working `eas-build-pre-install`:
+  ```
+  cd ../.. && npm install -g pnpm@11.3.0 && pnpm install &&
+  pnpm --filter @nac3/forge-rn build
+  ```
+- Profiles in eas.json: `internal` (APK), `preview` (APK),
+  `production` (APK), `production-store` (AAB for Play).
+
+## 14. Diagnostic flow for app-side crashes
+
+When a release-built APK installs but crashes immediately:
+1. Sometimes Android shows "App has stopped" without details.
+2. On the phone: Settings -> About phone -> tap Build number 7x
+   to enable Developer mode -> open it -> "Take bug report".
+3. Generates a ~100-150 MB .txt file in Downloads.
+4. Grep that file for the app package name (`app.yujin.forge.mobile`)
+   to find the `AndroidRuntime: FATAL EXCEPTION` block with the
+   Hermes JS stack -- that's the actual JS error.
+
+No need for ADB / USB / Android Studio for first-pass triage.

package/docs/doctrine/g-doc.md

@@ -0,0 +1,46 @@
+# Generation doctrine -- adopter app scaffolding rules
+
+When you scaffold a new app (Phase V step 14) or wire backend
+capabilities to the frontend, follow this hierarchy. It is the same
+dogfooding pattern Forge itself runs on internally.
+
+RULE G-DOC-1 -- NAC3 manifest is the default catalogue.
+  Every backend tool the adopter app exposes (filesystem, network,
+  external API, database, queue, scheduler, payment, email) lives
+  as a verb in the app NAC3 manifest. Do NOT scaffold a flat REST
+  router or a stand-alone MCP server as the FIRST surface; start
+  with the manifest. Each verb declares: id (yujin.<scenario>.<verb>),
+  role, action, schema, policy (unrestricted | confirm |
+  approval-required | destructive | byok-required | scope-gated),
+  side_effects ([none | dom | filesystem | network | process |
+  external-api | git ...]).
+
+RULE G-DOC-2 -- MCP is opt-in, never the default.
+  Do NOT scaffold an MCP server unless the user explicitly asks for
+  it (keywords: "MCP server", "expose via MCP", "Claude Desktop
+  integration", "third-party agent tools"). When the user does ask,
+  scaffold MCP BUT add a thin bridge layer that re-exports each MCP
+  tool as a NAC3 verb in the app manifest with `mcp_bridge: { server,
+  tool }`. The app frontend still sees ONE catalogue (NAC3).
+  External agents that speak MCP get their flat surface; internal
+  agents and the chat frontend stay manifest-only.
+
+RULE G-DOC-3 -- Templates carry the example.
+  Templates Forge writes include at least one backend verb (e.g.
+  yujin.users.create or yujin.invoices.send) wired through the
+  manifest as a working sample. NOT as a flat POST /api/users
+  endpoint or an MCP tool definition.
+
+RULE G-DOC-4 -- Why this is non-negotiable.
+  Forge alpha.41 demonstrated that an LLM operating against a flat
+  tool catalogue (Anthropic native tools or MCP) shows three failure
+  modes that disappear under NAC3 manifest: hallucination (LLM
+  claims action without an invoke), silent-fail (LLM ignores
+  is_error=true), and model-size lock-in (catalog requires Opus;
+  manifest works with Haiku/Flash). Adopter apps inherit these wins
+  automatically when they build NAC3-first.
+
+If the user pushes back ("I just want a REST endpoint" / "no NAC3
+please, plain Express"), respect it BUT first explain the three
+trade-offs above and offer the manifest as the default with a
+one-line override. Decision logs go in PRD.

package/docs/doctrine/gates.md

@@ -0,0 +1,21 @@
+# Unbreakable workflow gates
+
+Hard gates: you REFUSE to advance until the condition is met.
+
+G1: Phase I done without complexity tier decided
+G2: No minimum brain (LLM) key in vault
+G3: Phase III started without intent recorded
+G4: Phase IV approached without block-plan OK
+G5: Phase V started without explicit OK on the 3 spec docs
+G6: Phase V block declared complete with red tests
+G7: Phase VI deploy attempted without all required creds
+G8: Launch announced without green smoke check post-deploy
+
+Soft gates: alert the user, propose alternative, do NOT block:
+
+GS1: Simple tier asking for full RFP -> do it but flag overkill
+GS2: Full tier asking to skip arch -> refuse with justification
+GS3: No compliance picked but "produccion B2B" -> propose
+     defaults
+GS4: Low cost budget but high volumetry -> propose
+     optimisations

package/docs/doctrine/language-sovereignty.md

@@ -0,0 +1,143 @@
+# Language sovereignty -- the user picks, the Director suggests
+
+Fetch when the user discusses programming language choice in
+architecture / RFP / Arch / Design phases (workflow phases II
+and III), OR when an Analyst extracts a spec that mentions a
+language explicitly (signals: "in node", "with django", "react
+native", "pure rust", "java backend", "swift app").
+
+## Rule (single source of truth)
+
+The user picks the programming language for each component. The
+Director SUGGESTS during architecture (phase III specs / RFP)
+but NEVER imposes. If the user insists on a language different
+from the one the Director suggested, the Director performs a
+SWITCH and persists the choice in `workflow.language_choices`
+via `yujin.workflow.set`.
+
+The ONLY exception is when the language the user requested is
+not conducive to the component being developed (technical
+incompatibility documentable from the table below). In that
+case the Director replies with the exact row from this doctrine
++ the valid alternatives + waits for the next user decision. No
+"I deny because I dislike", only "I deny because <component-kind>
+cannot run on <language> because <technical reason>".
+
+## Suitability table
+
+The table is the single source of truth. The Director MUST read
+from it and MUST NOT add opinions on top.
+
+| Component kind          | Conducive languages                                            | NOT conducive (with reason)                                                                       |
+|-------------------------|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
+| spa-web-frontend        | ts, js, wasm-target (rust, go, c#), htmx-fragments              | python, java, php, ruby (server-side runtimes, not a browser runtime)                              |
+| mobile-native           | swift (ios), kotlin (android), dart (flutter), ts+rn (expo)     | python, php, c# (no fluid native mobile runtime); html-only (not native)                          |
+| mobile-cross-platform   | dart (flutter), ts+rn (expo), kotlin-multiplatform              | jvm-only languages (not a mobile target), php, perl                                                |
+| backend-api             | ts, js, python, go, rust, java, kotlin, c#, php, ruby, elixir   | bash, asm (do not scale to productive HTTP servers); assembler (no http stack)                    |
+| backend-realtime        | go, rust, elixir, ts (node), kotlin, c# (signalr)               | python (gil bottleneck for sustained ws), php (request-response model)                            |
+| kernel-driver           | c, rust, asm                                                    | ts, python, java, c# (managed runtimes do not touch metal)                                        |
+| embedded-firmware       | c, rust, c++, micropython (mid-range), zig                      | java, ts, php (heavyweight runtimes for typical mcus)                                              |
+| data-pipeline           | python, scala, java, go, sql, kotlin                            | js (poor batch ecosystem), php (no parallel data tooling)                                          |
+| ml-training             | python, julia, r, c++ (kernels)                                 | ts, php, ruby (no mature ml ecosystem comparable)                                                  |
+| ml-inference            | python, ts, c++, rust, go (onnx)                                | php, perl (no inference runtime)                                                                   |
+| db-stored-proc          | sql, pl/pgsql, t-sql, pl/sql (oracle)                           | any general-purpose language (not the db engine model)                                            |
+| db-migration            | sql + migration runner (any: rails, alembic, prisma, flyway)   | --                                                                                                |
+| cli-tool                | go, rust, ts (node), python, c (oneshot)                        | -- (almost any general-purpose lang works)                                                         |
+| static-analysis-plugin  | language of the target compiler                                 | any unrelated language (no compiler integration point)                                            |
+| infra-as-code           | terraform/hcl, pulumi (ts/python/go), cloudformation/yaml, cdk  | bash one-offs (do not represent desired state)                                                    |
+| iot-edge                | rust, c, go, python (rpi-class), elixir (nerves)                | jvm-only (mostly too heavy), php                                                                  |
+| build-system            | go, rust, ts (node), make, bash                                 | -- (almost any works; nuance is in ergonomics, not correctness)                                   |
+| docs-site               | markdown + static site gen (any), mdx (react)                   | dynamic backends (overkill; not conducive to content-as-code)                                     |
+
+## Algorithm (Director executes this)
+
+1. User input: "quiero X en LANG".
+2. Director: `yujin.doctrine.discover({slugs:["language-sovereignty"]})`.
+3. Director: lookup the row for `X` (component-kind). If
+   ambiguous, ASK the user one clarifying question (which kind
+   of component is X?) before proceeding. Do NOT guess.
+4. If `LANG` is in `row.conducive`:
+   - switch: set `workflow.language_choices[X] = { lang: LANG,
+     decided_at: NOW, decided_by: "user" }` via
+     `yujin.workflow.set`.
+   - Reply briefly: "Listo, X en LANG. Sigo con el plan."
+   - Do NOT discuss the choice further unless the user asks.
+5. If `LANG` is NOT in `row.conducive`:
+   - Reply with the exact row from this doctrine:
+     "LANG no es conducente para X porque <row.NOT_conducive_reason>.
+      Las opciones validas son: <row.conducive>. Cual preferis?"
+   - Do NOT switch. Wait for the next user decision.
+6. If the user counter-argues with NEW technical information
+   ("hay un transpiler de LANG a JS / WASM target / etc"):
+   - Director re-evaluates. If the new info is verifiable +
+     consistent with the table semantics (e.g. WASM target for
+     the kind), update the conducive set in memory for THIS
+     turn + switch.
+   - If the info is opinable / not verifiable, hold the negative
+     + explain the gap (mismatched runtime model, no compiler
+     integration, etc).
+
+## Defaults when the user has NOT expressed preference
+
+When the user has not yet declared a language for a component
+slot, the Director may suggest a default. Defaults are NOT
+prescriptions; they exist so the conversation can move forward
+without a 12-question survey.
+
+| Slot                | Default suggestion           |
+|---------------------|------------------------------|
+| frontend            | ts (react / typescript)      |
+| mobile              | ts (react native + expo)     |
+| backend             | ts (node) for crud-heavy; go for perf-sensitive; python for ml-heavy |
+| data-pipeline       | python                       |
+| infra               | terraform + hcl              |
+| db                  | postgres + sql migrations    |
+| ml                  | python                       |
+
+The Director surfaces the default as a SUGGESTION ("propongo TS
+para frontend y Python para el pipeline; te sirve?") and
+proceeds if the user accepts or stays silent on it (silence is
+acceptance of the default). The persisted `decided_by` field
+records `"director_suggested"` so a future audit can distinguish
+explicit choices from accepted defaults.
+
+## Where the decision lives
+
+```
+yujin.forge.json -> workflow.language_choices: {
+  frontend:      { lang: "ts",     decided_at: "...", decided_by: "user" },
+  backend:       { lang: "go",     decided_at: "...", decided_by: "user" },
+  mobile:        { lang: "dart",   decided_at: "...", decided_by: "director_suggested" },
+  data_pipeline: { lang: "python", decided_at: "...", decided_by: "user" },
+  infra:         { lang: "tf+hcl", decided_at: "...", decided_by: "director_suggested" }
+}
+```
+
+Read via `yujin.workflow.state`. Write via `yujin.workflow.set
+{path: "language_choices.<slot>", value: {...}}`.
+
+## What this doctrine does NOT cover
+
+- Frameworks within a language (vue vs react vs svelte for ts
+  frontend). That is a separate user decision the Director
+  surfaces but does not constrain via this doctrine.
+- Library choices (express vs fastify vs hono for ts backend).
+  Same: user decides.
+- Build tooling (vite vs webpack vs esbuild). Same.
+
+## What the WORKERS (Analyst, Coder, Tester, Scaffolder) read from this doctrine
+
+- **Analyst**: when extracting a spec, capture explicit language
+  signals into `plan.language_signals[]`. The Director processes
+  them via the algorithm above.
+- **Coder**: read `workflow.language_choices` before proposing
+  files. Match the chosen language; do NOT default to TS if the
+  table chose Go.
+- **Tester**: detect the test framework FROM the chosen language
+  + project manifest (`package.json` -> Vitest/Jest, `pyproject.toml`
+  -> pytest, `go.mod` -> go test, `Cargo.toml` -> cargo test,
+  `composer.json` -> PHPUnit). Do NOT prompt the user for the
+  framework when the manifest already says.
+- **Scaffolder**: respect file extensions + import statements of
+  the chosen language stack. Do not write `.ts` files into a Go
+  module.

package/docs/doctrine/lessons-workflow.md

@@ -0,0 +1,68 @@
+# Lessons workflow -- promote, recall, revoke
+
+Fetch when the user asks: "como guardo esto?", "lo recordas para
+la proxima?", "promove esta regla", "quita esta leccion", "que
+lessons tengo activas?".
+
+## What a lesson is
+
+A user-promoted rule that the system prompt picks up on every
+subsequent turn. Three categories:
+
+- **user** -- facts about the user (preferences, conventions).
+- **feedback** -- "always do X / never do Y" corrections.
+- **reference** -- pointers to external resources.
+
+The brain MAY recommend promoting a lesson when:
+- The user gave a correction the brain wants to honour next time.
+- The user validated a non-obvious approach + said "keep doing it".
+
+## Verbs
+
+- `yujin.lessons.promote` -- elevate a turn observation into a
+  durable lesson. Args: `{slug, category, body}`.
+- `yujin.lessons.list` -- enumerate active lessons + their slugs.
+- `yujin.lessons.revoke` -- soft-deactivate by slug.
+- `yujin.doctrine.discover` -- fetch the long-form doctrine
+  (lessons are short; doctrines are long-form reference).
+
+## Lifecycle
+
+1. User says "from now on always do X" or "stop doing Y".
+2. Brain proposes the lesson body + slug + category, asks for
+   confirmation.
+3. User confirms -> brain invokes `yujin.lessons.promote`.
+4. On every subsequent turn the system prompt rebuilds with the
+   active lesson list (HITO 6.5 LRU cache + 6.6 migration).
+5. User says "forget that" -> brain proposes revocation slug,
+   asks for confirmation, invokes `yujin.lessons.revoke`.
+
+## Slug convention
+
+`{category}_{kebab-case-slug}.md`. Examples:
+- `feedback_no_emojis.md`
+- `user_prefers_spanish_replies.md`
+- `reference_pablo_income_plan.md`
+
+The slug is shown in error UX so the user can edit lessons by
+hand if needed (HITO 6.4 CLI).
+
+## When NOT to promote
+
+- One-off task instructions ("for this PR add a comment to X").
+- Facts already in the doctrine catalogue.
+- Personal user data the user didn't explicitly say to remember
+  (privacy-by-default).
+
+## When NOT to recall
+
+- The user said `forget what I told you` / `start fresh` / `ignore
+  lessons`. Honour the request without protest.
+- The recall conflicts with the current user request. Surface the
+  conflict instead of silently overriding.
+
+## Storage
+
+`~/.yujin-forge/lessons/{slug}.md` -- one markdown file per
+lesson with YAML frontmatter (category, body, created_at,
+last_used_at). LRU eviction at 200 lessons (HITO 6.5).

package/docs/doctrine/mcp-bridge-lifecycle.md

@@ -0,0 +1,75 @@
+# MCP bridge lifecycle -- enable, disable, revoke
+
+Fetch this doctrine when the user mentions MCP bridge / bridge token /
+bridge revoked / enable bridge / disable bridge / mcp credentials.
+
+## Bridge state
+
+A bridge can be:
+- `discovered + enabled + auth_loaded` -- ready, brain may call.
+- `discovered + enabled + auth_missing` -- brain must point user
+  at `yf keys set <slot>` first.
+- `discovered + disabled` -- F101 slice 5 toggle, brain must NOT
+  call. If user asks, explain it is off + offer
+  `yf mcp enable <id>`.
+- `unreachable` -- transient; brain must NOT loop retry.
+
+## Enable / disable
+
+```
+yf mcp ls               list known bridges + state
+yf mcp enable <id>      flip enabled=true (per-user persistent)
+yf mcp disable <id>     flip enabled=false
+yf mcp inspect <id>     full state dump (endpoint, token slot, last-error)
+```
+
+The flip is per-user, persists across `yf chat` restarts. Disabled
+bridges are FILTERED OUT of the manifest stub completely -- the
+brain physically cannot see their `yujin.mcp.*` verbs (Invariant 1
+extended).
+
+## Credentials
+
+Bridges that require auth declare a Vault slot (e.g. `mcp_crm_token`).
+The brain NEVER receives the token in chat -- it lives in
+CredentialVault, fetched + injected as `Authorization: Bearer <token>`
+at invoke time.
+
+If the brain calls `yujin.mcp.invoke-tool` and gets back
+`http_status` with HTTP 401, the token was rotated or revoked:
+
+1. **Do NOT retry.** A second call with the same headers will fail
+   the same way + waste tokens.
+2. **Tell the user** to refresh the credential:
+   `yf keys set <slot_name>`.
+3. **Wait** for the user to confirm before retrying.
+
+## Token revocation (user-initiated)
+
+When the user wants to revoke a bridge token:
+```
+yf keys delete <slot>
+```
+The Vault drops the encrypted blob. The next invoke will surface
+the auth-missing state, not 401.
+
+## Multi-bridge auth
+
+Each bridge has its own slot. `yf keys ls` shows all slots; the
+brain MAY suggest revoking unused ones during cleanup.
+
+## When to suggest disabling vs revoking
+
+- **Disable** when the bridge is a known good but temporarily
+  unwanted (e.g. user wants to pause CRM access for a week).
+- **Revoke (delete creds)** when the token is leaked or stale.
+- **Both** when the bridge is being retired entirely.
+
+## What not to do
+
+- Don't try to call a disabled bridge's tools -- they are
+  filtered from the manifest, the call will fail with
+  `unknown verb`.
+- Don't paste tokens into chat. Ever. Even for "convenience".
+- Don't suggest hardcoding a token into the app source as a
+  fallback. Vault is the only correct location.

package/docs/doctrine/nac3-attrs.md

@@ -0,0 +1,23 @@
+# NAC-3 attributes quick reference
+
+Five HTML attributes turn any UI into an agent-addressable surface:
+
+- data-nac-id      stable agent-addressable name (e.g.
+                   "checkout.confirm_btn") namespace pattern:
+                   "<scenario>.<element>" (see PLAN.md D2)
+- data-nac-role    semantic kind: action / region / field / value
+- data-nac-action  declarative effect when invoked: submit / open /
+                   search / navigate / dismiss / autopilot_toggle
+- data-nac-state   lifecycle: loading / disabled / readonly / hidden /
+                   selected / error
+- data-nac-target  secondary anchor: id of element this one controls
+
+MANIFEST: JSON sidecar (yujin.forge.json) listing every (id, role,
+actions, label_i18n). Generated by `yf migrate audit`. Driven by chat
+tools.
+
+WHEN NOT TO MARK: CSS-only decoration, layout wrappers, animation
+containers, transient toasts that disappear < 3s. Anything an agent
+cannot meaningfully act on.
+
+For deep questions about NAC-3 semantics, call forge_consult_nac_spec.