@phi-code-admin/phi-code 0.85.0 → 0.87.0

package/CHANGELOG.md

@@ -1,5 +1,88 @@
 # Changelog
 
+## [0.87.0] - 2026-07-10
+
+### Added
+
+- **The /plan orchestrator's phase state machine is now unit-tested.** Its
+  decision core — what to do after each phase given the messages and the report
+  (user abort > auth error > transient retry > BLOCKED pause > review-FAIL fix
+  cycle > continue) — is extracted into a pure module
+  (`extensions/phi/providers/phase-machine.ts`) and covered by 32 tests,
+  including the cases where a model deviates from the text contract: a missing
+  or unparseable `VERDICT:` line is now surfaced to the user instead of being
+  silently treated as a pass, and zero-tool-call / queue-race paths are pinned.
+  The `agent_end` hook keeps the exact same behavior but now only interprets
+  the decision (I/O), it no longer decides.
+- **Section parsing tolerates the header shapes models actually emit.**
+  `extractSection` (HANDOFF / BLOCKING) now handles a markdown heading, a
+  standalone bold label (`**HANDOFF**`) or a plain `LABEL:` line, and splits a
+  report written entirely with bold labels — previously a bold-only `**HANDOFF**`
+  returned nothing. Added regression tests for these deviations.
+
+### Changed
+
+- **extensions/ and the sigma-\* packages are now linted.** Biome previously
+  skipped them entirely (typecheck covered them, lint did not); they are in the
+  linted set and the whole repo is clean (`biome ci .` passes on 752 files,
+  zero warnings). Idiomatic-but-flagged regex-exec loops in web-search were
+  rewritten through an `execAll` generator rather than silenced with rule
+  overrides.
+- **Releases are reproducible.** `npm run build` no longer regenerates the
+  model catalog from models.dev — the committed `packages/ai/src/*.generated.ts`
+  is the source of truth and `build` just compiles it, so a publish ships
+  exactly what is in git. Regeneration is an explicit `npm run generate
+  --workspace=packages/ai` step; a scheduled `refresh-models.yml` workflow
+  opens a PR weekly so the catalog still stays fresh with a human in the loop.
+
+### CI / process
+
+- **CI now gates lint, format, types and catalog-cleanliness on every PR**
+  (`biome ci`, `tsgo --noEmit`, and `git diff --exit-code` on the generated
+  catalog), not just build + test — fork PRs that bypass the local pre-commit
+  hook are covered. A pull-request template makes the discipline checklist
+  explicit, and `docs/fork-policy.md` documents the reproducible-catalog flow.
+
+## [0.86.0] - 2026-07-10
+
+### Changed
+
+- **Single source of truth for bundled assets.** The duplicated root-level
+  `agents/`, `skills/` and `config/` directories (which had silently diverged
+  from the published copies) are gone; `packages/coding-agent/{agents,skills,config}`
+  is now the only copy. Routing defaults live in `SmartRouter.defaultConfig()`
+  with `config/routing.example.json` + `config/routing.schema.json` as
+  documentation, kept in sync by a dedicated test. Agent `.md` parsing is
+  unified in `extensions/phi/providers/agent-def.ts`, shared by the /plan
+  orchestrator and the /agents command (they previously had two drifting
+  parsers, and /agents' bundled-agents path resolved nowhere in either
+  layout).
+- **Rebrand completed for everything user-facing** (see the new
+  [docs/fork-policy.md](docs/fork-policy.md) for what deliberately stays "pi"
+  to keep upstream merges cheap):
+  - The npm README and all docs/ now document `phi`, `~/.phi/` and
+    `@phi-code-admin/phi-code` (they still documented upstream `pi` commands,
+    `~/.pi/` paths and the upstream install).
+  - The system prompt now introduces the agent as phi (it said "operating
+    inside pi", so the model described itself as pi).
+  - `--help`/`update` texts, the config selector's `~/.pi/` label (factually
+    wrong), the tmux hint, the "Location of executable" message and the HTTP
+    User-Agent now derive from the configured app name. `phi update pi` keeps
+    working as a hidden legacy alias of `update self`.
+  - The bun-binary fallback download link pointed at upstream Pi releases; it
+    now points at phi-code releases. Cloudflare attribution UA is `phi-code`.
+  - Docs now name the runtime env vars `PHI_CODING_AGENT_DIR` /
+    `PHI_CODING_AGENT_SESSION_DIR` (the `PI_*` names they documented do not
+    exist at runtime; all other `PI_*` variables are unchanged and stay
+    supported).
+
+### Removed
+
+- **Dead code**: `sigma-agents` no longer ships the unused `SubAgentManager`
+  and `ModelProfiler` (never imported by anything; the orchestrator has its
+  own phase logic). Legacy root-level `_legacy/`, `pi-test.sh`, `pi-test.ps1`
+  and `test.sh` (which still targeted `~/.pi/`) are deleted.
+
 ## [0.85.0] - 2026-07-10
 
 ### Fixed

