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

package/dist/docs/SQ_BY_STEP.yaml

@@ -0,0 +1,147 @@
+# SQ rules active per workflow step (alpha.59y.3)
+#
+# Maps each step of docs/PRODUCT_WORKFLOW.md (18 steps across 6
+# phases) to the docs/SQ.md rule slugs that apply at that step.
+# The chat server uses this to inject the relevant subset of SQ
+# into the per-turn workflow state block, instead of dumping all
+# 50+ rules every time.
+#
+# Schema:
+#   step_<N>_<slug>:    [rule_slug, rule_slug, ...]
+#
+# Rule slugs use the section number from SQ.md (0.1, 0.2, 1.3,
+# 2.4, 14, 15, etc). Sub-sections (14.1, 14.2) roll up to their
+# parent unless the parent is broken.
+#
+# Cross-cutting rules (apply to every step):
+#   0.1 -- user time is sacred
+#   0.2 -- no fallback to legacy
+#   0.3 -- no silent damage
+#   0.4 -- industrial quality
+#   0.5 -- agnostic by default
+#   0.8 -- dual-mode comm
+#   0.11 -- vault autonomy
+#   14   -- producer/consumer symmetry
+#   15   -- test things yourself
+#
+# These are implied in every step; they are NOT repeated here to
+# keep the resolver's output compact. The resolver always merges
+# them into the active set.
+#
+# ASCII-only.
+
+cross_cutting:
+  - "0.1"   # tiempo del user
+  - "0.2"   # cero fallback legacy
+  - "0.3"   # cero dano silencioso
+  - "0.4"   # calidad industrial
+  - "0.5"   # agnostico por default
+  - "0.8"   # dual mode didactico/tecnico
+  - "0.11"  # autonomia via vault
+  - "14"    # producer/consumer symmetry
+  - "15"    # autonomia / test things yourself
+
+step_1_triage:
+  - "0.6"   # definicion proyecto Yujin
+  - "0.10"  # target desktop+mobile vs mobile-pure
+  - "1.1"   # lectura docs proyecto
+  - "1.2"   # volumetrias antes arquitectura
+
+step_2_vault:
+  - "0.11"  # autonomia vault (refuerzo)
+  - "2.8"   # security boundaries
+
+step_3_intent:
+  - "0.6"   # definicion proyecto
+  - "1.1"   # lectura docs
+  - "0.10"  # target
+
+step_3_5_legacy_audit:
+  - "1.1"
+  - "1.2"
+
+step_4_functional:
+  - "1.1"
+  - "0.6"
+
+step_5_nfr_quantitative:
+  - "1.2"   # volumetrias antes arquitectura -- CRITICAL aqui
+  - "1.3"   # solicitudes simultaneas
+
+step_6_nfr_structural:
+  - "1.3"   # escalables
+  - "0.7"   # componentes obligatorios
+
+step_7_nfr_governance:
+  - "2.7"   # provenance
+  - "2.8"   # security boundaries
+
+step_8_nfr_operational:
+  - "2.6"   # multilang
+  - "0.7"   # componentes obligatorios
+  - "0.9"   # test playwright visual
+
+step_9_block_prioritisation:
+  - "0.5"   # agnostico
+  - "1.3"
+
+step_10_rfp:
+  - "1.1"
+  - "1.2"
+  - "1.3"
+  - "3.1"   # INFRASTRUCTURE.md
+  - "3.2"   # ARCHITECTURE.md
+
+step_11_architecture:
+  - "1.2"
+  - "1.3"
+  - "0.7"
+  - "2.7"
+  - "2.8"
+  - "2.9"   # single source of truth modelos LLM
+  - "3.2"   # ARCHITECTURE.md emit aqui
+  - "8"     # activos estrategicos / IP
+
+step_12_solution_design:
+  - "0.5"
+  - "0.7"
+  - "2.6"
+  - "2.7"
+  - "2.9"
+
+step_13_approval_gate:
+  - "0.3"   # cero dano silencioso (refuse to advance without OK)
+  - "0.4"   # calidad industrial
+
+step_14_bootstrap:
+  - "0.7"   # componentes obligatorios scaffolded
+  - "2.1"   # tests scaffolded
+  - "2.4"   # code style
+  - "2.5"   # build + deploy
+  - "2.6"   # 10 idiomas
+  - "2.9"
+
+step_15_block_dev:
+  - "2.1"   # tests primero
+  - "2.2"   # coverage 100% visual
+  - "2.3"   # coverage 100% backend
+  - "2.4"   # code style
+  - "0.9"   # playwright visual approve
+  - "14"    # producer/consumer audit (refuerzo)
+  - "15"    # autonomia (refuerzo)
+
+step_16_deploy:
+  - "0.11"
+  - "2.5"
+  - "3.1"   # INFRASTRUCTURE.md updated
+  - "3.4"   # MAINTENANCE_MANUAL.md
+
+step_17_postlaunch:
+  - "3.3"   # USER_MANUAL.md emit
+  - "3.4"   # MAINTENANCE_MANUAL.md emit
+  - "0.8"   # dual mode docs
+
+step_18_iteration:
+  - "0.3"   # cero dano silencioso (adenda flow)
+  - "0.4"
+  - "7"     # memoria de decisiones

