@pi-unipi/unipi 3.0.0-alpha.21 → 3.0.0-alpha.22

package/CHANGELOG.md

@@ -6,6 +6,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [3.0.0-alpha.22] — 2026-10-03
+
+### Changed
+- `utility`: harness annotations (e.g. the Fusion "delegate shell work" nudge) render once in simple mode instead of three rows.
+- `utility`: simple mode hides tool-result images until Ctrl+O; images no longer overlap the text below them in any render style. (UNI-71)
+- `utility`: simple mode spacing — text sits directly above its tool group, one blank row before the next text; same in sidekick/subagent panels. (UNI-45)
+- `utility`: the transcript render style now defaults to `simple` (one collapsed line per tool call). Set `utility.render.style` to `regular` in `/unipi:settings` for Pi's own view. An unknown stored value now falls back to the default instead of `regular`.
+- `ask-user`: `ask_user` is removed from the agent's tools while disabled in settings; the unavailable row says why (turned off vs no interactive UI). (UNI-69)
+- `long-horizon`: `/unipi:regular` and goal stop update the footer mode immediately. (UNI-66)
+
+### Docs
+- v3 docs rewritten in plain controlled English (README, package READMEs, guide, reference, architecture, Unicrab story), with screenshots.
+
 ## [3.0.0-alpha.21] — 2026-10-03
 
 ### Added

package/README.md

@@ -1,126 +1,193 @@
-<p align="center"><img src="docs/assets/unipi-logo.png" width="200" alt="UniPi"></p>
+<p align="center">
+  <img src="docs/assets/unipi-logo.png" width="220" alt="UniPi logo: Unicrab behind three terminal screens">
+</p>
+
+<h1 align="center">UniPi</h1>
+
+<p align="center">
+  <b>Extensions that make the Pi coding agent finish long work, remember it and show it.</b>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@pi-unipi/unipi"><img src="https://img.shields.io/npm/v/%40pi-unipi%2Funipi?label=npm&color=e8452c" alt="npm version"></a>
+  <a href="https://github.com/Neuron-Mr-White/unipi/actions/workflows/ci.yml"><img src="https://github.com/Neuron-Mr-White/unipi/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/pi-%5E0.87.1-555" alt="Pi 0.87.1 or later">
+</p>
+
+<p align="center">
+  <a href="docs/guide/getting-started.md">Getting started</a> ·
+  <a href="docs/README.md">Docs</a> ·
+  <a href="docs/architecture/README.md">Architecture</a> ·
+  <a href="docs/reference/commands.md">Commands</a> ·
+  <a href="docs/story/unicrab.md">Meet Unicrab</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
+
+## Install
 
-# Unipi
-
-23 workspace packages that turn Pi into a full development workstation. Structured workflows, persistent memory, parallel agents, web research, notifications, context management, command autocomplete, and a live status bar — all wired together through a shared event system.
-
-One command installs everything:
 ```bash
 pi install npm:@pi-unipi/unipi
 ```
 
