@navels/neal 0.1.0 → 0.2.0

package/dist/neal/providers/telemetry.js

@@ -63,6 +63,8 @@ async function writeRunEvent(event, options) {
             await logger.event('provider.turn_completed', {
                 ...commonEventData(event),
                 ...(event.usage !== undefined ? { usage: event.usage } : {}),
+                ...(event.costUsd !== undefined ? { costUsd: event.costUsd } : {}),
+                ...(event.costSource !== undefined ? { costSource: event.costSource } : {}),
             });
             break;
         case 'tool_started':
@@ -121,6 +123,8 @@ async function writeRunEvent(event, options) {
             await logger.event('provider.usage_reported', {
                 ...commonEventData(event),
                 usage: event.usage,
+                ...(event.costUsd !== undefined ? { costUsd: event.costUsd } : {}),
+                ...(event.costSource !== undefined ? { costSource: event.costSource } : {}),
             });
             break;
         case 'provider_error':

package/dist/neal/retrospective.js

@@ -28,6 +28,26 @@ function getArchivedRetrospectivePath(state, kind) {
     const suffix = state.finalCommit ? `-${state.finalCommit}` : '';
     return join(state.runDir, `RETROSPECTIVE-final${suffix}.md`);
 }
+function getCurrentRunMetricsPath(runDir) {
+    return join(runDir, 'RUN_METRICS.json');
+}
+// Mirrors getArchivedRetrospectivePath's scope/kind/commit naming so the
+// machine-readable metrics archive lines up with the retrospective archive.
+function getArchivedRunMetricsPath(state, kind) {
+    const scopeLabel = getCurrentScopeLabel(state);
+    if (kind === 'scope_accepted') {
+        const suffix = state.finalCommit ? `-${state.finalCommit}` : '';
+        return join(state.runDir, `RUN_METRICS-scope-${scopeLabel}${suffix}.json`);
+    }
+    if (kind === 'blocked') {
+        return join(state.runDir, `RUN_METRICS-blocked-scope-${scopeLabel}.json`);
+    }
+    if (kind === 'failed') {
+        return join(state.runDir, `RUN_METRICS-failed-scope-${scopeLabel}.json`);
+    }
+    const suffix = state.finalCommit ? `-${state.finalCommit}` : '';
+    return join(state.runDir, `RUN_METRICS-final${suffix}.json`);
+}
 async function loadRunEvents(runDir) {
     try {
         const content = await readFile(getEventsPath(runDir), 'utf8');
@@ -306,7 +326,8 @@ async function renderRetrospective(state, kind) {
     const changedFiles = await summarizeChangedFiles(state);
     const verificationSummary = summarizeVerification(scopeEvents);
     const metricsEvents = kind === 'done' ? events : scopeEvents;
-    const runMetricsSummary = renderRunMetricsMarkdown(summarizeRunMetrics(metricsEvents));
+    const metrics = summarizeRunMetrics(metricsEvents);
+    const runMetricsSummary = renderRunMetricsMarkdown(metrics);
     const assessment = buildAssessment(state, scopeEvents);
     const narrativeRetrospective = buildNarrativeRetrospective({
         state,
@@ -320,7 +341,7 @@ async function renderRetrospective(state, kind) {
     const derivedPlan = getDerivedPlanView(state);
     const showDerivedPlanContext = Boolean(derivedPlan);
     const parentScopeLabel = derivedPlan?.executing ? getParentScopeLabel(state) : null;
-    return [
+    const content = [
         `# Neal Retrospective`,
         '',
         `## Outcome`,
@@ -377,15 +398,23 @@ async function renderRetrospective(state, kind) {
         ...renderInteractiveBlockedRecoveryHistoryLines(state.interactiveBlockedRecoveryHistory),
         '',
     ].join('\n');
+    return { content, metrics };
 }
 async function writeRetrospectiveFile(path, content) {
     await writeTextAtomic(path, content);
 }
+async function writeRunMetricsFile(path, metrics) {
+    await writeTextAtomic(path, `${JSON.stringify(metrics, null, 2)}\n`);
+}
 export async function writeCheckpointRetrospective(state, kind) {
-    const content = await renderRetrospective(state, kind);
+    const { content, metrics } = await renderRetrospective(state, kind);
     const currentPath = getCurrentRetrospectivePath(state.runDir);
     const archivedPath = getArchivedRetrospectivePath(state, kind);
     await writeRetrospectiveFile(currentPath, content);
     await writeRetrospectiveFile(archivedPath, content);
-    return { currentPath, archivedPath };
+    const currentMetricsPath = getCurrentRunMetricsPath(state.runDir);
+    const archivedMetricsPath = getArchivedRunMetricsPath(state, kind);
+    await writeRunMetricsFile(currentMetricsPath, metrics);
+    await writeRunMetricsFile(archivedMetricsPath, metrics);
+    return { currentPath, archivedPath, currentMetricsPath, archivedMetricsPath };
 }

package/dist/neal/run-metrics.js

@@ -48,6 +48,21 @@ function addUsage(target, value) {
 function hasUsage(usage) {
     return Object.values(usage).some((value) => value > 0);
 }
+// Accumulate cost from one counted event into the provider bucket. Presence is
+// tracked separately from value: costUsd stays null until an event carries a
+// numeric costUsd, then it holds the running sum. A single provider/role bucket
+// has one source; if both appear, 'provider' wins.
+function accumulateCost(bucket, data) {
+    const raw = data.costUsd;
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) {
+        return;
+    }
+    bucket.costUsd = (bucket.costUsd ?? 0) + raw;
+    const source = data.costSource;
+    if (source === 'provider' || source === 'rate') {
+        bucket.costSource = bucket.costSource === 'provider' || source === 'provider' ? 'provider' : 'rate';
+    }
+}
 function cloneEmptyUsage() {
     return { ...EMPTY_USAGE };
 }
@@ -210,10 +225,13 @@ export function summarizeRunMetrics(events) {
                 label: identity.label,
                 turns: 0,
                 usage: cloneEmptyUsage(),
+                costUsd: null,
+                costSource: null,
             };
             existing.turns += 1;
             if (!hasDedicatedUsageEvents) {
                 addUsage(existing.usage, data.usage);
+                accumulateCost(existing, data);
             }
             providers.set(identity.key, existing);
         }
@@ -226,8 +244,11 @@ export function summarizeRunMetrics(events) {
                 label: identity.label,
                 turns: 0,
                 usage: cloneEmptyUsage(),
+                costUsd: null,
+                costSource: null,
             };
             addUsage(existing.usage, data.usage);
+            accumulateCost(existing, data);
             providers.set(identity.key, existing);
         }
         else if (event.type === 'provider.command_completed') {
@@ -276,6 +297,25 @@ export function summarizeRunMetrics(events) {
         phase.durationMs = start !== null && end !== null && end >= start ? end - start : null;
     }
     const publicPhases = phases.map(({ startIndex: _startIndex, endIndex: _endIndex, ...phase }) => phase);
+    const providerSummaries = [...providers.values()].sort((left, right) => {
+        const turns = right.turns - left.turns;
+        if (turns !== 0) {
+            return turns;
+        }
+        return usageSortValue(right) - usageSortValue(left);
+    });
+    // Coverage is computed only over usage-bearing buckets so a partial subtotal
+    // never masquerades as a complete run total.
+    const usageBearing = providerSummaries.filter((provider) => hasUsage(provider.usage));
+    const pricedUsageBearing = usageBearing.filter((provider) => provider.costUsd !== null);
+    const costCoverage = pricedUsageBearing.length === 0
+        ? 'none'
+        : pricedUsageBearing.length === usageBearing.length
+            ? 'complete'
+            : 'partial';
+    const totalCostUsd = costCoverage === 'none'
+        ? null
+        : providerSummaries.reduce((sum, provider) => (provider.costUsd !== null ? sum + provider.costUsd : sum), 0);
     return {
         observedStartedAt: firstTimestamp,
         observedCompletedAt: lastTimestamp,
@@ -288,13 +328,9 @@ export function summarizeRunMetrics(events) {
         toolEventCount,
         fileChangeEventCount,
         phases: publicPhases,
-        providers: [...providers.values()].sort((left, right) => {
-            const turns = right.turns - left.turns;
-            if (turns !== 0) {
-                return turns;
-            }
-            return usageSortValue(right) - usageSortValue(left);
-        }),
+        providers: providerSummaries,
+        totalCostUsd,
+        costCoverage,
     };
 }
 function formatDuration(value) {
@@ -327,6 +363,31 @@ function formatProviderName(summary) {
 function usageCell(value) {
     return value > 0 ? formatNumber(value) : '-';
 }
+function formatCostAmount(value) {
+    return `$${value.toFixed(4)}`;
+}
+// Cost cell for the Provider Usage table: '-' when the bucket reported no cost,
+// otherwise the fixed-precision USD amount with a footnote marker on
+// rate-computed cells.
+function formatCost(value, source) {
+    if (value === null) {
+        return '-';
+    }
+    return source === 'rate' ? `${formatCostAmount(value)}*` : formatCostAmount(value);
+}
+// The top-summary cost line, labeled by coverage so a partial subtotal is never
+// presented as a complete run total.
+function formatEstimatedCostLine(metrics) {
+    if (metrics.costCoverage === 'none' || metrics.totalCostUsd === null) {
+        return '- Estimated cost: unknown';
+    }
+    if (metrics.costCoverage === 'partial') {
+        const usageBearing = metrics.providers.filter((provider) => hasUsage(provider.usage));
+        const priced = usageBearing.filter((provider) => provider.costUsd !== null);
+        return `- Estimated cost (partial — ${priced.length} of ${usageBearing.length} priced providers): ${formatCostAmount(metrics.totalCostUsd)}`;
+    }
+    return `- Estimated cost: ${formatCostAmount(metrics.totalCostUsd)}`;
+}
 export function renderRunMetricsMarkdown(metrics) {
     const commandSummary = metrics.resolvedNonZeroCommandCount > 0
         ? `- Commands: ${metrics.commandCount} total, ${metrics.unresolvedNonZeroCommandCount} unresolved non-zero or failed, ${metrics.resolvedNonZeroCommandCount} resolved by later passing rerun`
@@ -337,16 +398,20 @@ export function renderRunMetricsMarkdown(metrics) {
         commandSummary,
         `- Tool events: ${metrics.toolEventCount}`,
         `- File change events: ${metrics.fileChangeEventCount}`,
+        formatEstimatedCostLine(metrics),
     ];
     if (metrics.phases.length > 0) {
         lines.push('', '### Phase Timing', '', '| Phase | Duration | Provider turns | Commands | Non-zero commands | Tool events | File changes |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: |', ...metrics.phases.map((phase) => `| ${formatPhaseName(phase.phase)} | ${formatPhaseDuration(phase)} | ${phase.providerTurns} | ${phase.commandCount} | ${phase.nonZeroCommandCount} | ${phase.toolEventCount} | ${phase.fileChangeEventCount} |`));
     }
     const providersWithUsage = metrics.providers.filter((provider) => provider.turns > 0 || hasUsage(provider.usage));
     if (providersWithUsage.length > 0) {
-        lines.push('', '### Provider Usage', '', '| Provider / role | Turns | Input | Cached input | Cache created | Cache read | Output | Reasoning output | Total |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |', ...providersWithUsage.map((provider) => {
+        lines.push('', '### Provider Usage', '', '| Provider / role | Turns | Input | Cached input | Cache created | Cache read | Output | Reasoning output | Total | Cost |', '| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |', ...providersWithUsage.map((provider) => {
             const usage = provider.usage;
-            return `| ${formatProviderName(provider)} | ${provider.turns} | ${usageCell(usage.inputTokens)} | ${usageCell(usage.cachedInputTokens)} | ${usageCell(usage.cacheCreationInputTokens)} | ${usageCell(usage.cacheReadInputTokens)} | ${usageCell(usage.outputTokens)} | ${usageCell(usage.reasoningOutputTokens)} | ${usageCell(usage.totalTokens)} |`;
+            return `| ${formatProviderName(provider)} | ${provider.turns} | ${usageCell(usage.inputTokens)} | ${usageCell(usage.cachedInputTokens)} | ${usageCell(usage.cacheCreationInputTokens)} | ${usageCell(usage.cacheReadInputTokens)} | ${usageCell(usage.outputTokens)} | ${usageCell(usage.reasoningOutputTokens)} | ${usageCell(usage.totalTokens)} | ${formatCost(provider.costUsd, provider.costSource)} |`;
         }));
+        if (providersWithUsage.some((provider) => provider.costUsd !== null && provider.costSource === 'rate')) {
+            lines.push('', '\\* Cost estimated from published or configured rates, not reported by the provider.');
+        }
     }
     else {
         lines.push('', '### Provider Usage', '', '- No provider usage events recorded.');

package/docs/compatible-models.md

@@ -24,6 +24,17 @@
 
 Sorted cheapest first ($/Mtok in·out, from the live OpenRouter catalog).
 
+> **Drift observed (2026-07-14):** `google/gemma-4-26b-a4b-it` — an all-roles PASS on
+> 2026-06-18 — failed the coder role 3/3 with `structured_output` in the CI smoke
+> (self-reference configuration). Slugs rot as providers re-route or re-quantize;
+> treat its row below as stale until re-qualified against the codex reference.
+>
+> **Self-reference caveat (2026-07-14):** `inclusionai/ling-2.6-1t` repeatedly failed the
+> reviewer broken-diff cell (2/3 attempts) in the CI smoke when serving as **its own
+> partner**. Its codex-referenced row below stands — this is a partner-duty weakness,
+> the same class the reference investigation documents. The smoke pin is
+> `minimax/minimax-m2.5`, which held up under self-reference.
+
 | Model | Coder | Reviewer | Planner | $/Mtok | ctx |
 |---|---|---|---|---|---|
 | `google/gemma-4-26b-a4b-it` | 3/3 | 6/6 | 1/1 | 0.06·0.33 | 262k |

package/docs/issue-pipeline.md

@@ -0,0 +1,124 @@
+# GitHub Issue Pipeline
+
+Assign a GitHub issue to neal and get a reviewed pull request back. A maintainer
+applies a trigger label to an issue; a GitHub Actions runner turns the issue
+into a neal plan, runs neal's planner/coder/reviewer loop to completion, and
+opens a pull request assigned to a human — or reports back on the issue if neal
+blocks. Humans own merge; the pipeline never pushes to a protected branch.
+
+This is a self-hosting use of neal itself: neal already *is* the middle of the
+loop (cross-model review, deterministic gating, bounded recovery), so the
+pipeline is a thin trigger plus a thin publish around `neal run`.
+
+## What it does
+
+```
+maintainer applies the trigger label to an issue
+        │  (gate: the labeler must have write access — the issue author is irrelevant)
+        ▼
+issue title + body ──▶ seed .neal/PLAN.md ──▶ neal run --unattended
+        │                                        (Opus 4.8 writes, sol reviews each diff)
+        ├─ exit 0 ──▶ push neal/issue-<n>, open a PR, assign the maintainer
+        ├─ exit 2 ──▶ comment the blocker on the issue, keep the branch
+        └─ exit 3 ──▶ comment the failure on the issue, open no PR
+```
+
+The plan is seeded inside `.neal/` — wrapper-owned, gitignored territory — so
+it can never collide with a tracked file or appear in review diffs, and it is
+never committed. The refined plan travels with the outcome instead: the PR
+body (or the blocked/failed issue comment) embeds it in a collapsed details
+block, which outlives the 3-day `.neal/` artifact retention.
+
+The outcome also carries a cost ledger — per-provider turns, tokens, and
+dollars aggregated from the run's `RUN_METRICS-final*.json` files. Claude
+cost is provider-reported; reviewer cost is rate-computed from neal's
+vendored published rate card (see `docs/providers.md`) and marked as such.
+
+## Running an issue locally
+
+`scripts/neal-issue-local.sh <issue-number> [plan-doc]` is the pipeline's
+local twin for subscription billing: the coder rides the Claude CLI login and
+the reviewer the codex CLI login (per `~/.neal/config.yml`) instead of the
+API keys CI uses. It shares the plan seed and PR-body construction with
+`pipeline/run.sh` through `pipeline/lib.sh`, so a local run produces the same
+branch name, the same PR format, and the same embedded plan and cost ledger.
+The optional second argument substitutes a pre-authored plan (for example a
+`multi_scope` plan spanning several issues) for the seeded `one_shot` one.
+The script unsets `OPENAI_API_KEY`/`ANTHROPIC_API_KEY` for the run so a stray
+exported key cannot silently switch billing from subscription to API.
+
+Every run executes in its own git worktree under `<repo>-worktrees/issue-<n>`,
+branched from `origin/main`. Runs on different issues can proceed in parallel
+(git enforces one worktree per branch), and the main checkout stays free for
+your own work throughout. On success the worktree is removed after the push —
+the branch lives on the PR. On blocked/failed outcomes the worktree is kept:
+it is the resume state (`cd` in and `neal resume`). The practical concurrency
+cap is your subscriptions, not git: parallel runs share your Claude and
+ChatGPT rate limits.
+
+- **Coder:** Claude Opus 4.8 (`anthropic-claude` adapter, `ANTHROPIC_API_KEY`).
+- **Reviewer:** GPT-5.6-sol via the `openai-compatible` adapter pointed at the
+  OpenAI API (`OPENAI_API_KEY`). The reviewer judges neal-inlined diff/context;
+  it has no repository tools, which keeps the runner setup to two env vars and
+  no extra CLI.
+
+## Setup
+
+One-time, by a maintainer. The workflow no-ops safely until this is done.
+
+1. **Secrets** (repo → Settings → Secrets → Actions, on the `neal-pipeline`
+   environment): `ANTHROPIC_API_KEY` and `OPENAI_API_KEY`. Use short-lived,
+   minimally-scoped keys and rotate them (see Security below).
+2. **Environment**: create a `neal-pipeline` environment (Settings →
+   Environments). Optionally add required reviewers so each run needs a manual
+   click before the secrets are exposed — recommended for a public repo.
+3. **Reviewer model**: set the repo variable `NEAL_REVIEWER_MODEL` to the sol
+   model slug your OpenAI key serves. Before the first run, qualify it:
+   `neal compat --model <slug> --role reviewer --reference anthropic-claude`
+   (locally, with the same key). If sol is not reachable over the OpenAI
+   Chat Completions API, point `NEAL_REVIEWER_BASE_URL`/`NEAL_REVIEWER_MODEL` at
+   an endpoint that serves it, or switch the reviewer to the `openai-codex`
+   adapter in `pipeline/config.yml`.
+4. **Trigger label**: create a label (default `neal:go`; override with the repo
+   variable `NEAL_TRIGGER_LABEL`). Optionally set `NEAL_READY_LABEL` (e.g.
+   `ready-for-human`) to tag the PRs neal opens.
+5. **Branch protection**: protect `main` (require PR + review). The pipeline can
+   push `neal/issue-*` branches and open PRs, but must never be able to merge or
+   push to `main`.
+
+## Security model
+
+This runs on a public repository, so the trust boundary is "arbitrary internet
+text becomes instructions to an agent with push access." The controls:
+
+- **Maintainer-gated trigger.** The gate checks the *labeler's* repo permission
+  (`write`/`maintain`/`admin`), not the issue author. An untrusted issue cannot
+  start a run — only a maintainer applying the label can.
+- **Untrusted issue input.** The issue title/body are passed as environment
+  variables (never interpolated into a shell command) and written to the seed
+  plan with `printf '%s'`, so they cannot inject shell commands. neal then
+  treats the seed as plan input, refined through the planner/reviewer loop.
+- **Least privilege.** The workflow token can push `neal/issue-*` branches, open
+  PRs, and comment — nothing else. Branch protection keeps the human merge gate.
+- **Boundaries in the plan.** The seed forbids edits to `.github/**` /
+  `pipeline/**` and forbids reading or printing secrets — defense-in-depth on
+  top of the token scope.
+- **Secret exposure caveat.** The coder runs with shell in the runner, where
+  `ANTHROPIC_API_KEY` and `OPENAI_API_KEY` live in the environment. A
+  prompt-injected coder could try to exfiltrate them; the maintainer gate is
+  what makes that acceptable (only a maintainer's labeled issue ever runs). Use
+  short-lived, minimally-scoped keys, the `neal-pipeline` environment's approval
+  gate, and rotate on any suspicion.
+
+## v1 limitations
+
+- **Seed shape is `one_shot`.** Best for well-scoped issues ("fix X", "add Y").
+  For large multi-part work neal's coder will split the scope into a sub-plan;
+  if it can't be done in scope, neal blocks and comments asking for a smaller
+  issue. Write issues with a clear, bounded objective for best results.
+- **Reviewer reads inlined context, not the repo.** The `openai-compatible`
+  reviewer judges the diff neal inlines, not the working tree. Switch to an
+  `openai-codex` reviewer (OS-sandboxed, repo-reading) once sol is confirmed on
+  that adapter's API path, if repo-reading review is wanted.
+- **No comment-driven iteration yet.** On a blocked run you re-apply the label to
+  retry; a maintainer-comment → `neal resume --message` loop is a v2 addition.

package/docs/maintenance.md

@@ -4,37 +4,48 @@ neal's behavior is defined in large part by the agent SDKs it drives, so
 dependency updates are a first-class concern, not routine hygiene. This document
 is the policy.
 
-## Two dependency tiers
+## Three dependency tiers
 
 | Tier | Packages | Pinning | Update posture |
 | --- | --- | --- | --- |
-| **Behavior-defining** | `@openai/codex-sdk`, `@anthropic-ai/claude-agent-sdk`, `@anthropic-ai/sdk`, `ai`, `@ai-sdk/openai-compatible`, `zod` | **exact** (enforced by `scripts/validate-release.mjs`) | **deliberate** — qualify before adopting; never auto-merge |
+| **Native SDKs** | `@openai/codex-sdk`, `@anthropic-ai/claude-agent-sdk` | **exact** (enforced by `scripts/validate-release.mjs`) | **deliberate** — behaviorally qualified on a subscription-authenticated machine via `scripts/qualify-sdk.sh`; never auto-merge |
+| **AI-SDK tier** | `ai`, `@ai-sdk/openai-compatible`, `zod` | **exact** (enforced by `scripts/validate-release.mjs`) | minor/patch **auto-merge** once CI **and the live smoke** are green (3-day soak); majors stay manual |
 | **Utility** | `dotenv`, `yaml`, `@types/node`, `tsx`, `typescript` | caret OK | routine — auto-merge on green CI after a soak period |
 
 The asymmetry exists because an agentic-SDK bump can change tool-calling,
 structured output, or sandbox behavior — i.e. break neal's loop **without**
-breaking compilation. Utility deps cannot.
+breaking compilation. Utility deps cannot. The native/AI-SDK split exists
+because CI can behaviorally exercise the AI-SDK tier (the smoke drives it
+live through `generic-agentic`) but not the native adapters, whose auth is
+subscription-based and lives only on a maintainer's machine.
 
 ## The update flow
 
-1. **Detect.** [Renovate](../renovate.json) opens PRs weekly: utility deps grouped
-   (auto-merge), agentic SDKs one-per-PR (labelled `agentic-sdk` /
-   `needs-qualification`, auto-merge **off**, pinned exact).
+1. **Detect.** [Renovate](../renovate.json) opens PRs weekly: utility deps
+   grouped, AI-SDK and native SDKs one-per-PR, pinned exact, labelled
+   `agentic-sdk` (native and AI-SDK majors additionally `needs-qualification`).
 2. **Verify (automatic).** CI (`.github/workflows/ci.yml`) runs typecheck + unit
-   tests + package verification — catches **API-shape / contract** breaks.
-3. **Verify (behavioral).**
-   - The **AI-SDK tier** (`ai`, `@ai-sdk/openai-compatible`, `zod`) is exercised
-     automatically by the live smoke (`.github/workflows/smoke.yml`): a real
-     `neal compat` run against a cheap OpenRouter model through `generic-agentic`.
-   - The **native tier** (`@openai/codex-sdk`, `@anthropic-ai/*`) cannot be smoked
-     in CI (subscription auth isn't available there), so qualify it **locally**
-     before merging:
-     ```
-     neal compat --model <a-known-good-slug> --role all
-     ```
-     and ideally a one-fixture end-to-end run.
+   tests + package verification — catches **API-shape / contract** breaks. The
+   live smoke (`.github/workflows/smoke.yml`) runs on every package.json /
+   lockfile PR: a real `neal compat` run against a cheap OpenRouter model
+   through `generic-agentic`, catching **behavioral** breaks in the AI-SDK
+   tier. AI-SDK minor/patch PRs auto-merge when both are green.
+   **The smoke requires the `OPENROUTER_API_KEY` repo secret** — without it
+   the smoke skips (green) and the AI-SDK auto-merge gate is compile-only.
+3. **Verify (behavioral, native tier).** `@openai/codex-sdk` and
+   `@anthropic-ai/claude-agent-sdk` cannot be smoked in CI, so qualify them
+   from any checkout with authenticated Claude/Codex CLIs:
+   ```
+   scripts/qualify-sdk.sh <pr-number>
+   ```
+   It runs the full suite plus a live `neal compat --role all` pass-through on
+   the bumped adapter (in a throwaway worktree, with roles and models pinned
+   explicitly so nothing leaks from `~/.neal/config.yml`), posts the compat
+   matrix to the PR, and approves on PASS (`--merge` also squash-merges).
 4. **Adopt.** Merge, bump neal's version, add a CHANGELOG entry noting the bump +
-   any behavior change, and cut a release via the existing workflow.
+   any behavior change, and cut a release via the existing workflow. Urgent
+   bumps (a fix neal needs immediately) may skip the Renovate soak with a
+   manual PR — qualify them the same way.
 
 ## Versioning
 

package/docs/providers.md

@@ -524,6 +524,69 @@ Settings resolve config-first with environment fallbacks:
   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 (shared by the
+   `openai-compatible` and `generic-agentic` providers).
+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/f1f33f560f7a39e86f7a2e5b26b9fa032f9dcaba/model_prices_and_context_window.json)
+   (retrieved 2026-07-15), 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 — "Cost estimated from published or configured rates, not reported by the
+provider." — to distinguish it from cost a provider reports directly. Cached
+input is billed once, at the cached rate.
 
 `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`
@@ -676,6 +739,60 @@ 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.
 
+### 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 (there is still no separate generic-agentic config surface), with the
+same config-first, environment-fallback resolution rules from
+[OpenAI-Compatible Endpoints](#openai-compatible-endpoints); 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: generic-agentic
+    model: null
+```
+
+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 `generic-agentic`. Note the reference
+caveat: `--model` defaults `--reference` to `openai-codex`, which needs a Codex
+login, so a purely-local operator should pass
+`--reference generic-agentic:<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 `generic-agentic`
+endpoint reviewer-only duty. That split only works if the local model calls
+tools reliably; if it is chat-only (no tool calling), use `openai-compatible`
+instead of `generic-agentic`, per the "Choosing a reviewer adapter for generic
+endpoints" guidance above.
+
 ## Adding A Built-In Provider
 
 To add another built-in provider:

package/docs/release.md

@@ -92,38 +92,42 @@ node scripts/verify-package.mjs
 ```
 
 Review the dry-run result before any real publish. Run `Publish` again with
-`dry_run: false` only when a first-publish or later release-preparation plan has
-explicitly authorized the real publish.
+`dry_run: false` only when a release-preparation plan has explicitly authorized
+the real publish.
 
-## First-Publish Boundary
+The real-publish path is **staged**: the workflow runs `npm stage publish`,
+which places the version in a staged, not-publicly-available state. A
+maintainer then reviews and approves it with 2FA — `npm stage list`,
+`npm stage view <stage-id>` / `npm stage download <stage-id>`, and
+`npm stage approve <stage-id>` (or the npmjs.com UI). Nothing reaches `latest`
+without that human approval, so a compromised workflow cannot ship directly.
 
-`@navels/neal` is not yet published to the npm registry. Local validation and
-the workflow run dry-run release checks, including `npm publish --dry-run
---access public`. A real public publish (`npm publish --access public`) happens
-only on the `dry_run: false` path, under the configured npm trusted publishing
-and an explicit authorization from a first-publish or later release-preparation
-plan.
+## First-Publish History
+
+`0.1.0` was published manually on 2026-07-12 with an interactive 2FA publish
+from a maintainer terminal: npm trusted publishing cannot be configured for a
+package that has never been published, so the first publish had to
+authenticate directly. Every release after `0.1.0` goes through the `Publish`
+workflow and the staged flow above.
 
 ## Trusted Publishing Setup
 
 The publish workflow relies on trusted publishing/OIDC and intentionally has no
 npm-token fallback. It grants `id-token: write` for OIDC, keeps repository
-contents read-only, uses the `npm-publish` GitHub environment, and publishes
-with `npm publish --access public` only on the real-publish path.
-
-Use this npm CLI setup command as the trusted publisher reference:
-
-```sh
-npm install -g npm@^11.10.0
-npm trust github @navels/neal --repo navels/neal --file publish.yml --env npm-publish --allow-publish
-```
-
-Current first-publish limitation: `@navels/neal` is not currently published, and
-the `npm trust github` command may be blocked until the package already exists
-on the npm registry. The npm trusted publisher configuration must match the
-repository workflow: package `@navels/neal`, owner/repo `navels/neal`, workflow
-filename `publish.yml`, environment `npm-publish`, and allowed action
-`npm publish`.
+contents read-only, uses the `npm-publish` GitHub environment, and runs
+`npm stage publish` only on the real-publish path (staged publishing requires
+npm >= 11.15.0; the workflow upgrades npm accordingly).
+
+The npm-side configuration for `@navels/neal`:
+
+- Publishing access: **Require two-factor authentication and disallow tokens**.
+  This blocks every traditional token permanently; trusted publishers are
+  unaffected because they use OIDC, and staged approvals always require a
+  maintainer's 2FA.
+- Trusted publisher: owner/repo `navels/neal`, workflow filename
+  `publish.yml`, environment `npm-publish`, allowed action **`npm stage
+  publish` only** (stage-only; plain `npm publish` is deliberately not
+  granted).
 
 ## Release Boundaries