one-code-extension 0.3.0 → 0.3.1

package/README.md

@@ -1,23 +1,16 @@
 # One Code
 
-**A familiar Claude Code experience, with your choice of model for every agent.**
+**Claude Code with the model slot left open. The full workflow, open source, on any model or provider.**
 
-One Code brings familiar Claude Code workflows to a terminal coding agent that
-lets you choose the models. It includes subagents, plan mode, permissions,
-skills, and git worktrees. Reuse your existing Claude Code setup, keep a capable model
-in the main conversation, delegate routine work to a cheaper one, and switch
-providers during a session.
+Claude Code is a good harness. It just ships bolted to one model. One Code
+unbolts it, and runs the whole workflow (subagents, git worktrees, auto mode,
+ultracode workflows, plan mode) on the model you pick. Keep Claude Code for the
+work that earns its best model. Reach for One Code whenever a cheaper or
+different model fits the job.
 
-- **Bring your setup.** Reuse `CLAUDE.md`, skills, commands, subagents, hooks,
-  permission rules, and MCP configuration.
-- **Choose models per task.** The main session and its subagents can use
-  different models and providers: Anthropic, OpenAI, Gemini, OpenRouter, or
-  local models supported by [pi](https://github.com/earendil-works/pi).
-- **Keep control as work grows.** Plan before editing, isolate changes in git
-  worktrees, and follow parallel agents from a live progress panel.
-
-Built on pi. Free and open source under the MIT license. Works alongside
-Claude Code, with the bundled app's state kept in `~/.onecode`.
+The parts that make the harness good (the steering, the permission gate, the
+context management) live in the harness, not the model. One Code brings all of
+them across, because the good part was never the logo.
 
 <p align="center">
   <img src="demo/onecode.gif" alt="One Code switching models and running an agentic task" width="820">
@@ -28,10 +21,30 @@ Claude Code, with the bundled app's state kept in `~/.onecode`.
 [Differences from Claude Code](docs/guide/differences-from-claude-code.md) ·
 [Command reference](docs/guide/reference.md)
 
-## Get started
-
-Requires **Node.js 22.19+**. Developed and verified on **macOS and Linux**;
-WSL is also supported. Native Windows is currently untested.
+## ✨ What you get
+
+- **Any model, any provider.** Anthropic, OpenAI, Gemini, OpenRouter, or a
+  local model. Bring your own and switch mid-session with `/model`. Nothing
+  stops you.
+- **Mix providers in one session.** The parent and each subagent pick their own
+  model and provider, so an ultracode workflow can fan out to a cheap tier while
+  the parent stays on a frontier model. A single-gateway setup cannot do this,
+  which is usually the reason people switch.
+- **Your Claude Code setup runs unchanged.** `CLAUDE.md`, `.claude/commands`,
+  `.claude/skills`, `.claude/agents`, `.mcp.json`, plugins, and permission rules
+  are picked up as they are. No migration, and no second config file to keep in
+  sync.
+- **Capability-tiered prompting.** A weaker model gets more guidance, not less.
+  Not out of politeness; it is how you get output you can use.
+- **A package, not a fork.** One Code is a [pi](https://github.com/earendil-works/pi)
+  package, so you extend it with your own extensions, themes, and settings.
+  Forks go stale; packages do not have to.
+- **Free and open source** under the MIT license.
+
+## 🚀 Get started
+
+You need **Node.js 22.19+**. One Code is developed and verified on macOS and
+Linux; WSL works too. Native Windows is untested.
 
 ```bash
 npm install -g @one-ai/one-code
@@ -39,51 +52,50 @@ cd your-project
 onecode
 ```
 
-Inside One Code, run `/login` to connect a provider, then `/model` to choose a
-model. You can also supply a provider key through an environment variable such
-as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
+Inside One Code, run `/login` to connect a provider, then `/model` to pick a
+model. You can also pass a provider key through an environment variable such as
+`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `OPENROUTER_API_KEY`.
 
-Open a project with an existing `CLAUDE.md` or `.claude/` setup to reuse it
-immediately. For a new project, `/init` drafts a `CLAUDE.md`.
+Open a project that already has a `CLAUDE.md` or `.claude/` setup and One Code
+reuses it right away. Starting fresh? `/init` drafts a `CLAUDE.md` for you.
 
-Not sure what is ready? `onecode doctor` (or `/doctor report` inside a session)
-reports which providers have credentials, which model each role will use, what
-of your Claude Code configuration was picked up, and which programs are missing;
-`/doctor` runs the full checkup, where the model repairs the findings.
+Not sure what is wired up? Run `onecode doctor` (or `/doctor report` inside a
+session). It reports which providers have credentials, which model each role
+uses, what of your Claude Code configuration was picked up, and which programs
+are missing. `/doctor` runs the full checkup and has the model fix what it finds.
 
-One Code is free; model access, usage charges, and rate limits depend on your
-provider. See [Providers and models](docs/guide/providers-and-models.md) for
-connection options.
+One Code is free. Model access, usage charges, and rate limits are between you
+and your provider. See [Providers and models](docs/guide/providers-and-models.md)
+for connection options.
 
 ### Other ways to install
 
 **Homebrew** installs Node for you:
 
 ```bash
-brew install isurumaduranga/one-ai/one-code
+brew install isurumaduranga/one-ai/onecode
 ```
 
-**Already using pi?** Add the extensions to your existing installation:
+**Already on pi?** Add the extensions to your existing installation:
 
 ```bash
 pi install npm:one-code-extension
 ```
 
 The app package, [`@one-ai/one-code`](https://www.npmjs.com/package/@one-ai/one-code),
-bundles a pinned pi version and provides the `onecode` command. The extension
-package, [`one-code-extension`](https://www.npmjs.com/package/one-code-extension),
-runs on your own pi and is tested against pi 0.83–0.85. Use `pi` in place of
-`onecode` for that installation.
+bundles a pinned pi and gives you the `onecode` command. The extension package,
+[`one-code-extension`](https://www.npmjs.com/package/one-code-extension), runs on
+your own pi and is tested against pi 0.83 to 0.85; use `pi` in place of `onecode`
+for that install.
 
 The app opens in a full-screen terminal interface by default. See the
-[installation guide](docs/guide/installation.md) for display settings and more
-details.
+[installation guide](docs/guide/installation.md) for display settings and more.
 
-## Put different models to work
+## 🎛️ Put different models to work
 
 A main conversation and a repository-wide investigation do not need the same
-model. With One Code, you can keep your preferred model in charge while
-subagents use another provider for exploration, tests, or review.
+model. Keep your preferred model in charge and let subagents use another
+provider for exploration, tests, or review.
 
 1. Choose the main model with `/model`.
 2. Set the default for subagents and workflow agents with
@@ -93,22 +105,22 @@ subagents use another provider for exploration, tests, or review.
    > Use subagents to investigate the authentication code and its tests.
    > Have them report their findings, then make the fix in the main session.
 
-Agent definitions in `.claude/agents/` can specify their own models, tools,
-and instructions. Use `/agents` to follow their progress and `/model` to
-change the main model as the task changes.
+Agent definitions in `.claude/agents/` can name their own model, tools, and
+instructions. Use `/agents` to follow their progress and `/model` to change the
+main model as the task changes.
 
-This gives you control over where you spend model capacity. Actual cost and
-quality depend on the models, task, and amount of delegated work.
+This is where you decide where the money goes. Actual cost and quality depend on
+the models, the task, and how much you delegate.
 
 [Subagents and workflows →](docs/guide/subagents-and-workflows.md)
 
-## Reuse the setup you already have
+## ♻️ Reuse the setup you already have
 
-One Code reads Claude Code configuration directly, without an import step.
+One Code reads Claude Code configuration directly. There is no import step.
 
 | Your configuration | How One Code uses it |
 |---|---|
-| `CLAUDE.md` | Project instructions, including nested files and `@path` imports. Falls back to `AGENTS.md` when no `CLAUDE.md` exists in a directory. |
+| `CLAUDE.md` | Project instructions, including nested files and `@path` imports. Falls back to `AGENTS.md` when a directory has no `CLAUDE.md`. |
 | `.claude/skills/` and `.claude/commands/` | Discoverable skills and slash commands. |
 | `.claude/agents/` | Subagent definitions with their model, tools, and instructions. |
 | `.claude/settings.json` | `allow`, `deny`, and `ask` permission rules, plus supported command hooks. |
@@ -116,62 +128,60 @@ One Code reads Claude Code configuration directly, without an import step.
 | Installed Claude Code plugins | Plugin agents, skills, commands, and MCP servers, namespaced by plugin. |
 
 Claude Code tool names such as `Read`, `Bash`, `Edit`, and `Task` work in
-permission rules and hook matchers. One Code stores its own settings separately
-and treats `~/.claude` as read-only.
+permission rules and hook matchers. One Code keeps its own settings separately
+and treats `~/.claude` as read-only, so nothing you already have gets rewritten.
 
-Compatibility covers these configuration and workflow surfaces. Features and
-skills that require Claude Code's own hosted or desktop services are not
-included.
+Compatibility covers configuration and workflow surfaces. Features and skills
+that need Claude Code's own hosted or desktop services are not included.
 
 [Configuration details →](docs/guide/bring-your-claude-code-setup.md) ·
 [Skills, plugins, and MCP →](docs/guide/skills-plugins-and-mcp.md)
 
-## Workflows that scale with the task
+## ⚙️ Workflows that scale with the task
 
 ### Subagents and git worktrees
 
 Give an investigation its own context window and bring the result back to the
-main conversation. Subagents run in the background, can receive follow-up
-messages, and can fork the current conversation when they need its context.
-Three agent definitions ship with One Code: `general-purpose`, `explore`, and
-`plan`.
+main conversation. Subagents run in the background, take follow-up messages, and
+can fork the current conversation when they need its context. Three agent
+definitions ship with One Code: `general-purpose`, `explore`, and `plan`.
 
-For parallel edits, give agents separate git worktrees. You can also move the
+For parallel edits, give agents their own git worktrees. You can also move the
 whole session into a worktree with `enter_worktree` and leave it with
 `exit_worktree`.
 
 ### Ultracode workflows
 
-Include **`ultracode`** in a request for a broad audit, migration, or review.
-The model writes a JavaScript workflow to coordinate agents in parallel, with
+Put **`ultracode`** in a request for a broad audit, migration, or review. The
+model writes a JavaScript workflow that coordinates agents in parallel, with
 progress visible in `/workflows`. Use `/effort ultracode` to keep this behavior
-active across turns.
+on across turns.
 
 Resume an interrupted run to reuse completed agent calls whose inputs still
-match. Save reusable scripts in `.claude/workflows/` to invoke them by name.
+match. Save reusable scripts in `.claude/workflows/` to call them by name.
 Optional output-token targets stop new and queued agents once reached;
-already-running agents can finish above the target.
+agents already running can finish above the target.
 
 ### Permissions and planning
 
-**Auto mode is the default.** A classifier evaluates actions that need review,
-while permission rules and deterministic checks enforce additional restrictions.
-`deny` rules take precedence over `allow` rules. Trust approval covers
-project-provided hooks, MCP servers, and allow rules.
+**Auto mode is the default.** A classifier judges actions that need review,
+while permission rules and deterministic checks enforce the rest. `deny` rules
+beat `allow` rules. Trust approval covers project-provided hooks, MCP servers,
+and allow rules.
 
 Press **ctrl+q** to cycle through manual, accept-edits, plan, and auto modes.
-Plan mode lets the agent investigate and write a dedicated plan file before
-you approve implementation. Use `/permissions` to inspect rules and `/auto-mode`
-to configure the classifier.
+Plan mode lets the agent investigate and write a plan file before you approve
+implementation. Use `/permissions` to inspect rules and `/auto-mode` to
+configure the classifier.
 
 The permission system is an application-level control. For OS-level isolation,
-run One Code inside a container. The guarantees and the known gaps are spelled
-out in the guide.
+run One Code inside a container. The guide spells out the guarantees and the
+known gaps.
 
 [Permissions and modes →](docs/guide/permissions-modes-and-auto-mode.md) ·
 [Hooks →](docs/guide/hooks.md)
 
-## Everyday tools
+## 🧰 Everyday tools
 
 | Capability | What you get |
 |---|---|
@@ -180,12 +190,12 @@ out in the guide.
 | Diagnostics | Language-server diagnostics after edits; install the relevant server on your `PATH`. |
 | Long sessions | Per-repository memory, a session scratchpad, and context compaction. |
 | Task tracking | A pinned progress widget, background monitors, and scheduled wake-ups. |
-| Tool discovery | Deferred tools loaded when needed to reduce prompt overhead. |
+| Tool discovery | Deferred tools loaded when needed to keep prompt overhead down. |
 | Reasoning and appearance | `/effort` or **shift+tab** for reasoning effort; `onecode` and `onecode-light` themes. |
 | Customization | Extend One Code with pi extensions, themes, and settings. |
 
 The bundled skills include `simplify`, `code-review`, `security-review`, and
-`fewer-permission-prompts`. A project skill with the same name takes precedence.
+`fewer-permission-prompts`. A project skill with the same name wins.
 
 For scripting and session management:
 
@@ -197,28 +207,29 @@ onecode --permission-mode plan   # start in plan mode
 ```
 
 See [Tools](docs/guide/tools.md) for every tool the model can call and the
-[command reference](docs/guide/reference.md) for every command, shortcut,
-flag, and environment variable.
+[command reference](docs/guide/reference.md) for every command, shortcut, flag,
+and environment variable.
 
-## Documentation
+## 📚 Documentation
 
 The [user guide](docs/guide/README.md) covers everything: installation,
 providers and models, the terminal interface, configuration, permissions and
 auto mode, hooks, subagents and workflows, skills, plugins, and MCP, tools,
-sessions and context, background work, the doctor, differences from Claude
-Code, troubleshooting, and a full reference.
+sessions and context, background work, the doctor, differences from Claude Code,
+troubleshooting, and a full reference.
 
-## Compatibility notes
+## 💡 Good to know
 
-- **Providers:** end-to-end verification has focused on Anthropic, OpenAI,
-  and OpenRouter. Other providers are less exercised.
-- **Web search:** set `BRAVE_SEARCH_API_KEY` or `TAVILY_API_KEY` when using a
-  provider without native search. With neither key, the fallback is Exa's
-  rate-limited keyless endpoint; One Code labels its results.
-- **Native Windows:** hooks and background shells currently assume `/bin/sh`.
-  Use WSL until native Windows support is verified.
+- **Providers:** end-to-end testing has focused on Anthropic, OpenAI, and
+  OpenRouter. Other providers are less exercised, so expect the occasional rough
+  edge.
+- **Web search:** set `BRAVE_SEARCH_API_KEY` or `TAVILY_API_KEY` on a provider
+  without native search. With neither key, the fallback is Exa's rate-limited
+  keyless endpoint, and One Code labels those results.
+- **Native Windows:** hooks and background shells assume `/bin/sh` for now. Use
+  WSL until native Windows is verified.
 
-## Install from source
+## 🔧 Install from source
 
 This installs the local extensions into an existing pi installation:
 
@@ -231,6 +242,12 @@ pi install ./one-code
 pi list
 ```
 
-## License
+## 🧠 Learn the ideas behind it
+
+One Code is the practical companion to the Harness Engineering 101 series, which
+builds these ideas up from first principles: what a coding harness actually does,
+and why the good parts are model-independent.
+
+## 📄 License
 
 [MIT](LICENSE). Contributions welcome.

package/docs/guide/README.md

@@ -6,7 +6,7 @@ One Code is and why it exists, see the [project README](../../README.md).
 
 ## Start here
 
-If you have never run One Code, read these in order:
+If you've never run One Code, read these in order:
 
 1. [Install One Code](installation.md). Install it and open your first
    session.
@@ -35,7 +35,7 @@ If you have never run One Code, read these in order:
 | [Sessions and context](sessions-and-context.md) | What the model sees, memory, compaction, the cache, recaps, and resuming sessions. |
 | [Tasks and background work](tasks-and-background-work.md) | The task list, background shells, monitors, loops, and how results reach the model. |
 | [Check your setup with doctor](doctor.md) | The report, the checkup, model presets, and the `onecode doctor` command. |
-| [Differences from Claude Code](differences-from-claude-code.md) | What is different by design, what is not provided, and known issues. |
+| [Differences from Claude Code](differences-from-claude-code.md) | What is different by design, what isn't provided, and known issues. |
 | [Troubleshooting](troubleshooting.md) | Symptoms, causes, and fixes. |
 | [Command and keyboard reference](reference.md) | Every command, shortcut, flag, environment variable, and file location. |
 

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

@@ -1,7 +1,9 @@
 # Bring your Claude Code setup
 
+[← One Code user guide](README.md)
+
 One Code reads the same configuration files as Claude Code, so your
-existing setup works without changes. There is no import step and nothing
+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.
 
@@ -17,12 +19,12 @@ 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.
 
-To give One Code instructions that Claude Code should not read, add an
+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 cannot answer,
+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.
 
 ## Skills, commands, and agents
@@ -74,7 +76,7 @@ The keys One Code honors:
 | Key | Scopes | Notes |
 |---|---|---|
 | `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 cannot select `auto` or `bypassPermissions`. |
+| `permissions.defaultMode` | All | A project file can't select `auto` or `bypassPermissions`. |
 | `permissions.disableBypassPermissionsMode` | All | `"disable"` refuses bypass mode from any source. |
 | `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). |
@@ -120,7 +122,7 @@ See [Where settings live](configuration.md#where-settings-live).
 
 ## What does not carry over
 
-Features that need Claude Code's own hosted or desktop services are not
+Features that need Claude Code's own hosted or desktop services aren't
 available. For the full list of tools, commands, and skills that are
 missing or different, see
 [Differences from Claude Code](differences-from-claude-code.md).

package/docs/guide/configuration.md

@@ -1,5 +1,7 @@
 # Configure One Code
 
+[← One Code user guide](README.md)
+
 Use this page to find the right settings file, learn what One Code stores
 and where, change the terminal appearance, and set up language-server
 diagnostics. Provider keys are covered in
@@ -36,7 +38,7 @@ atomically; a malformed file is reported rather than overwritten.
 | `PI_CODING_AGENT_DIR` | pi's agent directory. The bundled app sets it to `~/.onecode/agent`. |
 | `CLAUDE_CONFIG_DIR` | Where Claude Code's user configuration is read from (default `~/.claude`). |
 
-Setting one does not move the others.
+Setting one doesn't move the others.
 
 ## What is stored under ~/.onecode
 
@@ -154,7 +156,7 @@ its files, from the nearest directory that has a project marker such as
 server that crashes is restarted twice, then disabled for the session.
 
 If the project's TypeScript installation lacks `lib/tsserver.js`
-(TypeScript 7's native compiler), the server cannot start; One Code
+(TypeScript 7's native compiler), the server can't start; One Code
 reports this. Install a TypeScript 5.x development dependency in that
 project.
 
@@ -163,7 +165,7 @@ precedence over the built-in table for the file extensions it claims.
 
 Run `/lsp` to see each server's status and diagnostic count, start
 failures, and plugin configuration problems. `/doctor report` lists the
-servers your project needs and whether they are installed.
+servers your project needs and whether they're installed.
 
 ## Environment variables
 

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

@@ -1,8 +1,10 @@
 # Differences from Claude Code
 
+[← One Code user guide](README.md)
+
 One Code recreates Claude Code's workflow on the pi agent harness with your
 choice of model. Most of what you know carries over. This page lists what
-is deliberately different, what is not provided, and the known limitations,
+is deliberately different, what isn't provided, and the known limitations,
 so nothing surprises you.
 
 ## What is the same
@@ -46,9 +48,9 @@ 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 are not.
+and `schedule_wakeup`; scheduled cloud sessions aren't.
 
-The `Agent` tool's remote isolation option is not implemented.
+The `Agent` tool's remote isolation option isn't implemented.
 
 ## Commands that are not provided
 
@@ -81,17 +83,17 @@ action but never pre-approve one. See [Hooks](hooks.md).
 
 ## Settings keys that are ignored
 
-`permissions.additionalDirectories` is not honored. The `env` block is read
+`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`,
-`cleanupPeriodDays`, and `spinnerTipsEnabled` are not read. Run
+`cleanupPeriodDays`, and `spinnerTipsEnabled` aren't read. Run
 `/doctor report` to see, per file, which keys were used, ignored, or
 refused.
 
 ## Prompt layout on Anthropic models
 
 Claude Code delivers part of its reminder stack to Opus and Sonnet as a
-system-role message after the first user message. pi's message model cannot
+system-role message after the first user message. pi's message model can't
 express that, so One Code uses the layout Claude Code uses for Haiku on
 every model. The content is the same; only the placement differs.
 
@@ -110,7 +112,7 @@ every model. The content is the same; only the placement differs.
 - Some models reject options that others accept. One Code sends minimal
   options to its side calls (classifier, recap, reader) for this reason. A
   provider incompatibility in a side call fails closed: a classifier that
-  cannot answer blocks the action.
+  can't answer blocks the action.
 - Prompt-cache lifetime and pricing are the provider's. The extended
   one-hour cache applies to Anthropic; other providers use their own
   values.
@@ -119,7 +121,7 @@ every model. The content is the same; only the placement differs.
 
 - A write or edit tool can reach a file that only a `Bash` deny rule
   protects, because in-project writes take the deterministic fast path in
-  auto mode and are not classified. Write `deny` rules for the write tools
+  auto mode and aren't classified. Write `deny` rules for the write tools
   as well. This is documented and accepted rather than fixed.
 - GLM-5.3 and GLM-5.3 Flash, used as the classifier, approve a request to
   back up the project to an unnamed outside location that the ruleset says
@@ -127,7 +129,7 @@ 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` does not persist across
+- 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
@@ -145,6 +147,6 @@ every model. The content is the same; only the placement differs.
   has had limited live testing.
 - Plugin marketplaces support git and local sources only; npm and pip
   sources, version pinning, dependency resolution, and enterprise
-  blocklists are not implemented.
+  blocklists aren't implemented.
 
 Open work is tracked in the project's issue tracker on GitHub.

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,5 @@ 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,
+Hooks run through `/bin/sh`. On native Windows this path doesn't exist,
 which is one reason native Windows is unsupported; use WSL.

package/docs/guide/installation.md

@@ -1,5 +1,7 @@
 # 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.
 
@@ -27,7 +29,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).
@@ -41,10 +43,10 @@ value you change later.
 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.
 
@@ -62,7 +64,7 @@ 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,7 +99,7 @@ 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.
@@ -108,7 +110,7 @@ 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
 ```