riffer 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1bf92e3bef065a4c07aadb273a7f6770b711c0f15f268726133c841cb3fd510
-  data.tar.gz: d7361c029b98ca819932e2c3d2d53113710bb434ad60092ee0578179fa844c5e
+  metadata.gz: 6c89776aeb032fbf837df103366fed830edcc20769cc9d4958a3a9bfa56a7803
+  data.tar.gz: 2153cf2967b9b70366987aeb9e59b215ff641bcd44668525c07d822ff9757579
 SHA512:
-  metadata.gz: 7f503377743f6629a1423234afb158570dc33ee225c82c0bc46e28938a839fe25b5bdfad6f61da274a8bf81e1e8dd6c505ad826593c5eb269251d47667fe9d7c
-  data.tar.gz: eddabf85e5416c777c3a9a441ce99cd1cb902ec1c339fa7338890ae8cb7e78c5e78628e1b886aea44cdc6228b99299fa3983816e10075d8c28b59229e4c0b376
+  metadata.gz: edfb2a10f17e1c0f6fb0630f5c2244370e01c5f32d05e9f065183da0b5b2d2cfec2453cac9a08714bd921716cd747609e4db61fb105a57769d79ab2f8988356a
+  data.tar.gz: 7d6dcdbab4be152033fcf75581252d3c9bda60c9e49825e75028d19670bae0490087ee8a90267a2af2f4fd8daabb5f370c8c2b7bb7cdcffe77a75b94a6b190ff

data/.agents/architecture.md

@@ -136,7 +136,7 @@ Context flow: `Agent#execute_tool_calls` → `Tools::Runtime#execute(tool_calls,
 
 ### MCP Integration (`lib/riffer/mcp/`)
 
-Register third-party MCP servers globally; agents opt-in by tag via `use_mcp`. Tags are application-defined (manifests may list several; any overlap with `use_mcp` opts in—see `docs/14_MCP.md`).
+Register third-party MCP servers globally; agents opt-in by tag via `use_mcp`. Tags are application-defined (manifests may list several; any overlap with `use_mcp` opts in—see `docs/MCP.md`).
 
 ```ruby
 Riffer::Mcp.register(
@@ -146,7 +146,7 @@ Riffer::Mcp.register(
   discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
 )
 
-# Optional: per-run tools/call headers (see docs/14_MCP.md)
+# Optional: per-run tools/call headers (see docs/MCP.md)
 Riffer.configure { |c| c.mcp.credentials = ->(manifest:, matched_tags:, context:) { ... } }
 
 class ResearchAgent < Riffer::Agent

data/.agents/code-style.md

@@ -2,9 +2,10 @@
 
 ## Formatting
 
-- Use StandardRB for linting and formatting
-- Custom rules are defined in `.standard.yml`
-- Run `bin/lint` to check, `bin/lint --fix` to auto-fix
+- Use RuboCop for linting and formatting
+- Config lives in `.rubocop.yml`, with cops sorted alphabetically
+- Run `bin/lint` to check, `bin/lint -a` to auto-fix (safe autocorrect), `bin/lint -A` for unsafe autocorrect
+- Never silence violations with inline `rubocop:disable` comments — fix them, or when an exception is genuinely warranted add a narrowly scoped override in `.rubocop.yml` with a comment explaining why
 
 ## Required Header
 

data/.agents/providers.md

@@ -3,7 +3,7 @@
 ## Steps
 
 1. Create `lib/riffer/providers/your_provider.rb` extending `Riffer::Providers::Base`
-2. Implement the required hook methods (see [Custom Providers](../docs/providers/07_CUSTOM_PROVIDERS.md) for the full API)
+2. Implement the required hook methods (see [Custom Providers](../docs/providers/CUSTOM_PROVIDERS.md) for the full API)
 3. Register in `Riffer::Providers::Repository::REPO`
 4. Add provider config to `Riffer::Config` if needed
 5. Create tests in `test/riffer/providers/your_provider_test.rb`
@@ -42,4 +42,4 @@ Use `depends_on` helper for runtime dependency checking if your provider require
 
 ## Reference
 
-For hook method signatures, structured output handling, file handling, and complete examples, see [Custom Providers](../docs/providers/07_CUSTOM_PROVIDERS.md).
+For hook method signatures, structured output handling, file handling, and complete examples, see [Custom Providers](../docs/providers/CUSTOM_PROVIDERS.md).

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.39.0"
+  ".": "0.40.0"
 }

