docs: fix doc-audit findings — graph, types, examples, defaults

Fixes all issues found by the doc-audit skill:

- Check 2: Create missing CLAUDE.md for neuron-tool, neuron-tool-macros,
  neuron-context. Add undocumented types to neuron-types (12 types),
  neuron-mcp (9 types), neuron-runtime (2 types), neuron-loop (1 type).
- Check 3: Fix broken sub_agents.rs reference in neuron/README.md,
  add all 25 examples to Learning Path (was 14, 1 broken).
- Check 4: Fix anthropic default flag in installation.md (was "No",
  should be "Yes" per Cargo.toml default = ["anthropic"]).
- Check 7: Fix dependency graph in CLAUDE.md, README.md, llms.txt,
  and dependency-graph.md to match actual Cargo.toml deps. Key
  corrections: neuron-mcp depends on neuron-tool (not just types),
  neuron-context is a peer leaf (not parent of neuron-loop).

Author: SecBear

CLAUDE.md

@@ -162,21 +162,20 @@ When making design decisions, apply these filters in order:
 neuron-types                    (zero deps, the foundation)
     ^
     |-- neuron-provider-*       (each implements Provider trait)
-    |-- neuron-tool             (implements Tool trait, registry, middleware)
-    |-- neuron-mcp              (wraps rmcp, bridges to Tool trait)
-    +-- neuron-context          (+ optional Provider for summarization)
+    |-- neuron-context          (compaction strategies, token counting)
+    +-- neuron-tool             (Tool trait, registry, middleware)
             ^
-        neuron-loop             (composes provider + tool + context)
-            ^
-        neuron-runtime          (sessions, DurableContext, guardrails, sandbox)
-            ^
-        neuron                  (umbrella re-export, build LAST)
-            ^
-        YOUR PROJECTS           (sdk, cli, tui, gui)
+            |-- neuron-mcp      (wraps rmcp, bridges to Tool trait)
+            |-- neuron-loop     (provider loop with tool dispatch)
+            +-- neuron-runtime  (sessions, DurableContext, guardrails, sandbox)
+                    ^
+                neuron          (umbrella re-export, build LAST)
+                    ^
+                YOUR PROJECTS   (sdk, cli, tui, gui)
 ```
 
 Arrows only point up. No circular dependencies. Each block knows only about
-`neuron-types` and the blocks directly below it.
+`neuron-types` and the blocks it directly depends on.
 
 **This graph must match actual Cargo.toml dependencies.** When adding or removing
 a dependency between crates, update this graph in the same commit.

README.md

@@ -78,15 +78,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 neuron-types                    (zero deps, the foundation)
     ^
     |-- neuron-provider-*       (each implements Provider trait)
-    |-- neuron-tool             (Tool trait, registry, middleware)
-    |-- neuron-mcp              (wraps rmcp, bridges to Tool trait)
-    +-- neuron-context          (+ optional Provider for summarization)
+    |-- neuron-context          (compaction strategies, token counting)
+    +-- neuron-tool             (Tool trait, registry, middleware)
             ^
-        neuron-loop             (composes provider + tool + context)
-            ^
-        neuron-runtime          (sub-agents, sessions, durability)
-            ^
-        neuron                  (umbrella re-export)
+            |-- neuron-mcp      (wraps rmcp, bridges to Tool trait)
+            |-- neuron-loop     (provider loop with tool dispatch)
+            +-- neuron-runtime  (sessions, DurableContext, guardrails, sandbox)
+                    ^
+                neuron          (umbrella re-export)
 ```
 
 Arrows point up. No circular dependencies.

docs/book/src/architecture/dependency-graph.md

@@ -9,18 +9,17 @@ circular dependencies.
 ```text
 neuron-types                    (zero deps, the foundation)
     ^
-    |-- neuron-provider-*       (each implements Provider)
-    |-- neuron-tool             (implements Tool, registry, middleware)
-    |-- neuron-mcp              (wraps rmcp, bridges to Tool)
-    +-- neuron-context          (+ optional Provider for summarization)
+    |-- neuron-provider-*       (each implements Provider trait)
+    |-- neuron-context          (compaction strategies, token counting)
+    +-- neuron-tool             (Tool trait, registry, middleware)
             ^
-        neuron-loop             (composes provider + tool + context)
-            ^
-        neuron-runtime          (sessions, DurableContext, guardrails)
-            ^
-        neuron                  (umbrella re-export)
-            ^
-        YOUR PROJECT            (SDK, CLI, TUI, GUI)
+            |-- neuron-mcp      (wraps rmcp, bridges to Tool trait)
+            |-- neuron-loop     (provider loop with tool dispatch)
+            +-- neuron-runtime  (sessions, DurableContext, guardrails, sandbox)
+                    ^
+                neuron          (umbrella re-export)
+                    ^
+                YOUR PROJECT    (SDK, CLI, TUI, GUI)
 ```
 
 ## Layer by layer
