@nac3/forge-cli 0.2.0-alpha.5 → 0.2.0-alpha.59z.118

package/dist/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/dist/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.

package/dist/docs/doctrine/office-tools.md

@@ -0,0 +1,102 @@
+# office.* verbs (F106) -- when + how
+
+The `office.*` namespace gives the brain four cross-platform native
+verbs for Excel + Word IO. They are NOT visible in the lazy manifest
+stub (slice 1) -- the brain fetches THIS doctrine via
+`yujin.doctrine.discover` when the user mentions Excel / Word / .xlsx
+/ .docx / spreadsheet / hoja / planilla / Word document.
+
+## Catalog
+
+| Verb | Use when | Policy |
+|---|---|---|
+| `office.excel.read`  | User wants to peek into or compute over an .xlsx / .xls / .csv | project-root-gated |
+| `office.excel.write` | User wants a fresh workbook (new file). Refuses to overwrite by default | approval-required |
+| `office.word.read`   | User wants text + heading outline from a .docx                  | project-root-gated |
+| `office.word.write`  | User wants a fresh .docx (new file). Refuses to overwrite by default | approval-required |
+
+## Args -- quick reference
+
+```
+office.excel.read   {path, sheet?, range?, header_row?}
+office.excel.write  {path, sheet?, rows[<obj|arr>], overwrite?}
+office.word.read    {path, include_outline?}
+office.word.write   {path, sections:[{kind:'heading'|'paragraph', level?, text}], overwrite?}
+```
+
+## Picking the right verb
+
+The brain MUST NOT use `yujin.fs.read-file` for .xlsx / .xls / .docx
+-- they are binary, the file content will look like noise + waste
+tokens. Always pick `office.excel.read` or `office.word.read`.
+
+The brain MUST NOT shell out to `python -c "import openpyxl..."` or
+similar. The verbs are cross-platform; no shell needed.
+
+## Excel patterns
+
+- **Read with header row (default):**
+  `office.excel.read({path:'data/x.xlsx'})` returns
+  `rows: [{col_a: 1, col_b: 2}, ...]`.
+- **Read raw cells (no header):**
+  `office.excel.read({path, header_row: false})` returns
+  `rows: [['col_a','col_b'], [1,2], ...]`.
+- **Specific sheet + range:**
+  `office.excel.read({path, sheet: 'Q1', range: 'A1:D50'})`.
+- **Write from objects:**
+  `office.excel.write({path:'out.xlsx', rows:[{name:'Ana', age:30}]})`.
+- **Write raw cells:**
+  `office.excel.write({path:'out.xlsx', rows:[['a','b'],[1,2]]})`.
+- **Overwrite existing file:**
+  pass `overwrite: true`. Refuses by default to avoid accidental
+  destruction.
+- **Output format:**
+  driven by extension. `.xlsx` -> xlsx, `.csv` -> csv, `.xls` -> biff8.
+
+## Word patterns
+
+- **Read text:**
+  `office.word.read({path:'docs/notes.docx'})` returns `text +
+  outline` (best-effort heading list).
+- **Outline-only mode:**
+  the outline is best-effort -- mammoth may miss some heading
+  styles. If empty, do not assume the doc has no headings.
+- **Write a structured doc:**
+  ```
+  office.word.write({
+    path: 'docs/notes.docx',
+    sections: [
+      { kind: 'heading',   level: 1, text: 'Title' },
+      { kind: 'paragraph', text: 'Intro paragraph.' },
+      { kind: 'heading',   level: 2, text: 'Section A' },
+      { kind: 'paragraph', text: 'Body.' },
+    ]
+  })
+  ```
+- **Only .docx output.** The verb refuses `.doc` (legacy binary
+  format -- not in the cross-platform path).
+- **Refuses overwrite by default.** Use `overwrite: true` for
+  destructive writes.
+
+## Hard caps
+
+- Read: 16 MB file size.
+- Excel write: 1,000,000 rows; 1024 fields per row.
+- Word write: 50,000 sections; 100,000 chars per section text.
+
+## Don't
+
+- Don't read .xlsx via `yujin.fs.read-file` (binary garbage).
+- Don't shell out to python/openpyxl/docx (cross-platform path
+  already covers it).
+- Don't claim "written" without invoking `office.*.write` first.
+- Don't overwrite without confirming or passing `overwrite: true`.
+
+## Do
+
+- Use `office.excel.read` -> pizarron tab for tabular data >10 rows.
+  Chat-pasting Excel rows is noisy.
+- Use `office.word.read` -> chat summary + pizarron full text if
+  the doc is long.
+- Pair `office.*.write` with R8 modal (policy=approval-required;
+  user confirms before disk write).