data/.rubocop.yml

@@ -0,0 +1,112 @@
+plugins:
+  - rubocop-minitest
+  - rubocop-performance
+  - rubocop-rake
+
+# ── Tier 1: house style — settings changed from RuboCop defaults everywhere ──
+
+Layout/BlockAlignment:
+  EnforcedStyleAlignWith: start_of_block
+
+Layout/DotPosition:
+  EnforcedStyle: trailing
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/HashSyntax:
+  EnforcedShorthandSyntax: either_consistent
+
+Style/NonNilCheck:
+  IncludeSemanticChanges: true
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+# ── Tier 2: shared base — additions and deviations from the house style ──
+
+AllCops:
+  DisabledByDefault: false
+  # Stricter than the house style, which leaves pending cops as warnings;
+  # enabling adopts new cops automatically and kills the warning spam.
+  NewCops: enable
+  SuggestExtensions: false
+
+# Size thresholds are noise; BlockNesting stays — deep nesting is the one
+# limit worth enforcing.
+Metrics:
+  Enabled: false
+
+Metrics/BlockNesting:
+  Enabled: true
+
+# A comment on every class is a "what" — conflicts with the comments rule.
+Style/Documentation:
+  Enabled: false
+
+# The function-module pattern needs a working `private`.
+Style/ModuleFunction:
+  EnforcedStyle: extend_self
+
+# Compact (`class Foo::Bar`) cuts LOC and nesting and ends the nested/compact
+# mix across codebases.
+Style/ClassAndModuleChildren:
+  EnforcedStyle: compact
+
+# Keyword arguments often stay unused to keep signatures uniform across
+# interchangeable implementations.
+Lint/UnusedMethodArgument:
+  AllowUnusedKeywordArguments: true
+
+# Additions, not overrides: RBS-inline annotations must lint.
+Layout/LeadingCommentSpace:
+  AllowRBSInlineAnnotation: true
+
+Layout/LineLength:
+  AllowedPatterns: ['#:']
+
+Minitest/MultipleAssertions:
+  Max: 3
+
+# ── Tier 3: riffer deviations, each with its reason ──
+
+# Tests use deliberately empty blocks: `.each { |_| }` to drain a stream for
+# its side effects, empty `in_span` bodies to assert span lifecycle, and no-op
+# stream doubles.
+Lint/EmptyBlock:
+  Exclude:
+    - test/**/*
+
+# Keyword-argument names are the calling contract for riffer's block-based
+# hooks (tool `execute` blocks, evaluator lambdas, dynamic instructions) —
+# underscore-prefixing a block keyword renames the keyword and breaks callers.
+Lint/UnusedBlockArgument:
+  AllowUnusedKeywordArguments: true
+
+# validate_as_tool! follows the validate!/save! idiom: raise or return true.
+# Its return value is not a predicate.
+Naming/PredicateMethod:
+  AllowBangMethods: true
+
+# has_tool_calls? is shipped public API — renaming it breaks consumers.
+Naming/PredicatePrefix:
+  AllowedMethods:
+    - has_tool_calls?
+
+# Riffer::Messages::Base#+ and Riffer::Providers::TokenUsage#+ merge objects;
+# the cop's `sum` rewrite starts the fold from 0 and raises on non-numeric
+# elements.
+Performance/Sum:
+  Exclude:
+    - lib/riffer/providers/base.rb
+    - lib/riffer/evals/run_result.rb
+    - lib/riffer/evals/scenario_result.rb

data/AGENTS.md

@@ -5,16 +5,16 @@ Ruby gem framework for building AI-powered agents with LLM provider adapters.
 ## Quick Reference
 
 - **Ruby**: 3.3.0+ (CI: 3.3, 3.4, 4.0)
-- **Lint + Test**: `bin/rake` (runs the default task: test + standard + steep:check)
+- **Lint + Test**: `bin/rake` (runs the default task: test + rubocop + steep:check)
 - **Autoloading**: Zeitwerk (file paths must match module/class names)
 - **Model format**: `provider/model` (e.g., `openai/gpt-4`)
