one-code-extension 0.4.1 → 0.5.0

package/docs/guide/reference.md

@@ -26,7 +26,7 @@ that explains it.
 | `/workflows stop <runId>` | Stop a running workflow. | |
 | `/workflows log <runId>` | Print a run's recent events. | |
 | `/workflows list` | List this session's runs and the saved workflows. | |
-| `/effort [level]` | Set the reasoning effort (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultracode`), or open the slider. | [Reasoning effort](subagents-and-workflows.md#reasoning-effort) |
+| `/effort [level]` | Set the reasoning effort (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, `ultracode`, or `auto` to clear the saved level), or open the slider. | [Reasoning effort](subagents-and-workflows.md#reasoning-effort) |
 | `/skills` | Manage which skills the model sees. | [Skills](skills-plugins-and-mcp.md#manage-skills) |
 | `/<skill-name> [args]` | Run a skill. | [Skills](skills-plugins-and-mcp.md#skills) |
 | `/skill:<name>`, `/skill:<plugin>:<name>` | Run a skill by its full name. | |
@@ -35,18 +35,21 @@ that explains it.
 | `/plugins` | Browse, install, and toggle plugins and marketplaces. | [Plugins](skills-plugins-and-mcp.md#plugins) |
 | `/mcp` | Manage MCP servers: status, reconnect, authenticate, enable, disable. | [MCP servers](skills-plugins-and-mcp.md#manage-servers) |
 | `/lsp` | Show language-server status. | [Language servers](configuration.md#language-server-diagnostics) |
-| `/permissions` | Show the permission mode and every loaded rule. | [Permissions](permissions-modes-and-auto-mode.md) |
+| `/permissions` | Open the permissions panel: approve calls auto mode denied, and manage rules, auto-mode rules, and workspace directories. | [Manage permissions in the panel](permissions-modes-and-auto-mode.md#manage-permissions-in-the-panel) |
+| `/add-dir [path]` | Add a workspace directory, for this session or remembered. | [Workspace directories](permissions-modes-and-auto-mode.md#workspace-directories) |
 | `/allow <rule> [global]` | Save an allow rule for this repository, or for every repository with `global`. | [Add a rule](permissions-modes-and-auto-mode.md#add-a-rule-during-a-session) |
 | `/auto-mode`, `/auto-mode config` | Show the effective auto-mode configuration. | [Auto mode](permissions-modes-and-auto-mode.md#configure-auto-mode) |
 | `/auto-mode setup` | Draft and save an auto-mode configuration for this environment. | |
 | `/auto-mode defaults` | Show the built-in environment description. | |
-| `/auto-mode model [provider/model-id\|clear]` | Choose or clear the classifier model. | |
-| `/memory` | Open an instruction file or the memory folder. | [Memory](sessions-and-context.md#memory) |
-| `/tasks`, `/tasks hide`, `/tasks show` | Print the task list, or hide and show its widget. | [Tasks](tasks-and-background-work.md#the-task-list) |
+| `/auto-mode model [provider/model-id\|clear]` | Choose the classifier model, or go back to the automatic pick. | [The classifier model](permissions-modes-and-auto-mode.md#the-classifier-model) |
+| `/memory` | Open an instruction file or the memory folder, turn auto-memory on or off, or switch config sources. | [Memory](sessions-and-context.md#memory) |
+| `/config` | Change this project's external instruction import approval. | [External instruction imports](sessions-and-context.md#external-instruction-imports) |
+| `/artifacts` | Pick a saved artifact to open, save to `~/Downloads`, or delete, or open the gallery. | [Artifacts](tools.md#artifacts) |
+| `/tasks` | List background shells, running agents and the agents you've viewed; open or stop one. | [Talk to an agent](subagents-and-workflows.md#talk-to-an-agent) |
 | `/background` | List background tasks. | [Background](tasks-and-background-work.md#the-background-list) |
-| `/loop <interval> <task>` | Repeat a task at a fixed interval (`30s`, `5m`, `1h`). | [Loops](tasks-and-background-work.md#scheduled-wake-ups-and-loops) |
+| `/loop <interval> <task>` | Repeat a task at a fixed interval (`5m`, `2h`, `1d`, or `… every 20m`). Ask the model to stop it. | [Loops](tasks-and-background-work.md#scheduled-wake-ups-and-loops) |
 | `/loop <task>` | Repeat a task, letting the model choose the pace. | |
-| `/loop status`, `/loop stop` | Report or end the loop. | |
+| `/loop`, `/loop <interval>` | Run the autonomous check, or the tasks in `.claude/loop.md`, on a loop. | |
 | `/tools-deferred` | List deferred tools and whether each is loaded. | [Tools](tools.md#eager-and-deferred-tools) |
 | `/init` | Have the model write a `CLAUDE.md` for the project. | [CLAUDE.md](bring-your-claude-code-setup.md#project-instructions-claudemd) |
 | `/clear` | Start a new session (pi's `/new`); the model is told. | [Sessions](sessions-and-context.md#start-over) |
@@ -103,19 +106,22 @@ The ones you will use most; `/hotkeys` shows all of them.
 |---|---|
 | **shift+tab** | Cycle the thinking level. |
 | **ctrl+t** | Show or hide thinking blocks. |
+| **alt+t** (**ctrl+\\** on macOS) | Show or hide the task list. |
 | **ctrl+o** | Expand or collapse a tool's output. |
 | **ctrl+p**, **shift+ctrl+p** | Cycle models forward or backward. |
 | **ctrl+l** | Open the model picker. |
 | **Esc** | Interrupt the model. |
 | **ctrl+c** | Clear the editor; press twice to exit. |
 | **ctrl+d** | Exit when the editor is empty. |
+| **Enter** while the model works | Queue a message. It reaches the model once the running tool calls finish. |
+| **ctrl+x ctrl+s** | Send queued messages now: interrupt the running turn and send them, with anything in the editor, as your next prompt. Running tools are cancelled. |
 | **alt+enter** (**ctrl+q** on Windows and WSL) | Queue a follow-up message while the model works. |
 | **alt+↑** | Restore queued messages to the editor. |
 | **ctrl+g** | Edit the prompt in your external editor. |
 | **ctrl+v** | Paste an image or text. |
 | **shift+enter**, **ctrl+j** | Insert a newline. |
-| **ctrl+x** | Copy the last reply. |
-| **PgUp**, **PgDn**, **Home**, **End** | Scroll the transcript in full-screen mode. |
+| **ctrl+x** | Copy the last reply. While the model works with a message queued or typed, it starts **ctrl+x ctrl+s** instead. |
+| **PgUp**, **PgDn**, **ctrl+home**, **ctrl+end** | Scroll the transcript in full-screen mode. On pi before 1.0.3, **Home** and **End** jump to the top and bottom instead. |
 | **ctrl+shift+f** | Search the transcript in full-screen mode. |
 | **!** at the start of a line | Run a shell command yourself. |
 
@@ -139,10 +145,11 @@ extension install, use `pi` in place of `onecode`.
 | `--no-session` | Do not save this session. |
 | `--permission-mode <mode>` | Start in `default`, `acceptEdits`, `plan`, `auto`, `bypassPermissions`, or `dontAsk`. |
 | `--dangerously-skip-permissions` | Start in bypass mode. |
+| `--add-dir <paths>` | Add workspace directories for this run, separated by `:` (`;` on Windows). |
 | `--model <provider/id>` | Start on a model. Add `:<level>` to set thinking. |
 | `--thinking <level>` | Start at a thinking level. |
-| `--provider <name>`, `--api-key <key>` | Choose a provider and supply a key for this run. |
-| `--tui-mode fullscreen` | Full-screen interface (the default under the app). |
+| `--provider <name>`, `--api-key <key>` | Choose a provider and supply a key for this run. On pi 1.0 and later, `--provider` needs `--model` too. |
+| `--tui-mode fullscreen`, `--tui-mode regular` | Full-screen interface (the default under the app and on pi 1.0 and later), or the terminal's normal screen with its scrollback. |
 | `--tools <list>` | Restrict the tools available. |
 | `-e <source>` | Load an extra extension. |
 | `--offline` | Skip network checks, including the update check. |
@@ -158,9 +165,9 @@ Set these before launching.
 | Variable | Effect |
 |---|---|
 | `ONECODE_STATE_DIR` | Where One Code keeps its state (default `~/.onecode`). Independent of pi's agent directory. |
+| `ONECODE_AGENT_DIR` | pi's agent directory under the bundled app (default `~/.onecode/agent`). |
 | `ONECODE_NO_UPDATE_CHECK=1` | Skip the daily update check. |
 | `ONECODE_DEBUG=1` | Report when a pi-internal patch in the bundled app didn't apply. |
-| `AA_API_KEY` | Artificial Analysis key for measured model selection. |
 | `BRAVE_SEARCH_API_KEY`, `TAVILY_API_KEY` | Web-search fallback keys. |
 
 ### Claude Code compatibility toggles
@@ -178,23 +185,26 @@ The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
 | `CC_SESSION_TITLE=0` | Turn off the automatic session title. |
 | `CC_RECAP_IDLE_MS` | Idle time before a recap, in milliseconds (default 300000). |
 | `CC_COMPACTION=0` | Use pi's compaction summary instead of Claude Code's. |
+| `CC_IDLE_COMPACT=0` | Turn off compaction of an idle session before its prompt cache expires. |
 | `CC_CLEAR_THINKING=0`, `=1` | Force the thinking-preservation request off or on for Anthropic models. Default: on for `api.anthropic.com` only. |
 | `CC_TOTAL_TOKENS=0` | Remove the `<total_tokens>` budget line. |
 | `CC_TOTAL_TOKENS_BUDGET` | The per-turn budget the line counts down from (default 15000000). |
 | `CC_PROMPT_TIER=frontier\|workhorse\|cheap\|tiny` | Force a system-prompt tier. |
+| `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` | Give frontier models and Sonnet 5 or later the task tools, which they run without by default. |
 | `CC_HOOKS_DEBUG=1` | Print hook dispatches to stderr and log decisions. |
 | `CC_AUTO_MODE_DEBUG=1` | Print classifier verdicts to stderr. `2` is more verbose. |
-| `CC_VERSION` | The version shown in the banner (set by the app). |
+| `CC_VERSION` | The version shown in the banner (set by the app, and not passed on to the commands it runs). |
 | `CC_PERMISSION_MODE` | Set by One Code to the live mode for child processes. Not an input; use `--permission-mode`. |
 
 ### pi and Claude Code variables honored
 
 | Variable | Effect |
 |---|---|
-| `PI_CODING_AGENT_DIR` | pi's agent directory. The app sets `~/.onecode/agent`. |
+| `PI_CODING_AGENT_DIR` | pi's agent directory on your own pi. The bundled app ignores it and uses `ONECODE_AGENT_DIR`; commands the app runs get your own value back. |
 | `PI_CACHE_RETENTION` | pi's prompt-cache lifetime. One Code sets `long` for interactive sessions unless you set it yourself. |
 | `PI_OFFLINE=1` | Same as `--offline`. |
 | `CLAUDE_CONFIG_DIR` | Where Claude Code's user configuration is read from. |
+| `ONECODE_CONFIG_MODE` | `claude-compatible` or `independent`, overriding the mode saved by `/memory`. See [Run One Code on its own setup](bring-your-claude-code-setup.md#run-one-code-on-its-own-setup). |
 | `CLAUDE_CODE_USE_POWERSHELL_TOOL` | `1` turns the `powershell` tool on (the default on Windows), `0` turns it off. Off Windows it needs a `pwsh` on PATH. See [Windows](windows.md). |
 | `CLAUDE_CODE_GIT_BASH_PATH` | The bash that drives the `bash` tool, hooks, and background shells. Also read from the `env` block of `~/.claude/settings.json`; a non-bash binary is ignored with a warning. |
 | `CLAUDE_CODE_SUBAGENT_MODEL` | Default subagent model on a Claude session. |
@@ -211,8 +221,10 @@ hook's environment, `CC_PERMISSION_MODE` for child tool gates.
 |---|---|
 | `~/.onecode/` | One Code's state. See [What is stored under ~/.onecode](configuration.md#what-is-stored-under-onecode). |
 | `~/.onecode/agent/` | pi's state under the bundled app: credentials, sessions, pi's settings, plugins. |
-| `~/.claude/` | Claude Code's configuration, read only, except `projects/<slug>/memory/`. |
+| `~/.claude/` | Claude Code's configuration, read only, except `projects/<slug>/memory/`. Not read in independent mode. |
 | `~/.claude/projects/<slug>/memory/` | Per-repository memory, shared with Claude Code. |
+| `~/.onecode/projects/<slug>/memory/` | Per-repository memory in independent mode. |
+| `.onecode/` | Project `commands/`, `agents/`, `workflows/` and `worktrees/` in independent mode. |
 | `.claude/` | Project configuration: `settings.json`, `settings.local.json`, `skills/`, `commands/`, `agents/`, `workflows/`, `worktrees/`. |
 | `.mcp.json` | Project MCP servers. |
 | `CLAUDE.md`, `CLAUDE.local.md`, `AGENTS.md`, `ONECODE.md` | Instruction files. |

package/docs/guide/sessions-and-context.md

@@ -17,14 +17,16 @@ it would there. The block contains, in order:
    working directory. In a directory that has no `CLAUDE.md`, an
    `AGENTS.md` is used instead. A `CLAUDE.local.md` next to either is
    included as your private, uncommitted instructions.
-2. **The auto-memory index.** The first 200 lines or 25 KB of `MEMORY.md`
-   from the repository's memory folder. See [Memory](#memory).
+2. **The auto-memory index.** The first 200 lines or 25,000 characters of
+   `MEMORY.md` from the repository's memory folder. When the index is
+   longer, a warning line after it tells the model how much was cut. See
+   [Memory](#memory).
 3. **Your email**, from `git config user.email` (or `GIT_AUTHOR_EMAIL` or
    `EMAIL`), for attribution.
-4. **Today's date.**
+4. **Today's date**, as your own clock shows it. If a session runs past
+   midnight, the model hears the new date on its next turn.
 
-`@path` references inside a `CLAUDE.md` are expanded in place, up to five
-levels deep, so a file that imports shared instructions keeps working.
+`@path` references inside a `CLAUDE.md` load shared instructions recursively.
 Paths resolve relative to the importing file; `~/` resolves to your home
 directory. References inside code spans and fenced blocks are left alone.
 
@@ -32,6 +34,30 @@ A `CLAUDE.md` larger than 40,000 characters, or a set of instruction files
 whose total exceeds that, triggers a warning at startup so you can trim it.
 Run `/memory` to open any of these files.
 
+### External instruction imports
+
+At interactive startup, One Code asks **Allow external CLAUDE.md file imports?**
+when project instructions (including `AGENTS.md`, private local instructions,
+and startup `.claude/rules`) import files outside the working directory.
+**No, disable external imports** is the default; Escape also records No.
+User-global instruction imports do not require this project approval.
+
+Both answers are remembered in `~/.onecode/projects/<slug>/settings.json`,
+never in Claude Code's files or the checkout. Subdirectories, symlink aliases,
+and linked worktrees share their repository's answer; outside Git, it applies
+to the working directory. Yes also covers future external imports. Only allow
+this for projects and imported files you trust, never third-party repositories.
+
+Use `/config` → **External CLAUDE.md includes** to change the answer. The row
+appears when external imports are detected. Changes affect future instruction
+loads (including nested instructions and compaction), not text already in the
+conversation or its frozen first-message block. Starting a new session loads
+the instructions under the saved answer.
+
+Print/JSON runs without a UI never ask and leave unapproved external imports
+out of context without recording a decision. Pi's RPC mode has a dialog UI:
+clients must answer the `extension_ui_request` before the first model request.
+
 ### ONECODE.md
 
 Instructions that only One Code should read go in `ONECODE.md`
@@ -50,7 +76,9 @@ The system prompt is an adaptation of Claude Code's, chosen by the
 capability of the model in use. Stronger models receive a terse prompt;
 smaller models receive more guidance and, on the smallest tier, extra
 search tools. It ends with a git status snapshot (branch, main branch, user,
-working-tree status, recent commits) taken once per session. See
+working-tree status, recent commits) taken once per session. A status
+longer than 2,000 characters is cut there, with a note telling the model
+to run `git status` itself, as Claude Code does. See
 [Prompting adapts to the model](providers-and-models.md#prompting-adapts-to-the-model).
 
 ## Memory
@@ -62,13 +90,26 @@ and subdirectories of one repository share one memory folder. This is the
 one place One Code writes under `~/.claude`, so a real Claude Code session
 on the same repository reads the same memories.
 
+In independent mode the folder is `~/.onecode/projects/<slug>/memory/`
+instead, and Claude Code doesn't see it. See
+[Run One Code on its own setup](bring-your-claude-code-setup.md#run-one-code-on-its-own-setup).
+
 The model writes one file per memory and keeps an index in `MEMORY.md`.
-When the index grows near its limit (200 lines or 25 KB), the model is
+When the index grows near its limit (200 lines or 25,000 characters), the model is
 warned; past the limit, a write to it still succeeds but returns an error
 so the model trims the index.
 
 Run `/memory` to open the memory folder or any instruction file. Files open
-in `$VISUAL` or `$EDITOR`; folders open in your file manager.
+in `$VISUAL` or `$EDITOR`; folders open in your file manager. The two rows
+at the top are settings, and both take effect from the next session:
+
+- **Auto-memory** turns memory on or off. Off, the model gets no memory
+  instructions and no `MEMORY.md` index, and the memory folder isn't
+  offered. It's saved as `autoMemoryEnabled` in `~/.onecode/settings.json`,
+  Claude Code's setting name, and `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`
+  overrides it.
+- **Config sources** switches between Claude-compatible and independent
+  mode. It asks you to confirm with a second **Enter**.
 
 ## The context window
 
@@ -88,6 +129,15 @@ can't reuse the cached prefix of the conversation.
 
 Set `CC_COMPACTION=0` to use pi's own summary instead.
 
+If you step away from a big session, One Code compacts it before the prompt
+cache runs out. On Claude models the session's cache lasts an hour, and once
+it expires your next message pays to write the whole conversation to the cache
+again. So after 54 idle minutes, a session holding 200,000 tokens or more is
+compacted while reading the cache is still cheap, and you'll see "Compacted
+while idle, before the prompt cache expired". It holds off while a turn is
+running or if you typed in the last minute. Set `CC_IDLE_COMPACT=0` to turn
+it off.
+
 ### The token budget line
 
 Like Claude Code, One Code tells the model how many tokens it has left in
@@ -123,10 +173,11 @@ Each session gets a scratchpad directory under the system temp directory,
 named by project and session. The model is told to use it for temporary
 files instead of `/tmp`; writes there need no approval.
 
-Tool output larger than 50 KB isn't truncated. It's written to a file
-under the session directory, and the model receives the path, the size,
-and a 2 KB preview in a `<persisted-output>` block, so it can read the part
-it needs.
+Tool output larger than 50 KB (30,000 characters for a shell command)
+isn't truncated. It's written to a file under the session directory, and
+the model receives the path, the size, and a 2 KB preview from the start
+of the output in a `<persisted-output>` block, so it can read the part it
+needs.
 
 ## While you are away
 
@@ -204,7 +255,9 @@ footer's total. Set `CC_SESSION_TITLE=0` to turn it off.
 
 ## Turn timing
 
-After each turn, a dim line such as `✻ Cooked for 5m 12s` reports how long
-it took, with a random verb, as in Claude Code. When background shells are
-still running, the line adds a count. Set `CC_TURN_DURATION=0` to turn it
-off.
+After each turn, a dim line such as `✻ Churned for 6m 59s · done 2:33 PM`
+reports how long it took and when it finished, with a random verb, as in
+Claude Code. The time follows your locale (`LC_ALL`, `LC_TIME` or `LANG`),
+and gains the weekday, then the date, once the turn is a day or a week old.
+When background shells are still running, the line adds a count, as in
+`· 1 shell still running`. Set `CC_TURN_DURATION=0` to turn it off.

package/docs/guide/skills-plugins-and-mcp.md

@@ -11,12 +11,14 @@ manage them.
 An Agent Skill is a packaged set of instructions for a kind of task. One
 Code discovers skills from these places, in order of precedence:
 
-1. `.claude/skills/` in the project
-2. `~/.claude/skills/` and `~/.agents/skills/`
-3. Skills from installed plugins
-4. The bundled catalog
+1. `~/.claude/skills/` and `~/.agents/skills/`, your own skills for every
+   project
+2. `.claude/skills/` and `.agents/skills/` in the project
+3. The bundled catalog
 
-A skill of the same name earlier in the list wins.
+A skill of the same name earlier in the list wins, so your own copy of a
+skill beats the one a repository ships. Skills from installed plugins keep
+their plugin prefix, so they never clash with these.
 
 The model calls a skill with the `skill` tool when a task matches its
 description. You can also run one yourself by typing its name as a slash
@@ -24,6 +26,12 @@ command, as in Claude Code: `/simplify`, `/code-review`, or any skill from
 `.claude/skills/`. Anything after the name is passed to the skill as
 arguments. Plugin skills keep their plugin prefix and are run as
 `/skill:<plugin>:<name>`. pi's `/skill:<name>` form works for every skill.
+The `/` list shows each skill once, by its bare name; type `/skill:` to list
+the `/skill:` forms.
+
+A skill whose frontmatter sets `disable-model-invocation: true` runs only
+when you type its command. As in Claude Code, the model doesn't see it in
+the skills listing, and the `skill` tool refuses it.
 
 A skill's slash command isn't created when the name is already taken by a
 built-in command, a `.claude/commands/` template, or another skill.
@@ -47,14 +55,20 @@ directory, never in the skill files.
 
 ### Bundled skills
 
-Four of Claude Code's built-in skills ship with One Code:
+Six of Claude Code's built-in skills ship with One Code:
 
+- `loop`: run a prompt on an interval, or let the model self-pace it. See
+  [Scheduled wake-ups and loops](tasks-and-background-work.md#scheduled-wake-ups-and-loops).
 - `simplify`: clean up recently changed code for clarity.
-- `code-review`: review changes for correctness bugs.
+- `code-review`: review changes for correctness bugs. Put a level first
+  (`/code-review high`) or let it follow your `/effort`.
 - `security-review`: review changes for security issues.
 - `fewer-permission-prompts`: scan your usage and propose an allowlist.
+- `artifact-design`: the page rules the model follows before publishing an
+  artifact. See [Artifacts](tools.md#artifacts).
 
-A skill of the same name in your own `.claude/skills/` takes precedence.
+A skill of the same name in your user or project skills folder takes
+precedence over the bundled one.
 
 ### Skills not bundled
 
@@ -63,12 +77,12 @@ doesn't have:
 
 | Group | Skills omitted |
 |---|---|
-| Hosted artifacts and design | `design`, `design-sync`, `dataviz`, the `artifact-*` guides, and the dashboard, report, table, explainer, plan, and whiteboard publishers. |
+| Hosted artifacts and design | `design`, `design-sync`, `dataviz`, `artifact-capabilities`, `artifact-diagramming`, and the dashboard, report, table, explainer, plan, and whiteboard publishers. |
 | Claude Code configuration, account, and desktop workflows | `update-config`, `keybindings-help`, `claude-in-chrome`, `debug`, `usage`, `explain-usage`, `setup-cowork`, `schedule` cloud routines, `batch`, and `claude-code-guide`. |
 | Run-skill generation | `run` and `run-skill-generator`. Use project-local run skills instead. |
 | API reference | `claude-api`. |
 
-One Code provides `/init` and `/loop` itself. Commit and pull-request
+One Code provides `/init` itself. Commit and pull-request
 workflows are available through the `commit-commands` plugin.
 
 You can add your own skills under `.claude/skills/`. A skill that requires a
@@ -127,6 +141,15 @@ resources to the model. One Code reads server definitions from:
 - `~/.claude.json` (the `mcpServers` key)
 - `.claude/settings.local.json`
 - Installed plugins
+- pi's own `mcp.json` files: `~/.pi/agent/mcp.json` and the project's
+  `.pi/mcp.json`
+
+One Code takes the place of pi's built-in MCP, so it reads pi's files too.
+If a server has the same name in one of them and in a Claude Code file, the
+Claude Code one wins and One Code tells you. pi's `enabled: false`, a stdio
+server's `cwd` and a leading `~/` work as they do in pi. A server whose `env`
+or `headers` value runs a command (`"!…"`) is skipped with a note, and pi's
+`oauth`, `auth`, `exposure` and `description` settings are ignored.
 
 Definitions may reference environment variables as `$VAR` or `${VAR}` in
 the command, arguments, environment, URL, and headers; an unset variable
@@ -135,20 +158,26 @@ verified; servers using server-sent events are untested.
 
 ### Approve a project's servers
 
-Servers listed in a project's `.mcp.json` run only after you approve them.
+Servers listed in a project's `.mcp.json` or `.pi/mcp.json` run only after
+you approve them.
 On the first start in a project, One Code shows the servers found, with the
-command each one runs, and offers to use this server, to use this and all
-future servers in the project, or to decline. Approvals are stored in
+command each one runs and the environment variables it sets, and offers to
+use this server, to use this and all future servers in the project, or to
+decline. Variables that change what runs, such as `NODE_OPTIONS`, `PATH`,
+`LD_PRELOAD` or `PYTHONPATH`, are shown with their values; for the rest
+only the name is shown, since they usually hold credentials. Approvals are stored in
 `~/.onecode/mcp/project-approvals.json`, tied to the server's
 configuration, so a changed command asks again. If you decline, the server
 appears as disabled in `/mcp`; choosing Enable there approves it.
 
-Claude Code's `enabledMcpjsonServers`, `disabledMcpjsonServers`, and
-`enableAllProjectMcpServers` settings are honored from
-`~/.claude/settings.json`, and from `.claude/settings.local.json` when that
-file isn't tracked by git. They are never honored from a checked-in
-`.claude/settings.json`, which would let a repository approve its own
-servers.
+Claude Code's `enabledMcpjsonServers` and `enableAllProjectMcpServers`
+settings are honored from `~/.claude/settings.json` only.
+`disabledMcpjsonServers` is honored from there and from
+`.claude/settings.local.json`. A project's own settings files never approve
+its servers: a checked-in file, or a `settings.local.json` that arrived
+with a copied checkout, would let the repository approve itself. If Claude
+Code approved a server in `.claude/settings.local.json`, One Code asks you
+once.
 
 In non-interactive runs, unapproved servers are skipped with a note on
 stderr.
@@ -163,6 +192,11 @@ A permission rule naming `mcp__<server>` covers every tool of that server.
 
 ### Manage servers
 
+When servers fail to connect at startup, for example with no network, One
+Code shows a single line such as `2 MCP servers failed · /mcp`, and
+`1 MCP server needs auth · /mcp` for servers waiting on sign-in. Each
+server's error is in `/mcp`.
+
 `/mcp` opens the server manager: servers grouped by source (user, project,
 plugin), each with its status, tool and resource counts, and any warnings.
 **Enter** on a server shows its details and a numbered action list:
@@ -173,6 +207,9 @@ plugin), each with its status, tool and resource counts, and any warnings.
   **Enable** reverses it.
 - **Authenticate** appears for HTTP servers that need OAuth. It opens your
   browser for sign-in; tokens are stored under `~/.onecode/mcp-auth/` with
-  owner-only permissions.
+  owner-only permissions. Tokens belong to the server's URL and headers, not
+  only its name: another server with the same name never receives them, and
+  a server whose URL or headers change asks you to sign in again. Only an
+  `https` sign-in page (or `http` on your own machine) is opened.
 
 Press the action's number to run it, or **Esc** to go back.

package/docs/guide/subagents-and-workflows.md

@@ -14,18 +14,43 @@ main conversation.
 
 ### Where subagents come from
 
-- Three ship with One Code: `general-purpose` (any task), `explore`
-  (read-only search), and `plan` (design an implementation plan).
+- Four ship with One Code: `general-purpose` (any task), `explore`
+  (read-only search), `plan` (design an implementation plan), and
+  `one-code-guide` (questions about One Code itself; see below).
 - Markdown definitions in `.claude/agents/` (project) and
   `~/.claude/agents/` (user), each setting an agent's model, tools, and
   system prompt. A project definition wins over a user definition of the
-  same name.
+  same name. The `tools` and `disallowedTools` lists read as they do in
+  Claude Code: `tools: "*"` means every tool, and an entry written as a
+  rule, such as `Bash(git push:*)`, grants or removes the whole tool.
 - Plugins can add agents, namespaced by plugin.
 - `fork`, a synthetic type that copies the current conversation.
 
 Run `/agents` with no agents running to list the catalog with each agent's
 tools.
 
+### Ask One Code about itself
+
+Ask "can One Code…?" or "how do I…?" and the model hands the question to
+`one-code-guide`, the way Claude Code uses its `claude-code-guide`. The guide
+answers from this user guide, installed with One Code, and from the docs of
+the pi you run, so the answer matches your versions. If pi's docs aren't on
+disk, it reads pi's published docs, which may describe a newer pi. It never
+answers from memory, and it cites the page each fact came from.
+
+It knows your setup too: your custom skills and agents, plugins, MCP
+servers, installed pi packages, and which settings you've changed. When One
+Code can't do what you want, it tells you so and suggests the smallest way
+to get there: an existing setting, a skill, an agent, a hook, an MCP server,
+or a pi extension of your own. For an extension it shows where the file goes
+and how to install it for the way you run One Code, `onecode install` for
+the app or `pi install` on your own pi.
+
+The guide can only read. It uses the shell only for read-only searches,
+never edits anything, and reads its docs without asking. It runs on your
+subagent model. A `one-code-guide.md` in `.claude/agents/` or
+`~/.claude/agents/` replaces it.
+
 ### Run a subagent
 
 The model delegates through the `Agent` tool. You steer it in plain
@@ -44,7 +69,9 @@ the `explore` agent". What happens next:
   too.
 - **A finished agent can be messaged later.** The `SendMessage` tool
   reaches a running agent live, or resumes a finished one from its saved
-  session. `list_agents` lists the session's agents and their status.
+  session. In a `-p` or `--mode json` run, a resumed agent's turn runs to
+  completion and the reply is returned inline. `list_agents` lists the
+  session's agents and their status.
 
 Two options change how a subagent runs:
 
@@ -55,17 +82,19 @@ Two options change how a subagent runs:
   one more, but no further.
 - **Worktree isolation.** The subagent gets its own git worktree, branched
   from `HEAD`, so it can edit files without colliding with your working
-  tree or other agents. A worktree the agent left unchanged is removed;
-  otherwise it's kept and its path reported.
+  tree or other agents. A worktree the agent left unchanged is removed.
+  If the agent edited files or made commits there, the worktree is kept
+  and its path and branch are reported, so no work is lost.
 
 ### Choose the subagent model
 
 Subagents and workflow agents can run on a different model or provider
-from the main session. The default is chosen for you: the cheapest model on
-your provider that meets the same capability floor auto mode's classifier
-uses (a Sonnet-class model for a Sonnet-class or stronger session), never a
-dearer one than your main model. When an Artificial Analysis key is
-configured, measured coding ability is used for that floor; see
+from the main session. The default is chosen for you. For the models people
+use most, a pairing table picks it: an Opus session delegates to Sonnet 5.5,
+a Sonnet 5.5 session to Haiku 5.5, GPT-6.1 Sol to GPT-6 Luna. For other
+models, it's the cheapest model on your provider in your main model's tier or
+above, and cheaper than it; if none costs less, subagents run on your main
+model. See
 [Automatic model selection](providers-and-models.md#automatic-model-selection).
 
 To set the default yourself:
@@ -91,20 +120,37 @@ agent.
 
 ### Follow agents live
 
-While agents run, the panel below the editor shows a tree: `main` first,
-then each agent with its type, what it's doing right now ("Reading
-src/index.ts", "Running a command"), its elapsed time, and its token count.
-Nested agents appear under their parent. A finished agent stays for a few
-seconds.
+While agents run, the panel below the editor shows a list: `main` first,
+then each agent with its type (or its name, for a fork), its description,
+its elapsed time and its token count. Nested agents appear under their
+parent. A finished agent leaves the list, and the panel says
+`/tasks to see subagents` for a few seconds.
 
 - Press **↓** from an empty editor to focus the rows (after the shells
   chip, if background shells exist).
-- **↑** and **↓** select an agent. **Enter** opens its live transcript.
+- **↑** and **↓** select an agent. **Enter** views it.
 - **x** stops the selected agent. **ctrl+x** then **ctrl+k** stops all of
   them.
-- In the transcript: **↑** and **↓** scroll, **PgUp** and **PgDn** page,
-  **Tab** moves to the next agent, **←** returns to the rows, **Enter**
-  closes the view.
+- **Esc** puts you back in the editor and keeps the agent on screen.
+
+### Talk to an agent
+
+Viewing an agent points the editor at it. The editor's border shows the
+agent, the empty editor reads `Message @<agent>…`, and whatever you send
+goes to that agent. If it's working, it picks the message up mid-turn. If
+it's idle, it starts a new turn. Either way, its reply reaches the main
+conversation as a notification, the same as its first report did. The
+agent stays in the panel, marked `idle`, while you have it open. **PgUp**
+and **PgDn** scroll its transcript. To get back, select `main` and press
+**Enter**, or press **Esc** in an empty editor. Slash commands and `!`
+lines still go to the main conversation.
+
+This is also what `f` in the `/btw` panel is for: it turns a side answer
+into a forked agent you can keep talking to.
+
+`/tasks` lists what's running in the background: shells, agents, and the
+finished agents you've viewed. **Enter** opens one, **x** stops a running
+one, **Esc** closes the list.
 
 `/agents` opens the panel on the newest agent.
 
@@ -117,17 +163,27 @@ and relative path then resolves there, and your main working tree stays
 untouched until `exit_worktree` leaves the worktree, keeping or removing
 it. Removal is refused while there is uncommitted or unmerged work. Ask for
 this when a task will make sweeping changes you want to review before
-merging.
+merging. Subagents and workflow agents started while the session is in the
+worktree run there too, and an isolated subagent's own worktree branches
+from the worktree's `HEAD`.
 
 ## Ultracode workflows
 
 For a big job (a broad audit, a migration, a review worth double-checking),
 include the word **`ultracode`** in your message. The model writes a short
 JavaScript script that fans the work out across many agents in parallel,
-then runs it with the `workflow` tool.
-
-The keyword arms the turn it appears in. A message you queue while the
-model is still working doesn't arm the next turn. For a longer stretch of
+then runs it with the `workflow` tool. Before it writes one, it loads the
+bundled `workflow-authoring` skill, the reference for the script API.
+
+By default the model keeps a workflow under 10 agents unless you ask for
+more. Change that with `workflowSizeGuideline`, or turn workflows off with
+`disableWorkflows`; both go in One Code's settings
+([Configuration](configuration.md#settings-reference)).
+
+The keyword arms the turn it appears in. That includes a message you
+queue while the model is still working: it arms once the model gets to
+your message. (Queued messages need pi 0.86 or later; the `onecode` app
+ships with it.) For a longer stretch of
 this kind of work, turn the mode on with `/effort ultracode`: it sets the
 reasoning effort to `xhigh` and keeps workflow orchestration armed until
 you change the effort again. The footer shows `✦ ultracode` while it's
@@ -151,8 +207,16 @@ armed.
 - Fan-out agents use the subagent default model, so a cheap subagent tier
   keeps a large run affordable while the main conversation stays on a
   frontier model.
+- Workflow agents get the tools a subagent gets, your MCP servers
+  included. An agent call that names an agent type follows that agent
+  file's `tools` and `disallowedTools`, as a subagent does.
 - In a `-p` or `--mode json` run, the workflow runs to completion and
   returns its result inline.
+- An agent the script runs with `isolation: 'worktree'` gets its own
+  worktree, like a subagent. If the agent leaves changes or commits there,
+  even when it fails, the worktree is kept: its path shows in the progress
+  strip and the agent's detail pane, and the final report lists every kept
+  worktree with its branch.
 
 ### The run viewer
 
@@ -184,12 +248,14 @@ the current run's script there.
 
 `/effort` sets how much reasoning the model spends: `off`, `minimal`,
 `low`, `medium`, `high`, `xhigh`, `max`, or `ultracode`. A bare `/effort`
-opens a slider (**←** and **→** or **h** and **l** move, **Enter** confirms).
+opens a slider (**←** and **→** or **h** and **l** move, **Enter** confirms,
+**s** applies the level to this session only).
 Levels the current model doesn't support are skipped. **shift+tab** cycles
 the plain levels; cycling away from `xhigh` while ultracode is armed turns
 ultracode off.
 
 Changing the effort re-caches the conversation, so the next request costs
-more than usual. `/effort` doesn't save the level across restarts; to
-save one, open pi's `/thinking` picker and press **ctrl+s**, or pass
-`--thinking <level>` at launch.
+more than usual. `low`, `medium`, `high` and `xhigh` are saved for the
+current model, so a new session on that model starts there; `max` and
+`ultracode` last for this session only. `/effort auto` clears the saved
+level, and `--thinking <level>` at launch overrides it.