sphinx-understand 0.1.0 → 0.1.1

package/README.md

@@ -1,342 +1,178 @@
-# Sphinx
+<p align="center"><img src="docs/logo.svg" width="96" alt="Sphinx logo"></p>
 
-Outsource your thinking, not your understanding.
+<h1 align="center">Sphinx</h1>
 
-Sphinx adds an understanding checkpoint to agent-assisted development. Before a configured Git operation, it asks you to predict the consequences of your changes. If you miss a concept, it explains the relevant execution path and gives you a new scenario to apply it to.
+<p align="center"><em>Outsource your thinking, not your understanding.</em></p>
 
-Install once for your machine. Git provides a local browser questionnaire and waits. On macOS, the page opens in the background, leaving your coding-agent window in place. Once you pass, the same push or commit continues automatically, whether you started it yourself or through a coding agent. An independent reviewer investigates committed changes using read-only diff, file, and search tools. It receives your project's context without the conversation that produced the code. Background preparation gets questions ready before a push when the destination is known.
+Sphinx adds an understanding check to agent-assisted development. When you push to a protected branch, Git waits while Sphinx asks you to predict what your change will do. If you miss something, it explains and gives you a new scenario to try. Once you pass, the same push continues. This works whether you or a coding agent ran `git push`.
 
-## Install
+The questions come from a separate reviewer model. It reads the committed change through read-only Git tools and does not see the conversation that produced the code.
 
-Requires Node.js 22.19 or newer, Git, and macOS, Linux, or WSL. Native Windows installation is not supported yet.
+## What a check looks like
 