-- **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/10_CONFIGURATION.md`, `docs/08_MESSAGES.md`). RDoc ≠ user docs.
+- **Docs**: when adding a public config option or message attribute, update the matching page in `docs/` (e.g., `docs/CONFIGURATION.md`, `docs/MESSAGES.md`). Adding a NEW page under `docs/` also requires a `docs-site/manifest.yml` entry — the site build fails without one. RDoc ≠ user docs.
 
 ## Topic Guides
 
 - [Architecture](.agents/architecture.md) - Core components and project structure
 - [Testing](.agents/testing.md) - Minitest spec DSL and VCR cassettes
-- [Code Style](.agents/code-style.md) - StandardRB, comment, and RDoc conventions
+- [Code Style](.agents/code-style.md) - RuboCop, comment, and RDoc conventions
 - [Providers](.agents/providers.md) - Adding new LLM provider adapters
 - [RBS Inline](.agents/rbs-inline.md) - Type annotations with rbs-inline
 
@@ -24,13 +24,13 @@ All wrappers `exec bundle exec …` under the hood.
 
 | Command         | Description                                  |
 | --------------- | -------------------------------------------- |
-| `bin/rake`      | Default task: test + standard + steep:check  |
+| `bin/rake`      | Default task: test + rubocop + steep:check   |
 | `bin/test`      | Run tests                                    |
-| `bin/lint`      | Check code style (pass `--fix` to auto-fix)  |
+| `bin/lint`      | Check code style (pass `-a` to auto-fix)     |
 | `bin/typecheck` | Run Steep type checker                       |
 | `bin/rbs`       | Generate RBS type signatures                 |
 | `bin/rbs-watch` | Watch and regenerate RBS files               |
-| `bin/docs`      | Build RDoc HTML                              |
+| `bin/docs`      | Build the docs site + API reference          |
 | `bin/build`     | Build the gem package                        |
 | `bin/console`   | Interactive console                          |
 | `bin/setup`     | Install dependencies                         |

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.40.0](https://github.com/janeapp/riffer/compare/riffer/v0.39.0...riffer/v0.40.0) (2026-08-12)
+
+
+### Features
+
+* replace RDoc guide pages with a static docs site ([#390](https://github.com/janeapp/riffer/issues/390)) ([eef94e1](https://github.com/janeapp/riffer/commit/eef94e140b618ae55a0dea2e0e94cf91462ae169))
+
 ## [0.39.0](https://github.com/janeapp/riffer/compare/riffer/v0.38.1...riffer/v0.39.0) (2026-07-29)
 
 

data/README.md

@@ -45,35 +45,37 @@ puts agent.generate('Hello world')
 
 ## Documentation
 
-For comprehensive documentation, see the [docs](docs/) directory:
-
-- [Overview](docs/01_OVERVIEW.md) - Core concepts and architecture
-- [Getting Started](docs/02_GETTING_STARTED.md) - Installation and first steps
-- [Agents](docs/03_AGENTS.md) - Defining and configuring agents
-- [Agent Lifecycle](docs/04_AGENT_LIFECYCLE.md) - Generate, stream, and responses
-- [Agent Loop](docs/05_AGENT_LOOP.md) - Tool execution flow and stopping
-- [Tools](docs/06_TOOLS.md) - Creating tools for agents
-- [Advanced Tools](docs/07_TOOL_ADVANCED.md) - Timeouts, runtime, and registration
-- [Messages](docs/08_MESSAGES.md) - Message types and formats
-- [Stream Events](docs/09_STREAM_EVENTS.md) - Streaming responses
-- [Configuration](docs/10_CONFIGURATION.md) - Framework configuration
-- [Evals](docs/11_EVALS.md) - Evaluating agent quality
-- [Guardrails](docs/12_GUARDRAILS.md) - Input/output validation
-- [Skills](docs/13_SKILLS.md) - Packaged agent capabilities
-- [MCP](docs/14_MCP.md) - Integrating third-party MCP servers
-- [Serialization](docs/15_SERIALIZATION.md) - Persisting and transferring agent definitions
-- [Tracing](docs/16_TRACING.md) - OpenTelemetry span contract and host wiring
-- [Providers](docs/providers/01_PROVIDERS.md) - LLM provider adapters
+Comprehensive guides live at [docs.riffer.ai](https://docs.riffer.ai):
+
+- [Overview](https://docs.riffer.ai/guides/overview/) - Core concepts and architecture
+- [Getting Started](https://docs.riffer.ai/guides/getting-started/) - Installation and first steps
+- [Agents](https://docs.riffer.ai/guides/agents/) - Defining and configuring agents
+- [Agent Lifecycle](https://docs.riffer.ai/guides/agent-lifecycle/) - Generate, stream, and responses
+- [Agent Loop](https://docs.riffer.ai/guides/agent-loop/) - Tool execution flow and stopping
+- [Tools](https://docs.riffer.ai/guides/tools/) - Creating tools for agents
+- [Advanced Tools](https://docs.riffer.ai/guides/advanced-tools/) - Timeouts, runtime, and registration
+- [Messages](https://docs.riffer.ai/guides/messages/) - Message types and formats
+- [Stream Events](https://docs.riffer.ai/guides/stream-events/) - Streaming responses
+- [Configuration](https://docs.riffer.ai/guides/configuration/) - Framework configuration
+- [Evals](https://docs.riffer.ai/guides/evals/) - Evaluating agent quality
+- [Guardrails](https://docs.riffer.ai/guides/guardrails/) - Input/output validation
+- [Skills](https://docs.riffer.ai/guides/skills/) - Packaged agent capabilities
+- [MCP](https://docs.riffer.ai/guides/mcp/) - Integrating third-party MCP servers
+- [Serialization](https://docs.riffer.ai/guides/serialization/) - Persisting and transferring agent definitions
+- [Tracing](https://docs.riffer.ai/guides/tracing/) - OpenTelemetry span contract and host wiring
+- [Providers](https://docs.riffer.ai/guides/providers/overview/) - LLM provider adapters
+
+The guide sources are in the [docs](docs/) directory.
 
 ### API Reference
 
-Generate the full API documentation with:
+The full API reference is published at [docs.riffer.ai/api](https://docs.riffer.ai/api/). Preview the site locally with:
 
 ```bash
