better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/providers.md

@@ -0,0 +1,229 @@
+<!--
+source: https://omp.sh/docs/providers
+fetched: 2026-09-06
+-->
+
+# Providers
+
+> Choose an account, API-key, local, or custom model route; authenticate it; and select a model that omp can actually use.
+
+## Choose the route that fits
+
+A provider is the account or backend, such as `anthropic`, `openai-codex`, or `ollama`. A model is selected as `provider/model-id`.
+
+For most people, the shortest path is:
+
+1. Start `omp`.
+2. Run `/model`.
+3. Choose a provider. Providers without credentials appear as **not configured**; select one and press Enter to start its login flow when available.
+4. Choose a model after login finishes.
+
+Use this table if you already know how you want to authenticate:
+
+| Route | Best for | First action |
+| --- | --- | --- |
+| OAuth or account sign-in | Browser, device-code, and hosted-account flows | In omp, run `/login`, or jump to one provider with `/login openai-codex` |
+| Coding subscription | ChatGPT Plus/Pro, Claude Pro/Max, Copilot, and other supported plans | Use the plan's provider ID, not the vendor's API provider ID |
+| API key | Usage-based APIs, CI, and non-interactive shells | Export the provider's environment variable, then start omp |
+| Local engine | Private or offline-capable inference with Ollama, llama.cpp, or LM Studio | Start the engine; omp discovers it without a login |
+| Custom endpoint | Team gateways, self-hosted APIs, and providers not built in | Add the endpoint to `~/.omp/agent/models.yml` |
+
+Account subscriptions and developer APIs are often separate products. For example, ChatGPT credentials use `openai-codex`; `openai` expects `OPENAI_API_KEY`. Google and xAI have similar splits. See [Provider-specific caveats](#provider-specific-caveats) before guessing an ID.
+
+## Get one route working
+
+### Sign in with OAuth or a subscription
+
+Inside an interactive session:
+
+```text
+/login openai-codex
+```
+
+Follow the browser, device-code, or paste-code instructions shown by omp. For a remote terminal, the flow may ask you to paste the final redirect URL or code back as `/login <value>`. When a provider supports several accounts or workspaces, run `/login <provider>` again to add another one; omp can rotate managed accounts.
+
+Then verify and select a concrete model:
+
+```sh
+omp models openai-codex
+omp --model openai-codex/gpt-5.5
+```
+
+`omp models <provider>` prints only models currently available to this installation. Copy a selector from that output if the example model has changed. In an existing session, run `/model` or `/model provider/model-id` instead.
+
+Use `/logout` to choose credentials to remove, or `/logout <provider>` to open that provider directly.
+
+### Use an API key
+
+For a one-off launch or CI job, put the key in the process environment:
+
+```sh
+OPENAI_API_KEY=sk-... omp --model openai/gpt-5.5
+```
+
+For an interactive setup, many key-based providers also appear in `/login`; omp opens the provider's key page, asks for the key, validates it, and stores the credential. Providers without a login entry use their environment variable.
+
+To persist an environment variable without adding it to shell startup files, omp loads `.env` files. An already-exported process value wins, followed by:
+
+1. `<current-directory>/.env`
+2. `~/.omp/agent/.env`
+3. `~/.omp/.env`
+4. `~/.env`
+
+Do not commit a project `.env` containing secrets. See [Environment variables](/docs/env) for every provider key name and the complete `.env` rules.
+
+Verify the route before starting a long task:
+
+```sh
+omp models openai
+omp --model openai/gpt-5.5 "Reply with the model provider and model ID you are using."
+```
+
+### Use a local engine
+
+omp probes these local providers automatically:
+
+| Provider ID | Default endpoint | Override |
+| --- | --- | --- |
+| `ollama` | `http://127.0.0.1:11434` | `OLLAMA_BASE_URL`, then `OLLAMA_HOST` |
+| `llama.cpp` | `http://127.0.0.1:8080` | `LLAMA_CPP_BASE_URL` |
+| `lm-studio` | `http://127.0.0.1:1234/v1` | `LM_STUDIO_BASE_URL` |
+
+Start the engine and load a model there first. No login or config file is required for the default keyless endpoints. Then ask omp what it found:
+
+```sh
+omp models ollama
+```
+
+Copy a selector from the output:
+
+```sh
+omp --model ollama/model-id
+```
+
+If an engine is on another machine, set its base-URL environment variable. An explicit provider with the same ID in `models.yml` replaces automatic discovery. `vllm` is also a built-in provider route, but configure or authenticate it when it is not exposed as an unauthenticated local endpoint.
+
+### Add a custom provider
+
+Use `~/.omp/agent/models.yml` for an OpenAI-compatible, Anthropic-compatible, or other supported public endpoint. This minimal example reads the key from `MY_GATEWAY_API_KEY`:
+
+```yaml
+providers:
+  my-gateway:
+    baseUrl: https://gateway.example.com/v1
+    api: openai-completions
+    apiKey: MY_GATEWAY_API_KEY
+    models:
+      - id: fast-chat
+        name: Fast Chat
+        contextWindow: 128000
+        maxTokens: 8192
+```
+
+Set the key and verify the loaded entry:
+
+```sh
+export MY_GATEWAY_API_KEY=...
+omp models my-gateway
+omp --model my-gateway/fast-chat
+```
+
+`apiKey` is resolved as an environment-variable name first and otherwise as literal text. Prefer an environment-variable name so the secret stays out of the file. Use `auth: none` instead of `apiKey` for a genuinely keyless endpoint.
+
+See [Custom models & providers](/docs/custom-models) for other wire APIs, model discovery, headers, secret commands, compatibility options, and model overrides.
+
+## How models become available
+
+At startup, omp assembles the model registry in this order:
+
+1. bundled providers and known models;
+2. provider overrides and custom models from `~/.omp/agent/models.yml` or `models.yaml`;
+3. cached or live discovery for supported providers and local engines;
+4. providers and models registered by loaded extensions.
+
+A custom model with the same `provider` and `id` replaces the bundled entry. Runtime discovery can update the models exposed by a provider; model overrides are reapplied afterward.
+
+A model is selectable only when:
+
+- its provider is not in the effective `disabledProviders` list; and
+- the provider is keyless or has a credential omp can resolve.
+
+Useful checks:
+
+```sh
+omp models                    # all currently available models
+omp models find sonnet        # search provider, ID, selector, or display name
+omp models refresh            # force fresh online discovery, then list
+```
+
+Inside the TUI, `/model` includes available models and shows catalog providers without credentials as locked. Selecting a login-capable locked provider starts its setup. Disabled providers are omitted.
+
+For initial selection, an explicit `--model` wins. Without it, omp considers the active model scope, a saved default, known provider defaults, and finally the first available model. Prefer an exact `provider/model-id` when the same model ID exists through several routes; bare IDs and fuzzy `--model` patterns depend on the available catalog and configured provider order. See [Model roles](/docs/roles) for persistent defaults and task-specific model choices.
+
+## Credential precedence
+
+When several credentials exist for the same provider, omp uses the first applicable source:
+
+1. runtime `--api-key` for this process;
+2. `models.yml``providers.<id>.apiKey`;
+3. stored OAuth credentials, refreshed when needed;
+4. an API key stored by `/login`;
+5. the provider environment variable, including values loaded from `.env`;
+6. another stored API key, such as a broker-migrated key;
+7. a custom-provider fallback resolver.
+
+This means a stored OAuth login normally wins over `ANTHROPIC_API_KEY` in the environment, while a key explicitly pinned in `models.yml` wins over OAuth. Keep provider IDs separate when you want both account and API access available.
+
+Local credentials normally live in `~/.omp/agent/agent.db`. With an auth broker configured, login, logout, refresh, and credential reads use the remote store instead. See [Secrets and auth](/docs/secrets) for storage, multiple accounts, the auth broker, and the provider-compatible auth gateway.
+
+## Current provider matrix
+
+The live catalog is authoritative: run `omp models` after authenticating. The groups below cover the current built-in model-provider IDs and the normal setup route.
+
+| Route | Provider IDs | Normal setup |
+| --- | --- | --- |
+| Major model APIs | `anthropic`, `openai`, `google`, `groq`, `mistral`, `xai`, `deepseek`, `openrouter` | API key; `anthropic`, `xai`, `deepseek`, and `openrouter` also offer guided `/login` setup |
+| Account and subscription access | `openai-codex`, `github-copilot`, `cursor`, `google-antigravity`, `google-gemini-cli`, `kimi-code`, `xai-oauth`, `devin`, `firepass`, `ollama-cloud` | `/login <provider>` |
+| Coding plans and regional portals | `aiand`, `alibaba-coding-plan`, `alibaba-token-plan`, `minimax-code`, `minimax-code-cn`, `qwen-portal`, `umans`, `xiaomi`, `xiaomi-token-plan-ams`, `xiaomi-token-plan-cn`, `xiaomi-token-plan-sgp`, `zai`, `zhipu-coding-plan` | `/login <provider>`; the flow either signs in or validates a pasted plan key |
+| Git-hosted assistants | `gitlab-duo`, `gitlab-duo-agent` | `/login <provider>` or `GITLAB_TOKEN`; GitHub Copilot is listed with subscriptions above |
+| Hosted inference APIs | `aimlapi`, `baseten`, `cerebras`, `coreweave`, `fireworks`, `gmi-cloud`, `huggingface`, `meta`, `minimax`, `moonshot`, `nanogpt`, `nvidia`, `novita`, `qianfan`, `sakana`, `siliconflow`, `siliconflow-cn`, `synthetic`, `together`, `venice`, `wafer-serverless` | Provider API key; most also support guided `/login` key entry |
+| Gateways and aggregators | `cloudflare-ai-gateway`, `kilo`, `litellm`, `opencode-go`, `opencode-zen`, `vercel-ai-gateway`, `zenmux` | Gateway key and, where required, a base URL or account/team setting |
+| Cloud identity routes | `amazon-bedrock`, `bedrock-mantle`, `azure`, `google-vertex` | Cloud-specific credentials and region/project/endpoint configuration |
+| Local and self-hosted engines | `ollama`, `llama.cpp`, `lm-studio`, `vllm` | Start the endpoint; authenticate only if the endpoint requires it |
+
+Exact environment-variable names are intentionally centralized in [Environment variables](/docs/env), because some providers accept more than one credential source.
+
+## Provider-specific caveats
+
+| Provider or family | What to know |
+| --- | --- |
+| OpenAI | `openai-codex` is ChatGPT subscription access. `openai` is the developer API and uses `OPENAI_API_KEY`. For a headless Codex sign-in, choose `openai-codex-device`; it stores the result for `openai-codex`. |
+| Anthropic | The `anthropic` route supports Claude Pro/Max OAuth and API keys. Repeating login can add separate organizations or subscription workspaces. A pinned `models.yml` key overrides stored OAuth. Foundry deployments have separate enterprise credential settings. |
+| Google | `google` uses `GEMINI_API_KEY`; `google-gemini-cli` and `google-antigravity` use account sign-in; `google-vertex` uses Google Cloud project/location credentials. These IDs are not interchangeable. |
+| xAI | `xai` is the paid API-key route. `xai-oauth` is the SuperGrok or X Premium+ account route. |
+| GitHub Copilot | Login uses GitHub's device flow. Enterprise users must authenticate against the intended Enterprise host; that host and API endpoint are kept with the credential. |
+| GitLab Duo | `gitlab-duo` is the non-agentic route; `gitlab-duo-agent` is the Duo Agent route. Both can use `GITLAB_TOKEN`, but their model catalogs and request paths differ. |
+| Z.AI | `/login zai` validates a coding-plan API key. The separate sign-in choice `zai-coding-plan` stores its minted credential under the model provider `zai`, so model selectors still start with `zai/`. |
+| Azure OpenAI | A key alone is not enough if omp cannot infer your deployment endpoint. Configure the Azure endpoint/deployment route described in [Custom models & providers](/docs/custom-models). |
+| Google Vertex | Application Default Credentials require a project and location. A catalog entry may exist before cloud identity is usable, so verify with `omp models google-vertex`. |
+| Amazon Bedrock | Bedrock uses the AWS credential chain and region rather than a normal bearer key. `bedrock-mantle` is a separate bearer-token route. |
+| Gateways | Use the gateway's provider ID when it has built-in discovery. For a private gateway or nonstandard URL, use `models.yml`; its configured `apiKey` deliberately overrides any stored upstream OAuth token. |
+| Local engines | Automatic discovery is skipped when the same provider ID is explicitly configured or disabled. The engine must already be running and expose at least one model. |
+
+## Troubleshooting
+
+**The provider is locked or absent from `omp models`.** Check its credential, then check whether it is disabled:
+
+```sh
+omp config get disabledProviders
+```
+
+A disabled provider stays unavailable even with valid credentials. Project settings can replace the global `disabledProviders` array; see [Settings](/docs/settings).
+
+**Login succeeded but the model list is stale.** Run `omp models refresh`, then list the provider again. Dynamic catalogs may differ by account, workspace, region, or plan.
+
+**The wrong account or key is used.** Compare your sources with the credential order above. Look for a pinned `models.yml` key, a stored OAuth account, an exported variable, and the four `.env` locations. Remove a managed account with `/logout <provider>`.
+
+**A custom provider is skipped.** Run `omp models`; validation errors are printed before the list. A provider with explicit models needs `baseUrl`, an `api` value, and `apiKey` unless it declares `auth: none`.
+
+**A local provider returns no models.** Confirm the engine is listening at the effective base URL and has a model loaded. Then run `omp models refresh`. An empty or unreachable local endpoint remains unavailable.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/quickstart.md

@@ -0,0 +1,117 @@
+<!--
+source: https://omp.sh/docs/quickstart
+fetched: 2026-09-06
+-->
+
+# Quickstart
+
+> Install omp, choose a provider and model, and complete your first coding task.
+
+omp works inside your existing project: describe a change in plain language, let the agent inspect and edit the code, then review the result and continue the conversation. This guide takes you from installation to a resumable first session.
+
+## 1. Install omp
+
+On macOS or Linux:
+
+```sh
+curl -fsSL https://omp.sh/install | sh
+```
+
+On Windows, run this in PowerShell:
+
+```powershell
+irm https://omp.sh/install.ps1 | iex
+```
+
+Confirm that the executable is available:
+
+```sh
+omp --version
+```
+
+If your shell cannot find `omp`, follow the PATH instruction printed by the installer, then open a new terminal and try again.
+
+## 2. Open your project
+
+Change into the project you want omp to work on. The directory where you launch omp becomes the project root for the session.
+
+```sh
+cd ~/code/my-project
+```
+
+Replace `~/code/my-project` with your project’s path.
+
+If you use an API key, export it in this terminal before launch. For example:
+
+```sh
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+If you use a provider subscription with browser sign-in, skip that command; the first-run setup will sign you in.
+
+Now launch the interactive app:
+
+```sh
+omp
+```
+
+## 3. Sign in and choose a model
+
+The first launch opens a setup wizard.
+
+1. On **Set up your providers**, keep the **Sign in** tab selected, choose your provider, and press <kbd>Enter</kbd>. Complete the browser login, then return to the terminal. You can sign in to more than one provider.
+2. If you exported an API key instead, it is already available to omp; press <kbd>Esc</kbd> to leave the provider step.
+3. Press <kbd>Esc</kbd> when you are done connecting providers.
+4. On **Choose your default model**, type to search, highlight a model from the provider you configured, and press <kbd>Enter</kbd>. omp saves this choice for new sessions.
+5. Finish the remaining terminal appearance prompts. They preview each choice before you save it.
+
+Later launches go directly to the prompt. OAuth users can reopen sign-in with `/login`; use `/model` to change the current session’s model.
+
+## 4. Give omp a coding task
+
+At the prompt, type a concrete outcome in ordinary language. This example works as a first tour of an unfamiliar project:
+
+```text
+Inspect this project for one small bug or inconsistency that can be verified locally. Explain what you found, make the smallest safe fix, and run the most relevant check.
+```
+
+Press <kbd>Enter</kbd>. omp will inspect the project, show its actions as tool cards, edit files when needed, and stream its response. Press <kbd>Ctrl</kbd>+<kbd>O</kbd> to expand or collapse full tool output.
+
+## 5. Review and continue
+
+Read the final summary and the reported check result. Ask for a focused review without leaving the session:
+
+```text
+Show me the diff and explain each changed file. Do not make more changes.
+```
+
+Then continue with a follow-up, just as you would with a teammate:
+
+```text
+Looks good. Run the relevant check once more and summarize any remaining risk.
+```
+
+If the agent is heading in the wrong direction during a turn, press <kbd>Esc</kbd> to interrupt it, then clarify the request.
+
+## 6. Exit and resume
+
+Press <kbd>Ctrl</kbd>+<kbd>D</kbd> or enter `/exit` to leave. omp saves the session automatically.
+
+To continue the most recent session for this project, return to the same project directory and run:
+
+```sh
+omp --continue
+```
+
+The conversation and selected model reopen in the same project so you can send the next message. Run `omp --resume` instead when you want to choose from recent sessions.
+
+## Optional next steps
+
+Your first session needs no configuration file. When you want to customize omp, continue with:
+
+- [Providers](/docs/providers) for API keys, OAuth providers, and authentication troubleshooting.
+- [Custom models & providers](/docs/custom-models) when the built-in catalog is not enough.
+- [Settings](/docs/settings) for user and project configuration.
+- [Using omp](/docs/using) for the editor, message queue, and everyday workflow.
+- [Sessions](/docs/sessions) for resume, fork, and session history.
+- [Keybindings](/docs/keybindings) for all default controls.

package/docs/80_upstream-docs-and-skills/dsh-dev-skill/pi-and-omp/omp/review.md

@@ -0,0 +1,248 @@
+<!--
+source: https://omp.sh/docs/review
+fetched: 2026-09-06
+-->
+
+# Code review
+
+> Run a focused, read-only review of a branch, working copy, commit, or GitHub pull request before you merge or ask omp to make fixes.
+
+## Review before you change
+
+Use `/review` when a change is ready for a deliberate correctness pass: before opening or merging a pull request, after a risky refactor, or when staged work deserves a second look. The command identifies a concrete diff, removes common generated noise, and reports only evidence-backed problems introduced by that diff.
+
+The shortest successful flow is:
+
+```text
+You: /review
+omp: Review Mode
+     1. Review against a base branch (PR Style)
+     2. Review uncommitted changes
+     3. Review a specific commit
+     4. Custom review instructions
+You: 2. Review uncommitted changes
+```
+
+Choose **uncommitted changes** while you are still working. In a Git repository, this reviews staged and unstaged diffs together. In a Jujutsu repository, it reviews the current JJ working-copy diff. omp then returns findings and an overall verdict; it does not edit the files.
+
+A review is intentionally stricter than an open-ended prompt such as `review this`. `/review` first establishes an exact VCS or pull-request scope and applies a consistent finding contract. A finding must describe a provable, actionable, unintended problem introduced by the patch and point to changed lines. The review follows changed values across module boundaries to their receiving handlers and ignores ordinary style preferences, documentation nits, and pre-existing defects. An open-ended prompt remains useful when you want broader architectural advice, a design critique, or edits, but its scope and output are whatever you ask for rather than this fixed patch-review workflow.
+
+## Choose the right review mode
+
+### Compare the current branch with a base branch
+
+Choose **Review against a base branch (PR Style)** for the local equivalent of reviewing a pull request:
+
+```text
+You: /review
+You: 1. Review against a base branch (PR Style)
+omp: Select base branch to compare against
+You: main
+```
+
+omp lists local and remote Git branches, determines the current branch, and reviews the three-dot diff from the selected base to the current branch. In other words, the scope starts at their merge base and includes the changes introduced on your branch. This is usually the right mode immediately before opening a PR.
+
+If the feature branch contains unrelated work, select a more appropriate base or review a specific commit instead. This chooser is Git-based; use the working-copy mode for current JJ changes.
+
+### Review staged and unstaged work
+
+Choose **Review uncommitted changes** for a pre-commit check:
+
+```text
+You: /review
+You: 2. Review uncommitted changes
+```
+
+For Git, omp combines both of these scopes:
+
+- unstaged changes in the working tree;
+- staged changes in the index.
+
+For Jujutsu, omp detects the repository and uses the JJ working-copy diff instead of Git status or Git diff. In either case, review findings refer to the actual changed files and lines. New untracked Git files are not present in a Git diff; add or stage them before reviewing if they belong in the scope.
+
+### Review one commit
+
+Choose **Review a specific commit** when you want to isolate one completed unit of work:
+
+```text
+You: /review
+You: 3. Review a specific commit
+omp: Select commit to review
+You: a13f62c Fix token refresh race
+```
+
+The chooser shows the 20 most recent Git commits. omp reviews the selected commit's patch, not all changes between that commit and the current branch. This is useful for checking a fix before cherry-picking it or separating a suspicious commit from a larger branch.
+
+### Review a GitHub pull request
+
+When a GitHub PR URL or `pr://` reference appeared recently in the active conversation branch, `/review` can add up to three choices above the numbered modes:
+
+```text
+You: Please look at https://github.com/acme/widgets/pull/418
+You: /review
+omp: Review Mode
+     Review PR acme/widgets#418 from conversation
+     1. Review against a base branch (PR Style)
+     ...
+You: Review PR acme/widgets#418 from conversation
+```
+
+The most recently mentioned PR appears first, duplicate references are collapsed, and references from abandoned conversation branches do not leak into the chooser.
+
+For a faster and less ambiguous flow, put an explicit PR URL on the command line. This bypasses the chooser:
+
+```text
+/review https://github.com/acme/widgets/pull/418
+```
+
+You can add a focus after the URL:
+
+```text
+/review https://github.com/acme/widgets/pull/418 focus on authorization boundaries
+```
+
+The standard GitHub URL may include `/files`, `/commits`, a query string, or an anchor. Fully qualified internal references also work:
+
+```text
+/review pr://acme/widgets/418/diff/all focus on migration safety
+```
+
+For a PR review, omp fetches the PR diff and keeps the review tied to that fetched content. It does not silently substitute files from the local checkout, which may be on a different revision. An issue URL, commit URL, another host, or an incomplete reference such as `pr://418` is not treated as a PR target; without an interactive UI it becomes ordinary focus text instead.
+
+PR review requires the GitHub CLI, `gh`, on `PATH`, authenticated with an account that can read the repository. Run `gh auth login` if necessary. A private PR also requires access to that private repository. You may provide `owner/repository` in the URL even when the current directory is not that repository.
+
+### Supply a custom focus
+
+Choose **Custom review instructions** when the standard working-copy scope is right but a particular risk deserves extra attention:
+
+```text
+You: /review
+You: 4. Custom review instructions
+omp: Enter custom review instructions
+You: Review the following:
+
+     Trace every new queue state through serialization, restart recovery,
+     and the consumer switch. Ignore naming unless it hides a correctness bug.
+```
+
+If the repository has uncommitted Git or JJ changes, omp includes that diff and applies your instructions to it. If no working-copy diff is available, the instructions become the review request, so name the files, commit, behavior, or other scope explicitly.
+
+You can also put focus words after `/review`:
+
+```text
+/review focus on cancellation and cleanup
+```
+
+In the interactive TUI, those words are carried into whichever standard mode you choose, and the separate custom-instructions choice is omitted. This is a convenient way to retain the normal VCS scope while emphasizing one concern.
+
+Good focus text names a failure boundary rather than asking for generic quality:
+
+```text
+/review focus on backward compatibility of the persisted session format
+/review focus on authorization checks after redirects
+/review focus on partial writes, retries, and idempotency
+```
+
+## How omp defines and scales the scope
+
+Before review, omp parses the unified diff into changed files and counts added and removed lines. It excludes common low-signal files from the review scope:
+
+- lock files such as `package-lock.json`, `Cargo.lock`, `poetry.lock`, and `flake.lock`;
+- minified files, generated files, snapshots, and source maps;
+- files under top-level `dist/`, `build/`, or `out/`, plus vendored dependencies;
+- images, fonts, PDFs, and common archives.
+
+The result reports excluded paths and reasons, so filtering is visible rather than silent. If every changed file is filtered, the command stops with **No reviewable files** instead of returning a misleading clean verdict. A file that merely happens to be named like generated output may need a custom, open-ended review if you intentionally want it inspected.
+
+Review breadth scales with the reviewable diff. The current concurrency heuristics are:
+
+| Reviewable change | Review breadth |
+| --- | --- |
+| Fewer than 100 changed lines, or at most 2 files | One focused pass |
+| Fewer than 500 changed lines | Up to 2 parallel slices |
+| Fewer than 2,000 changed lines | Up to 4 slices, roughly one per 3 files |
+| Fewer than 5,000 changed lines | Up to 8 slices, roughly one per 2 files |
+| 5,000 lines or more | Up to 16 slices, never more than the file count |
+
+Added and removed lines both count. Related implementation and test files remain part of the same coherent review area rather than being judged without context.
+
+For a diff of at most 20 reviewable files and 50,000 characters, the full diff is carried into the review. Above either limit, omp uses short per-file previews and has the review read the assigned diff sections directly. This reduces prompt noise without reducing the intended file scope. For local reviews, surrounding file context may also be read when needed. For GitHub PRs, context stays within the fetched PR diff rather than using local workspace files.
+
+These rules make large reviews tractable, not infallible. A huge mechanical change may still be better reviewed in several logical commits, while a tiny authentication change may justify a very specific custom focus.
+
+## Read the result
+
+A finding contains:
+
+- **Priority** — urgency and impact, from `P0` to `P3`.
+- **Confidence** — a value from `0.0` to `1.0` estimating how likely the reported bug is real.
+- **Title and explanation** — the discrete fix to make, the trigger condition, and the impact.
+- **File and line range** — a short range that overlaps the reviewed diff.
+
+| Priority | Meaning | Practical response |
+| --- | --- | --- |
+| `P0` | Universal release or operations blocker, such as data corruption or an authentication bypass. | Stop the release and investigate immediately. |
+| `P1` | High-impact defect that should be fixed in the next cycle. | Fix before merge unless you explicitly accept the risk. |
+| `P2` | Medium-impact edge case or correctness problem. | Plan and verify a fix; decide merge timing from your project policy. |
+| `P3` | Informational, low-impact improvement. | Treat as optional unless it reveals a project requirement. |
+
+Confidence is not severity. A `P0` at `0.55` describes a catastrophic claim with uncertain evidence; a `P2` at `0.98` describes a narrower problem supported by strong evidence. Verify both the trigger and the affected path before acting.
+
+The final verdict is **correct** or **incorrect**, followed by a short explanation and verdict confidence. **Correct** means no correctness bugs or blockers were established under this review contract; it does not certify style, documentation completeness, performance in every environment, or the absence of all possible defects. **Incorrect** means the review established at least one material correctness problem. Finding counts are also summarized by priority; **Findings: none** is not a substitute for your own domain-specific checks.
+
+## Turn findings into a deliberate follow-up
+
+`/review` is read-only. It does not apply suggestions, modify your working tree, run a fix, or merge a PR. That separation gives you a decision point.
+
+For each finding:
+
+1. Open the cited changed lines and reproduce the stated trigger against surrounding code.
+2. Decide whether the finding is valid and whether its priority matches your release policy.
+3. Ask omp for the precise action you want, referencing the finding rather than saying only “fix everything.”
+4. Run the relevant behavior or focused test, then review the resulting patch again if the fix was substantial.
+
+For example:
+
+```text
+The P1 finding in src/auth/refresh.ts is valid. Fix the refresh race without
+changing the public token API, run the focused auth test, and show me the result.
+```
+
+Or reject a finding explicitly:
+
+```text
+The P2 finding assumes retries can overlap, but this worker is single-flight by
+contract. Confirm that invariant from the implementation and leave the code unchanged.
+```
+
+This preserves your control over scope and avoids converting a mistaken or low-confidence observation into an automatic edit.
+
+## Headless use
+
+Without an interactive UI, `/review` cannot show the mode chooser. A plain command requests a focused review of recent code changes, and trailing words become its focus:
+
+```sh
+omp -p "/review focus on authentication regressions"
+```
+
+Use an explicit GitHub PR URL when automation needs a deterministic remote scope:
+
+```sh
+omp -p "/review https://github.com/acme/widgets/pull/418 focus on API compatibility"
+```
+
+An explicit valid PR URL is fetched directly in both interactive and headless use. Without one, headless mode does not offer base-branch or commit selection; make the surrounding prompt identify the intended recent changes, or run the interactive TUI when you need one of those choosers. Review output remains read-only, so a CI script must decide separately whether and how a verdict affects its exit or merge policy.
+
+## Troubleshooting
+
+- **No uncommitted changes found** — the Git working tree and index are clean, or the JJ working-copy diff is empty. Choose base-branch or commit mode if the work is already committed.
+- **No diff content found** — Git status noticed a change but staged and unstaged unified diffs were empty. A common cause is an untracked file; add or stage it, then rerun `/review`.
+- **No changes between *base* and *branch*** — confirm the selected base and current branch. The comparison is merge-base-based, so choosing the current branch or the wrong remote branch can produce an empty diff.
+- **No git branches found** — run omp inside the intended Git checkout and confirm it has branch refs. Detached `HEAD` can also make branch-oriented review confusing; use commit mode when that is the real scope.
+- **No commits found** — the directory is not a readable Git repository or has no history. Use working-copy or custom mode as appropriate.
+- **No reviewable files (all changes filtered out)** — every diff path matched a noise rule. This is not a clean review; use a custom open-ended prompt if those generated or binary artifacts genuinely need inspection.
+- **Failed to get diff / Failed to get commit** — check that the repository and selected revision still exist and that Git or JJ can read them. Rerun after resolving an in-progress VCS operation or invalid ref.
+- **Failed to fetch PR diff** — ensure `gh` is installed, run `gh auth login`, verify the account can view the repository and PR, and retry the explicit URL.
+- **PR … has no diff content available** — the PR may have no changes, the fetched diff may be unavailable, or GitHub may not expose patch text for its contents. Open the PR's Files changed view before treating this as a clean result.
+- **A recent PR is missing from the chooser** — only the three most recent distinct PR references on the active conversation branch are offered. Paste the full URL directly after `/review` to bypass detection.
+- **The wrong files were reviewed** — cancel and choose the scope again. Use base-branch mode for the whole feature branch, uncommitted mode for the current working copy, commit mode for one commit, or an explicit PR URL for remote changes.