@@ -67,31 +66,31 @@ Implements the tool system:
 
 Depends only on `neuron-types`.
 
-### neuron-mcp (leaf node)
+### neuron-mcp
 
 Wraps the `rmcp` crate (the official Rust MCP SDK) and bridges MCP tools into
-neuron's `ToolDyn` trait. Depends only on `neuron-types` and `rmcp`.
+neuron's `ToolDyn` trait. Depends on `neuron-types`, `neuron-tool`, and `rmcp`.
 
 ### neuron-context (leaf node)
 
 Implements `ContextStrategy` for client-side context compaction. Some strategies
 (like summarization) optionally use a `Provider` for LLM calls, but the
 dependency is on the trait, not on any concrete provider crate.
 
-### neuron-loop (composition layer)
+### neuron-loop
 
-The agentic while-loop that composes a provider, tool registry, and context
-strategy. This is the ~300-line commodity loop that every agent framework
-converges on. It depends on:
+The agentic while-loop that composes a provider and tool registry. This is the
+~300-line commodity loop that every agent framework converges on. It depends on:
 
-- `neuron-types` (for all trait definitions)
+- `neuron-types` (for trait definitions)
+- `neuron-tool` (for `ToolRegistry`)
 
-The loop is generic over `<P: Provider>` and accepts a `ToolRegistry` and
-optional `ContextStrategy` implementation.
+The loop is generic over `<P: Provider, C: ContextStrategy>` and accepts a
+`ToolRegistry`. `neuron-context` is a dev-dependency only (for tests).
 
-### neuron-runtime (runtime layer)
+### neuron-runtime
 
-Adds cross-cutting runtime concerns on top of the loop:
+Adds cross-cutting runtime concerns:
 
 - **Sessions** -- persistent conversation state via `StorageError`-aware backends
 - **DurableContext** -- wraps side effects for Temporal/Restate replay
@@ -100,7 +99,8 @@ Adds cross-cutting runtime concerns on top of the loop:
 - **PermissionPolicy** -- tool call authorization
 - **Sandbox** -- isolated tool execution environments
 
-Depends on `neuron-types` and `neuron-loop`.
+Depends on `neuron-types` and `neuron-tool`. `neuron-loop` and `neuron-context`
+are dev-dependencies only (for tests).
 
 ### neuron (umbrella)
 
@@ -118,14 +118,15 @@ neuron = { version = "0.2", features = ["anthropic", "openai"] }
 or below, never at layer N or above. This is enforced by `Cargo.toml`
 dependencies -- circular dependencies are a compile error in Rust.
 
-**Each block knows only about `neuron-types` and the blocks directly below it.**
+**Each block knows only about `neuron-types` and the blocks it directly depends on.**
 `neuron-tool` has no idea that `neuron-loop` exists. `neuron-provider-anthropic`
 has no idea that `neuron-runtime` exists. This means you can use any block
 independently.
 
-**No cross-leaf dependencies.** Provider crates do not depend on the tool crate.
-The MCP crate does not depend on any provider crate. Leaf nodes are fully
-independent of each other.
+**Provider crates are fully independent.** Provider crates do not depend on the
+tool crate, the MCP crate, or each other. `neuron-mcp`, `neuron-loop`, and
+`neuron-runtime` share a dependency on `neuron-tool` but are independent of
+each other.
 
 ## Practical implications
 

docs/book/src/getting-started/installation.md

@@ -19,7 +19,7 @@ cargo add neuron --features anthropic
 
 | Feature | Enables | Default |
 |---------|---------|---------|
-| `anthropic` | `neuron-provider-anthropic` | No |
+| `anthropic` | `neuron-provider-anthropic` | Yes |
 | `openai` | `neuron-provider-openai` | No |
 | `ollama` | `neuron-provider-ollama` | No |
 | `mcp` | `neuron-mcp` (Model Context Protocol) | No |

llms.txt

@@ -12,21 +12,20 @@ neuron is **serde, not serde_json**. It defines traits, provides foundational im
 
 ## Architecture
 
