agentforge-py 0.2.1__py3-none-any.whl

agentforge/templates/_shared/docs/runbooks/01-set-up-new-agent.md.tmpl

@@ -0,0 +1,67 @@
+# 01 — Set up a new AgentForge agent
+
+> **Goal:** verify the freshly scaffolded `{{ project_slug }}`
+> agent runs end-to-end against your provider.
+> **Time:** ~10 minutes.
+> **Prereqs:** none (this is runbook 01).
+
+## TL;DR
+
+```bash
+cd {{ project_slug }}
+uv sync
+cp .env.example .env       # then fill in real credentials
+agentforge config validate
+agentforge run "hello"
+```
+
+## Step by step
+
+1. **Install dependencies** with `uv sync`. AgentForge uses uv
+   workspaces; the lock file pins every version.
+2. **Configure credentials** by copying `.env.example` to `.env`
+   and filling in the LLM provider's API key (`ANTHROPIC_API_KEY`,
+   `AWS_ACCESS_KEY_ID`, or `OPENAI_API_KEY` depending on what
+   you scaffolded). Never check `.env` into git.
+3. **Validate the config** with `agentforge config validate`.
+   That parses `agentforge.yaml`, expands `${ENV_VAR}` references,
+   and surfaces any unknown keys.
+4. **Run the agent** with `agentforge run "your first task"`.
+   The default output is rich-formatted; pass `--output-format
+   json` for structured output (handy in CI).
+5. **Check the trace** — every step the agent emitted is on the
+   returned `RunResult`. `agentforge run --record "..."` followed
+   by `agentforge debug --replay <run-id>` lets you step through.
+
+## Variations
+
+- **Different provider** — edit `agentforge.yaml > providers >
+  default` to point at the provider you prefer, then update
+  `.env` accordingly. See runbook 13 for multi-provider setups.
+- **No credentials yet** — `MockLLMClient.deterministic("ok")`
+  in your own tests lets you exercise the loop without hitting
+  a real API (see runbook 06).
+- **Batch / CI mode** — `agentforge run --no-prompts --task-file
+  ./task.txt --output-format json` is the script-friendly path.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `agentforge: command not found` | uv venv isn't activated | `uv sync` then prefix commands with `uv run` |
+| `config invalid` exit code 2 | unknown YAML key | check the diff between your `agentforge.yaml` and `agentforge config schema` output |
+| `No LLM provider registered` | provider package not installed | `agentforge add module <provider>` (e.g. `agentforge add module bedrock`) |
+| `BudgetExceeded` on first run | budget too low for the model | bump `agent.budget.usd` in `agentforge.yaml` |
+
+## Related
+
+- Runbook 02 — Add a tool
+- Runbook 06 — Test your agent
+- Runbook 13 — Configure multi-provider
+- Feature spec: `docs/features/feat-011-scaffolding-and-upgrade.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- Project-specific setup notes go here. Survives upgrades. -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/02-add-a-tool.md

@@ -0,0 +1,67 @@
+# 02 — Add a tool
+
+> **Goal:** make a new capability available to your agent's
+> reasoning loop.
+> **Time:** ~10 minutes.
+> **Prereqs:** runbook 01 done.
+
+## TL;DR
+
+```python
+from agentforge import tool
+
+@tool
+async def fetch_weather(*, city: str) -> str:
+    """Return the current weather summary for `city`."""
+    return await my_weather_api(city)
+
+agent = Agent(model="...", tools=[fetch_weather])
+```
+
+## Step by step
+
+1. **Decide tool surface** — what kwargs does the LLM pass? Each
+   becomes a typed parameter on the function. Use Pydantic models
+   only when the inputs are nested.
+2. **Author the tool** with the `@tool` decorator. Type hints
+   drive the JSON schema the LLM sees; do NOT hand-write a schema.
+3. **Add a docstring** — the first line is what the LLM reads to
+   decide when to call your tool. Keep it short and behaviour-
+   focused: "Returns X given Y", not "This tool will...".
+4. **Pass the tool to `Agent(tools=[...])`** or list it under
+   `agent.tools:` in `agentforge.yaml` so it's auto-resolved on
+   `agentforge run`.
+5. **Cover with a test** — instantiate via `FakeTool.fake(...)`
+   for tests where the real call would be too slow / costly
+   (see runbook 06).
+
+## Variations
+
+- **Class-based tool** — subclass `Tool` directly when you need
+  per-instance state (DB pool, HTTP client). Pattern in
+  `agentforge_core.contracts.tool`.
+- **Destructive tools** — set `capabilities: ClassVar = frozenset
+  ({"destructive"})` on the class. The `capability_check`
+  guardrail (runbook 11) will deny it unless allowlisted.
+- **Long-running tools** — return early with a status; let the
+  next iteration check completion. Don't `await` for 30 seconds.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| LLM never calls the tool | docstring too vague | rewrite to be behaviour-focused: "Fetches X for Y" |
+| `ValidationError` on tool call | type hints don't match LLM args | check the JSON schema with `tool.to_spec()` |
+| Tool runs but observation lost | tool returns `None` | return a string (or a dict; the framework JSON-serialises) |
+| Tool ran twice unexpectedly | LLM retried | check the previous observation surfaced clearly; vague observations cause retries |
+
+## Related
+
+- Runbook 06 — Test your agent (covers `FakeTool.fake`)
+- Runbook 11 — Add safety guardrails (capability gating)
+- Feature spec: `docs/features/feat-004-tools-system.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/03-add-a-pipeline-task.md