package/dist/docs/doctrine/accessibility.md

@@ -0,0 +1,78 @@
+# yujin.a11y.* verbs (F107) -- screen reader + voice-first
+
+The `yujin.a11y.*` namespace gives the brain three
+panel-dispatch verbs to drive the accessibility surface of any
+adopter app. Fetch this doctrine via `yujin.doctrine.discover`
+when the user mentions screen reader / accessibility / voice
+announce / focus / aria.
+
+## Catalog
+
+| Verb | Use when |
+|---|---|
+| `yujin.a11y.announce` | A status / error / async completion needs to reach screen-reader users + the voice loop |
+| `yujin.a11y.focus`    | Keyboard focus needs to land on a specific element (after open modal, after async load) |
+| `yujin.a11y.label`    | An element needs a screen-reader description, optional shortcut + role hints |
+
+All three are `policy: unrestricted`, `side_effects: ['dom']`,
+`handler_side: panel`.
+
+## Args -- quick reference
+
+```
+yujin.a11y.announce   {text, politeness?:'polite'|'assertive', speak?, locale?}
+yujin.a11y.focus      {slug, scroll?, announce?}
+yujin.a11y.label      {slug, description, shortcut?, role?}
+```
+
+`slug` is the NAC-3 element slug (the value of the `data-nac-slug`
+attribute the adopter declared at source). It MUST match
+`[a-z0-9][a-z0-9._-]*` -- no spaces, no `/`, max 120 chars.
+
+## When to announce
+
+- After a destructive action completed -> `announce({text: '...
+  eliminado', politeness:'assertive'})`.
+- After a long-running task finished -> `announce({text:'Deploy
+  listo', speak:true})` to also TTS it.
+- For ambient progress -> default `politeness:'polite'` so the
+  screen reader does not interrupt.
+
+## When to focus
+
+- After opening a modal: focus the modal's primary button
+  (`scroll:true, announce:true` by default).
+- After loading new content into a region: focus the heading
+  so screen-reader users know where they are.
+- NEVER force focus mid-typing -- the user's keyboard input wins.
+
+## When to label
+
+- The adopter forgot to ship a `data-nac-label` -- the assistant
+  can patch the live a11y tree without forcing a source edit.
+- A shortcut or role hint helps disambiguate (two buttons with
+  the same visible text).
+
+## Don't
+
+- Don't fire `announce` for visual-only chatter ("rendered the
+  pizarron tab"). The screen reader gets EVERY announce -- noisy
+  is worse than silent.
+- Don't use `focus` to scroll the page for sighted users; use the
+  panel scroll API instead.
+- Don't invent verbs like `yujin.a11y.read-page` -- only the three
+  above exist.
+
+## Voice-first integration
+
+`announce` with `speak: true` forwards the text to the existing
+voice loop (Yujin TTS gateway or BYOK provider). Locale defaults
+to the user's voice config; pass `locale: 'es-AR'` to override
+for an individual announcement.
+
+## Mobile
+
+The React-Native adapter consumes the same payloads:
+- `aria-live polite/assertive` -> `AccessibilityInfo.announceForAccessibility`
+- `focus` -> native `setAccessibilityFocus` ref
+- `label` -> `accessibilityLabel` + `accessibilityHint`

package/dist/docs/doctrine/agent-orchestrator.md