package/dist/docs/doctrine/pizarron.md

@@ -0,0 +1,52 @@
+# Pizarron doctrine -- full reference
+
+The panel has TWO zones with distinct responsibilities:
+  1. Chat (left)  -> conversational dialog ONLY, 1-3 sentences,
+     what gets READ aloud.
+  2. Pizarron (right) -> structured content, NOT auto-read.
+
+TWO PIZARRON VERBS, DIFFERENT MEANINGS:
+
+  yujin.pizarron.create-tab -- show AD-HOC content YOU generated
+    (table, code you wrote, doc, BPMN). Side effects: dom ONLY.
+    NO file_path. The pizarron is A CANVAS, NOT a file editor.
+
+  yujin.pizarron.open-file -- READ a project file from disk AND
+    open it as an EDITOR tab. Side effects: filesystem + dom.
+    When you invoke this, the server reads the file and the
+    pizarron renders the tab in edit mode. Opening does NOT
+    persist changes -- to save you must call
+    yujin.fs.write-project-file with the new content.
+
+RULE -- "leeme" / "leemelo" / "lee la tabla":
+  If the user asks to read aloud something ALREADY in the
+  pizarron (refs: "la tabla", "el codigo", "la pestana", "esto",
+  "lo que pusiste"), invoke yujin.pizarron.read-tab. Do NOT use
+  yujin.reader.open -- that is for opening a NEW file from disk
+  into the document reader, NOT for TTS of a pizarron tab.
+  Confusing the two means the reading never happens.
+
+CRITICAL RULE -- "abrir en pizarra" NEVER means "saved":
+  If the user says "edita aaa.txt with content X and commit",
+  you CANNOT respond "I opened the file, save it with Ctrl+S and
+  I will commit later". That sequence has 3 actions:
+    (a) open (yujin.pizarron.open-file),
+    (b) write the new content (yujin.fs.write-project-file),
+    (c) commit (yujin.git.commit).
+  You have all 3 verbs. Do them in order -- do NOT ask the user
+  to do (b) for you. The pizarron is a view, NOT storage.
+
+R7 -- HONEST SEQUENCING (anti-hallucination cont.):
+  If the user asks for a sequence of N actions and you only have
+  verbs for K (K < N), SAY SO BEFORE starting. No "step 1 done,
+  now proceeding with step 2" when step 2 has no manifest verb.
+  Example of the bug this rule prevents:
+    User: "edit me X and commit it".
+    BAD: invoke create-tab + reply "save it with Ctrl+S and then
+         I commit" (non-existent intermediate step + commit
+         promise you cannot keep).
+    GOOD: invoke yujin.pizarron.open-file (read disk), then
+          yujin.fs.write-project-file (write the new content),
+          then yujin.git.commit. Three chained invokes. Your chat
+          reply summarises the 3 actions AFTER all 3 returned
+          result_ok=true.

package/dist/docs/doctrine/r8-modal.md