-Dependencies flow upward. Each block depends only on neuron-types and the blocks directly below it.
+Dependencies flow upward. Each block depends only on neuron-types and the blocks it directly needs.
 
 ```
 neuron-types                    (zero deps, the foundation)
     ^
     |-- neuron-provider-*       (each implements Provider trait)
-    |-- neuron-tool             (implements Tool trait, registry, middleware)
-    |-- neuron-mcp              (wraps rmcp, bridges to Tool trait)
-    +-- neuron-context          (+ optional Provider for summarization)
+    |-- neuron-context          (compaction strategies, token counting)
+    +-- neuron-tool             (Tool trait, registry, middleware)
             ^
-        neuron-loop             (composes provider + tool + context)
-            ^
-        neuron-runtime          (sessions, DurableContext, guardrails, sandbox)
-            ^
-        neuron                  (umbrella re-export, build LAST)
+            |-- neuron-mcp      (wraps rmcp, bridges to Tool trait)
+            |-- neuron-loop     (provider loop with tool dispatch)
+            +-- neuron-runtime  (sessions, DurableContext, guardrails, sandbox)
+                    ^
+                neuron          (umbrella re-export, build LAST)
 ```
 
 ## Key Traits (all in neuron-types)

neuron-context/CLAUDE.md

@@ -0,0 +1,75 @@
+# neuron-context
+
+Context management strategies for long-running agents -- token counting,
+compaction, injection, and persistent context.
+
+## Key types
+
+- `TokenCounter` -- heuristic token estimator using chars-per-token ratio
+  (default 4.0). Estimates messages, tool definitions, and raw text.
+- `InjectionTrigger` -- enum (`EveryNTurns`, `OnTokenThreshold`) controlling
+  when a `SystemInjector` rule fires.
+- `SystemInjector` -- injects system prompt content based on turn count or
+  token thresholds. Rule-based, checked each turn.
+- `ContextSection` -- a named, prioritized text section (label, content,
+  priority) for structured system prompts.
+- `PersistentContext` -- aggregates `ContextSection`s and renders them sorted
+  by priority into a single string.
+- `SlidingWindowStrategy` -- `ContextStrategy` impl that keeps system messages
+  plus the last N non-system messages. Triggers on token threshold.
+- `SummarizationStrategy<P: Provider>` -- `ContextStrategy` impl that
+  summarizes old messages via an LLM provider, preserving recent messages
+  verbatim. Generic over `Provider`.
+- `ToolResultClearingStrategy` -- `ContextStrategy` impl that replaces old
+  tool result content with `[tool result cleared]`, keeping the most recent N
+  intact.
+- `CompositeStrategy` -- chains multiple strategies in order, stopping early
+  when the token count drops below the threshold.
+- `BoxedStrategy` -- type-erased wrapper around any `ContextStrategy` for use
+  in `CompositeStrategy`. Uses `Arc<dyn ErasedStrategy>` internally because
+  `ContextStrategy` is RPITIT and not dyn-compatible.
+
+## Key design decisions
+
+- **Token counting is heuristic.** `TokenCounter` uses a chars-per-token ratio,
+  not a real tokenizer. Good enough for compaction thresholds; avoids a
+  tokenizer dependency.
+- **All strategies implement `ContextStrategy`** from `neuron-types`. The loop
+  calls `should_compact()` / `compact()` / `token_estimate()` uniformly.
+- **`BoxedStrategy` exists for type erasure.** `ContextStrategy` uses RPITIT
+  (`compact` returns `impl Future`), making it not dyn-compatible.
+  `BoxedStrategy` wraps an internal `ErasedStrategy` trait that boxes the
+  future, enabling heterogeneous strategy collections in `CompositeStrategy`.
+- **`SummarizationStrategy` is the only strategy with a `Provider` dependency.**
+  It takes a generic `P: Provider` and calls `complete()` to summarize old
+  messages. All other strategies are pure computation.
+- **Fixed cost estimates for images (300) and documents (500).** These are rough
+  approximations in `TokenCounter` since binary content has no char-based
+  estimate.
+
+## Dependencies
+
+- `neuron-types` -- `ContextStrategy` trait, `Message`, `ContentBlock`,
+  `Provider`, `ContextError`
+- `serde`, `serde_json` -- serialization
+- `tracing` -- instrumentation
+
+Dev-only: `tokio`, `proptest`, `criterion`
+
+## Structure
+
+```
+neuron-context/
+    CLAUDE.md
+    Cargo.toml
+    src/
+        lib.rs           # Re-exports all public types
+        counter.rs       # TokenCounter
+        injector.rs      # InjectionTrigger, SystemInjector
+        persistent.rs    # ContextSection, PersistentContext
+        strategies.rs    # SlidingWindowStrategy, SummarizationStrategy,
+                         # ToolResultClearingStrategy, CompositeStrategy,
+                         # BoxedStrategy
+    benches/
+        compaction.rs    # Criterion benchmarks
+```

neuron-loop/CLAUDE.md

@@ -4,6 +4,7 @@ Agentic while loop for neuron. Composes Provider + Tool + Context.
 
 ## Key types
 - `AgentLoop<P, C>` — the core loop, generic over Provider and ContextStrategy
