diff --git a/AGENTS.md b/AGENTS.md
index bf199f4..413eb99 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,6 +2,8 @@
 
 This repository implements VectorLint — a prompt‑driven, structured‑output content reviewer. Use this guide to navigate the codebase, run it locally, and contribute safely.
 
+Use [`CONTEXT.md`](./CONTEXT.md) as the shared VectorLint domain language across code, docs, tests, and agent work. Prefer its terms when naming modules, writing tests, drafting docs, and describing architecture.
+
 ## Project Structure & Module Organization
 
 - `src/`
@@ -77,6 +79,18 @@ These guidelines reduce common LLM coding mistakes. They bias toward caution ove
 - Keep security and scope-boundary comments when they explain constraints that the implementation must preserve.
 - Test supported behavior and current invariants; do not add negative tests solely to memorialize rejected designs.
 
+### Documentation Artifact Boundaries
+
+- Do not commit raw planning or investigation artifacts to the product codebase.
+- Keep audits, plans, specs, run notes, and similar coordination artifacts out of tracked repo paths such as `docs/audits/`, `docs/plans/`, `docs/specs/`, `audits/`, `plans/`, and `specs/`.
+- Store coordination artifacts in `.agent-runs/` or another ignored workspace location.
+- If a durable architectural decision must be committed, write it as an ADR. ADRs are the only allowed committed decision/planning artifacts.
+- Product documentation may describe shipped behavior, configuration, and usage, but it must not preserve internal audit, plan, or spec documents as reviewed product docs.
+- `CONTEXT.md` is the project’s ubiquitous language. It may define internal domain concepts needed by contributors, provided those concepts use the same terminology users encounter.
+- `AGENTS.md` should require consistent terminology across code, tests, and documentation.
+- User-facing `/docs` should use only the subset of that language needed for user goals.
+- Internal contracts, processing stages, tool names, architecture constraints, and rejected alternatives should not leak into `/docs` merely because they exist in `CONTEXT.md`.
+
 ## Configuration System
 
 ### Quick Start
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..34b48e9
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,147 @@
+# VectorLint
+
+VectorLint is a content review harness. This language file defines the terms used to describe reviews, rules, findings, scoring, and execution so product, documentation, tests, and code can share the same vocabulary.
+
+## Language
+
+### Review Model
+
+**Content Review Harness**:
+A system that reviews supplied target content against source-backed rules and returns structured review results. The harness does not own exploration, research, workspace search, or content rewriting.
+_Avoid_: Autonomous agent, workspace agent, agent mode
+
+**Review**:
+A review of target content against one or more rules. It produces findings, scores, diagnostics, usage metadata, and output.
+_Avoid_: Lint run when referring to the domain process, agent session
+
+### Review Inputs
+
+**Caller**:
+The person or system that invokes VectorLint and supplies the target, target content, and any allowed review context. A caller does not define rules or configuration as part of the review invocation.
+_Avoid_: Agent, user agent, workspace owner
+
+**Target**:
+The subject of a review. A target identifies what VectorLint is reviewing, regardless of whether it came from a file, memory, or another caller-provided source.
+_Avoid_: File when the review subject may not be a file, page when the content may not be documentation
+
+**Target File**:
+A file used as the source of a target. A target file is one way to provide target content, but not every target must come from a file.
+_Avoid_: Target when the distinction between the file and the review subject matters
+
+**Target Content**:
+The actual text or content body reviewed for a target. Findings and finding evidence are grounded in target content.
+_Avoid_: Target file, page content
+
+**Review Context**:
+Additional content explicitly supplied to VectorLint for a review. Review context is in scope only because it was allowed as part of the review input.
+_Avoid_: Caller context, workspace context, discovered context, ambient context
+
+**On-Page Boundary**:
+The rule that VectorLint reviews only target content and review context. VectorLint must not discover arbitrary workspace files or expand the review scope on its own.
+_Avoid_: Workspace scope, project-wide scope, cross-file scope
+
+### Rules
+
+**Rule**:
+A source-backed instruction that defines observable violation conditions VectorLint should look for. Rules exist before a review is invoked.
+_Avoid_: Prompt when referring to the domain concept, model instruction when implying the model authored it
+
+**Via Negativa Review**:
+A review approach that looks for evidence a rule was violated rather than evidence the content aligns with an ideal. VectorLint rules should be written so a model can answer whether an observable violation condition is present.
+_Avoid_: Alignment review, subjective assessment
+
+**Violation Condition**:
+An observable yes/no condition that counts as a rule violation when present in target content. A violation condition should be specific enough to ground a finding in finding evidence.
+_Avoid_: Criterion when it implies subjective grading, preference, guideline
+
+**Rule Pack**:
+A named collection of related rules that can be applied together.
+_Avoid_: Preset when describing the domain concept, folder
+
+**Review Configuration**:
+Pre-existing settings that determine how VectorLint runs reviews, selects rules, and formats behavior. Configuration is not the same as target content or review context.
+_Avoid_: Caller input when referring to review invocation, target configuration
+
+**Check Rule**:
+A rule expressed through observable violation conditions. This is the only future-facing rule style in VectorLint.
+_Avoid_: Direct rule, standard rule
+
+### Execution
+
+**Model Call**:
+The call shape VectorLint uses to run a reviewer model against target content during a review.
+_Avoid_: Execution strategy, content access, process mode, rule type, mode
+
+**Single Model Call**:
+A model call where VectorLint supplies the review request and target content without giving the model a read tool. If VectorLint chunks a large target, each chunk is still reviewed through a single model call.
+_Avoid_: Direct strategy, standard mode, check path
+
+**Agent Model Call**:
+A bounded model call where the model may request sections of the target content through a single target-scoped read capability. This is for context management during large or context-sensitive reviews; it is not workspace exploration.
+_Avoid_: Autonomous agent mode, workspace agent, file reader
+
+**Auto Model Call**:
+The model call value where VectorLint deterministically chooses between single and agent.
+_Avoid_: Smart mode, agent fallback
+
+**Target Read Capability**:
+The bounded ability to read line ranges from target content. It cannot read arbitrary files, search the workspace, rewrite rules, or create top-level workspace findings.
+_Avoid_: Tool suite, workspace tools, read_file
+
+### Findings
+
+**Candidate Finding**:
+A potential issue raised before VectorLint has decided whether it should be reported. Candidate findings may be filtered out or become diagnostics.
+_Avoid_: Violation when the issue has not been accepted, result
+
+**Verified Finding**:
+A finding that VectorLint has accepted for reporting because it is grounded in the target content and passes review filters.
+_Avoid_: Issue when finding-evidence status matters, raw finding
+
+**Finding**:
+A reported content issue produced by a review. When precision matters, use candidate finding or verified finding.
+_Avoid_: Violation as the default user-facing term, problem
+
+**Finding Evidence**:
+The exact target-content text or surrounding context that supports a finding.
+_Avoid_: Quote when the text may include surrounding context, match when referring to the concept rather than a located span
+
+**Finding Evidence Verification**:
+The act of confirming that the finding evidence for a candidate finding can be located in the target content. Unverified finding evidence should not become a verified finding.
+_Avoid_: Line fallback, model-provided location
+
+**Finding Processing**:
+The review step that turns candidate findings into verified findings, diagnostics, scores, and final review output.
+_Avoid_: Projection, result processing, output processing
+
+**Diagnostic**:
+A structured note about review execution or finding processing, especially when something affects trust, completeness, or interpretation but is not itself a content finding.
+_Avoid_: Finding, warning when referring to the structured domain object
+
+### Scoring And Output
+
+**Severity**:
+The impact level attached to a finding or rule outcome.
+_Avoid_: Priority, importance
+
+**Score**:
+A normalized quality measurement for a rule or review. Scores come from verified finding count or density for objective violation checks.
+_Avoid_: Grade when referring to the domain object, rating
+
+**Review Result**:
+The structured outcome of a review: verified findings, scores, diagnostics, usage metadata, and operational status.
+_Avoid_: Projection result, formatter result, raw model output
+
+**Output Format**:
+The representation used to present a review result to a human or machine, such as line output or JSON.
+_Avoid_: Review result, report type
+
+**Review Budget**:
+The explicit limits for a review, such as model calls, target size, review context size, chunks per rule, and duration. A review budget limits work, not the number of verified findings emitted.
+_Avoid_: Rate limit, timeout when referring to the full budget concept
+
+### Historical Terms
+
+**Autonomous Agent Mode**:
+The old VectorLint direction where VectorLint exposed workspace tools to a model and let it explore beyond the target content. This is historical language only; current domain language should use single model call, agent model call, caller, and content review harness.
+_Avoid_: Agent mode as a current feature, workspace-agent review
diff --git a/README.md b/README.md
index 10016f7..bd2e433 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
-# VectorLint: Prompt it, Lint it! [![npm version](https://img.shields.io/npm/v/vectorlint.svg)](https://www.npmjs.com/package/vectorlint) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+# VectorLint [![npm version](https://img.shields.io/npm/v/vectorlint.svg)](https://www.npmjs.com/package/vectorlint) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
-VectorLint is a command-line tool that uses LLMs to find and score terminology, consistency, and style issues that require contextual understanding.
+VectorLint is a content review harness that turns observable quality standards into measurable feedback for agents.
+
+VectorLint reviews content against rules that describe observable traits. It returns structured, source-grounded findings and quality scores, giving agents repeatable signals they can use to revise content and review it again.
 
 ![VectorLint Screenshot](./assets/VectorLint_screenshot.jpeg)
 