@@ -0,0 +1,60 @@
+# R8 -- the modal IS the question (full doctrine + examples)
+
+For ANY verb with policy="destructive" or "approval-required"
+(yujin.git.commit, yujin.git.push, yujin.fs.write-project-file,
+yujin.lifecycle.*, yujin.github.clone-repo, etc), the panel
+OPENS A NATIVE MODAL with the concrete args and three buttons
+(Approve / Reject / Cancel). THE MODAL IS THE QUESTION. Do NOT
+repeat it in chat.
+
+CORRECT PROTOCOL:
+  1. Build the args carefully (which files, which message, which
+     remote/branch). If you need to inspect state first
+     (e.g. branch-status to know what is dirty), do THAT query
+     first -- it is read-only.
+  2. ONE short summary sentence: "I will git commit with message
+     X including only aaa.txt." Do NOT add "Confirms?" /
+     "Respond yes or no" / "Let me know when you approve" --
+     that is the trap that triggers the bug.
+  3. Invoke the verb with nac3_invoke. The dispatcher returns
+     {nac3_panel_approval_required: true, trace_id, verb, args}.
+     The panel opens the modal automatically.
+  4. WAIT. Do NOT ask for confirmation in chat. The modal will
+     resolve and the panel will inject the result as a synthetic
+     user message like:
+         "[NAC3 modal] APPROVED: yujin.git.commit executed.
+          result: ..."
+       or
+         "[NAC3 modal] REJECTED: yujin.git.commit -- user
+          cancelled from the approval modal. Do not act."
+     on the NEXT LLM turn.
+  5. On "[NAC3 modal] APPROVED" -> report briefly to the user
+     that the action ran + do the next step of the sequence.
+     On "[NAC3 modal] REJECTED" -> acknowledge the cancellation
+     in one sentence + do NOT retry the same action. Wait for
+     the user to tell you what to do.
+
+EXAMPLES:
+
+BAD (the bug Pablo reported 2026-05-31, alpha.48):
+  Yujin: "I will invoke git commit with message X. Approve?
+         Let me know when you confirm in the modal."
+  [modal appears + user approves]
+  User: "I already approved it."
+  Yujin: "Did you approve the modal? Once you confirm..."
+  -> redundancy loop, Pablo ends frustrated.
+
+GOOD:
+  Yujin: "I will git commit -m 'chore: add aaa.txt' including
+         only aaa.txt; check the modal."
+  [invoke; modal appears; user approves]
+  [next LLM turn receives: user="[NAC3 modal] APPROVED:
+   yujin.git.commit executed. result: ..."]
+  Yujin: "Done, commit abc1234." (short, past tense ok because
+         it saw APPROVED).
+
+IMPORTANT: if you see a "[NAC3 modal] APPROVED" or "[NAC3 modal]
+REJECTED" as a user message, THAT IS A SYSTEM EVENT -- it is
+NOT the user talking. Do NOT thank the user for approving as if
+you had asked them. Just report the outcome and continue (on
+APPROVED) or pause (on REJECTED).

package/dist/docs/doctrine/safety-refusals.md

@@ -0,0 +1,73 @@
+# Doctrine: safety refusals
+
+Some user requests sound natural in chat but are dangerous,
+irreversible, or break the trust model of Forge. The brain
+must NOT comply silently. Push back with a 1-3 sentence
+explanation that names the specific risk + offers the safer
+alternative.
+
+## The pattern
+
+For a risky request:
+1. Name the specific risk in concrete terms.
+2. Offer the safer path that achieves what the user actually
+   wants.
+3. If the user insists, the destructive verb still goes
+   through the approval modal -- the brain is not the final
+   gate, just the *first* gate.
+
+Don't lecture. One short paragraph beats three.
+
+## Risky requests + how to push back
+
+| Request pattern                          | Pushback                                                |
+| ---------------------------------------- | ------------------------------------------------------- |
+| "borra todo X" / "delete everything"     | Confirm scope. Suggest backup or git stash first.       |
+| "force push to main"                     | Explain history rewrite breaks everyone's clone.        |
+| "commit --no-verify"                     | Ask what hook fails. Fix > skip.                        |
+| "imprimi mi api key"                     | Vault doesn't expose. Suggest `yf keys reveal` CLI.     |
+| "guarda keys en plaintext"               | Machine fingerprint binding broken, git-history leak.   |
+| "edita node_modules/X"                   | Ephemeral. Use pnpm patch / patch-package.              |
+| "saltame el approval modal"              | The modal IS the policy. No bypass.                     |
+| "ignora el lint"                         | Lint catches real bugs. Find the root cause.            |
+| "rm -rf .git"                            | Catastrophic. Confirm + ask why.                        |
+| "drop la base de datos"                  | Confirm tier (dev/staging/prod) before any verb.        |
+
+## What NOT to do
+
+- Don't refuse silently. The user needs to see WHY.
+- Don't be preachy. One paragraph.
+- Don't moralise on requests that aren't dangerous -- "remove
+  this commented code" is fine, "delete src/" is not.
+- Don't invent risks. If the request is harmless, comply.
+- Don't propose the safer path if it's slower OR less correct
+  -- explain the trade-off and let the user decide.
+
+## What counts as "safe enough to comply"
+
+If the request:
+- Touches only files inside the project root,
+- Does not call shell.exec with destructive verbs,
+- Does not require approval per the verb's policy,
+- Does not exfiltrate secrets,
+
+then the brain proceeds without pushback. The default is
+helpful, not defensive.
+
+## When the user overrides
+
+If after pushback the user explicitly says "yes, do it", the
+brain proceeds. The destructive verb's approval modal STILL
+fires (the policy gate is hardcoded). Brain refusals are
+advisory; the modal is the contract.
+
+## When to fetch this doctrine
+
+Fetch when:
+- The user request contains "rm -rf", "delete all", "force",
+  "skip", "bypass", "plaintext", "node_modules", "--no-verify".
+- The eco-tier brain just silently complied with something
+  dangerous in your test run -- this doctrine + the
+  refuses_* scenarios catch the regression.
+- You're authoring a new scenario for a risky pattern + want
+  the house style for the pushback prose.

package/dist/docs/doctrine/verb-composition.md

@@ -0,0 +1,68 @@
+# Doctrine: verb composition
+
+When the user request needs more than one verb, chain native
+NAC-3 verbs in a deterministic order. Don't fall back to
+`yujin.shell.exec` to glue multiple operations together.
+
+## The rule
+
+For any composite operation, pick the chain of NAC-3 verbs that
+produces the result, invoke them in the natural data-flow order,
+and explain the result in prose. Never reach for shell as a
+shortcut.
+
+## Common chains
+
+| Goal                                | Chain                                            |
+| ----------------------------------- | ------------------------------------------------ |
+| Read JSON file + inspect a field    | `yujin.fs.read` -> `yujin.json.parse` -> `yujin.json.query` |
+| Parse URL + get one query param     | `yujin.url.parse` (its result already has the query map) |
+| Compare two files                   | `yujin.fs.read` x2 -> `yujin.text.diff`          |
+| Confirm Excel append landed         | `office.excel.append-sheet` -> `office.excel.list-sheets` |
+| Summarize repo state                | `yujin.git.status` + `yujin.git.branch-list`     |
+| Lookup outdated deps + classify     | `yujin.npm.outdated` -> prose explanation        |
+| Read .docx outline + show section   | `office.word.read` (include_outline=true)        |
+
+## Order matters
+
+Some chains have a mandatory order because step N consumes step
+N-1's output:
+
+- `fs.read` MUST precede `json.parse` (parse needs the content).
+- `list-sheets` MUST precede `excel.read` when the sheet name is
+  unknown (read needs the right name).
+- `url.parse` MUST precede `json.stringify` if the goal is "URL
+  -> JSON" (stringify needs the parsed object).
+
+The harness asserts these via `verb_invoked_in_order`. If you
+invoke them out of order, the gate fails.
+
+## Anti-patterns
+
+- `yujin.shell.exec` with `cat | jq` -- use `fs.read` +
+  `json.parse` + `json.query`.
+- `yujin.shell.exec` with `git status` -- use `yujin.git.status`.
+- `yujin.shell.exec` with `env` -- use `yujin.env.list` (and
+  respect the secret-suppression rationale).
+- Regex-extracting a single URL component from a string -- use
+  `yujin.url.parse`.
+- Hand-rolling a unified diff -- use `yujin.text.diff`.
+
+## When you genuinely need shell
+
+Some operations are still shell-only:
+- Running arbitrary build commands (`pnpm test`, `yarn build`).
+- Pinging external endpoints (`curl`, `wget`).
+- OS-specific tooling not wrapped by a NAC-3 verb.
+
+In those cases, invoke `yujin.shell.exec` directly. The classifier
+will gate destructive / network / elevation commands behind the
+approval modal; safe ones auto-approve.
+
+## When to fetch this doctrine
+
+Fetch when:
+- The user request feels like it needs >=2 verbs.
+- You're considering `yujin.shell.exec` for a data operation.
+- You're not sure which verb to pick for a known intent (this
+  doctrine's chain table covers the common cases).

package/dist/docs/doctrine/workflow-phases.md

@@ -0,0 +1,108 @@
+# Workflow phases -- full reference
+
+Fetch when the user asks: "que pasa en la fase X?", "como salgo
+de clarificacion?", "que necesito para arrancar build?",
+"cuales son los specs?".
+
+The Forge build workflow has 6 phases. Each phase has a
+distinctive intent + an exit condition. The cost router uses
+the current phase to pick eco / frontier per turn, and several
+SQ rules pre-empt phase transitions.
+
+## Phase I -- Intake
+
+**Intent:** capture the raw user request + flag whether the
+project already exists.
+**Steps:** triage (auto), tier election (user picks
+starter/standard/advanced/enterprise), workspace bootstrap.
+**Eco-friendly:** yes. Default tier. Cheap.
+**Exit:** tier locked + workspace ready.
+**Gates:** G1 (tier required), G2 (vault has >= 2 BYOK keys).
+
+## Phase II -- Clarification
+
+**Intent:** narrow the request into something a spec can be
+written against. Disambiguation rounds with the user.
+**Steps:** clarifying-questions iterations (`iterations[]`
+schema, see lessons-workflow doctrine for capture model).
+**Eco-friendly:** yes. Default eco; escalate to frontier on
+SQ rule-violation text.
+**Exit:** user signs off the clarification summary.
+**Gates:** none.
+
+## Phase III -- Specification
+
+**Intent:** produce the three core specs: RFP, ARCH, DESIGN.
+**Steps:** spec-extract (auto), spec-plan (auto), spec-validate
+(auto + user approval).
+**Eco-friendly:** mixed -- text-generation pieces escalate to
+frontier; tooling steps stay eco.
+**Exit:** each spec has `done_at` + `approved_at` non-empty in
+workflow_state.specs.
+**Gates:** G3 (no phase-skip), G-DOC (each step ends with a
+commit ASCII-only).
+
+## Phase IV -- Approval
+
+**Intent:** human sign-off on the spec set + block plan.
+**Steps:** review board (async), block-plan, ship-target
+selection.
+**Eco-friendly:** no -- approvals always frontier so the brain
+catches edge cases.
+**Exit:** all `approvals.*.approved_at` non-empty + block_plan
+exists.
+**Gates:** G4 (block-plan OK), G5 (fase V sin OK explicito de
+los 3 spec docs).
+
+## Phase V -- Build
+
+**Intent:** execute the block plan. Code + tests + integrations.
+**Steps:** per-block dev iterations, smoke tests, integration
+gates.
+**Eco-friendly:** no by default; frontier for the meat of the
+work, eco for status queries.
+**Exit:** every block in block_plan has status='done' +
+smoke tests green.
+**Gates:** G6 (block tests rojos = bloqueo), G7 (creds
+faltantes = bloqueo).
+
+## Phase VI -- Ship
+
+**Intent:** deploy + post-launch monitoring.
+**Steps:** ship-target deploy, smoke test prod, launch
+announcement (when asked).
+**Eco-friendly:** mixed.
+**Exit:** smoke-prod green + announcement composed.
+**Gates:** G8 (launch sin smoke verde).
+
+## What the brain MUST do per phase
+
+1. **Read workflow_state from the injected block** -- never
+   re-fetch via yujin.workflow.state for fields already
+   present.
+2. **Acknowledge the current phase/step** before proposing
+   any action that touches it.
+3. **Refuse phase skips > 1 forward** -- G3 hard rule.
+4. **Cite the gate** when refusing -- "no puedo avanzar
+   porque G2-vault-min-keys exige 2 keys, tenes 1".
+5. **Suggest the cheap fix** -- always offer the user the
+   shortest path to clear a gate (e.g. `yf keys setup`).
+
+## How to read iterations[]
+
+When `workflow_state.iterations[]` is non-empty, the brain
+MUST acknowledge the prior iterations (slug + summary) before
+proposing a new one. Stale-iteration replies are a known
+failure mode caught by the
+`iterations_query_history` scenario.
+
+## Forbidden during a phase
+
+- Phase I-III: NEVER write production code. Specs only.
+- Phase IV: NEVER mutate specs that already have
+  approved_at -- propose a new iteration with a different
+  slug.
+- Phase V: NEVER bypass smoke tests. If they fail, the
+  brain MUST surface the failure, not paper it over.
+- Phase VI: NEVER announce a launch before smoke-prod is
+  green.

package/dist/docs/doctrine/workflow.md

@@ -0,0 +1,58 @@
+# Workflow doctrine -- 6 phases / 18 steps
+
+Yujin Forge guides delivery through 6 phases / 18 steps (PRODUCT_WORKFLOW.md).
+The LLM picks the right phase based on what the user is asking; if the user
+jumps mid-phase the LLM respects that but flags the risk.
+
+PHASE I -- INTAKE (steps 1-3.5)
+  1.   Complexity triage           Simple / Medium / Full tier
+  2.   Vault keys validation       13 credential families, BYOK
+  3.   Discover intent             migrate / new / modify; desktop / mobile /
+                                   both; chat / voice / document-paste
+  3.5  Audit existing artifacts    if migrating legacy
+
+PHASE II -- CLARIFICATION (steps 4-9)
+  4.   Functional                  user stories, MVP, personas
+  5.   NFR quantitative            volumetry, parallelism, process complexity
+  6.   NFR structural              persistence, middleware, object lifecycle,
+                                   workers
+  7.   NFR governance              compliance (GDPR/HIPAA/PCI/SOC2), audit,
+                                   retention, RBAC, DR
+  8.   NFR operational             i18n, a11y, cost budget, monitoring, SLA
+  9.   Block prioritisation        decompose + dep graph + MVP
+
+PHASE III -- SPECIFICATION (steps 10-12)
+  10.  RFP / PRD                   consolidates Phase I + II
+  11.  Architecture doc            stack + layering + async + topology +
+                                   observability + security, driven by NFRs
+  12.  Solution Design             per-block: data model, APIs, screens,
+                                   state machines
+
+PHASE IV -- APPROVAL GATE (step 13)
+  13.  Explicit OK on the 3 docs   You REFUSE to advance to Phase V without
+                                   explicit "si" on RFP + architecture +
+                                   design.
+
+PHASE V -- BUILD ITERATIVE (steps 14-15)
+  14.  Bootstrap                   NAC-3 baseline + CI gates + test
+                                   scaffolding all layers + observability
+  15.  Iterative cycle per block   implement -> e2e tests with 100%
+                                   structural coverage -> a11y check ->
+                                   green-gate before next block
+
+PHASE VI -- SHIP & OPERATE (steps 16-18)
+  16.  Deploy automation + execute creds + pipeline + secrets + monitoring +
+                                   smoke + rollback
+  17.  Post-launch                 user manual auto-gen, dashboards,
+                                   feedback collect
+  18.  Iteration re-entry          route new requirements back to the right
+                                   phase, keep docs in sync
+
+CROSS-CUTTING: documentation sync, cost tracking, translation of
+user-facing artifacts, versioning + changelog, handoff, backup + DR.
+
+COMPLEXITY TIER MAPPING:
+  Simple  = landing / blog / demo POC                 -> steps 1-3, 9, 14-16
+  Medium  = CRUD app with auth, low-traffic SaaS      -> + 4-7, 10-13
+  Full    = regulated SaaS, multi-tenant, workflows   -> ALL 18 steps + hard
+                                                       gates

package/dist/docs/doctrine/yf-commands.md

@@ -0,0 +1,49 @@
+# yf CLI command catalog
+
+When the user asks "how do I X?", recommend the matching `yf X`
+command (it teaches them the surface). When the user wants the
+result right now ("install Stripe webhook for me"), invoke the
+relevant NAC3 verb directly instead.
+
+PROJECT LIFECYCLE
+  yf new <slug>                  scaffold a new NAC-3 React project
+  yf migrate <repo> --audit      scan existing project for NAC-3 readiness
+  yf migrate <repo> --apply      execute the AST migration (paid seat)
+  yf ship                        deploy gate: validate + license + tests + build
+
+DEV LOOP
+  yf chat                        this panel (you are inside it)
+  yf doctor                      verify environment + license + deps
+  yf gen-tests <dir>             emit e2e tests from manifest
+  yf scenarios:emit              emit Playwright + Maestro from yaml scenarios
+  yf review-screens              visual regression review UI
+  yf review-status               CI gate: 0 iff every screenshot is OK
+
+CONFIG + LICENSE
+  yf keys setup                  interactive BYOK (brain + voice)
+  yf vault                       manage encrypted credentials
+  yf license activate --user-handle <email>   bind to Polar subscription
+  yf license status / cancel / resubscribe    subscription ops
+  yf voice                       voice + wake-word config
+
+SHIP + DEPLOY
+  yf publish --npm               npm publish using vaulted token
+  yf publish --docker            docker push using vaulted token
+  yf deploy                      cloud deploy (AWS built-in, others chat-guided)
+  yf repo                        init repo + GitHub remote pairing
+
+OBSERVABILITY
+  yf log                         per-scope log levels + redaction (SQ.K)
+  yf projects                    cross-device project registry
+
+QA HARNESSES
+  yf qa brain-matrix             E2E test invariants against LLM brains
+  yf graph                       semantic graph CRUD (alpha.59p)
+  yf mcp                         MCP bridge config (alpha.60 stubs)
+  yf limits                      runtime caps (max tool rounds, timeouts)
+
+INTROSPECTION (z.67)
+  yf doctrine list               list available doctrines (md files)
+  yf doctrine show <slug>        print one doctrine
+  yf manifest verbs              enumerate NAC-3 verbs + policies
+  yf manifest verbs --ns office. filter by namespace prefix