@@ -0,0 +1,69 @@
+# 03 — Add a pipeline task
+
+> **Goal:** insert a deterministic, non-LLM step into the agent's
+> workflow (e.g. parse a file, call a metric API, normalise
+> input).
+> **Time:** ~15 minutes.
+> **Prereqs:** runbook 02 (you understand tools).
+
+## TL;DR
+
+```python
+from agentforge import Pipeline, Task
+
+class FetchPRMetadata(Task):
+    async def run(self, *, pr_url: str) -> dict:
+        return await my_github_client.get_pr(pr_url)
+
+pipeline = Pipeline([FetchPRMetadata, AgentStep, RenderReport])
+```
+
+## Step by step
+
+1. **Identify deterministic boundaries** — anything that has a
+   stable function from inputs to outputs (file parsing, API
+   normalisation, score thresholding) is a Task, not an LLM call.
+2. **Author the Task** — subclass `Task`; declare typed inputs
+   and outputs; `async def run(...)` is the body.
+3. **Compose** with `Pipeline([T1, T2, T3])` — tasks run in
+   order, each receiving the previous one's output.
+4. **Mix LLM steps** — use the framework's `AgentStep` wrapper
+   to drop an agent run into a pipeline; the surrounding tasks
+   handle deterministic pre/post processing.
+5. **Capture failures** — Tasks raise `TaskError` for
+   recoverable cases; the framework surfaces it as a step in
+   the agent's trace.
+
+## Variations
+
+- **Parallel tasks** — `Pipeline.parallel([T1, T2])` runs them
+  concurrently and joins their outputs into a dict.
+- **Conditional branching** — wrap with `Pipeline.branch(
+  condition_fn, true_pipe, false_pipe)`.
+- **Retry** — set `retries=N` on the Task class; the framework
+  re-runs with exponential backoff.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Task output not visible to LLM | task didn't make output visible to the agent step | thread output through `AgentStep`'s task context |
+| Pipeline fails fast on first error | default behaviour | wrap with `Pipeline.tolerant(...)` for best-effort runs |
+| Memory blows up on large pipelines | task results held in RAM | persist intermediate outputs to memory store (runbook 08) |
+
+## Related
+
+- Runbook 02 — Add a tool (different shape: tools are LLM-
+  invoked, tasks are deterministic)
+- Runbook 08 — Add memory
+- Feature spec: `docs/features/feat-015-pipelines-and-deterministic-tasks.md`
+
+> **Note:** Pipelines + Tasks are feat-015 territory. If your
+> framework version pre-dates that feature, this runbook is
+> aspirational — fall back to wrapping deterministic steps as
+> tools.
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/04-pick-reasoning-strategy.md