-bin/docs
+bin/rake docs:serve
 ```
 
-Then open `doc/index.html` in your browser.
+Then open <http://localhost:8000>. The site uses root-absolute paths, so it must be served over HTTP — opening `_site/index.html` via `file://` won't work.
 
 ## Development
 
@@ -86,17 +88,17 @@ bin/setup
 Common workflows are wrapped in `bin/`. Each is a thin `exec bundle exec …` script — use them
 instead of typing `bundle exec` yourself:
 
-| Command         | Description                                 |
-| --------------- | ------------------------------------------- |
-| `bin/rake`      | Default task: test + standard + steep:check |
-| `bin/test`      | Run tests                                   |
-| `bin/lint`      | Check code style (pass `--fix` to auto-fix) |
-| `bin/typecheck` | Run Steep type checker                      |
-| `bin/rbs`       | Generate RBS type signatures                |
-| `bin/rbs-watch` | Watch and regenerate RBS files              |
-| `bin/docs`      | Build RDoc HTML                             |
-| `bin/build`     | Build the gem package                       |
-| `bin/console`   | Interactive console                         |
+| Command         | Description                                |
+| --------------- | ------------------------------------------ |
+| `bin/rake`      | Default task: test + rubocop + steep:check |
+| `bin/test`      | Run tests                                  |
+| `bin/lint`      | Check code style (pass `-a` to auto-fix)   |
+| `bin/typecheck` | Run Steep type checker                     |
+| `bin/rbs`       | Generate RBS type signatures               |
+| `bin/rbs-watch` | Watch and regenerate RBS files             |
+| `bin/docs`      | Build the docs site + API reference        |
+| `bin/build`     | Build the gem package                      |
+| `bin/console`   | Interactive console                        |
 
 `bin/rake <task>` is the escape hatch for any rake task without a named wrapper (e.g.
 `bin/rake test:slow`, `bin/rake release`).

data/Rakefile

@@ -5,20 +5,40 @@ require "minitest/test_task"
 
 Minitest::TestTask.create
 
-require "standard/rake"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
 require "rdoc/task"
 
 RDoc::Task.new do |rdoc|
-  rdoc.rdoc_dir = "doc"
-  rdoc.title = "Riffer Documentation"
+  rdoc.rdoc_dir = "_site/api"
+  rdoc.title = "Riffer API Reference"
   rdoc.main = "README.md"
   rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt")
   rdoc.rdoc_files.include("lib/**/*.rb")
   rdoc.options << "--charset" << "utf-8"
-  rdoc.options << "--page-dir" << "docs"
 end
 
