docs: link every capability README to its source module + enforce it

CodeRabbit re-flagged planning/README.md for a missing source link. Only
guardrails had one, so add the source-module link to all 15 remaining
capability READMEs (matching the doc pages) and add a parity test so the
requirement is mechanical and cannot silently regress.

pydantic_ai_harness/code_mode/README.md

@@ -2,6 +2,8 @@
 
 Replace individual tool calls with a single sandboxed Python execution environment.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/code_mode/)
+
 ## The problem
 
 Standard tool calling requires one model round-trip per tool call. An agent that needs to fetch 10 items and process each one makes 11+ model calls -- slow, expensive, and context-heavy.

pydantic_ai_harness/compaction/README.md

@@ -17,6 +17,8 @@ steps (it is not recomputed from the full history every turn).
 All strategies preserve tool-call / tool-return **pairing** -- core does not validate this, and a
 provider rejects an orphaned pair. The zero-LLM strategies never call a model.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/compaction/)
+
 ## The menu
 
 | Capability | Cost | What it does | Reach for it when |

pydantic_ai_harness/context/README.md

@@ -11,6 +11,8 @@
 
 Discover and load a repo's accumulated coding-assistant context engineering (CE).
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/context/)
+
 ## The problem
 
 A repo accumulates CE for whatever coding assistant worked in it: instruction

pydantic_ai_harness/docs/README.md

@@ -11,6 +11,8 @@
 
 Give an agent a tool that locates and returns Pydantic AI documentation on demand.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/docs/)
+
 ## The problem
 
 An agent that authors Pydantic AI capabilities, hooks, tools, or toolsets needs the

pydantic_ai_harness/dynamic_workflow/README.md

@@ -13,6 +13,8 @@ Let one agent coordinate a whole team of sub-agents by writing a small Python sc
 > The extensions planned in [What is coming](#what-is-coming), structured sub-agent inputs and durable
 > workflows, touch the sub-agent call contract itself.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/dynamic_workflow/)
+
 ## The idea
 
 Say you have a few specialist agents. One reviews code. One summarizes findings. One writes the

pydantic_ai_harness/experimental/acp/README.md

@@ -21,6 +21,8 @@
 
 Expose a Pydantic AI agent to editors and terminal UIs over the [Agent Client Protocol](https://agentclientprotocol.com).
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/experimental/acp/)
+
 ## The problem
 
 Editors like [Zed](https://zed.dev/docs/ai/external-agents) speak ACP: a stdio JSON-RPC protocol that lets a TUI or editor drive an external coding agent -- streaming its text, rendering its file edits as diffs, and prompting the user to approve sensitive tool calls. To plug a Pydantic AI agent into one of these editors you would otherwise have to implement the ACP server side yourself.

pydantic_ai_harness/filesystem/README.md

@@ -2,6 +2,8 @@
 
 Give an agent sandboxed, pattern-filtered access to a directory tree.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/filesystem/)
+
 ## The problem
 
 Letting an agent touch the filesystem directly is risky: path traversal

pydantic_ai_harness/logfire/README.md

@@ -9,6 +9,8 @@ Install the extra:
 pip install 'pydantic-ai-harness[logfire]'
 ```
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/logfire/)
+
 ## `ManagedPrompt`
 
 Back an agent's instructions with a Logfire-managed

pydantic_ai_harness/media/README.md

@@ -19,6 +19,8 @@ Content-addressed stores and walker helpers that move large binary payloads out
 
 These are building blocks, not a capability. There is no class you add to `Agent(capabilities=[...])` yet. [`StepPersistence`](../step_persistence/) uses them to keep snapshots small when messages carry `BinaryContent`. A forthcoming `MediaExternalizer` capability will reuse the same stores to rewrite `BinaryContent` into URL parts before the model sees them.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/media/)
+
 ## Why
 
 A conversation that carries images, audio, or other `BinaryContent` inlines those bytes into every message. Persist that history and each snapshot re-serializes the payloads. Content-addressed storage writes each payload once, keyed by its own hash, and leaves a short `media://` URI in its place. The same bytes are stored once no matter how many messages or snapshots reference them.

pydantic_ai_harness/overflowing_tool_output/README.md

@@ -19,6 +19,8 @@ This is the overflow-to-file follow-up the `compaction` README names as out of s
 moves large tool outputs *out* of the window at production time, rather than compressing or
 dropping context already inside it.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/overflowing_tool_output/)
+
 ## The three modes
 
 | Mode | Cost | Lossy? | What the model gets |

pydantic_ai_harness/planning/README.md

@@ -11,6 +11,8 @@
 
 Give an agent a structured, self-updating task plan -- without ever invalidating the prompt cache.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/planning/)
+
 ## The problem
 
 Long agentic runs drift: the model loses track of what it set out to do and what's left. The usual fix -- keep a running plan and re-inject it into the system prompt each turn -- invalidates the prompt cache. The system prompt sits at the front of the request, so every plan edit changes the cached prefix and forces the whole conversation to be re-processed at full token price.

pydantic_ai_harness/runtime_authoring/README.md

@@ -11,6 +11,8 @@
 
 Let an agent author, validate, and persist real pydantic-ai capabilities at runtime.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/runtime_authoring/)
+
 ## The problem
 
 A coding agent often discovers, mid-task, that it wants a behavior its host does not

pydantic_ai_harness/shell/README.md

@@ -3,6 +3,8 @@
 Give an agent the ability to run shell commands, with allow/deny controls and
 managed background processes.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/shell/)
+
 ## The problem
 
 Agents frequently need to run a build, a test suite, a linter, or a quick

pydantic_ai_harness/step_persistence/README.md

@@ -21,6 +21,8 @@ It is not a full graph-state checkpoint. Capability-state restore, workspace
 snapshots, and graph-node resume are out of scope and tracked separately
 (see `pydantic-ai-harness` issues #149 and #196).
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/step_persistence/)
+
 ## What it gives you
 
 1. **Append-only step events** -- every interesting boundary (run start/end,

pydantic_ai_harness/subagents/README.md

@@ -11,6 +11,8 @@
 
 Let an agent delegate self-contained tasks to named child agents.
 
+[Source](https://github.com/pydantic/pydantic-ai-harness/tree/main/pydantic_ai_harness/subagents/)
+
 ## The problem
 
 A single agent that does everything accumulates a large tool set and a long context. Splitting the work across specialized sub-agents keeps each context focused, but wiring up delegation by hand means writing a tool per agent, forwarding deps, threading usage limits, and telling the model what it can delegate to.

tests/test_docs_parity.py

@@ -293,3 +293,14 @@ def test_graduated_doc_page_has_no_experimental_framing(page: Path) -> None:
 def test_capability_readme_heading_matches_capability(package: Path) -> None:
     problem = _heading_problem(_h1((package / 'README.md').read_text(encoding='utf-8')))
     assert problem is None, f'{package.relative_to(_ROOT) / "README.md"}: {problem}'
+
+
+@pytest.mark.parametrize('package', _CAPABILITY_PACKAGES, ids=lambda p: str(p.relative_to(_ROOT)))
+def test_capability_readme_links_source(package: Path) -> None:
+    module = package.relative_to(_ROOT / 'pydantic_ai_harness').as_posix()
+    expected = f'{_SOURCE_LINK}{module}/'
+    targets = _markdown_link_targets((package / 'README.md').read_text(encoding='utf-8'))
+    assert any(expected in t for t in targets), (
+        f'{package.relative_to(_ROOT) / "README.md"} must link its own source module '
+        f'(a Markdown link containing `{expected}`), so parity tooling can find the implementation.'
+    )