@@ -0,0 +1,67 @@
+# 04 — Pick a reasoning strategy
+
+> **Goal:** choose the right `ReasoningStrategy` for your task.
+> **Time:** ~5 minutes.
+> **Prereqs:** runbook 01 done.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+agent:
+  strategy: react              # default — most agents stay here
+  # strategy: plan-execute     # multi-step plans with verification
+  # strategy: tree-of-thoughts # search over candidate paths
+  # strategy: multi-agent      # supervisor + worker fan-out
+```
+
+## Step by step
+
+1. **Default to ReAct.** It's the simplest stable loop: think →
+   act → observe. Most agent failures come from prompts or
+   tools, not the loop itself. Switching strategies on Day 1 is
+   premature.
+2. **Move to Plan-Execute** when the task naturally decomposes
+   into a plan + execution: code reviewers, multi-file edits,
+   research with structured outputs.
+3. **Move to Tree-of-Thoughts** when you have a verifier and
+   need to explore multiple candidate paths. Expensive — only
+   when the task warrants it.
+4. **Move to Multi-Agent** when distinct sub-agents have
+   meaningfully different system prompts / tool sets (security
+   reviewer + style reviewer + correctness reviewer).
+5. **Measure before switching** — runbook 10 covers evaluators.
+   Don't change strategy without a baseline.
+
+## Variations
+
+- **Custom strategy** — subclass `ReasoningStrategy` and
+  register via `@register("strategies", "my-name")`. Run
+  `run_strategy_conformance` from `agentforge.testing` against
+  it.
+- **Iteration cap** — `agent.max_iterations` (default 25) is
+  enforced by every shipped strategy; ToT respects it
+  per-branch.
+- **Budget reservation** — strategies coordinate with
+  `BudgetPolicy` automatically; you don't need to thread cost
+  manually.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Agent loops indefinitely | tool observations too vague to make progress | improve tool docstrings + observation strings |
+| `iteration_cap` finish_reason | max_iterations too low | bump it or switch to Plan-Execute |
+| Plan-Execute "plan" step is junk | system prompt didn't give planning hints | seed examples in the prompt; runbook 05 |
+| ToT cost spike | verifier too lenient, expanding too many branches | tighten verifier prompt; cap `max_branches` |
+
+## Related
+
+- Runbook 05 — Write prompts
+- Runbook 10 — Add evaluators (baseline before switching)
+- Feature spec: `docs/features/feat-002-reasoning-strategies.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/05-write-prompts.md

@@ -0,0 +1,75 @@
+# 05 — Write prompts
+
+> **Goal:** author a system prompt that produces consistent
+> agent behaviour.
+> **Time:** ~20 minutes.
+> **Prereqs:** runbook 01 done.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+agent:
+  system_prompt_file: ./prompts/system.md
+```
+
+```markdown
+<!-- prompts/system.md -->
+You are a {{ role }}. Your job is {{ goal }}.
+
+## Tools
+You have these tools available: {{ tool_summary }}.
+Use them only when you cannot answer from existing context.
+
+## Output
+Produce a `SimpleFinding` object with severity in {low, medium, high}.
+
+## Style
+Be concise. Cite sources. Refuse silently if asked to bypass safety.
+```
+
+## Step by step
+
+1. **Start with a role + goal sentence.** Two sentences is
+   enough. Long preambles dilute the rest of the prompt.
+2. **List tools and their purpose.** The LLM already knows the
+   schemas (the framework injects them). What it doesn't know
+   is *when* to prefer one over another. Tell it.
+3. **Define output shape** — point at the finding variant
+   (`SimpleFinding`, `PatchFinding`, etc.) you want. The
+   framework will enforce it via the configured renderer.
+4. **Pin style** — concise, cite, refuse-silently. Models
+   respect concrete style rules more than vibe descriptors.
+5. **Iterate on examples.** Add 1-3 worked examples for hard
+   cases. Examples are cheaper than rule-tweaking.
+
+## Variations
+
+- **Per-strategy prompts** — multi-agent supervisors carry a
+  separate prompt under `agent.workers.<role>.system_prompt`.
+- **Tool-specific framing** — for tools whose names are
+  ambiguous, restate intent at point of use: "Call `lookup_user`
+  with the email from the issue body".
+- **Dynamic context** — use Jinja in the prompt file; the
+  framework expands `{{ runtime_context.user }}` etc. at run
+  time.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| Output drifts from the schema | prompt over-emphasises prose | move output-shape rule to the top |
+| Model refuses to answer | safety phrasing too defensive | tone down "you must never..." → "decline politely when..." |
+| Repeated tool calls with same args | tool docstring + system prompt disagree | reconcile; the docstring wins for the LLM |
+| Verbose, low-signal responses | no concision rule | add "respond in ≤ 200 words" |
+
+## Related
+
+- Runbook 02 — Add a tool (tool docstrings)
+- Runbook 10 — Add evaluators (measure prompt impact)
+- Feature spec: `docs/features/feat-008-findings-and-output-shapes.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/06-test-your-agent.md