@@ -30,35 +32,27 @@ Run VectorLint without installing:
 npx vectorlint path/to/article.md
 ```
 
-## Enforce Your Style Guide
+## Define Your Quality Standards
 
-Define rules as Markdown files with YAML frontmatter to enforce your specific content standards:
+Define rules as Markdown files with YAML frontmatter. Each rule describes the observable traits that indicate content does not meet one of your standards.
 
-- **Check SEO Optimization** - Verify content follows SEO best practices
-- **Detect AI-Generated Content** - Identify artificial writing patterns
-- **Verify Technical Accuracy** - Catch outdated or incorrect technical information
-- **Ensure Tone & Voice Consistency** - Match content to appropriate tone for your audience
+Rules can identify prohibited terminology, unsupported claims, repetitive explanations, vague guidance, or other quality issues specific to your content.
 
-If you can write a prompt for it, you can lint it with VectorLint.
+VectorLint works best when each rule states what evidence counts as a finding instead of asking for a general judgment of whether the content is good.
 
 👉 **[Learn how to create custom rules →](./CREATING_RULES.md)**
 
 ## Quality Scores
 
-VectorLint scores your content using error density, enabling you to measure quality across documentation. This gives your team a shared understanding of which content needs attention and helps track improvements over time.
-
-- **Density-Based Scoring:** For errors that can be counted, scores are calculated based on **error density (errors per 100 words)**, making quality assessment fair across documents of any length.
-
-## How VectorLint Reduces False Positives
+VectorLint turns review results into comparable quality signals. Agents can use those scores to measure whether revisions improve content across repeated review cycles.
 
-VectorLint uses a PAT (Pay A Tax) review approach:
+For countable findings, VectorLint calculates scores from error density, or findings per 100 words. This makes results comparable across content of different lengths.
 
-1. **Candidate generation:** the model returns all potential violations with required gate-check fields (rule support, exact evidence, context support, plausible non-violation, and fix quality).
-2. **Deterministic surfacing:** VectorLint applies a strict filter and only surfaces violations that pass all required gates.
+## Grounded Findings
 
-This means CLI output is intentionally stricter than raw model candidates, reducing noisy findings and improving precision.
+Every reported finding includes evidence from the reviewed content. VectorLint confirms that evidence can be located in the source and omits findings that cannot be grounded there.
 
-The confidence gate is user-configurable via:
+Adjust finding sensitivity with:
 
 ```bash
 CONFIDENCE_THRESHOLD=0.75