-task docs: :rdoc
+namespace :docs do
+  desc "Build the docs site (landing, guides, 404, assets) into _site/"
+  task :site do
+    ruby "docs-site/build.rb"
+  end
+
+  desc "Build the docs site and validate all internal links and anchors"
+  task check: :site do
+    ruby "docs-site/check.rb"
+  end
+
+  desc "Build the docs site and serve it at http://localhost:8000"
+  task serve: :site do
+    ruby "-run -e httpd _site -p 8000"
+  end
+end
+
+desc "Build the full deployable docs tree (site + API reference) into _site/"
+task docs: %w[docs:site rdoc]
 
 namespace :rbs do
   desc "Generate RBS type signatures from inline annotations"
@@ -42,4 +62,4 @@ namespace :steep do
   end
 end
 
-task default: %i[test standard steep:check]
+task default: %i[test rubocop steep:check]

data/Steepfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 D = Steep::Diagnostic
 
 target :lib do

data/docs/{03_AGENTS.md → AGENTS.md}

@@ -126,7 +126,7 @@ end
 
 ### use_mcp
 
-Loads tools from registered [MCP](14_MCP.md) servers by tag. Like `uses_tools`, **`use_mcp` is not inherited**—add it on each subclass that should include MCP tools.
+Loads tools from registered [MCP](MCP.md) servers by tag. Like `uses_tools`, **`use_mcp` is not inherited**—add it on each subclass that should include MCP tools.
 
 ### provider_options
 
@@ -263,7 +263,7 @@ class MyAgent < Riffer::Agent
 end
 ```
 
-Accepts a `Riffer::Tools::Runtime` subclass, a `Riffer::Tools::Runtime` instance, or a `Proc`. When unset, defaults to `Riffer.config.tool_runtime` (captured at agent class definition time). See [Tools — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
+Accepts a `Riffer::Tools::Runtime` subclass, a `Riffer::Tools::Runtime` instance, or a `Proc`. When unset, defaults to `Riffer.config.tool_runtime` (captured at agent class definition time). See [Tools — Tool Runtime](TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 
 ### guardrail
 
@@ -284,7 +284,7 @@ class MyAgent < Riffer::Agent
 end
 ```
 
-See [Guardrails](12_GUARDRAILS.md) for detailed documentation.
+See [Guardrails](GUARDRAILS.md) for detailed documentation.
 
 ## Configuration Object
 
@@ -333,7 +333,7 @@ Keys and values may be `String` or `Symbol`; both are stringified, and entries w
 Tags propagate to **two** places:
 
 1. The provider's native per-request metadata field (see the mapping below).
-2. Observability — stamped as `riffer.tag.<key>` on **every** span the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail`). See [Tracing](16_TRACING.md).
+2. Observability — stamped as `riffer.tag.<key>` on **every** span the call emits (`invoke_agent`, `chat`, `execute_tool`, `execute_guardrail`). See [Tracing](TRACING.md).
 
 ### Reserved key: `user_id`
 
@@ -361,12 +361,12 @@ Riffer does not validate tag count, key/value length, or charset — it forwards
 
 | Goal                          | Feature           | Guide                                                                |
 | ----------------------------- | ----------------- | -------------------------------------------------------------------- |
-| Call APIs or run functions    | Tools             | [Tools](06_TOOLS.md)                                                 |
+| Call APIs or run functions    | Tools             | [Tools](TOOLS.md)                                                 |
 | Return structured JSON        | Structured Output | [structured_output](#structured_output)                              |
-| Validate or filter content    | Guardrails        | [Guardrails](12_GUARDRAILS.md)                                       |
-| Measure output quality        | Evals             | [Evals](11_EVALS.md)                                                 |
-| Add packaged capabilities     | Skills            | [Skills](13_SKILLS.md)                                               |
-| Control the tool-use loop     | Agent Loop        | [Agent Loop](05_AGENT_LOOP.md)                                       |
-| Human-in-the-loop approval    | Interrupts        | [Agent Lifecycle](04_AGENT_LIFECYCLE.md#interrupting-the-agent-loop) |
-| Run tools concurrently        | Tool Runtime      | [Advanced Tools](07_TOOL_ADVANCED.md#tool-runtime-experimental)      |
-| Stream responses in real time | Streaming         | [Agent Lifecycle](04_AGENT_LIFECYCLE.md#stream)                      |
+| Validate or filter content    | Guardrails        | [Guardrails](GUARDRAILS.md)                                       |
+| Measure output quality        | Evals             | [Evals](EVALS.md)                                                 |
+| Add packaged capabilities     | Skills            | [Skills](SKILLS.md)                                               |
+| Control the tool-use loop     | Agent Loop        | [Agent Loop](AGENT_LOOP.md)                                       |
+| Human-in-the-loop approval    | Interrupts        | [Agent Lifecycle](AGENT_LIFECYCLE.md#interrupting-the-agent-loop) |
+| Run tools concurrently        | Tool Runtime      | [Advanced Tools](TOOL_ADVANCED.md#tool-runtime-experimental)      |
+| Stream responses in real time | Streaming         | [Agent Lifecycle](AGENT_LIFECYCLE.md#stream)                      |

data/docs/{04_AGENT_LIFECYCLE.md → AGENT_LIFECYCLE.md}

@@ -341,7 +341,7 @@ msg.structured_output?    # => true
 msg.structured_output     # => {sentiment: "positive", score: 0.95}
 ```
 
