@nac3/forge-cli 0.2.0-alpha.9 → 0.2.1-alpha.60

package/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/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/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/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/docs/doctrine/cost-router-escalation.md

@@ -0,0 +1,103 @@
+# 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 |
+| `next_turn_frontier_hint.json` written by last turn     | post-reply quality detectors (z.188) |
+
+### Next-turn frontier hint (alpha.59z.188, PND-036/037/038)
+
+After every reply the chat server runs three pure detectors:
+
+1. **completion_hallucination**: the LLM said "voy a configurar /
+   procedere a setup / ya he procesado" but invoked zero tools.
+   Implemented in `src/chat/completion_hallucination_detector.ts`;
+   waives when a tool fired, the reply mentions a verb id like
+   `yujin.X.Y`, or contains a fenced code block (proof of intent).
+2. **unwarranted_refusal**: the LLM said "no tengo capacidad de X"
+   AND the user asked about a topic AND the manifest has a verb
+   that does X. Implemented in `src/chat/refusal_detector.ts`.
+3. **confusion_signal**: the LLM apologized ("mis disculpas /
+   hubo un error / aun estoy en proceso"). Independent of (1);
+   even when a tool fired, an apology means the tier is over its
+   head.
+
+Any of those flags triggers two side effects:
+- append a row to `~/.yujin-forge/hallucinations.jsonl` (telemetry).
+- write `~/.yujin-forge/next_turn_frontier_hint.json` (one-shot).
+
+On the next user message, `selectBrainForTurn` reads + atomically
+consumes the hint file. If present, the turn forces frontier
+regardless of gate verdict. User overrides (/eco /frontier) still
+win.
+
+This is INDEPENDENT of the smart-auto classifier -- it kicks in
+even when the classifier is unreachable.
+
+## 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/docs/doctrine/default-design-system.md

@@ -0,0 +1,120 @@
+# Default design system -- Yujin DS first
+
+Fetch when the user discusses UI / component design / look-and-
+feel (signals: "componente", "modal", "sidebar", "card", "view",
+"icon", "color", "fuente", "diseno", "interfaz", "UI", "form",
+"button", "table", "kanban", "tabs"). Auto-injected on every
+turn whose intent matches the UI heuristic.
+
+## Rule (single source of truth)
+
+The default front-end design system for any Forge-generated
+project is **Yujin Design System** (`yujin-design-system/`). The
+package ships with 258 DTCG-compliant tokens, 30 NAC3-attributed
+component templates, 170 sumi-e icons + a kanji wordmark
+catalog, and font references (Google Fonts CDN, no bundled
+binaries).
+
+When the user asks for a UI element, agents MUST:
+
+1. Consult `yujin.design.list-templates` to see which Yujin
+   components cover the kind of element being requested.
+2. Use `yujin.design.get-template({slug})` to retrieve the HTML
+   + CSS + `nac3_attrs` + variants for the picked component.
+3. Splice the template into the project; do NOT hand-roll an
+   equivalent layout from scratch.
+4. Iconography: only pick from `yujin.design.list-sumie` (170
+   canonical icons). Use `yujin.design.get-icon({slug})` to
+   inline the SVG. Do NOT generate or import third-party icons
+   (no Material, no Font Awesome) unless the user explicitly
+   asks (override flow below).
+5. Colors / typography / spacing: only via tokens from
+   `yujin.design.tokens()`. Do NOT hardcode `#3A4DBC` or
+   `font-family: Inter`; use `var(--color-accent)` and
+   `var(--font-family-sans)`.
+
+## Override flow
+
+The user CAN override the default ("usa shadcn", "use Material",
+"this app needs Tailwind only", "I want my own brand colors"):
+
+- Agent invokes `yujin.design.override({system_id, reason})`.
+- This is `policy: 'approval_required'` so R8 opens a modal.
+- The user confirms (or rejects); the choice persists in
+  `tenant_config.design_override`.
+- Subsequent turns honor the override + the doctrine becomes a
+  soft suggestion ("Yujin DS is the Forge default, but this
+  tenant has overridden to <system>").
+
+## Why this is the default
+
+- Coherent visual language across every Forge-generated product
+  -- the user does not need to re-learn the look-and-feel per
+  product.
+- 30 components are enough to compose every standard SaaS UX
+  (CRM, admin panel, marketing site, e-commerce, dashboard,
+  task tracker, settings).
+- NAC3 attributes pre-applied -- every Yujin component is
+  voice-controllable + accessibility-ready out of the box.
+- 170 sumi-e icons cover virtually every business concept
+  (finance, sales, support, manufacturing, quality, HR, mobile,
+  AI, comms, document, geo, weather, animal). One coherent
+  illustration style.
+
+## Files in the package
+
+```
+yujin-design-system/
+  manifest.json                 catalog + version + license
+  tokens/
+    yujin-tokens.json           258 DTCG W3C tokens
+    yujin-tokens.css            generated CSS (same source-of-truth)
+  components/
+    _index.json                 list of 30 components by category
+    button.yujin.json           one file per component
+    card.yujin.json
+    ...                         (30 total)
+  icons/
+    sumie/
+      manifest.json             170 icons with tags
+      branch-sakura.svg         one SVG file per icon
+      ...                       (170 total)
+  fonts/
+    README.md                   reference-only policy (Google Fonts CDN)
+```
+
+## Six NAC3 verbs
+
+| Verb                            | Returns                                            | Policy             |
+|---------------------------------|----------------------------------------------------|--------------------|
+| `yujin.design.list-templates`   | `[{slug, category, description, variants}]`       | safe               |
+| `yujin.design.get-template`     | full ComponentTemplate (html, css, nac3, props)   | safe               |
+| `yujin.design.list-sumie`       | `[{slug, tags, file}]` (filtered by tag if given) | safe               |
+| `yujin.design.get-icon`         | inline SVG string                                  | safe               |
+| `yujin.design.tokens`           | full DTCG token tree                               | safe               |
+| `yujin.design.override`         | persists tenant_config.design_override            | approval-required  |
+
+## What this doctrine does NOT cover
+
+- Framework choice within TypeScript (Vue vs React vs Svelte).
+  See `docs/doctrine/language-sovereignty.md` -- the user
+  decides per slot, and the doctrine table records the choice.
+- Build tooling (Vite vs Webpack vs esbuild). Out of scope.
+- Theme switching per tenant. The override flow above persists
+  one choice per tenant; multi-theme support is a separate
+  feature.
+
+## What the WORKERS (Analyst, Coder, Director) do with this
+
+- **Analyst**: when extracting a spec that mentions UI elements
+  (forms, dashboards, modals), tag each one with the matching
+  Yujin component slug in `plan.components[]`. The Coder then
+  knows which template to pull.
+- **Coder**: before writing ANY UI file, invoke
+  `yujin.design.list-templates` + `yujin.design.get-template`
+  for the components in the plan. Splice the templates. Apply
+  variants from the spec. Do NOT hand-write `.css` from
+  scratch.
+- **Director**: when the user explicitly requests an override
+  ("use shadcn"), invokes `yujin.design.override` instead of
+  silently accepting. The R8 modal confirms.

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.