-```sh
-npm install -g sphinx-understand
-sphinx install
-```
-
-There is no account or hosted Sphinx service. To work from a checkout instead, run `npm install -g .` in the repository.
-
-Onboarding starts by asking which coding agents you use, then offers economical reviewer presets for those clients. Codex uses GPT-6 Luna; Claude Code uses Haiku. You can instead choose paid OpenRouter coding models or enter your own routes for small, medium, and large changes. Git defaults are pushes to `main` or `master` at standard depth. Existing installations keep their saved models unless you choose a replacement.
-
-**Every OpenRouter route requires an API key, including free models.** The installer accepts an existing `OPENROUTER_API_KEY` or prompts for a key with hidden input. Create one at [OpenRouter's key settings](https://openrouter.ai/settings/keys). Paid routes also need OpenRouter credits. Sphinx stores a supplied key in a user-only `credentials.json` file outside your repositories (mode `0600`); this is a local file, not an OS keychain. `sphinx auth` replaces it later. Keys are never stored in project configuration.
-
-Using OpenRouter sends filtered evidence to OpenRouter and its selected model provider, billed separately from your coding-agent plan. Codex and Claude reviewer routes use that CLI's existing authentication and consume its allowance. For unattended installation, choose a preset explicitly:
-
-```sh
-sphinx install --yes --preset codex-economy
-# or
-sphinx install --yes --preset claude-economy
-# or, using paid OpenRouter credits
-sphinx install --yes --preset openrouter-value --allow-paid
-```
-
-Fresh `install --yes` requires a preset or an explicit reviewer route; it does not silently choose a free model. Reinstalling an existing configuration preserves its routes. The free OpenRouter router remains an explicit best-effort option (`--preset openrouter-free`); its model selection, rate limits, and tool support can interrupt a check. Sphinx does not automatically switch providers or upgrade models after a failure.
+This is an illustrative exchange for a change that adds a background job queue:
 
-You need a recent, signed-in CLI with access to the selected model for Codex or Claude review. Pi, Cursor, and OpenCode integrations present checkpoints, but do not supply reviewer authentication or models. Their users choose an installed Codex/Claude CLI transport or OpenRouter separately.
+> **Question.** The worker commits the operation but crashes before acknowledging the job. After redelivery, can the operation happen twice? Give a short reason.
+>
+> **Your answer.** No, the job is marked done when the operation commits.
+>
+> **Sphinx.** Not quite. The job is only marked done by the acknowledgement, which happens after the commit. A crash between the two leaves it unacknowledged, so the queue delivers it again and the operation runs a second time.
+>
+> **New scenario.** A worker stalls past the visibility timeout, so a second worker receives the same job. Both commit before either acknowledges. What stops a duplicate, if anything?
 
-The independent reviewer runs in an embedded [Pi SDK](https://pi.dev/docs/latest/sdk) session. OpenRouter supplies model responses directly. The Codex and Claude routes use fresh, isolated CLI calls as model transports underneath Pi; their CLI sign-in and usage allowance are reused, while Pi runs the reviewer's tool loop and context management.
+Questions cover behavior, failure modes, and invariants rather than file names or function names. The check is open-book: you can read the code, or ask your agent to show it to you, while you answer.
 
-The installer configures user-level Git hooks and adapters for detected coding clients, then opens the selected installed clients. Codex, Claude Code, Pi, and OpenCode start fresh CLI sessions; Cursor opens a new editor window. Activation supplies no prompt and makes no Sphinx model request. It does not restart existing client processes.
+## Before you install
 
-Complete any trust or connection prompts in the opened client. **In Codex, open `/hooks` to review and trust the installed hooks.** Opening the client does not verify MCP connectivity or complete hook trust, and Sphinx does not bypass those reviews. The normal blocking flow uses a local browser questionnaire, opened in the background on macOS. Codex/Claude native forms and Pi extension dialogs handle fallback checkpoints; each client controls those dialogs' appearance.
+- **Requirements.** Node.js 22.19 or newer, Git, and macOS, Linux, or WSL. Native Windows is not supported yet.
+- **It applies to every repository on this machine.** `sphinx install` sets your global Git `core.hooksPath`. Your existing hooks still run first. Right after install, pushes to `main` or `master` in any repository are checked. `sphinx init` lets you adjust that for each repository.
+- **It blocks Git.** A matching push waits until you pass, pause, or skip, for up to 25 minutes. Your coding agent's shell may time out sooner.
+- **You need a reviewer model account.** This can be a signed-in Codex or Claude Code CLI, which uses that plan's allowance. It can also be an OpenRouter API key, which bills separately and is required even for free models, or any [OpenAI-compatible endpoint](docs/configuration.md#openai-compatible-endpoints). Sphinx has no account or hosted service of its own.
+- **Code leaves your machine.** The reviewer provider receives the changed code and related files from the commit, your answers, and `.sphinxcontext.md`. Ignored files are never read, and `.env` files, private keys, and common credential files are excluded by default. Add your own sensitive paths to `.sphinxignore` before your first check. Ignore rules match file paths, so they will not catch a secret pasted into ordinary source.
+- **There is no default cap on model calls.** A typical check makes about 5 to 8 requests, plus about one per answer. You can [set a cap](docs/configuration.md#model-calls-tokens-and-limits), and you should set spending limits with paid providers.
+- **This is practice, not a security gate.** Anyone with local access, including a coding agent, can bypass hooks or get outside help. Passing does not prove who wrote the code or that you understood it unaided. The examiner is an LLM and can be wrong.
 
-In Cursor, start a new Agent conversation in the opened window. Activation flags known versions older than 1.7 for an update; newer versions still need the hook events used by Sphinx.
+## Quick start
 
-| Development client | Checkpoint experience | Installed integration |
-| --- | --- | --- |
-| Codex | Local browser questionnaire; native MCP form for fallback checks | MCP server and lifecycle hooks |
-| Claude Code | Local browser questionnaire; native MCP form for fallback checks | MCP server and lifecycle hooks |
-| Pi 1.2+ | Local browser questionnaire; native dialogs for fallback checks | Local Pi extension |
-| Cursor | Local browser questionnaire | Local user hooks |
-| OpenCode 1.x | Local browser questionnaire | Local OpenCode plugin |
-
-`--agents auto` detects clients by their executable, configuration directory, or existing Sphinx installation. Select a subset explicitly with `--agents codex,claude,pi,cursor,opencode`, or use `--agents none` for Git-only setup. These integrations are separate from the evaluator model routes.
-
-Guided setup presents checkboxes with **All supported agents** first and detected agents preselected. Use the arrow keys to move, Space to toggle, and Enter to confirm. Clear every checkbox to skip agent setup. Previously connected integrations remain installed.
-
-Interactive installation opens clients by default. Use `--no-launch` to defer this step. `install --yes` configures Sphinx without opening clients unless you also pass `--launch`. To open configured clients later, use `activate`; it does not reinstall or change their settings:
+### 1. Install (required)
 
 ```sh
-sphinx install --no-launch
-sphinx install --yes --preset codex-economy --launch
-sphinx activate
-sphinx activate --agents codex,claude
+npm install -g sphinx-understand
+sphinx install
 ```
 
-`activate --agents` selects a subset of configured integrations; `--json` returns launch results without terminal styling. If a client is missing or the environment cannot open a terminal or editor, Sphinx reports a focused command to run yourself. Existing sessions stay open; Pi can also load its extension with `/reload`.
-
-Client policies can disable forms even when the integration is installed. In Codex 0.162.1, approval policy `never` cancels native elicitation unless the host enables full-access form input for the user thread. A cancelled form leaves the checkpoint pending; use `sphinx check` in a terminal. Sphinx does not change your approval policy.
+Guided setup asks which coding agents you use and which reviewer to use. It suggests Haiku through Claude Code or GPT-6 Luna through Codex. If you choose OpenRouter, it asks for an API key. It then offers the recommended checkpoints (pushes to `main` or `master` at standard depth) or **Customize** to pick events, branches, remotes, and depth. To install without prompts:
 
 ```sh
-sphinx doctor
+sphinx install --yes --preset claude-economy --agents claude
 ```
 
-Global defaults apply to existing and future repositories using that Git configuration. Repositories that override `core.hooksPath` need an explicit compatibility step; Sphinx diagnoses the override:
+You should see:
 
-```sh
-cd your-repo
-sphinx install --repo
+```text
+✓ Git hooks installed for this user. Existing hooks are chained.
+✓ Claude Code native questionnaire hooks and Sphinx MCP server installed.
 ```
 
-Existing hooks run first, and their rejection is preserved. Sphinx chains all existing hook types, including those with streaming protocols. Reinstallation is idempotent. Agent settings are merged, not replaced. Remote machines, containers, and hosted coding agents need their own setup; this installation covers your local machine.
+Use `--preset codex-economy` for Codex, or `--agents none` if you don't use a coding agent. Other presets, OpenRouter, OpenAI-compatible endpoints, and custom routes are covered in [configuration](docs/configuration.md#reviewer-models).
+
+### 2. Load Sphinx in your coding agent (required if you use one)
 
-The Git hook serves a local browser questionnaire for the exact checkpoint and waits for its result. You answer directly on that page; the development model receives only the Git result and status. It does not launch the interview or relay questions and answers. Native fallback dialogs in Pi require an interactive session or a dialog-capable RPC client.
+Guided setup opens your selected agents in fresh sessions. Then:
 
-On macOS, Sphinx opens the questionnaire in a background browser tab without activating Terminal or minimizing your coding window. Other environments print the loopback URL for you to open; a remote session needs access to that machine's loopback listener. CI does not start a questionnaire. One page handles all checkpoints in a Git operation, and unrelated tool calls do not reopen paused checks. Closing the tab leaves Git waiting until its deadline; Pause stops it and saves progress. `sphinx check` remains an explicit terminal alternative. A new Git attempt can queue another presentation. Cursor's installed user hooks cover local sessions, not cloud agents.
+- **Codex:** open `/hooks` and trust the Sphinx hooks. Sphinx cannot do or verify this for you.
+- **Claude Code:** start a new session. `/mcp` should show `sphinx` connected.
+- **Pi, Cursor, OpenCode:** see [per-client notes](docs/integrations.md#per-client-notes).
 
-## Set up a repository
+If you skip this step, the Git checkpoint still works. However, your agent won't know it should wait for a blocked push, and the fallback forms used when the browser can't open won't be available.
 
-After installing Sphinx once, run this in a repository:
+### 3. Set up a repository (required)
 
 ```sh
+cd your-repo
 sphinx init
 ```
 
-The guided setup explains the available Git events and question depths, then asks which destination branches and remotes to cover. It creates `.sphinxconfig`, `.sphinxignore`, and `.sphinxcontext.md`, preserving existing files. Model selection and credentials remain in your machine-wide settings.
+This asks which branches and events to check and how deep the questions should go. Then it creates three files without overwriting existing ones:
 
-Use `.sphinxcontext.md` to describe what the project does, who uses it, important workflows, and architecture boundaries. Its text is included in every reviewer, compaction, and grading request. The reviewer checks its claims against code; it cannot override Sphinx policy or authorize reading ignored files. Keep it under 16,000 bytes, without secrets. Changing context invalidates prepared questions and prior completion records. The context file itself also respects `.sphinxignore`.
+- `.sphinxconfig`: the repository's policy.
+- `.sphinxignore`: paths that are never read. **Edit this now** if the repository has private or generated files.
+- `.sphinxcontext.md`: a short description of what the project does, which every reviewer request receives. Leave out secrets.
+
+To set it up without prompts:
 
 ```sh
-sphinx init --yes --context 'A booking service for shared equipment. Reservations must never overlap.'
+sphinx init --yes --branches main
 ```
 
-Without a supplied description, setup creates an editable template. In a repository without context, the reviewer must establish purpose from available documentation and source rather than invent requirements.
+Commit the three files to share the policy with collaborators.
 
-Branch defaults come from your effective configuration, initially `main` and `master`. They do not change because you happen to be working on a feature branch. To set up checks only when pushing to `main`, without prompts:
+### 4. Check the setup (recommended)
 
 ```sh
-sphinx init --yes --branches main --events pre-push --level standard --mode block
+sphinx doctor
 ```
 
-Commit `.sphinxconfig`, `.sphinxignore`, and `.sphinxcontext.md` to share repository settings and background with collaborators. Rerunning `init` preserves them; edit the files directly to update existing settings. If a legacy `.sphinx.json` exists, `init` creates `.sphinxconfig` from that policy and leaves the old file intact. When both exist, `.sphinxconfig` takes precedence; their policies are not merged.
-
-`init` configures the repository. It does not reinstall hooks, contact a model, or change your global settings. The machine-wide hooks already cover ordinary repositories. Use `sphinx install --repo` only when that repository has its own hooks directory; use `sphinx doctor` to inspect coverage.
+It should end with `✓ Configured integrations are in place.` and exit with status 0. If not, it says what needs attention, such as a repository with its own hooks directory. Fix that with `sphinx install --repo`.
 
-## Find your way around
-
-Human-facing terminal output uses an ASCII sphinx, restrained colors, clear option descriptions, and a visible assessment progress summary. Color is off by default when output is redirected, `NO_COLOR=1` disables it, and `--json` returns machine-readable data without banners or ANSI styling.
-
-Each command has its own help:
+### 5. Push and pass your first check
 
 ```sh
-sphinx --help
-sphinx init --help
-sphinx help check
+git push origin main
 ```
 
-| Command | Use it to |
-| --- | --- |
-| `install` | Set up machine-wide Git hooks and coding-agent integrations, then open selected clients |
-| `activate` | Open configured coding clients without reinstalling |
-| `init` | Choose and save this repository's checkpoint policy |
-| `check` | Start or resume an understanding check |
-| `prepare` | Schedule background investigation; use `--retry` after a failure |
-| `pending` | List unfinished checks |
-| `answer`, `explain`, `dispute` | Respond, learn a concept, or challenge a question |
-| `status` | Inspect this repository's policy and pending work |
-| `config` | Inspect settings or change machine-wide reviewer presets, model routes, and call ceiling |
-| `doctor` | Check hook and agent integration coverage |
-| `auth` | Save or replace your OpenRouter key |
-| `uninstall` | Remove integrations while preserving unrelated settings |
-
-`help`, `status`, `pending`, and `config` do not invoke an evaluator. JSON commands work without an interactive terminal; `sphinx init --json` accepts defaults and returns its setup result.
-
-## What happens when you push
-
-1. Git supplies the exact source and destination commits. Sphinx applies branch/event policy and filters paths before reading contents.
-2. If the exact change already passed, the operation continues. Otherwise the hook saves a pending checkpoint and keeps the original Git process waiting.
-3. The hook serves a private questionnaire on loopback and prints its local URL. On macOS it opens the page in the background, without activating Terminal or minimizing the coding agent. You answer in the page; Git's stdin and the coding agent's shell are never used for questionnaire input.
-4. Sphinx reuses matching prepared questions, waits for an existing review, or starts a fresh reviewer. The reviewer reads relevant diffs and follows related source and tests before committing questions, private answer keys, and supporting evidence. A separate model request checks the questions against that evidence before displaying them. Small changes get one question; larger changes have higher ceilings based on your chosen depth. You answer directly in the form.
-5. Correct answers clear concepts. An incorrect answer gets an explanation and replaces that concept's question with a different transfer scenario. Every proposed replacement gets a fresh source audit before display, without the human answer or grading conversation. Grading costs one request; a proposed replacement adds one audit within any explicitly configured call limit. Ambiguity or evaluator failure never creates a completion record.
-6. Sphinx revalidates every original snapshot and completion record, then returns control to the same Git process. The push or commit continues automatically, without replaying its command. Completion is bound to the exact repository, commits/index, destination, ignore policy, project context, assessment policy, and expiry.
-
-Pausing, cancellation, stale code/policy, or the 25-minute interview deadline stops the operation and saves progress. Closing or refreshing a browser tab does not submit an answer; the same local URL remains available while Git is waiting. The coding client or remote connection may impose a shorter timeout. An operation that already exited cannot be resumed. CI and unavailable presentation leave the check pending and stop Git. Native/manual fallback can complete the check, followed by a new Git invocation. Advisory operations already proceeded and must not be repeated.
-
-## When it's urgent
-
-- **Skip this time:** the questionnaire has a *Skip this time* button, available even while the review is still running. Git continues immediately.
-- **Yolo mode:** `sphinx yolo` toggles skipping checks. Inside a Git repository it applies to that repository; outside one it applies globally (repositories with their own setting win). Run it again to turn it off. `--reason "prod hotfix"` is optional.
-
-Skips never count as understanding: no receipt is written and nothing resurfaces later. Every skip or toggle is appended with its optional reason to `~/.config/sphinx/overrides.jsonl`. `sphinx status` shows whether yolo is on and lists recent overrides.
-
-The questionnaire streams the reviewer's progress live (files read, searches, drafting and auditing questions) while you wait.
-
-## Background preparation and investigation
-
-Installed `post-commit`, `post-merge`, `post-rewrite`, and `post-checkout` hooks schedule a detached worker after the original hook completes. A short debounce coalesces rapid updates. The worker investigates the expected protected destination using local remote-tracking refs, and saves questions without opening a form or awarding completion. `sphinx status` reports preparation; `sphinx prepare` schedules it explicitly.
-
-Preparation and the push check share the exact assessment ID, lock, questions, and counted model usage. Source, destination/base, policy, ignore rules, or context changes cause a cache miss. Superseded work is discarded. Failed jobs are not automatically retried; `sphinx prepare --retry` makes that choice explicit. Set `backgroundPreparation: false` globally or in `.sphinxconfig` to opt out. A repository cannot re-enable preparation disabled globally.
-
-The first push of a new repository or a branch without local remote-tracking history may need a cold review. Sphinx does not fetch or guess missing remote history during preparation. Explicit pushes to a different destination can also miss the prepared cache. Pre-commit checks review the exact staged snapshot on demand.
-
-Before the first model request, Sphinx supplies bounded diff pages and a filtered file inventory using local reads. The reviewer then requests missing diff pages, source ranges, file listings, and literal searches. It can inspect unchanged callers, dependencies, and tests at the same pinned revision. File names are navigation hints; only inspected source can support a question. Sphinx enforces ignores and tool access locally; it never grants the reviewer an unrestricted shell or the developer's working files. Large patches are inspected incrementally rather than bundled into one prompt.
-
-Pi owns the reviewer session, tool loop, and [native context compaction](https://pi.dev/docs/latest/compaction). Sphinx supplies the restricted Git tools, project context, and model transports. It also keeps a separate bounded archive of exact tool observations and their provenance. Pi session entries, evidence, and an assessment awaiting its independent audit are saved privately under the checkpoint lock. Interrupted reviews resume from that state without repeating the investigation. The reviewer can recover archived observations after compaction with `read_evidence`. Pi can summarize older conversation history without replacing that evidence archive. Final questions must cite inspected evidence, and grading receives the relevant original observations, private rubric, and project context.
-
-The agent integration shares state with Git, so there is one assessment per change. The local questionnaire and native fallback forms send your responses directly to Sphinx; the development model receives only completion status and the original Git result. It does not relay questions or answers. There is no extra development-model turn for each answer.
-
-Each form lets you answer, learn the concept, dispute the premise, or pause. Pausing or dismissing keeps the assessment incomplete. It does not reopen on unrelated shell commands; retrying a blocked Git operation queues it again. The integration associates queued checks with the agent session, including when the shell uses `cd` or `git -C`.
-
-The local questionnaire also works for shell/GUI pushes outside supported coding agents. Platforms without a reliable background browser opener print the local URL instead of taking focus. SSH users can forward the loopback port or use `sphinx check` explicitly. If presentation is unavailable, Sphinx leaves the checkpoint pending and stops Git. Native after-tool callbacks or `sphinx check` can then complete the fallback check, but cannot revive a Git process that already exited.
-
-Example question for a change introducing background jobs:
-
-> The worker commits the operation but crashes before acknowledging the job. After redelivery, can the operation happen twice? Give a short reason.
-
-The examiner assesses actual behavior. Explaining a bug in the implementation can demonstrate understanding. An invalid question or answer key must be corrected before the concept can pass; disputes never award completion. It should not ask which file contains a class or whether you remember a function name.
-
-Interactive commands during a terminal check:
+Git prints the questionnaire address and waits:
 
 ```text
-/learn              Explain this concept and give me a new scenario
-/dispute <reason>   Recheck an ambiguous or incorrect premise
-/quit               Save progress and leave the operation pending
+Sphinx: understanding check needed for refs/heads/main (medium change).
+Sphinx: Git is waiting for your answers in the local Sphinx questionnaire. It will continue automatically after you pass. Do not start another copy of this Git operation.
+Sphinx questionnaire: http://127.0.0.1:56114/fSdZM7yg…
+Sphinx: questionnaire opened in a background browser tab. Your coding window stays in place.
 ```
 
-The CLI also exposes a manual JSON protocol for integrations and debugging. These commands return questions and feedback, but never private answer keys. Codex/Claude use `sphinx mcp` internally; Pi calls the same questionnaire controller from its extension. Neither asks the coding model to run these commands or supply answers:
+On macOS, the page opens in a background browser tab. On Linux, WSL, and over SSH, Git prints `open the local URL above to answer` instead, so open the printed address yourself. From a remote session, forward the same port and open the URL unchanged, or run `sphinx check`; see [remote machines](docs/integrations.md#remote-machines-ssh-and-ci). Questions can take a moment while the reviewer reads the change, and the page shows its progress as it works. Beside each question, the page shows the checkpoint's changed files, lines added and removed, a browsable diff, and the code locations the reviewer read for that question. Answer each question with a prediction and a short reason. When you pass:
 
-```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
+```text
+Sphinx: understanding check complete. Continuing this Git operation.
+To github.com:you/your-repo.git
+ * [new branch]      main -> main
 ```
 
-## Keep model usage small
-
-Routing is deterministic and makes no model request of its own. The default heuristics use **added plus deleted lines**, file count, and configurable consequential path terms:
-
-| 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 include names containing `auth`, `permission`, `migration`, `billing`, `payment`, `crypto`, `security`, or `terraform`. A matching path promotes a change to large even when the patch is tiny. A one-file change is not necessarily small: line count and consequential paths count too. These are configurable heuristics, not a semantic risk classification. Ignored files do not contribute to routing counts.
+Pushing the same change again does not ask again. A pass lasts 24 hours, unless the code, destination, or policy changes.
 
-The same deterministic tier sets the question ceiling together with your chosen depth:
+## During and after a check
 
-| 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 |
+- **Wrong answer.** You get an explanation and a new scenario about the same concept. Disputes and errors never count as passing.
+- **Explain this.** Shows the concept and asks you a new question.
+- **Dispute question.** Use this if a question's premise is wrong or ambiguous. A bad question must be corrected before that concept can pass.
+- **Pause check.** Saves your progress and stops the push. Run the same `git push` later to pick up where you left off.
+- **Closing the tab** doesn't stop anything. Git keeps waiting, and the same address works until the 25-minute deadline.
+- **Skip this time.** Lets the push through immediately, even while the review is still running. Skips never count as passing.
+- **`sphinx yolo`** turns checks off for the current repository, or globally when run outside one. Run it again to turn checks back on. A repository's own setting wins over the global one, so turning yolo off inside a repository keeps checks on there even while global yolo is on. `--reason "prod hotfix"` is optional.
+- **`sphinx check`** runs the same check in your terminal instead of the browser.
 
-These are ceilings, not quotas. The evaluator asks fewer questions when the evidence supports fewer distinct behaviors, with at least one question for an assessed change. It does not add filler to reach the ceiling. A wrong answer still leads to teaching and a replacement question about the same concept, so retries can exceed the initial question count subject to any explicitly configured model-call cap.
+Every skip and yolo toggle is logged with its reason, and `sphinx status` lists recent ones. If Git exited before you finished, for example because your agent's shell timed out, run the push once more. Never start a second copy while one is still waiting. For more cases, see [troubleshooting](docs/integrations.md#troubleshooting).
 
-Sphinx chooses the tier and uses its saved model route. Depth sets how many concepts it can assess; changing models does not change the question ceiling. Presets are starting points you can change without reinstalling:
+Your answers go straight from the page to Sphinx. Your coding agent sees only the check's status, progress, and usage, never your answers.
 
-| 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 |
+## Limits and cost
 
-Codex and Claude presets keep the 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 automatically upgrades to a more expensive model. Model access and plan limits depend on your account; see [Codex models](https://learn.chatgpt.com/docs/models) and [Claude model configuration](https://code.claude.com/docs/en/model-config).
+Question count depends on the size of the change and the depth you choose. Small changes get one question, and large ones get up to three at the default depth. After commits, Sphinx prepares questions in the background, so they are often ready by the time you push. Calls, tokens, and (when reported) cost appear in the questionnaire.
 
 ```sh
-# Change the saved reviewer routes without reinstalling.
+sphinx config --max-model-calls 30        # optional cap per check (1–100)
 sphinx config --preset openrouter-value --allow-paid
-
-# Or choose each tier yourself.
-sphinx config --small claude:haiku --medium claude:haiku --large claude:sonnet
 ```
 
-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 listed 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 includes multiple requests and repeated context. Existing saved routes do not change automatically: apply the preset to opt in, and use `--max-output-tokens` to override its output ceiling. The assessment's call limit stays unchanged.
-
-The [evaluation results](eval/RESULTS.md) retain measured question quality, grading failures and corrections across Haiku, Qwen, DeepSeek and GLM. These synthetic cases are a limited development benchmark, not a reliability guarantee. Haiku's low-cost preset is experimental because it still rejected a sufficient qualitative answer in a focused test. DeepSeek remains an experimental open-weight preset; other OpenRouter models can be selected with explicit tier routes. Price and tool support alone do not establish question quality.
-
-Interactive setup labels paid choices before selection. Noninteractive commands require `--allow-paid` or an existing `allowPaid: true` setting to choose paid OpenRouter routes. Free routes send zero-price provider limits even when another route permits paid models. There are no automatic paid fallbacks or uncounted model requests. Automatic retries and cache warming are disabled. Free availability and account limits still apply; see [OpenRouter limits](https://openrouter.ai/docs/api_reference/limits).
-
-OpenRouter requests require endpoint support for their tool and output parameters. Capability metadata is a compatibility check, not a guarantee that every response is valid; unusable output leaves the check pending. OpenRouter's [provider routing](https://openrouter.ai/docs/guides/routing/provider-selection) and [structured-output documentation](https://openrouter.ai/docs/guides/features/structured-outputs) explain these requirements.
-
-Other controls:
-
-- Investigation counts every model request, including any compaction. The first request already includes filtered, bounded diff pages read from the immutable checkpoint. These local reads consume no model calls; a self-contained change can propose questions on the first request. One independent audit request checks the whole proposed assessment before it is shown, subject to any configured call cap. Each submitted answer, learning request, or dispute uses one further request, plus another independent audit whenever it proposes a replacement question.
-- Resume reuses the saved investigation, evidence, questions, and progress; approved changes reuse completion records. Listing status and pushing an already approved change consume no inference. A waiting Git operation can launch a review when no matching questions are prepared.
-- Model calls have no default cap (`maxModelCalls: null`, `agentMaxTurns: null`); the reviewer still stops after three consecutive invalid responses and at the timeout. This covers background investigation, compaction, auditing, grading, corrections, and failed requests. Set an optional machine-wide cap with `sphinx config --max-model-calls 30` (1–100), or clear it with `sphinx config --max-model-calls unlimited` (`none` is an alias). These commands change no model routes and make no model request. Existing saved numeric caps remain in effect until changed. Existing checks adopt an edited cap when resumed and before their next request, preserving questions, progress, and all used calls. Lowering a cap below usage blocks further calls; clearing it preserves the count without a limit. If a review fails, the questionnaire offers explicit continuation of saved work; with a configured cap, it can offer a one-attempt extension when too few calls remain. Pause is the default. Provider failures never retry automatically. Setup, credential, stale-code, and deterministic evidence failures need to be resolved first. `sphinx check --id <id>` resumes saved work, and `--retry-review` can extend a configured allowance for a failed, questionless review. Active questionnaires cannot be reset this way.
-- Small/medium/large reviews aim for 5/7/8 calls including the independent audit. These are planning targets, not hard stops. The advanced `agentMaxTurns` setting defaults to `null`; a numeric value explicitly caps investigation, compaction, question generation, and auditing for one review attempt. There is no hidden request cap when both settings are `null`. An explicitly configured total cap reserves calls for grading and limits all review and learning requests. Correctable tool or question-validation errors return feedback to Pi; they never increase an explicit cap or switch providers. `timeoutSeconds` still bounds the whole investigation, so unlimited calls do not mean unlimited execution time. `maxContextBytes` caps serialized review context—prompts, tools, and schemas—at 100,000 bytes by default. Pi compacts earlier using an estimated context threshold; review context that still exceeds the cap is rejected before a model call. Transport metadata is outside this count. The cap does not apply to the whole Git diff. `toolResultBytes` is an upper bound for each page (16,000 by default); pages are reduced to reserve context room for bounded batches of reads.
-- Your configured `maxOutputTokens` applies to every tier, without an additional hidden size-based cap. Set it with `sphinx config --max-output-tokens 8192` (allowed range: 512–16,384). OpenRouter counts hidden model reasoning within this output limit; a larger ceiling can avoid truncation and permits more billed output, without increasing the assessment's call limit. Codex/Claude receive concise-output instructions and local timeout/output-byte limits; their CLI interfaces do not provide an equivalent hard Sphinx token cap.
-- Small/medium changes request low reasoning effort; large changes request medium effort on supporting coding-agent CLIs.
+Context size, output tokens, and review time are always capped. Provider failures never retry automatically. For routing thresholds, model tables, pricing, and every limit, see [configuration and cost](docs/configuration.md).
 
-Explicit call caps bound requests; context and page limits bound evidence. These controls they are not a guaranteed dollar or subscription-token ceiling. Set provider-side spending limits for paid accounts.
-
-## Files Sphinx never reads
-
-Built-in exclusions apply recursively and cannot be undone by project negations:
-
-- `.env` and `.env.*`, including `.env.example`.
-- Common private key and keystore names (`*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.jks`, `*.keystore`, `id_rsa`, `id_ed25519`, and related SSH names).
-- Common credential files such as `.netrc`, `.npmrc`, `.pypirc`, `*credentials*.json`, `service-account*.json`, and `secrets.json` / `secrets.yaml` / `secrets.yml`.
-
-Repository setup creates `.sphinxignore` without overwriting an existing one. Edit it to add project exclusions, for example:
-
-```gitignore
-# Project-specific private or generated files
-internal/customer-exports/
-/config/production.json
-*.generated.ts
-dist/
-```
+Version 0.1 checks local commits and pushes only. It does not cover web merges, CI-required checks, or deployments. It cannot read binary file contents, and it tests understanding rather than auditing the code. The [evaluation results](eval/RESULTS.md) record question quality, grading errors, and costs on synthetic changes. They do not certify arbitrary repositories.
 
-The supported syntax is `*`, `**`, `?`, root `/`, directory suffix `/`, comments beginning with `#`, and local `!` negations. Escape a leading `#` or `!` with `\`. This is a small gitignore-like parser, not the full Git pattern language.
+## Commands
 
-Machine-wide patterns live in `~/.config/sphinx/ignore`. Project rules cannot undo global exclusions or the built-in sensitive-file rules. `.sphinxconfig` can add `exclude` patterns too. An ignored-only change requires no assessment.
-
-**Filtering happens before patch, line-count, and blob-content retrieval, including searches of unchanged files.** Ignored paths' contents are not read, persisted as evidence, or sent to an evaluator. Git may enumerate their names/object IDs to identify changes. Snapshot identity still binds the full commit/index, so a later ignored-file edit alongside an already assessed change can invalidate the previous record. Uncommitted working files are not used as code evidence; pre-commit pins indexed object IDs, and pre-push reads Git objects. The separately supplied `.sphinxcontext.md` is read from the current project directory and its hash binds the assessment.
-
-Ignore rules match paths. They do not detect a secret embedded in an otherwise included source file. Add sensitive project-specific paths before running an assessment. Ignore policy symlinks are rejected rather than followed. Sphinx does not automatically apply `.gitignore` to already tracked files.
-
-## Configuration
-
-Global settings are stored at `~/.config/sphinx/config.json`. `SPHINX_HOME` relocates all Sphinx settings, credentials, and assessment state. `sphinx config` shows effective settings and configuration paths; `--preset`, `--small`, `--medium`, and `--large` change your machine-wide reviewer routes. Route changes invalidate prepared questions and completion records under the previous assessment policy. For a complete global example using the explicitly paid Haiku preset, see [examples/config.json](examples/config.json).
-
-Question depth controls coverage within the change-tier ceilings above:
-
-- `relaxed`: observable behavior and the most consequential edge case.
-- `standard`: behavior, failure modes, and relevant system interactions.
-- `thorough`: also consider supported rollout, rollback, and compatibility assumptions.
-
-All depths ask one question for a small change. Model routes remain separate: choosing a stronger evaluator does not increase the question count.
-
-Repository policy uses JSON in `.sphinxconfig`. Start with `sphinx init` or [.sphinxconfig.example](.sphinxconfig.example):
-
-```json
-{
-  "version": 1,
-  "events": ["pre-push"],
-  "branches": ["main", "release/*"],
-  "level": "standard",
-  "mode": "block",
-  "exclude": ["vendor/**"]
-}
-```
-
-Supported repository overrides are `enabled`, `level`, `events`, `branches`, `remotes`, `exclude`, and `backgroundPreparation`, with `version: 1`. A repository cannot redirect source to another provider, supply credentials, or raise your usage budget. Repository excludes add to global excludes. `enabled: false` disables Sphinx for that repository. Existing `.sphinx.json` files remain supported when `.sphinxconfig` is absent.
-
-For commit checkpoints, enable `pre-commit` and run `sphinx check --staged`. Push policies match the **destination** branch, not the name of the local branch. For a manual push check, `--remote` and `--branch` select the destination; otherwise Sphinx uses the upstream. Actual pending push snapshots take precedence when resuming. Multiple destination refs are assessed separately. Tag-only pushes and deletions do not trigger v0.1 checks.
-
-## Uninstall
-
-```sh
-sphinx uninstall --repo   # Remove an explicit repository integration, if present
-sphinx uninstall         # Remove user-level Git/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 user edits are preserved and reported. Global uninstall leaves explicit repository installations in place, with a warning; remove those before removing the executable. Configuration, credentials, and assessment state remain in `SPHINX_HOME` for you to keep or delete.
-
-## Scope and limitations
+| Command | Use it to |
+| --- | --- |
+| `install` | Set up machine-wide Git hooks and agent integrations |
+| `init` | Create this repository's policy, ignore, and context files |
+| `doctor` | Check hook and integration coverage |
+| `status` | Show this repository's policy, pending checks, and recent skips |
+| `check` | Start or resume a check in the terminal (`--staged` for commits) |
+| `pending` | List unfinished checks |
+| `yolo` | Toggle skipping checks |
+| `config` | Change reviewer models and limits |
+| `auth` | Save your OpenRouter key or an OpenAI-compatible endpoint |
+| `prepare` | Schedule background preparation (`--retry` after a failure) |
+| `activate` | Open configured coding agents without reinstalling |
+| `uninstall` | Remove Sphinx integrations, keeping unrelated settings |
 
-Sphinx is a voluntary practice for retaining understanding. A local user or agent can bypass hooks, change state, or answer with outside help. Completion is not proof of human authorship or unaided understanding, and an LLM examiner can be wrong.
+Each command explains itself with `sphinx <command> --help`. `--json` gives machine-readable output, and `NO_COLOR=1` turns off color.
 
-This first version handles local Git commit/push checkpoints. Web merges, CI-required checks, deployment gates, signed remote attestations, automatic new-agent discovery after installation, and native Windows support are future work. Run `sphinx install` again to upgrade an existing installation with preparation hooks, or after adding a supported agent. Binary contents are not available as textual evidence. Missing remote history needs a `git fetch` before assessment. A first push compares against an empty tree; the reviewer investigates relevant parts through its tools, subject to its budgets. A comprehension assessment is not an exhaustive code audit.
+## Reference
 
-The [live evaluation results](eval/RESULTS.md) record question quality, grading, costs, and observed failures on synthetic changes. They do not certify arbitrary repositories or every supported client version. See [CONTRIBUTING.md](CONTRIBUTING.md). The automated suite uses fixture evaluators and mock MCP clients, including an end-to-end Git-to-questionnaire workflow; it makes no paid or live inference requests.
+- [Configuration and cost](docs/configuration.md): reviewer models, OpenRouter, pricing, routing, limits, `.sphinxconfig`, `.sphinxignore`, project context, and background preparation.
+- [Integrations and troubleshooting](docs/integrations.md): Codex, Claude Code, Pi, Cursor, OpenCode, fallback forms, SSH, existing hooks, the JSON protocol, and uninstalling.
+- [Architecture](docs/architecture.md): the checkpoint sequence, the reviewer and its evidence, compaction, and state.
+- [Evaluation](eval/README.md) and [results](eval/RESULTS.md).
 
 ## Development
 
@@ -345,10 +181,7 @@ npm ci
 npm test
 npm run eval -- --out /tmp/sphinx-eval.json
 node bin/sphinx.js --help
+npm install -g .   # use this checkout as the installed sphinx
 ```
 
-The reviewer uses `@earendil-works/pi-coding-agent` 1.2.0. Install the locked dependencies with `npm ci` before development. Tests use Node's test runner, real temporary Git repositories, isolated integration homes, and fixture model backends. Never run installer tests against a real home directory or Git configuration.
-
-The [evaluation runner](eval/README.md) includes committed Git fixtures, executable behavior oracles, question-quality checks, and known correct, incorrect, and invalid-question grading probes. Its default mode makes no model requests. Explicit live runs accept request/cost limits and save synthetic questions, evidence, grading results, and failure traces for inspection.
-
-See [docs/architecture.md](docs/architecture.md) for module boundaries and assessment state. MIT licensed.
+Tests use Node's test runner, real temporary Git repositories, isolated homes, and fixture model backends. The suite makes no live model requests. Never run installer tests against a real home directory or Git configuration. See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.

package/docs/architecture.md

@@ -25,6 +25,15 @@ flowchart LR
   Q -->|unavailable| H[Native or manual fallback]
 ```
 
+## Checkpoint sequence
+
+1. Git supplies the exact source and destination commits. Sphinx applies branch/event policy and filters paths before reading contents.
+2. If the exact change already passed, the operation continues. Otherwise the hook saves a pending checkpoint and keeps the original Git process waiting.
+3. The hook serves a private questionnaire on loopback and prints its URL. Git's stdin and the coding agent's shell are never used for questionnaire input.
+4. Sphinx reuses matching prepared questions, waits for an in-progress review, or starts a fresh reviewer. The reviewer reads relevant diffs and follows related source and tests before committing questions, private answer keys, and supporting evidence. A separate model request audits the questions against that evidence before display.
+5. Correct answers clear concepts. An incorrect answer gets an explanation and replaces that concept's question with a different transfer scenario, which receives its own source audit without the human answer or grading conversation. Ambiguity or evaluator failure never creates a completion record.
+6. Sphinx revalidates every original snapshot and completion record, then returns control to the same Git process without replaying its command. Completion is bound to the exact repository, commits/index, destination, ignore policy, project context, assessment policy, and expiry.
+
 ## Modules
 
 | Module | Responsibility |
@@ -46,6 +55,7 @@ flowchart LR
 | `presentations.js` | Session-bound queues and hook-owned presentation markers, without code or answers |
 | `git-gate.js` | Waiting Git gate, exact snapshot/receipt revalidation, batch ownership, and fallback |
 | `browser-interview.js`, `browser-page.js` | Loopback human questionnaire, background browser opening, recovery, cancellation, and batch reuse |
+| `change-view.js` | Read-only questionnaire display of the frozen checkpoint comparison: file list, per-file stats, diffs, and verified question evidence ranges |
 | `git-interview.js` | Explicit separate-terminal transport retained for compatibility |
 | `native-check.js` | Direct human-form assessment loop, queue claims, cancellation, and summary-only results |
 | `mcp.js` | Bounded stdio JSON-RPC transport, form elicitation, and lifecycle tool responses |
@@ -88,6 +98,8 @@ Advertised form support does not guarantee the client will display a request: cl
 
 A paused or dismissed presentation is consumed while its assessment remains pending. Unrelated shell commands therefore do not reopen it. A new Git attempt queues presentation again and resumes existing progress. Session identifiers let the integration find requests from commands that change directories or use `git -C`; Codex supplies its thread ID, and the Claude SessionStart hook appends a Sphinx session tag through `CLAUDE_ENV_FILE`. Outside native hosts, `sphinx check` provides the terminal interview using the same assessment state.
 
+The browser questionnaire shows the change it is asking about. A sticky header names the repository, Git operation, destination, exact comparison, file and line totals, and progress, labeled as checkpoint changes rather than a whole pull request. Beside the question, a file list (all changed files or only those relevant to the question) and a unified diff are rendered from the checkpoint's recorded blob IDs: the push base and head, or the pinned index entries of a commit checkpoint. Later commits and working-tree edits cannot change them. Renames are detected for display only; the reviewer still uses `--no-renames`. Binary, symlink, submodule, mode-only, empty, non-UTF-8, and oversized files show an explicit state and never receive invented line counts. Long diffs are truncated with a visible count, and excluded files appear only as a count. Question evidence lists the paths the question cites. Line ranges appear only when a retained reviewer observation (read_file, read_diff page, or search match) matches the checkpoint's blob IDs and, for diff pages, its exact bytes at the recorded offset. Model-written evidence reasons are not shown because they can reveal the answer. Display updates never rotate the actionable revision, and browsing never touches the draft answer or the current question.
+
 Pi's development-client integration is a separate local extension from the embedded reviewer runtime. It observes built-in `bash` and `powershell` results, then calls the same questionnaire controller for queued Git requests. `ctx.ui.select` presents Answer, Learn, Dispute, and Pause; `ctx.ui.input` collects the person's response. Only a fixed status message is appended to the shell result. Questions, feedback, and human answers never enter the coding transcript. Interactive or dialog-capable RPC mode is required; noninteractive modes preserve pending work for a terminal check. Pi's built-in shell session ID associates requests across `cd` and `git -C`.
 
 Cursor and OpenCode adapters inspect queued fallback presentation metadata after shell tools and use the same local browser questionnaire. The client hook waits for a status-only result. This fallback cannot resume Git after it has exited; guidance permits a new invocation only after checking that the original operation failed at Sphinx, and forbids repeating waiting or successful operations. Questions, feedback, answer keys, human responses, and browser URLs never pass through the adapter's returned tool result. Cursor receives a context note; OpenCode receives a shell-result note and a TUI toast when available. Session environment tags support cross-directory routing. Cursor user hooks apply only to local sessions.
@@ -106,6 +118,10 @@ Every request includes bounded project context (maximum 16,000 bytes). Context i
 
 Before Pi validates a `finish_review` call, Sphinx normalizes two lossless representation differences: a valid JSON-object string in `assessment` becomes an object, and `summary` or `evidenceIds` nested inside it moves to the envelope only when that outer field is absent. Questions, keys and citations are never rewritten by this step. Duplicate metadata, unknown properties and malformed JSON remain subject to strict rejection. The original native provider message and opaque continuation are retained separately from Pi's normalized arguments. Recorded response replays cover both native tool calls and structured CLI transports without spending another inference request.
 
+The reviewer requests further diff pages, source ranges, file listings, and literal searches through Sphinx's tools. It can inspect unchanged callers, dependencies, and tests at the same pinned revision. File names are navigation hints; only inspected source can support a question. Sphinx enforces ignores and tool access locally and never grants an unrestricted shell or the developer's working files. Large patches are inspected incrementally rather than bundled into one prompt.
+
+Pi session entries, the evidence archive, and an assessment awaiting its independent audit are saved privately under the checkpoint lock, so an interrupted review resumes without repeating the investigation. After compaction, the reviewer can recover archived observations with `read_evidence`.
+
 Pi's [native compaction](https://pi.dev/docs/latest/compaction) summarizes older conversation history and rebuilds the active context. Sphinx separately archives exact observations with IDs, paths, revisions, and ranges under a fixed byte budget. Compaction can shorten Pi's transcript without changing this archive; a model summary cannot replace code evidence. Final questions must cite inspected paths backed by archived observations. Grading receives the question's selected original evidence, rubric, project context, and verbatim human answer.
 
 New assessments separate their minimal acceptance criteria—one prediction and its causal reason—from the longer answer key and explanation. The independent audit checks both against source and aligns the visible question with the minimum criteria. A question that bundles extra checks must be narrowed, not given hidden requirements. Grading still rejects an unsupported key, but explanatory implementation details do not become additional requirements for the human. Older saved questions remain readable and are assessed against their visible behavioral question. All acceptance criteria and explanatory keys stay private.