@agimon-ai/doompi 0.0.1-alpha.27 → 0.0.1-alpha.29

package/README.md

@@ -6,23 +6,32 @@
 > wakes up with database tools, browser controls, and their small novel of schemas. This
 > is our config.
 
-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 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. 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.
+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
@@ -31,9 +40,13 @@ npm install -g @agimon-ai/doompi
 
 The package pins and installs the upstream Pi version used by `dpi`.
 
+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
 
-DoomPi is alpha software. Configuration and package boundaries may still change between alpha releases.
+DoomPi is alpha software. Configuration and package boundaries may still change between alpha
+releases.
 
 - Node.js 22.19.0 or newer
 - macOS or Linux on arm64 or x64 for the bundled Runner backend
@@ -55,8 +68,10 @@ pi                                         # run your existing Pi setup for comp
 `.doom/profiles.yaml` in the current repository. It preserves existing files unless you pass
 `--force` and does not create or change `.pi/settings.json`.
 
-`dpi sync` writes DoomPi's generated state, package alias, and theme resource, but it does
-not register DoomPi in either normal Pi settings file.
+`dpi sync` installs missing configured feature packages, writes DoomPi's generated state,
+package alias, and theme resource, but it does not register DoomPi in either normal Pi
+settings file. It prepares every declared layer so switching modes does not depend on the
+root package's dependency closure.
 
 ### Sync storage and worktrees
 
@@ -78,12 +93,12 @@ doompi sync                                  # register DoomPi in normal Pi sett
 pi                                           # DoomPi now starts through the regular Pi command
 ```
 
-`doompi` remains available as an explicit harness when you want one-run matrix flags:
+`doompi` remains available as an explicit harness when you want per-run matrix flags:
 
 ```bash
-doompi --major-mode dev --domains development
-doompi --domains marketing --profile marketing
-doompi --domains analytics --explain
+doompi --major-mode copilot --no-domains
+doompi --major-mode minimal --no-domains
+doompi --major-mode copilot --no-domains --explain
 ```
 
 ## Philosophy
@@ -98,7 +113,7 @@ A major mode is the base config. It names the extension layers for development,
 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.
 
-Minor modes are battery-included switches inside that base. They start off, stack freely,
+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:
 
 - **Help mode:** expose package-owned guidance only while you need it.
@@ -110,10 +125,10 @@ and keep their model tools and skills out of context until turned on. DoomPi shi
 
 ### Domains
 
-A domain is a named group of Pi plugins. It carries the skills and MCP servers for one
+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.
 
-Plugins are catalogued once and domains refer to their names. A configured root may be a
+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:
 
@@ -194,8 +209,8 @@ 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 coding tools; the release
-note waits for it and gets marketing context plus a brand voice:
+declares the DoomPi session it wants. Here, implementation gets development tools; an
+article waits for it and gets focused blog-writing context:
 
 ```yaml
 on:
@@ -209,22 +224,77 @@ jobs:
         timeout-minutes: 180
         interactiveRun:
           default: |
-            doompi --major-mode dev --domains development --auto-stop \
+            doompi --major-mode examples --domains development --auto-stop \
               --cwd "$PWD" "$JOB_SYSTEM_PROMPT"
 
-  release-note:
+  article:
     runs-on: ubuntu-latest
     needs: implement
     steps:
-      - name: Write the release note
+      - name: Write the article
         timeout-minutes: 30
         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"
 ```
 
+#### Native plugin and workflow examples
+
+This source repository includes a complete, deliberately small example stack:
+
+```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
+```
+
+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:
+
+```bash
+doompi --major-mode examples --domains engineering --explain
+doompi --major-mode examples --domains blog --explain
+```
+
+The same bundles can be installed directly through either native marketplace:
+
+```bash
+# Codex
+codex plugin marketplace add .
+codex plugin add development@doompi-examples
+
+# Claude Code
+claude plugin marketplace add ./ --scope user
+claude plugin install development@doompi-examples --scope user
+```
+
+Substitute `testing` or `blog-writing` to install another bundle. No DoomPi-specific plugin
+schema is involved.
+
+List and dry-run the tracked workflows before spending a model call:
+
+```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"
+```
+
+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.
+
 #### Loop
 
 Workflow definitions are exposed like skills, so the agent can choose one for the job. A
@@ -233,24 +303,32 @@ it. One session becomes the dispatcher instead of the place every job has to fit
 
 ## Features
 
-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.
+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.
 
 ### Foundation and interface
 
 #### Configuration and composition
 
-[`@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.
+[`@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.
 
 #### Supporting packages
 
 [`@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-extension-contracts`][pkg-doompi-extension-contracts]
-contains the shared Cordis service and event contracts used by extension authors.
+materialization, resource staging, and MCP scoping.
+[`@agimon-ai/doompi-extension-contracts`][pkg-doompi-extension-contracts] 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.
@@ -285,12 +363,14 @@ should not expose the task tool.
 #### Runner
 
 [`@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 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 durable logs remain available to the current session 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`.
+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 durable logs remain available to the current session 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. 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
 
@@ -310,26 +390,29 @@ being embedded as special snapshots in the compact summary.
 
 #### 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. The initial contributors expose
-`doompi-help`, `workflow-help`, and `doompi-config-help`. Parent and detached-child sessions both
-include the Help runtime, while its guidance stays withdrawn until Help mode is activated.
+[`@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.
+[`@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.
+[`@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
 
@@ -344,39 +427,39 @@ configured.
 
 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. 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.
+for approval. It does not sandbox Bash, external tools, or the operating system. 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.
 
 #### 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.
+[`@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. 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.
+[`@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 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 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.
+[`@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] 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 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.
+[`@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 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;
@@ -398,7 +481,7 @@ available, and the same model continues to provide bounded command correction.
 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.
+- `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.
 
@@ -411,13 +494,41 @@ from `~/.pi/.doom/`; relative paths in repository config resolve from the reposi
 ### `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 DoomPi distribution always activates Help, Hooks, Goal,
-Voice, Runner, File Edit, Autocompact, Loop, Plan, Workflow, Log, and MCP, so neither
-`doompi init` nor `dpi init` repeats them in user configuration. Add layers only for optional,
-consumer-owned, or explicitly configured packages. Packages may be bare strings, or mappings
-when the package accepts configuration:
+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, then builds the
+synchronized matrix. `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:
@@ -440,17 +551,23 @@ majorMode:
     layers: [team, review]
 ```
 
-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.
+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.
+
+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`.
 
 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
 
-Plugins are catalogued once, then domains refer to their names. A root can be a marketplace,
+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.
 
@@ -575,26 +692,34 @@ its owning package's controls; values supplied by callers are not automatically
 
 ## Troubleshooting and direct use
 
-- Run `doompi sync --check` to detect drift and `doompi sync` to rebuild synchronized state.
+- Run `doompi sync --check` to detect drift or missing configured packages, and `doompi sync`
+  to install them and rebuild synchronized state.
 - If RMUX is unavailable on a supported target, Runner reports the fallback it uses. Linux native
   artifacts require a compatible loader and libc environment.
 - 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 artifacts are selected by Runner and should not be installed directly.
-  The distribution remains the supported way to get the coordinated defaults.
+  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](docs/architecture.md) for standard Pi package composition, canonical fingerprints, transition classification, synchronized bundles, shared-host Cordis lifecycle ownership, and parent/child isolation.
+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
-nx build @agimon-ai/doompi
-nx test @agimon-ai/doompi
-nx typecheck @agimon-ai/doompi
-nx lint @agimon-ai/doompi
+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
 ```
 
 DoomPi is maintained by [Agimon](https://agimon.ai/about).
@@ -603,9 +728,10 @@ DoomPi is maintained by [Agimon](https://agimon.ai/about).
 
 MIT
 
-## Package release order
+## Maintainer release order
 
-Publish [`@agimon-ai/doompi-extension-contracts`][pkg-doompi-extension-contracts] first, then
+Publish [`@agimon-ai/doompi-extension-contracts`][pkg-doompi-extension-contracts] 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.
@@ -618,6 +744,10 @@ loaded extension graph inside the same release boundary as the packages that con
 [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

package/dist/_virtual/_rolldown/runtime.cjs

@@ -0,0 +1 @@
+var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,s)=>(s=n==null?{}:e(i(n)),o(r||!n||!n.__esModule||!a.call(n,`default`)?t(s,`default`,{value:n,enumerable:!0}):s,n));exports.__toESM=s;

package/dist/bin/cli.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+const e=require("../src/commands/cli/help.cjs"),t=process.argv.slice(2),n=t[0],r=n===`init`||n===`sync`||n===`compat`,i=!r&&t.some(e=>e===`--help`||e===`-h`)?(e.printHelp(),0):!r&&t.some(e=>e===`--version`||e===`-v`)?(process.stdout.write(`${e.HARNESS_VERSION}\n`),0):void 0;(i===void 0?Promise.resolve().then(()=>require("../src/commands/cli/cliApp.cjs")).then(({runCli:e})=>e(t)):Promise.resolve(i)).then(e=>{process.exitCode=e},e=>{let t=e instanceof Error?e.message:String(e);process.stderr.write(`[doompi] ${t}\n`),process.exitCode=1});
+//# sourceMappingURL=cli.cjs.map

package/dist/bin/cli.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.cjs","names":["HARNESS_VERSION"],"sources":["../../src/bin/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * CLI Entry Point for doom-pi\n *\n * The executable installed as the `doom-pi` binary, and the file the repository\n * launchers (pi.sh, claude.sh, codex.sh) invoke directly from source.\n */\n\nimport { HARNESS_VERSION, printHelp } from '../commands/cli/help.ts';\n\nconst args = process.argv.slice(2);\nconst command = args[0];\nconst ownsArguments = command === 'init' || command === 'sync' || command === 'compat';\n\n// Keep informational startup independent from telemetry, configuration, Pi,\n// and the extension compiler. Those graphs are useful for a real command but\n// used to account for almost all of `doompi --help` and `doompi --version`.\nconst informationalExit =\n  !ownsArguments && args.some((argument) => argument === '--help' || argument === '-h')\n    ? (() => {\n        printHelp();\n        return 0;\n      })()\n    : !ownsArguments && args.some((argument) => argument === '--version' || argument === '-v')\n      ? (() => {\n          process.stdout.write(`${HARNESS_VERSION}\\n`);\n          return 0;\n        })()\n      : undefined;\n\nconst run =\n  informationalExit === undefined\n    ? import('../commands/cli/cliApp.ts').then(({ runCli }) => runCli(args))\n    : Promise.resolve(informationalExit);\n\nrun.then(\n  (exitCode) => {\n    process.exitCode = exitCode;\n  },\n  (error: unknown) => {\n    const message = error instanceof Error ? error.message : String(error);\n    process.stderr.write(`[doompi] ${message}\\n`);\n    process.exitCode = 1;\n  },\n);\n"],"mappings":";gDAWM,EAAO,QAAQ,KAAK,MAAM,CAAC,EAC3B,EAAU,EAAK,GACf,EAAgB,IAAY,QAAU,IAAY,QAAU,IAAY,SAKxE,EACJ,CAAC,GAAiB,EAAK,KAAM,GAAa,IAAa,UAAY,IAAa,IAAI,GAE9E,EAAA,UAAU,EACH,GAET,CAAC,GAAiB,EAAK,KAAM,GAAa,IAAa,aAAe,IAAa,IAAI,GAEnF,QAAQ,OAAO,MAAM,GAAGA,EAAAA,gBAAgB,GAAG,EACpC,GAET,IAAA,IAGN,IAAsB,IAAA,GAAA,QAAA,QAAA,CAAA,CAAA,SAAA,QAClB,gCAAA,CAAA,CAAA,CAAoC,MAAM,CAAE,YAAa,EAAO,CAAI,CAAC,EACrE,QAAQ,QAAQ,CAAiB,EAAA,CAEnC,KACD,GAAa,CACZ,QAAQ,SAAW,CACrB,EACC,GAAmB,CAClB,IAAM,EAAU,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,EACrE,QAAQ,OAAO,MAAM,YAAY,EAAQ,GAAG,EAC5C,QAAQ,SAAW,CACrB,CACF"}

package/dist/bin/cli.d.cts

@@ -0,0 +1 @@
+export {}

package/dist/bin/cli.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/bin/cli.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import{HARNESS_VERSION as e,printHelp as t}from"../src/commands/cli/help.mjs";const n=process.argv.slice(2),r=n[0],i=r===`init`||r===`sync`||r===`compat`,a=!i&&n.some(e=>e===`--help`||e===`-h`)?(t(),0):!i&&n.some(e=>e===`--version`||e===`-v`)?(process.stdout.write(`${e}\n`),0):void 0;(a===void 0?import(`../src/commands/cli/cliApp.mjs`).then(({runCli:e})=>e(n)):Promise.resolve(a)).then(e=>{process.exitCode=e},e=>{let t=e instanceof Error?e.message:String(e);process.stderr.write(`[doompi] ${t}\n`),process.exitCode=1});export{};
+//# sourceMappingURL=cli.mjs.map

package/dist/bin/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../../src/bin/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * CLI Entry Point for doom-pi\n *\n * The executable installed as the `doom-pi` binary, and the file the repository\n * launchers (pi.sh, claude.sh, codex.sh) invoke directly from source.\n */\n\nimport { HARNESS_VERSION, printHelp } from '../commands/cli/help.ts';\n\nconst args = process.argv.slice(2);\nconst command = args[0];\nconst ownsArguments = command === 'init' || command === 'sync' || command === 'compat';\n\n// Keep informational startup independent from telemetry, configuration, Pi,\n// and the extension compiler. Those graphs are useful for a real command but\n// used to account for almost all of `doompi --help` and `doompi --version`.\nconst informationalExit =\n  !ownsArguments && args.some((argument) => argument === '--help' || argument === '-h')\n    ? (() => {\n        printHelp();\n        return 0;\n      })()\n    : !ownsArguments && args.some((argument) => argument === '--version' || argument === '-v')\n      ? (() => {\n          process.stdout.write(`${HARNESS_VERSION}\\n`);\n          return 0;\n        })()\n      : undefined;\n\nconst run =\n  informationalExit === undefined\n    ? import('../commands/cli/cliApp.ts').then(({ runCli }) => runCli(args))\n    : Promise.resolve(informationalExit);\n\nrun.then(\n  (exitCode) => {\n    process.exitCode = exitCode;\n  },\n  (error: unknown) => {\n    const message = error instanceof Error ? error.message : String(error);\n    process.stderr.write(`[doompi] ${message}\\n`);\n    process.exitCode = 1;\n  },\n);\n"],"mappings":";8EAWA,MAAM,EAAO,QAAQ,KAAK,MAAM,CAAC,EAC3B,EAAU,EAAK,GACf,EAAgB,IAAY,QAAU,IAAY,QAAU,IAAY,SAKxE,EACJ,CAAC,GAAiB,EAAK,KAAM,GAAa,IAAa,UAAY,IAAa,IAAI,GAE9E,EAAU,EACH,GAET,CAAC,GAAiB,EAAK,KAAM,GAAa,IAAa,aAAe,IAAa,IAAI,GAEnF,QAAQ,OAAO,MAAM,GAAG,EAAgB,GAAG,EACpC,GAET,IAAA,IAGN,IAAsB,IAAA,GAClB,OAAO,iCAA4B,CAAC,MAAM,CAAE,YAAa,EAAO,CAAI,CAAC,EACrE,QAAQ,QAAQ,CAAiB,EAAA,CAEnC,KACD,GAAa,CACZ,QAAQ,SAAW,CACrB,EACC,GAAmB,CAClB,IAAM,EAAU,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,EACrE,QAAQ,OAAO,MAAM,YAAY,EAAQ,GAAG,EAC5C,QAAQ,SAAW,CACrB,CACF"}

package/dist/bin/doomRunner.cjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../src/adapters/repository/repository.cjs"),t=require("../src/adapters/modules/moduleResolution.cjs");let n=require("node:url");const r=`@agimon-ai/doompi-runner/bin/cli`;async function i(i=process.argv.slice(2)){let a;try{a=e.findRepositoryRoot(process.cwd())}catch(e){throw Error(`doom-runner must be invoked inside a configured repository.`,{cause:e})}let o=t.consumerPackageEntry(r,a);if(!o)throw Error(`Doom Runner is not installed for this repository. Add @agimon-ai/doompi-runner to .doom/modes.yaml and run doompi sync.`);let s=await import((0,n.pathToFileURL)(o).href);if(typeof s.main!=`function`)throw Error(`${r} does not export a callable main function.`);return s.main(i)}process.argv[1]&&require("url").pathToFileURL(__filename).href===(0,n.pathToFileURL)(process.argv[1]).href&&i().then(e=>{process.exitCode=e},e=>{let t=e instanceof Error?e.message:String(e);process.stderr.write(`[doom-runner] ${t}\n`),process.exitCode=1}),exports.main=i;
+//# sourceMappingURL=doomRunner.cjs.map

package/dist/bin/doomRunner.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"doomRunner.cjs","names":["findRepositoryRoot","consumerPackageEntry","pathToFileURL"],"sources":["../../src/bin/doomRunner.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * CLI Entry Point for doom-runner\n *\n * The Runner package is selectable, so this compatibility executable resolves\n * it from the active repository instead of retaining it in DoomPi's dependency\n * closure. The Runner package's own entry only self-invokes when it is argv[1],\n * which it is not once this shim imports it by absolute path.\n */\n\nimport { pathToFileURL } from 'node:url';\nimport { consumerPackageEntry } from '../adapters/modules/moduleResolution.ts';\nimport { findRepositoryRoot } from '../adapters/repository/repository.ts';\n\nconst RUNNER_CLI_EXPORT = '@agimon-ai/doompi-runner/bin/cli';\n\ninterface RunnerCliModule {\n  readonly main?: unknown;\n}\n\nexport async function main(argv: readonly string[] = process.argv.slice(2)): Promise<number> {\n  let repoRoot: string;\n  try {\n    repoRoot = findRepositoryRoot(process.cwd());\n  } catch (error) {\n    throw new Error('doom-runner must be invoked inside a configured repository.', { cause: error });\n  }\n  const entry = consumerPackageEntry(RUNNER_CLI_EXPORT, repoRoot);\n  if (!entry) {\n    throw new Error(\n      'Doom Runner is not installed for this repository. Add @agimon-ai/doompi-runner to .doom/modes.yaml and run doompi sync.',\n    );\n  }\n  const loaded = (await import(pathToFileURL(entry).href)) as RunnerCliModule;\n  if (typeof loaded.main !== 'function') {\n    throw new Error(`${RUNNER_CLI_EXPORT} does not export a callable main function.`);\n  }\n  return (loaded.main as (args: readonly string[]) => Promise<number>)(argv);\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {\n  main().then(\n    (exitCode) => {\n      process.exitCode = exitCode;\n    },\n    (error: unknown) => {\n      const message = error instanceof Error ? error.message : String(error);\n      process.stderr.write(`[doom-runner] ${message}\\n`);\n      process.exitCode = 1;\n    },\n  );\n}\n"],"mappings":";oNAeA,MAAM,EAAoB,mCAM1B,eAAsB,EAAK,EAA0B,QAAQ,KAAK,MAAM,CAAC,EAAoB,CAC3F,IAAI,EACJ,GAAI,CACF,EAAWA,EAAAA,mBAAmB,QAAQ,IAAI,CAAC,CAC7C,OAAS,EAAO,CACd,MAAU,MAAM,8DAA+D,CAAE,MAAO,CAAM,CAAC,CACjG,CACA,IAAM,EAAQC,EAAAA,qBAAqB,EAAmB,CAAQ,EAC9D,GAAI,CAAC,EACH,MAAU,MACR,yHACF,EAEF,IAAM,EAAU,MAAM,QAAA,EAAOC,EAAAA,cAAAA,CAAc,CAAK,CAAC,CAAC,MAClD,GAAI,OAAO,EAAO,MAAS,WACzB,MAAU,MAAM,GAAG,EAAkB,2CAA2C,EAElF,OAAQ,EAAO,KAAsD,CAAI,CAC3E,CAEI,QAAQ,KAAK,IAAA,QAAA,KAAA,CAAA,CAAA,cAAA,UAAA,CAAA,CAAA,QAAA,EAA0BA,EAAAA,cAAAA,CAAc,QAAQ,KAAK,EAAE,CAAC,CAAC,MACxE,EAAK,CAAC,CAAC,KACJ,GAAa,CACZ,QAAQ,SAAW,CACrB,EACC,GAAmB,CAClB,IAAM,EAAU,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,EACrE,QAAQ,OAAO,MAAM,iBAAiB,EAAQ,GAAG,EACjD,QAAQ,SAAW,CACrB,CACF"}

package/dist/bin/doomRunner.d.cts

@@ -0,0 +1,13 @@
+//#region src/bin/doomRunner.d.ts
+/**
+ * CLI Entry Point for doom-runner
+ *
+ * The Runner package is selectable, so this compatibility executable resolves
+ * it from the active repository instead of retaining it in DoomPi's dependency
+ * closure. The Runner package's own entry only self-invokes when it is argv[1],
+ * which it is not once this shim imports it by absolute path.
+ */
+declare function main(argv?: readonly string[]): Promise<number>;
+//#endregion
+export { main };
+//# sourceMappingURL=doomRunner.d.cts.map

package/dist/bin/doomRunner.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doomRunner.d.cts","names":[],"sources":["../../src/bin/doomRunner.ts"],"mappings":";;;;;;;;;iBAqBsB,KAAK,2BAAkD"}

package/dist/bin/doomRunner.d.mts

@@ -0,0 +1,13 @@
+//#region src/bin/doomRunner.d.ts
+/**
+ * CLI Entry Point for doom-runner
+ *
+ * The Runner package is selectable, so this compatibility executable resolves
+ * it from the active repository instead of retaining it in DoomPi's dependency
+ * closure. The Runner package's own entry only self-invokes when it is argv[1],
+ * which it is not once this shim imports it by absolute path.
+ */
+declare function main(argv?: readonly string[]): Promise<number>;
+//#endregion
+export { main };
+//# sourceMappingURL=doomRunner.d.mts.map

package/dist/bin/doomRunner.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doomRunner.d.mts","names":[],"sources":["../../src/bin/doomRunner.ts"],"mappings":";;;;;;;;;iBAqBsB,KAAK,2BAAkD"}

package/dist/bin/doomRunner.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import{findRepositoryRoot as e}from"../src/adapters/repository/repository.mjs";import{consumerPackageEntry as t}from"../src/adapters/modules/moduleResolution.mjs";import{pathToFileURL as n}from"node:url";const r=`@agimon-ai/doompi-runner/bin/cli`;async function i(i=process.argv.slice(2)){let a;try{a=e(process.cwd())}catch(e){throw Error(`doom-runner must be invoked inside a configured repository.`,{cause:e})}let o=t(r,a);if(!o)throw Error(`Doom Runner is not installed for this repository. Add @agimon-ai/doompi-runner to .doom/modes.yaml and run doompi sync.`);let s=await import(n(o).href);if(typeof s.main!=`function`)throw Error(`${r} does not export a callable main function.`);return s.main(i)}process.argv[1]&&import.meta.url===n(process.argv[1]).href&&i().then(e=>{process.exitCode=e},e=>{let t=e instanceof Error?e.message:String(e);process.stderr.write(`[doom-runner] ${t}\n`),process.exitCode=1});export{i as main};
+//# sourceMappingURL=doomRunner.mjs.map

package/dist/bin/doomRunner.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"doomRunner.mjs","names":[],"sources":["../../src/bin/doomRunner.ts"],"sourcesContent":["#!/usr/bin/env node\n\n/**\n * CLI Entry Point for doom-runner\n *\n * The Runner package is selectable, so this compatibility executable resolves\n * it from the active repository instead of retaining it in DoomPi's dependency\n * closure. The Runner package's own entry only self-invokes when it is argv[1],\n * which it is not once this shim imports it by absolute path.\n */\n\nimport { pathToFileURL } from 'node:url';\nimport { consumerPackageEntry } from '../adapters/modules/moduleResolution.ts';\nimport { findRepositoryRoot } from '../adapters/repository/repository.ts';\n\nconst RUNNER_CLI_EXPORT = '@agimon-ai/doompi-runner/bin/cli';\n\ninterface RunnerCliModule {\n  readonly main?: unknown;\n}\n\nexport async function main(argv: readonly string[] = process.argv.slice(2)): Promise<number> {\n  let repoRoot: string;\n  try {\n    repoRoot = findRepositoryRoot(process.cwd());\n  } catch (error) {\n    throw new Error('doom-runner must be invoked inside a configured repository.', { cause: error });\n  }\n  const entry = consumerPackageEntry(RUNNER_CLI_EXPORT, repoRoot);\n  if (!entry) {\n    throw new Error(\n      'Doom Runner is not installed for this repository. Add @agimon-ai/doompi-runner to .doom/modes.yaml and run doompi sync.',\n    );\n  }\n  const loaded = (await import(pathToFileURL(entry).href)) as RunnerCliModule;\n  if (typeof loaded.main !== 'function') {\n    throw new Error(`${RUNNER_CLI_EXPORT} does not export a callable main function.`);\n  }\n  return (loaded.main as (args: readonly string[]) => Promise<number>)(argv);\n}\n\nif (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {\n  main().then(\n    (exitCode) => {\n      process.exitCode = exitCode;\n    },\n    (error: unknown) => {\n      const message = error instanceof Error ? error.message : String(error);\n      process.stderr.write(`[doom-runner] ${message}\\n`);\n      process.exitCode = 1;\n    },\n  );\n}\n"],"mappings":";4MAeA,MAAM,EAAoB,mCAM1B,eAAsB,EAAK,EAA0B,QAAQ,KAAK,MAAM,CAAC,EAAoB,CAC3F,IAAI,EACJ,GAAI,CACF,EAAW,EAAmB,QAAQ,IAAI,CAAC,CAC7C,OAAS,EAAO,CACd,MAAU,MAAM,8DAA+D,CAAE,MAAO,CAAM,CAAC,CACjG,CACA,IAAM,EAAQ,EAAqB,EAAmB,CAAQ,EAC9D,GAAI,CAAC,EACH,MAAU,MACR,yHACF,EAEF,IAAM,EAAU,MAAM,OAAO,EAAc,CAAK,CAAC,CAAC,MAClD,GAAI,OAAO,EAAO,MAAS,WACzB,MAAU,MAAM,GAAG,EAAkB,2CAA2C,EAElF,OAAQ,EAAO,KAAsD,CAAI,CAC3E,CAEI,QAAQ,KAAK,IAAM,YAAY,MAAQ,EAAc,QAAQ,KAAK,EAAE,CAAC,CAAC,MACxE,EAAK,CAAC,CAAC,KACJ,GAAa,CACZ,QAAQ,SAAW,CACrB,EACC,GAAmB,CAClB,IAAM,EAAU,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,EACrE,QAAQ,OAAO,MAAM,iBAAiB,EAAQ,GAAG,EACjD,QAAQ,SAAW,CACrB,CACF"}