@@ -0,0 +1,75 @@
+# 06 — Test your agent
+
+> **Goal:** unit-test your agent without hitting a real LLM or
+> network.
+> **Time:** ~15 minutes.
+> **Prereqs:** runbook 02 (you have at least one tool).
+
+## TL;DR
+
+```python
+import pytest
+from agentforge.testing import MockLLMClient, FakeTool, agent_factory
+
+@pytest.mark.asyncio
+async def test_population_lookup() -> None:
+    llm = MockLLMClient.from_script([
+        {"text": "Looking up.",
+         "tool_calls": [{"name": "search", "args": {"q": "Spain"}}]},
+        {"text": "47.5M", "stop_reason": "end_turn"},
+    ])
+    web = FakeTool.fake("search", lambda **kw: "47.5M people")
+    agent = agent_factory(model=llm, tools=[web])
+    result = await agent.run("How many in Spain?")
+    assert "47.5M" in result.output
+```
+
+## Step by step
+
+1. **Use `MockLLMClient.from_script(...)`** for tests that need
+   to drive specific LLM responses. `deterministic("ok")` works
+   when you only care that the loop completes.
+2. **Stub tools with `FakeTool.fake(name, fn)`** — accepts a
+   static value or a callable. Preserves the real tool's
+   `name` so the LLM sees the same surface.
+3. **Use `agent_factory(...)`** instead of raw `Agent(...)`. It
+   bakes in safe defaults (in-memory store, no log filter
+   mutation, low budget) so tests stay isolated.
+4. **Assert on `result.output`** for the answer, and on
+   `mock_llm.tool_calls_observed` for the LLM's tool-use
+   sequence. Both are cheaper than parsing trace strings.
+5. **Record once, replay forever.** For tests that exercise a
+   real provider response, `record_llm(real, "cassette.jsonl")`
+   captures it; subsequent runs use
+   `MockLLMClient.from_recording(...)`.
+
+## Variations
+
+- **Property-based tests** — pair `agent_factory` with Hypothesis
+  strategies for input fuzzing.
+- **Golden sets** — `agentforge-testing` ships
+  `GoldenSetRunner.from_jsonl(...)`; fixture lines hold
+  `task` + `expected` (exact / contains / regex / any_of).
+- **Snapshot rendering** — `assert_snapshot(text, path)` for
+  scorecard / patch output. `UPDATE_SNAPSHOTS=1 pytest`
+  re-records.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `MockLLMClient exhausted` | the agent made more LLM calls than scripted | extend the script or relax with `deterministic` |
+| Test runs hit a real API | imported the real client by accident | wrap construction in `agent_factory(model=mock_llm)` |
+| Stub-tool not invoked | name mismatch between FakeTool and what the script says the LLM called | both must use the same `name=` value |
+| Flaky asyncio teardown warning | event-loop GC noise on macOS | already filtered in pyproject; safe to ignore |
+
+## Related
+
+- Runbook 02 — Add a tool
+- Runbook 10 — Add evaluators
+- Feature spec: `docs/features/feat-016-testing-framework.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/07-debug-a-run.md

@@ -0,0 +1,70 @@
+# 07 — Debug a run
+
+> **Goal:** reproduce a failed run locally and step through what
+> the agent saw.
+> **Time:** ~15 minutes.
+> **Prereqs:** runbooks 01 + 06.
+
+## TL;DR
+
+```bash
+# In the offending env (or anywhere with a recorded run):
+agentforge run --record "the failing task"
+# Note the printed run_id, then:
+agentforge debug --replay <run_id>
+> step
+> state
+> inspect tool_call.arguments
+> quit
+```
+
+## Step by step
+
+1. **Reproduce with recording.** `agentforge run --record "..."`
+   persists every `Step` to the configured memory store under
+   `category="__step"`. Without `--record`, the trace dies with
+   the process.
+2. **Pick the run_id.** It prints to stdout at run end (also
+   present on `RunResult.run_id`).
+3. **Open the REPL** with `agentforge debug --replay <run_id>`.
+   Reads from memory; no LLM call required.
+4. **Step + inspect.** `step` advances; `state` prints the
+   current step's payload; `inspect <dotted-path>` drills in
+   (`inspect tool_call.arguments`). `back` rewinds; `steps`
+   lists the whole trace.
+5. **Bisect.** If the failure is in step 17 of 22, `--to-step
+   N` on `agentforge run --replay` re-runs the loop up to step
+   N with the recorded LLM responses and stops.
+
+## Variations
+
+- **Replay tools** — `replay_tools(memory, run_id, [your_tools])`
+  returns wrappers whose `run()` returns the recorded
+  observation. Pair with `ReplayLLMClient.from_recording(...)`
+  for byte-identical replays.
+- **Cassette replay** — `agentforge run --replay <run_id> --to-
+  step 5` is the CLI surface around the same primitives.
+- **Tracing** — the OTel root span ID is in
+  `RunResult.metadata` if observability is enabled (runbook 12);
+  cross-reference with your APM dashboard.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No recorded steps for run_id` | run was not recorded | add `--record` next reproduction; configure `modules.memory` |
+| Replay diverges from original | tool or LLM args drifted | use `ReplayLLMClient.from_recording` AND `replay_tools` together |
+| REPL EOF errors | piped stdin without newline | append `\n` to the scripted input |
+| `ReplayExhausted` | trying to replay further than recorded | task changed; re-record with the new task |
+
+## Related
+
+- Runbook 06 — Test your agent
+- Runbook 08 — Add memory (recording lives in the memory store)
+- Feature spec: `docs/features/feat-017-cli-runtime.md` (debug,
+  replay)
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/08-add-memory.md

