one-code-extension 0.4.0 → 0.5.0

package/docs/guide/bring-your-claude-code-setup.md

@@ -7,6 +7,10 @@ existing setup works without changes. There's no import step and nothing
 to convert. Open a project that already has a `.claude/` directory, and One
 Code picks up each of the following as it is.
 
+That's the default, Claude-compatible mode. If you'd rather One Code ignore
+your Claude Code setup entirely, switch to independent mode. See
+[Run One Code on its own setup](#run-one-code-on-its-own-setup).
+
 ## Project instructions: CLAUDE.md
 
 One Code loads `CLAUDE.md` files and includes them in the model's context
@@ -15,17 +19,25 @@ exactly as Claude Code does: your global `~/.claude/CLAUDE.md`, then the
 directory, plus any `CLAUDE.local.md` beside them for private instructions.
 `@path` imports are expanded in place.
 
-If a directory has no `CLAUDE.md`, One Code uses its `AGENTS.md` instead, so
-a repository that standardized on `AGENTS.md` works too. A `CLAUDE.md` takes
-precedence over an `AGENTS.md` in the same directory.
+If the project has no `CLAUDE.md` or `CLAUDE.local.md` anywhere on that
+path, One Code loads its `AGENTS.md` files instead, in the same places, plus
+any `.claude/AGENTS.md`. So a repository that standardized on `AGENTS.md`
+works too. Once a `CLAUDE.md` exists, the `AGENTS.md` files are left out,
+the same rule Claude Code follows.
+
+Claude Code's `instructionFiles` option changes that rule, and One Code
+honours it: `claude-md` never loads `AGENTS.md`, `claude-md-and-agents-md`
+loads it beside `CLAUDE.md`, and `managed-only` drops your own and the
+project's instruction files.
 
 To give One Code instructions that Claude Code shouldn't read, add an
 `ONECODE.md`. See [ONECODE.md](sessions-and-context.md#onecodemd).
 
-To generate a `CLAUDE.md` for a project that lacks one, run `/init`. It has
-the model survey the project (build, test, and lint commands, layout,
-existing AI-tool configuration), ask you about what the code can't answer,
-and write the file. It never overwrites an existing `CLAUDE.md` silently.
+To generate a `CLAUDE.md` for a project that lacks one, run `/init`. It sends
+the prompt Claude Code's `/init` sends: the model reads the project and writes
+down how to build, lint, and test it and the big-picture architecture, folding
+in your README and any Cursor, Copilot, or `AGENTS.md` rules. If the project
+already has a `CLAUDE.md`, it suggests improvements instead.
 
 ## Skills, commands, and agents
 
@@ -78,14 +90,17 @@ The keys One Code honors:
 | `permissions.allow`, `permissions.deny`, `permissions.ask` | All | Project allow rules need one-time approval. See [Permissions](permissions-modes-and-auto-mode.md#permission-rules). |
 | `permissions.defaultMode` | All | A project file can't select `auto` or `bypassPermissions`. |
 | `permissions.disableBypassPermissionsMode` | All | `"disable"` refuses bypass mode from any source. |
+| `permissions.blockReadsOutsideWorkingDirectories` | All | `true` makes the read tools refuse paths outside the working directories. See [Reads outside the working directories](permissions-modes-and-auto-mode.md#reads-outside-the-working-directories). |
+| `permissions.additionalDirectories` | All | Project directories need one-time approval. See [Workspace directories](permissions-modes-and-auto-mode.md#workspace-directories). |
 | `autoMode.*` | User, managed | Never read from project files. See [Configure auto mode](permissions-modes-and-auto-mode.md#configure-auto-mode). |
 | `hooks` | All | Project hooks need one-time approval. See [Hooks](hooks.md). |
 | `env.CLAUDE_CODE_SUBAGENT_MODEL` | User, managed | The only `env` key read. |
 | `enabledPlugins` | All | Later scope wins per plugin. |
-| `enabledMcpjsonServers`, `disabledMcpjsonServers`, `enableAllProjectMcpServers` | User, untracked local | Never from a checked-in project file. |
+| `enabledMcpjsonServers`, `enableAllProjectMcpServers` | User | Never from a project file, local included. |
+| `disabledMcpjsonServers` | User, local | |
 | `mcpServers` | `~/.claude.json`, `.claude/settings.local.json` | |
 
-Not honored: `permissions.additionalDirectories`, other `env` keys,
+Not honored: other `env` keys,
 `includeCoAuthoredBy`, `apiKeyHelper`, `forceLoginMethod`,
 `cleanupPeriodDays`, and `spinnerTipsEnabled`. Run `/doctor report` to see,
 for every file found, which keys were used, ignored, or refused.
@@ -112,6 +127,42 @@ memories. This is the one place One Code writes under `~/.claude`. Run
 `/memory` to open memory and instruction files. See
 [Memory](sessions-and-context.md#memory).
 
+## Run One Code on its own setup
+
+Maybe you don't use Claude Code at all, or you want One Code's
+instructions, agents and memory kept apart from it. Independent mode does
+that: One Code stops reading anything of Claude Code's. No `~/.claude`, no
+project `.claude/`, no `CLAUDE.md`, no `~/.claude.json` or `.mcp.json`, and
+no managed settings either.
+
+To switch, run `/memory`, press **↑** to reach the **Config sources** row,
+and press **Enter**. One Code asks first, since this changes everywhere it
+reads configuration from: press **Enter** again to switch, or **Esc** to
+keep the mode you have. The row shows **(from next start)** until you restart
+One Code, because the switch applies to the next session, not the one
+you're in. `/doctor` shows which mode is running.
+
+Here's where each mode looks:
+
+| What | Claude-compatible (default) | Independent |
+|---|---|---|
+| Instructions | `CLAUDE.md` family, or `AGENTS.md` when there's none; `ONECODE.md` | `AGENTS.md` in every directory; `ONECODE.md` |
+| Skills | `.claude/skills/`, `~/.claude/skills/`, `.agents/skills/`, `~/.agents/skills/`, pi's skills | `.agents/skills/`, `~/.agents/skills/`, pi's skills |
+| Commands, agents, workflows | `.claude/` and `~/.claude/` | `.onecode/` and `~/.onecode/` (`commands/`, `agents/`, `workflows/`) |
+| Settings, hooks, permissions | Claude Code's settings files, managed settings, and One Code's files | One Code's files only: `~/.onecode/settings.json` and the per-repository one |
+| MCP servers | `~/.claude.json`, `.mcp.json`, `.claude/settings.local.json`, pi's `mcp.json` files | pi's `mcp.json` files |
+| Memory | `~/.claude/projects/<slug>/memory/` | `~/.onecode/projects/<slug>/memory/` |
+| Worktrees | `.claude/worktrees/` | `.onecode/worktrees/` |
+
+In independent mode, the settings you'd put in `~/.claude/settings.json`
+(permissions, `defaultMode`, hooks, the `env` block, `autoMode`) go in
+`~/.onecode/settings.json` instead, with the same keys. Memories don't move
+between modes, so each mode starts with its own.
+
+Independent mode skips managed settings too. If your organization manages
+Claude Code with a policy file, that policy doesn't apply to One Code in
+this mode.
+
 ## What stays separate
 
 One Code's own state lives in `~/.onecode`. Everything it saves (a chosen

package/docs/guide/configuration.md

@@ -23,11 +23,15 @@ Code reads but never writes.
 | Claude Code user configuration that One Code reads | `~/.claude/settings.json` |
 | Claude Code project configuration that One Code reads | `.claude/settings.json`, `.claude/settings.local.json` |
 
+In independent mode One Code doesn't read either Claude Code file; Claude
+Code's settings keys, such as `permissions`, `hooks` and `env`, go in One
+Code's two files instead.
+
 The per-repository slug is derived from the repository root, so worktrees
 and subdirectories of one repository share one file.
 
-Commands such as `/allow`, `/subagent`, `/auto-mode model`, and the
-`/mcp` panel write to One Code's files. Both One Code files are written
+Commands such as `/allow`, `/subagent`, `/auto-mode model`, and the `/mcp`
+panel write to One Code's files. Both One Code files are written
 atomically; a malformed file is reported rather than overwritten.
 
 ### Relocating directories
@@ -35,10 +39,14 @@ atomically; a malformed file is reported rather than overwritten.
 | Variable | Moves |
 |---|---|
 | `ONECODE_STATE_DIR` | One Code's state (default `~/.onecode`). |
-| `PI_CODING_AGENT_DIR` | pi's agent directory. The bundled app sets it to `~/.onecode/agent`. |
+| `ONECODE_AGENT_DIR` | pi's agent directory under the bundled app (default `~/.onecode/agent`). |
+| `PI_CODING_AGENT_DIR` | pi's agent directory on your own pi. The bundled app ignores it, so it never touches your own pi's settings. |
 | `CLAUDE_CONFIG_DIR` | Where Claude Code's user configuration is read from (default `~/.claude`). |
 
-Setting one doesn't move the others.
+Setting one doesn't move the others. Commands the bundled app runs for you
+(the `bash` tool, `!` commands, hooks, MCP servers, and language servers)
+get your own `PI_CODING_AGENT_DIR` back, so a `pi` started from inside a
+session is your own pi, not the app.
 
 ## What is stored under ~/.onecode
 
@@ -46,13 +54,16 @@ Setting one doesn't move the others.
 |---|---|
 | `settings.json` | User-wide One Code settings. |
 | `projects/<slug>/settings.json` | Per-repository settings. |
+| `projects/<slug>/memory/` | Per-repository memory, in independent mode. |
+| `agents/`, `commands/`, `workflows/` | Your agents, slash commands and saved workflows, in independent mode. |
 | `agent/` | pi's own state under the bundled app: credentials, model catalog, sessions, pi's settings, and One Code's plugin directory (`agent/plugins/`). |
 | `plans/<name>.md` | Plan files from plan mode. |
+| `artifacts/` | Pages published with the `artifact` tool: `index.html` is the gallery; each `<id>/` holds the current page, its details, and `versions/` with every earlier version. |
 | `hooks/project-approvals.json` | Which projects' hooks you approved. |
 | `mcp/project-approvals.json` | Which projects' MCP servers you approved. |
 | `permissions/project-allow-approvals.json` | Which projects' allow rules you trusted. |
-| `mcp-auth/<server>.json` | OAuth tokens for MCP servers, owner-readable only. |
-| `cache/artificial-analysis.json` | The cached model-capability snapshot, when a key is set. |
+| `mcp-auth/<server>-<hash>.json` | OAuth tokens for MCP servers, one file per server name, URL and headers, owner-readable only. |
+| `cache/model-catalog/` | The daily copy of the models.dev, OpenRouter and Hugging Face catalogs behind the model tiers. |
 | `hooks/hooks-decisions.jsonl` | A hook decision log, written only while `CC_HOOKS_DEBUG` is set. |
 
 The bundled app also keeps a timestamp of its last update check at
@@ -66,20 +77,27 @@ appear in `projects/<slug>/settings.json`.
 | Key | Type | Set by | Effect |
 |---|---|---|---|
 | `subagentModel` | string | `/subagent` | Default model for subagents and workflow agents: `provider/model-id`, a short alias, or `inherit`. |
+| `suggestNewerModels` | boolean | By hand | Suggest a newer model in the same line at a similar or lower price. Defaults to `true`; `false` turns off notices and the `/doctor` suggestion. |
+| `modelTiers` | object | By hand (user settings only) | Your own tier for a model, keyed by `provider/id` or by the provider's model id alone: `frontier`, `workhorse`, `cheap` or `tiny`. See [Prompting adapts to the model](providers-and-models.md#prompting-adapts-to-the-model). |
+| `refreshModelCatalog` | boolean | By hand | `false` stops the daily refresh of the model catalogs behind the tiers; the copy on disk stays in use. Defaults to `true`. |
 | `permissions.allow` | string array | `/allow` (per repository) or `/allow … global` | Allow rules in Claude Code's format. |
 | `autoMode.environment` | string array | `/auto-mode setup` | Describes your environment to the classifier. |
 | `autoMode.hard_deny`, `autoMode.soft_deny`, `autoMode.allow` | string array | `/auto-mode setup` | Extra classifier rules, appended to the built-ins. |
-| `autoMode.classifierModel` | string | `/auto-mode model` | The classifier model. |
 | `autoMode.classifyAllShell` | boolean | By hand | Send every shell command to the classifier. |
+| `autoMode.classifierModel` | string | `/auto-mode model` | The classifier model, `provider/model-id`, instead of the automatic pick. Read from this file and managed settings only, never from `~/.claude` or a project. |
 | `autoMode.logDecisions` | boolean | By hand | Log every gate decision next to the session files. |
 | `webSearch.apiKeys.brave`, `webSearch.apiKeys.tavily` | string | By hand | Search keys when the environment variables are not set. |
 | `webSearch.order` | string array | By hand | Order of the fallback search backends: `brave`, `tavily`, `exa-free`. |
-| `capabilityIndex.artificialAnalysisApiKey` | string | By hand | Artificial Analysis key for measured model selection. |
 | `disabledMcpServers` | string array | `/mcp` (user or per repository) | MCP servers kept disabled. |
+| `artifacts.autoOpen` | boolean | By hand | `false` stops the browser opening when the model publishes a new artifact. Defaults to `true`. |
+| `enableWorkflows` | boolean | By hand (user or per repository) | `false` turns the `workflow` tool off. Defaults to `true`. |
+| `disableWorkflows` | boolean | By hand (user or per repository) | `true` turns the `workflow` tool off, whatever `enableWorkflows` says. |
+| `workflowSizeGuideline` | string | By hand (user or per repository) | How big the model keeps a workflow: `small` (under 5 agents), `medium` (under 10, the default), `large` (under 50) or `unrestricted`. A guideline, not a limit. |
+| `configMode` | string | `/memory` | `claude-compatible` (the default) or `independent`. Applies from the next start. See [Run One Code on its own setup](bring-your-claude-code-setup.md#run-one-code-on-its-own-setup). |
 
-Two keys are stamped alongside model choices (`subagentModelSetFor`,
-`autoMode.classifierModelSetFor`) to record the provider a choice was made
-on; leave them alone.
+`subagentModelSetFor` and `autoMode.classifierModelSetFor` are stamped
+alongside the subagent and classifier choices to record the provider each
+was made on; leave them alone.
 
 The main model chosen with `/model` is saved in pi's own settings file as
 `defaultProvider` and `defaultModel`, not in One Code's.
@@ -90,15 +108,20 @@ The bundled app starts in full-screen mode with the `onecode` theme and
 quiet startup. It sets these on first run in pi's settings and never
 overrides a value you change later.
 
-On your own pi, to use full-screen mode for one session:
+On your own pi, 1.0 and later start in full-screen mode. On an older pi,
+to use full-screen mode for one session:
 
 ```bash
 pi --tui-mode fullscreen
 ```
 
+To keep the terminal's normal screen and scrollback instead, use
+`--tui-mode regular`, or set `"tuiMode": "regular"` in pi's settings.
+
 For a persistent setting, merge these keys into pi's settings file (the
 first two rows of the table under [Where settings live](#where-settings-live)),
-preserving its other keys such as `packages`:
+preserving its other keys such as `packages`. On pi 1.0 and later you can
+leave out `tuiMode`, since full-screen is already the default:
 
 ```json
 {
@@ -122,9 +145,20 @@ Set the subagent default with `/subagent`, or apply a preset with
 [Providers and models](providers-and-models.md) and
 [Choose the subagent model](subagents-and-workflows.md#choose-the-subagent-model).
 
+If you pick a model that has a newer version in the same line, say Qwen 3.6
+27B when Qwen 3.8 27B exists, One Code tells you when the session starts or
+when you switch models. It only suggests a model you can use with your
+credentials, released later, and priced at most 10% higher (blending three
+input tokens to one output token, since coding work is input-heavy).
+
+The notice shows once per session and model, with the `/model` command to
+switch. It never switches for you and never enters the conversation, and
+`/doctor` reports the same suggestion. Print and JSON runs don't show it. To
+turn it off, add `"suggestNewerModels": false` to `~/.onecode/settings.json`.
+
 ## Permission settings
 
-`/permissions` shows the mode and rules, `/allow` adds a rule, and
+`/permissions` opens the permissions panel, `/allow` adds a rule, and
 `/auto-mode setup` configures the classifier. **ctrl+q** (**alt+m** on Windows and WSL) cycles modes. To
 start a session in a given mode:
 

package/docs/guide/differences-from-claude-code.md

@@ -29,8 +29,16 @@ so nothing surprises you.
 | Models | Anthropic models. | Any provider pi supports, switchable mid-session, with a different model per role. |
 | Tool names on the wire | PascalCase (`Read`, `Bash`). | snake_case (`read`, `bash`); `Agent` and `SendMessage` keep their names. Claude Code names still work in rules and hook matchers. |
 | Permission-mode key | shift+tab. | ctrl+q; alt+m on Windows and WSL. pi reserves shift+tab for the reasoning-effort dial and, on Windows, ctrl+q for queuing a follow-up. |
-| Task-list key | ctrl+t. | `/tasks show` and `/tasks hide`. pi reserves ctrl+t for thinking blocks. |
-| Deleting files in auto mode | The whole project directory is trusted. | A delete is approved only when git can recover the file; otherwise the classifier decides. |
+| Send queued messages now (**ctrl+x ctrl+s**) | Running tools move to the background, and **ctrl+enter** works too where the terminal sends it. | Running tools are cancelled, and only **ctrl+x ctrl+s** is bound. |
+| Task-list key | ctrl+t. | alt+t; ctrl+\\ on macOS. pi reserves ctrl+t for thinking blocks, and macOS terminals type a character for option+t. |
+| Where auto mode's classifier runs | On Anthropic's API server, through a request field the endpoint must support; the local classifier is a fallback only until about October 23, 2026 ([LiteLLM's notes](https://docs.litellm.ai/blog/claude-code-server-side-auto-mode)). | In the harness, on a model from your own provider, so auto mode works with any provider. |
+| Permission shortcuts by model | One set for every model; auto mode needs a Sonnet- or Opus-class model. | Claude Code's shortcuts for frontier and workhorse models. Cheap and tiny models, which Claude Code can't run in auto mode, get stricter checks. |
+| Deleting files in auto mode | An in-project `rm` runs without the classifier; `git reset --hard` is classified. | The same with frontier and workhorse models. With cheap and tiny models, every delete goes to the classifier. |
+| Reading outside the working directories in auto mode | Runs without the classifier after a one-time question. | The same with frontier and workhorse models, except credential files, which are classified. With cheap and tiny models, the classifier decides. |
+| A path in the project that is a symlink to somewhere outside it, in auto mode | The classifier judges the command as written. | The classifier is also told where the path really leads, so a write to `notes.txt` that lands in `~/.ssh/authorized_keys` is judged as that write. |
+| Approving a call auto mode denied | `/permissions` tells the model permission was granted; the retry is judged again. | The approval lets that exact call run once without the classifier. |
+| Auto-mode built-in rules | A section's built-in rules can be switched off. | Always in effect; your rules only add to them. |
+| Workspace directories | Reads, edits in accept-edits mode, and auto-mode writes. | The same, except that credential files there still prompt. With cheap and tiny models, auto-mode writes there go to the classifier. |
 | Bypass mode | Protected paths stay protected. | Bypass mode bypasses everything, including protected paths. |
 | First-run consent for auto mode | Asked once. | Not asked. Auto mode is on from the first session. |
 | OS sandbox | Paired with auto mode. | None. Run One Code in a container for OS-level isolation. |
@@ -44,11 +52,15 @@ so nothing surprises you.
 ## Tools that are not provided
 
 These Claude Code tools depend on Anthropic-hosted or desktop services and
-have no equivalent here: `Artifact`, `ReportFindings`,
-`ShareOnboardingGuide`, `PushNotification`, `RemoteTrigger`, `DesignSync`,
-`CronCreate`, `CronList`, `CronDelete`, `EndConversation`, and
-`SendFeedback`. Scheduling within a session is available through `/loop`
-and `schedule_wakeup`; scheduled cloud sessions aren't.
+have no equivalent here: `ReportFindings`, `ShareOnboardingGuide`,
+`PushNotification`, `RemoteTrigger`, `DesignSync`, `EndConversation`, and
+`SendFeedback`. `Artifact` is local: One Code saves the page on your
+machine and opens it in your browser instead of publishing it to claude.ai.
+The page has no runtime capabilities (no shared data, comments, or calls
+back to the model), and there are no artifact types such as slide decks.
+See [Artifacts](tools.md#artifacts). Scheduling within a session is
+available through the cron tools, `/loop`, and `schedule_wakeup`;
+scheduled cloud sessions aren't.
 
 The `Agent` tool's remote isolation option isn't implemented.
 
@@ -56,17 +68,18 @@ The `Agent` tool's remote isolation option isn't implemented.
 
 Claude Code commands with no One Code or pi counterpart: `/cost` (the
 footer shows cost instead), `/status`, `/vim`, `/terminal-setup`, `/bug`,
-`/help`, `/rewind`, `/add-dir`, `/hooks`, `/ide`, `/install-github-app`,
+`/help`, `/rewind`, `/hooks`, `/ide`, `/install-github-app`,
 `/statusline`, `/privacy-settings`, and `/upgrade`. pi's `/changelog` and
 `/settings` cover part of `/release-notes` and `/config`. `/review` is
 available through the `commit-commands` plugin when installed.
 
 ## Skills that are not bundled
 
-One Code bundles four of Claude Code's built-in skills: `simplify`,
-`code-review`, `security-review`, and `fewer-permission-prompts`. It does
-not bundle the skills that need Claude Code's hosted or desktop surfaces
-(`design`, `dataviz`, the `artifact-*` guides, and the publishers), the
+One Code bundles six of Claude Code's built-in skills: `loop`, `simplify`,
+`code-review`, `security-review`, `fewer-permission-prompts`, and
+`artifact-design` (adapted to local artifacts). It does not bundle the skills
+that need Claude Code's hosted or desktop surfaces (`design`, `dataviz`,
+`artifact-capabilities`, `artifact-diagramming`, and the publishers), the
 account and desktop skills (`update-config`, `keybindings-help`,
 `claude-in-chrome`, `debug`, `usage`, `schedule`, `batch`,
 `claude-code-guide`), the run-skill generators, or the `claude-api`
@@ -83,9 +96,8 @@ action but never pre-approve one. See [Hooks](hooks.md).
 
 ## Settings keys that are ignored
 
-`permissions.additionalDirectories` isn't honored. The `env` block is read
-only for `CLAUDE_CODE_SUBAGENT_MODEL`, and only from user and managed
-scope. `includeCoAuthoredBy`, `apiKeyHelper`, `forceLoginMethod`,
+The `env` block is read only for `CLAUDE_CODE_SUBAGENT_MODEL`, and only
+from user and managed scope. `includeCoAuthoredBy`, `apiKeyHelper`, `forceLoginMethod`,
 `cleanupPeriodDays`, and `spinnerTipsEnabled` aren't read. Run
 `/doctor report` to see, per file, which keys were used, ignored, or
 refused.
@@ -106,11 +118,11 @@ every model. The content is the same; only the placement differs.
   default on Windows, `CLAUDE_CODE_USE_POWERSHELL_TOOL=0` turns it off), and
   your `PowerShell(...)` rules, `CLAUDE_CODE_GIT_BASH_PATH`, and per-hook
   `shell` field work unchanged. The PowerShell tool's description is Claude
-  Code's own text. What differs: One Code has no PowerShell command parser
-  yet, so in auto mode every PowerShell command that isn't on Claude Code's
-  read-only cmdlet list goes to the classifier (Claude Code auto-approves
-  more in-project work), and the git-recoverability shortcut for in-project
-  deletes is bash-only. Verified on CI runners and through a `pwsh` on
+  Code's own text. PowerShell commands are judged from PowerShell's own
+  parse, as in Claude Code. What differs: native commands run from
+  PowerShell (`git status`, `npm test`) always go to the classifier in auto
+  mode, where Claude Code approves some of them itself. Read-only uses of
+  Windows' own `findstr` and `where.exe` are the exceptions. Verified on CI runners and through a `pwsh` on
   macOS; a real Windows desktop has not been driven end to end yet. See
   [Windows](windows.md).
 
@@ -138,9 +150,6 @@ every model. The content is the same; only the placement differs.
 - Running a skill in a one-shot run (`-p '/simplify'`) delivers the skill
   but starts no model turn, so the process exits without doing anything.
   Interactive sessions are unaffected.
-- The reasoning effort set with `/effort` doesn't persist across
-  restarts; the model chosen with `/model` does. To save a level, open
-  pi's `/thinking` picker and press **ctrl+s**, or pass `--thinking`.
 - A subagent spawn that is blocked before it starts can leave its requested
   run name reserved; a retry with the same name is renamed automatically.
 - Under pi's RPC transport, `SessionStart` hooks fire twice per `/clear`.

package/docs/guide/doctor.md

@@ -28,10 +28,13 @@ the findings.
    offers, and where the credential came from. An error when none is
    ready, with the free options named.
 3. **Models.** The main model with its price and context window, the
-   prompt tier it gets, the reasoning effort, the subagent model and how it
-   was chosen, the auto-mode classifier model, the reader model used by
-   web fetch and recaps, capability verdicts for each role when an
-   Artificial Analysis key is set, and the permission mode.
+   prompt tier it gets and the rule that set it, the reasoning effort, the
+   subagent model and how it was chosen, the auto-mode classifier model and
+   your `/auto-mode model` setting, the reader model used by web fetch and
+   recaps, how fresh the model catalogs behind the tiers are, and the
+   permission mode. A model you chose by hand gets a warning when a newer one
+   is available in its line or it's far weaker than your main model, and the
+   classifier one also when its context window is smaller than your session's.
 4. **Presets.** The three model presets for your provider and the model
    each role would get under each.
 5. **Imported configuration.** Every settings file found, with the keys One
@@ -53,22 +56,26 @@ In the panel, press **f** to run the checkup on the report you're reading.
 
 ## Model presets
 
-A preset sets the main model, the subagent model, and the classifier model
-together, from the provider you're connected to. Only current-generation,
-priced models that support tool calls are considered.
+A preset sets the main model and subagent model from the provider you're
+connected to, and returns the classifier to the automatic pick. Each preset's
+preview shows the classifier its main model would get (see
+[Automatic model selection](providers-and-models.md#automatic-model-selection)).
+A preset only recommends a main model that's priced, can call tools, and isn't
+replaced by a newer model this provider serves. It also skips any model
+`/doctor` would flag as having a newer version at about the same price, so a
+preset never points you at a model the same report calls outdated.
 
 | Preset | Main model | Subagents | Classifier |
 |---|---|---|---|
-| `economical` | The cheapest small model. | Inherit the main model. | Automatic. |
-| `balanced` | The cheapest Sonnet-class model. | Chosen automatically (a cheaper Sonnet-class model when one exists, else the main model). | Automatic. |
+| `economical` | The cheapest cheap-tier model, else the cheapest workhorse or frontier one. | Inherit the main model. | Automatic. |
+| `balanced` | The cheapest workhorse- or frontier-tier model. | Chosen automatically (a cheaper model in the main model's tier or above when one exists, else the main model). | Automatic. |
 | `quality` | The most capable model available. | Inherit the main model. | Automatic. |
 
 `/doctor presets` shows what each preset would pick. `/doctor preset balanced`
 applies one; the aliases `economy`, `cheap`, `balance`, `max`, `maximum`,
-and `best` also work. Applying a preset writes the subagent and classifier
-choices to `~/.onecode/settings.json` and remembers the main model as pi's
-default. Undo any part with `/model`, `/subagent clear`, or
-`/auto-mode model clear`.
+and `best` also work. Applying a preset writes the subagent choice to
+`~/.onecode/settings.json` and remembers the main model as pi's
+default. Undo the changes with `/model`, `/subagent clear` or `/auto-mode model`.
 
 ## The command-line form
 

package/docs/guide/hooks.md

@@ -24,6 +24,12 @@ stored in `~/.onecode/hooks/project-approvals.json` with a hash of the hook
 configuration, so any change asks again. Declining is remembered for the
 session only. User, managed, and plugin hooks never prompt.
 
+Set `disableAllHooks: true` in your user settings to skip user, project, and
+plugin hooks. Managed hooks still run unless managed settings also disable
+hooks, and a managed value always takes precedence. In a project's
+`.claude/settings.json` or `.claude/settings.local.json`, the setting skips only
+that project's own hooks, so a repository you clone can't switch off yours.
+
 Only command hooks are supported. Hook entries of type `http`, `prompt`, or
 `agent` are skipped with a diagnostic.
 
@@ -71,7 +77,10 @@ The hook's standard input is a JSON object with these fields:
 | `reason` | `SessionEnd` | `clear`, `logout`, `prompt_input_exit`, or `other`. |
 | `agent_id`, `agent_type` | Inside a subagent | Identify the subagent making the call. |
 
-The hook's environment also carries `CLAUDE_PROJECT_DIR`.
+The hook's environment also carries `CLAUDE_PROJECT_DIR`, the parent project
+root. A worktree-isolated child's hooks run in the child's working directory,
+while settings and project-hook approval still come from the parent project.
+Cancelling a turn stops its running hooks and their descendant processes.
 
 Hook matchers match on the tool name. Claude Code's PascalCase names work.
 
@@ -84,13 +93,14 @@ Hook matchers match on the tool name. Claude Code's PascalCase names work.
 | Exit code 2 | The action is blocked. Standard error is the reason. |
 | Any other exit code | The hook passes and its output is ignored. |
 | Timeout | `PreToolUse` and `UserPromptSubmit` block (fail closed). Other events pass. |
+| Output exceeds 1,000,000 bytes on either stream | The command stops. `PreToolUse` and `UserPromptSubmit` block; other events show a notice. Incomplete output is not used as a verdict or context. |
 | The command could not be started | The hook passes; this is an environment problem, not a verdict. |
 
 Envelope fields honored in a JSON result:
 
 | Field | Effect |
 |---|---|
-| `continue: false` | Blocks, with `stopReason` as the reason. |
+| `continue: false` | Blocks, with `stopReason` as the reason. For `Stop`, ends the turn without requesting another response. |
 | `decision: "block"` | Blocks, with `reason` as the reason. |
 | `hookSpecificOutput.permissionDecision` | `"deny"` and `"ask"` both block, with `permissionDecisionReason`. `"allow"` is read but never honored; a hook can't pre-approve an action, and the permission gate still runs. |
 | `hookSpecificOutput.updatedInput` | Replaces the tool's input (`PreToolUse`). |
@@ -99,7 +109,12 @@ Envelope fields honored in a JSON result:
 | `systemMessage` | Shown to you. |
 
 A `PreToolUse` block stops the call before the permission gate runs, so no
-approval prompt appears for a hook-blocked call.
+approval prompt appears for a hook-blocked call. A malformed response from one
+hook does not discard another hook's denial.
+
+A blocking `Stop` hook can request at most eight consecutive continuations per
+user turn. The ninth block ends the turn with a notice. Hooks still receive
+`stop_hook_active` so they can stop requesting continuations earlier.
 
 ## Debugging hooks
 

package/docs/guide/installation.md

@@ -102,9 +102,31 @@ pi install npm:one-code-extension
 ```
 
 Use `pi` in place of `onecode` for every command in this guide. The
-extension is tested against pi 0.83 through 0.86 and warns at startup when
-your pi is outside that range. Full-screen mode is opt-in on your own pi;
-see [Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).
+extension is tested against pi 0.84.3 through 1.3 and warns at startup when
+your pi is outside that range. It doesn't load on a pi older than 0.84.3;
+update pi first with `pi update`. pi 1.0 and later start in full-screen mode;
+on an older pi it's opt-in. See
+[Full-screen mode and themes](configuration.md#full-screen-mode-and-themes).
+
+pi 0.99 and later ship their own tool search and MCP as built-in
+extensions. One Code brings its own versions of both, so pi skips the
+built-ins and prints a warning about each at every start. The warnings tell
+you to remove the extension that replaced them. Don't: that's One Code. To
+hide them, run `pi config` and turn off `tool-search` and `mcp` under
+Built-in, or add this to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "extensions": ["-builtin:tool-search", "-builtin:mcp"]
+}
+```
+
+On the first start where the built-ins are still on, One Code asks whether
+to turn them off for you and explains why. Say yes and it adds those two
+entries to your settings; the warnings stop from the next start. Say no and
+it won't ask again, but it shows a short notice under pi's warnings, and
+`/doctor` can still make the change. The bundled app turns both off on its
+own.
 
 A few interface refinements are applied only by the bundled app, because
 they patch pi internals the extension API can't reach: a clean exit that
@@ -149,7 +171,8 @@ A Homebrew install sees the notice a day after the npm release, because
 Homebrew refuses packages younger than that and `brew upgrade` would find
 nothing sooner. Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check;
 `--offline` skips it too.
-On your own pi, update with `pi update --extensions`.
+On your own pi, update the extension with `pi update npm:one-code-extension`.
+A bare `pi update` updates pi itself and skips extensions.
 
 Both packages are released together with the same version number.