+- `AgentLoopBuilder<P, C>` — builder pattern for constructing AgentLoop
 - `LoopConfig` — system prompt, max turns, parallel tool execution
 - `AgentResult` — final response, messages, usage, turn count
 - `TurnResult` — per-turn result enum for step-by-step iteration

neuron-mcp/CLAUDE.md

@@ -4,9 +4,13 @@ MCP (Model Context Protocol) integration for neuron.
 
 ## Key types
 - `McpClient` — connects to MCP servers via stdio or HTTP transport
+- `StdioConfig` — configuration for stdio-based MCP connections
+- `HttpConfig` — configuration for HTTP-based MCP connections
 - `McpToolBridge` — bridges MCP tools to `ToolDyn` for use in `ToolRegistry`
 - `McpServer` — exposes a `ToolRegistry` as an MCP server
 - `PaginatedList<T>` — paginated response wrapper
+- `McpResource`, `McpResourceContents` — MCP resource types
+- `McpPrompt`, `McpPromptArgument`, `McpPromptMessage`, `McpPromptContent`, `McpPromptResult` — MCP prompt types
 
 ## Key patterns
 - Wraps `rmcp` (official Rust MCP SDK), does not reimplement the protocol

neuron-runtime/CLAUDE.md

@@ -10,6 +10,7 @@ sandboxing.
 - `FileSessionStorage` -- one JSON file per session
 - `InputGuardrail`, `OutputGuardrail` -- safety checks with Pass/Tripwire/Warn
 - `GuardrailResult` -- Pass, Tripwire(reason), Warn(reason)
+- `ErasedInputGuardrail`, `ErasedOutputGuardrail` -- type-erased guardrails for dyn dispatch
 - `GuardrailHook` -- ObservabilityHook adapter that runs guardrails on PreLlmCall/PostLlmCall
 - `LocalDurableContext<P>` -- passthrough DurableContext for local dev
 - `Sandbox` trait, `NoOpSandbox` -- tool execution isolation

neuron-tool-macros/CLAUDE.md

@@ -0,0 +1,65 @@
+# neuron-tool-macros
+
+Proc-macro crate that derives `Tool` implementations from annotated async functions.
+
+## Exports
+
+- `#[neuron_tool(name = "...", description = "...")]` — attribute macro applied
+  to an async function. Generates a zero-sized tool struct, an args struct, and
+  a `Tool` trait impl.
+
+## What the macro generates
+
+Given a function `calculate`, the macro emits:
+
+- **`CalculateArgs`** — struct with `Deserialize` + `JsonSchema` derives. Fields
+  come from the function parameters (all except the last `&ToolContext` param).
+  Doc comments on parameters become doc comments on fields (which `schemars`
+  picks up for JSON Schema descriptions).
+- **`CalculateTool`** — unit struct implementing `neuron_types::Tool`. The impl
+  provides `NAME`, `Args`/`Output`/`Error` associated types, `definition()`
+  (builds `ToolDefinition` with schema from `schemars::schema_for!`), and
+  `call()` (destructures args and runs the original function body).
+
+Naming convention: function name is converted to PascalCase, then suffixed with
+`Tool` or `Args`.
+
+## Key design decisions
+
+- **Attribute macro, not derive.** The input is a function, not a struct, so
+  `#[proc_macro_attribute]` is the correct form.
+- **Last parameter must be `&ToolContext`.** The macro strips it from the args
+  struct and threads it through to `call()`. A `let _ = &ctx;` suppresses
+  unused-variable warnings when the function uses `_ctx`.
+- **Schema via `schemars`** on the generated args struct. The macro does not
+  hand-build JSON Schema — it relies on `schemars::schema_for!` at the call
+  site, so the user's crate must depend on `schemars` and `serde_json`.
+- **No `ToolDyn` generation.** Type erasure is handled by `ToolRegistry` in
+  `neuron-tool` when the tool is registered.
+- **Return type must be `Result<Output, Error>`.** The macro extracts both type
+  parameters from the return type at compile time.
+- **Compile errors, not panics.** All validation failures return `syn::Error`
+  for clear diagnostics.
+
+## Dependencies
+
+- `syn` — parsing Rust syntax
+- `quote` — generating token streams
+- `proc-macro2` — proc-macro utilities
+
+No runtime dependencies. The generated code references `neuron_types`, `serde`,
+`schemars`, and `serde_json`, but those are dependencies of the user's crate,
+not of this macro crate.
+
+## Structure
+
+```
+neuron-tool-macros/
+    CLAUDE.md
+    Cargo.toml
+    src/
+        lib.rs          # Everything: attribute parsing, code generation, helpers
+```
+
+Single-file crate. Internal helpers: `AgentToolArgs` (attribute parser),
+`to_pascal_case`, `expand_neuron_tool` (main codegen), `extract_result_types`.