@@ -72,15 +66,15 @@ CONFIDENCE_THRESHOLD=0.75
 
 ### 1. Zero-Config Mode (Fastest)
 
-If you just want to check your content against a style guide:
+If you want to review content against a single set of quality standards:
 
 ```bash
 vectorlint init --quick
 ```
 
-This creates a `VECTORLINT.md` file where you can paste your style guide.
+This creates a `VECTORLINT.md` file where you can define your quality standards.
 
-> **Note:** You must set up your credentials in `~/.vectorlint/config.toml` (see Step 3) before running checks.
+> **Note:** Before running a review, set up your credentials in either `~/.vectorlint/config.toml` or a local `.env` file (see Step 3).
 
 Then run:
 
@@ -97,14 +91,15 @@ vectorlint init
 ```
 
 This creates:
+
 - **VectorLint Config** (`.vectorlint.ini`): Project-specific settings.
-- **App Config** (`~/.vectorlint/config.toml`): LLM provider API keys.
+- **App Config** (`~/.vectorlint/config.toml`): Model provider API keys.
 
 👉 **[Full configuration reference →](./CONFIGURATION.md)**
 
 ### 3. Configure API Keys
 
-Open your global **App Config** (`~/.vectorlint/config.toml`) and uncomment the section for your preferred LLM provider (OpenAI, Anthropic, Gemini, or Azure).
+Open your global **App Config** (`~/.vectorlint/config.toml`) and uncomment the section for your preferred model provider (OpenAI, Anthropic, Gemini, or Azure).
 
 ```toml
 [env]