-## Requirements
-
-- **Pi (`@earendil-works/pi-coding-agent`) `^0.87.1`** — Unipi 3.0.0-alpha tracks the Pi 0.87 SDK (extension boundary events, `SessionManager`-canonical context, `TranscriptContext` custom-provider inputs, native prompt-cache warming). Older Pi releases still load most extensions, but npm will flag the peer dependency mismatch; pin `@pi-unipi/*@<3.0.0` if you must stay on an older Pi.
-
-## What You Get
-
-**[Workflow](./packages/workflow/README.md)** — **plan mode** (`/unipi:plan`, `Alt+P`) and **permission modes** (`ask` · `auto` · `full`). Plan mode makes a session read-only except for its plan file; auto mode lets jev judge ambiguous bash before it runs.
-
-**[Long-Horizon](./packages/long-horizon/)** — Mode-gated long-horizon execution: `/goal` (one objective until verifiably true, propose+verify), `/ralph` (task-file iteration loops), `/swarm` (independent fan-out + synthesis), `/graph` (dependent multi-step work). A TypeSafe jev prompt judge routes each turn; one automation owner per session with park/resume; runaway-guard steering; token/turn/stall budgets.
-
-**[Memory](./packages/memory/README.md)** — Markdown files + [MemPalace](https://github.com/mempalace/mempalace) semantic search share a memory palace across pi, Devin, and zcode. Facts, preferences, and decisions persist across sessions; v2 data converts via `/unipi:memory migrate`.
-
-**[Compactor](./packages/compactor/README.md)** — Compaction that keeps work going. Lossless zero-LLM summaries (or Pi's model summary), rebuilt from the full session history, led by the live goal/ralph/kanboard state; the full history stays searchable with session recall.
-
-**[Prefix-cache architecture](./docs/prefix-cache-architecture.md)** — Append-only request discipline, explicit cache epochs, deterministic tools, privacy-safe diagnostics, provider limitations, and bounded cold-epoch output.
-
-**[Subagents](./packages/subagents/README.md)** — Parallel execution with file locking. Spawn background agents to research, fix, or build while the main agent keeps going.
-
-**[Fusion](./packages/fusion/README.md)** — Run two models as one: a frontier lead delegates to a cheaper persistent sidekick that keeps its own context and shells, and stays in the loop while the sidekick works. Pair them from `/unipi:model`; `/unipi:fusion-stats` shows what the sidekick saved you.
-
-**[Background Tasks](./packages/background-tasks/README.md)** — Long-running commands and delegate agents that survive the turn that started them, with a live dock, output capture, and a wake line while the agent waits on them.
-
-**[Web API](./packages/web-api/README.md)** — Web search, page reading, content summarization. Defaults to [wigolo](https://github.com/KnockOutEZ/wigolo), a local-first engine with multi-engine search and on-device reranking — $0/query, no API key. Plus a smart-fetch engine with browser-grade TLS fingerprinting. Paid providers as fallbacks, and auto-selection falls through when a provider is unavailable.
-
-
-**[MCP](./packages/mcp/README.md)** — Browse 7,800+ MCP servers, add them interactively. Tools from servers register automatically as Pi tools.
-
-**[Notify](./packages/notify/README.md)** — Push notifications to native OS, Gotify, Telegram, or ntfy. Per-event platform routing plus native focus suppression so alerts can stay quiet while Pi is already focused.
-
-**[Footer](./packages/footer/README.md)** — Persistent status bar showing live stats from every package. Now with the Glance footer: a framed input box with an animated rainbow brand, git branch title, and a live session strip (turns, wall/tool time, TTFT, tok/s, cache hit). Responsive layout, presets, per-segment toggling.
-
-**[BTW](./packages/btw/README.md)** — Inline side questions (`/unipi:btw`) answered by a fresh read-only session seeded from the current context — the main agent never sees them.
+UniPi needs [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+`0.87.1` or later. This command installs 21 extension packages. Each package
+also works alone.
+
+<p align="center">
+  <img src="docs/assets/screenshots/simple-memory-glance.png" alt="A UniPi session in simple mode with memory recall, memory save and the glance footer">
+</p>
+
+This screenshot shows one turn in a demo session:
+
+- **Simple mode** (the default) shows each tool call as one line.
+- **Memory** finds the test setup from an earlier session and saves a new fact
+  for later sessions.
+- **The glance footer** frames the input box. It shows the git branch, the
+  mode, the context use and the model. The strip below it shows turns, steps,
+  wall time, tool time, time to first token, tokens per second and cache hits.
+
+## Why UniPi
+
+Pi is a small coding agent for the terminal. It reads files, edits files and
+runs commands. UniPi adds the parts that a long session needs.
+
+| UniPi gives you | How |
+|---|---|
+| **Memory between sessions** | Facts and decisions go to Markdown files and to a MemPalace index. |
+| **Two models as one** | Fusion pairs a lead model with a sidekick model. |
+| **Work that finishes** | `goal`, `ralph`, `swarm` and `graph` modes keep the agent on a long task. |
+| **A warm prompt cache** | Changing state goes into new tail messages. The prefix stays the same. |
+| **One driver for each turn** | A turn arbiter selects one continuation when the agent stops. |
+| **Compaction with no model call** | The default `vcc` method rebuilds the summary from the full session history. |
+| **Parallel hands** | Subagents and background tasks work while the lead continues. |
+| **A board for deferred work** | Kanboard keeps tasks in Markdown files, with a web UI and a terminal UI. |
+| **Hang detection** | Watchdog asks a small judge model about long tool calls. |
+| **A short transcript** | Simple mode shows one line for each tool call. Ctrl+O expands it. |
+
+## Proof
+
+Each feature below exists because published results support it. The numbers
+come from the linked sources. They are not UniPi benchmarks. The "why" column
+is our opinion.
+
+| Feature | Benchmark | Why we have it | Source |
+|---|---|---|---|
+| **Memory** | 96.6% recall@5 on LongMemEval, with raw semantic search and 0 API calls. | Chat assistants lose about 30% accuracy when facts span many sessions. We want the agent to find last week's decision without a model call. MemPalace does this on your machine. | [MemPalace](https://github.com/MemPalace/mempalace) · [LongMemEval](https://arxiv.org/abs/2410.10813) |
+| **Fusion** | Frontier-level FrontierCode score at up to 60% lower cost. | Most turns in a coding session are routine edits and commands. We think a frontier model should plan and review, and a lower-cost model should do the typing. | [Devin Fusion](https://cognition.com/blog/devin-fusion) |
+| **Fusion with two frontier models** | 69.0% on DRACO for two frontier models together. The best single model scored 65.3%. | Different models make different mistakes. A second strong model finds errors that one model misses. Use two frontier models when quality matters more than cost. | [OpenRouter Fusion](https://openrouter.ai/blog/announcements/fusion-beats-frontier/) · [Mixture-of-Agents](https://arxiv.org/abs/2406.04692) |
+| **Goal** | HumanEval pass@1 went from 80% to 91% with a loop on test feedback. | An agent that grades its own work stops too early or claims success. Self-written checks can hide real failures. Our goal loop continues until a separate verifier agrees, inside turn and stall budgets. | [Reflexion](https://arxiv.org/abs/2303.11366) · [Self-authored verification](https://arxiv.org/abs/2607.24300) |
+| **Ralph** | Six repositories overnight for $297 in API cost (a reported hackathon result). | Long tasks do not fit in one context window. A checklist file keeps the progress on disk. Each iteration works the next items and checks them off. A verifier reads the file before the loop ends. We think a simple loop is the right tool for checklist work. | [Ralph loop](https://ghuntley.com/ralph/) · [YC hackathon report](https://paddo.dev/blog/ralph-wiggum-autonomous-loops/) |
+| **Swarm** | 90.2% higher than a single agent on Anthropic's research eval. | Independent items do not need to wait for each other. Each worker gets a clean context, and the lead reads only the summaries. A swarm uses more tokens, so we keep it for wide work. | [Anthropic multi-agent research](https://www.anthropic.com/engineering/multi-agent-research-system) |
+| **Graph** | Up to 3.7× lower latency, 6.7× lower cost and about 9% higher accuracy than ReAct. | Many tasks have steps that need earlier results. A graph runs the independent steps at the same time. Each step gets only the inputs it needs. | [LLMCompiler (ICML 2024)](https://arxiv.org/abs/2312.04511) |
+| **Prefix cache** | Up to 90% lower cost and 85% lower latency for long prompts. | Each agent turn sends the full conversation again. In our UniPi 2.4 logs, each cache miss sent about 62,700 tokens again at the full price. UniPi keeps the prefix byte-identical, so a turn pays full price only for the new tail. | [Anthropic prompt caching](https://claude.com/blog/prompt-caching) · [Modular handbook](https://handbook.modular.com/inference-optimization/prefix-caching/) · [our cache study](docs/deepseek-cache-rate-research.md) |
+
+Long work matters more each year. METR measured that the length of software
+tasks that agents can finish doubles about every 7 months
+([METR](https://metr.org/blog/2025-03-19-measuring-ai-ability-to-complete-long-tasks/)).
+UniPi gives these longer runs memory, budgets and a verifier.
+
+Two notes on the sources. OpenRouter's Fusion uses a panel of models and a
+judge. UniPi Fusion uses a lead and a sidekick. The Ralph numbers are a
+reported result, not a controlled benchmark.
+
+The [architecture pages](docs/architecture/README.md) show how each mechanism
+works in UniPi, with the limits from the source.
+
+## Kanboard
+
+Kanboard is a task board for each project. You and the agent use the same
+board. The agent claims a task, works it, and sends it to review with a
+summary. You approve it or send it back with a note.
+
+<p align="center">
+  <img src="docs/assets/screenshots/kanboard-dashboard.png" alt="Kanboard dashboard: tasks waiting on you, running agents, ready tasks and a 14-day throughput chart">
+</p>
+
+The dashboard shows what needs you across all projects. You can approve a
+review or answer a blocked question in one click.
+
+<p align="center">
+  <img src="docs/assets/screenshots/kanboard-board.png" alt="Kanboard board view with Backlog, Todo, In Progress, Blocked, In Review and Done lanes">
+</p>
+
+- Run `/unipi:kanboard open` to open the board in your browser.
+- Run `/unipi:kanboard-add <title>` to add a task without an agent turn.
+- Run `/unipi:kanboard-do <request>` to give the agent a budget of tasks and
+  board writes.
+- Run `/unipi:kanboard-autowork start` to let the agent work every ready task.
+
+The screenshots use demo data. Read the [Kanboard README](packages/kanboard/README.md).
+
+## Harness architecture
+
+UniPi adds these mechanisms to the Pi harness. Each page gives the problem, a
+diagram, the limits from the source, and the files to read.
+
+| Mechanism | Problem it solves |
+|---|---|
+| [Event bus](docs/architecture/event-bus.md) | 21 packages must work together without import-time coupling. |
+| [Turn arbiter](docs/architecture/turn-arbiter.md) | Several packages want to continue the run when the agent stops. Only one may act. |
+| [Prefix cache](docs/architecture/prefix-cache.md) | One changed byte in the request prefix makes the provider bill the full context again. |
+| [Compaction](docs/architecture/compaction.md) | A summary must keep the live task, and it must not grow at each compaction. |
+| [Long-horizon](docs/architecture/long-horizon.md) | Multi-turn work needs one driver, a separate judge and hard budgets. |
+| [Delegation](docs/architecture/delegation.md) | Work goes to other models and processes. Each one needs a known context boundary. |
+| [Harness messages](docs/architecture/harness-messages.md) | Text from the harness reaches the model as user text. The user must see where it came from. |
+| [Watchdog](docs/architecture/watchdog.md) | A timer cannot tell a hung command from a slow build. |
+
+```mermaid
+flowchart LR
+  stop(["agent stops"]) --> arb{"turn arbiter<br/>1 nudge maximum"}
+  arb -- "priority 100" --> lh["long-horizon<br/>goal · ralph · swarm · graph"]
+  arb -- "priority 50" --> claims["kanboard<br/>claimed task"]
+  arb -- "priority 40" --> auto["kanboard<br/>autowork"]
+  lh --> tail["new tail message<br/>(prefix stays cached)"]
+  claims --> tail
+  auto --> tail
+  tail --> next(["next turn"])
+```
 
-**[Ask User](./packages/ask-user/README.md)** — Structured input for decision gates. Single-select, multi-select, freeform. The agent asks instead of guessing.
+## Packages
 
-**[Kanboard](./packages/kanboard/README.md)** — Web UI and TUI overlay for kanban boards. Parses all workflow documents into cards with progress indicators.
+| Area | Packages |
+|---|---|
+| Finish long work | [Long-Horizon](packages/long-horizon/README.md) · [Workflow](packages/workflow/README.md) · [Kanboard](packages/kanboard/README.md) |
+| Keep context | [Compactor](packages/compactor/README.md) · [Memory](packages/memory/README.md) |
+| Work in parallel | [Fusion](packages/fusion/README.md) · [Subagents](packages/subagents/README.md) · [Background Tasks](packages/background-tasks/README.md) · [BTW](packages/btw/README.md) |
+| Reach outside | [Web API](packages/web-api/README.md) · [MCP](packages/mcp/README.md) · [Notify](packages/notify/README.md) |
+| Stay safe | [Watchdog](packages/watchdog/README.md) · [Skill Registry](packages/skill-registry/README.md) · [Ask User](packages/ask-user/README.md) |
+| See and control | [Footer](packages/footer/README.md) · [Info Screen](packages/info-screen/README.md) · [Input Shortcuts](packages/input-shortcuts/README.md) · [Command Enchantment](packages/autocomplete/README.md) |
+| Maintain | [Utility](packages/utility/README.md) · [Updater](packages/updater/README.md) · [Core](packages/core/README.md) |
 
-**[Info Screen](./packages/info-screen/README.md)** — Dashboard overlay showing module status, tools, and custom data groups.
+The [docs index](docs/README.md#packages) gives one line and the npm name for
+each package.
 
-**[Utility](./packages/utility/README.md)** — Environment info, diagnostics, cleanup, name badge, and Shiki-powered diff rendering.
+## Meet Unicrab
 
-**[Updater](./packages/updater/README.md)** — Checks npm for new versions on session start. Changelog browser and readme browser in TUI overlays.
+<img align="right" src="docs/assets/unicrab-pixel.png" width="120" alt="Unicrab pixel art">
 
-**[Input Shortcuts](./packages/input-shortcuts/README.md)** — Keyboard shortcuts via vim-style chord overlay. Stash/restore, undo/redo, clipboard, thinking toggle.
+Unicrab is the UniPi mascot. It started as the author's pet crab. Now it says
+hello when Pi starts and leaves hints above the input box. Press `Alt+H` for the
+next hint.
 
-**[Command Enchantment](./packages/autocomplete/README.md)** — Enhanced `/unipi:*` autocomplete with full command names, package tags, descriptions, colors, and registry audits that catch stale command docs before release.
+Read [The making of Unicrab](docs/story/unicrab.md): from a real crab, to pixel
+art, to a terminal character that is 7 columns wide.
 
-## Architecture
+<p align="center">
+  <img src="docs/assets/screenshots/unicrab-start.png" alt="The UniPi start screen with Unicrab in half-block pixel art">
+</p>
 
-Packages discover each other through events, not direct imports. Core defines the event types and constants. Every package emits `MODULE_READY` on load and subscribes to events it cares about.
+## Docs
 
-```
-┌─────────────────────────────────────────────────────────┐
-│                        Core                             │
-│              Events, Constants, Utilities                │
-└───────────────────────┬─────────────────────────────────┘
-                        │
-    ┌───────────────────┼───────────────────┐
-    │                   │                   │
-    ▼                   ▼                   ▼
-┌─────────┐       ┌──────────┐       ┌──────────┐
-│ Workflow │       │ Compactor│       │  Memory  │
-│  Skills  │       │  Engine  │       │  Store   │
-└────┬─────┘       └────┬─────┘       └────┬─────┘
-     │                  │                  │
-     └──────────────────┼──────────────────┘
-                        ▼
-                  ┌──────────┐
-                  │  Footer  │ ← Subscribes to all events
-                  └──────────┘
-```
+- [Getting started](docs/guide/getting-started.md)
+- [Commands](docs/reference/commands.md) · [Agent tools](docs/reference/tools.md) · [Shortcuts](docs/reference/shortcuts.md) · [Settings](docs/reference/settings.md) · [Glossary](docs/reference/glossary.md)
+- [Architecture](docs/architecture/README.md)
+- [All docs](docs/README.md)
 
-Coexists triggers enhance behavior when packages are installed together. Workflow skills detect subagents and inject parallel strategies. All skills get MCP tools when MCP is installed. Web-api adds web research to investigation skills. Each package works standalone.
-
-## Commands (Brief)
-
-| Category | Prefix | Examples |
-|----------|--------|----------|
-| Workflow | `/unipi:` | plan (plan mode), permission (permission modes) |
-| Kanboard | `/unipi:` | kanboard (board: capture, work runner, web UI) |
-| Long-Horizon | `/unipi:goal`, `/unipi:ralph`, `/unipi:swarm`, `/unipi:graph` | <prompt>, start, stop, status, resume, clear |
-| Memory | `/unipi:memory-` | process, search, consolidate, forget |
-| Compactor | `/unipi:` | compact-vcc, compact-by-llm, session-recall, compact-stats, compact-doctor, compact-help |
-| Notify | `/unipi:notify-` | settings, test, set-tg, set-ntfy |
-| MCP | `/unipi:mcp-` | add, settings, sync, status |
-| Web | `/unipi:web-` | settings, cache-clear |
-| BTW | `/unipi:btw` | question |
-| Utility | `/unipi:` | env, doctor, status, cleanup, badge-name |
-| Kanboard | `/unipi:kanboard` | toggle, doctor |
-| Footer | `/unipi:footer` | toggle, settings |
-| Watchdog | `/unipi:settings` | jev judges long-running tools; kills or warns when stuck |
-| Updater | `/unipi:` | readme, changelog |
-| Info | `/unipi:info` | dashboard, settings |
-
-## Agent Tools (Brief)
-
-| Tool | Package | What It Does |
-|------|---------|--------------|
-| `create_goal` / `get_goal` / `update_goal` | long-horizon | Goal propose+verify lifecycle |
-| `todowrite` | long-horizon | Visible session plan |
-| `ralph_done` / `loop_status` | long-horizon | Loop iteration + progress |
-| `swarm_report` / `swarm_status` / `swarm_yield` | long-horizon | Fan-out supervision |
-| `update_agent_graph` / `graph_output` / `view_agent_graph` | long-horizon | Dependent work graph |
-| `spawn_helper` / `get_helper_result` | subagents | Parallel agents |
-| `memory_store` / `memory_search` / `memory_delete` | memory | Memory CRUD |
-| `web_search` / `multi_web_content_read` / `web_llm_summarize` | web-api | Web research |
-| `image_generate` / `image_edit` / `image_recognize` | utility | Image generation, editing and vision (recognize hides while the session model has vision) |
-| `notify_user` | notify | Push notifications |
-| `sidekick` / `read_subagent` | fusion | Delegate to the persistent sidekick and collect its report |
-| `bg_run` / `bg_status` / `bg_logs` / `bg_kill` / `bg_delegate` / `bg_result` | background-tasks | Long-running commands and background delegate agents |
-| `ask_user` | ask-user | User input |
-| `session_recall` / `context_budget` | compactor | Context management |
+The docs use STE-flavored English
+([ASD-STE100](https://www.asd-ste100.org/)): short sentences, active voice and
+one meaning for each word. The [style guide](docs/contributing/docs-style.md)
+gives the rules.
 
 ## Development
 
@@ -129,65 +196,33 @@ git clone https://github.com/Neuron-Mr-White/unipi.git
 cd unipi
 npm install
 npm run typecheck
+npm test
 ```
 
-### Project Structure
-
-```
-unipi/
-├── packages/
-│   ├── core/           # Shared constants, events, utilities
-│   ├── workflow/       # plan mode + permission modes
-│   ├── skill-registry/  # per-project skill on/off + jev-judged exposure
-│   ├── long-horizon/  # /goal /ralph /swarm /graph mode-gated execution
-│   ├── memory/         # SQLite + vector search
-│   ├── compactor/      # Context engine
-│   ├── subagents/      # Parallel execution
-│   ├── fusion/         # Lead + sidekick pairing
-│   ├── background-tasks/ # Long-running tasks and delegates
-│   ├── web-api/        # Web research
-│   ├── image/          # Image generation and vision
-│   ├── mcp/            # MCP server integration
-│   ├── notify/         # Push notifications
-│   ├── footer/         # Status bar
-│   ├── btw/            # Side conversations
-│   ├── ask-user/       # Structured input
-│   ├── kanboard/       # Kanban visualization
-│   ├── info-screen/    # Dashboard overlay
-│   ├── utility/        # Diagnostics, diff rendering
-│   ├── updater/        # Auto-update, browsers
-│   ├── input-shortcuts/ # Keyboard shortcuts
-│   ├── autocomplete/   # Enhanced command autocomplete
-│   └── unipi/          # Umbrella package
-├── docs/               # Project documentation (specs, plans, fixes, …)
-├── .unipi/             # Runtime data (config, sessions, ralph)
-└── CHANGELOG.md
-```
-
-### Adding a Package
-
-1. Create `packages/your-package/` with `package.json` and `index.ts`
-2. Depend on `@pi-unipi/core` for constants and events
-3. Emit `MODULE_READY` on load
-4. Add to umbrella package dependencies and imports
-5. Run `npm run typecheck`
+To add a package:
 
-### Running Tests
+1. Create `packages/<name>/` with a `package.json` and an `index.ts`.
+2. Import events and constants from `@pi-unipi/core`.
+3. Emit `MODULE_READY` when the package loads.
+4. Add the package to `packages/unipi/index.ts` and to the root
+   `package.json`.
+5. Run `npm run typecheck` and `npm test`.
 
-```bash
-npm test
-```
+Packages talk over events and shared state holders. Import from
+`@pi-unipi/core`, not from a peer package. The
+[event bus page](docs/architecture/event-bus.md) explains the rules.
 
 ## Contributing
 
-1. Fork the repo
-2. Create a feature branch
-3. Make your changes
-4. Run `npm run typecheck` and `npm test`
-5. Submit a pull request
+1. Fork the repository.
+2. Create a branch.
+3. Make your change.
+4. Run `npm run typecheck` and `npm test`.
+5. Open a pull request.
 
-Keep packages focused. One package, one responsibility. Use events for cross-package communication — no direct imports between packages.
+Keep one job in each package. For docs, follow the
+[style guide](docs/contributing/docs-style.md).
 
 ## License
 
-MIT
+MIT © Neuron Mr White

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/unipi",
-  "version": "3.0.0-alpha.21",
+  "version": "3.0.0-alpha.22",
   "description": "All-in-one extension suite for Pi coding agent",
   "type": "module",
   "license": "MIT",
@@ -82,26 +82,26 @@
     "typebox": "^1.1.38"
   },
   "dependencies": {
-    "@pi-unipi/ask-user": "3.0.0-alpha.21",
-    "@pi-unipi/background-tasks": "3.0.0-alpha.21",
-    "@pi-unipi/btw": "3.0.0-alpha.21",
-    "@pi-unipi/command-enchantment": "3.0.0-alpha.21",
-    "@pi-unipi/compactor": "3.0.0-alpha.21",
-    "@pi-unipi/core": "3.0.0-alpha.21",
-    "@pi-unipi/footer": "3.0.0-alpha.21",
-    "@pi-unipi/fusion": "3.0.0-alpha.21",
-    "@pi-unipi/info-screen": "3.0.0-alpha.21",
-    "@pi-unipi/input-shortcuts": "3.0.0-alpha.21",
-    "@pi-unipi/kanboard": "3.0.0-alpha.21",
-    "@pi-unipi/mcp": "3.0.0-alpha.21",
-    "@pi-unipi/memory": "3.0.0-alpha.21",
-    "@pi-unipi/notify": "3.0.0-alpha.21",
-    "@pi-unipi/skill-registry": "3.0.0-alpha.21",
-    "@pi-unipi/subagents": "3.0.0-alpha.21",
-    "@pi-unipi/updater": "3.0.0-alpha.21",
-    "@pi-unipi/utility": "3.0.0-alpha.21",
-    "@pi-unipi/web-api": "3.0.0-alpha.21",
-    "@pi-unipi/workflow": "3.0.0-alpha.21"
+    "@pi-unipi/ask-user": "3.0.0-alpha.22",
+    "@pi-unipi/background-tasks": "3.0.0-alpha.22",
+    "@pi-unipi/btw": "3.0.0-alpha.22",
+    "@pi-unipi/command-enchantment": "3.0.0-alpha.22",
+    "@pi-unipi/compactor": "3.0.0-alpha.22",
+    "@pi-unipi/core": "3.0.0-alpha.22",
+    "@pi-unipi/footer": "3.0.0-alpha.22",
+    "@pi-unipi/fusion": "3.0.0-alpha.22",
+    "@pi-unipi/info-screen": "3.0.0-alpha.22",
+    "@pi-unipi/input-shortcuts": "3.0.0-alpha.22",
+    "@pi-unipi/kanboard": "3.0.0-alpha.22",
+    "@pi-unipi/mcp": "3.0.0-alpha.22",
+    "@pi-unipi/memory": "3.0.0-alpha.22",
+    "@pi-unipi/notify": "3.0.0-alpha.22",
+    "@pi-unipi/skill-registry": "3.0.0-alpha.22",
+    "@pi-unipi/subagents": "3.0.0-alpha.22",
+    "@pi-unipi/updater": "3.0.0-alpha.22",
+    "@pi-unipi/utility": "3.0.0-alpha.22",
+    "@pi-unipi/web-api": "3.0.0-alpha.22",
+    "@pi-unipi/workflow": "3.0.0-alpha.22"
   },
   "devDependencies": {
     "@earendil-works/pi-agent-core": "^0.87.1",