docs: update all documentation to v2.5.0

README.md:
- Badge 2.4.0 → 2.5.0
- Architecture tree: add mcp/, 16 stacks, 7 agents
- Feature matrix: add MCP templates row (EN + ES)
- Skills table: add /cap alias row (EN + ES)
- Agents table: add Model column with haiku/sonnet/opus (EN + ES)
- Stacks table: add hookify and trading rows (EN + ES)
- Practices pipeline: mention /cap and auto-detect (EN + ES)
- Docs section: update changelog/roadmap refs (EN + ES)

ROADMAP.md:
- Header: v2.4.0 → v2.5.0
- Add v2.5.0 completed section
- Remove duplicate v2.6.0 section
- v2.6.0 correctly marked as "próximo"

docs/changelog.md: add v2.5.0 entry
docs/usage-guide.md: version 2.0.0→2.5.0, add MCP templates section (#13)
  and model routing section (#14), update agents count 6→7, /cap alias
docs/best-practices.md: add Model selection subsection (EN + ES)
docs/creating-stacks.md: add Stacks vs MCP templates comparison
docs/troubleshooting.md: add MCP troubleshooting + /cap no-detect case
docs/roadmap.md: reframe as historical document, link to ROADMAP.md

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: luiseiman

README.md

@@ -1,6 +1,17 @@
 # Roadmap claude-kit
 
-Estado actual: **v2.4.0** (2026-03-21)
+Estado actual: **v2.5.0** (2026-03-21)
+
+---
+
+## v2.5.0 — Completado
+
+- `/forge capture` sin args: auto-detección de contexto de sesión, propone insight pre-formateado, pide confirmación Y/n/edit antes de guardar
+- `/cap`: alias shorthand para `/forge capture` — 4 chars vs 14
+- Regla proactiva de captura en `template/rules/_common.md`: Claude sugiere `/cap` al detectar workaround, bug multi-intento, decisión con trade-offs, o comportamiento no-obvio
+- MCP server templates en `mcp/`: github, postgres, supabase, redis, slack — cada uno con config.json, permissions.json, rules.md
+- `template/rules/model-routing.md`: criterios explícitos para haiku/sonnet/opus por tipo de tarea
+- 7 agents actualizados con modelo explícito (researcher/test-runner=haiku, implementer/code-reviewer/session-reviewer=sonnet, architect/security-auditor=opus)
 
 ---
 
@@ -25,41 +36,7 @@ Estado actual: **v2.4.0** (2026-03-21)
 
 ---
 
-## v2.5.0 — Learning loop + MCP + Model routing
-
-Foco: cerrar el loop de aprendizaje automático, cubrir el gap de MCP, y establecer model routing explícito.
-
-### `/forge capture` sin args — auto-detección de contexto
-
-- `/forge capture` sin argumentos analiza el contexto reciente de la conversación
-- Propone un insight pre-formateado basado en señales de la sesión (workaround, bug multi-intento, decisión con trade-offs)
-- Pide confirmación o edición antes de guardar — nunca escribe sin aprobación del usuario
-- Complementa la regla proactiva de A1 (ya implementada en `template/rules/_common.md`)
-- Complementa el alias `/cap` (ya implementado en `global/commands/cap.md`)
-- Modifica: `skills/capture-practice/SKILL.md` — agregar rama de `$ARGUMENTS` vacío
-
-### MCP server templates
-
-- Nuevo directorio `mcp/` con templates para servicios comunes
-- Templates iniciales: github, postgres, supabase, redis, slack
-- Cada template: `config.json` (entrada mergeable a mcpServers), `permissions.json` (allow/deny por tool), `rules.md` (reglas Claude-consumed con globs frontmatter)
-- `mcp/README.md`: instrucciones de instalación y composición
-- `mcp/_detect.md`: señales de detección para `/forge bootstrap`
-- `/forge bootstrap` detecta `mcpServers` en `~/.claude/settings.json` y sugiere instalar rules
-- Separación global/proyecto: mcpServers vive en `~/.claude/`, rules en `.claude/rules/mcp-<name>.md`
-
-### Model routing rules
-
-- Nuevo archivo `template/rules/model-routing.md`
-- Criterios explícitos para haiku / sonnet / opus por tipo de tarea
-- Los 7 agents actualizan su frontmatter `model:` con el modelo óptimo por rol:
-  - `researcher`, `test-runner` → haiku (velocidad sobre profundidad)
-  - `implementer`, `code-reviewer`, `session-reviewer` → sonnet (implementación estándar)
-  - `architect`, `security-auditor` → opus (razonamiento profundo, consecuencias altas)
-
----
-
-## v2.6.0 — CI/CD + Ecosystem automation
+## v2.6.0 — CI/CD + Ecosystem automation (próximo)
 
 Foco: integración con flujos de trabajo de PR y detección automática de cambios de stack.
 

ROADMAP.md

@@ -132,6 +132,18 @@ Enable: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
 - Each teammate = full session (~5x tokens)
 - Verify they don't edit the same files
 
+### Model selection
+
+Use the right model for the task — defined in `template/rules/model-routing.md`:
+
+- **haiku**: search, test execution, repetitive transforms, short lookups
+- **sonnet**: implementation, debugging, code review, documentation
+- **opus**: architecture decisions, security audits, ambiguous high-stakes tasks
+
+Escalate when: multiple valid approaches with real consequences, production/security risk, or unclear approach after 2 attempts.
+
+Agents have explicit model defaults. Override only when the task warrants it.
+
 ---
 
 ## 4. Project lifecycle
@@ -333,6 +345,18 @@ Activar: `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`
 - Cada teammate = sesión completa (~5x tokens)
 - Verificar que no editen los mismos archivos
 
+### Selección de modelo
+
+Usar el modelo correcto por tipo de tarea — definido en `template/rules/model-routing.md`:
+
+- **haiku**: búsquedas, ejecución de tests, transforms repetitivos, lookups cortos
+- **sonnet**: implementación, debugging, code review, documentación
+- **opus**: decisiones arquitectónicas, auditorías de seguridad, tareas ambiguas de alto impacto
+
+Escalar cuando: múltiples approaches válidos con consecuencias reales, riesgo en producción/seguridad, o approach poco claro después de 2 intentos.
+
+Los agentes tienen modelos explícitos por defecto. Overridear solo cuando la tarea lo justifica.
+
 ---
 
 ## 4. Ciclo de vida del proyecto

docs/best-practices.md

@@ -4,6 +4,20 @@
 >
 > Historial de versiones. Las entradas usan español/inglés mixto según la evolución del proyecto. Los términos técnicos son universales.
 
+## v2.5.0 (2026-03-21)
+
+### Learning Loop + MCP Templates + Model Routing
+
+- Nuevo: `/forge capture` modo auto-detección — sin args, analiza contexto de sesión, propone insight pre-formateado, pide confirmación Y/n/edit antes de guardar
+- Nuevo: `/cap` — alias shorthand para `/forge capture` (4 chars vs 14)
+- Nuevo: Regla proactiva en `template/rules/_common.md` — Claude sugiere `/cap` al detectar workaround, bug multi-intento, decisión con trade-offs, o comportamiento de API no-obvio
+- Nuevo: `mcp/` — templates de servidores MCP para github, postgres, supabase, redis, slack. Cada uno con config.json (mcpServers entry), permissions.json (allow/deny/prompt por tool), rules.md (reglas Claude-consumed). Auto-detectados por `/forge bootstrap`
+- Nuevo: `template/rules/model-routing.md` — criterios explícitos haiku/sonnet/opus por tipo de tarea, con tabla de escalation y MCP operations
+- Cambio: 7 agents con modelo explícito — researcher/test-runner=haiku, implementer/code-reviewer/session-reviewer=sonnet, architect/security-auditor=opus. Anterior: todos en `model: inherit`
+- ROADMAP reescrito: documenta v2.4.0 completado, v2.5.0 completado, v2.6.0 próximo, descartados
+
+---
+
 ## v2.4.0 (2026-03-21)
 
 ### Init, Unregister, Auto-update, Privacy

docs/changelog.md

@@ -205,3 +205,16 @@ stacks/redis/
 ```
 
 Detección en bootstrap: `redis` aparece en `requirements.txt` o `pyproject.toml`.
+
+## Stacks vs MCP templates
+
+Stacks and MCP server templates are complementary, not alternatives:
+
+| | Stack | MCP template |
+|---|---|---|
+| **What it provides** | Rules, permissions, hooks for local code | Config, permissions, rules for external services |
+| **Location** | `stacks/<name>/` | `mcp/<name>/` |
+| **Installed to** | `.claude/rules/` + `.claude/settings.json` | `.claude/rules/mcp-<name>.md` + permissions |
+| **When to use** | Your code uses this technology | Claude uses this external service via MCP |
+
+Example: A project using Redis locally AND the Redis MCP server would use **both**: the `redis` stack (rules for writing Redis code) and `mcp/redis/` (rules for using Redis tools in Claude sessions).

docs/creating-stacks.md

@@ -1,8 +1,12 @@
-# Roadmap claude-kit v1.0.0 → v2.0.0
+# Roadmap claude-kit — Historical (v1.0.0 → v2.5.0)
 
-> Development roadmap. Entries use mixed Spanish/English. See [changelog.md](changelog.md) for completed items.
+> **This document is the historical development roadmap used during v1.x and v2.x development.**
+> For the current roadmap and upcoming features, see [ROADMAP.md](../ROADMAP.md).
+> For completed version history, see [changelog.md](changelog.md).
 >
-> Hoja de ruta de desarrollo. Las entradas usan español/inglés mixto. Ver [changelog.md](changelog.md) para items completados.
+> **Este documento es el roadmap histórico de desarrollo usado durante v1.x y v2.x.**
+> Para el roadmap actual y features próximas, ver [ROADMAP.md](../ROADMAP.md).
+> Para el historial de versiones completadas, ver [changelog.md](changelog.md).
 
 ## Vision / Visión
 

docs/roadmap.md

@@ -121,3 +121,30 @@ chmod +x .claude/hooks/*.sh
    - El hook evita duplicados por día
 
 **Fix:** Instalar manualmente el hook global siguiendo las instrucciones en el script.
+
+## MCP server tools not available
+
+**Symptom:** Claude can't use GitHub/Postgres/Supabase tools even though the MCP server is configured.
+
+**Checklist:**
+1. Is the server registered in `~/.claude/settings.json` under `mcpServers`?
+2. Is the required env var set? (`GITHUB_TOKEN`, `DATABASE_URL`, `SUPABASE_ACCESS_TOKEN`)
+3. Is the npm package installed or accessible via `npx`?
+
+**Fix:** Copy the `mcpServers` entry from `mcp/<server>/config.json` into `~/.claude/settings.json`.
+
+## MCP tool denied unexpectedly
+
+**Symptom:** Claude says a tool is blocked when you expected it to work.
+
+**Cause:** The tool appears in the `deny` list in `.claude/settings.json` from the template in `mcp/<server>/permissions.json`.
+
+**Fix:** Review `mcp/<server>/permissions.json`. Move the tool from `deny` to `allow` (or remove from deny) in `.claude/settings.json` if appropriate for your project.
+
+## /cap or /forge capture auto-detect finds nothing
+
+**Symptom:** Running `/cap` returns "No generalizable insight detected in this session."
+
+**Cause:** The skill looks for specific signals (workaround, multi-attempt bug, arch decision, non-obvious API behavior). Routine sessions with clean first-attempt solutions won't trigger.
+
+**Fix:** Use `/cap "description"` with explicit text. Auto-detect is for non-trivial sessions only.

docs/troubleshooting.md

@@ -1,7 +1,7 @@
 # Usage Guide — claude-kit
 
-**Version:** 2.0.0
-**Date:** 2026-03-20
+**Version:** 2.5.0
+**Date:** 2026-03-21
 
 claude-kit is a configuration factory for Claude Code. It generates and maintains the `.claude/` folder of your projects: rules, hooks, permissions, agents, and commands. Everything is markdown + shell scripts — no application code.
 
@@ -21,6 +21,8 @@ claude-kit is a configuration factory for Claude Code. It generates and maintain
 10. [Generated structure](#10-generated-structure)
 11. [Config validation](#11-config-validation)
 12. [FAQ](#12-faq)
+13. [MCP server templates](#13-mcp-server-templates)
+14. [Model routing](#14-model-routing)
 
 ---
 
@@ -46,7 +48,7 @@ cd ~/Documents/GitHub/claude-kit   # or wherever you cloned claude-kit
 | Component | Location | Method |
 |-----------|----------|--------|
 | Skills (15) | `~/.claude/skills/` | Symlinks |
-| Agents (6) | `~/.claude/agents/` | Symlinks |
+| Agents (7) | `~/.claude/agents/` | Symlinks |
 | `/forge` command | `~/.claude/commands/forge.md` | Copy (Claude Code does not follow symlinks for commands) |
 | Global CLAUDE.md | `~/.claude/CLAUDE.md` | Merge with `<!-- forge:custom -->` preservation |
 | Global settings.json | `~/.claude/settings.json` | Merge of deny list + hooks |
@@ -65,7 +67,7 @@ Output:
 CLAUDE.md:     OK synced
 settings.json: deny list 9 items (template: 9)
 Skills:        15/15 installed
-Agents:        6/6 installed
+Agents:        7/7 installed
 Commands:      forge.md (file)
 ```
 
@@ -277,7 +279,9 @@ Deletes `.claude/` and re-runs a full bootstrap. But:
 
 | Command | Description |
 |---------|-------------|
-| `/forge capture "text"` | Record an insight in inbox |
+| `/forge capture "text"` | Record an insight in inbox (explicit) |
+| `/forge capture` | Auto-detect mode: analyzes session context, proposes insight, asks Y/n/edit before saving |
+| `/cap` | Shorthand alias for `/forge capture` (auto-detect mode) |
 | `/forge update` | Process inbox -> evaluate -> incorporate |
 | `/forge watch` | Check for updates in Anthropic docs |
 | `/forge scout` | Review curated repos for patterns |
@@ -425,7 +429,7 @@ Last update: 2026-03-20
 | Rules (_common + stack) | Y | Y | Y |
 | Hook lint-on-save | -- | Y | Y |
 | Commands (audit, health, debug, review) | -- | Y | Y |
-| Agents (6) + orchestration | -- | Y | Y |
+| Agents (7) + orchestration | -- | Y | Y |
 | CLAUDE_ERRORS.md | -- | Y (empty) | Y (pre-populated) |
 | Rule memory.md | -- | Y | Y |
 | Hook warn-missing-test | -- | -- | Y |
@@ -617,6 +621,73 @@ No. With the `minimal` profile they are not installed. With `standard` and `full
 
 ---
 
+## 13. MCP server templates
+
+MCP servers extend Claude Code with tools for external services. claude-kit provides ready-to-use templates in `mcp/` covering configuration, permissions, and usage rules.
+
+### Available templates
+
+| Server | Package | Tools |
+|--------|---------|-------|
+| `github` | `@modelcontextprotocol/server-github` | Issues, PRs, code search, file contents |
+| `postgres` | `@modelcontextprotocol/server-postgres` | Read-only SQL queries, schema inspection |
+| `supabase` | `@supabase/mcp-server-supabase` | Projects, tables, migrations, branches, logs |
+| `redis` | `mcp-server-redis` (community) | Key inspection, stream monitoring |
+| `slack` | `@modelcontextprotocol/server-slack` | Messages, channels, search |
+
+### Installation
+
+**Step 1 — Register the server globally (once per machine):**
+Copy the `mcpServers` entry from `mcp/<server>/config.json` into `~/.claude/settings.json`. Replace `${ENV_VAR}` with real values or set env vars in your shell profile.
+
+**Step 2 — Install project rules:**
+```bash
+cp mcp/<server>/rules.md .claude/rules/mcp-<server>.md
+```
+
+Or let `/forge bootstrap` handle it automatically — it detects configured `mcpServers` in `~/.claude/settings.json` and offers to install matching rule templates.
+
+### Security posture
+
+Each template defines three tiers:
+- **Auto-allowed**: read operations (list, get, search)
+- **Prompt required**: write operations not in allow or deny lists
+- **Always denied**: destructive operations (delete_project, merge_pull_request, flushdb)
+
+See [mcp/README.md](../mcp/README.md) for full documentation.
+
+---
+
+## 14. Model routing
+
+claude-kit includes explicit model selection criteria in `template/rules/model-routing.md`. Every bootstrapped project gets this rule, which guides both direct Claude work and subagent instantiation.
+
+### Criteria
+
+| Model | Use for |
+|-------|---------|
+| **haiku** | File search, grepping, running tests, repetitive transformations, short factual questions |
+| **sonnet** | Feature implementation, bug fixing (known root cause), code review, standard debugging, docs |
+| **opus** | Architecture decisions with real tradeoffs, security audits, ambiguous tasks, production-risk operations |
+
+### Agent assignments
+
+| Agent | Model | Reason |
+|-------|-------|--------|
+| researcher | haiku | Exploration — speed over depth |
+| test-runner | haiku | Execute and report — no reasoning needed |
+| implementer | sonnet | Standard implementation work |
+| code-reviewer | sonnet | Focused review, single concern |
+| session-reviewer | sonnet | Pattern analysis, not architecture |
+| architect | opus | Tradeoffs with lasting consequences |
+| security-auditor | opus | Missing a vulnerability has prod consequences |
+
+### Escalation rule
+
+Start with sonnet. Escalate to opus when: 2+ valid approaches with real consequences for choosing wrong, task touches security/data integrity/production systems, or after 2 attempts the approach is still unclear.
+
+---
+
 ## Full visual flow
 
 ```