@agimon-ai/doompi 0.0.1-alpha.2 → 0.0.1-alpha.20

package/README.md

@@ -2,358 +2,229 @@
 
 **A coding agent that loads only the skills and tools you name.**
 
-Plugin systems scope what an agent knows. Nothing scopes what it can reach. Claude Code
-gives you `enableAllProjectMcpServers` and a static denylist, both repository-wide, so
-every session pays for every MCP server's tool schemas whether the task is a database
-migration or a landing page.
+> It begins with one useful MCP server. Then another. Soon the agent fixing a heading
+> wakes up with database tools, browser controls, and their small novel of schemas. This
+> is our config.
 
-Doompi makes both a declared input. Three YAML files decide what a session loads, and
-`--explain` prints the bill before you launch.
+Doompi is a configuration framework for [Pi](https://github.com/earendil-works/pi)
+tailored for people whose agent has one MCP server too many. It turns extensions, skills,
+MCP servers, and system prompts into config instead of background noise.
+
+![Doompi terminal interface showing tasks, Plan mode, and the Leader menu](https://cdn.jsdelivr.net/npm/@agimon-ai/doompi@latest/assets/doompi-tui.png)
+
+Plugin systems scope what an agent knows. Nothing scopes what it can reach. Claude Code's
+`enableAllProjectMcpServers` and static denylist are repository-wide. Doompi draws that
+boundary around the session. Pick a major mode and some domains; add a profile if you want
+one. Four YAML files decide what loads; `doompi --explain` tells you what got in, why, and
+what it costs before launch.
+
+It borrows its shape from [Doom Emacs Core](https://github.com/doomemacs/core): quick to
+start, close to Pi, opinionated where defaults help, and easy to pull apart when they do
+not. Use it as-is, build your own config on top, or raid it for parts.
 
 ## Install
 
 ```bash
-npm install -g @agimon-ai/doompi @earendil-works/pi-coding-agent
+npm install -g @agimon-ai/doompi
 ```
 
-## Quickstart
+The package pins and installs the upstream Pi version used by `dpi`.
 
-```bash
-doompi init                                  # seed ~/.pi/.doom, once per machine
-mkdir .doom && cp ~/.pi/.doom/*.yaml .doom/  # the repository config Doompi reads
-doompi --explain                             # what would load, and why
-doompi                                       # start a session
-```
+## Try DoomPi without replacing your Pi setup
 
-`.doom/` is committed to git, so a checkout carries its own agent configuration. Edit a
-YAML file and the next launch picks it up.
+`dpi` is the comparison runner. Use it to try DoomPi beside your current `pi` customization
+before registering anything in Pi's settings:
 
 ```bash
-doompi --major-mode dev --domains development
-doompi --domains marketing --profile marketing
-doompi --domains analytics --explain
+dpi init                                   # create this repository's .doom configuration
+dpi sync                                   # resolve and synchronize the DoomPi experiment
+dpi                                        # run the DoomPi experiment
+pi                                         # run your existing Pi setup for comparison
 ```
 
-## The three axes
-
-Doompi wraps [Pi](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) and
-resolves a declared configuration into a session rather than asking you to wire one up.
-The three choices are independent: adding a domain requires no knowledge of major modes,
-and swapping a profile changes nothing about either.
+`dpi init` creates `.doom/config.yaml`, `.doom/modes.yaml`, `.doom/domains.yaml`, and
+`.doom/profiles.yaml` in the current repository. It preserves existing files unless you pass
+`--force` and does not create or change `.pi/settings.json`.
 
-| Choice         | Decides                              | Declared in           |
-| -------------- | ------------------------------------ | --------------------- |
-| **Major mode** | what the agent is wrapped in         | `.doom/modes.yaml`    |
-| **Domains**    | what it knows, and what it can reach | `.doom/domains.yaml`  |
-| **Profile**    | who it speaks as                     | `.doom/profiles.yaml` |
+`dpi sync` writes DoomPi's generated state, package alias, and theme resource, but it does
+not register DoomPi in either normal Pi settings file.
 
-A domain names plugins and an MCP allowlist together, so `--domains marketing` and
-`--domains development` are the same agent with different knowledge and a different reach,
-not two different agents. That is the lever for keeping context small, and
-[`--explain`](#minimal-context) prices it before you commit.
+### Sync storage and worktrees
 
-## What is actually different
+Generated sync artifacts are kept out of the repository at:
 
-**Compaction reads state, it does not summarize prose.** When the context fills, Doompi
-does not guess at coordination state from the transcript. It reads the live plan, task
-graph, and team snapshot, and commits them next to the summary as authoritative. The agent
-comes out the other side knowing what it was doing, what is still running, and who is doing
-what. See [Long runs](#long-runs).
+```text
+~/.pi/.doom/sync/<repo-label>--<repo-id-32hex>/
+  shared-cache/objects/<full-build-sha256>/
+  worktrees/<worktree-label>--<worktree-id-32hex>/
+```
 
-**Spec-driven and meta-prompting systems change what the agent is told. Doompi changes what
-it loads.** The two compose fine. This one is about the context window, not the prompt.
+The repository identity comes from Git's canonical common directory, while each
+worktree gets its own identity. Linked worktrees therefore share immutable,
+content-addressed build objects but never share state, `dist`, manifests, staged
+resources, or per-process `run` files. Runtime loading uses only verified artifacts
+materialized in the current worktree directory; it never loads directly from the
+shared cache. The global `~/.pi/.doom/*.yaml` configuration and persistent
+`~/.pi/.doom/plugin-cache` behavior are unchanged.
+
+Older releases may have written state under `<repository>/.pi/doom`. That location
+is a read-only fallback only when the corresponding home-scoped state is absent.
+`doompi sync --check` reports that migration is required, and `doompi sync` rebuilds
+into the home-scoped worktree namespace rather than copying the legacy files. DoomPi
+does not automatically delete legacy, orphaned, or unused generated directories.
+
+For a fair comparison, `dpi` lets Pi merge the same ordinary settings from
+`~/.pi/agent/settings.json` and `<repo>/.pi/settings.json`. It then overlays only these
+DoomPi-owned values in memory:
+
+```json
+{
+  "extensions": ["@agimon-ai/doompi", "!extensions/**"],
+  "themes": ["themes/doom-pi-dark.json"],
+  "theme": "doom-pi-dark",
+  "quietStartup": true
+}
+```
 
-**One configuration serves two readers.** A human gets a keyboard surface that does not
-move; an autonomous agent gets a small tool surface and a context window that compacts
-itself.
+Those four values are never written by `dpi`, including when Pi saves an unrelated option.
+Every other value keeps Pi's normal global/project precedence and trust handling.
 
-## Philosophy
+When you are comfortable with DoomPi and no longer need the side-by-side experiment, register
+it for normal Pi:
 
-**Give the agent fewer things to choose between.** [Major modes, domains, and
-profiles](#major-modes-domains-profiles) decide what loads, so a session carries the skills
-and MCP servers its domains named and nothing else. Whatever still overflows [compacts in
-the background](#long-runs).
+```bash
+doompi init                                  # seed ~/.pi/.doom and Pi integration resources
+doompi sync                                  # register DoomPi in normal Pi settings
+pi                                           # DoomPi now starts through the regular Pi command
+```
 
-**Shift the work onto deterministic workflows.** Autonomous runs are [GitHub Actions
-shaped](#workflows), with jobs, dependencies, steps, timeouts, and declared artifacts, so
-the same job resolves the same way every time.
+`doompi` remains available as an explicit harness when you want one-run matrix flags:
 
-**Keep the keyboard ergonomic.** `SPC` is the whole surface, Spacemacs and Doom Emacs
-style, and [it opens only when the draft is empty](#leader-space), so a half-written prompt
-is never a casualty.
+```bash
+doompi --major-mode dev --domains development
+doompi --domains marketing --profile marketing
+doompi --domains analytics --explain
+```
 
-**Batteries included, without the bloat.** Plan mode, tasks, teams, a supervised runner,
-voice, and workflows ship in the box, but [core is not a
-layer](#core-is-not-a-layer) and every opinion waits behind a layer or a domain.
+## Philosophy
 
-**One major mode, several minor modes.** A session runs under exactly one major mode, which
-is what selects its layers. [Plan, loop, and workflow](#minor-modes) are minor modes: you
-toggle them mid-session, they stack, and they report themselves on a shared status line.
+An agent does not need every tool for every job. Doompi separates the base session from
+the things you switch on for a while: modes choose behavior, domains choose subject
+matter, and profiles choose a point of view.
 
-## Two ways to run
+### Major and minor modes
 
-The launcher resolves your three choices per run and spawns Pi with them. Skills, agents,
-MCP configs, and the persona prompt are assembled into a temporary directory that is
-deleted on exit. Nothing is written back into the repository, and every session pays the
-resolution cost.
+A major mode is the base config. It names the extension layers for development, marketing,
+or whatever else you do. Define as many as you like; only one is active at a time, and you
+can switch it without leaving the session.
 
-`doompi sync` is the other way in, and the Doom Emacs one. Resolve once, write the
-result where Pi looks, then run `pi` yourself.
+Minor modes are battery-included switches inside that base. They start off, stack freely,
+and keep their model tools and skills out of context until turned on. Doompi ships six:
 
-```bash
-doompi init          # seed ~/.pi/.doom, once per machine
-doompi build         # warm the selected launch bundle and skill cache
-doompi sync          # resolve the selection into .pi/
-pi                   # the agent
+- **Help mode** — expose package-owned guidance only while you need it.
+- **Plan mode** — make the repository read-only while you agree on an approach.
+- **Loop mode** — run a prompt now, then run it again on a schedule.
+- **Goal mode** — keep one objective in view until it is done or dismissed.
+- **Workflow mode** — run jobs with dependencies, timeouts, and artifacts.
+- **Voice mode** — replace typing with local speech.
 
-doompi sync --check  # exit non-zero when the synced config is out of date
-```
+### Domains
 
-A synced session takes `--major-mode`, `--domains`, `--profile`, and `--mute` the same way
-the launcher does, and `/major-mode`, `/domains`, and `/profile` all switch in place: the
-extension set is composed on every load rather than frozen at startup, so a reload is
-enough.
-
-Both paths compose the extension set from the same function, `assembleExtensions`, which
-owns load order. Two things differ. A synced session forces `--auto-stop` off, and it
-reads mute from `DOOMPI_MUTE` instead of an argument.
-
-`doompi build` is the launcher warm-up step, analogous to `doom build`: it resolves the
-selected matrix, compiles its exact extension graph into one `.pi/doom/dist` ESM file,
-and warms the persistent skill manifest without starting Pi or changing
-`.pi/settings.json`. A sidecar manifest retains every original extension and exact
-`SKILL.md` path, so resource discovery never depends on the bundle's location.
-Launch still builds on a cache miss, so the command is optional; run it after installing
-or upgrading Doom packages when first-input latency matters.
-
-Syncing does not disturb the launcher. Pi merges the extensions a project declares with
-the ones passed on the command line, so the synced entry stands down whenever it sees the
-composed set already there, which is what the launcher and every detached subagent pass.
-
-## For humans
-
-### Leader Space
-
-`@agimon-ai/doompi-ui` owns the leader state machine, rendering, conflict handling, and the
-core bindings.
-
-Space opens the leader **only when the draft is empty**. With text in the editor, space is
-a space. `ctrl+space` opens the leader either way, and the draft survives the sequence, so
-you never lose a half-written prompt to a keystroke. That is the space the human keeps.
-
-Inside a sequence: `escape` cancels, `backspace` pops one segment, and any key that
-matches nothing cancels. There is no partial state to get stuck in.
-
-Core groups. Every level of the map renders in leader-key alphabetical order, so the table
-below is the order you see:
-
-| Key | Group     | Bindings                                 |
-| --- | --------- | ---------------------------------------- |
-| `e` | extension | `e` external editor, `t` tools browser   |
-| `h` | help      | `h` hotkeys, `l` log metrics             |
-| `m` | models    | `m` select, `n` next, `t` thinking level |
-| `q` | quit      | `q` exit                                 |
-| `s` | sessions  | `f` fork, `n` new, `r` resume, `t` tree  |
-
-`t` is deliberately left out of core at the root and reserved for doom-task.
-
-Optional feature extensions own the bindings for their own commands. The UI never
-hardcodes a binding for a layer that may not be loaded, so a group appears only while its
-extension is loaded:
-
-| Chord                | Source                        | Opens                          |
-| -------------------- | ----------------------------- | ------------------------------ |
-| `SPC a`              | `@agimon-ai/doompi-team`      | subagent fleet                 |
-| `SPC h l`            | `@agimon-ai/doompi-log`       | log metrics                    |
-| `SPC l s`, `SPC l l` | `@agimon-ai/doompi-loop`      | start loops, list/stop loops   |
-| `SPC p p/c/d/f`      | `@agimon-ai/doompi-plan`      | plan normal/cancel/debug/fable |
-| `SPC t t`            | `@agimon-ai/doompi-task`      | tasks                          |
-| `SPC r r`            | `@agimon-ai/doompi-runner`    | background processes           |
-| `SPC v v`            | `@agimon-ai/doompi-voice`     | record or transcribe           |
-| `SPC w w/l/r`        | `@agimon-ai/doompi-workflow`  | launch/manage/recover          |
-| `SPC e f`            | `@agimon-ai/doompi-file-edit` | session edits                  |
-| `SPC e s`            | `@agimon-ai/doompi`           | skills catalog                 |
-| `SPC e c`            | `@agimon-ai/doompi-ui`        | config panel (core binding)    |
-
-Contributions go through the public `@agimon-ai/doompi-ui/leader` API:
-
-```ts
-registerDoomLeaderContribution(pi, {
-  source: '@agimon-ai/doompi-log',
-  bindings: [
-    {
-      id: 'log.metrics',
-      path: [
-        { key: 'h', label: 'help', order: 70 },
-        { key: 'l', label: 'logs', detail: 'telemetry' },
-      ],
-      command: { name: 'log-metrics' },
-    },
-  ],
-});
-```
+A domain is a named group of Pi plugins. It carries the skills and MCP servers for one
+kind of work, and `/domains` switches it while the session is running.
 
-A path excludes the leading `SPC`. The UI turns this into `SPC h l`, dispatches
-`/log-metrics` through the normal editor submission path, and preserves the draft. A
-binding carries either a `command` descriptor or an `action` name, never both. Commands
-stay owned by the extension that registered the slash command; actions route back to the
-contributor through `registerDoomLeaderActionHandlers`, which is what doom-plan uses.
-
-The map is deterministic because the registry is strict:
-
-- Keys are a single lowercase alphanumeric character, paths are at most four segments.
-- Shared group prefixes must agree on label, detail, and order, or the contribution is
-  rejected.
-- Exact chord conflicts are rejected rather than silently overridden. A conflict in a core
-  binding throws; a conflict from a contributor produces a diagnostic and a warning.
-- Re-registering the same `source` replaces that source's complete binding set. Registering
-  an empty set removes it.
-- Rebuilds sort by source name then binding id, so load order does not affect the result.
-- Options render in leader-key alphabetical order at every level. A segment's `order` is
-  group identity that shared prefixes must agree on, not a display position.
-
-Registration runs over Pi's shared extension event bus with a 250 ms timeout. A timeout is
-swallowed, so an extension loaded without the UI degrades quietly instead of failing.
-
-### Major modes, domains, profiles
-
-Three choices, three files, committed to git. They are independent. Adding a domain
-requires no knowledge of major modes, and swapping a profile changes nothing about either.
-
-| Choice          | Loads                                 | Declared in           |
-| --------------- | ------------------------------------- | --------------------- |
-| **Major modes** | a named set of layers                 | `.doom/modes.yaml`    |
-| **Domains**     | plugins, meaning skills and MCP       | `.doom/domains.yaml`  |
-| **Profiles**    | a persona and the brand it speaks for | `.doom/profiles.yaml` |
-
-**Layers are protection and steering.** A layer is a set of Pi extensions plus a set of
-hook groups. The extensions add behavior the agent runs with; the hooks fire around its
-tool calls and can block it, warn it, or steer it back. You define the set you want, along
-the lines of `guardrails`, `lint`, `code-intel`, `team`, `plan-mode`, `runner`, and
-`ask-user`. The hooks themselves live in `.doom/hooks.yaml`, one registry shared by every
-frontend, where a group is either `core` and always loads, or is pulled in by whichever
-layer wants it.
-
-**A major mode is the one you actually pick.** You do not assemble layers one by one at the
-prompt. You select one named major mode with `--major-mode <name>`, and
-`.doom/modes.yaml` says which layers it contains. A session has exactly one, the way
-an Emacs buffer has exactly one major mode. The file can choose the fallback without
-renaming that mode:
+Plugins are catalogued once and domains refer to their names. A configured root may be a
+Codex-compatible marketplace or a folder whose direct children are plugins, so a repository
+with many plugins does not need one entry per directory:
 
 ```yaml
-defaultMajorMode: minimal
-majorMode:
-  minimal: [guardrails, team]
-  copilot: [guardrails, team, plan-mode, runner]
-```
-
-An explicit `--major-mode` wins, then `DOOMPI_MAJOR_MODE`, then
-`defaultMajorMode`. Omitting the field preserves the compatible `copilot` fallback.
+plugins:
+  roots: [plugins]
+  entries:
+    remote-review:
+      source: url
+      url: https://github.com/acme/review-plugin.git
+      ref: v1.2.0
 
-The flag is `--major-mode` and not `--mode` because Pi already owns `--mode` for its output
-mode (`text`, `json`, `rpc`), and for any other value it consumes the argument and ignores
-it without a diagnostic. Use `--output-format` for Pi's output mode.
-
-**Domains are plugins, and a plugin is skills plus MCP.** Selecting a domain decides which
-plugins contribute their skills and subagents, which MCP servers the session can reach,
-and whether the always-on shared skills apply. A domain can take a whole plugin or a named
-subset of one. This is the choice that decides how much the agent can see, so it is also
-the lever for keeping context small. Defaults are plural because domains compose:
-
-```yaml
-defaultDomains: [development, qa]
 domains:
   development:
-    plugins: [plugins/development]
-  qa:
-    plugins: [plugins/qa]
+    description: Implementation and code-review tools.
+    plugins: [pi-development, remote-review]
 ```
 
-Explicit `--domain` or `--domains` flags win, then `DOOMPI_DOMAINS`, then
-`defaultDomains`.
-
-**Profiles are a persona and a brand.** `.doom/profiles.yaml` points at a directory under
-`agents/<brand>/<person>/`, and doom concatenates that person's `profile.md`, `SOUL.md`,
-and `AGENTS.md` into the system prompt: identity and the brand it represents, then voice,
-then role and rules. A profile also carries environment defaults, and nothing else. It
-cannot select domains, major modes, models, presets, or policy, and an exported value
-always beats a profile default.
+DoomPi also checks personal and repository Codex marketplace layouts. Marketplace IDs use
+`plugin@marketplace`. Remote Git and npm sources are downloaded once into the persistent
+`~/.pi/.doom/plugin-cache` directory. Cache entries are reused until their source descriptor
+changes; use a Git SHA or exact npm version for reproducible installs. Home and repository
+catalogs merge, and repository names replace matching home names.
 
-Switching is live. `/major-mode`, `/domains`, and `/profile` re-resolve into the running
-session and reload. A domain or profile switch always applies in place. A major mode switch
-applies in place too unless the new mode changes which extension packages load, since Pi
-freezes the `--extension` set at construction; the picker tells you when a relaunch is
-needed.
+A blog is not one task. Research it, draft it, make the assets, then review it. Turn on the
+`visual` domain while making assets; the other three steps have no reason to carry it.
 
-### Minor modes
+### Profile
 
-A major mode is chosen once per session and selects layers. Minor modes are the opposite:
-you toggle them while the session runs, several can be on at once, and none of them changes
-which extensions are loaded.
+An LLM has no house style until you give it one. A profile can supply a narrative, brand
+rules, or a different voice. It is optional; no profile is a perfectly good profile.
 
-| Minor mode | Toggle               | Owned by                     |
-| ---------- | -------------------- | ---------------------------- |
-| plan       | `/plan`, `SPC p`     | `@agimon-ai/doompi-plan`     |
-| loop       | `/loop`, `SPC l`     | `@agimon-ai/doompi-loop`     |
-| workflow   | `/workflow`, `SPC w` | `@agimon-ai/doompi-workflow` |
+Profile roots remove the need to list every persona folder. A root may itself contain the
+persona files, or its direct-child folders become profiles named after those folders. DoomPi
+recognizes `profile.md`, `SOUL.md`, and `AGENTS.md` and never searches deeper directories.
 
-Each one publishes a label to a shared `MODES` line rather than painting a row of its own,
-so three enabled modes cost one line rather than three. The registry is
-`@agimon-ai/doompi-extension-contracts/mode`.
+```yaml
+profiles:
+  roots: [agents/acme]
+  entries:
+    editor:
+      persona: agents/special/editor
+      env:
+        EDITOR_MODE: strict
+```
 
-## For autonomous agents
+Roots from the home and repository files accumulate relative to their declaring config.
+Repository discoveries replace same-named home discoveries. Explicit entries override
+discovery and can add string environment defaults; repository entries replace matching home
+entries. Select one at launch with `--profile editor` or switch with `/profile`.
 
-### Minimal context
+## What this buys you
 
-Fewer options, better choices. Domains cut the skill list and the tool list together. A
-domain that names three plugins gives the agent those plugins' skills and nothing else,
-and one with an `mcp` allowlist reaches only the servers and proxy upstreams it names.
+Every tool schema and skill name competes for the same context. Loading less has two
+immediate effects:
 
-`--explain` prints what any combination costs before you launch it, and ends with the bill:
+1. You spend fewer tokens before the work begins.
+2. The model has fewer plausible-but-wrong tools and skills to choose from.
 
-```
-$ doompi --domains development --explain
-...
-skills: 24 (from 3 directories)
-
-context cost (tokens)
-  skills prompt       3,772  always on
-  persona                 0  always on
-  startup total       3,772
-  skill bodies       54,145  read on demand
-
-  Excludes MCP tool schemas, which the servers only report once connected,
-  and skills contributed by extensions, which register after startup.
-```
+The savings get larger when each workflow job starts with its own config instead of
+inheriting the last job's toolbox.
 
-Every figure comes from files on disk, so two runs of the same selection print the same
-numbers and you can reproduce them on your own repository rather than trusting these.
+### Copilot
 
-MCP tool schemas are the one cost this cannot price. They exist only after a server
-connects, and pricing them would mean spawning every configured server on a command meant
-to be instant. Scoping them is still a declared choice; the saving is just not counted here.
+I got tired of remembering slash commands, so `SPC` is the map. It opens only when the
+draft is empty; a space in the middle of a prompt remains a space. Press it, read the
+choices, then press the next key.
 
-A domain without an `mcp` key admits everything, and one unscoped domain in the selection
-unfilters the rest. Scoping applies only when every selected domain declares it.
+When the keyboard is the wrong tool, autonomous Voice mode keeps the conversation going.
+You can talk to the agent while doing the chores instead of carrying a laptop around the
+house, and the primary agent can speak its own opening, milestone, and final updates.
 
-A domain can also take a named subset of one plugin's skills, by name or glob.
+### Autopilot
 
-### Workflows
+Copilot helps while you are present. Loop and Workflow keep work moving when you are not.
+Together they can dispatch structured jobs from one live session.
 
-Long autonomous work runs as workflows, in the shape a GitHub Actions user already knows:
-`on:`, `jobs:`, `needs:`, `steps:`, timeouts, and declared artifacts.
+#### Workflows
 
-The payoff is that every step names the session it wants. A workflow is where
-`--major-mode`, `--domains`, and `--profile` stop being things you type and become part of
-the definition, so one run can hand each job exactly the context that job needs and nothing
-else:
+GitHub Actions already has a decent vocabulary for long jobs, so Doompi reuses it. Each job
+declares the Doompi session it wants. Here, implementation gets coding tools; the release
+note waits for it and gets marketing context plus a brand voice:
 
 ```yaml
+on:
+  workflow_dispatch:
+
 jobs:
   implement:
-    needs: intake
     steps:
-      - name: Implement
+      - name: Build the feature
         timeout-minutes: 180
         artifacts: [implementation/report.md]
         interactiveRun:
@@ -361,10 +232,10 @@ jobs:
             doompi --major-mode dev --domains development --auto-stop \
               --cwd "$PWD" "$JOB_SYSTEM_PROMPT"
 
-  announce:
+  release-note:
     needs: implement
     steps:
-      - name: Draft the release note
+      - name: Write the release note
         timeout-minutes: 30
         artifacts: [marketing/release-note.md]
         interactiveRun:
@@ -374,208 +245,322 @@ jobs:
               --cwd "$PWD" "$JOB_SYSTEM_PROMPT"
 ```
 
-Two jobs, two different agents. `implement` runs under a major mode carrying lint and code
-intelligence and a domain carrying coding skills. `announce` drops both, takes a domain
-scoped to a handful of MCP servers, and adds a profile, so the release note comes out in a
-named persona's voice rather than the agent's own. Neither job can drift into the other's
-context, and the same job resolves the same way on every run.
-
-The one real departure from GitHub Actions is `extends:`, which lets a job inherit shared
-setup from a named template rather than repeating it.
+#### Loop
 
-The engine itself is not in this package. `@agimon-ai/doompi-workflow` provides the in-session
-surface on `SPC w`, and its dispatcher exposes `list_workflows` to any session but scopes
-`launch_workflow` to the root session, so a subagent can look but not spawn. The `workflow`
-hook group is `core`, so it loads in any major mode.
+Workflow definitions are exposed like skills, so the agent can choose one for the job. A
+loop can send a subagent to fetch the next task, then dispatch the workflow that matches
+it. One session becomes the dispatcher instead of the place every job has to fit.
 
-### Long runs
+## Features
 
-Tasks, teams, runners, and compaction share one working state, so a long autonomous run
-does not lose its place.
+Doompi is a distribution, not one giant extension. Each package owns one job; shared TUI
+and session contracts make them behave like one. Use the defaults together or replace
+them one at a time.
 
-- **Tasks** (`SPC t`) are a file-backed graph with dependencies and delegation, not a
-  scratch list.
-- **Teams** (`SPC a`) run named subagents asynchronously against that same board,
-  sequentially or in parallel.
-- **Runners** (`SPC r`) replace the bash tool and detach long commands, then reconcile
-  them afterwards.
-- **Compaction** runs on a three-pass ladder in a worker thread, so the session never
-  blocks on it.
+### Configuration and composition
 
-The integration is the point. When compaction summarizes, it does not guess at
-coordination state: it reads the live plan, tasks, and team snapshot, and commits them
-next to the summary as authoritative rather than leaving them to be reconstructed from
-prose. Detached runners reconcile themselves once the context has been rewritten. The
-agent comes out the other side knowing what it was doing, what is still running, and who
-is doing what.
+[`@agimon-ai/doompi`][pkg-doompi] is both an extension and the command-line config compiler. `dpi init`
+creates repository config for an isolated experiment, while `doompi init` creates the personal
+config and registers the permanent Pi integration. The sync commands resolve every major mode
+and domain into a distribution Pi can load quickly. A large major mode with 15 extensions adds
+only 400 ms of code startup time.
 
-## Core is not a layer
+### Leader key
 
-Telemetry, workflow orchestration, the dispatch loop, and editor plumbing ship
-unconditionally and are absent from `modes.yaml` on purpose. They are the reason the
-harness exists, so making them optional would only create broken configurations. Layers
-are for opinions, not foundations.
+[`@agimon-ai/doompi-ui`][pkg-doompi-ui] turns `SPC` into a map of the available commands. It stays out of
+the way when a draft is not empty, and other packages contribute bindings through one
+leader API instead of hardcoding their own menus.
 
-## Who owns what
+### Agent team
 
-Doom Pi is a meta-package. It depends on the Doom closure (`@agimon-ai/doompi-*`) and composes
-it, and it depends on nothing that belongs to the repository consuming it. The Agiflow and
-Agent Hooks extensions are consumer-owned: the repository declares them in its own
-`.doom/modes.yaml` and installs them itself, and they load after the Doom packages.
+[`@agimon-ai/doompi-team`][pkg-doompi-team] runs named subagents asynchronously against a shared task board.
+They can work in parallel, message one another, and use the model policy attached to the
+selected Team package entry. `SPC a l` lists available agents; `SPC a r` opens current-session runs and
+their controls.
 
-That split decides where a specifier resolves. A package the repository declares resolves
-from the repository root, walking its module chain; anything that does not resolve there
-falls back to what ships with the installed meta-package. So a consumer can add a layer
-without Doom Pi knowing the package exists, and Doom Pi can ship its own closure without
-the consumer declaring it.
+### Tasks
 
-Package resources follow the same rule: the UI theme is shipped by `@agimon-ai/doompi-ui`
-and the workflow-recovery skill by `@agimon-ai/doompi-workflow`, each declared in its own
-manifest, so an installed package is discoverable without this checkout. Every Doom package
-publishes through an explicit `files` allowlist, which keeps repository material such as
-`docs/ideas/` out of any tarball.
+[`@agimon-ai/doompi-task`][pkg-doompi-task] keeps a task graph on disk, not a disposable checklist in the
+transcript. Dependencies and delegation survive compaction, and work can be handed to a
+subagent—including a smaller model when the job does not need the expensive one. Seeded
+`minimal` and `copilot` modes select its `task` layer; omit that layer when a major mode
+should not expose the task tool.
 
-A repository is recognised by a Doom or trusted Pi marker: a `.doom/` directory, or an
-existing `.pi/settings.json`. No Nx, pnpm workspace, or plugins profile is required, so a
-plain repository that installs the package can launch it.
+### Runner
 
-## Lazy config
+[`@agimon-ai/doompi-runner`][pkg-doompi-runner] replaces Pi's blocking `bash` tool with
+supervised command execution in the generated default Copilot mode. Short commands still return
+inline; commands that pass the configurable threshold—60 seconds by default—move into the
+background with durable logs. Use `background: true` for an immediate detached run or
+`interactive: true` when the command needs terminal input. Runner IDs, controls, and logs survive
+compaction and context rewrites and remain available through Runner Space at `SPC r r` or the
+`doom-runner` CLI. Platform-specific RMUX binaries are selected automatically, with a fallback
+when RMUX is unavailable. Custom modes must include the `runner` layer to replace `bash`.
 
-Under the launcher, everything is resolved per run and nothing is written back into the
-repository. Editing a YAML file is the entire change.
+### Auto-compact
 
-`doompi sync` trades that for a pinned setup: the same resolution runs once and lands in
-`.pi/doom/`, and a Pi session reads it instead of recomputing it. Edit a YAML file and the
-next session says the config changed, the way doom emacs asks you to re-run `doom sync`.
+Ordinary compaction waits for one summary to save an overgrown session.
+[`@agimon-ai/doompi-autocompact`][pkg-doompi-autocompact] leaves checkpoints instead:
 
-`doompi init` seeds `~/.pi/.doom` with all five file names, but only `config.yaml` from
-there is read at runtime. Major modes, domains, profiles, and hooks are always read from the
-repository `.doom/`, so the other four seeded files affect nothing beyond the inputs hash.
+1. At 50%, it writes the first compact summary.
+2. Later, it combines that summary with the messages since; the model decides whether the
+   result is ready to use.
+3. On the third pass, it combines them again and forces compaction.
 
-Either way the hook registry compiles to the files other frontends read before any harness
-code runs, and `doompi sync` regenerates them.
+The work runs off-thread. Each checkpoint carries the live plan, task graph, team state,
+and user request with it, so coordination does not have to be guessed back out of prose.
 
-## Other frontends
+### Help mode
 
-Pi is the primary frontend. Claude Code, Codex, and Antigravity run through
-`doompi compat <provider>` and share the same domain config as far as each can:
+[`@agimon-ai/doompi-help`][pkg-doompi-help] keeps package guidance out of the default prompt. A fresh parent
+session performs no Help retrieval and exposes no Help skills. Use `SPC h e`, or the existing
+`minor_mode` client in headless sessions, to activate the package indexes; use the same action
+to deactivate them before the next interaction. The initial contributors expose
+`doompi-help`, `workflow-help`, and `doompi-config-help`. Child sessions never assemble the
+Help runtime.
 
-|                     | Pi                | Claude Code                   | Codex                    | Antigravity         |
-| ------------------- | ----------------- | ----------------------------- | ------------------------ | ------------------- |
-| domains to plugins  | yes               | yes                           | yes                      | yes                 |
-| hooks               | from the registry | generated `settings.json`     | generated `hooks.json`   | copied `hooks.json` |
-| MCP servers         | scoped            | scoped                        | unscoped                 | scoped              |
-| MCP proxy upstreams | scoped            | scoped                        | scoped                   | scoped              |
-| major mode          | packages + hooks  | shared hook groups            | shared hook groups       | shared hook groups  |
-| personas            | system prompt     | `--append-system-prompt-file` | `developer_instructions` | no                  |
+### MCP
 
-Compatibility frontends use the selected major mode for shared hook state. Layer packages
-and Pi extensions are loaded only by Pi.
+[`@agimon-ai/doompi-mcp`][pkg-doompi-mcp] is the gate between a session and its servers. It reads `.mcp.json`
+and other common formats, then exposes only the servers and proxy upstreams allowed by the
+selected domains. Switch domains and that boundary reloads with them.
 
-Antigravity is the odd one. It reads its configuration from the workspace and from the
-user's home directory rather than from arguments, so every selection is written to disk
-before launch and reverted when it is no longer selected. Everything the harness writes is
-tracked in a managed-state file, so a file you created by hand is never silently replaced.
-Its hooks are copied from `.antigravity-local/hooks.json`, which is maintained by hand
-rather than generated from the registry.
+### Ask user question
 
-Where a concept has no equivalent, it is left out rather than approximated.
+[`@agimon-ai/doompi-user-feedback`][pkg-doompi-user-feedback] gives the agent a structured question that actually
+waits for an answer. In autonomous Voice mode it skips the modal, narrates the choices,
+and accepts the next spoken response as an ordinary user message.
 
-## Files
+### Logging and telemetry
 
-All Doompi configuration lives in `.doom/`, committed to git.
+Doompi telemetry records counters and spans, never prompt text or file content, in a local
+SQLite database by default. `SPC h l` opens the metrics, and
+[`@agimon-ai/log-sink-mcp`][pkg-log-sink-mcp] gives the agent CLI tools for inspecting its own
+runs.
 
-```
-.doom/
-  config.yaml               projectTrust, plus the selection sync pins
-  domains.yaml              domains, plus aliases for shorthand bundles
-  modes.yaml          layer definitions and the named major modes built from them
-  hooks.yaml                canonical hooks for all three frontends
-  profiles.yaml             persona and environment profiles
-
-agents/<product>/<person>/  persona source, referenced never copied
-```
+### Plan mode
 
-`doompi sync` writes into `.pi/`:
+A promise to "only plan" is not a permission boundary. [`@agimon-ai/doompi-plan`][pkg-doompi-plan] makes the
+repository read-only while the agent explores, persists the plan, and hands it back for
+approval. Use `SPC p p` for normal planning, `SPC p d` for debug planning, `SPC p f` for
+the Fable flow, and `SPC p e` to exit. Turn it on when the approach should be settled
+before the files move.
 
-```
-.pi/settings.json           committed; sync owns extensions, themes, and theme
-.pi/doom/                   generated and gitignored
-  state.json                environment, resolved paths, and the inputs hash
-  mcp.json  mcp-extension.ts  agents/  persona.md  doom-pi-dark.json
-  run/<pid>/                one session's live switches, never the baseline
-    harness-state.json      that session's own state, owned by its process
-```
+### Loop mode
 
-### One owner for the state
+[`@agimon-ai/doompi-loop`][pkg-doompi-loop] is an in-session scheduler. It runs a prompt immediately and then
+repeats it on an interval; several loops can coexist. Use `SPC l s` to start one and
+`SPC l l` to list or stop them. It is for recurring checks and prompts that belong to the
+current session.
 
-The resolved matrix a session runs on is a file, not a set of variables.
-`DOOMPI_STATE` points at it, and everything else the harness exports is derived from
-it: a projection published for the readers that can only see an environment, which are bash
-hooks, the shell launchers, `agent-hooks`, and any process spawned by any of them. Two
-fields never appear there at all, because nothing outside `@agimon-ai/doompi-config` reads
-them and every hook spawn would otherwise copy them: the plugin hook list and the profile's
-environment defaults.
+### Goal mode
 
-Ownership is per process, and that is the point. Doom Team subagents run detached, from an
-environment snapshot, and can outlive the parent that spawned them. So a spawner writes the
-child a file of its own in that run's directory, and any process that finds a file it does
-not own copies it before its first write. A child can neither corrupt its parent's session
-nor lose its own when the parent cleans up.
+[`@agimon-ai/doompi-goal`][pkg-doompi-goal] pins one objective to the session until it completes or you end
+it. Use `SPC g g` for status, `SPC g s` to start, `SPC g e` to end, and `SPC g p` for
+history. Finished goals leave the prompt and tools behind but remain in history when you
+want to restart one.
 
-It also regenerates the two hook files the other frontends read before any harness code
-runs, which live outside `.pi/`:
+### Workflow mode
 
+[`@agimon-ai/doompi-workflow`][pkg-doompi-workflow] runs GitHub Actions-style job graphs with dependencies,
+timeouts, artifacts, and a separate Doompi session for each step. Use `SPC w w` to launch,
+`SPC w l` to manage, `SPC w r` to recover a failed run, and `SPC w e` to give the agent
+workflow tools or take them back. It is for work that needs hard job boundaries and
+explicit handoffs rather than one long conversation.
+
+### Voice mode
+
+[`@agimon-ai/doompi-voice`][pkg-doompi-voice] records and transcribes speech locally; audio stays on the
+machine. `SPC v v` is one-shot manual dictation and never enables Voice tools. `SPC v a`
+toggles autonomous capture; only its exact-active TUI session receives the two Voice
+façades plus the standalone `narrate` tool.
+
+While `narrate` is available, the primary agent calls it before every user-facing final
+response. One concise spoken answer is enough for a short conversation or clarification;
+longer work also gets an opening and meaningful milestone calls. Each ready-to-speak
+utterance is limited to 4,096 characters, waits for physical playback, and returns
+`completed`, `interrupted`, `superseded`, or `failed`.
+
+If the agent never attempts `narrate` during a run, exact-active Voice speaks one sanitized
+turn-end fallback rather than leaving the final response silent. Finals of at most 320
+characters use deterministic speech; longer finals use the configured
+`voice.autoCapture.model` for one bounded summary, with deterministic degradation on
+failure or timeout. Any `narrate` attempt suppresses this safety net, so it cannot duplicate
+or retry direct speech. Voice does not generate automatic intent, plan, milestone, or tool
+progress narration. External task, workflow, and user-feedback narration remains
+available, and the same model continues to provide bounded command correction.
+
+## Configuration
+
+Doompi reads four configuration files:
+
+- `config.yaml` defines runtime settings such as trust, editor, planning, and voice behavior.
+- `modes.yaml` defines extension layers and major modes.
+- `domains.yaml` catalogs plugins and sets session access.
+- `profiles.yaml` supplies persona files and environment defaults.
+
+Each matrix file has two optional layers: personal defaults in `~/.pi/.doom/` and repository
+overrides in `<repository>/.doom/`. Doompi loads both. Unique named entries from either layer
+remain available; a same-named repository entry replaces the complete personal entry. Plugin
+and profile roots from both layers are retained. Relative paths in personal config resolve
+from `~/.pi/.doom/`; relative paths in repository config resolve from the repository root.
+
+### `modes.yaml`: choose behavior
+
+A layer is an ordered bundle of extension packages and hook groups. A major mode names the
+layers that should run together. Packages may be bare strings, or mappings when the package
+accepts configuration:
+
+```yaml
+layers:
+  team:
+    packages:
+      - name: '@agimon-ai/doompi-team'
+        config:
+          models:
+            - model: provider/model-id
+              thinking: high
+  review:
+    packages:
+      - '@scope/review-extension'
+
+defaultMajorMode: copilot
+majorMode:
+  minimal:
+    description: Lean sessions with delegation and little else.
+    layers: [team]
+  copilot:
+    description: General coding with delegation and review tools.
+    layers: [team, review]
 ```
-.claude/settings.json       the "hooks" key only; every other key is preserved
-.codex-local/hooks.json     the whole file
-```
 
-Edit `hooks.yaml` and re-run `doompi sync` to regenerate both.
+Order matters: Doompi assembles layers and their packages from left to right. Put settings
+under the package that consumes them; a layer is composition, not a mystery bag of shared
+configuration. Home and repository `layers` and `majorMode` records merge by name, with the
+repository definition winning a collision.
+
+Choose a mode with `--major-mode copilot`, switch it with `/mode`, or change
+`defaultMajorMode` when one mode should be the ordinary starting point.
+
+### `domains.yaml`: choose content and access
 
-## Selection
+Plugins are catalogued once, then domains refer to their names. A root can be a marketplace,
+a single plugin, or a container whose direct-child folders are plugins. Discovery is
+intentionally nonrecursive: a tool buried five directories down should not load by accident.
 
-Use singular `--profile <name>` for one persona and its environment defaults. Use
-`--domains <name[,name...]>` for plugin bundles. Both `--major-mode` and `--profile` take
-exactly one name, reject a comma, and can be given only once. The removed `--layer`,
-`--layers`, `--profiles`, and `--target` flags throw and point at the replacement, and so
-does the removed `DOOMPI_LAYER` variable: a stale export is worth an error rather than a
-session quietly starting on the default.
+```yaml
+defaultDomains: [development]
+
+plugins:
+  roots: [plugins]
+  entries:
+    remote-review:
+      source: url
+      url: https://github.com/acme/review-plugin.git
+      ref: v1.2.0
+    published-research:
+      source: npm
+      package: '@acme/research-plugin'
+      version: 1.4.0
 
-Defaults when you name nothing: `defaultMajorMode` from `.doom/modes.yaml` and the
-`defaultDomains` list from `.doom/domains.yaml`. Omitting those fields preserves the
-compatible fallbacks: major mode `copilot`, plus domain `marketing` for the legacy
-`marketing` mode or `default` for every other mode.
+domains:
+  development:
+    description: Repository implementation tools.
+    plugins: [coding-tools]
+  review:
+    description: Focused review skills with a narrow MCP boundary.
+    plugins:
+      - name: remote-review
+        skills: [typescript]
+        agents: [reviewer]
+        hooks: false
+        mcp: true
+    mcp:
+      servers: [filesystem]
+      proxy: [github]
+
+aliases:
+  work: [development, review]
+```
 
-Environment equivalents are `DOOMPI_MAJOR_MODE`, `DOOMPI_DOMAINS`, and `DOOMPI_PROFILE`.
-`DOOMPI_PRESET` and `DOOMPI_ADDITIONAL_DIRS` work the same way for `--preset` and
-`--add-dir`. An empty `DOOMPI_DOMAINS` means no domains, not the default. No profile is
-selected unless one is named.
+Here, `coding-tools` is discovered from `plugins/coding-tools`; its manifest name, or its
+folder name when no manifest name exists, becomes the catalog ID. Local roots and entries
+resolve beside the declaring file. Git and npm entries are cached in
+`~/.pi/.doom/plugin-cache`; pin a Git SHA or exact package version when reproducibility
+matters. Domains may load an entire plugin or select only its skills, agents, hooks, and MCP
+configuration. The optional `mcp` mapping is an allowlist, not a request to start every server
+in the repository.
 
-There is one variable per axis. A nested run inherits its launcher's choice because the
-launcher writes the resolved value into the child environment under the same name, so
-anything you exported yourself is what a top-level run uses and what a spawned run
-overrides. These used to be two variables, `DOOM_PI_*` for the selection and
-`AGENT_HARNESS_*` for the resolved projection, with the second outranking the first. Any
-surviving `AGENT_HARNESS_*` variable now throws and names its replacement, because a stale
-export in a shell profile is worth an error.
+Select one or more domains with `--domains development,review`, use an alias such as
+`--domains work`, or switch them with `/domains`. `--no-domains` is useful when the right
+amount of repository context is none.
 
-`DOOMPI_LAYERS`, plural, is a different variable from `DOOMPI_LAYER`. It carries the
-resolved layer components rather than the mode that selected them.
+### `profiles.yaml`: choose a point of view
 
-A repository can also pin the full selection used by a bare `doompi sync` or
-`doompi build`. A flag still wins, then an exported variable, then the matching
-`selection` field, then `modes.yaml`'s `defaultMajorMode` or `domains.yaml`'s
-`defaultDomains`:
+A profile directory becomes discoverable when it directly contains `profile.md`, `SOUL.md`,
+or `AGENTS.md`. A root may be one profile or a container of direct-child profiles. The folder
+name becomes the profile name; Doompi concatenates those three files in that order.
 
 ```yaml
-# .doom/config.yaml
-selection:
-  majorMode: dev
-  domains: [development]
-  profile: house-voice
+profiles:
+  roots: [personas]
+  entries:
+    release-writer:
+      persona: personas/release-writer
+      env:
+        BRAND: acme
+        TONE: concise
+```
+
+With that config, `personas/release-writer/profile.md` is enough to discover
+`release-writer`. The explicit entry is optional; use one when the profile needs another name,
+an exact persona path, or string environment defaults. Explicit entries override discovered
+folders. Already exported environment values win, so selecting a profile never quietly
+replaces a value supplied by the caller.
+
+Discovery never recurses. Persona paths must remain under `agents/` or a root declared in the
+same file, and symlinks may not escape the persona boundary. Legacy profiles written directly
+under `profiles` still load, but new configuration should use `roots` and `entries`.
+
+Select a profile with `--profile release-writer` or switch it with `/profile`. Leaving the
+catalog empty is valid; no profile remains a first-class choice.
+
+### Check the matrix before launch
+
+The fastest configuration debugger is the one that does not start a model:
+
+```bash
+doompi --major-mode copilot --domains work --profile release-writer --explain
+dpi sync
+doompi sync --check
 ```
 
-Pi asks once before it trusts a project and loads `.pi` resources, so a synced session
-prompts on first run regardless of `projectTrust`, which reaches Pi as a launcher flag.
-Answer yes, or run `/trust`.
+`--explain` prints the resolved mode, domains, profile, plugins, skills, agents, MCP boundary,
+and estimated prompt cost. `dpi sync` resolves the repository configuration and synchronizes
+DPI without registering it in normal Pi settings. `doompi sync --check` turns drift into a
+non-zero exit code for CI. If the explanation is surprising, fix the YAML before paying a model
+to be surprised with you.
+
+## Package release order
+
+Publish [`@agimon-ai/doompi-extension-contracts`][pkg-doompi-extension-contracts] first, then
+[`@agimon-ai/doompi-help`][pkg-doompi-help], and only then the
+[`@agimon-ai/doompi`][pkg-doompi] runtime that consumes them. Generated changelogs remain owned
+by the release tooling.
+
+[pkg-doompi]: https://www.npmjs.com/package/@agimon-ai/doompi
+[pkg-doompi-ui]: https://www.npmjs.com/package/@agimon-ai/doompi-ui
+[pkg-doompi-team]: https://www.npmjs.com/package/@agimon-ai/doompi-team
+[pkg-doompi-task]: https://www.npmjs.com/package/@agimon-ai/doompi-task
+[pkg-doompi-runner]: https://www.npmjs.com/package/@agimon-ai/doompi-runner
+[pkg-doompi-autocompact]: https://www.npmjs.com/package/@agimon-ai/doompi-autocompact
+[pkg-doompi-help]: https://www.npmjs.com/package/@agimon-ai/doompi-help
+[pkg-doompi-mcp]: https://www.npmjs.com/package/@agimon-ai/doompi-mcp
+[pkg-doompi-user-feedback]: https://www.npmjs.com/package/@agimon-ai/doompi-user-feedback
+[pkg-log-sink-mcp]: https://www.npmjs.com/package/@agimon-ai/log-sink-mcp
+[pkg-doompi-plan]: https://www.npmjs.com/package/@agimon-ai/doompi-plan
+[pkg-doompi-loop]: https://www.npmjs.com/package/@agimon-ai/doompi-loop
+[pkg-doompi-goal]: https://www.npmjs.com/package/@agimon-ai/doompi-goal
+[pkg-doompi-workflow]: https://www.npmjs.com/package/@agimon-ai/doompi-workflow
+[pkg-doompi-voice]: https://www.npmjs.com/package/@agimon-ai/doompi-voice
+[pkg-doompi-extension-contracts]: https://www.npmjs.com/package/@agimon-ai/doompi-extension-contracts