package/README.md

@@ -1,43 +1,16 @@
+<p align="center"><strong>φ phi-code</strong></p>
 <p align="center">
-  <a href="https://pi.dev">
-    <img alt="pi logo" src="https://pi.dev/logo-auto.svg" width="128">
-  </a>
+  <a href="https://www.npmjs.com/package/@phi-code-admin/phi-code"><img alt="npm" src="https://img.shields.io/npm/v/@phi-code-admin/phi-code?style=flat-square" /></a>
+  <a href="https://github.com/uglyswap/phi-code"><img alt="GitHub" src="https://img.shields.io/badge/github-uglyswap%2Fphi--code-181717?style=flat-square&logo=github" /></a>
 </p>
-<p align="center">
-  <a href="https://discord.com/invite/3cU7Bz4UPx"><img alt="Discord" src="https://img.shields.io/badge/discord-community-5865F2?style=flat-square&logo=discord&logoColor=white" /></a>
-  <a href="https://www.npmjs.com/package/@earendil-works/pi-coding-agent"><img alt="npm" src="https://img.shields.io/npm/v/@earendil-works/pi-coding-agent?style=flat-square" /></a>
-</p>
-<p align="center">
-  <a href="https://pi.dev">pi.dev</a> domain graciously donated by
-  <br /><br />
-  <a href="https://exe.dev"><img src="docs/images/exy.png" alt="Exy mascot" width="48" /><br />exe.dev</a>
-</p>
-
-> New issues and PRs from new contributors are auto-closed by default. Maintainers review auto-closed issues daily. See [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
 ---
 
-Pi is a minimal terminal coding harness. Adapt pi to your workflows, not the other way around, without having to fork and modify pi internals. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Pi Packages](#pi-packages) and share them with others via npm or git.
-
-Pi ships with powerful defaults but skips features like sub agents and plan mode. Instead, you can ask pi to build what you want or install a third party pi package that matches your workflow.
-
-Pi runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps. See [openclaw/openclaw](https://github.com/openclaw/openclaw) for a real-world SDK integration.
-
-## Share your OSS coding agent sessions
-
-If you use pi for open source work, please share your coding agent sessions.
+phi-code is a terminal coding harness with persistent memory, sub-agents, intelligent model routing, and a five-phase plan orchestrator — built as a fork of [Pi](https://github.com/earendil-works/pi-mono) (see [docs/fork-policy.md](docs/fork-policy.md)). Adapt phi to your workflows, not the other way around. Extend it with TypeScript [Extensions](#extensions), [Skills](#skills), [Prompt Templates](#prompt-templates), and [Themes](#themes). Put your extensions, skills, prompt templates, and themes in [Phi Packages](#phi-packages) and share them with others via npm or git.
 
-Public OSS session data helps improve models, prompts, tools, and evaluations using real development workflows.
+Where upstream Pi deliberately skips sub agents and plan mode, phi-code ships them out of the box: `/plan` runs a five-phase explore → plan → code → test → review pipeline with per-phase models from `~/.phi/agent/routing.json`, a local vector memory (`memory_search`/`memory_write`), and a knowledge-graph ontology.
 
-For the full explanation, see [this post on X](https://x.com/badlogicgames/status/2037811643774652911).
-
-To publish sessions, use [`badlogic/pi-share-hf`](https://github.com/badlogic/pi-share-hf). Read its README.md for setup instructions. All you need is a Hugging Face account, the Hugging Face CLI, and `pi-share-hf`.
-
-You can also watch [this video](https://x.com/badlogicgames/status/2041151967695634619), where I show how I publish my `pi-mono` sessions.
-
-I regularly publish my own `pi-mono` work sessions here:
-
-- [badlogicgames/pi-mono on Hugging Face](https://huggingface.co/datasets/badlogicgames/pi-mono)
+phi-code runs in four modes: interactive, print or JSON, RPC for process integration, and an SDK for embedding in your own apps.
 
 ## Table of Contents
 
@@ -58,7 +31,7 @@ I regularly publish my own `pi-mono` work sessions here:
   - [Skills](#skills)
   - [Extensions](#extensions)
   - [Themes](#themes)
-  - [Pi Packages](#pi-packages)
+  - [Phi Packages](#phi-packages)
 - [Programmatic Usage](#programmatic-usage)
 - [Philosophy](#philosophy)
 - [CLI Reference](#cli-reference)
@@ -68,30 +41,26 @@ I regularly publish my own `pi-mono` work sessions here:
 ## Quick Start
 
 ```bash
-curl -fsSL https://pi.dev/install.sh | sh
-```
-
-Or with npm:
-
-```bash
-npm install -g @earendil-works/pi-coding-agent
+npm install -g @phi-code-admin/phi-code
 ```
 
 Authenticate with an API key:
 
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
-pi
+phi
 ```
 
 Or use your existing subscription:
 
 ```bash
-pi
+phi
 /login  # Then select provider
 ```
 
-Then just talk to pi. By default, pi gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [pi packages](#pi-packages).
+Run `/setup` to configure providers (OpenCode Zen/Go, Alibaba Coding Plan, OpenAI, Anthropic, Google, OpenRouter, Groq, local Ollama/LM Studio) and assign per-phase models, or `/phi-init` for the guided first-run wizard.
+
+Then just talk to phi. By default, phi gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [phi packages](#phi-packages).
 
 **Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 
@@ -99,7 +68,7 @@ Then just talk to pi. By default, pi gives the model four tools: `read`, `write`
 
 ## Providers & Models
 
-For each built-in provider, pi maintains a list of tool-capable models, updated with every release. Authenticate via subscription (`/login`) or API key, then select any model from that provider via `/model` (or Ctrl+L).
+For each built-in provider, phi maintains a list of tool-capable models, updated with every release. Authenticate via subscription (`/login`) or API key, then select any model from that provider via `/model` (or Ctrl+L).
 
 **Subscriptions:**
 - Anthropic Claude Pro/Max
@@ -137,7 +106,7 @@ For each built-in provider, pi maintains a list of tool-capable models, updated
 
 See [docs/providers.md](docs/providers.md) for detailed setup instructions.
 
-**Custom providers & models:** Add providers via `~/.pi/agent/models.json` if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md).
+**Custom providers & models:** Add providers via `~/.phi/agent/models.json` if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md).
 
 ---
 
@@ -190,11 +159,11 @@ Type `/` in the editor to trigger commands. [Extensions](#extensions) can regist
 | `/reload` | Reload keybindings, extensions, skills, prompts, and context files (themes hot-reload automatically) |
 | `/hotkeys` | Show all keyboard shortcuts |
 | `/changelog` | Display version history |
-| `/quit` | Quit pi |
+| `/quit` | Quit phi |
 
 ### Keyboard Shortcuts
 
-See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).
+See `/hotkeys` for the full list. Customize via `~/.phi/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).
 
 **Commonly used:**
 
@@ -219,7 +188,7 @@ Submit messages while the agent is working:
 - **Escape** aborts and restores queued messages to editor
 - **Alt+Up** retrieves queued messages back to editor
 
-On Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so pi can receive the follow-up shortcut.
+On Windows Terminal, `Alt+Enter` is fullscreen by default. Remap it in [docs/terminal-setup.md](docs/terminal-setup.md) so phi can receive the follow-up shortcut.
 
 Configure delivery in [settings](docs/settings.md): `steeringMode` and `followUpMode` can be `"one-at-a-time"` (default, waits for response) or `"all"` (delivers all queued at once). `transport` selects provider transport preference (`"sse"`, `"websocket"`, or `"auto"`) for providers that support multiple transports.
 
@@ -231,14 +200,14 @@ Sessions are stored as JSONL files with a tree structure. Each entry has an `id`
 
 ### Management
 
-Sessions auto-save to `~/.pi/agent/sessions/` organized by working directory.
+Sessions auto-save to `~/.phi/agent/sessions/` organized by working directory.
 
 ```bash
-pi -c                  # Continue most recent session
-pi -r                  # Browse and select from past sessions
-pi --no-session        # Ephemeral mode (don't save)
-pi --session <path|id> # Use specific session file or ID
-pi --fork <path|id>    # Fork specific session file or ID into a new session
+phi -c                  # Continue most recent session
+phi -r                  # Browse and select from past sessions
+phi --no-session        # Ephemeral mode (don't save)
+phi --session <path|id> # Use specific session file or ID
+phi --fork <path|id>    # Fork specific session file or ID into a new session
 ```
 
 Use `/session` in interactive mode to see the current session ID before reusing it with `--session <id>` or `--fork <id>`.
@@ -277,14 +246,14 @@ Use `/settings` to modify common options, or edit JSON files directly:
 
 | Location | Scope |
 |----------|-------|
-| `~/.pi/agent/settings.json` | Global (all projects) |
-| `.pi/settings.json` | Project (overrides global) |
+| `~/.phi/agent/settings.json` | Global (all projects) |
+| `.phi/settings.json` | Project (overrides global) |
 
 See [docs/settings.md](docs/settings.md) for all options.
 
 ### Telemetry and update checks
 
-Pi has two separate startup features:
+phi has two separate startup features:
 
 - **Update check:** fetches `https://registry.npmjs.org/@phi-code-admin/phi-code/latest` to check whether a newer phi-code version exists. Disable it with `PI_SKIP_VERSION_CHECK=1`. Disabling update checks only turns off this check.
 - **Install/update telemetry:** none. phi-code sends no telemetry pings (the inherited upstream ping to `pi.dev` was removed).
@@ -295,8 +264,8 @@ Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations desc
 
 ## Context Files
 
-Pi loads `AGENTS.md` (or `CLAUDE.md`) at startup from:
-- `~/.pi/agent/AGENTS.md` (global)
+phi loads `AGENTS.md` (or `CLAUDE.md`) at startup from:
+- `~/.phi/agent/AGENTS.md` (global)
 - Parent directories (walking up from cwd)
 - Current directory
 
@@ -306,7 +275,7 @@ Disable context file loading with `--no-context-files` (or `-nc`).
 
 ### System Prompt
 
-Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`.
+Replace the default system prompt with `.phi/SYSTEM.md` (project) or `~/.phi/agent/SYSTEM.md` (global). Append without replacing via `APPEND_SYSTEM.md`.
 
 ---
 
@@ -317,19 +286,19 @@ Replace the default system prompt with `.pi/SYSTEM.md` (project) or `~/.pi/agent
 Reusable prompts as Markdown files. Type `/name` to expand.
 
 ```markdown
-<!-- ~/.pi/agent/prompts/review.md -->
+<!-- ~/.phi/agent/prompts/review.md -->
 Review this code for bugs, security issues, and performance problems.
 Focus on: {{focus}}
 ```
 
-Place in `~/.pi/agent/prompts/`, `.pi/prompts/`, or a [pi package](#pi-packages) to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md).
+Place in `~/.phi/agent/prompts/`, `.phi/prompts/`, or a [phi package](#phi-packages) to share with others. See [docs/prompt-templates.md](docs/prompt-templates.md).
 
 ### Skills
 
 On-demand capability packages following the [Agent Skills standard](https://agentskills.io). Invoke via `/skill:name` or let the agent load them automatically.
 
 ```markdown
-<!-- ~/.pi/agent/skills/my-skill/SKILL.md -->
+<!-- ~/.phi/agent/skills/my-skill/SKILL.md -->
 # My Skill
 Use this skill when the user asks about X.
 
@@ -338,13 +307,13 @@ Use this skill when the user asks about X.
 2. Then that
 ```
 
-Place in `~/.pi/agent/skills/`, `~/.agents/skills/`, `.pi/skills/`, or `.agents/skills/` (from `cwd` up through parent directories) or a [pi package](#pi-packages) to share with others. See [docs/skills.md](docs/skills.md).
+Place in `~/.phi/agent/skills/`, `~/.agents/skills/`, `.phi/skills/`, or `.agents/skills/` (from `cwd` up through parent directories) or a [phi package](#phi-packages) to share with others. See [docs/skills.md](docs/skills.md).
 
 ### Extensions
 
 <p align="center"><img src="docs/images/doom-extension.png" alt="Doom Extension" width="600"></p>
 
-TypeScript modules that extend pi with custom tools, commands, keyboard shortcuts, event handlers, and UI components.
+TypeScript modules that extend phi with custom tools, commands, keyboard shortcuts, event handlers, and UI components.
 
 ```typescript
 export default function (pi: ExtensionAPI) {
@@ -354,7 +323,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-The default export can also be `async`. pi waits for async extension factories before startup continues, which is useful for one-time initialization such as fetching remote model lists before calling `pi.registerProvider()`.
+The default export can also be `async`. phi waits for async extension factories before startup continues, which is useful for one-time initialization such as fetching remote model lists before calling `pi.registerProvider()`.
 
 **What's possible:**
 - Custom tools (or replace built-in tools entirely)
@@ -366,47 +335,47 @@ The default export can also be `async`. pi waits for async extension factories b
 - Git checkpointing and auto-commit
 - SSH and sandbox execution
 - MCP server integration
-- Make pi look like Claude Code
+- Make phi look like Claude Code
 - Games while waiting (yes, Doom runs)
 - ...anything you can dream up
 
-Place in `~/.pi/agent/extensions/`, `.pi/extensions/`, or a [pi package](#pi-packages) to share with others. See [docs/extensions.md](docs/extensions.md) and [examples/extensions/](examples/extensions/).
+Place in `~/.phi/agent/extensions/`, `.phi/extensions/`, or a [phi package](#phi-packages) to share with others. See [docs/extensions.md](docs/extensions.md) and [examples/extensions/](examples/extensions/).
 
 ### Themes
 
-Built-in: `dark`, `light`. Themes hot-reload: modify the active theme file and pi immediately applies changes.
+Built-in: `dark`, `light`. Themes hot-reload: modify the active theme file and phi immediately applies changes.
 
-Place in `~/.pi/agent/themes/`, `.pi/themes/`, or a [pi package](#pi-packages) to share with others. See [docs/themes.md](docs/themes.md).
+Place in `~/.phi/agent/themes/`, `.phi/themes/`, or a [phi package](#phi-packages) to share with others. See [docs/themes.md](docs/themes.md).
 
-### Pi Packages
+### Phi Packages
 
 Bundle and share extensions, skills, prompts, and themes via npm or git. Find packages on [npmjs.com](https://www.npmjs.com/search?q=keywords%3Api-package) or [Discord](https://discord.com/channels/1456806362351669492/1457744485428629628).
 
-> **Security:** Pi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
+> **Security:** phi packages run with full system access. Extensions execute arbitrary code, and skills can instruct the model to perform any action including running executables. Review source code before installing third-party packages.
 
 ```bash
-pi install npm:@foo/pi-tools
-pi install npm:@foo/pi-tools@1.2.3      # pinned version
-pi install git:github.com/user/repo
-pi install git:github.com/user/repo@v1  # tag or commit
-pi install git:git@github.com:user/repo
-pi install git:git@github.com:user/repo@v1  # tag or commit
-pi install https://github.com/user/repo
-pi install https://github.com/user/repo@v1      # tag or commit
-pi install ssh://git@github.com/user/repo
-pi install ssh://git@github.com/user/repo@v1    # tag or commit
-pi remove npm:@foo/pi-tools
-pi uninstall npm:@foo/pi-tools          # alias for remove
-pi list
-pi update                               # update pi and packages (skips pinned packages)
-pi update --extensions                  # update packages only
-pi update --self                        # update pi only
-pi update --self --force                # reinstall pi even if current
-pi update npm:@foo/pi-tools             # update one package
-pi config                               # enable/disable extensions, skills, prompts, themes
+phi install npm:@foo/pi-tools
+phi install npm:@foo/pi-tools@1.2.3      # pinned version
+phi install git:github.com/user/repo
+phi install git:github.com/user/repo@v1  # tag or commit
+phi install git:git@github.com:user/repo
+phi install git:git@github.com:user/repo@v1  # tag or commit
+phi install https://github.com/user/repo
+phi install https://github.com/user/repo@v1      # tag or commit
+phi install ssh://git@github.com/user/repo
+phi install ssh://git@github.com/user/repo@v1    # tag or commit
+phi remove npm:@foo/pi-tools
+phi uninstall npm:@foo/pi-tools          # alias for remove
+phi list
+phi update                               # update phi and packages (skips pinned packages)
+phi update --extensions                  # update packages only
+phi update --self                        # update phi only
+phi update --self --force                # reinstall phi even if current
+phi update npm:@foo/pi-tools             # update one package
+phi config                               # enable/disable extensions, skills, prompts, themes
 ```
 
-Packages install to `~/.pi/agent/git/` (git) or global npm. Use `-l` for project-local installs (`.pi/git/`, `.pi/npm/`). Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers. If you use a Node version manager and want package installs to reuse a stable npm context, set `npmCommand` in `settings.json`, for example `["mise", "exec", "node@20", "--", "npm"]`.
+Packages install to `~/.phi/agent/git/` (git) or global npm. Use `-l` for project-local installs (`.phi/git/`, `.phi/npm/`). Git packages install dependencies with `npm install --omit=dev` by default, so runtime deps must be listed under `dependencies`; when `npmCommand` is configured, git packages use plain `install` for compatibility with wrappers. If you use a Node version manager and want package installs to reuse a stable npm context, set `npmCommand` in `settings.json`, for example `["mise", "exec", "node@20", "--", "npm"]`.
 
 Create a package by adding a `pi` key to `package.json`:
 
@@ -423,7 +392,7 @@ Create a package by adding a `pi` key to `package.json`:
 }
 ```
 
-Without a `pi` manifest, pi auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).
+Without a `pi` manifest, phi auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).
 
 See [docs/packages.md](docs/packages.md).
 
@@ -434,7 +403,7 @@ See [docs/packages.md](docs/packages.md).
 ### SDK
 
 ```typescript
-import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@earendil-works/pi-coding-agent";
+import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "@phi-code-admin/phi-code";
 
 const authStorage = AuthStorage.create();
 const modelRegistry = ModelRegistry.create(authStorage);
@@ -456,7 +425,7 @@ See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).
 For non-Node.js integrations, use RPC mode over stdin/stdout:
 
 ```bash
-pi --mode rpc
+phi --mode rpc
 ```
 
 RPC mode uses strict LF-delimited JSONL framing. Clients must split records on `\n` only. Do not use generic line readers like Node `readline`, which also split on Unicode separators inside JSON payloads.
@@ -467,11 +436,11 @@ See [docs/rpc.md](docs/rpc.md) for the protocol.
 
 ## Philosophy
 
-Pi is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with [extensions](#extensions), [skills](#skills), or installed from third-party [pi packages](#pi-packages). This keeps the core minimal while letting you shape pi to fit how you work.
+phi is aggressively extensible so it doesn't have to dictate your workflow. Features that other tools bake in can be built with [extensions](#extensions), [skills](#skills), or installed from third-party [phi packages](#phi-packages). This keeps the core minimal while letting you shape phi to fit how you work.
 
 **No MCP.** Build CLI tools with READMEs (see [Skills](#skills)), or build an extension that adds MCP support. [Why?](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)
 
-**No sub-agents.** There's many ways to do this. Spawn pi instances via tmux, or build your own with [extensions](#extensions), or install a package that does it your way.
+**No sub-agents.** There's many ways to do this. Spawn phi instances via tmux, or build your own with [extensions](#extensions), or install a package that does it your way.
 
 **No permission popups.** Run in a container, or build your own confirmation flow with [extensions](#extensions) inline with your environment and security requirements.
 
@@ -488,22 +457,22 @@ Read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/)
 ## CLI Reference
 
 ```bash
-pi [options] [@files...] [messages...]
+phi [options] [@files...] [messages...]
 ```
 
 ### Package Commands
 
 ```bash
-pi install <source> [-l]     # Install package, -l for project-local
-pi remove <source> [-l]      # Remove package
-pi uninstall <source> [-l]   # Alias for remove
-pi update [source|self|pi]   # Update pi and packages (skips pinned packages)
-pi update --extensions       # Update packages only
-pi update --self             # Update pi only
-pi update --self --force     # Reinstall pi even if current
-pi update --extension <src>  # Update one package
-pi list                      # List installed packages
-pi config                    # Enable/disable package resources
+phi install <source> [-l]     # Install package, -l for project-local
+phi remove <source> [-l]      # Remove package
+phi uninstall <source> [-l]   # Alias for remove
+phi update [source|self]   # Update phi and packages (skips pinned packages)
+phi update --extensions       # Update packages only
+phi update --self             # Update phi only
+phi update --self --force     # Reinstall phi even if current
+phi update --extension <src>  # Update one package
+phi list                      # List installed packages
+phi config                    # Enable/disable package resources
 ```
 
 ### Modes
@@ -516,10 +485,10 @@ pi config                    # Enable/disable package resources
 | `--mode rpc` | RPC mode for process integration (see [docs/rpc.md](docs/rpc.md)) |
 | `--export <in> [out]` | Export session to HTML |
 
-In print mode, pi also reads piped stdin and merges it into the initial prompt:
+In print mode, phi also reads piped stdin and merges it into the initial prompt:
 
 ```bash
-cat README.md | pi -p "Summarize this text"
+cat README.md | phi -p "Summarize this text"
 ```
 
 ### Model Options
@@ -586,7 +555,7 @@ Prefix files with `@` to include in the message:
 
 ```bash
 pi @prompt.md "Answer this"
-pi -p @screenshot.png "What's in this image?"
+phi -p @screenshot.png "What's in this image?"
 pi @code.ts @test.ts "Review these files"
 ```
 
@@ -594,39 +563,39 @@ pi @code.ts @test.ts "Review these files"
 
 ```bash
 # Interactive with initial prompt
-pi "List all .ts files in src/"
+phi "List all .ts files in src/"
 
 # Non-interactive
-pi -p "Summarize this codebase"
+phi -p "Summarize this codebase"
 
 # Non-interactive with piped stdin
-cat README.md | pi -p "Summarize this text"
+cat README.md | phi -p "Summarize this text"
 
 # Different model
-pi --provider openai --model gpt-4o "Help me refactor"
+phi --provider openai --model gpt-4o "Help me refactor"
 
 # Model with provider prefix (no --provider needed)
-pi --model openai/gpt-4o "Help me refactor"
+phi --model openai/gpt-4o "Help me refactor"
 
 # Model with thinking level shorthand
-pi --model sonnet:high "Solve this complex problem"
+phi --model sonnet:high "Solve this complex problem"
 
 # Limit model cycling
-pi --models "claude-*,gpt-4o"
+phi --models "claude-*,gpt-4o"
 
 # Read-only mode
-pi --tools read,grep,find,ls -p "Review the code"
+phi --tools read,grep,find,ls -p "Review the code"
 
 # High thinking level
-pi --thinking high "Solve this complex problem"
+phi --thinking high "Solve this complex problem"
 ```
 
 ### Environment Variables
 
 | Variable | Description |
 |----------|-------------|
-| `PI_CODING_AGENT_DIR` | Override config directory (default: `~/.pi/agent`) |
-| `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory (overridden by `--session-dir`) |
+| `PHI_CODING_AGENT_DIR` | Override config directory (default: `~/.phi/agent`) |
+| `PHI_CODING_AGENT_SESSION_DIR` | Override session storage directory (overridden by `--session-dir`) |
 | `PI_PACKAGE_DIR` | Override package directory (useful for Nix/Guix where store paths tokenize poorly) |
 | `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
 | `PI_SKIP_VERSION_CHECK` | Skip the phi-code version update check at startup. This prevents the npm registry latest-version request |