@@ -114,7 +109,7 @@ OPENAI_API_KEY = "sk-..."
 
 > *Note: You can also use a local `.env` file in your project, which takes precedence over the global config.*
 
-**Run a check:**
+**Run a review:**
 
 ```bash
 vectorlint doc.md
@@ -124,9 +119,9 @@ VectorLint is bundled with a `VectorLint` preset containing rules for AI pattern
 
 👉 **[Learn how to create custom rules →](./CREATING_RULES.md)**
 
-### 4. Optional: Enable Langfuse observability
+### 4. Optional: Configure Langfuse observability
 
-VectorLint can emit AI execution telemetry through Langfuse without hardcoding Langfuse into the provider layer. This is best-effort instrumentation for the Vercel AI SDK calls used by `VercelAIProvider`.
+VectorLint can send model execution telemetry to Langfuse.
 
 Add these environment variables to your global config or local `.env` file:
 
@@ -144,11 +139,26 @@ Notes:
 - Prompts and outputs are recorded when Langfuse observability is enabled.
 - Do not send secrets, credentials, or PII unless your policy explicitly allows observability tooling to access that data.
 
+## Choose a Review Strategy
+
+VectorLint chooses a review strategy automatically. The default works for most
+content:
+
+```bash
+vectorlint doc.md
+```
+
+Use `--model-call` when you need to override that strategy for a particular
+review. Choose `single` for normal, self-contained documents or `agent` for
+large documents whose relevant context spans multiple sections.
+
+See [Model calls](docs/model-calls.mdx) for selection guidance and examples.
+
 ## Contributing
 
 We welcome your contributions! Whether it's adding new rules, fixing bugs, or improving documentation, please check out our [Contributing Guidelines](.github/CONTRIBUTING.md) to get started.
 
 ## Resources
 
-- **[Creating Custom Rules](./CREATING_RULES.md)** - Write your own quality checks in Markdown
+- **[Creating Rules](./CREATING_RULES.md)** - Define observable quality standards in Markdown
 - **[Configuration Guide](./CONFIGURATION.md)** - Complete reference for `.vectorlint.ini`
diff --git a/docs/best-practices.mdx b/docs/best-practices.mdx
index ed807cd..7b3bb2c 100644
--- a/docs/best-practices.mdx
+++ b/docs/best-practices.mdx
@@ -51,6 +51,20 @@ LLMs review content relative to an implied standard. Make that standard explicit
 
 A grammar rule without context produces generic grammar findings. The same rule with a developer audience context produces findings calibrated to technical writing conventions.
 
+## Write observable violation conditions
+
+VectorLint works best when each rule names what counts as a violation. Treat a rule as a checklist of conditions the reviewer can confirm from target evidence.
+
+```markdown
+Flag a headline when it:
+1. Omits the product or feature being discussed
+2. Promises a benefit that the article does not support
+3. Uses vague value words such as "seamless", "powerful", or "robust"
+4. Exceeds 70 characters
+```
+
+Observable conditions make findings easier to verify and reduce subjective disagreements during review.
+
 ## Tier strictness by content type
 
 Not all content deserves the same quality bar. Apply strictness in proportion to how much a failure costs — measured in user trust, support load, or brand impact.
diff --git a/docs/cli-reference.mdx b/docs/cli-reference.mdx
index b140f0b..3aecd2a 100644
--- a/docs/cli-reference.mdx
+++ b/docs/cli-reference.mdx
@@ -58,10 +58,35 @@ vectorlint --help
 
 ## Flags
 
-| Flag | Description |
-|------|-------------|
-| `--help` | Print help and exit |
-| `--version` | Print the installed VectorLint version and exit |
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--help` | — | Print help and exit |
+| `--version` | — | Print the installed VectorLint version and exit |
+| `--config <path>` | `.vectorlint.ini` | Path to a custom project config file |
+| `--debug-json` | `false` | Write debug JSON artifacts under `.vectorlint/runs/` |
+| `--model-call <value>` | `auto` | Review strategy: `single`, `agent`, or `auto` |
+| `--output <format>` | `line` | Output format: `line`, `json`, `vale-json`, or `rdjson` |
+| `--show-prompt` | `false` | Print full prompt and injected content |
+| `--show-prompt-trunc` | `false` | Print truncated prompt/content previews |
+| `--verbose` | `false` | Enable verbose logging |
+
+### `--model-call`
+
+`--model-call` selects the review strategy. Leave the default, `auto`, enabled for most reviews.
+
+```bash
+vectorlint doc.md --model-call single
+vectorlint doc.md --model-call agent
+vectorlint doc.md --model-call auto
+```
+
+| Value | Use it for |
+| --- | --- |
+| `auto` | Most reviews; VectorLint selects a strategy for the current document |
+| `single` | Normal, self-contained documents and focused rules |
+| `agent` | Large documents or reviews that compare context across sections |
+
+See [Model calls](/model-calls) for usage guidance.
 
 ## Output
 
