one-code-extension 0.3.0 → 0.4.0

package/docs/guide/doctor.md

@@ -1,5 +1,7 @@
 # Check your setup with doctor
 
+[← One Code user guide](README.md)
+
 `/doctor` is One Code's health check, modelled on Claude Code's. It measures
 your setup, reports what a session will use, and can have the model repair
 the findings.
@@ -18,7 +20,7 @@ the findings.
 ## What the report contains
 
 1. **Installation.** Whether you run the bundled app or the extension on
-   your own pi, the pi version and whether it is in the tested range, the
+   your own pi, the pi version and whether it's in the tested range, the
    Node version and platform, pi's agent directory, One Code's state
    directory, where Claude Code configuration is read from, and whether a
    newer One Code is available.
@@ -47,12 +49,12 @@ Findings are listed first, errors before warnings, each with a suggested
 fix. The report is "ready" when at least one provider works, a model is
 selected, and there are no errors.
 
-In the panel, press **f** to run the checkup on the report you are reading.
+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 are connected to. Only current-generation,
+together, from the provider you're connected to. Only current-generation,
 priced models that support tool calls are considered.
 
 | Preset | Main model | Subagents | Classifier |

package/docs/guide/hooks.md

@@ -1,5 +1,7 @@
 # Hooks
 
+[← One Code user guide](README.md)
+
 Hooks are shell commands that run at fixed points in a session. One Code
 runs Claude Code's command hooks from your existing settings files, with
 the same input, output, and exit-code contract, so hooks you wrote for
@@ -39,8 +41,8 @@ Only command hooks are supported. Hook entries of type `http`, `prompt`, or
 | `PostCompact` | After context compaction, with the summary. |
 
 Claude Code's `Notification`, `SubagentStop`, and `PermissionRequest`
-events are not supported. pi has no event that carries the notification
-concept, and the other two are not implemented.
+events aren't supported. pi has no event that carries the notification
+concept, and the other two aren't implemented.
 
 Hooks also run inside subagents: a `PreToolUse` hook that blocks a command
 blocks it in a subagent too.
@@ -55,7 +57,7 @@ The hook's standard input is a JSON object with these fields:
 | Field | Present | Meaning |
 |---|---|---|
 | `session_id` | Always | The session id. |
-| `transcript_path` | Always | The session file, or an empty string when there is none. |
+| `transcript_path` | Always | The session file, or an empty string when there's none. |
 | `cwd` | Always | The working directory. |
 | `hook_event_name` | Always | The event name from the table. |
 | `tool_name`, `tool_input` | Tool events | The tool and its arguments. Tool names are One Code's names; see [Claude Code tool names](tools.md#claude-code-tool-names). |
