@agimon-ai/doompi 0.0.1-alpha.1 → 0.0.1-alpha.100

package/README.md

@@ -1,546 +1,791 @@
-# Doompi
+# DoomPi
 
 **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 an opinionated, composable distribution of
+[Pi](https://github.com/earendil-works/pi). It is closer in spirit to Spacemacs, Doom Emacs, or a
+curated Neovim setup than to a single plugin. It is 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. They do less to scope which configured plugins and MCP
+servers a particular session can load. Claude Code's `enableAllProjectMcpServers` and static
+denylist are repository-wide. DoomPi draws that loading 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.
+
+## Contents
+
+[Install](#install) · [Try DoomPi](#try-doompi-without-replacing-your-pi-setup) ·
+[Philosophy](#philosophy) · [What this buys you](#what-this-buys-you) · [Features](#features) ·
+[Configuration](#configuration) · [Trust and data boundaries](#trust-and-data-boundaries) ·
+[CLI reference](#cli-reference) · [Troubleshooting](#troubleshooting-and-direct-use) ·
+[Architecture](#architecture) · [Development](#development)
 
 ## 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`. It also owns the
+[`doompi-server` executable and server API](docs/server/index.md) used by the web and desktop clients.
 
-```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
-```
+The root package contains the fixed host foundation only. Feature packages are selected by
+`.doom/modes.yaml` and installed into the consumer repository when they are first needed.
+
+## Status and requirements
 
-`.doom/` is committed to git, so a checkout carries its own agent configuration. Edit a
-YAML file and the next launch picks it up.
+DoomPi is alpha software. Configuration and package boundaries may still change between alpha
+releases.
+
+- Node.js 22.19.0 or newer
+- Release targets: macOS arm64, Linux x64, and Linux arm64
+- Pi 0.87.1 and Pi TUI 0.87.1 for packages that declare them as peer requirements
+
+## Try DoomPi without replacing your Pi setup
+
+`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
+`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`.
 
-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 sync` installs missing configured feature packages and publishes a generated runtime, web bundle,
+and API route set for the current repository and worktree. It does not change either normal Pi settings
+file. It prepares every declared layer so switching modes does not depend on the root package's
+dependency closure.
 
-| 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` |
+### Sync storage and worktrees
 
-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.
+DoomPi stores generated sync data under `~/.pi/.doom/sync`, outside the repository. Repository and
+worktree identities select separate namespaces. Outside a repository, the canonical `~/.pi/.doom`
+configuration gets its own global composition and registration. Each successful sync writes a new immutable
+generation, then atomically publishes that generation's registration as the final commit step. A failed sync
+removes its unpublished generation and leaves the previous registration active. One sync target never rewrites
+another target's registration or generation.
 
-## What is actually different
+`dpi` preserves Pi's normal global and repository settings, then applies DoomPi's extension and theme
+settings in memory. It never writes those values to `.pi/settings.json`.
 
-**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).
+Export the published HTTP and socket contracts with `doompi api-export --out ./api-schema --strict`. See [compiled API export](docs/server/api-export.md) for artifact formats, CI checks, and package declarations.
 
-**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.
+Run `doompi sync --check` to detect missing, invalid, or stale registered state. Unregistered legacy state
+is not loaded. Inside a repository, `doompi sync` publishes that repository and worktree. Outside every
+repository, it publishes the global composition from `~/.pi/.doom`.
 
-**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.
+When you are comfortable with DoomPi and no longer need the side-by-side experiment, initialize the
+normal Pi integration and synchronize the scopes you use:
 
-## Philosophy
+```bash
+doompi init                                  # seed ~/.pi/.doom and register the managed Pi integration
+doompi sync                                  # publish the current repository, or the global composition
+pi                                           # use the nearest repository, otherwise the global composition
+```
+
+`doompi` remains available as an explicit harness when you want per-run matrix flags:
 
-**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 --major-mode copilot --no-domains
+doompi --major-mode minimal --no-domains
+doompi --major-mode copilot --no-domains --explain
+```
 
-**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.
+## Philosophy
 
-**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.
+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.
 
-**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.
+### Major and minor modes
 
-**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.
+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. Synchronized
+sessions can reload compatible changes; launcher-owned composition changes require a relaunch.
 
-## Two ways to run
+Minor modes are batteries-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:
 
-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.
+- **Help mode:** expose package-owned guidance only while you need it.
+- **Plan mode:** remove Pi's file-editing tools 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` is the other way in, and the Doom Emacs one. Resolve once, write the
-result where Pi looks, then run `pi` yourself.
+### Domains
 
-```bash
-doompi init          # seed ~/.pi/.doom, once per machine
-doompi sync          # resolve the selection into .pi/
-pi                   # the agent
+A domain is a named group of agent plugins. It carries the skills and MCP servers for one
+kind of work, and `/domains` switches it while the session is running.
 
-doompi sync --check  # exit non-zero when the synced config is out of date
-```
+Plugins are cataloged 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:
 
-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.
-
-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' },
-    },
-  ],
-});
+```yaml
+plugins:
+  roots: [plugins]
+  entries:
+    remote-review:
+      source: url
+      url: '<REVIEW_PLUGIN_GIT_URL>'
+      ref: v1.2.0
+
+domains:
+  development:
+    description: Implementation and code-review tools.
+    plugins: [pi-development, remote-review]
 ```
 
-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 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.
-
-**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.
-
-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.
-
-### Minor modes
-
-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.
-
-| 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` |
-
-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`.
-
-## For autonomous agents
-
-### Minimal context
-
-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.
-
-`--explain` prints what any combination costs before you launch it, and ends with the bill:
+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.
 
+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.
+
+### Profile
+
+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.
+
+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.
+
+```yaml
+profiles:
+  roots: [agents/acme]
+  entries:
+    editor:
+      persona: agents/special/editor
+      env:
+        EDITOR_MODE: strict
 ```
-$ 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.
-```
 
-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.
+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`.
+
+## What this buys you
+
+Every tool schema and skill name competes for the same context. Loading less has two
+immediate effects:
+
+1. You spend fewer tokens before the work begins.
+2. The model has fewer plausible-but-wrong tools and skills to choose from.
 
-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.
+The savings get larger when each workflow job starts with its own config instead of
+inheriting the last job's toolbox.
 
-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.
+### Copilot
 
-A domain can also take a named subset of one plugin's skills, by name or glob.
+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.
 
-### Workflows
+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.
 
-Long autonomous work runs as workflows, in the shape a GitHub Actions user already knows:
-`on:`, `jobs:`, `needs:`, `steps:`, timeouts, and declared artifacts.
+### Autopilot
 
-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:
+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.
+
+#### Workflows
+
+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 development tools; an
+article waits for it and gets focused blog-writing context:
 
 ```yaml
+on:
+  workflow_dispatch:
+
 jobs:
   implement:
-    needs: intake
     steps:
-      - name: Implement
+      - name: Build the feature
         timeout-minutes: 180
-        artifacts: [implementation/report.md]
         interactiveRun:
           default: |
-            doompi --major-mode dev --domains development --auto-stop \
+            doompi --major-mode examples --domains development --auto-stop \
               --cwd "$PWD" "$JOB_SYSTEM_PROMPT"
 
-  announce:
+  article:
     needs: implement
     steps:
-      - name: Draft the release note
+      - name: Write the article
         timeout-minutes: 30
-        artifacts: [marketing/release-note.md]
         interactiveRun:
           default: |
-            doompi --major-mode marketing --domains marketing \
-              --profile brand-voice --auto-stop \
+            doompi --major-mode examples --domains blog --auto-stop \
               --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.
+#### Native plugin and workflow examples
 
-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.
+This source repository includes a complete, deliberately small example stack:
 
-### Long runs
+```text
+plugins/
+  development/   implementation skill and developer agent
+  testing/       testing and review skills, tester and reviewer agents
+  blog-writing/  research, outline, drafting, and editorial skills and agents
+automations/workflows/
+  dev-feature.workflow.yml
+  dev-fix.workflow.yml
+  blog-writing.workflow.yml
+```
 
-Tasks, teams, runners, and compaction share one working state, so a long autonomous run
-does not lose its place.
+Each plugin has both `.codex-plugin/plugin.json` and `.claude-plugin/plugin.json`, while its
+`skills/` and `agents/` content is shared. `.doom/domains.yaml` exposes the `development`,
+`testing`, and `blog` domains plus the `engineering` alias. `.doom/modes.yaml` mirrors the
+standalone package set with workspace-local paths, keeps its canonical modes, and adds a layer-free
+`examples` base mode for the tracked workflows. Inspect the exact session before launch:
 
-- **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.
+```bash
+doompi --major-mode examples --domains engineering --explain
+doompi --major-mode examples --domains blog --explain
+```
 
-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.
+The same bundles can be installed directly through either native marketplace:
 
-## Core is not a layer
+```bash
+# Codex
+codex plugin marketplace add .
+codex plugin add development@doompi-examples
 
-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.
+# Claude Code
+claude plugin marketplace add ./ --scope user
+claude plugin install development@doompi-examples --scope user
+```
 
-## Who owns what
+Substitute `testing` or `blog-writing` to install another bundle. No DoomPi-specific plugin
+schema is involved.
 
-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.
+List and dry-run the tracked workflows before spending a model call:
 
-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.
+```bash
+pnpm exec workflow-mcp list-workflows automations/workflows
+pnpm exec workflow-mcp run-workflow automations/workflows/dev-feature.workflow.yml \
+  --dry-run --skip-launch --prompt "Add a health check"
+pnpm exec workflow-mcp run-workflow automations/workflows/blog-writing.workflow.yml \
+  --dry-run --skip-launch --prompt "Write a practical guide to scoped agent tooling"
+```
 
-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.
+Real runs delegate to tmux by default and accept `WORKFLOW_LAUNCHER=cmux`. Development runs do
+not create branches, commits, or pushes. Blog runs leave review-ready Markdown, sources, and a
+publication checklist in the workflow run directory without writing into a site or calling a CMS.
+These examples live in the source repository and are not part of the published npm tarball.
 
-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.
+#### Loop
 
-## Lazy config
+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.
+
+## Features
 
-Under the launcher, everything is resolved per run and nothing is written back into the
-repository. Editing a YAML file is the entire change.
+DoomPi is a distribution, not one giant extension. Each package owns one job; shared TUI,
+Cordis services, and session contracts make them behave like one. Use the generated
+`default.packages` list together, remove packages you do not want, or replace its entries one
+at a time. Selectable packages are not runtime dependencies of the root package or of one another.
 
-`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`.
+### Foundation and interface
+
+#### Configuration and composition
 
-`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.
+[`@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.
 
-Either way the hook registry compiles to the files other frontends read before any harness
-code runs, and `doompi sync` regenerates them.
+#### Supporting packages
 
-## Other frontends
+[`@agimon-ai/doompi-config`][pkg-doompi-config] resolves the four YAML files and exposes the
+configuration API. [`@agimon-ai/doompi-domain`][pkg-doompi-domain] owns domain selection, plugin
+materialization, resource staging, and MCP scoping.
+[`@agimon-ai/doompi-core`][pkg-doompi-core] contains the shared
+Cordis service and event contracts used by extension authors.
+[`@agimon-ai/doompi-hashline`][pkg-doompi-hashline] provides the shared snapshot tags and line-anchor
+protocol. [`@agimon-ai/doompi-read`][pkg-doompi-read] and [`@agimon-ai/doompi-grep`][pkg-doompi-grep]
+produce editable anchors for writable files while preserving Pi's native output for non-writable files.
+[`@agimon-ai/doompi-edit`][pkg-doompi-edit] replaces Pi's search-and-replace `edit` tool with
+stale-safe ranges anchored to the file content the model read or searched.
+[`@agimon-ai/doompi-file-edit`][pkg-doompi-file-edit] opens files in the configured editor and
+keeps the edit timeline. [`@agimon-ai/doompi-log`][pkg-doompi-log] collects session events, while
+[`@agimon-ai/doompi-telemetry`][pkg-doompi-telemetry] is the library-level telemetry adapter.
 
-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:
+Runner selects matching RMUX and RTK native artifacts automatically. Do not install them directly.
+The packages cover macOS and Linux on arm64 and x64 for both [RMUX][pkg-rmux-darwin-arm64] and
+[RTK][pkg-rtk-darwin-arm64].
 
-|                     | 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                  |
+#### Leader key
 
-Compatibility frontends use the selected major mode for shared hook state. Layer packages
-and Pi extensions are loaded only by Pi.
+[`@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.
 
-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.
+### Coordinated work
 
-Where a concept has no equivalent, it is left out rather than approximated.
+#### Agent team
 
-## Files
+[`@agimon-ai/doompi-team`][pkg-doompi-team] runs named subagents asynchronously. It owns agents,
+runs, membership, intercom, and model policy; Task owns the persistent task graph used for
+delegation. Agents can work in parallel and message one another. `SPC a l` lists available agents;
+`SPC a r` opens current-session runs and their controls.
 
-All Doompi configuration lives in `.doom/`, committed to git.
+#### Tasks
 
-```
-.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
-```
+[`@agimon-ai/doompi-task`][pkg-doompi-task] keeps a task graph on disk, not a disposable checklist in the
+transcript. Dependencies persist independently of transcript 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.
 
-`doompi sync` writes into `.pi/`:
+#### Runner
 
-```
-.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
+[`@agimon-ai/doompi-runner`][pkg-doompi-runner] replaces Pi's blocking `bash` tool with
+supervised command execution. `doompi init` includes Runner in `default.packages`, so every
+generated mode gets it. Short commands still return inline; commands that pass the configurable
+threshold of 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 and complete raw logs remain available to the current session through
+Runner Space at `SPC r l` or the `doom-runner` CLI. Runner tries bundled RMUX, then `rmux` on PATH,
+then `tmux` on PATH. If no pane backend accepts the run, non-interactive commands use a supervised
+subprocess; interactive commands require RMUX or tmux. Conservatively recognized single commands
+use the matching RTK stdin filter after completion. Compound commands, pipelines, incompatible
+formats, and unsupported commands keep bounded raw output. Remove Runner from `default.packages` to keep Pi's
+`bash`, or add it to a named layer when only selected modes should replace `bash`.
+
+#### Auto-compact
+
+Ordinary compaction waits for one summary to save an overgrown session.
+[`@agimon-ai/doompi-autocompact`][pkg-doompi-autocompact] leaves checkpoints instead:
+
+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.
+
+The work runs off-thread and can make up to three additional summarization calls. The standard
+adapter preserves staged conversation checkpoints; Task and Team keep their own state rather than
+being embedded as special snapshots in the compact summary.
+
+### Context and access
+
+#### Help mode
+
+[`@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. Help names state their intent: authoring
+guides use `doompi-author-*`, while operational guides use `doompi-use-*`. Core authoring guidance
+covers extensions, runtime config, major modes, domains, profiles, hooks, workflows, and skills.
+Parent and detached-child sessions both include the Help runtime, while root and axis authoring
+guides remain parent-owned and all guidance stays withdrawn until Help mode is activated.
+
+#### MCP
+
+[`@agimon-ai/doompi-mcp`][pkg-doompi-mcp] is the gate between a session and its servers. It reads
+repository and legacy plugin `.mcp.json` plus Agent Plugins v1 `mcp.json`, then exposes only the
+servers and proxy upstreams allowed by the selected domains. A domain switch persists an immutable
+projection; after Pi replaces the factories, Config publishes it through the session Cordis
+registry and MCP starts a fresh in-memory `mcp-proxy` container. No Hono server or localhost proxy
+sits in this path.
+
+#### Ask user question
+
+[`@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.
+
+#### Logging and telemetry
+
+DoomPi logging records operational metadata such as counters, spans, session IDs, tool names, and
+errors. Callers remain responsible for values they attach to telemetry. `SPC h l` opens current-session
+metrics, and [`@agimon-ai/log-sink-mcp`][pkg-log-sink-mcp] provides historical lookup when a sink is
+configured.
+
+### Modes and automation
+
+#### Plan mode
+
+A promise to "only plan" is not a permission boundary. [`@agimon-ai/doompi-plan`][pkg-doompi-plan]
+removes Pi's `edit` and `write` tools while the agent explores, persists the plan, and hands it back
+for approval. It does not sandbox Bash, external tools, or the operating system. `SPC p e` enters
+normal planning and leaves it again once on; `SPC p d` is debug planning and `SPC p f` the Fable
+flow.
+Turn it on when the approach should be settled before the files move.
+
+#### Loop mode
+
+[`@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.
+
+#### Goal mode
+
+[`@agimon-ai/doompi-goal`][pkg-doompi-goal] pins one objective to the session until it completes or
+you end it. `SPC g e` starts a goal and ends it once one is held; `SPC g g` shows status and
+`SPC g l` lists repository history. Finished goals stop contributing active instructions and tools but remain in history when
+you want to restart one.
+
+#### 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 l` to
+browse the repository's workflows and launch one with `r`, `SPC w r` to inspect this session's runs,
+`SPC w c` 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] captures PCM audio through the local platform helper
+and can transcribe it locally. Transcript text, session state, and model requests may still cross
+process or provider boundaries according to the configured engines. `SPC v m` is one-shot manual
+dictation and never enables Voice tools. `SPC v e` enters autonomous capture and exits it again; 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. Final narration contains the complete answer, including every user-relevant
+conclusion, question, warning, result, and next action in the written response, rather than
+leaving essential information only in text. Short turns need one complete spoken answer;
+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 default packages, 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. The top-level `default.packages` list is the ordered package
+baseline for every major mode. `doompi init` and `dpi init` write the distribution's current
+feature packages there so the baseline is visible and replaceable. If `default` is absent,
+DoomPi adds no default feature packages. Use `default.packages: []` for an explicit empty
+baseline. The fixed host core remains active independently of this setting, and named layers
+keep their existing behavior.
+
+Launch installs missing required packages from the defaults and selected layers. `doompi sync`
+installs missing required packages from the defaults and every declared layer, moves every
+package in Pi's managed `.pi/npm` store to its newest published version, then builds the
+synchronized matrix. A package whose published version cannot be read, because the machine is
+offline or the registry refuses the request, keeps its installed version and is named in the
+sync output. `doompi sync --check` reports missing packages without modifying the repository. Optional packages and local paths are not installed automatically. Removing an
+entry stops activating it but leaves Pi's package cache available for later reuse.
+
+Packages in `default` and named layers may be bare strings, or mappings when the package accepts
+configuration:
+
+```yaml
+default:
+  packages:
+    - '@agimon-ai/doompi-help'
+    - '@agimon-ai/doompi-hook'
+    - '@agimon-ai/doompi-goal'
+    - '@agimon-ai/doompi-voice'
+    - '@agimon-ai/doompi-runner'
+    - '@agimon-ai/doompi-read'
+    - '@agimon-ai/doompi-grep'
+    - '@agimon-ai/doompi-edit'
+    - '@agimon-ai/doompi-file-edit'
+    - '@agimon-ai/doompi-autocompact'
+    - '@agimon-ai/doompi-loop'
+    - '@agimon-ai/doompi-plan'
+    - '@agimon-ai/doompi-workflow'
+    - '@agimon-ai/doompi-log'
+    - '@agimon-ai/doompi-mcp'
+
+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]
 ```
 
-### One owner for the state
+Order matters: DoomPi assembles `default.packages` first, then the selected 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. If both
+sources declare `default`, the repository block replaces the personal block as one whole package
+list.
 
-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.
+Configurations created before the hashline tools were split may contain only `doompi-edit`.
+Replace that entry with the ordered `doompi-read`, `doompi-grep`, and `doompi-edit` trio. Init
+preserves existing configuration unless it is run with `--force`.
 
-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.
+Choose a mode with `--major-mode copilot`, switch it with `/mode`, or change
+`defaultMajorMode` when one mode should be the ordinary starting point.
 
-It also regenerates the two hook files the other frontends read before any harness code
-runs, which live outside `.pi/`:
+### `domains.yaml`: choose content and access
 
-```
-.claude/settings.json       the "hooks" key only; every other key is preserved
-.codex-local/hooks.json     the whole file
+Plugins are cataloged 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.
+
+```yaml
+defaultDomains: [development]
+
+plugins:
+  roots: [plugins]
+  entries:
+    remote-review:
+      source: url
+      url: '<REVIEW_PLUGIN_GIT_URL>'
+      ref: v1.2.0
+    published-research:
+      source: npm
+      package: '@acme/research-plugin'
+      version: 1.4.0
+
+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]
 ```
 
-Edit `hooks.yaml` and re-run `doompi sync` to regenerate both.
+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.
 
-## Selection
+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.
 
-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.
+### `profiles.yaml`: choose a point of view
 
-Defaults when you name nothing: major mode `copilot`, domains `default`. The `marketing`
-major mode is the one exception and defaults to the `marketing` domain. That is the only
-place where one choice influences another.
+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.
 
-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.
+```yaml
+profiles:
+  roots: [personas]
+  entries:
+    release-writer:
+      persona: personas/release-writer
+      env:
+        BRAND: acme
+        TONE: concise
+```
 
-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.
+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.
 
-`DOOMPI_LAYERS`, plural, is a different variable from `DOOMPI_LAYER`. It carries the
-resolved layer components rather than the mode that selected them.
+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`.
 
-A repository can declare what it selects by default, which is what a bare `doompi sync`
-pins. A flag still wins, then an exported variable, then this:
+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.
 
-```yaml
-# .doom/config.yaml
-selection:
-  majorMode: dev
-  domains: [development]
-  profile: house-voice
+### 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
+```
+
+`--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.
+
+## Trust and data boundaries
+
+DoomPi executes the extensions, remote Git/npm plugins, hooks, MCP stdio commands, workflows, and
+shell commands you configure. Treat them as trusted executable code. Runner commands inherit the
+process environment and operating-system privileges; their logs may contain command output and
+secrets. MCP credentials may live in the system keyring or private configuration files.
+
+Voice can keep PCM capture and transcription local when local engines are selected, but transcript
+text and model requests follow the configured providers. Loop, Workflow, Plan, Autocompact, Team,
+and autonomous Voice can make additional model calls. Telemetry is disabled or redirected through
+its owning package's controls; values supplied by callers are not automatically scrubbed.
+
+## CLI reference
+
+| Command or option                            | What it does                                                                      |
+| -------------------------------------------- | --------------------------------------------------------------------------------- |
+| `dpi init`, `dpi sync`, `dpi`                | Creates, synchronizes, and runs the repository-scoped comparison setup            |
+| `doompi init`                                | Seeds personal config and installs the managed Pi dispatcher, settings, and theme |
+| `doompi sync`                                | Publishes the current repository, or the global composition outside repositories  |
+| `doompi sync --check`                        | Exits non-zero when the applicable registered generation is missing or stale      |
+| `doompi compat <codex\|claude\|antigravity>` | Resolves the selected matrix and launches the compatibility adapter               |
+| `doom-runner`                                | Inspects and controls supervised Runner processes and logs                        |
+| `--explain`                                  | Prints the resolved matrix and estimated prompt cost without launching Pi         |
+| `--emit-mcp <dir>`, `--no-mcp`               | Writes the resolved MCP config or disables MCP for one run                        |
+| `--cwd <path>`, `--auto-stop`                | Chooses the working directory or exits after an interactive agent settles         |
+| `--` and remaining arguments                 | Forwards provider or Pi arguments unchanged where the selected command allows it  |
+
+## Troubleshooting and direct use
+
+- Run `doompi sync --check` to detect drift or missing configured packages, and `doompi sync`
+  to install them and rebuild synchronized state.
+- If neither RMUX nor tmux is available, non-interactive Runner calls report the supervised subprocess
+  fallback. Interactive calls require RMUX or tmux. Linux native artifacts require a compatible loader and libc.
+- Leader menus and overlays require Pi's interactive TUI. Commands and tools remain the interface
+  for JSON, RPC, and other headless sessions where the owning package supports them.
+- Install a directly loaded Pi subsystem with `pi install npm:@agimon-ai/<package>`. Library consumers
+  use `npm install`; native RMUX and RTK artifacts are selected by Runner and should not be installed
+  directly.
+  The root `doom-runner` command delegates to Runner from the active repository and asks you to add
+  Runner to `modes.yaml` when it is absent. The distribution remains the supported way to get the
+  coordinated defaults.
+
+## Architecture
+
+See [Architecture](https://github.com/AgiFlow/doompi/blob/main/docs/architecture.md) for standard Pi
+package composition, canonical fingerprints, transition classification, synchronized bundles,
+shared-host Cordis lifecycle ownership, and parent/child isolation.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm examples:check
+pnpm nx build @agimon-ai/doompi
+pnpm nx test @agimon-ai/doompi
+pnpm nx typecheck @agimon-ai/doompi
+pnpm nx lint @agimon-ai/doompi
 ```
 
-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`.
+DoomPi is maintained by [Agimon](https://agimon.ai/about).
+
+## License
+
+MIT
+
+## Maintainer release order
+
+Publish [`@agimon-ai/doompi-core`][pkg-doompi-core] and
+[`@agimon-ai/doompi-hashline`][pkg-doompi-hashline] 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.
+
+The deploy workflow blocks publishing unless the deterministic DoomPi architecture sweep and the
+packed-install system tests both pass. This keeps the shared Cordis host contract and independently
+loaded extension graph inside the same release boundary as the packages that consume them.
+
+[pkg-doompi]: https://www.npmjs.com/package/@agimon-ai/doompi
+[pkg-doompi-ui]: https://www.npmjs.com/package/@agimon-ai/doompi-ui
+[pkg-doompi-config]: https://www.npmjs.com/package/@agimon-ai/doompi-config
+[pkg-doompi-domain]: https://www.npmjs.com/package/@agimon-ai/doompi-domain
+[pkg-doompi-hashline]: https://www.npmjs.com/package/@agimon-ai/doompi-hashline
+[pkg-doompi-read]: https://www.npmjs.com/package/@agimon-ai/doompi-read
+[pkg-doompi-grep]: https://www.npmjs.com/package/@agimon-ai/doompi-grep
+[pkg-doompi-edit]: https://www.npmjs.com/package/@agimon-ai/doompi-edit
+[pkg-doompi-file-edit]: https://www.npmjs.com/package/@agimon-ai/doompi-file-edit
+[pkg-doompi-log]: https://www.npmjs.com/package/@agimon-ai/doompi-log
+[pkg-doompi-telemetry]: https://www.npmjs.com/package/@agimon-ai/doompi-telemetry
+[pkg-rmux-darwin-arm64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rmux-darwin-arm64
+[pkg-rmux-darwin-x64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rmux-darwin-x64
+[pkg-rmux-linux-arm64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rmux-linux-arm64
+[pkg-rmux-linux-x64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rmux-linux-x64
+[pkg-rtk-darwin-arm64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rtk-darwin-arm64
+[pkg-rtk-darwin-x64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rtk-darwin-x64
+[pkg-rtk-linux-arm64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rtk-linux-arm64
+[pkg-rtk-linux-x64]: https://www.npmjs.com/package/@agimon-ai/doompi-runner-rtk-linux-x64
+[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-core]: https://www.npmjs.com/package/@agimon-ai/doompi-core