@hoilab/ada-cli 0.84.21 → 0.85.0

package/README.md

@@ -1,703 +1,248 @@
 <p align="center">
-  <a href="https://pi.dev">
-    <img alt="pi logo" src="https://pi.dev/logo-auto.svg" width="128">
-  </a>
+<pre>
+  █████╗ ██████╗  █████╗
+ ██╔══██╗██╔══██╗██╔══██╗
+ ███████║██║  ██║███████║
+ ██╔══██║██║  ██║██╔══██║
+ ██║  ██║██████╔╝██║  ██║
+ ╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝
+</pre>
 </p>
 
-> ⚠️ This is **Ada CLI** — a rebranded fork of pi.dev. The `pi` binary becomes `ada`, config moves to `~/.ada/`, and it auto-syncs with upstream. See [ADA-CLI.md](../../ADA-CLI.md).
+<h3 align="center">Ada CLI — the enterprise-grade autonomous coding agent</h3>
 
 <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/@hoilab/ada-cli"><img alt="npm" src="https://img.shields.io/npm/v/@hoilab/ada-cli?style=flat-square" /></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).
+<p align="center">🇬🇧 English · <a href="README.es.md">🇪🇸 Español</a></p>
 
----
-
-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.
-
-## Share your OSS coding agent sessions
-
-If you use pi for open source work, please share your coding agent sessions.
-
-Public OSS session data helps improve models, prompts, tools, and evaluations using real development workflows.
-
-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)
-
-## Table of Contents
-
-- [Quick Start](#quick-start)
-- [Providers & Models](#providers--models)
-- [Interactive Mode](#interactive-mode)
-  - [Editor](#editor)
-  - [Commands](#commands)
-  - [Keyboard Shortcuts](#keyboard-shortcuts)
-  - [Message Queue](#message-queue)
-- [Sessions](#sessions)
-  - [Branching](#branching)
-  - [Compaction](#compaction)
-- [Settings](#settings)
-- [Context Files](#context-files)
-- [Customization](#customization)
-  - [Prompt Templates](#prompt-templates)
-  - [Skills](#skills)
-  - [Extensions](#extensions)
-  - [Themes](#themes)
-  - [Pi Packages](#pi-packages)
-- [Programmatic Usage](#programmatic-usage)
-- [Philosophy](#philosophy)
-- [CLI Reference](#cli-reference)
+> Ada CLI is HOILAB's fork of [pi.dev](https://pi.dev) (`earendil-works/pi`): the `pi` binary becomes `ada-cli`, config moves to `~/.ada/`, and the fork auto-syncs with upstream daily so security fixes and new models land immediately. See [ADA-CLI.md](../../ADA-CLI.md) for the full sync mechanics. New issues and PRs from new contributors are auto-closed by default — see [CONTRIBUTING.md](../../CONTRIBUTING.md).
 
 ---
 
-## Quick Start
+Ada CLI is a coding agent built on pi.dev's proven minimal terminal core, with an **Ada Intelligence Engine** layered on top: autonomous goal pursuit with a mandatory evidence-backed judge, sandboxed parallel workflows, a traceability graph that gates "done" on observed evidence, durable cross-session memory with a tamper-evident audit log and PII scanning, encrypted secrets, and a native desktop app — all wired to the same `settings.json` your terminal already uses.
 
-```bash
-npm install -g --ignore-scripts @earendil-works/pi-coding-agent
-```
+Where most coding agents ask you to trust a single long-running chat, Ada is built to be **auditable**: every autonomous action either has cited evidence behind it or it doesn't happen.
 
-`--ignore-scripts` disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs.
+- **Everything is optional and inspectable.** The core stays as minimal as pi.dev's — four tools (`read`, `write`, `edit`, `bash`) by default. Autonomy, memory, and orchestration are opt-in layers you can turn off in `settings.json`.
+- **Autonomy requires a signed-off contract.** The [Goal Engine](#ada-intelligence-engine) won't touch a codebase until you `/goal approve` its plan, runs fixed TDD phases, and never marks work `done` without a judge citing evidence for it.
+- **Nothing is "done" on the model's word alone.** The [Work Graph](#ada-intelligence-engine) gates completion on observed evidence — a passing test, a real diff, a verified command — not a claim in the transcript.
+- **Memory is compliance-ready by default.** The [Memory Engine](#ada-intelligence-engine) blocks PII before it's ever written to disk and keeps a hash-chained audit log of every write and rejection.
+- **Secrets stay off disk, and out of reach of the agent.** The built-in [Vault](#ada-intelligence-engine) is a local encrypted store shared across the CLI, desktop app, and subagents of an unlocked session. Provider credentials and MCP tokens never enter the model's context. An explicit `@vault:NAME` reference *does* expand into the prompt — that is its purpose, so the model can use the secret in a command — but the expansion is redacted in everything persisted and displayed. The agent cannot read the vault: `core/aprobacion/politica.ts` denies it permanently, and that denial survives `yolo`.
+- **Teams get a GUI, not just a terminal.** The [Ada Desktop](../../desktop/) app (Tauri + Next.js) reads the exact same SDK and config as the CLI — no parallel product to maintain.
+- **Extensible instead of opinionated.** No baked-in MCP, sub-agent framework, or permission popups — build exactly the workflow you need with [extensions](docs/extensions.md), [skills](docs/skills.md), or third-party [Ada packages](docs/packages.md). See [Philosophy](#philosophy).
 
-Installer alternative:
+## Getting Started
 
 ```bash
-curl -fsSL https://pi.dev/install.sh | sh
+npm install -g --ignore-scripts @hoilab/ada-cli
 ```
 
-Authenticate with an API key:
-
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
-pi
-```
-
-Or use your existing subscription:
-
-```bash
-pi
-/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).
-
-**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)
-
----
-
-## Providers & Models
-
-For each built-in provider, pi maintains a list of tool-capable models. Configured provider catalogs refresh automatically; run `pi update --models` to force an immediate refresh. Authenticate via subscription (`/login`) or API key, then select any model from that provider via `/model` (or Ctrl+L).
-
-**Subscriptions:**
-- Anthropic Claude Pro/Max
-- OpenAI ChatGPT Plus/Pro (Codex)
-- GitHub Copilot
-
-**API keys:**
-- Anthropic
-- Ant Ling
-- OpenAI
-- Azure OpenAI
-- DeepSeek
-- NVIDIA NIM
-- Google Gemini
-- Google Vertex
-- Amazon Bedrock
-- Mistral
-- Groq
-- Cerebras
-- Cloudflare AI Gateway
-- Cloudflare Workers AI
-- xAI
-- OpenRouter
-- Vercel AI Gateway
-- ZAI Coding Plan (Global)
-- ZAI Coding Plan (China)
-- OpenCode Zen
-- OpenCode Go
-- Hugging Face
-- Fireworks
-- Together AI
-- Baseten
-- Kimi For Coding
-- MiniMax
-- Xiaomi MiMo
-- Xiaomi MiMo Token Plan (China)
-- Xiaomi MiMo Token Plan (Amsterdam)
-- Xiaomi MiMo Token Plan (Singapore)
-
-Pi also supports the llama.cpp router server. Configure it with `/login llama.cpp`, manage downloads and loaded models with `/llama`, then select a loaded model with `/model`. See [docs/llama-cpp.md](docs/llama-cpp.md) for setup and usage.
-
-See [docs/providers.md](docs/providers.md) for other provider 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).
-
----
-
-## Interactive Mode
-
-<p align="center"><img src="docs/images/interactive-mode.png" alt="Interactive Mode" width="600"></p>
-
-The interface from top to bottom:
-
-- **Startup header** - Shows shortcuts (`/hotkeys` for all), loaded AGENTS.md files, prompt templates, skills, and extensions
-- **Messages** - Your messages, assistant responses, tool calls and results, notifications, errors, and extension UI
-- **Editor** - Where you type; border color indicates thinking level
-- **Footer** - Working directory, session name, total token/cache usage (`↑` input, `↓` output, `R` cache read, `W` cache write, `CH` latest cache hit rate), cost, context usage, current model. Totals include assistant responses, usage reported by tools, and summary generation.
-
-The editor can be temporarily replaced by other UI, like built-in `/settings` or custom UI from extensions (e.g., a Q&A tool that lets the user answer model questions in a structured format). [Extensions](#extensions) can also replace the editor, add widgets above/below it, a status line, custom footer, or overlays.
-
-### Editor
-
-| Feature | How |
-|---------|-----|
-| File reference | Type `@` to fuzzy-search project files |
-| Path completion | Tab to complete paths |
-| Multi-line | Shift+Enter (or Ctrl+Enter on Windows Terminal) |
-| External editor | Ctrl+G opens `externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere |
-| Clipboard | Ctrl+V to paste an image or text (Alt+V on Windows), or drag images onto terminal |
-| Bash commands | `!command` runs and sends output to LLM, `!!command` runs without sending |
-
-Standard editing keybindings for delete word, undo, etc. See [docs/keybindings.md](docs/keybindings.md).
-
-### Commands
-
-Type `/` in the editor to trigger commands. [Extensions](#extensions) can register custom commands, [skills](#skills) are available as `/skill:name`, and [prompt templates](#prompt-templates) expand via `/templatename`.
-
-| Command | Description |
-|---------|-------------|
-| `/login`, `/logout` | Manage provider credentials |
-| [`/llama`](docs/llama-cpp.md) | Download, load, and unload llama.cpp router models |
-| `/model` | Switch models |
-| `/scoped-models` | Enable/disable models for Ctrl+P cycling |
-| `/settings` | Thinking level, theme, message delivery, transport |
-| `/resume` | Pick from previous sessions |
-| `/new` | Start a new session |
-| `/name <name>` | Set session display name |
-| `/session` | Show session info (file, ID, messages, tokens, cost) |
-| `/tree` | Jump to any point in the session and continue from there |
-| `/trust` | Save project trust decision for future sessions (restart required) |
-| `/fork` | Create a new session from a previous user message |
-| `/clone` | Duplicate the current active branch into a new session |
-| `/compact [prompt]` | Manually compact context, optional custom instructions |
-| `/copy` | Copy last assistant message to clipboard |
-| `/export [file]` | Export session to HTML or JSONL file |
-| `/import <file>` | Import and resume a session from a JSONL file |
-| `/share` | Upload as private GitHub gist with shareable HTML link |
-| `/reload` | Reload keybindings, extensions, skills, prompts, themes, and context files |
-| `/hotkeys` | Show all keyboard shortcuts |
-| `/changelog` | Display version history |
-| `/quit` | Quit pi |
-
-### Keyboard Shortcuts
-
-See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`. See [docs/keybindings.md](docs/keybindings.md).
-
-**Commonly used:**
-
-| Key | Action |
-|-----|--------|
-| Ctrl+C | Clear editor |
-| Ctrl+C twice | Quit |
-| Escape | Cancel/abort |
-| Escape twice | Open `/tree` |
-| Ctrl+L | Open model selector |
-| Ctrl+P / Shift+Ctrl+P | Cycle scoped models forward/backward |
-| Shift+Tab | Cycle thinking level |
-| Ctrl+O | Collapse/expand tool output |
-| Ctrl+T | Collapse/expand thinking blocks |
-| Ctrl+X | Copy the last assistant message |
-
-### Message Queue
-
-Submit messages while the agent is working:
-
-- **Enter** queues a *steering* message, delivered after the current assistant turn finishes executing its tool calls
-- **Alt+Enter** queues a *follow-up* message, delivered only after the agent finishes all work
-- **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.
-
-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.
-
----
-
-## Sessions
-
-Sessions are stored as JSONL files with a tree structure. Each entry has an `id` and `parentId`, enabling in-place branching without creating new files. See [docs/session-format.md](docs/session-format.md) for file format.
-
-### Management
-
-Sessions auto-save to `~/.pi/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 --name "my task"    # Set session display name at startup
-pi --session <path|id> # Use specific session file or ID
-pi --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>`.
-
-### Branching
-
-**`/tree`** - Navigate the session tree in-place. Select any previous point, continue from there, and switch between branches. All history preserved in a single file.
-
-<p align="center"><img src="docs/images/tree-view.png" alt="Tree View" width="600"></p>
-
-- Search by typing, fold/unfold and jump between branches with Ctrl+←/Ctrl+→ or Alt+←/Alt+→, page with ←/→
-- Filter modes (Ctrl+O): default → no-tools → user-only → labeled-only → all
-- Press Ctrl+X to copy the selected message
-- Press Shift+L to label entries as bookmarks and Shift+T to toggle label timestamps
-
-**`/fork`** - Create a new session file from a previous user message on the active branch. Opens a selector, copies the active path up to that point, and places the selected prompt in the editor for modification.
-
-**`/clone`** - Duplicate the current active branch into a new session file at the current position. The new session keeps the full active-path history and opens with an empty editor.
-
-**`--fork <path|id>`** - Fork an existing session file or partial session UUID directly from the CLI. This copies the full source session into a new session file in the current project.
-
-### Compaction
-
-Long sessions can exhaust context windows. Compaction summarizes older messages while keeping recent ones.
-
-**Manual:** `/compact` or `/compact <custom instructions>`
-
-**Automatic:** Enabled by default. Triggers on context overflow (recovers and retries) or when approaching the limit (proactive). Configure via `/settings` or `settings.json`.
-
-Compaction is lossy. The full history remains in the JSONL file; use `/tree` to revisit. Customize compaction behavior via [extensions](#extensions). See [docs/compaction.md](docs/compaction.md) for internals.
-
----
-
-## Settings
-
-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) |
-
-See [docs/settings.md](docs/settings.md) for all options.
-
-### Project Trust
-
-On interactive startup, pi asks before trusting a project folder that contains project-local settings, resources, or project `.agents/skills` and has no saved decision for the folder or a parent folder in `~/.pi/agent/trust.json`. Trusting a project allows pi to load `.pi/settings.json` and `.pi` resources, install missing project packages, and execute project extensions.
-
-Before the trust decision, pi loads only context files, user/global extensions, and CLI `-e` extensions so they can handle the `project_trust` event. Project-local extensions, project package-managed extensions, and project settings are loaded only after the project is trusted. This split also applies when switching to a session from a different cwd whose trust has not been resolved in the current process.
-
-Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a trust prompt. Without an applicable saved trust decision, they use `defaultProjectTrust` from global settings: `ask` (default) and `never` ignore those project resources, while `always` trusts them. Pass `--approve`/`-a` or `--no-approve`/`-na` to override project trust for one run.
-
-If no extension or saved decision applies, `defaultProjectTrust` controls the fallback behavior. Set it to `"ask"`, `"always"`, or `"never"` in `~/.pi/agent/settings.json`, or change it with `/settings`.
-
-`pi config` and package commands use the same project trust flow, except `pi update` never prompts. Pass `--approve` to trust project-local settings for one command or `--no-approve` to ignore them.
-
-Use `/trust` in interactive mode to save a project trust decision for future sessions, including trust for the immediate parent folder. It writes `~/.pi/agent/trust.json` only; the current session is not reloaded, so restart pi for changes to take effect.
-
-### Telemetry and update checks
-
-Pi has two separate startup features:
-
-- **Update check:** fetches `https://pi.dev/api/latest-version` to check whether a newer Pi version exists. Disable it with `PI_SKIP_VERSION_CHECK=1`. Disabling update checks only turns off this check.
-- **Install/update telemetry:** after first install or a changelog-detected update, sends an anonymous version ping to `https://pi.dev/api/report-install`. This setting also controls optional provider attribution headers for OpenRouter, Cloudflare, and direct NVIDIA NIM requests. Opt out by setting `enableInstallTelemetry` to `false` in `settings.json`, or by setting `PI_TELEMETRY=0`. This does not disable update checks; Pi may still contact `pi.dev` for the latest version unless update checks are disabled or offline mode is enabled.
-
-Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
-
----
-
-## Context Files
-
-Pi loads `AGENTS.md` (or `CLAUDE.md`) at startup from:
-- `~/.pi/agent/AGENTS.md` (global)
-- Parent directories (walking up from cwd)
-- Current directory
-
-If a directory contains `AGENTS.override.md`, Pi loads it instead of `AGENTS.md` or `CLAUDE.md` from that directory. Context files from other directories are still concatenated.
-
-Use for project instructions (`AGENTS.md`/`CLAUDE.md`), conventions, common commands. All matching files are concatenated.
-
-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`.
-
----
-
-## Customization
-
-### Prompt Templates
-
-Reusable prompts as Markdown files. Type `/name` to expand.
-
-```markdown
-<!-- ~/.pi/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).
-
-### 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 -->
-# My Skill
-Use this skill when the user asks about X.
-
-## Steps
-1. Do this
-2. Then that
+ada-cli
 ```
 
-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).
+Or authenticate with an existing subscription: run `ada-cli`, then `/login`. First run in a new project asks you to trust the folder — see [Project Trust](docs/security.md).
 
-### Extensions
+Compliance controls in detail — ledger, retention purge, machine policy,
+art. 9 detection, OTLP and SBOM — with what each one proves and what it does
+not: [Compliance](docs/compliance.md).
 
-<p align="center"><img src="docs/images/doom-extension.png" alt="Doom Extension" width="600"></p>
+Full walkthrough: [Quickstart](docs/quickstart.md) · [Providers & models](docs/providers.md) · [Windows](docs/windows.md) · [Termux](docs/termux.md) · [tmux](docs/tmux.md)
 
-TypeScript modules that extend pi with custom tools, commands, keyboard shortcuts, event handlers, and UI components.
+### One limitation of the published package
 
-```typescript
-export default function (pi: ExtensionAPI) {
-  pi.registerTool({ name: "deploy", ... });
-  pi.registerCommand("stats", { ... });
-  pi.on("tool_call", async (event, ctx) => { ... });
-}
-```
-
-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()`.
-
-**What's possible:**
-- Custom tools (or replace built-in tools entirely)
-- Sub-agents and plan mode
-- Custom compaction and summarization
-- Permission gates and path protection
-- Custom editors and UI components
-- Status lines, headers, footers
-- Git checkpointing and auto-commit
-- SSH and sandbox execution
-- MCP server integration
-- Make pi 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/).
-
-### Themes
+`ada-cli session <id> <op>` (compact, rename, fork, kill, ops) needs a protocol
+extension point that this fork adds to `@earendil-works/pi-{client,protocol,server}`.
+Those are upstream packages: the published `@hoilab/ada-cli` resolves them from
+the npm registry, so an installed copy does not carry it. The command says so
+instead of failing with an opaque error. Everything else — including `serve`,
+`attach` and the whole agent — works from the published package.
 
-Built-in: `dark`, `light`. Themes hot-reload: modify the active theme file and pi immediately applies changes.
+A source build has no such limitation.
 
-Place in `~/.pi/agent/themes/`, `.pi/themes/`, or a [pi package](#pi-packages) to share with others. See [docs/themes.md](docs/themes.md).
+### Building from source
 
-### Pi 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.
+Organisations that will not install from a public registry can build the same
+artifact locally. `dist/` is what the published package and the desktop app
+consume, so it has to be built — running from `src/` is not the same thing.
 
 ```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 only
-pi update --all                         # update pi and packages
-pi update --extensions                  # update packages only
-pi update --models                      # refresh model catalogs 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
-```
-
-Packages install to `~/.pi/agent/git/` (git) or `~/.pi/agent/npm/` (npm). Use `-l` for project-local installs (`.pi/git/`, `.pi/npm/`). Git `@ref` values are pinned tags or commits; pinned packages are skipped by `pi update --extensions` and `pi update --all`, so use `pi install git:host/user/repo@new-ref` to move an existing package to a new ref. 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`:
-
-```json
-{
-  "name": "my-pi-package",
-  "keywords": ["pi-package"],
-  "pi": {
-    "extensions": ["./extensions"],
-    "skills": ["./skills"],
-    "prompts": ["./prompts"],
-    "themes": ["./themes"]
-  }
-}
-```
-
-Without a `pi` manifest, pi auto-discovers from conventional directories (`extensions/`, `skills/`, `prompts/`, `themes/`).
-
-See [docs/packages.md](docs/packages.md).
-
----
-
-## Programmatic Usage
-
-### SDK
-
-```typescript
-import { createAgentSession, ModelRuntime, SessionManager } from "@earendil-works/pi-coding-agent";
-
-const modelRuntime = await ModelRuntime.create();
-const { session } = await createAgentSession({
-  sessionManager: SessionManager.inMemory(),
-  modelRuntime,
-});
-
-await session.prompt("What files are in the current directory?");
+git clone https://github.com/HOILAB/ada-cli.git
+cd ada-cli
+npm ci                                   # exact versions from npm-shrinkwrap.json
+npm run build --prefix packages/coding-agent
+npm link --prefix packages/coding-agent  # puts `ada-cli` on PATH
 ```
 
-For advanced multi-session runtime replacement, use `createAgentSessionRuntime()` and `AgentSessionRuntime`.
-
-See [docs/sdk.md](docs/sdk.md) and [examples/sdk/](examples/sdk/).
-
-### RPC Mode
-
-For non-Node.js integrations, use RPC mode over stdin/stdout:
+To verify the build before trusting it:
 
 ```bash
-pi --mode rpc
+npm run check          # types, lint, pinned deps, shrinkwrap, startup budget, fork budget
+npx vitest run         # the full suite (from packages/coding-agent)
+ada-cli --version
 ```
 
-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.
-
-See [docs/rpc.md](docs/rpc.md) for the protocol.
-
----
+`ada-cli update` only runs when you ask for it and it queries the npm registry
+for this package, so a source build stays put until you rebuild it. Nothing
+phones home — see [Telemetry and update checks](docs/settings.md#telemetry-and-update-checks).
+
+## Measured against the alternatives
+
+Four coding tasks, the **installed package** (not the source tree), the same
+free OpenRouter model as the competing agent, comparing each one's own session
+logs:
+
+| task | Ada | oh-my-pi |
+|---|---:|---:|
+| queue: fix a bug and add a method | 4 calls | 4 |
+| parser: honour quotes in CSV splitting | **4** | 10 |
+| retry: two bugs at once | 5 | 4 |
+| stack: add a method, throw on empty | 4 | 4 |
+| **total round trips** | **17** | **22** |
+
+Both produced correct code on all four — verified by *running* the result, not
+reading it. Ada uses somewhat more context per turn (its system prompt carries
+the compliance doctrine, and it re-reads a file after editing to verify), and
+fewer round trips, which is what costs time and money per call.
+
+**Re-run on the release candidate (0.85.0)** with a different free model
+(`x-preview-f-free` via the same gateway for both agents) and freshly written
+task fixtures, same method — installed package, executed results, each one's
+own session logs:
+
+| task | Ada | oh-my-pi |
+|---|---:|---:|
+| queue: fix a bug and add a method | 8 calls | 8 |
+| parser: honour quotes in CSV splitting | **13** | 15 |
+| retry: two bugs at once | 7 | **4** |
+| stack: add a method, throw on empty | **7** | 10 |
+| **total round trips** | **35** | **37** |
+
+Again 8/8 correct across both agents. On this model the aggregate favours Ada,
+with per-task wins split both ways — the honest reading is functional parity
+with fewer round trips, not dominance.
+
+The one feature where the competing agent still led — reading PDFs, which it
+does by rendering the document in a headless browser and screenshotting it — is
+closed as of this release: `read` now extracts a PDF's text layer with
+`node:zlib` alone. It reports the three states that matter (text extracted /
+scanned, no text layer / unreadable) instead of letting a scanned document pass
+for an empty file; what it deliberately does not do is reproduce exact layout,
+which would need the browser back.
+
+## Built for Enterprise
+
+- **Governed autonomy.** Permission modes (`plan` / `manual` / `auto` / `yolo`) and the Goal Engine's `askBefore` brakes gate irreversible actions (publish, delete, spend) behind explicit approval, in both the CLI and the desktop app. `manual` asks before every write; `auto` is the default; `plan` makes the tree read-only.
+- **Evidence over assertions.** The Goal Engine's judge and the Work Graph's gates both require cited, observed evidence before anything counts as complete — no autonomous run can silently mark itself done.
+- **Retention you can defend.** `ada-cli audit purge --dias N --politica "..."` deletes old ledger files by writing a **chained tombstone** first — which period, how many entries, under what policy, and the closing hash. `audit verify` then reports the gap as *explained* rather than as tampering, so complying with GDPR art. 5.1.e stops looking like covering your tracks. `--dry-run` shows exactly what would go, down the same code path that removes it.
+- **A policy the user cannot switch off.** A third configuration scope lives where the operating system requires administrator rights to write (`/Library/Application Support/Ada/`, `/etc/ada/`, `%ProgramData%\Ada\`). It can only ever *restrict*: a `modoMaximo` ceiling lowers the requested permission mode and never raises it, and tools listed in `denegadas` stay denied even in `yolo`. There is deliberately no environment variable pointing at another file — that would be the back door that voids the policy with one `export`. `ada-cli politica` shows whether it is in force, and whether the file is one this account could edit. Every decision records which rule decided it.
+- **Privacy and audit built in.** `memoryPrivacyLevel: "strict"` (default) blocks PII before it's persisted; every memory write, rejection, and search is hash-chained in an audit log via `/memory-audit` — designed to support GDPR/AI Act obligations without extra tooling.
+- **Secrets isolation.** Provider credentials and MCP tokens never enter the model's prompt context, and nothing in the vault touches disk unencrypted. `auth.json` is encrypted at rest with AES-256-GCM under a key held in the system keychain.
+- **Budgeted, bounded runs.** Every autonomous surface (Goal Engine, Workflows) enforces turn limits, repeat-loop detection, a stop-file kill switch, and token/cost budgets — no open-ended spend.
+- **Deployable as CLI or desktop.** Same SDK, same `settings.json`, same audit trail whether your team works in a terminal or a GUI.
+- **Stays current automatically.** A deterministic daily sync (`scripts/sync-ada.sh` + GitHub Action) re-bases onto upstream pi.dev, so security fixes and new provider support land without manual patch-tracking.
+
+## Ada Intelligence Engine
+
+pi.dev is deliberately minimal — its own philosophy is to skip sub-agents and plan mode and let each team extend it their own way. Ada CLI takes the opposite bet: it ships that orchestration layer as part of the product.
+
+| Module | What it's for |
+|---|---|
+| 🎯 **Goal Engine** (`/goal`) | Pursues an objective autonomously, turn by turn, through fixed TDD phases, gated by a contract (`doneCriteria` + `verifyCommand`) you must approve before it starts. A mandatory judge requires cited evidence before anything is marked done, backed by safety brakes (turn limits, loop detection, stop-file, cost/token budget). |
+| ⚙️ **Workflows** (`/workflow`) | Orchestrates multiple agents in parallel via sandboxed JS scripts, budgeted and resumable after an interruption. Ships 5 ready-to-use builtins: deep research, code review, product build, codebase audit, multi-perspective. |
+| 🕸️ **Work Graph** (`/graph`) | A typed graph connecting intent → requirement → task → file → test. Gates block declaring work "done" without observed evidence — never on the model's word alone. |
+| 🧠 **Memory Engine** (`/memory-audit`, `/memory-consolidate`, `/memory-insights`) | Durable 3-layer memory (global, project, past failures) with full-text session search, a tamper-evident audit log, and a PII scanner that blocks sensitive data before it's ever stored. |
+| ✨ **Prompt Optimizer** | Before processing a request, decides whether to ask up to 3 clarifying questions (`clarify`) or rewrite it as a structured prompt (`enhance`). |
+| 🔐 **Vault** (`/vault`) | Passphrase-encrypted local secret store, shared across the CLI, the desktop app, and subagents of an unlocked session. |
+| 🖥️ **Desktop app** | Tauri 2 + Next.js, running on the exact same SDK and `settings.json` as the CLI. pi.dev is terminal-only. |
+| ⏰ **Scheduler** (`ada-cli schedule`) | Recurring work that runs inside `ada-cli serve`. `maxRuns` and `expiresAt` are **mandatory** — an open-ended recurring job is open-ended spend, and nobody remembers to turn it off. Each job gets its own session so two schedules never contaminate each other's context. |
+| 🔁 **Continual Harness** (`ada-cli refine`) | Turns what a finished session learned into durable notes injected into future prompts. Every proposal **requires cited evidence** (`file:line`, a command and its output, a message from you); the ones without it are rejected and shown to you. The base system prompt is never touched. |
+| 🌐 **Web tools** (`web_search`, `web_fetch`) | Native TypeScript, key from the encrypted vault, SSRF-guarded — private ranges and the cloud metadata endpoint are blocked before the request is made. Opt-in per subagent: network access is never inherited from `readOnly`. |
+| 🔌 **MCP** (`mcp_list_tools`, `mcp_call_tool`) | A real TypeScript MCP client with tokens from the vault. Exactly **two** tools, never one per remote tool: a 40-tool server would flood the system prompt and displace the cacheable prefix. |
+| 💾 **Prompt cache optimizer** | Reorders the system prompt so stable content comes first, meters the real hit rate per provider, and repairs provider-specific quirks. With prefix caching the cost of a change depends on its **position**, not its size — on DeepSeek a miss costs 31x a hit. |
+| 🖧 **Resident sessions** (`ada-cli serve` / `attach` / `session`) | Work survives closing the terminal. Reattach to watch or steer, and run `compact`, `rename`, `fork` or `kill` over the socket. |
+| 🧩 **Editor integration** (`ada-cli acp`) | Speaks Agent Client Protocol over stdio, so Zed and any ACP client can drive Ada instead of the TUI. |
+
+<details>
+<summary><b>Row-by-row comparison vs. upstream pi.dev</b> (verified against both codebases)</summary>
+
+| | pi.dev (upstream) | Ada CLI (this fork) |
+|---|---|---|
+| Product | CLI (`pi`) | CLI (`ada-cli`) **+ desktop app** |
+| Multi-turn autonomy | Not included — skips sub-agents and plan mode by design | **Goal Engine**: contract-first loop, fixed TDD phases, mandatory judge with cited evidence, safety brakes |
+| Orchestrated parallelism | No | **Workflows**: sandboxed JS scripts (`node:vm`) with `agent()/parallel()/pipeline()`, resumable journal, 5 builtins |
+| Work traceability | No | **Work Graph**: typed graph with evidence-gated completion |
+| Cross-session memory | Only within the active session / context files (`AGENTS.md`) | **Memory Engine**: 3 durable layers + full-text session search + tamper-evident audit log + PII scanner |
+| Prompt optimization | No | **Prompt Optimizer**: `clarify` or `enhance` before processing |
+| Secrets | No | **Vault**, encrypted, shared CLI/desktop/subagents |
+| Slash commands | pi.dev's base set | + `/goal` `/workflow` `/graph` `/vault` `/memory-audit` `/memory-consolidate` `/memory-insights` |
+| Anti-recursion | N/A | `goal_*`/`workflow`/`graph_add_nodes`/memory tools register only on the main session — subagents never self-orchestrate |
+| Upstream sync | — (it is upstream) | Deterministic daily reset + delta reapply, no manual merges |
+
+</details>
+
+<details>
+<summary><b>Ada CLI vs. Prime Agent</b> (another pi.dev fork, 17k+ ⭐)</summary>
+
+[PrimeIntellect-ai/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent) is also built on `earendil-works/pi`, with a persistent-Python-kernel execution model and a self-improving "Continual Harness". Full breakdown with sources: [docs/AUDIT.md §8](../../docs/AUDIT.md).
+
+| Capability | Ada CLI | Prime Agent | Edge |
+|---|---|---|---|
+| Background sessions surviving terminal close | `ada serve` / `ada attach` / `ada session` | Daemon-backed `attach`/`detach` | Even |
+| Editor integration (Agent Client Protocol) | `ada acp` | `acp` mode | Even |
+| Scheduling / recurring work | `ada-cli schedule`, with mandatory `maxRuns`/`expiresAt` | `/heartbeat`, cron schedules | Even |
+| Self-improving instructions | `ada-cli refine`, every proposal requires cited evidence | `/refine` with rollback snapshots | Even |
+| Agent-to-agent messaging | Deliberately blocked (anti-recursion by design) | Built in | Design trade-off, not a gap |
+| Executable / Python-backed skills | Markdown only, by choice | Python packages + skill-creator | Prime Agent |
+| MCP integration | Native TypeScript client, tokens from the vault | Protocol lives inside the Python kernel | **Ada CLI** |
+| Web search | `web_search`/`web_fetch`, key in the vault, SSRF-guarded | Python skill, key in plaintext `auth.json` | **Ada CLI** |
+| Prompt-cache optimisation | Prefix stabilisation + per-provider hit-rate metering | None | **Ada CLI** |
+| Work traceability graph | Yes, evidence-gated | None | **Ada CLI** |
+| Native desktop app | Yes | TUI-only | **Ada CLI** |
+| Dedicated encrypted secrets vault | Yes | Plain `auth.json` | **Ada CLI** |
+| Mandatory evidence-backed judge | Yes, by default | User-configurable gates, not forced | **Ada CLI** |
+
+See [docs/AUDIT.md](../../docs/AUDIT.md) for the full technical audit, the exact fork/sync mechanics, and the capability-by-capability parity breakdown — including what we deliberately chose *not* to copy, and why.
+
+</details>
+
+### The three guarantees, and what they are not
+
+These are enforced in code, not by policy. Each line is checkable — open the file and read it.
+
+| Guarantee | Where it is enforced |
+|---|---|
+| **A goal cannot complete without a judge citing evidence.** The judge is independent, sees only the goal, its `doneCriteria`, the `verifyCommand` and the cited evidence, and runs on its own session — on a different model when the workers are configured on a cheaper tier. No verdict, no completion. | `workflows/goal-engine/engine.ts` (`runJudge`), `resource-loader.ts` |
+| **Subagents cannot orchestrate or write durable memory — structurally.** The tools are not registered in a subagent's registry at all; it is not a permission check that could be bypassed or relaxed. Asserted in `test/anti-recursion-tools.test.ts`. | `agent-session.ts` (`_isSubagentSession` gates) |
+| **Memory is written through a PII scanner and a hash-chained audit log.** Rejections are logged too, and `/memory-audit` verifies the chain. | `memory-engine/scanner.ts`, `memory-engine/audit.ts` |
+
+**What Ada does *not* claim.** The workflow interpreter rejects scripts that use `require`, `process` or `import`, but that check is a **text filter, not a security boundary**: `node:vm` is escapable through the constructor chain, and we verified it — a script reaching the host process, its 67 environment variables and its working directory. Node documents this itself: *«The node:vm module is not a security mechanism.»* The filter's real job is to turn naive host access into a readable error, and the guard for that limit lives in `test/workflows-sandbox-limite.test.ts`. The **leaf agents Ada spawns are ordinary sessions** with `read`/`bash`/`edit`/`write` and the same OS permissions as any coding agent, yours included. **Ada is not an OS sandbox**; for untrusted work, run it in a container. What Ada does contain is narrower and real: credentials live in an encrypted vault that is permanently out of the agent's reach, every tool call and command is recorded in a hash-chained ledger, and extensions go through the same approval policy as the agent.
+
+Engine command reference, `settings.json` schema, and model-routing rules: [docs/AUDIT.md §4](../../docs/AUDIT.md) covers the architecture; slash-command syntax for `/goal`, `/workflow`, `/graph`, `/memory-*`, and `/vault` is documented inline via `--help` and `/hotkeys` in the CLI itself.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md) — install, authenticate, run a first session
+- [Using Ada](docs/usage.md) — interactive mode, slash commands, CLI reference
+- [TUI reference](docs/tui.md) — full keyboard shortcuts, message queue, tree navigation
+- [Sessions](docs/sessions.md) · [Compaction](docs/compaction.md) — branching, forking, context management
+- [Settings](docs/settings.md) — global and project configuration
+- [Security](docs/security.md) · [Containerization](docs/containerization.md) — project trust, sandboxing
+- [Extensions](docs/extensions.md) · [Skills](docs/skills.md) · [Prompt templates](docs/prompt-templates.md) · [Themes](docs/themes.md) · [Ada packages](docs/packages.md)
+- [SDK](docs/sdk.md) · [RPC mode](docs/rpc.md) · [JSON mode](docs/json.md) — headless and embedded usage
+- [docs/AUDIT.md](../../docs/AUDIT.md) — fork architecture, sync mechanics, and the full competitive analysis
 
 ## 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.
-
-**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 permission popups.** Run in a container, or build your own confirmation flow with [extensions](#extensions) inline with your environment and security requirements.
-
-**No plan mode.** Write plans to files, or build it with [extensions](#extensions), or install a package.
-
-**No built-in to-dos.** They confuse models. Use a TODO.md file, or build your own with [extensions](#extensions).
-
-**No background bash.** Use tmux. Full observability, direct interaction.
-
-Read the [blog post](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/) for the full rationale.
-
----
-
-## CLI Reference
-
-```bash
-pi [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 only, or one package source
-pi update --all              # Update pi and packages
-pi update --extensions       # Update packages only
-pi update --models           # Refresh model catalogs 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
-```
-
-`pi config` and project package commands accept `--approve`/`--no-approve` to trust or ignore project-local settings for one command. `pi update` never prompts for project trust.
-
-### Modes
-
-| Flag | Description |
-|------|-------------|
-| (default) | Interactive mode |
-| `-p`, `--print` | Print response and exit |
-| `--mode json` | Output all events as JSON lines (see [docs/json.md](docs/json.md)) |
-| `--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:
-
-```bash
-cat README.md | pi -p "Summarize this text"
-```
-
-### Model Options
-
-| Option | Description |
-|--------|-------------|
-| `--provider <name>` | Provider (anthropic, openai, google, etc.) |
-| `--model <pattern>` | Model pattern or ID (supports `provider/id` and optional `:<thinking>`) |
-| `--api-key <key>` | API key (overrides env vars) |
-| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max` |
-| `--models <patterns>` | Comma-separated patterns for Ctrl+P cycling |
-| `--list-models [search]` | List available models |
-
-### Session Options
-
-| Option | Description |
-|--------|-------------|
-| `-c`, `--continue` | Continue most recent session |
-| `-r`, `--resume` | Browse and select session |
-| `--session <path\|id>` | Use specific session file or partial UUID |
-| `--fork <path\|id>` | Fork specific session file or partial UUID into a new session |
-| `--session-dir <dir>` | Custom session storage directory |
-| `--no-session` | Ephemeral mode (don't save) |
-| `--name <name>`, `-n <name>` | Set session display name at startup |
-
-### Tool Options
-
-| Option | Description |
-|--------|-------------|
-| `--tools <list>`, `-t <list>` | Allowlist specific tool names across built-in, extension, and custom tools |
-| `--exclude-tools <list>`, `-xt <list>` | Disable specific tool names across built-in, extension, and custom tools |
-| `--no-builtin-tools`, `-nbt` | Disable built-in tools by default but keep extension/custom tools enabled |
-| `--no-tools`, `-nt` | Disable all tools by default |
-
-Available built-in tools: `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`
-
-### Resource Options
-
-| Option | Description |
-|--------|-------------|
-| `-e`, `--extension <source>` | Load extension from path, npm, or git (repeatable) |
-| `--no-extensions` | Disable extension discovery |
-| `--skill <path>` | Load skill (repeatable) |
-| `--no-skills` | Disable skill discovery |
-| `--prompt-template <path>` | Load prompt template (repeatable) |
-| `--no-prompt-templates` | Disable prompt template discovery |
-| `--theme <path>` | Load theme (repeatable) |
-| `--no-themes` | Disable theme discovery |
-| `--no-context-files`, `-nc` | Disable AGENTS.md and CLAUDE.md context file discovery |
-
-Combine `--no-*` with explicit flags to load exactly what you need, ignoring settings.json (e.g., `--no-extensions -e ./my-ext.ts`).
-
-### Other Options
-
-| Option | Description |
-|--------|-------------|
-| `--system-prompt <text>` | Replace default prompt (context files and skills still appended) |
-| `--append-system-prompt <text>` | Append to system prompt |
-| `--tui-mode <mode>` | TUI mode: `regular` (default) or experimental `fullscreen` |
-| `--use-theme <name[/name]>` | Set the initial interactive theme for this run without changing settings |
-| `--verbose` | Force verbose startup |
-| `-a`, `--approve` | Trust project-local files for this run |
-| `-na`, `--no-approve` | Ignore project-local files for this run |
-| `-h`, `--help` | Show help |
-| `-v`, `--version` | Show version |
-
-### File Arguments
-
-Prefix files with `@` to include in the message:
-
-```bash
-pi @prompt.md "Answer this"
-pi -p @screenshot.png "What's in this image?"
-pi @code.ts @test.ts "Review these files"
-```
-
-### Examples
-
-```bash
-# Interactive with initial prompt
-pi "List all .ts files in src/"
-
-# Non-interactive
-pi -p "Summarize this codebase"
-
-# Non-interactive with piped stdin
-cat README.md | pi -p "Summarize this text"
-
-# Named one-shot session
-pi --name "release audit" -p "Audit this repository"
-
-# Different model
-pi --provider openai --model gpt-4o "Help me refactor"
-
-# Model with provider prefix (no --provider needed)
-pi --model openai/gpt-4o "Help me refactor"
-
-# Model with thinking level shorthand
-pi --model sonnet:high "Solve this complex problem"
-
-# Limit model cycling
-pi --models "claude-*,gpt-4o"
-
-# Read-only mode
-pi --tools read,grep,find,ls -p "Review the code"
-
-# Disable one extension or built-in tool while keeping the rest available
-pi --exclude-tools ask_question
-
-# High thinking level
-pi --thinking high "Solve this complex problem"
-```
-
-### Environment Variables
-
-| Variable | Description |
-|----------|-------------|
-| `AI_AGENT` | Set to `pi` by the CLI and RPC entry points so generic tooling can attribute child processes to Pi |
-| `PI_CODING_AGENT` | Set to `true` by the CLI and RPC entry points so child processes can detect that they run inside Pi |
-| `PI_CODING_AGENT_DIR` | Override config directory (default: `~/.pi/agent`) |
-| `PI_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 Pi version update check at startup. This prevents the `pi.dev` latest-version request |
-| `PI_TELEMETRY` | Override install/update telemetry and provider attribution headers. Use `1`/`true`/`yes` to enable or `0`/`false`/`no` to disable. This does not disable update checks |
-| `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache (Anthropic: 1h, OpenAI: 24h) |
-| `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |
-
-Commands run by the LLM-callable bash tool also receive current session metadata:
-
-| Variable | Description |
-|----------|-------------|
-| `PI_SESSION_ID` | Current session ID |
-| `PI_SESSION_FILE` | Absolute session JSONL path; unset for ephemeral sessions |
-| `PI_PROVIDER` | Currently selected model provider |
-| `PI_MODEL` | Currently selected model ID |
-| `PI_REASONING_LEVEL` | Current effective reasoning level |
-
-These values are resolved when each command starts. See [Environment Variables](docs/environment-variables.md#bash-tool-session-environment) for semantics, examples, and custom-tool opt-out.
-
----
+Ada stays extensible instead of opinionated: no baked-in MCP (build a skill or extension instead — [why](https://mariozechner.at/posts/2025-11-02-what-if-you-dont-need-mcp/)), no forced sub-agent framework, no permission popups, no built-in to-dos. Build exactly what your workflow needs with [extensions](docs/extensions.md), [skills](docs/skills.md), or a third-party [Ada package](docs/packages.md) — see the [original pi.dev rationale](https://mariozechner.at/posts/2025-11-30-pi-coding-agent/).
 
 ## Contributing & Development
 
-See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines and [docs/development.md](docs/development.md) for setup, forking, and debugging.
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) and [docs/development.md](docs/development.md).
 
 ## License
 
@@ -705,9 +250,9 @@ MIT
 
 ## See Also
 
-- [@earendil-works/pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai): Core LLM toolkit
-- [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core): Agent framework
-- [@earendil-works/pi-tui](https://www.npmjs.com/package/@earendil-works/pi-tui): Terminal UI components
+- [@earendil-works/pi-ai](https://www.npmjs.com/package/@earendil-works/pi-ai) — core LLM toolkit
+- [@earendil-works/pi-agent-core](https://www.npmjs.com/package/@earendil-works/pi-agent-core) — agent framework
+- [@earendil-works/pi-tui](https://www.npmjs.com/package/@earendil-works/pi-tui) — terminal UI components
 
 <p align="center">
   <a href="https://pi.dev">pi.dev</a> domain graciously donated by