@@ -0,0 +1,76 @@
+# Agent orchestrator (HITO 5) -- intent + scope
+
+Fetch when the user asks "que es un agente?", "quiero un agente
+que..." , "scheduled job", "background task", "agente automatico",
+"que corra mientras duermo".
+
+## Status
+
+Design draft. No agent code shipped yet. CLARIFY-BEFORE-CODE
+gates: `docs/HITO_5_AGENT_ORCHESTRATOR_DESIGN.md` lists 10 points
+Pablo must answer before slice 1 lands.
+
+If the user asks the brain to create an agent today, the brain
+should:
+
+1. Acknowledge agents are designed but not built.
+2. Offer the manual interim: a saved CLI script + a doc the user
+   keeps in `~/.yujin-forge/scripts/<slug>.md`.
+3. Point at the design doc for the long-form plan.
+4. Capture the user's intent in a lesson via
+   `yujin.lessons.promote` (HITO 6.4) so the design doc can
+   absorb the use-case before code lands.
+
+## What an agent will be (when built)
+
+A saved configuration that can run a sequence of NAC-3 verbs +
+MCP bridge tools on behalf of the user, with bounded scope,
+explicit approval surface, and optional schedule.
+
+Each agent declares:
+- `slug`, `name`, `description`, `icon`
+- `tier` -- eco / frontier / managed
+- `system_prompt`
+- `tool_allowlist` (subset of manifest)
+- `default_args`
+- `trigger` -- manual / cron / event:<entity>:<verb>
+- `output_sink` -- chat / pizarron-tab / webhook / none
+- `policy_override` -- inherit / auto / request-approval
+- `auth_scope` -- which Vault tokens this agent can use
+- `quota` -- per-day calls + tokens + cost USD
+- `audit_label` -- mandatory free-text on every dispatch row
+
+## Where agents will live
+
+`~/.yujin-forge/agents/` -- one folder per agent slug, with
+`definition.json` + `runs/<ts>.json` + `runs/<ts>.audit.jsonl`.
+Managed variant adds a `managed_handle.json` with the Workers
+KV key.
+
+## What's NEVER on the allowlist
+
+- `yujin.shell.exec` (too broad)
+- `yujin.keys.set` / `yujin.keys.delete`
+- `yujin.mcp.set-creds`
+- `yujin.workflow.set`
+
+Agents cannot rotate credentials, mutate workflow state, or run
+arbitrary shell.
+
+## Recommended seed templates (when slice 7 ships)
+
+- `daily-prs` -- list open PRs, summarise in pizarron.
+- `ticket-triage` -- triage support inbox, propose tags.
+- `brain-matrix-watcher` -- nightly brain matrix run + diff.
+- `support-replies` -- draft replies, await approval.
+- `lessons-promote` -- auto-promote lessons after N approvals.
+- `costs-report` -- weekly cost-meter digest.
+
+## When to point users at the design doc
+
+If a question is structural ("how would the agent talk to my
+Slack?", "what's the latency?"), pull `HITO_5_AGENT_ORCHESTRATOR_DESIGN.md`
+from disk via `yujin.fs.read-file` + answer from there.
+
+If the question is "I want X agent" the brain captures the
+intent + flags it for the design phase.

package/dist/docs/doctrine/byok-vs-managed.md

@@ -0,0 +1,81 @@
+# BYOK vs managed brain -- when to recommend which
+
+Fetch when the user asks: "que conviene?", "BYOK?", "managed?",
+"why am I being told to setup keys?", "cap exhausted", "credit
+ran out".
+
+## The two paths
+
+| Mode | Where the LLM call lives | Who pays |
+|---|---|---|
+| **BYOK** (bring-your-own-key) | Directly from `yf chat` to the provider (Anthropic / Google / OpenAI) using the user's API key from CredentialVault | The user, on their own provider account |
+| **Managed brain** | `yf chat` -> Cloudflare Workers route -> provider, with a per-user cost-meter in KV | Yujin operator, billed back via subscription |
+
+## When BYOK wins
+
+- User already has a provider account + budget.
+- Privacy: the prompt never leaves the user's machine -> Anthropic
+  directly. No third party in the middle.
+- Heavy / sustained use: BYOK has no per-month cap.
+- Custom models the managed runtime doesn't proxy (e.g. specific
+  Bedrock variants).
+
+## When managed wins
+
+- First-day onboarding: no provider account yet, but wants to try.
+- Cost predictability: hard cap, can't accidentally rack up bills.
+- Multi-device: no need to re-pair keys per laptop.
+- Voice + reading flows on mobile: managed already wires
+  pizarron / lessons / projects without a key per device.
+
+## What to do when cap exhausted
+
+If the user is on managed and hits the monthly cap, the brain
+should:
+
+1. Acknowledge the cap with the actual number if known.
+2. Offer two paths, in this order:
+   a. Configure BYOK -> `yf keys setup`. Costs pass directly to the
+      user's provider account; no cap.
+   b. Wait for the reset (first of next month). Read-only on
+      managed in the meantime.
+3. NEVER silently retry the same call.
+4. NEVER suggest fishing for a different provider unless the
+   user explicitly asks.
+
+## What to do when no keys configured
+
+- Brain MUST refuse anything that needs an LLM call.
+- Recommend `yf keys setup` for the simplest path.
+- Be clear about what each key unlocks (`anthropic_api_key` ->
+  Sonnet/Haiku/Opus; `openai_api_key` -> GPT-4o; `google_ai_key`
+  -> Gemini).
+- Don't ask the user to paste keys in chat. The Vault setup
+  prompts the user for the secret directly.
+
+## Slot canonical names
+
+Vault canonical:
+- `anthropic_api_key`
+- `openai_api_key`
+- `google_ai_key`
+- `deepseek_api_key`
+- `xai_api_key`
+- `mistral_api_key`
+- `cohere_api_key`
+
+SDK-convention aliases the brain matrix runner accepts:
+`CLAUDE_API_KEY` -> `ANTHROPIC_API_KEY`,
+`GEMINI_API_KEY` -> `GOOGLE_AI_KEY`. The user's `.env` may use
+either set.
+
+## Edge cases
+
+- Mixed mode: user has BYOK + managed both. cost_router picks the
+  cheaper or the available one per turn; the brain should not
+  assume one specific provider.
+- Override: `yf brain set <tier>` pins the next chat to a
+  specific tier regardless of the router.
+- Local fallback: there is no offline brain. If the network is
+  down and there's no cached response, the chat is broken --
+  surface that to the user instead of fabricating an answer.

