docs(agents): drop stale folder tree; fix flat docs path + guard names

AGENTS.md's File-structure ASCII tree and capability-authoring's doc paths
still showed docs/capabilities// docs/experimental/ (flattened in this PR) and
the old /docs/harness URL. Delete the tree rather than redraw it -- the layout
is discoverable by listing the repo; keep only the non-obvious conventions
(flat docs/, the README<->doc parity requirement). Also fix the Vocabulary
guard examples (InputGuard/OutputGuard, not the nonexistent InputGuardrail/
CostGuard).

AGENTS.md

@@ -21,7 +21,7 @@ change instead of reimplementing core behavior in harness.
 - **Capability**: an `AbstractCapability` subclass that bundles tools, hooks, instructions, and model settings into a reusable unit. This is the core abstraction of pydantic-ai-harness.
 - **Hook**: a lifecycle method on `AbstractCapability` that intercepts agent graph execution (e.g. `before_model_request`, `wrap_run`, `after_tool_execute`)
 - **Toolset**: a collection of tools that a capability can provide to the agent
-- **Guard**: a type of capability that validates inputs/outputs or controls tool access (e.g. `InputGuardrail`, `CostGuard`)
+- **Guard**: a type of capability that validates inputs/outputs or controls tool access (e.g. `InputGuard`, `OutputGuard`)
 - **Harness**: this package -- a collection of pre-made capabilities for Pydantic AI.
 - **AICA**: AI Code Assistant -- the automated agent that implements issues, reviews plans, and handles PR feedback
 - **Ralph loop**: the state-machine-based workflow that drives AICA through phases (TRIAGE -> GOALS -> PLAN -> CODE -> VERIFY -> REVIEW -> PUBLISH)
@@ -114,31 +114,18 @@ Always run `make lint && make typecheck && make test` before committing.
 
 ## File structure
 
-```
-pydantic_ai_harness/
-  __init__.py          # public API re-exports
-  <capability>/        # each capability gets its own package
-    __init__.py        # public exports for the capability
-    _capability.py     # capability class (AbstractCapability subclass)
-    _toolset.py        # toolset implementation
-    README.md          # GitHub/PyPI docs for the capability
-docs/                  # source for the unified docs site (pydantic.dev/docs/harness)
-  index.md             # harness overview / landing page
-  capabilities/
-    <capability>.md    # released capability doc (mirrors the README)
-  experimental/
-    <capability>.md    # experimental capability doc
-tests/
-  conftest.py          # shared fixtures (TestModel, test_agent)
-  <capability>/        # tests mirror source packages
-    test_<capability>.py
-```
+The tree is discoverable by listing it; only the conventions that are not are
+recorded here.
 
-Each released capability has **two** hand-maintained docs that must stay in
-sync: the `README.md` next to the code (GitHub/PyPI) and the `docs/` page (the
-docs site). A user-facing change updates both. See
-`agent_docs/review-checklist.md` "Docs" for the parity gate and the
-`docs-parity-reviewer` subagent that enforces it before merge.
+Each released capability is a self-contained package under
+`pydantic_ai_harness/<capability>/` (naming and exports are covered in the
+preflight above), with tests under `tests/<capability>/`. It ships **two**
+hand-maintained docs that must stay in sync: the `README.md` next to the code
+(GitHub/PyPI) and the `docs/<capability>.md` page (the docs site at
+pydantic.dev/docs/ai/harness). The `docs/` folder is flat -- there are no
+`capabilities/` or `experimental/` subdirectories. A user-facing change updates
+both; `agent_docs/review-checklist.md` "Docs" and the `docs-parity-reviewer`
+subagent enforce the parity before merge.
 
 Do not add placeholder template files for new capabilities. Start from the
 existing `CodeMode` package shape, then delete what the new capability does not

agent_docs/capability-authoring.md

@@ -26,10 +26,11 @@ Each capability package should normally have:
 - `_capability.py` for the public capability class
 - `_toolset.py` only if the capability needs toolset behavior
 - `README.md` with focused usage docs (serves GitHub and PyPI)
-- a unified-docs page: `docs/capabilities/<capability>.md` once released, or
-  `docs/experimental/<capability>.md` while experimental. It mirrors the README
+- a unified-docs page at `docs/<capability>.md` (the `docs/` folder is flat --
+  no `capabilities/` or `experimental/` subdirectories). It mirrors the README
   for the docs site, drops badges, links other harness pages with relative `.md`
-  links and Pydantic AI docs with root-relative `/ai/...` links, and ends
+  links and Pydantic AI docs with root-relative `/ai/...` links, links its
+  source module, and -- where the capability exposes a public class -- may end
   with a `::: pydantic_ai_harness.<Class>` autodoc block. The README and this
   page are kept in sync (see `review-checklist.md` "Docs").
 - mirrored tests under `tests/<capability>/`