@navels/neal 0.1.0 → 0.3.0

package/docs/providers.md

@@ -1,25 +1,22 @@
-# Provider Adapters
+# Provider adapters
 
-Neal's writer-run provider layer is an internal extension point for built-in
+neal's writer-run provider layer is an internal extension point for built-in
 agent SDK adapters. A provider adapter maps one SDK's sessions, tools,
 structured-output behavior, errors, usage data, and stream/message events into
-Neal-owned contracts.
+neal-owned contracts.
 
-Neal currently ships built-in adapters for:
+neal currently ships built-in adapters for:
 
 - `openai-codex`
 - `anthropic-claude`
-- `openai-compatible` (structured-advisor/reviewer roles only, backed by the
-  AI SDK's OpenAI-compatible chat provider; see
-  [OpenAI-Compatible Endpoints](#openai-compatible-endpoints))
-- `generic-agentic` (Neal-owned agentic writer for any OpenAI-compatible
-  tool-calling endpoint; coder-first, with a tool-capable read-only
-  structured-advisor/reviewer path; see
-  [Generic Agentic Writer](#generic-agentic-writer))
-
-Neal does not currently load external provider plugins or discover
+- `openai-compatible`, a neal-owned agent loop for any OpenAI-compatible
+  tool-calling endpoint, with writer tools for the coder and read-only tools
+  for the reviewer. See
+  [OpenAI-compatible provider](#openai-compatible-provider).
+
+neal does not currently load external provider plugins or discover
 npm-installed providers. Public `neal review` is a separate read-only findings
-flow that uses configured provider adapters; it is not a writer-run mode and is
+flow that uses configured provider adapters. It is not a writer-run mode and is
 not a registered provider id.
 
 `neal setup` can inspect local built-in provider runtime availability while
@@ -29,7 +26,7 @@ entrypoint and Claude SDK-bundled or standalone executable paths, but it does
 not authenticate, send prompts, collect secrets, or verify account state. Use
 `neal check` after setup for the live provider connectivity prompt.
 
-## Contract Overview
+## Contract overview
 
 Provider contracts live in `src/neal/providers/types.ts`. A built-in provider
 module should export a `NealProviderDefinition` plus any focused test hooks it
@@ -50,7 +47,7 @@ checks all resolve provider identity through that registry.
 
 ## Roles
 
-Neal exposes three effective agent roles for writer runs:
+neal exposes three effective agent roles for writer runs:
 
 - `planner`: writes and revises plan artifacts through the coder adapter surface.
   It inherits the coder provider/model unless configured explicitly.
@@ -59,8 +56,8 @@ Neal exposes three effective agent roles for writer runs:
 - `reviewer`: runs schema-oriented rounds for review, plan review, support, and
   final completion review work through the structured-advisor adapter surface.
 
-Provider capability roles remain `coder` and `structured-advisor`; `planner` is
-a Neal role label backed by the configured provider's coder adapter. The same
+Provider capability roles remain `coder` and `structured-advisor`. `planner` is
+a neal role label backed by the configured provider's coder adapter. The same
 provider may support both capability roles, or only one. The checked-in config
 template and first-run setup examples use `openai-codex` for the coder role and
 `anthropic-claude` for the reviewer role, but fresh writer runs still require
@@ -77,17 +74,16 @@ Each provider capability role declares:
 - read, write, and shell tool access
 - session resume support
 - model override support
-- Neal structured control protocol support
+- neal structured control protocol support
 - usage reporting support
 
-Capabilities are enforced before writer work starts or resumes. Neal requires
+Capabilities are enforced before writer work starts or resumes. neal requires
 the planner and coder effective roles to resolve to providers with the coder
-capability, write and shell access, and Neal structured control protocol support.
+capability, write and shell access, and neal structured control protocol support.
 The reviewer effective role must resolve to a provider with the
-structured-advisor capability and either read tool access or structured-output
-support that lets Neal inline the review context (full diff, plan document, and
-run artifacts) directly into reviewer prompts. Session resume support is
-required when a persisted session handle is present.
+structured-advisor capability and read tool access: every reviewer inspects
+the repository directly. Session resume support is required when a persisted
+session handle is present.
 
 Current built-in capabilities are intentionally conservative:
 
@@ -95,35 +91,30 @@ Current built-in capabilities are intentionally conservative:
   read, write, and shell capable because the current SDK configuration uses
   broad local access. The structured-advisor (reviewer) role is read capable
   but never write or shell capable (see
-  [The Read-Only Reviewer Invariant](#the-read-only-reviewer-invariant)).
+  [The read-only reviewer invariant](#the-read-only-reviewer-invariant)).
 - Anthropic Claude supports coder and structured-advisor roles. The coder role
   is read, write, and shell capable. The structured-advisor (reviewer) role is
   read capable but never write or shell capable.
-- OpenAI-Compatible supports only the structured-advisor role, with no read,
-  write, or shell tool access and no session resume. Neal compensates by
-  inlining reviewer context into prompts; see
-  [OpenAI-Compatible Endpoints](#openai-compatible-endpoints).
-- Generic Agentic supports coder and structured-advisor roles. The coder role
-  is read, write, and shell capable through Neal-owned tools executed locally.
-  The structured-advisor role is read capable (a read-only toolset; no write
-  or shell access), so a generic reviewer inspects the repository directly
-  with read tools instead of receiving Neal-inlined context. Neither role
-  supports session resume. See
-  [Generic Agentic Writer](#generic-agentic-writer).
+- OpenAI-compatible supports coder and structured-advisor roles. The coder
+  role is read, write, and shell capable through neal-owned tools executed
+  locally. The structured-advisor role is read capable (a read-only toolset,
+  no write or shell access), so its reviewer inspects the repository directly
+  with read tools. Neither role supports session resume. See
+  [OpenAI-compatible provider](#openai-compatible-provider).
 
 The `coder` capability describes adapter paths, not a global promise that every
 writer-run workflow is read-only: writer-run coder turns use provider SDKs with
 broad local permissions. The separate public `neal review` command enforces its
 own read-only boundary in the review command flow.
 
-### Coder Tool Policy Enforcement
+### Coder tool policy enforcement
 
 Plan-authoring rounds pass a `toolPolicy` (`allowedWritePaths` restricted to
 the plan document, `allowRun: false`) to the coder adapter. Enforcement
 strength is adapter-specific and mechanical where each SDK allows it:
 
-- `generic-agentic`: full jail. The policy selects the Neal-owned plan-author
-  toolset — writes only to the allowlisted paths, no shell tool at all.
+- `openai-compatible`: full jail. The policy selects the neal-owned plan-author
+  toolset: writes only to the allowlisted paths, no shell tool at all.
 - `anthropic-claude`: tool exclusion plus a path callback. `allowRun: false`
   removes Bash from the turn's tools list, and a PreToolUse hook denies any
   write-class tool call whose resolved path is not allowlisted.
@@ -136,27 +127,26 @@ strength is adapter-specific and mechanical where each SDK allows it:
 Rounds without a `toolPolicy` are unaffected on every adapter: ordinary coder
 scope rounds keep full access because verification legitimately runs commands.
 
-### The Read-Only Reviewer Invariant
+### The read-only reviewer invariant
 
-A reviewer exists to *judge*, never to *modify* or *re-execute*. Neal enforces
+A reviewer exists to *judge*, never to *modify* or *re-execute*. neal enforces
 this structurally: every *supported* `structured-advisor` capability has
 `write: false` and `shell: false`. The invariant constrains only `write` and
-`shell` — `read` is intentionally left unconstrained, so it stays `true` for
-read-tool reviewers (`openai-codex`, `anthropic-claude`, `generic-agentic`) and
-`false` for the inline-context reviewer (`openai-compatible`, which reviews from
-Neal-inlined context rather than read tools).
+`shell`. `read` is not part of the invariant, but every built-in reviewer
+(`openai-codex`, `anthropic-claude`, `openai-compatible`) declares read access,
+and the writer-run capability check requires it.
 
 `src/neal/providers/registry.ts` asserts this over every registered provider
-definition — built-in or test-registered — at the definition-resolution
+definition (built-in or test-registered) at the definition-resolution
 chokepoint and at test registration time, so no provider definition can ever
 declare a writing or shell-running reviewer. The assertion checks only the
-`write`/`shell` half; it never constrains `read`, and it never touches the
+`write`/`shell` half. It never constrains `read`, and it never touches the
 `coder` capability (coders keep `write`/`shell`).
 
 Two consequences follow from no reviewer holding shell access:
 
 - Reviewers never re-run tests or other verification. Verification happens once,
-  performed by the coder; the reviewer trusts the coder's reported result plus
+  performed by the coder. The reviewer trusts the coder's reported result plus
   its own reading of the diff and (for read-tool reviewers) the repository.
 - Reviewers never mutate the checkout. A review produces a verdict and findings,
   not edits.
@@ -164,23 +154,23 @@ Two consequences follow from no reviewer holding shell access:
 Usage reporting is `opportunistic`: providers emit usage only when the SDK
 event or result supplies it.
 
-### Review Doctrine Access Modes
+### Review doctrine access modes
 
-Reviewer prompts render Neal's shared review doctrine in one of three access
+Reviewer prompts render neal's shared review doctrine in one of two access
 modes, derived from the configured reviewer provider's structured-advisor
 tool access:
 
-- `read-only` (read access without shell access; `openai-codex`,
-  `anthropic-claude`, and `generic-agentic` today): the reviewer is instructed
-  to inspect the repository through read tools only — reading changed files and
-  searching the tree — and is never instructed to run commands, run tests, or
-  use scratch directories. Commit-range visibility depends on whether the
-  provider exposes its own range-diff tool:
-  - `generic-agentic` declares a read-only `git_diff` commit-range tool
+- `read-only` (read access without shell access, which every built-in reviewer
+  today): the reviewer is instructed to inspect the repository through read
+  tools only (reading changed files and searching the tree) and is never
+  instructed to run commands, run tests, or use scratch directories.
+  Commit-range visibility depends on whether the provider exposes its own
+  range-diff tool:
+  - `openai-compatible` declares a read-only `git_diff` commit-range tool
     (`providesRangeDiffTool`), so its reviewer inspects the range with that tool
     and receives no inlined diff.
   - native read-only reviewers such as `openai-codex` and `anthropic-claude`
-    have read and search tools but no commit-range diff tool, so Neal inlines
+    have read and search tools but no commit-range diff tool, so neal inlines
     the commit-range diff into the reviewer prompt as the source of truth for
     what the range changed (including deletions and renames that head-state file
     reads cannot reveal), and the reviewer uses its read/search tools to verify
@@ -189,28 +179,23 @@ tool access:
   In both branches the doctrine states that absence from a diff is not evidence
   of absence from the repository: the reviewer must open files with read tools
   before claiming a missing import or declaration.
-- `no-read` (no repository read access; `openai-compatible` today): Neal
-  inlines the review context — the full diff, plan document content, review
-  history, and run artifacts, with per-section truncation caps — directly
-  into reviewer prompts, and the doctrine never instructs repository, file,
-  tool, or shell access.
 - `tool-access` (read and shell access): a reviewer is instructed to inspect
   and execute against the repository directly. Because the read-only reviewer
   invariant forbids any supported `structured-advisor` capability from holding
   shell access (see
-  [The Read-Only Reviewer Invariant](#the-read-only-reviewer-invariant)), no
-  built-in reviewer resolves to this mode today; it would require a
+  [The read-only reviewer invariant](#the-read-only-reviewer-invariant)), no
+  built-in reviewer resolves to this mode today. It would require a
   shell-capable reviewer, which the registry assertion rejects.
 
-Neither shell-less read-tool reviewers nor the inline-context reviewer are ever
-instructed to run verification: the doctrine reflects that verification is the
-coder's, trusted by the reviewer's reading or inlined context. Write access does
-not affect review doctrine: reviews never instruct repository mutation, and no
-supported reviewer capability declares write access in any case.
+Read-tool reviewers are never instructed to run verification: the doctrine
+reflects that verification is the coder's, trusted by the reviewer's reading.
+Write access does not affect review doctrine: reviews never instruct repository
+mutation, and no supported reviewer capability declares write access in any
+case.
 
-## Runtime Turns
+## Runtime turns
 
-Provider adapters receive Neal-owned turn arguments rather than reading Neal
+Provider adapters receive neal-owned turn arguments rather than reading neal
 configuration directly.
 
 Plain coder turns receive:
@@ -220,7 +205,7 @@ Plain coder turns receive:
 - `inactivityTimeoutMs`
 - optional `resumeHandle`
 - optional structured `outputSchema`, retained only for raw coder prompt
-  compatibility outside Neal product control paths
+  compatibility outside neal product control paths
 - optional `onSessionStarted` callback
 - optional provider event sink
 
@@ -257,9 +242,9 @@ All turn argument shapes also accept an optional `signal` (`AbortSignal`).
 Adapters must treat an aborted signal as a request to terminate the in-flight
 SDK turn and surface a normalized provider error rather than hanging.
 
-### Turn Liveness
+### Turn liveness
 
-Neal layers two independent timeouts over every provider turn:
+neal layers two independent timeouts over every provider turn:
 
 - `neal.agent_turn_startup_timeout_ms` (default `300000`) bounds startup
   silence: the window after a turn starts during which the provider has shown
@@ -271,15 +256,15 @@ Neal layers two independent timeouts over every provider turn:
   progress, the startup timer disarms permanently and only this timeout
   applies.
 
-When the startup timer fires, Neal aborts the silent attempt via the turn's
+When the startup timer fires, neal aborts the silent attempt via the turn's
 `signal` and retries the same turn up to `neal.agent_turn_retry_limit` times
-(default `1`). This means Neal may rerun a turn even though the provider never
+(default `1`). This means neal may rerun a turn even though the provider never
 reported an error: the provider went silent before doing any work, which is
 indistinguishable from a stalled SDK stream. Retries are safe because zero
 observable progress was made. Keep `agent_turn_retry_limit` low (the default of
-1 is recommended); persistent startup silence usually indicates a provider or
+1 is recommended). Persistent startup silence usually indicates a provider or
 network problem that more retries will not fix. Coder turns that resume an
-existing session are never retried by this layer; the orchestrator's existing
+existing session are never retried by this layer. The orchestrator's existing
 fresh-session recovery owns those.
 
 Liveness outcomes are auditable in `events.ndjson` as
@@ -294,48 +279,49 @@ Provider session handles are opaque strings. Providers should preserve and
 return the SDK session handle when one exists, including on normalized failures
 where the SDK exposed a session before the failure.
 
-Neal persists handles separately for planner, coder, and reviewer work. Resume
+neal persists handles separately for planner, coder, and reviewer work. Resume
 checks fail early if the configured provider role does not support session
 resume and a persisted handle must be resumed.
 
-## Structured Output
+## Structured output
 
-Neal product control paths use `neal-json-block-v1`. Provider adapters transport
+neal product control paths use `neal-json-block-v1`. Provider adapters transport
 assistant text, preserve session handles, normalize SDK errors, and delegate
 control-payload extraction, parsing, validation, bounded repair, telemetry, and
-normalized structured-output errors to Neal's shared runtime. The
-`generic-agentic` writer is the one exception: it consumes the same protocol
-spec (schema, validator, labels) but fulfills it through the AI SDK's native
-structured-output channel in a dedicated finalization turn, with no fenced-text
-transport — see [Generic Agentic Writer](#generic-agentic-writer).
-
-Coder adapters expose `runStructuredPrompt<TStructured>()` for Neal-owned
+normalized structured-output errors to neal's shared runtime. The
+`openai-compatible` adapter is the one exception: its coder and
+structured-advisor paths consume the same protocol spec (schema, validator,
+labels) but fulfill it through the AI SDK's native structured-output channel in
+a dedicated finalization turn, with no fenced-text transport. See
+[OpenAI-compatible provider](#openai-compatible-provider).
+
+Coder adapters expose `runStructuredPrompt<TStructured>()` for neal-owned
 structured coder decisions. That method receives a caller-owned
 `neal-json-block-v1` protocol spec, returns the typed `structured` object plus
 the provider `sessionHandle`, emits `structured_output_received` only after
-Neal validation succeeds, and normalizes missing structured control payloads as
+neal validation succeeds, and normalizes missing structured control payloads as
 `structured_output_missing`.
 
 `runPrompt(..., outputSchema)` remains supported for compatibility with
-older raw coder harness coverage. `neal check` and Neal-owned coder decision
+older raw coder harness coverage. `neal check` and neal-owned coder decision
 rounds use `neal-json-block-v1` through `runStructuredPrompt()` rather than
 parsing provider JSON strings in round code.
 
-Neal's shared `neal-json-block-v1` runtime appends provider-neutral transport
+neal's shared `neal-json-block-v1` runtime appends provider-neutral transport
 instructions requiring optional useful prose followed by exactly one final
 fenced `neal-json` JSON block. It then extracts, parses, validates, and repairs
 that control object with the caller-supplied schema label, schema, validator,
 and repair limit. Raw whole-response JSON objects are accepted only as a
-compatibility tolerance for older mocks and pre-migration paths; the prompt
+compatibility tolerance for older mocks and pre-migration paths. The prompt
 contract remains prose plus one final `neal-json` block. State-facing
-`structured_output_received` telemetry is emitted only after Neal validation
+`structured_output_received` telemetry is emitted only after neal validation
 succeeds.
 
 Anthropic Claude and OpenAI Codex structured coder and structured-advisor
 protocol calls do not pass SDK-native `outputFormat` or `outputSchema`. Those
-SDK-native surfaces are compatibility details for non-Neal raw provider calls,
-not the Neal product protocol. Invalid or missing local JSON can recover through
-a bounded repair turn. Repair turns are side-effect-free by prompt; Claude
+SDK-native surfaces are compatibility details for non-neal raw provider calls,
+not the neal product protocol. Invalid or missing local JSON can recover through
+a bounded repair turn. Repair turns are side-effect-free by prompt. Claude
 repair turns also omit repo tools and session resume, and Codex repair turns run
 through the most restrictive available streamed-turn options.
 
@@ -374,8 +360,8 @@ round code should not import SDK-specific provider error classes.
 Normalized error kinds are:
 
 - `timeout`
-- `no_progress_timeout` (emitted by Neal's turn liveness supervisor, not by
-  adapters; see Turn Liveness above)
+- `no_progress_timeout` (emitted by neal's turn liveness supervisor, not by
+  adapters, as described under Turn liveness above)
 - `api_error`
 - `structured_output_missing`
 - `structured_output_invalid`
@@ -388,10 +374,10 @@ Each normalized error carries the provider id, role, optional session handle,
 kind, retryability, and cause. Round code wraps normalized provider errors into
 round-level failures only when it needs round-specific context.
 
-## Status-Visible Errors
+## Status-visible errors
 
 Provider failures are visible to automation through `neal status --json` and
-`neal status --json --all` as `providerError`. Neal derives that summary from
+`neal status --json --all` as `providerError`. neal derives that summary from
 the latest `provider.provider_error` event when present, including timestamp,
 provider id, role, label, session handle, normalized kind, bounded message, and
 retryability. If a run failed before a provider event was available, status may
@@ -402,21 +388,21 @@ fall back to the latest `phase.error` as an unclassified run error with
 must not include SDK payloads, full prompts, provider `providerData`, full
 assistant text, raw command output, credentials, or environment dumps. Keep rich
 diagnostics in local support artifacts such as `events.ndjson` and
-`stderr.log`; public wrappers should use the bounded status summary.
+`stderr.log`. Public wrappers should use the bounded status summary.
 
-## Model Overrides
+## Model overrides
 
 Provider factories receive an optional model override from `agent.*.model`.
-`model: null` means Neal lets the provider choose its default model. A non-null
+`model: null` means neal lets the provider choose its default model. A non-null
 model is accepted only when the provider role declares `supportsModelOverride`.
 
 Model selection stays provider-local after the registry passes the configured
 override into the adapter factory.
 
-## Reasoning Effort Overrides
+## Reasoning effort overrides
 
 Each role accepts an optional reasoning-effort override from `agent.*.effort`.
-`effort: null` (or an omitted key) means Neal sends no effort option and the
+`effort: null` (or an omitted key) means neal sends no effort option and the
 provider uses its default reasoning depth. A non-null effort is mapped to the
 closest provider-native option: OpenAI Codex receives
 `ThreadOptions.modelReasoningEffort` and Anthropic Claude receives
@@ -426,10 +412,13 @@ Supported values are provider-specific:
 
 - `openai-codex`: `minimal`, `low`, `medium`, `high`, `xhigh`.
 - `anthropic-claude`: `low`, `medium`, `high`, `xhigh`, `max`.
-- `openai-compatible`: no supported values; any configured `effort` is rejected
-  with the standard effort config error.
-- `generic-agentic`: no supported values; any configured `effort` is rejected
-  with the standard effort config error.
+- `openai-compatible`: no supported values. Any configured `effort` is rejected
+  with the standard effort config error. This is a neal limitation, not a claim
+  that compatible endpoints cannot control reasoning. Some expose an effort or
+  token-budget setting, but the accepted values and behavior vary by endpoint
+  and model. Supporting that safely requires an endpoint-specific pass-through
+  or capability contract. Until then, neal leaves reasoning at the upstream
+  default.
 
 Effort support is declared per capability role. An effort value the configured
 provider does not support is rejected before a writer run starts or resumes with
@@ -442,20 +431,21 @@ is set explicitly, an omitted `agent.planner.effort` resolves to provider
 default (`null`) rather than inheriting the coder effort, so set
 `agent.planner.effort` explicitly to override it.
 
-## OpenAI-Compatible Endpoints
-
-The `openai-compatible` provider lets the reviewer role run against any
-OpenAI-compatible Chat Completions endpoint (DeepSeek, OpenRouter, vLLM, and
-similar). It is API-only and covers structured-advisor work: reviewer rounds
-for scope review, plan review, support, final completion, provider check, and
-`neal review` findings adjudication.
-
-The adapter is implemented on the AI SDK's OpenAI-compatible chat provider —
-the same substrate the `generic-agentic` writer uses — with the external
-contract unchanged: same provider id, same config block, same chat-only
-capabilities, same normalized error kinds and retryability, same provider
-events. Gateway behaviors learned from live failures are preserved through a
-Neal-owned response interceptor: upstream errors embedded as an `error`
+## OpenAI-compatible provider
+
+The `openai-compatible` provider runs the planner, coder, and reviewer roles
+against any OpenAI-compatible Chat Completions endpoint with a strong
+tool-calling model (OpenRouter, vLLM, DeepSeek, and similar). The planner uses
+the coder path. neal owns
+the agentic loop (one model turn per request, with a neal-owned outer loop
+over the message history) and supplies its own tool set (`read_file`,
+`write_file`, `edit_file`, `list_dir`, `grep`, and `run`), so any endpoint
+whose model can call tools reliably can serve as the coder, and, through a
+read-only subset of the same tools, as the reviewer.
+
+The adapter is implemented on the AI SDK's OpenAI-compatible chat provider.
+Gateway behaviors learned from live failures are preserved through a
+neal-owned response interceptor: upstream errors embedded as an `error`
 object inside an HTTP 200 body keep their status-based retryability
 (OpenRouter wraps upstream 429s this way), and reasoning-model responses
 whose final text arrives in `message.reasoning` / `message.reasoning_content`
@@ -464,132 +454,40 @@ AI SDK's normalized shape (`inputTokens` / `outputTokens` / `totalTokens`
 plus detail fields), with the raw response usage object preserved under
 `usage.raw`.
 
-Role restrictions and behavior:
-
-- Structured-advisor/reviewer roles only. There is no coder or planner
-  support; selecting `openai-compatible` for those roles fails the capability
-  check with a clear error before any run starts.
-- No tool access of any kind (`read`, `write`, and `shell` are all declared
-  false). Neal inlines the review context — the full diff, plan document
-  content, review history, and run artifacts, with per-section truncation
-  caps — directly into reviewer prompts, and reviewer prompts render the
-  `no-read` review doctrine mode (see
-  [Review Doctrine Access Modes](#review-doctrine-access-modes)). The
-  tradeoff: an inline-context reviewer cannot independently run verification
-  commands or read beyond the inlined sections, so review quality depends on
-  the inlined context. For tool-calling models, the `generic-agentic`
-  reviewer path avoids that tradeoff; see
-  [Generic Agentic Writer](#generic-agentic-writer).
-- No session resume. The adapter never returns a resumable session handle, so
-  no reviewer session state is persisted for it.
-- No `effort` support. Any configured `agent.reviewer.effort` for this
-  provider is rejected with the standard effort config error.
-- Structured output uses Neal's `neal-json-block-v1` protocol and bounded
-  repair loop, not provider-specific `response_format` or strict JSON schema.
-- Requests are non-streaming Chat Completions; `neal.inactivity_timeout_ms`
-  acts as the whole-request timeout. Model quality, rate limits, and exact API
-  behavior vary by upstream provider.
-
-### Configuration
-
-Add a `providers.openai_compatible` block (repo `config.yml` overrides
-`~/.neal/config.yml`, matching normal config precedence) and point the
-reviewer role at the provider. A worked DeepSeek example:
-
-```yaml
-providers:
-  openai_compatible:
-    base_url: https://api.deepseek.com
-    api_key_env: DEEPSEEK_API_KEY
-    default_model: deepseek-chat
-
-agent:
-  coder:
-    provider: openai-codex
-    model: null
-  reviewer:
-    provider: openai-compatible
-    model: deepseek-chat
-```
-
-Settings resolve config-first with environment fallbacks:
-
-- `base_url`: `providers.openai_compatible.base_url`, else
-  `OPENAI_COMPATIBLE_BASE_URL`. Required.
-- `api_key_env`: `providers.openai_compatible.api_key_env`, else the default
-  `OPENAI_COMPATIBLE_API_KEY`. The API key value is read from that named
-  environment variable; Neal never stores the key itself.
-- model: the role-level `agent.reviewer.model` override, else
-  `providers.openai_compatible.default_model`, else `OPENAI_COMPATIBLE_MODEL`.
-  One of these is required.
-- `headers`: optional string-to-string map of extra HTTP headers (useful for
-  OpenRouter attribution headers).
-
-`neal setup` offers `openai-compatible` for the reviewer role only and prints
-guidance when the base URL, API key, or model is unresolved. `neal setup`
-detection reports which config keys or environment variables are missing
-without making network calls.
-
-### Live Smoke Check (optional)
-
-The default test suite never requires live credentials or network access. To
-verify a real endpoint end to end, set credentials and run `neal check` with
-the reviewer role configured for `openai-compatible` — the `provider-check`
-structured round exercises the adapter against the live endpoint:
-
-```sh
-OPENAI_COMPATIBLE_BASE_URL=https://api.deepseek.com \
-OPENAI_COMPATIBLE_API_KEY=... \
-OPENAI_COMPATIBLE_MODEL=deepseek-chat \
-pnpm start -- check
-```
-
-## Generic Agentic Writer
-
-The `generic-agentic` provider runs the coder role (and the inherited planner
-role) against any OpenAI-compatible Chat Completions endpoint with a strong
-tool-calling model (OpenRouter, vLLM, DeepSeek, and similar). Unlike the
-API-only `openai-compatible` reviewer adapter, this provider is a real writer:
-Neal owns the agentic loop (one model turn per request, with a Neal-owned
-outer loop over the message history) and supplies its own tool set —
-`read_file`, `write_file`, `edit_file`, `list_dir`, `grep`, and `run` — so any
-endpoint whose model can call tools reliably can serve as the coder, and,
-through a read-only subset of the same tools, as the reviewer.
-
-Because endpoint quality varies, qualify a generic-agentic model with
+Because endpoint quality varies, qualify an `openai-compatible` model with
 [`neal compat`](compat.md) before trusting it with real work: it drives the
 candidate through complete neal runs against trivial bundled fixtures and emits
 a binary PASS/FAIL per (model, role). `neal check` proves only connectivity and
-basic protocol; `neal compat` proves the full loop.
+basic protocol. `neal compat` proves the full loop.
 
 Role support and behavior:
 
-- Coder-first. The coder capability role is read, write, and shell capable;
-  the planner inherits the coder provider unless configured explicitly.
+- Coder-first. The coder capability role is read, write, and shell capable.
+  The planner inherits the coder provider unless configured explicitly.
 - Tool-capable reviewer. The structured-advisor role runs the same
-  Neal-owned loop over a read-only toolset — `read_file`, `list_dir`,
-  `grep`, and the read-only `git_diff` commit-range inspector — so a generic
+  neal-owned loop over a read-only toolset (`read_file`, `list_dir`,
+  `grep`, and the read-only `git_diff` commit-range inspector), so the
   reviewer inspects the repository directly under the `read-only` review
   doctrine mode (see
-  [Review Doctrine Access Modes](#review-doctrine-access-modes)) instead of
-  receiving Neal-inlined context. `git_diff` is a Neal-owned fixed-argv git
-  query (never a shell string) that gives the reviewer actual commit-range
-  visibility, including deletions and renames that head-state file reads
-  cannot reveal. After the read-tool loop completes with a zero-tool-call
-  turn, the structured payload is requested in a single dedicated
-  finalization turn that carries no tools. The same adapter also serves the
-  final-completion summary gate when `generic-agentic` is the coder.
+  [Review doctrine access modes](#review-doctrine-access-modes)). `git_diff`
+  is a neal-owned fixed-argv git query (never a shell string) that gives the
+  reviewer actual commit-range visibility, including deletions and renames
+  that head-state file reads cannot reveal. After the read-tool loop
+  completes with a zero-tool-call turn, the structured payload is requested
+  in a single dedicated finalization turn that carries no tools. The same
+  adapter also serves the final-completion summary gate when
+  `openai-compatible` is the coder.
 - No session resume (`supportsSessionResume: false` on both roles). The
   adapter never persists a provider session handle, so `neal resume` after an
   interruption or failure restarts the interrupted scope from scratch in a
   fresh session rather than resuming mid-conversation. Already-accepted
-  scopes stay committed; only the in-flight scope is redone. Top-level
+  scopes stay committed. Only the in-flight scope is redone. Top-level
   plan-refinement revision rounds likewise start a fresh planner session per
   round instead of resuming the planning conversation.
 - Step caps: each coder prompt's tool loop is bounded by the exported
-  `GENERIC_AGENTIC_MAX_STEPS` constant (currently `48` model turns per
-  prompt); structured-advisor/reviewer rounds use the smaller exported
-  `GENERIC_AGENTIC_ADVISOR_MAX_STEPS` constant (currently `24` — reviews are
+  `OPENAI_COMPATIBLE_MAX_STEPS` constant (currently `48` model turns per
+  prompt). Structured-advisor/reviewer rounds use the smaller exported
+  `OPENAI_COMPATIBLE_ADVISOR_MAX_STEPS` constant (currently `24`: reviews are
   bounded inspections, not implementations). Reaching either cap fails the
   attempt with a non-retryable `provider_failed` error naming the cap. There
   are no config knobs for the caps.
@@ -599,26 +497,26 @@ Role support and behavior:
   tool-turns-per-review is auditable from `events.ndjson` when qualifying a
   model for reviewer duty.
 - No `effort` support. Any configured `effort` for this provider is rejected
-  with the standard effort config error.
+  with the standard effort config error. See
+  [Reasoning effort overrides](#reasoning-effort-overrides) for why.
 - Structured output is SDK-native. After the tool loop's normal
   zero-tool-call completion turn, the adapter makes exactly one dedicated
   finalization turn (no tools) through the AI SDK's `Output.object`
   structured-output channel and validates the result against the protocol
   schema. There is no fenced-JSON text protocol on this provider and no
   second chance for a malformed payload: a finalization failure is a single
-  non-retryable error — kind `structured_output_missing` when the model
+  non-retryable error (kind `structured_output_missing` when the model
   produced no parseable object, or `structured_output_invalid` when the
-  object failed validation — with a truncated excerpt of the rejected text
+  object failed validation) with a truncated excerpt of the rejected text
   preserved under the `provider_error` event's `providerData.diagnostic`, so
   failed runs stay classifiable. Tool inputs are likewise strict: arguments
   must match the tool's schema as sent, with no coercion of stringified
   JSON. This failure taxonomy is the qualification signal for candidate
-  models — a model that cannot pass `neal check` on this provider is not
+  models: a model that cannot pass `neal check` on this provider is not
   pool-eligible.
 - Transient API failures (408/429/5xx, network errors, and empty
   HTTP-200 responses) are retried with bounded backoff and surfaced as
-  `api_retry` progress events, matching the `openai-compatible` adapter's
-  behavior.
+  `api_retry` progress events.
 
 Trust level is identical to the vendor writer providers: the `run` tool
 executes arbitrary shell commands in the scope working tree with no sandbox.
@@ -626,32 +524,39 @@ The path jail on file-tool arguments keeps `read_file`, `write_file`,
 `edit_file`, `list_dir`, and `grep` inside the repository (including through
 symlinks), but it does not contain what `run` can do. Apply the same
 disposable-checkout guidance as for the other writer providers.
-Structured-advisor rounds never receive `write_file`, `edit_file`, or `run`;
-the read-only toolset is jailed the same way.
-
-Choosing a reviewer adapter for generic endpoints: prefer `generic-agentic`
-when the endpoint's model calls tools reliably — the reviewer reads the
-actual repository and commit range with bounded, targeted tool calls instead
-of judging a truncation-capped inlined diff, and reviewer prompts stay small.
-Prefer `openai-compatible` for genuinely chat-only endpoints or models whose
-tool calling is unreliable; the inline-context path remains correct and fully
-supported.
+Structured-advisor rounds never receive `write_file`, `edit_file`, or `run`.
+The read-only toolset is jailed the same way.
 
 Model guidance: use a paid tool-calling slug for coder duty. Rate-limited
-`:free` pools are acceptable for reviewer-only use but are not suitable as
-coders. Model qualification runs and a tested-models table are future work;
-until that lands, treat models other than `qwen/qwen3-coder` (validated
-end-to-end as the coder) and `openai/gpt-oss-120b` (validated live as the
-read-only reviewer and as the inline-context reviewer) as unqualified and
-trial them on a disposable project first.
+`:free` pools are not suitable as coders, and they are usually too flaky for
+reviewer duty. Treat the dated [compatible-models.md](compatible-models.md)
+whitelist as the current evidence for `openai-compatible` model compatibility.
+It is a contract smoke test, not a skill ranking, so still trial unfamiliar
+models on a disposable project before using them on real work.
 
 ### Configuration
 
-Settings reuse the `providers.openai_compatible` block — there is no separate
-`providers.generic_agentic` config surface — with the same config-first,
-environment-fallback resolution documented in
-[OpenAI-Compatible Endpoints](#openai-compatible-endpoints). A worked
-OpenRouter example:
+Add a `providers.openai_compatible` block (repo `neal.yml` overrides
+`~/.neal/config.yml`, matching normal config precedence) and point one or
+more roles at the provider. A worked DeepSeek example:
+
+```yaml
+providers:
+  openai_compatible:
+    base_url: https://api.deepseek.com
+    api_key_env: DEEPSEEK_API_KEY
+    default_model: deepseek-chat
+
+agent:
+  coder:
+    provider: openai-codex
+    model: null
+  reviewer:
+    provider: openai-compatible
+    model: deepseek-chat
+```
+
+A worked OpenRouter example driving the coder through the provider:
 
 ```yaml
 providers:
@@ -662,31 +567,175 @@ providers:
 
 agent:
   coder:
-    provider: generic-agentic
+    provider: openai-compatible
     model: null
   reviewer:
     provider: anthropic-claude
     model: null
 ```
 
-The planner inherits the coder provider unless configured explicitly, so this
-config routes planning through `generic-agentic` too. Coder model precedence
-is `agent.coder.model`, else `providers.openai_compatible.default_model`,
-else `OPENAI_COMPATIBLE_MODEL`; one of these is required. Structured-advisor
-rounds additionally honor a Neal-internal round-level model override first,
-matching the `openai-compatible` adapter.
+The planner inherits the coder provider unless configured explicitly, so the
+OpenRouter config above routes planning through `openai-compatible` too.
+Structured-advisor rounds additionally honor a neal-internal round-level model
+override first.
+
+Settings resolve config-first with environment fallbacks:
+
+- `base_url`: `providers.openai_compatible.base_url`, else
+  `OPENAI_COMPATIBLE_BASE_URL`. Required.
+- `api_key_env`: `providers.openai_compatible.api_key_env`, else the default
+  `OPENAI_COMPATIBLE_API_KEY`. The API key value is read from that named
+  environment variable. neal never stores the key itself.
+- model: the role-level `agent.<role>.model` override, else
+  `providers.openai_compatible.default_model`, else `OPENAI_COMPATIBLE_MODEL`.
+  One of these is required.
+- `headers`: optional string-to-string map of extra HTTP headers (useful for
+  OpenRouter attribution headers).
+- `pricing`: an **optional override** for per-million-token rates. It is no
+  longer required to get a dollar cost (see "Cost pricing" below). Set it only
+  for models the vendored rate card does not key exactly, or to pin different
+  rates. All three rates are required when the block is present (a partial block
+  is a configuration error). Rates are in USD per one million tokens:
+
+  ```yaml
+  providers:
+    openai_compatible:
+      base_url: https://api.deepseek.com
+      api_key_env: DEEPSEEK_API_KEY
+      default_model: deepseek-chat
+      pricing:
+        input_per_million: 0.27
+        cached_input_per_million: 0.07
+        output_per_million: 1.10
+  ```
+
+#### Cost pricing
+
+neal resolves each run's dollar cost per provider/role bucket in this order:
+
+1. **Provider-reported cost.** The Claude adapter passes through the provider's
+   own `total_cost_usd`. It always wins when present.
+2. **Configured `pricing` override.** The
+   `providers.openai_compatible.pricing` block above.
+3. **Vendored published rate card.** The default rate source, keyed by model
+   slug. neal ships a trimmed copy of LiteLLM's
+   [`model_prices_and_context_window.json`](https://raw.githubusercontent.com/BerriAI/litellm/d9661222492a098555f40cb8b50014054bea5ab8/model_prices_and_context_window.json)
+   (retrieved 2026-07-18), so any adapter whose resolved model slug is exactly a
+   card key gets a rate-computed cost with **zero configuration**.
+4. **Tokens only.** If none of the above yields pricing, the run shows token
+   counts only. neal never invents dollars.
+
+Card lookup is **exact-match only**: the resolved model slug must be an exact
+card key. neal does not strip provider prefixes and does not fall back to the
+basename after a `/`, so a slash-qualified slug (for example a local or gateway
+slug like `local/gpt-5.5` or `azure/<deployment>`) is priced only if the card
+lists that exact string. Otherwise it stays tokens-only. LiteLLM lists many
+`vendor/model` keys directly, so provider-qualified slugs are still priced when
+the card carries that exact key. Set an explicit `pricing` override for slugs the
+card does not key exactly.
+
+**Base-tier only.** Card cost uses each model's published base /
+standard-context per-token rates only. neal does **not** apply long-context
+surcharges, tiered, batch, or priority rates. A turn whose prompt crosses a
+model's long-context threshold (for example GPT-5.6 Sol above 272K prompt tokens,
+which upstream prices at 2× input / 1.5× output) is priced at the base tier and
+is therefore an **underestimate** for that turn. Operators who need exact
+long-context cost can pin explicit rates via the `pricing` override.
+
+The `openai-codex` provider is now card-priced by its configured model (each
+role is priced by the model it actually ran). There is no codex pricing config
+block by design, so a codex role with no configured model (SDK default) stays
+tokens-only.
+
+The card is community-maintained list prices, and rate-computed cost is an
+estimate. Rate-computed cost (from either the vendored card or a configured
+override) is flagged with a footnote (`*`) in the retrospective's Provider Usage
+table. The note reads "Cost estimated from published or configured rates, not
+reported by the provider." That distinguishes it from cost a provider reports
+directly. Cached input is billed once, at the cached rate.
+
+`neal setup` offers `openai-compatible` for the planner, coder, and reviewer
+roles and prints guidance when the base URL, API key, or model is unresolved.
+`neal setup` detection reports which config keys or environment variables are
+missing without making network calls.
+
+### Live smoke check (optional)
+
+The default test suite never requires live credentials or network access. To
+verify a real endpoint end to end, set credentials and run `neal check` with
+the reviewer role configured for `openai-compatible`. The `provider-check`
+structured round exercises the adapter against the live endpoint:
+
+```sh
+OPENAI_COMPATIBLE_BASE_URL=https://api.deepseek.com \
+OPENAI_COMPATIBLE_API_KEY=... \
+OPENAI_COMPATIBLE_MODEL=deepseek-chat \
+pnpm start -- check
+```
+
+### Local endpoints (Ollama, llama.cpp, vLLM)
+
+A local server that speaks the OpenAI-compatible Chat Completions API (Ollama,
+llama.cpp's `server`, vLLM, and similar) is just another endpoint for this
+provider. It reuses the same `providers.openai_compatible` block documented
+above, with the same config-first, environment-fallback resolution rules from
+[Configuration](#configuration). Only the `base_url`, model slug, and auth
+variable change.
+
+```yaml
+providers:
+  openai_compatible:
+    base_url: http://localhost:11434/v1
+    api_key_env: OLLAMA_API_KEY # any non-empty placeholder for servers that ignore auth
+    default_model: qwen3-coder:30b
+
+agent:
+  coder:
+    provider: openai-codex
+    model: null
+  reviewer:
+    provider: openai-compatible
+    model: null
+```
 
-## Adding A Built-In Provider
+neal has no `api_key` config field: it resolves the key from the environment
+variable named by `api_key_env` (default `OPENAI_COMPATIBLE_API_KEY`), and the
+AI SDK requires that value to be non-empty even when the local server ignores
+auth. So export a non-empty placeholder to the variable you named
+(`export OLLAMA_API_KEY=ollama`) before starting a run. Use the fully qualified
+local slug your server reports (Ollama tags such as `qwen3-coder:30b`), not a
+bare family name.
+
+Qualify a local model with [`neal compat`](compat.md)
+(`neal compat --model <slug> --role all`) before trusting it with writer runs.
+`--model` forces the candidate onto `openai-compatible`. Note the reference
+caveat: `--model` defaults `--reference` to `openai-codex`, which needs a Codex
+login, so a purely-local operator should pass
+`--reference openai-compatible:<same-slug>` for a self-contained check, while
+being aware that self-reference is a weaker qualification partner (a candidate
+grading itself), so treat its PASS with more caution than a native reference
+(see [compatible-models.md](compatible-models.md)).
+
+Set realistic role expectations. Local models below the whitelist bar usually
+fail the **coder** role on structured output (`structured_output` dominates the
+coder-FAIL rows in [compatible-models.md](compatible-models.md)), so the config
+above is the realistic starting point: keep the coder on a native provider
+(`openai-codex` or `anthropic-claude`) and give the local `openai-compatible`
+endpoint reviewer-only duty. That split only works if the local model calls
+tools reliably: the reviewer path is tool-driven, so a chat-only model (no
+tool calling) is not supported in any role.
+
+## Adding a built-in provider
 
 To add another built-in provider:
 
 1. Implement a provider module under `src/neal/providers/`.
 2. Export a `NealProviderDefinition`.
 3. Register the definition in `src/neal/providers/registry.ts`.
-4. Map SDK sessions and resume handles to opaque Neal handles.
+4. Map SDK sessions and resume handles to opaque neal handles.
 5. Map SDK stream or message events to `ProviderRuntimeEvent` values.
 6. Normalize SDK errors to `NealProviderError`.
-7. Add focused tests for event mapping, capabilities, Neal structured control
+7. Add focused tests for event mapping, capabilities, neal structured control
    protocol behavior, session handles, and normalized errors.
 8. Document SDK prerequisites, environment assumptions, supported roles,
    capabilities, and limitations.
@@ -696,7 +745,7 @@ not need a real SDK. SDK adapter tests should stay focused on provider-specific
 event collection, structured-output parsing, retry behavior, and error
 normalization.
 
-## SDK Prerequisites
+## SDK prerequisites
 
 Provider documentation should state the SDK package, required credentials or
 login state, model assumptions, filesystem/tool permission assumptions, and any
@@ -707,18 +756,16 @@ Current built-in writer providers run with broad local permissions:
 - OpenAI Codex uses `approvalPolicy: never` and
   `sandboxMode: danger-full-access`.
 - Anthropic Claude uses `permissionMode: bypassPermissions`.
-- OpenAI-Compatible is the exception: it makes HTTP API calls only and has no
-  local filesystem or shell access.
-- Generic Agentic makes HTTP API calls for model turns but executes Neal-owned
-  tools locally; the coder role's `run` tool executes shell commands with no
-  sandbox, matching the vendor writers' trust level. Structured-advisor
-  rounds execute only the read-only toolset locally.
+- OpenAI-compatible makes HTTP API calls for model turns but executes
+  neal-owned tools locally. The coder role's `run` tool executes shell
+  commands with no sandbox, matching the vendor writers' trust level.
+  Structured-advisor rounds execute only the read-only toolset locally.
 
 Those settings are part of current writer-run behavior. Do not narrow or widen
 them as part of provider registration unless a separate product change requires
 it.
 
-## Review Boundary
+## Review boundary
 
 Public `neal review` uses a separate read-only findings loop:
 
@@ -733,16 +780,16 @@ writes isolated artifacts under `.neal/reviews/<review-id>/`.
 Two distinct read-only guarantees apply here, and they should not be conflated:
 
 - The provider-capability invariant (see
-  [The Read-Only Reviewer Invariant](#the-read-only-reviewer-invariant)):
+  [The read-only reviewer invariant](#the-read-only-reviewer-invariant)):
   every supported `structured-advisor` capability has `write: false` and
   `shell: false`, so a writer-run reviewer/structured-advisor round cannot
-  write or run shell by capability — this holds for both writer runs and
+  write or run shell by capability. This holds for both writer runs and
   `neal review`.
 - The `neal review` command's additional artifact-boundary guard: the command
   checks protected writer state and worktree changes after provider rounds and
   fails if anything outside its review artifacts changed. This post-round guard
   is owned by the `neal review` command flow, not by a provider capability, and
-  is specific to `neal review`; a writer run does not perform this artifact
+  is specific to `neal review`. A writer run does not perform this artifact
   diff.
 
 So the capability invariant guarantees reviewers never write or run shell in