sphinx-understand 0.1.0 → 0.1.1

package/docs/configuration.md

@@ -0,0 +1,241 @@
+# Configuration, models, and cost
+
+This page is the reference for reviewer models, usage limits, repository policy, and file exclusions. For the first-run path, see the [README](../README.md).
+
+- [Settings locations](#settings-locations)
+- [Reviewer models](#reviewer-models)
+- [Routing and question counts](#routing-and-question-counts)
+- [Model calls, tokens, and limits](#model-calls-tokens-and-limits)
+- [Repository policy](#repository-policy)
+- [Project context](#project-context)
+- [Files Sphinx never reads](#files-sphinx-never-reads)
+- [Background preparation](#background-preparation)
+
+## Settings locations
+
+| What | Where |
+| --- | --- |
+| Machine-wide settings | `~/.config/sphinx/config.json` |
+| OpenRouter key and OpenAI-compatible endpoint | `~/.config/sphinx/credentials.json` (mode `0600`) |
+| Machine-wide ignore patterns | `~/.config/sphinx/ignore` |
+| Skip and yolo log | `~/.config/sphinx/overrides.jsonl` |
+| Repository policy | `.sphinxconfig` (legacy `.sphinx.json` is read when `.sphinxconfig` is absent) |
+| Repository exclusions | `.sphinxignore` |
+| Project context | `.sphinxcontext.md` |
+
+`SPHINX_HOME` relocates all machine-wide settings, credentials, and assessment state. `sphinx config` shows effective settings and paths. A complete global example using the paid Haiku preset is in [examples/config.json](../examples/config.json).
+
+Model routes, credentials, and usage limits are machine-wide only. A repository cannot redirect review to another provider, supply credentials, or raise your limits.
+
+## Reviewer models
+
+Sphinx picks one of three saved routes (small, medium, large) for each change. Presets fill all three; you can change them at any time without reinstalling:
+
+```sh
+sphinx config --preset claude-economy
+sphinx config --preset openrouter-value --allow-paid
+sphinx config --small claude:haiku --medium claude:haiku --large claude:sonnet
+```
+
+| Preset | Small and medium | Large | Usage source |
+| --- | --- | --- | --- |
+| `codex-economy` | `codex:gpt-6-luna` | `codex:gpt-6-luna` | Your Codex CLI account |
+| `claude-economy` | `claude:haiku` | `claude:haiku` | Your Claude CLI account |
+| `openrouter-value` (experimental) | `openrouter:anthropic/claude-haiku-5.5` | `openrouter:anthropic/claude-haiku-5.5` | Paid OpenRouter credits |
+| `openrouter-deepseek` (experimental) | `openrouter:deepseek/deepseek-v3.2` | `openrouter:deepseek/deepseek-v3.2` | Paid OpenRouter credits |
+| `openrouter-free` | `openrouter:openrouter/free` | `openrouter:openrouter/free` | OpenRouter free availability and limits |
+
+Unattended installation needs an explicit preset or route; Sphinx does not silently choose a free model:
+
+```sh
+sphinx install --yes --preset codex-economy
+sphinx install --yes --preset claude-economy
+sphinx install --yes --preset openrouter-value --allow-paid
+```
+
+Reinstalling keeps saved routes unless you choose a replacement. Updating Sphinx does not migrate saved routes. Changing a route invalidates prepared questions and completion records made under the previous route.
+
+### Codex and Claude routes
+
+These use your signed-in Codex or Claude CLI and consume that account's allowance. You need a recent CLI with access to the selected model; see [Codex models](https://learn.chatgpt.com/docs/models) and [Claude model configuration](https://code.claude.com/docs/en/model-config). The economy presets keep the same economical model for all tiers; investigation effort and question count still scale with change size. The Claude `haiku` alias follows the available Haiku model. Neither preset upgrades to a more expensive model.
+
+**These routes bill your signed-in plan by default.** Sphinx removes `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `CODEX_API_KEY`, and similar variables from the reviewer CLI's environment, so a key in your shell cannot silently switch reviews to API credits. If the CLI is not signed in with a Claude or ChatGPT plan, the check stops with instructions. To let the CLIs use API keys instead, run `sphinx config --cli-billing api`.
+
+Each call is a fresh, isolated CLI invocation used as a model transport underneath the embedded [Pi SDK](https://pi.dev/docs/latest/sdk) reviewer. It does not reuse your coding conversation. See [architecture](architecture.md#independent-investigation-and-compaction).
+
+Pi, Cursor, and OpenCode integrations present checkpoints but do not supply a reviewer model. Their users pick a Codex/Claude CLI route, OpenRouter, or an OpenAI-compatible endpoint.
+
+### OpenRouter routes
+
+**Every OpenRouter route requires an API key, including free models.** The installer accepts an existing `OPENROUTER_API_KEY` or prompts for one with hidden input; `sphinx auth` replaces it later. Create a key in [OpenRouter's key settings](https://openrouter.ai/settings/keys). The key is stored in a user-only local file, not an OS keychain, and never in project configuration.
+
+Filtered evidence goes to OpenRouter and its selected upstream provider, billed separately from your coding-agent plan. Paid routes need OpenRouter credits.
+
+- **Paid consent.** Guided setup labels paid choices. Noninteractive commands need `--allow-paid` or an existing `allowPaid: true` setting. Free routes send zero-price provider limits even when another route permits paid models. There are no automatic paid fallbacks.
+- **Free router.** `openrouter-free` is best-effort. Its model selection, rate limits, and tool support can interrupt a check; see [OpenRouter limits](https://openrouter.ai/docs/api_reference/limits). Sphinx does not switch providers or upgrade models after a failure.
+- **Endpoint compatibility.** Requests need endpoint support for tools and output parameters. Capability metadata is a compatibility check, not a guarantee; unusable output leaves the check pending. See OpenRouter [provider routing](https://openrouter.ai/docs/guides/routing/provider-selection) and [structured outputs](https://openrouter.ai/docs/guides/features/structured-outputs).
+
+### OpenAI-compatible endpoints
+
+Any OpenAI chat-completions-compatible endpoint (OpenAI, Groq, Together, vLLM, Ollama, LM Studio, and others) can run reviews. It must support tool calls and JSON-schema structured output.
+
+```sh
+sphinx auth --provider openai --base-url https://api.openai.com/v1   # prompts for the key (hidden)
+sphinx config --provider openai --model gpt-5-mini                    # or per size: --large openai:<model>
+```
+
+The key is stored next to its URL and only ever sent there. Plain `http://` is allowed only for localhost, where a key is optional. For scripts, set `SPHINX_OPENAI_BASE_URL`, plus `SPHINX_OPENAI_API_KEY` unless the endpoint is localhost. Sphinx never reads `OPENAI_API_KEY`.
+
+### Reference pricing and quality
+
+The paid value preset uses Haiku 5.5 with an 8,192-token output ceiling, including reasoning. Reference prices checked **October 15, 2026** start at $0.10 input / $0.50 output per million tokens below 100,000 input tokens; the higher context tier is $0.50 / $2.50. Rates vary by endpoint and over time; see [Haiku endpoints](https://openrouter.ai/api/v1/models/anthropic/claude-haiku-5.5/endpoints). At the lower rates, 30,000 input plus 2,000 output tokens costs about $0.004. A whole check makes several requests with repeated context.
+
+The [evaluation results](../eval/RESULTS.md) record measured question quality, grading failures, and corrections across Haiku, Qwen, DeepSeek, and GLM on synthetic changes. They are a limited development benchmark, not a reliability guarantee. The Haiku preset is experimental because it rejected a sufficient qualitative answer in a focused test; DeepSeek is an experimental open-weight preset. Price and tool support alone do not establish question quality.
+
+## Routing and question counts
+
+Routing is deterministic and makes no model request. It counts **added plus deleted lines**, changed files, and consequential path terms. Ignored files do not count.
+
+| Tier | Default rule |
+| --- | --- |
+| Small | At most 80 changed lines and 3 files |
+| Medium | Between the small and large thresholds |
+| Large | At least 400 changed lines, 12 files, or a consequential path |
+
+Consequential paths contain `auth`, `permission`, `migration`, `billing`, `payment`, `crypto`, `security`, or `terraform`. A matching path makes even a tiny patch large. These are configurable heuristics, not a semantic risk classification.
+
+The tier and your chosen depth set the maximum number of initial questions:
+
+| Change tier | Relaxed | Standard | Thorough |
+| --- | --- | --- | --- |
+| Small | 1 | 1 | 1 |
+| Medium | Up to 2 | Up to 2 | Up to 3 |
+| Large | Up to 2 | Up to 3 | Up to 5 |
+
+- `relaxed`: observable behavior and the most consequential edge case.
+- `standard`: behavior, failure modes, and relevant system interactions.
+- `thorough`: also supported rollout, rollback, and compatibility assumptions.
+
+These are ceilings, not quotas: the reviewer asks fewer questions when the evidence supports fewer distinct behaviors, and never pads. A wrong answer adds a replacement question for the same concept, so a check can ask more than the initial count. Changing the model does not change the question count.
+
+## Model calls, tokens, and limits
+
+**Model calls have no default cap** (`maxModelCalls: null`, `agentMaxTurns: null`). Every request is counted: background investigation, compaction, the question audit, grading, replacement audits, and failed requests. The questionnaire shows calls and tokens as the check runs, plus cost when the provider reports it.
+
+| Step | Typical requests |
+| --- | --- |
+| Investigation for a small / medium / large change | Aims for 5 / 7 / 8, including the question audit. These are planning targets, not stops. |
+| Each answer, learning request, or dispute | 1 |
+| A proposed replacement question | 1 more, for an independent source audit |
+| Status, help, config, pending, or pushing an already approved change | 0 |
+
+Set or clear an optional cap. This changes no routes and makes no model request:
+
+```sh
+sphinx config --max-model-calls 30          # 1–100
+sphinx config --max-model-calls unlimited   # `none` is an alias
+```
+
+- Existing numeric caps stay in effect until changed. A check adopts an edited cap when resumed, preserving questions, progress, and counted calls. Lowering a cap below current usage blocks further calls.
+- An explicit cap reserves calls for grading and the final audit; a lone remaining request cannot start a question synthesis that would lack its audit.
+- `agentMaxTurns` (advanced) caps investigation, compaction, question generation, and auditing for one review attempt.
+
+Other limits always apply:
+
+| Setting | Default | Bounds |
+| --- | --- | --- |
+| `timeoutSeconds` | 180 | The whole investigation. Unlimited calls do not mean unlimited time. |
+| `maxContextBytes` | 100,000 | Serialized review context (prompts, tools, schemas), not the whole diff. Pi compacts before this; context that still does not fit is rejected before a model call. |
+| `toolResultBytes` | 16,000 | Each tool page. Pages shrink to leave room for batched reads. |
+| `maxOutputTokens` | 4,096 (8,192 in `openrouter-value`) | Every request, 512–16,384. Set with `sphinx config --max-output-tokens 8192`. |
+
+OpenRouter counts hidden reasoning within `maxOutputTokens`; a higher ceiling can prevent truncation and permits more billed output. Codex and Claude CLIs get concise-output instructions and local timeout and output-byte limits, but their interfaces have no equivalent hard token cap. Small and medium changes request low reasoning effort; large changes request medium effort where the CLI supports it.
+
+**Retries.** Provider failures never retry automatically and never switch providers. Cache warming is disabled. Without a call cap, the reviewer stops after three consecutive invalid responses. Correctable tool or question-validation errors are returned to Pi as feedback within any explicit cap. If a review fails, the questionnaire offers to continue from saved work; Pause is the default. From a terminal, `sphinx check --id <id>` resumes saved work, and `--retry-review` gives a failed, questionless review one further attempt (with an explicit cap, up to `maxModelCalls` additional requests). Setup, credential, stale-code, and evidence-loading failures must be fixed first.
+
+Call caps bound requests and byte limits bound evidence. Neither is a dollar or subscription ceiling. **Set provider-side spending limits for paid accounts.**
+
+## Repository policy
+
+`sphinx init` creates `.sphinxconfig`, `.sphinxignore`, and `.sphinxcontext.md` when they are absent and never overwrites them. Edit the files directly afterwards. Commit them to share policy with collaborators. Start from `sphinx init` or [.sphinxconfig.example](../.sphinxconfig.example):
+
+```json
+{
+  "version": 1,
+  "events": ["pre-push"],
+  "branches": ["main", "release/*"],
+  "level": "standard",
+  "exclude": ["vendor/**"]
+}
+```
+
+| Key | Meaning |
+| --- | --- |
+| `enabled` | `false` disables Sphinx for this repository |
+| `events` | `pre-push`, `pre-commit`, or both |
+| `branches` | Push policies match the **destination** branch; commit policies match the current local branch |
+| `remotes` | Remote name patterns for pushes; default `*` |
+| `level` | `relaxed`, `standard`, or `thorough` |
+| `exclude` | Extra ignore patterns, added to machine-wide ones |
+| `backgroundPreparation` | `false` opts this repository out |
+
+Branch defaults come from machine-wide settings (initially `main` and `master`), not from the branch you happen to have checked out. Without prompts:
+
+```sh
+sphinx init --yes --branches main --events pre-push --level standard
+```
+
+If both `.sphinxconfig` and legacy `.sphinx.json` exist, `.sphinxconfig` wins and they are not merged; `init` copies a legacy policy into `.sphinxconfig` and leaves the original.
+
+**Commit checkpoints.** Enable `pre-commit`. To run one by hand, `sphinx check --staged` assesses the index, including partial staging.
+
+**Manual push checks.** `sphinx check --remote origin --branch main` selects the destination; otherwise Sphinx uses the upstream. Multiple destination refs are assessed separately. Tag-only pushes and deletions do not trigger checks in v0.1.
+
+## Project context
+
+`.sphinxcontext.md` describes what the project does, who uses it, important workflows, and architecture boundaries. It is included in every reviewer, compaction, and grading request.
+
+```sh
+sphinx init --yes --context 'A booking service for shared equipment. Reservations must never overlap.'
+```
+
+- Keep it under 16,000 bytes and free of secrets. It respects `.sphinxignore`.
+- The reviewer checks its claims against code. It cannot override Sphinx policy or authorize reading ignored files.
+- Without context, the reviewer establishes purpose from documentation and source rather than inventing requirements.
+- Changing it invalidates prepared questions and completion records.
+
+## Files Sphinx never reads
+
+Built-in exclusions apply recursively and cannot be undone by project negations:
+
+- `.env` and `.env.*`, including `.env.example`.
+- Private key and keystore names: `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `id_rsa`, `id_ed25519`, and related SSH names.
+- Credential files: `.netrc`, `.npmrc`, `.pypirc`, `*credentials*.json`, `service-account*.json`, `secrets.json`, `secrets.yaml`, `secrets.yml`.
+
+Add project exclusions to `.sphinxignore`:
+
+```gitignore
+# Project-specific private or generated files
+internal/customer-exports/
+/config/production.json
+*.generated.ts
+dist/
+```
+
+Supported syntax is `*`, `**`, `?`, root `/`, directory suffix `/`, `#` comments, and local `!` negations; escape a leading `#` or `!` with `\`. This is a small gitignore-like parser, not the full Git pattern language. Project rules cannot undo machine-wide (`~/.config/sphinx/ignore`) or built-in exclusions. Ignore-policy symlinks are rejected. `.gitignore` is not applied to tracked files.
+
+**Filtering happens before patch, line-count, and content retrieval, including searches of unchanged files.** Ignored files' contents are not read, saved as evidence, or sent to a model. Git may list their names and object IDs locally to identify changes. A change that touches only ignored files needs no assessment.
+
+Ignore rules match paths. They do not detect a secret inside an included source file. Add sensitive paths before your first assessment.
+
+Evidence comes from Git objects, not your working files: pre-commit reads the staged index, pre-push reads commits. `.sphinxcontext.md` is read from the working directory and its hash is bound to the assessment. Snapshot identity covers the full commit or index, so editing an ignored file alongside an assessed change can still invalidate the earlier completion.
+
+## Background preparation
+
+After commits, merges, rewrites, and checkouts, Sphinx schedules a detached reviewer for the expected destination so questions are ready before you push. It uses local remote-tracking refs and never fetches. It never opens a questionnaire or approves a push.
+
+- `sphinx status` shows preparation progress; `sphinx prepare` schedules it explicitly; `sphinx prepare --retry` retries a failed job (failures never retry on their own).
+- Preparation and the push check share one assessment, lock, question set, and usage count. A change to source, destination, policy, ignore rules, or context discards prepared work.
+- Set `backgroundPreparation: false` in `config.json` or `.sphinxconfig` to opt out. A repository cannot re-enable preparation disabled machine-wide.
+- While yolo is on, preparation is paused: no new model request starts, although one already in progress may finish.
+- A first push, a branch without local tracking history, or a push to an unexpected destination needs a cold review at push time. Pre-commit checks always review on demand. Run `git fetch` if remote history is missing.

package/docs/integrations.md

@@ -0,0 +1,135 @@
+# Integrations and troubleshooting
+
+The Git hook is the checkpoint. It works on its own, including for pushes from a terminal or GUI client. Coding-agent integrations add two things: guidance telling the agent to wait for a blocked Git command, and fallback forms for checks that could not open in the browser. For the first-run path, see the [README](../README.md).
+
+- [Supported clients](#supported-clients)
+- [Choosing and opening clients](#choosing-and-opening-clients)
+- [Per-client notes](#per-client-notes)
+- [How a checkpoint reaches you](#how-a-checkpoint-reaches-you)
+- [Remote machines, SSH, and CI](#remote-machines-ssh-and-ci)
+- [Git hooks and existing hooks](#git-hooks-and-existing-hooks)
+- [Manual JSON protocol](#manual-json-protocol)
+- [Troubleshooting](#troubleshooting)
+- [Uninstall](#uninstall)
+
+## Supported clients
+
+| Client | Checkpoint | Fallback | Installed integration |
+| --- | --- | --- | --- |
+| Codex | Local browser questionnaire | Native MCP form | MCP server and lifecycle hooks |
+| Claude Code | Local browser questionnaire | Native MCP form | MCP server and lifecycle hooks |
+| Pi 1.2+ | Local browser questionnaire | Native dialogs | Local Pi extension |
+| Cursor 1.7+ | Local browser questionnaire | Browser, after Git exits | Local user hooks |
+| OpenCode 1.x | Local browser questionnaire | Browser, after Git exits | Local OpenCode plugin |
+
+Client integrations are separate from the reviewer model. Pi, Cursor, and OpenCode do not supply reviewer authentication; choose a Codex/Claude CLI route, OpenRouter, or an OpenAI-compatible endpoint (see [configuration](configuration.md#reviewer-models)).
+
+## Choosing and opening clients
+
+`--agents auto` (the default) detects clients by executable, configuration directory, or an existing Sphinx installation. Guided setup shows checkboxes with **All supported agents** first and detected clients preselected: arrow keys move, Space toggles, Enter confirms. Clear every box to skip agent setup; previously connected integrations stay installed.
+
+```sh
+sphinx install --agents codex,claude,pi,cursor,opencode   # explicit subset
+sphinx install --agents none                              # Git only
+```
+
+Run `sphinx install` again after installing a new supported client; Sphinx does not discover new clients on its own.
+
+Interactive installation opens the selected clients afterwards: fresh Codex, Claude Code, Pi, and OpenCode CLI sessions, or a new Cursor window. Opening a client sends no prompt and makes no Sphinx model request. Existing client processes are not restarted.
+
+```sh
+sphinx install --no-launch                            # install without opening clients
+sphinx install --yes --preset codex-economy --launch  # unattended install, then open
+sphinx activate                                       # open configured clients later
+sphinx activate --agents codex,claude
+```
+
+`activate` does not reinstall or change settings; `--json` returns launch results. If a client is missing or no terminal or editor can be opened, Sphinx prints the command to run yourself.
+
+Opening a client does not verify MCP connectivity or hook trust. Sphinx never bypasses a client's trust review. Check what Sphinx can see with `sphinx doctor`.
+
+## Per-client notes
+
+**Codex.** Open `/hooks` and trust the Sphinx hooks; `sphinx doctor` cannot verify this. Codex approval policies can cancel native forms: in Codex 0.162.1, approval policy `never` cancels them unless the host enables full-access form input for the user thread. A cancelled form leaves the check pending; finish it with `sphinx check` in a terminal. Sphinx does not change your approval policy.
+
+**Claude Code.** Start a new session to load the hooks. Confirm the `sphinx` server is connected in `/mcp`.
+
+**Pi.** Start a new session, or run `/reload` in an existing one. Native fallback dialogs need an interactive session or a dialog-capable RPC client; noninteractive modes leave the check pending for `sphinx check`.
+
+**Cursor.** Start a new Agent conversation in the opened window. Activation flags versions older than 1.7 for an update. The installed user hooks cover local sessions, not Cursor cloud agents.
+
+**OpenCode.** Start a new session. The plugin is installed in OpenCode's configuration directory (honoring `OPENCODE_CONFIG_DIR` or `XDG_CONFIG_HOME`).
+
+Each client controls how its own forms and dialogs look, and may keep its own interaction logs.
+
+## How a checkpoint reaches you
+
+1. **Browser (normal).** The blocked Git hook serves a questionnaire on `127.0.0.1` and prints its URL. On macOS it opens in a background browser tab without activating Terminal or moving your coding window; elsewhere, open the printed URL. One page handles every checkpoint in a Git operation. Git continues when you pass.
+2. **Native fallback.** If the browser page cannot be presented, Git stops and the check is queued. Codex and Claude Code show an MCP form after the shell command exits; Pi shows extension dialogs; Cursor and OpenCode point you to the browser page. Because Git has already exited, passing a fallback check does not resume it; run the Git command again once.
+3. **Terminal.** `sphinx check` runs the same check in your terminal at any time. It supports `/learn`, `/dispute <reason>`, and `/quit` (save and leave pending).
+
+All three share one assessment per change. **Your answers go directly to Sphinx; the coding model never sees questions, answers, or feedback.** It receives only status, assessment IDs, progress, and usage counts. It does not start the interview or relay answers, and there is no extra coding-model turn per answer. A paused or dismissed check does not reopen on unrelated shell commands; retrying the blocked Git command queues it again. The integration follows checks across `cd` and `git -C`.
+
+Agent guidance tells the coding agent not to start a duplicate Git command while one is waiting and not to answer for you. The host may still cancel a long-running shell command before you finish; in that case, complete the check and retry once.
+
+## Remote machines, SSH, and CI
+
+The installation covers your local machine. Remote machines, containers, and hosted coding agents need their own installation.
+
+Sphinx opens the browser automatically only on macOS. On Linux, WSL, and over SSH it prints the loopback URL instead. From a remote session, forward the same port number (for example `ssh -L <port>:127.0.0.1:<port> host`) and open the printed URL unchanged in your local browser; the page rejects other hosts and ports. Or run `sphinx check` on the remote machine. A remote connection may time out sooner than Sphinx's 25-minute wait.
+
+CI never starts a questionnaire. The check stays pending and Git stops.
+
+## Git hooks and existing hooks
+
+`sphinx install` sets a machine-wide Git `core.hooksPath`, which covers existing and new repositories that use that Git configuration. Existing repository hooks still run first, with their arguments and input, and their rejection is preserved. Hooks with streaming protocols are forwarded directly. Reinstallation is idempotent, and agent settings are merged rather than replaced.
+
+A repository that sets its own `core.hooksPath` needs a compatibility step. `sphinx doctor` reports this:
+
+```sh
+cd your-repo
+sphinx install --repo
+```
+
+Besides the checkpoint hooks, `post-commit`, `post-merge`, `post-rewrite`, and `post-checkout` schedule [background preparation](configuration.md#background-preparation).
+
+## Manual JSON protocol
+
+For integrations and debugging, the CLI returns questions and feedback as JSON. It never returns answer keys. Codex and Claude use `sphinx mcp` internally, and Pi calls the same controller from its extension; none of them asks the coding model to run these commands.
+
+```sh
+sphinx pending --json
+sphinx check --json
+sphinx answer <assessment-id> --text 'Your answer and reason' --json
+sphinx explain <assessment-id> --json
+sphinx dispute <assessment-id> --text 'Why the premise is wrong' --json
+```
+
+These are for a person or a test harness. A coding agent must not answer on your behalf.
+
+`help`, `status`, `pending`, and `config` never call a model. `--json` output contains no banners or ANSI styling; color is off when output is redirected, and `NO_COLOR=1` disables it.
+
+## Troubleshooting
+
+| Symptom | What to do |
+| --- | --- |
+| Git is waiting and no page opened | Open the `Sphinx questionnaire:` URL that Git printed. |
+| You closed the tab | Git keeps waiting. Reopen the same URL until the 25-minute deadline. |
+| You paused, the deadline passed, or the host cancelled the shell | Progress is saved. Run the Git command once more, or `sphinx check` first. |
+| A native form was cancelled or never appeared | Run `sphinx check` in a terminal. In Codex, see the approval policy note above. |
+| The review failed before questions appeared | The page offers to continue from saved work. From a terminal: `sphinx check --id <id>`, or `--retry-review` for a failed, questionless review. See [limits](configuration.md#model-calls-tokens-and-limits). |
+| The check keeps coming back after you passed | Something changed: code, destination base, policy, ignore rules, context, or reviewer route. Completion also expires after 24 hours. |
+| Hooks do not run in one repository | `sphinx doctor`, then `sphinx install --repo` if it reports a hooks override. |
+| Missing remote history | `git fetch`, then push again. |
+
+Never start a second copy of a Git command that is still waiting.
+
+## Uninstall
+
+```sh
+sphinx uninstall --repo   # remove an explicit repository integration, if present
+sphinx uninstall          # remove machine-wide Git and agent integrations
+npm uninstall -g sphinx-understand
+```
+
+Uninstall restores the previous hook configuration when Sphinx still owns it and removes only its own unchanged agent handlers and MCP registration. Later edits are preserved and reported. Machine-wide uninstall leaves explicit repository installations in place, with a warning; remove those first. Configuration, credentials, and assessment state stay in `~/.config/sphinx` for you to keep or delete.

package/docs/logo.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" fill="#16130f">
+<style>@media (prefers-color-scheme: dark){svg{fill:#ede7dd}}</style><mask id="m"><rect width="64" height="64" fill="#fff"/><path d="M24 22h16v14c0 6-3.6 10-8 10s-8-4-8-10z" fill="#000"/><rect x="26.5" y="44" width="11" height="12" fill="#000"/><rect x="17" y="18.2" width="30" height="1.8" fill="#000"/><g fill="#000"><rect y="26" width="21" height="2.2"/><rect x="43" y="26" width="21" height="2.2"/><rect y="32" width="21" height="2.2"/><rect x="43" y="32" width="21" height="2.2"/><rect y="38" width="21" height="2.2"/><rect x="43" y="38" width="21" height="2.2"/><rect y="44" width="21" height="2.2"/><rect x="43" y="44" width="21" height="2.2"/><rect y="50" width="21" height="2.2"/><rect x="43" y="50" width="21" height="2.2"/></g></mask>
+<path mask="url(#m)" d="M24 5h16c5 0 8.5 3.5 10 9l6 16-4 2v28H12V32l-4-2 6-16c1.5-5.5 5-9 10-9z"/><rect x="26.6" y="27.4" width="4.2" height="2.2" rx="1.1"/><rect x="33.2" y="27.4" width="4.2" height="2.2" rx="1.1"/><rect x="29.2" y="38.6" width="5.6" height="1.8" rx=".9"/><path d="M29.4 47.2h5.2l-.6 9.4h-4z"/></svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sphinx-understand",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Outsource your thinking, not your understanding. A comprehension checkpoint for agent-assisted development.",
   "homepage": "https://github.com/parthh01/sphinx#readme",
   "repository": {

package/src/browser-interview.js

@@ -9,6 +9,8 @@ import { prepareInteractiveCheck } from './check-recovery.js';
 import { claimCheckpointDialog, finishCheckpointDialog, waitForCheckpointTerminal } from './terminal-launch.js';
 import { browserPage } from './browser-page.js';
 import { recordOverride } from './overrides.js';
+import { withTextStream, partialField } from './stream.js';
+import { loadChangeView } from './change-view.js';
 
 const ID = /^[a-f0-9]{64}$/u;
 const cancelled = () => Object.assign(new Error('Check paused. Progress is saved.'), { code: 'SPHINX_CANCELLED' });
@@ -35,7 +37,7 @@ export async function openQuestionnaireBrowser(url, { env = process.env, platfor
 function publicFields(state) {
   if (!state) return {};
   return {
-    id: state.id, target: state.target,
+    id: state.id, target: state.target, event: state.event,
     route: state.route && { provider: state.route.provider, model: state.route.model, tier: state.route.tier },
     progress: state.progress, usage: state.usage, tokens: state.tokens,
     ...(state.question ? { question: { id: state.question.id, prompt: state.question.prompt, choices: state.question.choices || [] } } : {}),
@@ -50,6 +52,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
   store: providedStore, readConfig = loadConfig, revalidate = revalidateSnapshot,
   reserve = claimCheckpointDialog, release = finishCheckpointDialog, waitForExisting = waitForCheckpointTerminal,
   openBrowser = openQuestionnaireBrowser, output = line => process.stderr.write(`${line}\n`), logOverride = recordOverride,
+  loadView = loadChangeView,
 } = {}) {
   const token = randomBytes(32).toString('base64url'), nonce = randomBytes(24).toString('base64');
   let server, origin, url, opened = false, closed = false, active, skip, resolver, sequence = 0, waitingGit = false;
@@ -60,6 +63,12 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
   // The chat transcript for the current checkpoint lives only in this process.
   // It contains public questions, feedback, and the human's own text.
   let transcript = [], turns = 0;
+  // Read-only display of the checkpoint's frozen comparison. It is loaded
+  // beside the questionnaire and can never block, grade, or approve it.
+  let view, evidence, evidenceKey;
+  const viewState = () => !view ? undefined : view.status === 'ready'
+    ? { status: 'ready', header: view.model.header, totals: view.model.totals }
+    : { status: view.status, ...(view.reason ? { reason: view.reason } : {}) };
   const say = item => { transcript = [...transcript, { id: `m${++turns}`, ...item }]; };
   const settle = status => { transcript = transcript.map(item => item.role === 'human' && item.status === 'checking' ? { ...item, status } : item); };
   const showQuestion = visible => {
@@ -78,8 +87,10 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       else stream.write(event);
     } catch { stream.destroy(); streams.delete(stream); }
   };
-  const publish = next => {
-    state = { ...next, messages: transcript, waitingGit, operationClosed: closed, revision: randomUUID(), sequence: ++sequence };
+  // Display-only updates (change view, evidence) keep the revision, so they
+  // never turn an answer already in flight into a stale submission.
+  const publish = (next, { display = false } = {}) => {
+    state = { ...next, messages: transcript, change: viewState(), evidence: evidence && evidence.checkpoint === next.id ? { questionId: evidence.questionId, refs: evidence.refs } : undefined, waitingGit, operationClosed: closed, revision: display ? next.revision : randomUUID(), sequence: ++sequence };
     const event = `data: ${JSON.stringify(state)}\n\n`;
     for (const stream of streams) writeEvent(stream, event);
   };
@@ -103,11 +114,20 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
     if (req.headers.host !== new URL(origin).host || (req.headers['sec-fetch-site'] && !['same-origin', 'none'].includes(req.headers['sec-fetch-site']))) return send(res, 403, { error: 'Forbidden request.' });
     const route = req.url?.split('?')[0];
     const segments = route?.split('/') || [];
-    if (!equal(segments[1], token) || segments.length > 3 || (segments[2] && !['state', 'events', 'action'].includes(segments[2]))) return send(res, 404, { error: 'Not found.' });
+    if (!equal(segments[1], token) || segments.length > 3 || (segments[2] && !['state', 'events', 'action', 'change', 'diff'].includes(segments[2]))) return send(res, 404, { error: 'Not found.' });
     if (req.method === 'GET' && !segments[2]) {
       res.writeHead(200, { ...headers, 'Content-Type': 'text/html; charset=utf-8' }); res.end(browserPage({ token, nonce })); return;
     }
     if (req.method === 'GET' && segments[2] === 'state') return send(res, 200, state);
+    if (req.method === 'GET' && ['change', 'diff'].includes(segments[2])) {
+      const query = new URL(req.url, origin).searchParams, current = view;
+      if (!current || query.get('id') !== current.id || state.id !== current.id) return send(res, 409, { error: 'This checkpoint changed. Reload the current change.' });
+      if (current.status !== 'ready') return send(res, current.status === 'loading' ? 202 : 200, viewState());
+      try { await current.check(); } catch { return send(res, 409, { error: 'The code or settings changed. This view no longer describes the checkpoint.' }); }
+      if (segments[2] === 'change') return send(res, 200, { status: 'ready', id: current.id, ...current.model.summary() });
+      try { return send(res, 200, await current.model.diff(query.get('path') ?? '', { context: query.get('context') ?? '3' })); }
+      catch (error) { return send(res, 404, { error: error.code === 'CHANGE_VIEW_UNAVAILABLE' ? error.message : 'This file diff is unavailable.' }); }
+    }
     if (req.method === 'GET' && segments[2] === 'events') {
       if (streams.size >= 8) return send(res, 429, { error: 'Too many open questionnaire pages.' });
       res.writeHead(200, { ...headers, 'Content-Type': 'text/event-stream; charset=utf-8', Connection: 'keep-alive' });
@@ -167,6 +187,37 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       output(automatic ? 'Sphinx: questionnaire opened in a background browser tab. Your coding window stays in place.' : 'Sphinx: open the local URL above to answer. No application was brought to the foreground.');
     }
   }
+  function startView(request, snapshot, config, operationEnv, store) {
+    evidence = undefined; evidenceKey = undefined;
+    const current = view = { id: request.id, status: 'loading', store, check: async () => {
+      const latest = await readConfig(snapshot.repoRoot, operationEnv);
+      if (policyHash(latest) !== policyHash(config) || !(await revalidate(snapshot, latest, { env: operationEnv }))) throw new Error('stale');
+    } };
+    Promise.resolve().then(() => loadView(snapshot, config, { env: operationEnv })).then(model => {
+      if (view !== current) return;
+      current.status = 'ready'; current.model = model; publish(state, { display: true }); refreshEvidence(request.id);
+    }, error => {
+      if (view !== current) return;
+      current.status = 'unavailable';
+      current.reason = error?.code === 'CHANGE_VIEW_UNAVAILABLE' ? error.message : 'The changed files could not be loaded for display.';
+      publish(state, { display: true });
+    });
+  }
+  function refreshEvidence(id) {
+    const current = view;
+    if (current?.status !== 'ready' || current.id !== id || !current.store) return;
+    current.store.read(id).then(async session => {
+      const question = session.questions?.[session.index];
+      if (!question || session.status === 'passed') return;
+      const key = `${id}:${question.id}`;
+      if (evidenceKey === key) return;
+      evidenceKey = key;
+      const refs = await current.model.evidenceFor(question, session.review).catch(() => []);
+      if (view !== current || evidenceKey !== key) return;
+      evidence = { checkpoint: id, questionId: question.id, refs };
+      publish(state, { display: true });
+    }).catch(() => {});
+  }
   async function present({ request, env: operationEnv = env, signal: requestSignal = signal } = {}) {
     if (offLimits(operationEnv)) return { status: 'unavailable', reason: 'noninteractive', id: request?.id };
     if (closed || active) return { status: 'unavailable', id: request?.id };
@@ -202,6 +253,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       const session = await store.read(request.id), config = await readConfig(request.repoRoot, operationEnv);
       if (session.snapshot.repoRoot !== request.repoRoot) throw new Error('This checkpoint belongs to another repository.');
       await validate(session.snapshot, config);
+      startView(request, session.snapshot, config, operationEnv, store);
       let visible = store.public(session);
       publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'working', message: 'Preparing your understanding check…' });
       await ensureServer(operationEnv);
@@ -229,13 +281,27 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       if (!visible) return skip ? skipped() : { status: 'pending', id: request.id };
       while (visible.status !== 'passed') {
         localSignal.throwIfAborted();
-        showQuestion(visible);
+        showQuestion(visible); refreshEvidence(request.id);
         const action = await waitForAction({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'question', ...(visible.browserError ? { error: visible.browserError } : {}) }, ['answer', 'learn', 'dispute']);
         try {
           await validate(session.snapshot, config);
-          visible = await store.answer(request.id, action.action === 'learn' ? 'I do not know. Explain this concept and give me a different scenario to apply it to.' : action.response.trim(), config, {
+          // Type the grader's feedback into the conversation as it streams.
+          // Only the first streamed feedback is shown; the saved result replaces it.
+          let draft, frozen = false, lastPublish = 0;
+          const onText = raw => {
+            if (frozen) return;
+            const field = partialField(raw, 'feedback');
+            if (!field?.text) return;
+            if (!draft) { say({ role: 'sphinx', kind: 'feedback', streaming: true, text: field.text }); draft = transcript.at(-1).id; }
+            else transcript = transcript.map(item => item.id === draft ? { ...item, text: field.text } : item);
+            if (field.complete) frozen = true;
+            const now = Date.now();
+            if (field.complete || now - lastPublish > 60) { lastPublish = now; publish(state); }
+          };
+          const dropDraft = () => { if (draft) transcript = transcript.filter(item => item.id !== draft); };
+          visible = await withTextStream(onText, () => store.answer(request.id, action.action === 'learn' ? 'I do not know. Explain this concept and give me a different scenario to apply it to.' : action.response.trim(), config, {
             learn: action.action === 'learn', dispute: action.action === 'dispute', expectedQuestionId: action.questionId, signal: localSignal,
-          });
+          })).finally(dropDraft);
           settle('graded');
           if (visible.feedback) say({ role: 'sphinx', kind: 'feedback', text: visible.feedback });
         } catch (error) {
@@ -249,7 +315,7 @@ export function createBrowserInterview({ env = process.env, signal, timeoutMs =
       }
       localSignal.throwIfAborted(); await validate(session.snapshot, config);
       finalStatus = 'passed';
-      publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'passed', message: 'Understanding check complete. Return to the original Git output for the operation’s result.' });
+      publish({ ...publicFields(visible), repoRoot: request.repoRoot, phase: 'passed', message: 'Understanding check passed for this checkpoint. It records your answers to these questions; it is not a review of every changed line or a claim that the code is correct. Return to the original Git output for the operation’s result.' });
       return { status: 'passed', id: request.id };
     } catch (error) {
       settle('not-graded');