package/dist/docs/doctrine/cost-router-escalation.md

@@ -0,0 +1,73 @@
+# Cost router escalation -- eco vs frontier
+
+Fetch when the user asks: "por que cambio de modelo?", "estoy en
+eco o frontier?", "me escalo solo", "como bajo a Haiku?", "deja
+de usar Sonnet".
+
+## What the router decides per turn
+
+`src/core/cost_router.ts` -- pure function that picks the brain
+tier for the next turn based on:
+
+1. **User override** (highest priority). `yf brain set eco|frontier`
+   pins one tier; the router short-circuits.
+2. **Verb tier hint** -- if the user already said which verb to
+   invoke + that verb has a known cheap path, eco wins.
+3. **Workflow phase** -- phases I + II (intake + clarification)
+   default to eco; phases III + IV + V (specs, build) default to
+   frontier.
+4. **Active SQ rules** -- presence of any rule from the workflow
+   phase rules pushes to frontier (cost of breaking a rule >
+   cost of using Sonnet).
+5. **Phase-crossover signal** -- last turn was eco, current text
+   contains "let's commit" / "ship it" / "proceed" -- escalate.
+6. **Smart-auto classifier** -- ambient turn, eco-keyword vs
+   frontier-keyword + length heuristic.
+7. **Frontier inertia** -- if the last turn was frontier AND the
+   current turn is short, stay on frontier for one more turn so a
+   quick clarification doesn't lose context.
+
+## Escalation triggers (push from eco -> frontier)
+
+| Signal | Source |
+|---|---|
+| `active_sq_rules` non-empty + rule-violation text       | workflow_inject + sq_resolver |
+| `phase_crossover: true` flag                            | incomplete_detector |
+| User text has 3+ frontier keywords                      | turn_classifier |
+| Last turn already escalated                             | frontier_inertia |
+| Attachment present (image / audio)                      | F101 attachment handler |
+
+## De-escalation (frontier -> eco)
+
+- 5+ minutes idle since last turn -> reset to default per phase.
+- User explicitly says `eco only` / `bajemos a Haiku`.
+- Workflow phase advances back to I (rare).
+
+## What to tell the user
+
+When the user asks why their last turn cost more / less than the
+previous one, the brain MAY say:
+
+- "Cambie a Sonnet en este turno porque el texto disparo G2-vault-min-keys
+  y el router escala las defensas de SQ."
+- "Te baje a Haiku porque la consulta es corta y la fase es II
+  (clarificacion)."
+
+The brain MUST NOT lie about the tier picked. The panel shows a
+badge with the actual tier per turn (alpha.58 #2).
+
+## Manual override
+
+```
+yf brain set eco
+yf brain set frontier
+yf brain reset
+```
+
+`reset` returns the router to automatic picking.
+
+## When the cap exhausts
+
+If the managed brain monthly cap fires, the router cannot
+escalate -- it surfaces a "cap exhausted" error and offers BYOK
+(see `byok-vs-managed` doctrine).

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