diff --git a/docs/docs.json b/docs/docs.json
index a4f8e34..0f99546 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -67,6 +67,7 @@
         "group": "Reference",
         "pages": [
           "cli-reference",
+          "model-calls",
           "configuration-schema",
           "env-variables",
           "frontmatter-fields",
diff --git a/docs/how-it-works.mdx b/docs/how-it-works.mdx
index dbede09..b2adb6d 100644
--- a/docs/how-it-works.mdx
+++ b/docs/how-it-works.mdx
@@ -1,58 +1,49 @@
 ---
 title: How it works
-description: How VectorLint reviews content, filters findings, and calculates scores.
+description: How VectorLint applies rules, verifies findings, and reports results.
 ---
 
-VectorLint sends your content to a large language model (LLM) with a structured prompt that defines your quality criteria. The model returns candidate findings, which VectorLint filters through a deterministic pipeline before surfacing violations in the CLI.
+VectorLint reviews target files against your content rules and reports specific, evidence-backed findings.
 
-If you haven't run your first check yet, start with the [Quickstart](/quickstart). This page is for understanding the architecture behind what you're running.
+If you haven't run your first review yet, start with the [Quickstart](/quickstart). This page explains what happens when you run that command.
 
 ## The review pipeline
 
-Every time you run `vectorlint doc.md`, three things happen in sequence.
+Every time you run `vectorlint doc.md`, VectorLint follows the same high-level path.
 
-### 1. Rule resolution
+### 1. Resolve targets and rules
 
-VectorLint reads your `.vectorlint.ini` to determine which rule packs apply to the file. It loads those rule files, prepends the contents of `VECTORLINT.md` (if present) to each rule's system prompt, and assembles the review context.
+VectorLint reads your project configuration to determine which rule packs apply to each target file. It loads rule files, applies `VECTORLINT.md` as global review context when present, and builds source-backed rules.
 
-If no `.vectorlint.ini` exists, VectorLint detects `VECTORLINT.md` and creates a synthetic "Style Guide Compliance" rule automatically. This is the zero-config path — the fastest way to get from nothing to a working review without writing any rule pack files.
+If no `.vectorlint.ini` exists, VectorLint detects `VECTORLINT.md` and creates a synthetic style-guide rule automatically. This is the zero-config path.
 
-### 2. LLM review
+### 2. Choose a review strategy
 
-VectorLint sends your content to the configured LLM provider with each rule's prompt. The model returns a list of specific violations with supporting evidence.
+VectorLint uses `auto` by default and selects a strategy based on the content being reviewed. You can override the default with `--model-call` when a particular document needs a different strategy.
 
-Rules run concurrently up to the `Concurrency` limit set in `.vectorlint.ini`.
+See [Model calls](/model-calls) for selection guidance and CLI examples.
 
-### 3. Filtering
+### 3. Review the content
 
-Raw model output contains noise — potential violations that don't hold up under scrutiny. VectorLint reduces false positives through a two-phase filtering process:
+VectorLint reviews the target against each applicable rule. For long documents, it divides the content into manageable sections and combines the results.
 
-1. **Candidate generation** — the model returns all potential violations, each tagged with required fields: rule support, exact evidence, context support, plausible non-violation, and fix quality.
-2. **Deterministic surfacing** — VectorLint applies a strict filter and only surfaces violations that pass all required gates.
+### 4. Validate and score findings
 
-The CLI output is intentionally stricter than raw model candidates with fewer results and higher confidence.
+Before reporting a finding, VectorLint confirms that its quoted evidence appears in the target content. It removes duplicate findings and calculates a score from the verified violations.
 
-You can tune how aggressively the filter operates with `CONFIDENCE_THRESHOLD` (default: `0.75`). Lower values surface more findings with higher recall; higher values surface fewer findings with higher precision. See [Configuring LLM providers](/llm-providers) for details.
+Findings without locatable evidence are omitted from the reported violations.
 
-## Scoring
+### 5. Present the results
 
-VectorLint calculates error density from verified violations per 100 words. A single error in a short document weighs more heavily than the same error in a long one, which normalizes quality assessment across documents of different lengths.
+VectorLint presents the verified findings using the requested output format:
 
-See [Quality scoring](/quality-scoring) for the full scoring reference.
-
-## Two ways to define quality
-
-VectorLint gives you two complementary tools for expressing your content standards:
-
-- **`VECTORLINT.md`** — plain-language style instructions that apply globally to every review. The fastest path to useful output: no rule files, no configuration syntax, just plain English instructions that the LLM uses as context for every check.
-- **Rule pack files** — structured LLM prompts for specific, measurable standards. Use these when you need reproducible, auditable results on a particular dimension of quality.
-
-The two work together: `VECTORLINT.md` sets the baseline context, and rule pack files enforce specific criteria on top of it.
-
-See [Defining your style rules](/style-guide) for how to create both.
+- `line` for human-readable terminal output
+- `json` for VectorLint's native machine-readable output
+- `vale-json` for Vale-compatible integrations
+- `rdjson` for reviewdog-compatible integrations
 
 ## Next steps
 
-- [Quickstart](/quickstart) — run your first review in minutes
-- [Defining your style rules](/style-guide) — create VECTORLINT.md and write custom rules
-- [Configuring a project](/project-config) — map files to rule packs
+- [Model calls](/model-calls) — choose `single`, `agent`, or `auto`
+- [Defining your style rules](/style-guide) — create `VECTORLINT.md` and custom rules
+- [CLI reference](/cli-reference) — confirm command syntax and flags
diff --git a/docs/logs/2026-03-31-agent-mode-implementation-plan.log.md b/docs/logs/2026-03-31-agent-mode-implementation-plan.log.md
deleted file mode 100644
index 4c19efb..0000000
--- a/docs/logs/2026-03-31-agent-mode-implementation-plan.log.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Execution Log
-
-- **Plan**: `docs/plans/2026-03-31-agent-mode-implementation-plan.md`
-- **Issue**: Not provided (executed from user directive in this session)
-- **Started**: 2026-03-31
-- **Status**: completed
-
----
-
-## Tasks
-
-### Task: Implement agent mode runtime, wiring, and contracts from red tests
-- **Status**: completed
-- **What was done**: Implemented the provider agent-loop contract, built the new agent runtime modules (types, session store, path safety, progress, executor), wired CLI/orchestrator `--mode agent` and `--print`, and updated README agent-mode documentation.
-- **Files changed**: `src/providers/llm-provider.ts`, `src/providers/vercel-ai-provider.ts`, `src/agent/types.ts`, `src/agent/review-session-store.ts`, `src/agent/path-utils.ts`, `src/agent/progress.ts`, `src/agent/executor.ts`, `src/cli/types.ts`, `src/schemas/cli-schemas.ts`, `src/cli/commands.ts`, `src/cli/orchestrator.ts`, `tests/providers/vercel-ai-provider-agent-loop.test.ts`, `README.md`
-- **Tried**: Initial agent-mode wiring used `process.cwd()` as repository root, which broke tool-relative file resolution in orchestrator tests; switched to inferred common root across targets for agent execution.
-
-### Task: Wire lint context, user instructions, and request-failure attribution
-- **Status**: completed
-- **What was done**: Added per-call lint context prompt augmentation, passed `userInstructionContent` through agent-mode orchestrator into executor system prompt construction, and split request-failure counting from operational finalize/workflow errors in agent mode.
-- **Files changed**: `src/agent/executor.ts`, `src/agent/prompt-builder.ts`, `src/cli/orchestrator.ts`, `tests/agent/agent-executor.test.ts`, `tests/orchestrator-agent-output.test.ts`, `tests/agent/prompt-builder.test.ts`
-- **Tried**: Initial test assertions for prompt-builder expected older section headings (`Role:`/`Operating Policy`); updated assertions to match current builder copy while preserving behavior checks.
diff --git a/docs/model-calls.mdx b/docs/model-calls.mdx
new file mode 100644
index 0000000..ea09f5e
--- /dev/null
+++ b/docs/model-calls.mdx
@@ -0,0 +1,53 @@
+---
+title: Model calls
+description: Choose single, agent, or auto model calls for VectorLint reviews.
+---
+
+VectorLint supports three review strategies through `--model-call`. Leave the default, `auto`, enabled for most reviews. Override it when the size or structure of a particular document calls for a different strategy.
+
+## Choose a strategy
+
+| Value | Use it for |
+| --- | --- |
+| `auto` | Most reviews. VectorLint selects a strategy for the current document. |
+| `single` | Normal, self-contained documents and focused rules. |
+| `agent` | Large documents or reviews that need to compare context across multiple sections. |
+
+## Use the default
+
+```bash
+vectorlint doc.md
+```
+
+This is equivalent to:
+
+```bash
+vectorlint doc.md --model-call auto
+```
+
+## Override the default
+
+Choose `single` for a normal, self-contained document:
+
+```bash
+vectorlint doc.md --model-call single
+```
+
+Choose `agent` for a large document or when a rule needs context from sections that are far apart:
+
+```bash
+vectorlint doc.md --model-call agent
+```
+
+Changing `--model-call` does not change which rules run, how findings are scored, or which output formats are available.
+
+## Combine with an output format
+
+```bash
+vectorlint doc.md --model-call agent --output json
+```
+
+## Related
+
+- [How it works](/how-it-works)
+- [CLI reference](/cli-reference)