@@ -0,0 +1,75 @@
+# 08 — Add memory / persistence
+
+> **Goal:** swap the default in-memory store for a durable
+> backend (SQLite / Postgres / Neo4j / SurrealDB).
+> **Time:** ~10 minutes.
+> **Prereqs:** runbook 01.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+modules:
+  memory:
+    driver: postgres
+    config:
+      dsn: "${DATABASE_URL}"
+      min_size: 1
+      max_size: 10
+```
+
+```bash
+agentforge add module memory-postgres
+agentforge db migrate
+```
+
+## Step by step
+
+1. **Pick a driver.** Default to SQLite for single-host
+   deployments; Postgres for managed-database / multi-writer;
+   Neo4j or SurrealDB if you need graph relationships
+   (supersede chains, finding lineage).
+2. **Install the module.** `agentforge add module memory-<driver>`
+   uses the framework's manifest applier (no manual pip).
+3. **Configure** under `modules.memory` in `agentforge.yaml`.
+   Use `${ENV_VAR}` interpolation for credentials — never put
+   them in the YAML literal.
+4. **Run schema migration** with `agentforge db migrate`. The
+   command is a no-op for drivers that create their schema
+   eagerly (in-memory, sqlite); a real DDL pass for postgres /
+   neo4j / surrealdb.
+5. **Verify** with `agentforge db query 'category:__step'` — if
+   your previous runs were recorded, you'll see step claims.
+
+## Variations
+
+- **Drop-in driver swap** — `agentforge swap memory sqlite
+  postgres` migrates the configuration; data migration is
+  separate (`agentforge db backup` then `db restore`).
+- **Multiple categories** — write your own claims via
+  `agent.memory.put(Claim(category="custom", ...))`. Reserved
+  categories (`__step`, `__eval`, `__run`) belong to the
+  framework.
+- **TTL** — drivers that declare the `ttl` capability honour
+  `agent.memory.set_ttl(...)`. Check with `agent.memory.supports
+  ("ttl")`.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `No module registered for memory:postgres` | driver not installed | `agentforge add module memory-postgres` |
+| `connection refused` | DSN points at the wrong host / port | check `${DATABASE_URL}` expansion via `agentforge config show --resolved` |
+| `delete() requires at least one filter` | called `memory.delete()` with no args | pass `run_id=` / `category=` / `older_than=` |
+| Schema version mismatch on upgrade | driver schema bumped | `agentforge db backup` → `agentforge db migrate` → `agentforge db restore` |
+
+## Related
+
+- Runbook 14 — Deploy your agent (DSN secret management)
+- Runbook 15 — Upgrade your agent (schema migrations)
+- Feature spec: `docs/features/feat-005-persistence-and-memory.md`
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->

agentforge/templates/_shared/docs/runbooks/09-add-mcp.md

@@ -0,0 +1,78 @@
+# 09 — Add MCP servers
+
+> **Goal:** consume Anthropic Model Context Protocol tool servers
+> as if they were native tools, or expose your agent's tools as
+> an MCP server.
+> **Time:** ~10 minutes.
+> **Prereqs:** runbook 02.
+
+## TL;DR
+
+```yaml
+# agentforge.yaml
+modules:
+  protocols:
+    - name: mcp
+      config:
+        servers:
+          - command: ["uv", "run", "filesystem-mcp"]
+            cwd: ./mcp-servers
+        expose_local_tools: true     # turn this agent into an MCP server too
+```
+
+```bash
+agentforge add module mcp
+```
+
+## Step by step
+
+1. **Install the MCP module.** `agentforge add module mcp` —
+   adds `agentforge-mcp` to dependencies and registers the
+   protocol under `modules.protocols`.
+2. **Declare upstream servers.** `servers:` is a list of command
+   specifications. Each spawns on agent start; the framework
+   handles handshake and tool discovery.
+3. **Restart the agent.** Discovered MCP tools appear in the
+   agent's tool list automatically; the LLM sees their schemas
+   alongside framework-native tools.
+4. **(Optional) Expose your tools.** `expose_local_tools: true`
+   makes this agent's tools available as an MCP server, so other
+   agents (or Claude Desktop) can call into it.
+5. **Verify** with `agentforge list tools` — MCP tools have an
+   `mcp:` prefix in the resolver listing.
+
+## Variations
+
+- **Per-server allowlist** — `servers[].tools: ["read_file",
+  "list_directory"]` restricts what gets exposed from each
+  server. Use this for least-privilege.
+- **Auth headers** — `servers[].auth.bearer: "${MCP_TOKEN}"` for
+  hosted MCP servers behind auth.
+- **Capability negotiation** — `expose_local_tools.exclude:
+  [...]` strips internal tools from the exposed MCP surface.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| MCP server fails to spawn | wrong command path | check `agentforge config show --resolved` matches your shell's view |
+| Tools not visible to LLM | discovery race | bump `servers[].start_timeout` (default 5s) |
+| Tool calls hang | MCP server blocking on stdio | check the server's logs; MCP requires line-delimited JSON |
+| `permission denied` from exposed server | client passed a tool not in allowlist | add to `expose_local_tools.tools` or remove the deny |
+
+## Related
+
+- Runbook 02 — Add a (native) tool
+- Runbook 11 — Add safety guardrails (MCP tools go through the
+  same gates)
+- Feature spec: `docs/features/feat-013-mcp-integration.md`
+
+> **Note:** MCP integration is feat-013. If this framework
+> version pre-dates the module shipping, install
+> `agentforge-mcp` manually from the framework repo's
+> `packages/`.
+
+<!-- agentforge:end-managed -->
+
+<!-- agentforge:custom -->
+<!-- agentforge:end-custom -->