@@ -90,7 +92,7 @@ Envelope fields honored in a JSON result:
 |---|---|
 | `continue: false` | Blocks, with `stopReason` as the reason. |
 | `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 cannot pre-approve an action, and the permission gate still runs. |
+| `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`). |
 | `hookSpecificOutput.updatedToolResult` | Replaces the tool's result (`PostToolUse`). |
 | `hookSpecificOutput.additionalContext` | Adds text to the model's context. |
@@ -105,5 +107,17 @@ Set `CC_HOOKS_DEBUG=1` before launching to print each hook dispatch and its
 outcome to stderr. Decisions are also appended to
 `~/.onecode/hooks/hooks-decisions.jsonl` while the variable is set.
 
-Hooks run through `/bin/sh`. On native Windows this path does not exist,
-which is one reason native Windows is unsupported; use WSL.
+## Which shell runs a hook
+
+Hooks run in bash, as in Claude Code: `/bin/bash` on macOS and Linux, Git
+Bash on Windows (`CLAUDE_CODE_GIT_BASH_PATH` points at a different bash;
+a value that isn't a bash or sh binary is ignored with a warning). A hook
+can ask for PowerShell instead with Claude Code's `shell` field:
+
+```json
+{ "type": "command", "command": "Get-Content $env:TEMP\\hook.log", "shell": "powershell" }
+```
+
+On a Windows machine without Git for Windows, hooks default to PowerShell.
+Matchers accept `Bash|PowerShell` and `Bash,PowerShell` to cover both shell
+tools. See [Windows](windows.md).

package/docs/guide/installation.md

@@ -1,19 +1,24 @@
 # Install One Code
 
+[← One Code user guide](README.md)
+
 One Code ships as two npm packages from one repository. Choose the one that
 fits how you already work.
 
 | You | Install | What you get |
 |---|---|---|
 | New to this, or you want the simplest setup | `npm install -g @one-ai/one-code` | The bundled app: its own `onecode` command, a pinned version of the pi coding agent inside it, and its state kept in `~/.onecode`. It coexists with any `pi` you already have. |
+| On Windows without Node.js | `powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 \| iex"` | The bundled app, with Node.js fetched for you when the machine has none. See [Install on Windows](#install-on-windows). |
 | Already running [pi](https://github.com/earendil-works/pi) | `pi install npm:one-code-extension` | The extensions only. They run on your existing pi. One Code's own state still goes to `~/.onecode`; pi's own files stay under your pi agent directory (`~/.pi/agent`). |
 
 ## Requirements
 
 - Node.js 22.19 or later. The app refuses to start on older versions,
   because pi crashes at import time there.
-- macOS or Linux. Windows Subsystem for Linux (WSL) works the same way.
-  Native Windows is untested and unsupported.
+- macOS, Linux, or Windows. Windows Subsystem for Linux (WSL) works like
+  Linux. On native Windows, One Code takes Claude Code's shape: Git for
+  Windows is recommended but optional, and PowerShell is the primary shell
+  tool. See [Windows](windows.md) for what is verified and what isn't.
 - `git`. Optional: `rg` (ripgrep) for faster search, the GitHub CLI for the
   pull-request marker in the footer, and a language server for your
   language (see
@@ -27,7 +32,7 @@ cd your-project
 onecode
 ```
 
-On the first run there is no provider yet: the banner shows `model none`.
+On the first run there's no provider yet: the banner shows `model none`.
 Run `/login` inside One Code to connect a provider, or set a provider key
 in your environment before launching. For a free option, see
 [Providers and models](providers-and-models.md).
@@ -36,15 +41,55 @@ The first run also seeds pi's settings under `~/.onecode/agent/` with the
 `onecode` theme, quiet startup, and full-screen mode. It never overrides a
 value you change later.
 
+## Install on Windows
+
+Open Windows Terminal or PowerShell and run:
+
+```powershell
+powershell -c "irm https://raw.githubusercontent.com/IsuruMaduranga/one-code/master/install.ps1 | iex"
+```
+
+The script looks for Node.js 22.19 or later on your PATH. When there is
+none, it downloads the current Node LTS for your CPU from nodejs.org as a
+zip, checks it against nodejs.org's published checksums, unpacks it under
+`%LOCALAPPDATA%\onecode\node`, and adds that folder to your user PATH.
+Nothing is installed system-wide and no Windows installer runs. It then
+runs `npm install -g @one-ai/one-code` and makes sure the `onecode` command
+is on your PATH. Open a new terminal afterwards so it sees the PATH change.
+
+The script also tells you when `git` is missing. One Code runs without it,
+but Git for Windows gives you the branch in the footer, `/init`, worktrees,
+and a bash tool for the model next to PowerShell. Install it with
+`winget install --id Git.Git -e`, or set `ONECODE_INSTALL_GIT=1` before
+running the script to have it do that for you.
+
+If you already have Node.js 22.19 or later, the plain npm command works the
+same on Windows as anywhere else:
+
+```powershell
+npm install -g @one-ai/one-code
+```
+
+The script's knobs are environment variables, because a piped script
+cannot take parameters: `ONECODE_INSTALL_NODE=1` downloads the standalone
+Node even when one exists, `ONECODE_NODE_VERSION` pins the version it
+downloads, and `ONECODE_NO_PATH_UPDATE=1` leaves your PATH alone and prints
+what to add. Read the script before running it if you like; it is the
+`install.ps1` at the root of the repository.
+
+Windows Subsystem for Linux (WSL) is Linux: use the npm or Homebrew route
+inside the distribution. For what works on native Windows, see
+[Windows](windows.md).
+
 ## Install with Homebrew
 
 Homebrew installs Node for you, so this route has no separate Node step:
 
 ```bash
-brew install isurumaduranga/one-ai/one-code
+brew install isurumaduranga/one-ai/onecode
 ```
 
-The formula is named `one-code`; the command it installs is `onecode`.
+The formula and the command it installs are both named `onecode`.
 Homebrew refuses npm packages published less than a day ago, so a release
 becomes installable this way about a day after it appears on npm.
 
@@ -57,12 +102,12 @@ 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.85 and warns at startup when
+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).
 
 A few interface refinements are applied only by the bundled app, because
-they patch pi internals the extension API cannot reach: a clean exit that
+they patch pi internals the extension API can't reach: a clean exit that
 erases the screen in regular mode, and suppression of pi's "Operation
 aborted" line when you interrupt a reply. Everything else is identical.
 
@@ -97,10 +142,13 @@ notice with the matching upgrade command when a newer version exists:
 
 ```bash
 npm install -g @one-ai/one-code      # npm installs
-brew upgrade one-code                # Homebrew installs
+brew upgrade onecode                 # Homebrew installs
 ```
 
-Set `ONECODE_NO_UPDATE_CHECK=1` to skip the check; `--offline` skips it too.
+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`.
 
 Both packages are released together with the same version number.
@@ -108,12 +156,14 @@ Both packages are released together with the same version number.
 ## Uninstall
 
 ```bash
-npm uninstall -g @one-ai/one-code    # or: brew uninstall one-code
+npm uninstall -g @one-ai/one-code    # or: brew uninstall onecode
 rm -rf ~/.onecode                    # One Code's state, including pi's under the app
 ```
 
-On your own pi, run `pi remove one-code-extension` (or remove the package
-entry from pi's settings). Removing `~/.onecode` deletes One Code's
+If the Windows script fetched Node.js for you, delete `%LOCALAPPDATA%\onecode`
+too and remove that folder from your user PATH. On your own pi, run
+`pi remove one-code-extension` (or remove the package entry from pi's
+settings). Removing `~/.onecode` deletes One Code's
 settings, approvals, plan files, and, under the bundled app, pi's sessions
 and credentials. Memory files stay in `~/.claude/projects/`, because they
 are shared with Claude Code.

package/docs/guide/permissions-modes-and-auto-mode.md

@@ -1,5 +1,7 @@
 # Permissions, modes, and auto mode
 
+[← One Code user guide](README.md)
+
 Every tool call the model makes passes through One Code's permission gate
 before it runs. This page explains the permission modes, how to switch
 between them, how to write rules, what the approval prompt offers, and how
@@ -16,7 +18,7 @@ For each tool call, the gate checks the following in order:
 1. **Protected paths.** A write to a protected file or directory (see
    [Protected paths](#protected-paths)) is never approved automatically. In
    auto mode it goes to the classifier; in other modes it prompts you.
-   Allow rules do not cover protected paths.
+   Allow rules don't cover protected paths.
 2. **`deny` rules.** A matching `deny` rule blocks the call. `deny` always
    wins.
 3. **`ask` rules.** A matching `ask` rule prompts you, even in a mode that
@@ -81,6 +83,18 @@ contains command substitution (`$(…)` or backticks), `eval`, `exec`, a pipe
 into an interpreter, or a base64 decode is never covered by a prefix or
 wildcard `allow` rule.
 
+### PowerShell rule patterns
+
+`PowerShell(...)` rules have the same shape and follow Claude Code's
+PowerShell matching: aliases are canonicalized on both sides
+(`PowerShell(Remove-Item:*)` catches `rm`, `del`, and `ri`), cmdlet names
+are case-insensitive, a line is split on `|`, `;`, `&&`, `||`, and newlines
+outside quotes and here-strings, an `allow` rule must cover every statement,
+and a `deny` or `ask` rule fires on any statement. A `$(…)` subexpression, a
+backtick escape, a script block, the `&`/`.` call operators,
+`Invoke-Expression`, or an encoded command keeps a wildcard `allow` from
+applying. Details in [Windows](windows.md#permission-rules).
+
 ### Add a rule during a session
 
 To add an allow rule for the current repository, run:
@@ -96,7 +110,7 @@ Add `global` at the end to save it for every repository instead:
 ```
 
 To review the current mode and every loaded rule, including which project
-rules are trusted and which rules could not be parsed, run `/permissions`.
+rules are trusted and which rules couldn't be parsed, run `/permissions`.
 
 Rules One Code adds are saved under `~/.onecode`, never under `~/.claude`.
 
@@ -104,7 +118,7 @@ Rules One Code adds are saved under `~/.onecode`, never under `~/.claude`.
 
 A mode sets the default answer for actions no rule covers. **Auto is the
 default**, matching Claude Code: a classifier approves routine actions and
-stops risky ones, so you are not prompted for every step.
+stops risky ones, so you're not prompted for every step.
 
 | Mode | Badge | What it does |
 |---|---|---|
@@ -118,10 +132,10 @@ stops risky ones, so you are not prompted for every step.
 The current badge appears in the banner and is announced when the mode
 changes.
 
-### Cycle modes with ctrl+q
+### Cycle modes with ctrl+q (alt+m on Windows and WSL)
 
-Press **ctrl+q** to cycle through manual, accept edits, plan, and auto.
-Two modes join the cycle only under conditions:
+Press **ctrl+q** to cycle through manual, accept edits, plan, and auto. On
+Windows and WSL the key is **alt+m**. Two modes join the cycle only under certain conditions:
 
 - **Auto** appears only when a model that can run the classifier is
   available. With no provider connected, the cycle skips it.
@@ -130,10 +144,11 @@ Two modes join the cycle only under conditions:
 **Don't ask** is never in the cycle; reach it with the `--permission-mode`
 flag or a settings file.
 
-Claude Code cycles modes with shift+tab. One Code cannot use that key
+Claude Code cycles modes with shift+tab. One Code can't use that key
 because pi reserves it for the reasoning-effort dial. On Windows and WSL,
-pi's own default keybindings also use ctrl+q to queue a follow-up message.
-If the two conflict there, change pi's binding in its keybindings file.
+pi's own default keybindings use ctrl+q to queue a follow-up message, so
+One Code cycles modes with alt+m there instead. The footer badge and the
+startup hints name whichever key applies on your machine.
 
 ### Choose the starting mode
 
@@ -160,12 +175,12 @@ Claude Code settings files. Merge this into the existing object:
 }
 ```
 
-The scopes are not equal:
+The scopes aren't equal:
 
 - **User scope** (`~/.claude/settings.json`) and **managed settings** can
   set any mode.
 - **Project scope** (`.claude/settings.json` and `.claude/settings.local.json`)
-  can set `default`, `acceptEdits`, `plan`, or `dontAsk`. It cannot set
+  can set `default`, `acceptEdits`, `plan`, or `dontAsk`. It can't set
   `auto` or `bypassPermissions`; a checked-in file must not be able to turn
   off approvals for whoever clones it.
 - A `defaultMode` in `~/.onecode/settings.json` has no effect.
@@ -198,7 +213,7 @@ and these choices:
 - **No, tell the agent what to do differently.** Deny it, with an optional
   note that is passed to the model as the reason.
 
-The "don't ask again" option is not offered for protected paths, for writes
+The "don't ask again" option isn't offered for protected paths, for writes
 that the auto-mode safety floor caught, or in auto mode. Session grants never
 apply in auto mode and are cleared when the session ends.
 
@@ -214,7 +229,10 @@ Reads and edits are confined to the working directory by default:
   mode, and is denied in don't-ask mode.
 - Accept-edits mode approves edits only inside the working directory.
 - The harness's own session directories count as inside: the auto-memory
-  folder, the session scratchpad, persisted tool output, and the plan file.
+  folder, the session scratchpad, persisted tool output, the plan file, and
+  this project's own session transcripts (with auto mode's decision log next
+  to them), which is what `/doctor` reads. Other projects' transcripts are
+  outside, as they are for Claude Code.
 
 Paths are compared after resolving symlinks, so a symlink inside the project
 that points outside it counts as outside.
@@ -226,7 +244,7 @@ check and always goes to the classifier.
 ## Protected paths
 
 Writes to these paths are never approved automatically in any mode other
-than bypass, and allow rules do not cover them.
+than bypass, and allow rules don't cover them.
 
 Protected directories, including everything inside them:
 
@@ -285,7 +303,7 @@ code. Only read-only tools and edits to one plan file are available.
   `plan` agent, and then write the plan.
 - You can read and edit the plan file yourself while the model works.
 
-Enter plan mode by cycling to it with **ctrl+q**, by starting with
+Enter plan mode by cycling to it with **ctrl+q** (**alt+m** on Windows and WSL), by starting with
 `--permission-mode plan`, or by asking the model to plan first (it can call
 `enter_plan_mode` itself).
 
@@ -300,11 +318,11 @@ shows the plan. Nothing runs until you choose. The choices are:
 5. **Keep planning.** No mode change; the model refines the plan file.
 
 The initial highlight is the option that restores your previous mode, or
-manual mode when that is not offered. It never lands on a more permissive
+manual mode when that isn't offered. It never lands on a more permissive
 option by default. Press the number of a choice to pick it directly, or
 **Esc** to keep planning.
 
-In a non-interactive run there is no one to approve, so `exit_plan_mode`
+In a non-interactive run there's no one to approve, so `exit_plan_mode`
 refuses and the session stays in plan mode with the plan on disk.
 
 ## Auto mode
@@ -317,20 +335,20 @@ classifier.
 
 - Actions a deterministic analysis proves safe. Read-only shell commands
   inside the working directory are the common case. This analysis can only
-  ever conclude "safe"; anything it cannot parse or recognize goes to the
+  ever conclude "safe"; anything it can't parse or recognize goes to the
   classifier rather than through.
 - Edits and writes to files inside the project that are not credential
   files, not protected paths, and not files that run code on their own
   (build wrappers, CI workflows, editor auto-run configuration).
 - Deleting or resetting files inside the project **when git can recover
   them**. A tracked, committed file can be restored, so removing it is
-  approved. An untracked or modified file cannot, so removing it goes to
+  approved. An untracked or modified file can't, so removing it goes to
   the classifier. Claude Code trusts the whole project directory here; One
   Code checks recoverability first.
 
 ### What goes to the classifier
 
-Everything else: destructive commands git cannot undo, anything that
+Everything else: destructive commands git can't undo, anything that
 reaches outside the project, network-affecting commands, writes to
 protected paths, and reads outside the working directory.
 
@@ -342,21 +360,21 @@ The classifier is Claude Code's two-stage ruleset, embedded verbatim:
    stated intent and the allow list, and either approves or blocks with a
    named rule.
 
-Verdicts are checked before they are acted on. A block must cite a real
+Verdicts are checked before they're acted on. A block must cite a real
 rule from the ruleset. An approval based on intent must quote your own
-words from the conversation. A classifier that cannot be reached, times
-out, or returns something unparseable blocks the action; a gate that cannot
+words from the conversation. A classifier that can't be reached, times
+out, or returns something unparseable blocks the action; a gate that can't
 consult its classifier approves nothing.
 
 A blocked action is reported to the model with the reason so it can choose
-a safer route. You are not prompted per action while auto mode runs. After
+a safer route. You're not prompted per action while auto mode runs. After
 repeated blocks in a row, auto mode pauses and the next action prompts you;
 approving it resumes auto mode.
 
 Allow rules that are broad enough to pre-approve arbitrary execution, such
 as `Bash(*)`, a wildcarded interpreter, or a rule that allows delegation to
-subagents, are suspended in auto mode so they cannot bypass the classifier.
-Session grants from the approval prompt do not apply in auto mode either.
+subagents, are suspended in auto mode so they can't bypass the classifier.
+Session grants from the approval prompt don't apply in auto mode either.
 
 ### The classifier model
 
@@ -427,13 +445,13 @@ One Code's security model is the permission gate plus auto mode, not an
 assumption that the model behaves. Read these facts before you leave a
 session unattended:
 
-- **There is no operating-system sandbox.** The gate decides whether a
+- **There's no operating-system sandbox.** The gate decides whether a
   command runs; nothing constrains what an approved command can touch. For
   an OS-level wall, run One Code inside a container. The gate and the
   container work together.
 - **Bypass mode bypasses everything**, including protected paths. Claude
   Code keeps its protected-path checks active even under
-  `--dangerously-skip-permissions`; One Code does not.
+  `--dangerously-skip-permissions`; One Code doesn't.
 - **Auto mode is the default without a first-run consent step**, and
   without the OS sandbox Claude Code pairs its own auto default with.
 - **A weak classifier is a weaker boundary.** Automatic selection applies a

package/docs/guide/providers-and-models.md

@@ -1,5 +1,7 @@
 # Providers and models
 
+[← One Code user guide](README.md)
+
 One Code talks to each model provider natively, so you choose the provider
 and the model, and you can change either one during a session. This page
 covers connecting a provider, storing a key, switching models, how One Code
@@ -31,8 +33,8 @@ Two providers hand out free models you can try at no cost:
   a key, or sign in from inside One Code with no key copying. Free models
   carry a `:free` suffix, such as `nvidia/nemotron-3-ultra-550b-a55b:free`.
 
-Credentials are stored by pi in its agent directory (`~/.onecode/agent/`
-under the bundled app). `/logout` removes them.
+pi stores credentials in its agent directory (`~/.onecode/agent/` under
+the bundled app). `/logout` removes them.
 
 ## Store keys as environment variables
 
@@ -100,10 +102,10 @@ otherwise to the matching class within your provider (`haiku` the cheapest
 capable model, `sonnet` the cheapest Sonnet-class model, `opus` and `fable`
 your main model). They never switch providers.
 
-Capability is judged by tier (see the next section). Models are excluded
-when they cannot call tools, have no price, or are a generation behind: a
-model released more than a year after its vendor's newest is demoted one
-tier, and one more than two years behind is never picked automatically.
+Capability is judged by tier (see the next section). One Code excludes
+models that can't call tools, have no price, or are a generation behind: a
+model released more than a year after its vendor's newest drops one tier,
+and one more than two years behind never gets picked automatically.
 Provider aliases such as `:free` or `:online` variants are skipped.
 
 ### Measured selection with Artificial Analysis
@@ -148,8 +150,8 @@ the system prompt to match:
 | Cheap | Haiku-class models and comparable "flash", "mini", or "small" models. | The verbose prompt Claude Code gives Haiku. |
 | Tiny | Sub-Haiku models. | The verbose prompt plus extra scaffolding and the `grep`, `find`, and `ls` tools. |
 
-The tier is derived from the model's name, release date, and price. You do
-not configure it; set `CC_PROMPT_TIER` to force one when you want to
+The tier is derived from the model's name, release date, and price. You
+don't configure it; set `CC_PROMPT_TIER` to force one when you want to
 experiment. `/doctor report` shows the tier in use.
 
 ## Web search on providers without a search API
@@ -161,7 +163,7 @@ API, in this order:
 
 1. **Brave Search**, when `BRAVE_SEARCH_API_KEY` is set.
 2. **Tavily**, when `TAVILY_API_KEY` is set.
-3. **Exa's free keyless endpoint**, when neither key is set. It is
+3. **Exa's free keyless endpoint**, when neither key is set. It's
    rate-limited and best-effort, so One Code warns you the first time a
    session uses it and labels every result that came from it.
 
@@ -187,7 +189,7 @@ so. Web fetch works on every provider; it never depends on a search API.
 - Some models reject request options others accept (a temperature, a
   reasoning setting). One Code sends minimal options to its side calls for
   this reason, and a side call that still fails does so loudly: a
-  classifier that cannot answer blocks the action; a reader that fails
+  classifier that can't answer blocks the action; a reader that fails
   returns the raw page.
 - Interactive sessions request the provider's extended prompt cache (one
   hour on Anthropic). Subagents and one-shot runs use the short default.

package/docs/guide/reference.md

@@ -1,5 +1,7 @@
 # Command and keyboard reference
 
+[← One Code user guide](README.md)
+
 A lookup for every slash command, keyboard shortcut, command-line flag,
 environment variable, and file location. Each entry points to the page
 that explains it.
@@ -47,7 +49,7 @@ that explains it.
 | `/loop status`, `/loop stop` | Report or end the 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`). | [Sessions](sessions-and-context.md#start-over) |
+| `/clear` | Start a new session (pi's `/new`); the model is told. | [Sessions](sessions-and-context.md#start-over) |
 | `/exit` | Quit (pi's `/quit`). | |
 
 ### pi commands
@@ -83,7 +85,7 @@ These come from pi and are available in every One Code session.
 
 | Shortcut | What it does |
 |---|---|
-| **ctrl+q** | Cycle the permission mode: manual, accept edits, plan, auto. |
+| **ctrl+q** (**alt+m** on Windows and WSL) | Cycle the permission mode: manual, accept edits, plan, auto. |
 | **↓** (empty editor) | Focus the panel below the editor: background shells, then subagents, then workflows. |
 | **ctrl+x** then **ctrl+k** | Stop every running agent (in the subagent panel). |
 | **x** | Stop the selected agent, shell, or workflow (in a panel). |
@@ -122,7 +124,7 @@ Rebind keys in pi's keybindings file; see pi's documentation.
 ## Command-line flags
 
 `onecode` forwards every flag to pi except `--version` and `doctor`. On the
-extension installation, use `pi` in place of `onecode`.
+extension install, use `pi` in place of `onecode`.
 
 | Flag | What it does |
 |---|---|
@@ -157,7 +159,7 @@ Set these before launching.
 |---|---|
 | `ONECODE_STATE_DIR` | Where One Code keeps its state (default `~/.onecode`). Independent of pi's agent directory. |
 | `ONECODE_NO_UPDATE_CHECK=1` | Skip the daily update check. |
-| `ONECODE_DEBUG=1` | Report when a pi-internal patch in the bundled app did not apply. |
+| `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. |
 
@@ -173,6 +175,7 @@ The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
 | `CC_FOOTER=0` | Keep pi's footer instead of One Code's status line. |
 | `CC_TURN_DURATION=0` | Remove the post-turn timing line. |
 | `CC_RECAP=0` | Turn off the "while you were away" recap. |
+| `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_CLEAR_THINKING=0`, `=1` | Force the thinking-preservation request off or on for Anthropic models. Default: on for `api.anthropic.com` only. |
@@ -192,6 +195,8 @@ The `CC_` prefix is historical; `ONECODE_`-prefixed aliases are planned.
 | `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. |
+| `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. |
 | `EDITOR`, `VISUAL` | Editor used by `/memory` (and pi's **ctrl+g**). |
 | `SHELL` | Shell used for commands (default `/bin/sh`). |

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

@@ -1,5 +1,7 @@
 # Sessions and context
 
+[← One Code user guide](README.md)
+
 This page covers what One Code puts into the model's context, how it keeps
 long sessions within the context window, what it remembers between
 sessions, and how to continue or branch a session.
@@ -82,7 +84,7 @@ full transcript if it needs a detail.
 Run `/compact` to compact at any time; you can pass instructions about what
 the summary should focus on. Compaction that happens because the context is
 full is more expensive than a manual or threshold compaction, because it
-cannot reuse the cached prefix of the conversation.
+can't reuse the cached prefix of the conversation.
 
 Set `CC_COMPACTION=0` to use pi's own summary instead.
 
@@ -107,7 +109,7 @@ turn it off.
 
 Interactive sessions ask the provider for an extended cache lifetime (one
 hour on Anthropic; provider-dependent elsewhere), so a pause between turns
-does not re-send the whole conversation. Subagents, workflow agents, and
+doesn't re-send the whole conversation. Subagents, workflow agents, and
 `-p` or `--mode json` runs use the provider's short default. Set
 `PI_CACHE_RETENTION` yourself to take over the choice. The footer shows the
 cache-hit rate of the latest turn.
@@ -121,7 +123,7 @@ 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 is not truncated. It is written to a file
+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.
@@ -182,6 +184,24 @@ Not restored:
 `/new`. Running background tasks are stopped and listed. The permission
 mode you chose carries over.
 
+### What the model learns about your commands
+
+As in Claude Code, a slash command you run is recorded for the model: the
+next message you send carries a short note that the command ran, wrapped in a
+caveat telling the model not to act on it. `/clear` opens the new session
+with that note, and a model switch records "Set model to …" the way Claude
+Code does. Commands that One Code cannot observe (pi's own `/compact`,
+`/settings`, `/name`) leave no note.
+
+### The session title
+
+After your first real message, One Code names the session the way Claude
+Code does: a cheap model on your provider turns the message into a short
+title (Claude Code's own naming prompt), which shows in the terminal tab as
+`One Code - <title> - <folder>` and in the session picker. A name you set
+with `/name` is never overwritten. The call's cost is included in the
+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