-See [Messages — Structured Output on Messages](08_MESSAGES.md#structured-output-on-messages) for details.
+See [Messages — Structured Output on Messages](MESSAGES.md#structured-output-on-messages) for details.
 
 ## Class Methods
 

data/docs/{10_CONFIGURATION.md → CONFIGURATION.md}

@@ -32,11 +32,11 @@ Riffer.config.anthropic.api_key
 
 ## Provider-Specific Configuration
 
-For provider credentials and setup, see the individual [Provider guides](providers/).
+For provider credentials and setup, see the individual [Provider guides](providers/PROVIDERS.md).
 
 ### MCP (Model Context Protocol)
 
-Optional settings for [MCP server integrations](14_MCP.md):
+Optional settings for [MCP server integrations](MCP.md):
 
 | Option             | Description                                                                                                     |
 | ------------------ | --------------------------------------------------------------------------------------------------------------- |
@@ -51,7 +51,7 @@ Riffer.configure do |config|
 end
 ```
 
-See [MCP](14_MCP.md) for registration, tags, and agent `use_mcp`.
+See [MCP](MCP.md) for registration, tags, and agent `use_mcp`.
 
 ### Tool Runtime (Experimental)
 
@@ -71,7 +71,7 @@ end
 | `Riffer::Tools::Runtime` instance | Custom runtime with specific options                                                                    |
 | `Proc`                            | Dynamic resolution                                                                                      |
 
-Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](07_TOOL_ADVANCED.md#tool-runtime-experimental) for details.
+Per-agent configuration overrides this global default. See [Advanced Tool Configuration — Tool Runtime](TOOL_ADVANCED.md#tool-runtime-experimental) for details.
 
 ### Skills
 
@@ -87,7 +87,7 @@ Riffer.configure do |config|
 end
 ```
 
-Per-agent override is available inside the `skills` block via `activate_tool MyCustomActivateTool`. See [Skills — Custom Activation Tool](13_SKILLS.md#custom-activation-tool).
+Per-agent override is available inside the `skills` block via `activate_tool MyCustomActivateTool`. See [Skills — Custom Activation Tool](SKILLS.md#custom-activation-tool).
 
 #### Default backend
 
@@ -117,11 +117,11 @@ end
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | `enabled`          | The kill switch, consulted on every span — flipping it at runtime takes effect immediately, short-circuiting to a no-op ahead of the backend. Accepts booleans or `'true'`/`'false'`/`'1'`/`'0'`. Defaults to `true`.                                                                                                                                                                                                                                                                                                                                              |
 | `capture_messages` | Opt-in capture of full message content on LLM-call spans (`gen_ai.input.messages`, `gen_ai.output.messages`, `gen_ai.system_instructions`) as GenAI-semconv JSON. Defaults to `false` — message content routinely carries sensitive data. File attachments serialize as metadata-only stubs (media type and name, never bytes), and riffer applies no size limit of its own — cap oversized attributes with the OTEL SDK attribute length limits.                                                                                                                  |
-| `backend`          | The backend riffer routes spans through. Assign `Riffer::Tracing::Otel.build` (pass `provider:` to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (`in_span` / `current_context` / `with_context`) to route into a non-OTEL system (e.g. Datadog APM). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to `in_span`. See [Tracing → Routing to a non-OpenTelemetry backend](16_TRACING.md#routing-to-a-non-opentelemetry-backend). |
+| `backend`          | The backend riffer routes spans through. Assign `Riffer::Tracing::Otel.build` (pass `provider:` to override the global tracer provider — e.g. an in-memory provider in tests), or any object satisfying the duck-typed contract (`in_span` / `current_context` / `with_context`) to route into a non-OTEL system (e.g. Datadog APM). Defaults to `nil` — a no-op. Raises `Riffer::ArgumentError` unless the value is `nil` or responds to `in_span`. See [Tracing → Routing to a non-OpenTelemetry backend](TRACING.md#routing-to-a-non-opentelemetry-backend). |
 
 ### Pricing
 
-Configure per-model token prices and riffer computes the cost of each LLM call onto its [`TokenUsage`](08_MESSAGES.md#token-usage-semantics). Riffer ships **no** price table — so an unconfigured model simply carries no cost (`token_usage.cost` is `nil`).
+Configure per-model token prices and riffer computes the cost of each LLM call onto its [`TokenUsage`](MESSAGES.md#token-usage-semantics). Riffer ships **no** price table — so an unconfigured model simply carries no cost (`token_usage.cost` is `nil`).
 
 ```ruby
 Riffer.configure do |config|
@@ -151,7 +151,7 @@ cost = (input − cache_read − cache_write) × input_rate
      + output      × output_rate
 ```
 
-(all rates ÷ 1,000,000; an unset cache rate falls back to `input_rate`.) Cost is for observability, not billing — it's a `Float`, and sub-cent rounding can accumulate over a long run. See [Messages → Token Usage Semantics](08_MESSAGES.md#token-usage-semantics) for how cost surfaces and aggregates.
+(all rates ÷ 1,000,000; an unset cache rate falls back to `input_rate`.) Cost is for observability, not billing — it's a `Float`, and sub-cent rounding can accumulate over a long run. See [Messages → Token Usage Semantics](MESSAGES.md#token-usage-semantics) for how cost surfaces and aggregates.
 
 ### Message ID Strategy
 
@@ -173,7 +173,7 @@ When the strategy is not `:none`, every `Riffer::Messages::Base` instance — us
 
 When constructing a `Riffer::Agent::Session` from persisted history with the strategy enabled, supply ids on every seeded message yourself — Riffer never fabricates identifiers for pre-existing history. Messages built via the `Riffer::Messages::*` constructors auto-generate ids per the strategy, so as long as those constructors are used at message-creation time, ids flow through.
 
-See [Messages — IDs](08_MESSAGES.md#ids) for more details.
+See [Messages — IDs](MESSAGES.md#ids) for more details.
 
 ### Experimental: History Healing
 
@@ -194,7 +194,7 @@ When enabled, two repairs run automatically:
 
 Defaults to `false` — pre-healing behavior. Seeded sessions pass through untouched, and orphan `tool_use` left by an interrupt remain in history for `execute_pending_tool_calls` to re-run on the next call.
 
-There is no per-call override and no customizable placeholder. Callers needing finer control can call `agent.session.update(tool_call_id:, ...)` after the interrupt returns to upgrade a placeholder in place. See [Agent Lifecycle — Healing pending tool results on interrupt](04_AGENT_LIFECYCLE.md#healing-pending-tool-results-on-interrupt-experimental).
+There is no per-call override and no customizable placeholder. Callers needing finer control can call `agent.session.update(tool_call_id:, ...)` after the interrupt returns to upgrade a placeholder in place. See [Agent Lifecycle — Healing pending tool results on interrupt](AGENT_LIFECYCLE.md#healing-pending-tool-results-on-interrupt-experimental).
 
 ## Agent-Level Configuration
 

data/docs/{02_GETTING_STARTED.md → GETTING_STARTED.md}

@@ -24,7 +24,7 @@ gem install riffer
 
 ## Provider Setup
 
-Riffer requires an LLM provider. See [Providers](providers/01_PROVIDERS.md) for setup instructions for each supported provider.
+Riffer requires an LLM provider. See [Providers](providers/PROVIDERS.md) for setup instructions for each supported provider.
 
 ## Creating Your First Agent
 
@@ -91,8 +91,8 @@ puts agent.generate("What time is it?")
 
 ## Next Steps
 
-- [Agents](03_AGENTS.md) - Agent configuration options
-- [Tools](06_TOOLS.md) - Creating tools with parameters
-- [Messages](08_MESSAGES.md) - Message types and history
-- [Stream Events](09_STREAM_EVENTS.md) - Streaming event types
-- [Providers](providers/01_PROVIDERS.md) - Provider-specific guides
+- [Agents](AGENTS.md) - Agent configuration options
+- [Tools](TOOLS.md) - Creating tools with parameters
+- [Messages](MESSAGES.md) - Message types and history
+- [Stream Events](STREAM_EVENTS.md) - Streaming event types
+- [Providers](providers/PROVIDERS.md) - Provider-specific guides

data/docs/{14_MCP.md → MCP.md}

@@ -91,7 +91,7 @@ Tool names must be unique across `uses_tools` and all included MCP servers; dupl
 
 ### Subclassing
 
-Like [`uses_tools`](03_AGENTS.md#uses_tools), **`use_mcp` is not inherited** from the superclass. Declare `use_mcp` on each agent class that should load MCP tools.
+Like [`uses_tools`](AGENTS.md#uses_tools), **`use_mcp` is not inherited** from the superclass. Declare `use_mcp` on each agent class that should load MCP tools.
 
 ## Progressive Tool Discovery
 

data/docs/{08_MESSAGES.md → MESSAGES.md}

@@ -77,7 +77,7 @@ end
 
 The cache buckets are subsets of `input_tokens`, never additions to it — summing `input_tokens + cache_read_tokens` double-counts. `total_tokens` (input + output) matches the totals providers report on their dashboards.
 
-- `cost` — the computed cost of the call, set when pricing is configured for the model in use (see [Configuration → Pricing](10_CONFIGURATION.md#pricing)); `nil` when the model is unpriced. It's for observability, not billing. Run-level usage sums per-call costs through `TokenUsage#+`, so `response.token_usage.cost` is the total spend across the run — but the sum is `nil` if any call in the run used an unpriced model, rather than silently under-reporting.
+- `cost` — the computed cost of the call, set when pricing is configured for the model in use (see [Configuration → Pricing](CONFIGURATION.md#pricing)); `nil` when the model is unpriced. It's for observability, not billing. Run-level usage sums per-call costs through `TokenUsage#+`, so `response.token_usage.cost` is the total spend across the run — but the sum is `nil` if any call in the run used an unpriced model, rather than silently under-reporting.
 
 #### Finish Reasons
 
@@ -269,7 +269,7 @@ When creating tool result messages, use the `id` as `tool_call_id`.
 
 Agents can emit messages as they're added during generation via the `on_message` callback. This is useful for persistence or real-time logging. Only agent-generated messages (Assistant, Tool) are emitted—not inputs (System, User).
 
-See [Agent Lifecycle - on_message](04_AGENT_LIFECYCLE.md#on_message) for details.
+See [Agent Lifecycle - on_message](AGENT_LIFECYCLE.md#on_message) for details.
 
 ## Consecutive Message Merging
 
@@ -317,7 +317,7 @@ msg.id     # => "0195a2e1-..." (auto-generated UUIDv7)
 msg.to_h   # => {role: :user, content: "Hello", id: "0195a2e1-..."}
 ```
 
-Supported strategies: `:none` (default), `:uuid`, `:uuidv7`. See [Configuration — Message ID Strategy](10_CONFIGURATION.md#message-id-strategy) for the full reference.
+Supported strategies: `:none` (default), `:uuid`, `:uuidv7`. See [Configuration — Message ID Strategy](CONFIGURATION.md#message-id-strategy) for the full reference.
 
 Ids pass through to subclass constructors via an `id:` kwarg and are preserved when set explicitly:
 
@@ -357,4 +357,4 @@ Subclasses implement `role` and optionally extend `to_h` with additional fields.
 
 ## Editing history after the fact
 
-The session's `messages` array is mutable, but the message value objects themselves are immutable. To edit recorded history — truncate an assistant message, rewrite a tool result, fill an orphan `tool_use` — use the mutators on `agent.session` (`update`, `remove`). Each one enforces the `tool_use` ↔ `tool_result` invariant. See [Mutating history](04_AGENT_LIFECYCLE.md#mutating-history) for the full list.
+The session's `messages` array is mutable, but the message value objects themselves are immutable. To edit recorded history — truncate an assistant message, rewrite a tool result, fill an orphan `tool_use` — use the mutators on `agent.session` (`update`, `remove`). Each one enforces the `tool_use` ↔ `tool_result` invariant. See [Mutating history](AGENT_LIFECYCLE.md#mutating-history) for the full list.