@agimon-ai/po 0.0.0-alpha.0

package/README.md

@@ -0,0 +1,755 @@
+# Po
+
+**An agent harness that loads only the skills and tools you name.**
+
+> 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.
+
+Po is an opinionated, composable agent harness built on
+[Pi](https://github.com/earendil-works/pi). It is tailored for people whose agent has one MCP
+server too many. It turns extensions, skills, MCP servers, and system prompts into explicit
+session configuration instead of background noise.
+
+![Po panda, an agent harness that loads only the skills and tools you name](https://cdn.jsdelivr.net/npm/@agimon-ai/po@latest/assets/banner.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. Po 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;
+`po --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 Po](#try-po-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/po @agimon-ai/po-web
+```
+
+The package owns the CLI and the [`po-server` executable and server API](docs/server/index.md) used
+by the web and desktop clients. Bare `po` starts the `po-web` console from `@agimon-ai/po-web`, which
+depends on `po`, so `po` finds it at run time and prints install guidance when it is missing.
+
+The root package contains the fixed host foundation only. Feature packages are selected by
+`.po/modes.yaml` and installed into the consumer repository when they are first needed.
+
+## Status and requirements
+
+Po is alpha software. Configuration and package boundaries may still change between alpha
+releases.
+
+- Node.js 24 or newer
+- Release targets: macOS arm64, Linux x64, and Linux arm64
+- Pi 1.0.0 for packages that declare it as a peer requirement
+
+## Pi 1.0 sessions and Codex Fast
+
+Headless sessions use fresh `durable-v1` storage. Earlier headless sessions cannot be resumed or
+converted. Their files remain untouched, without migration or backups.
+
+Use `/fast on|off` in CLI or server sessions, or the **Fast** switch in the web model picker.
+Fast requests Codex priority service, which may increase cost, independently of thinking effort.
+Fresh top-level sessions default to off. New subagents and child sessions inherit the parent's
+current setting, then persist their own setting across resumes. Other providers never receive
+Po's priority flag.
+
+## Quick start
+
+```bash
+po init                                  # seed ~/.po
+po sync                                  # install configured packages and ensure the global builds
+po                                       # start po-web and po-server, then open the printed URL
+```
+
+`po init` creates `config.yaml`, `modes.yaml`, `domains.yaml`, and `profiles.yaml` under
+`~/.po`. It preserves existing files unless you pass `--force`, and it removes the Po entries
+and theme that earlier versions wrote to Pi user settings.
+
+`po sync` installs the packages every declared layer names, so switching modes does not depend on the
+root package's dependency closure. It then ensures the one global web build and the MCP app build exist.
+It does not change either normal Pi settings file.
+
+### No generated per-repository state
+
+Po writes nothing per repository or worktree. po-server composes every session live from configuration
+and installed packages, importing each package's built `dist` directly, so a rebuilt or added package
+reaches the next session without a sync or a restart. The cockpit web build is shared: it lives under
+`~/.po/build/web/<key>`, where the key covers every web plugin package the global root and the
+admitted workspaces use, so two repositories with the same plugins share one build.
+
+Export the HTTP and socket contracts with `po api-export --out ./api-schema --strict`. It reads each
+installed server package's built contract. See [API export](docs/server/api-export.md) for artifact
+formats, CI checks, and package declarations.
+
+Run `po sync --check` to report missing packages or a missing global web build without writing anything.
+Inside a repository, `po sync` installs for that repository. Outside every repository, it installs for the
+global configuration in `~/.po`.
+
+Bare `po` passes every argument to `po-web`. Use `--explain` to resolve a selection without
+starting a session:
+
+```bash
+po --major-mode copilot --no-domains --explain
+po --major-mode minimal --no-domains --explain
+```
+
+## Philosophy
+
+An agent does not need every tool for every job. Po 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.
+
+### Major and minor modes
+
+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.
+
+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. Po ships six:
+
+- **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.
+
+### Domains
+
+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 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:
+
+```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]
+```
+
+Po also checks personal and repository Codex marketplace layouts. Marketplace IDs use
+`plugin@marketplace`. Remote Git and npm sources are downloaded once into the persistent
+`~/.po/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. Po
+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
+```
+
+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.
+
+The savings get larger when each workflow job starts with its own config instead of
+inheriting the last job's toolbox.
+
+### Copilot
+
+Po's web console exposes package-owned tools, commands, settings, and panels.
+Po no longer ships terminal leader menus, shortcuts, overlays, or widgets.
+
+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.
+
+### Autopilot
+
+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
+
+Po's native Workflow runtime starts each step as a configured child session.
+Jobs select their major mode, domains, and system prompt through `runConfig`.
+The tracked examples below contain complete definitions.
+
+#### 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. `.po/domains.yaml` exposes the `development`,
+`testing`, and `blog` domains plus the `engineering` alias. `.po/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
+po --major-mode examples --domains engineering --explain
+po --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@po-examples
+
+# Claude Code
+claude plugin marketplace add ./ --scope user
+claude plugin install development@po-examples --scope user
+```
+
+Substitute `testing` or `blog-writing` to install another bundle. No Po-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
+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
+
+Po is a modular agent harness, not one giant extension. Each package owns one job; shared UI,
+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/po`][pkg-po] is the command-line config compiler and the `po-server` runtime.
+`po init` creates the personal config, and bare `po` starts the `po-web` console. Sync resolves every major
+mode and domain into native server, web, MCP, and resource contributions.
+
+#### Supporting packages
+
+[`@agimon-ai/po-config`][pkg-po-config] resolves the four YAML files and exposes the
+configuration API. [`@agimon-ai/po-domain`][pkg-po-domain] owns domain selection, plugin
+materialization, resource staging, and MCP scoping.
+[`@agimon-ai/po-core`][pkg-po-core] contains the shared
+Cordis service and event contracts used by extension authors.
+[`@agimon-ai/po-hashline`][pkg-po-hashline] provides the shared snapshot tags and line-anchor
+protocol. [`@agimon-ai/po-read`][pkg-po-read] and [`@agimon-ai/po-grep`][pkg-po-grep]
+produce editable anchors for writable files while preserving native output for non-writable files.
+[`@agimon-ai/po-edit`][pkg-po-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/po-file-edit`][pkg-po-file-edit] keeps the edit timeline and file snapshots.
+[`@agimon-ai/po-log`][pkg-po-log] collects session events, while
+[`@agimon-ai/po-telemetry`][pkg-po-telemetry] is the library-level telemetry adapter.
+
+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].
+
+#### Shared UI
+
+[`@agimon-ai/po-ui`][pkg-po-ui] supplies shared web presentation and theme utilities.
+Terminal leader bindings and overlays have been retired.
+
+### Coordinated work
+
+#### Agent team
+
+[`@agimon-ai/po-team`][pkg-po-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 through native Team tools.
+
+#### Tasks
+
+[`@agimon-ai/po-task`][pkg-po-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.
+
+#### Runner
+
+[`@agimon-ai/po-runner`][pkg-po-runner] replaces Pi's blocking `bash` tool with
+supervised command execution. `po 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
+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/po-autocompact`][pkg-po-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/po-help`][pkg-po-help] keeps package guidance out of the default prompt. A
+fresh parent session performs no Help retrieval and exposes no Help skills. Activate Help with the
+native `minor_mode` tool, then deactivate it before the next interaction.
+Help names state their intent: authoring
+guides use `po-author-*`, while operational guides use `po-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/po-mcp`][pkg-po-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; Config publishes it through the native 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/po-user-feedback`][pkg-po-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
+
+Po logging records operational metadata such as counters, spans, session IDs, tool names, and
+errors. Callers remain responsible for values they attach to telemetry. Native diagnostics expose
+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/po-plan`][pkg-po-plan]
+removes `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 the native
+planning tools and web review surface; terminal planning menus are no longer available.
+Turn it on when the approach should be settled before the files move.
+
+#### Loop mode
+
+[`@agimon-ai/po-loop`][pkg-po-loop] is an in-session scheduler. It runs a prompt immediately
+and then repeats it on an interval; several loops can coexist. Native `loop_start`, `loop_list`,
+and `loop_stop` tools control recurring checks and prompts in the current session.
+
+#### Goal mode
+
+[`@agimon-ai/po-goal`][pkg-po-goal] pins one objective to the session until it completes or
+you end it. Native goal tools manage the active objective and repository history. Finished goals
+stop contributing active instructions and tools but remain in history when you want to restart one.
+
+#### Workflow mode
+
+[`@agimon-ai/po-workflow`][pkg-po-workflow] runs GitHub Actions-style job graphs with
+dependencies, timeouts, artifacts, and a separate Po session for each step. Native workflow tools
+and the web workflow dock expose launch, status, and recovery. It is for work that needs hard job
+boundaries and explicit handoffs rather than one long conversation.
+
+#### Voice mode
+
+[`@agimon-ai/po-voice`][pkg-po-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. Native `voice` controls manual
+dictation, while `voice-auto` controls autonomous capture. The active native session receives the
+Voice capabilities and `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, 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. Native workflow and user-feedback narration remain available, and the same
+model continues to provide bounded command correction.
+
+## Configuration
+
+Po 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 `~/.po/` and repository
+overrides in `<repository>/.po/`. Po 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 `~/.po/`; 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. `po init` writes the distribution's current
+feature packages there so the baseline is visible and replaceable. If `default` is absent,
+Po 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. `po sync`
+installs missing required packages from the defaults and every declared layer, moves every
+package in Po's shared `~/.po/runtime` 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. `po 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/po-help'
+    - '@agimon-ai/po-hook'
+    - '@agimon-ai/po-goal'
+    - '@agimon-ai/po-voice'
+    - '@agimon-ai/po-runner'
+    - '@agimon-ai/po-read'
+    - '@agimon-ai/po-grep'
+    - '@agimon-ai/po-edit'
+    - '@agimon-ai/po-file-edit'
+    - '@agimon-ai/po-autocompact'
+    - '@agimon-ai/po-loop'
+    - '@agimon-ai/po-plan'
+    - '@agimon-ai/po-workflow'
+    - '@agimon-ai/po-log'
+    - '@agimon-ai/po-mcp'
+
+layers:
+  team:
+    packages:
+      - name: '@agimon-ai/po-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]
+```
+
+Order matters: Po 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 `po-edit`.
+Replace that entry with the ordered `po-read`, `po-grep`, and `po-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 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]
+```
+
+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
+`~/.po/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.
+
+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.
+
+### `profiles.yaml`: choose a point of view
+
+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; Po concatenates those three files in that order.
+
+```yaml
+profiles:
+  roots: [personas]
+  entries:
+    release-writer:
+      persona: personas/release-writer
+      env:
+        BRAND: acme
+        TONE: concise
+```
+
+With that config, `personas/release-writer/profile.md` is enough to discover
+`release-writer`. The explicit entry is optional; use one when the profile needs another name,
+an exact persona path, or string environment defaults. Explicit entries override discovered
+folders. Already exported environment values win, so selecting a profile never quietly
+replaces a value supplied by the caller.
+
+Discovery never recurses. Persona paths must remain under `agents/` or a root declared in the
+same file, and symlinks may not escape the persona boundary. Legacy profiles written directly
+under `profiles` still load, but new configuration should use `roots` and `entries`.
+
+Select a profile with `--profile release-writer` or switch it with `/profile`. Leaving the
+catalog empty is valid; no profile remains a first-class choice.
+
+### Check the matrix before launch
+
+The fastest configuration debugger is the one that does not start a model:
+
+```bash
+po --major-mode copilot --domains work --profile release-writer --explain
+po sync
+po sync --check
+```
+
+`--explain` prints the resolved mode, domains, profile, plugins, skills, agents, MCP boundary,
+and estimated prompt cost. `po sync` resolves the repository configuration and publishes
+synchronized state. `po 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
+
+Po 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                                                                       |
+| ---------------------------------------- | ---------------------------------------------------------------------------------- |
+| `po`                                     | Starts the `po-web` console and its headless `po-server`; arguments go to po-web   |
+| `po init`                                | Seeds personal config and removes Po entries earlier versions wrote to Pi settings |
+| `po sync`                                | Publishes the current repository, or the global composition outside repositories   |
+| `po sync --check`                        | Exits non-zero when the applicable registered generation is missing or stale       |
+| `po 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                         |
+| `--` and remaining arguments             | Forwards provider or Pi arguments unchanged where the selected command allows it   |
+
+## Troubleshooting and direct use
+
+- Run `po sync --check` to detect drift or missing configured packages, and `po 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.
+- Po-owned packages expose native server, web, and MCP facets, not Pi entry points. Install them with
+  `npm install` or select them in `modes.yaml`. Third-party Pi settings packages still load through
+  the upstream SDK extension host, including provider registration before model selection.
+- Terminal leader menus, shortcuts, overlays, and widgets are no longer shipped. Native commands,
+  tools, and web panels remain where the owning package provides them. 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.
+- The Ollama preset and launcher `--mute` and `--auto-stop` flags are retired. They do not have
+  replacement terminal extensions.
+
+## Architecture
+
+See [Architecture](https://github.com/AgiFlow/po/blob/main/docs/architecture.md) for native
+server/web/MCP facets, canonical fingerprints, transition classification, shared-host Cordis
+lifecycle ownership, and parent/child isolation. Po no longer composes its own Pi factories;
+third-party Pi packages remain supported through the SDK host.
+
+## Development
+
+```bash
+pnpm install
+pnpm build
+pnpm examples:check
+pnpm nx build @agimon-ai/po
+pnpm nx test @agimon-ai/po
+pnpm nx typecheck @agimon-ai/po
+pnpm nx lint @agimon-ai/po
+```
+
+Po is maintained by [Agimon](https://agimon.ai/about).
+
+## License
+
+MIT
+
+## Maintainer release order
+
+Publish [`@agimon-ai/po-core`][pkg-po-core] and
+[`@agimon-ai/po-hashline`][pkg-po-hashline] first, then
+[`@agimon-ai/po-help`][pkg-po-help], and only then the
+[`@agimon-ai/po`][pkg-po] runtime that consumes them. Generated changelogs remain owned
+by the release tooling.
+
+The deploy workflow blocks publishing unless the deterministic Po 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-po]: https://www.npmjs.com/package/@agimon-ai/po
+[pkg-po-ui]: https://www.npmjs.com/package/@agimon-ai/po-ui
+[pkg-po-config]: https://www.npmjs.com/package/@agimon-ai/po-config
+[pkg-po-domain]: https://www.npmjs.com/package/@agimon-ai/po-domain
+[pkg-po-hashline]: https://www.npmjs.com/package/@agimon-ai/po-hashline
+[pkg-po-read]: https://www.npmjs.com/package/@agimon-ai/po-read
+[pkg-po-grep]: https://www.npmjs.com/package/@agimon-ai/po-grep
+[pkg-po-edit]: https://www.npmjs.com/package/@agimon-ai/po-edit
+[pkg-po-file-edit]: https://www.npmjs.com/package/@agimon-ai/po-file-edit
+[pkg-po-log]: https://www.npmjs.com/package/@agimon-ai/po-log
+[pkg-po-telemetry]: https://www.npmjs.com/package/@agimon-ai/po-telemetry
+[pkg-rmux-darwin-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-darwin-arm64
+[pkg-rmux-darwin-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-darwin-x64
+[pkg-rmux-linux-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-linux-arm64
+[pkg-rmux-linux-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rmux-linux-x64
+[pkg-rtk-darwin-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-darwin-arm64
+[pkg-rtk-darwin-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-darwin-x64
+[pkg-rtk-linux-arm64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-linux-arm64
+[pkg-rtk-linux-x64]: https://www.npmjs.com/package/@agimon-ai/po-runner-rtk-linux-x64
+[pkg-po-team]: https://www.npmjs.com/package/@agimon-ai/po-team
+[pkg-po-task]: https://www.npmjs.com/package/@agimon-ai/po-task
+[pkg-po-runner]: https://www.npmjs.com/package/@agimon-ai/po-runner
+[pkg-po-autocompact]: https://www.npmjs.com/package/@agimon-ai/po-autocompact
+[pkg-po-help]: https://www.npmjs.com/package/@agimon-ai/po-help
+[pkg-po-mcp]: https://www.npmjs.com/package/@agimon-ai/po-mcp
+[pkg-po-user-feedback]: https://www.npmjs.com/package/@agimon-ai/po-user-feedback
+[pkg-log-sink-mcp]: https://www.npmjs.com/package/@agimon-ai/log-sink-mcp
+[pkg-po-plan]: https://www.npmjs.com/package/@agimon-ai/po-plan
+[pkg-po-loop]: https://www.npmjs.com/package/@agimon-ai/po-loop
+[pkg-po-goal]: https://www.npmjs.com/package/@agimon-ai/po-goal
+[pkg-po-workflow]: https://www.npmjs.com/package/@agimon-ai/po-workflow
+[pkg-po-voice]: https://www.npmjs.com/package/@agimon-ai/po-voice
+[pkg-po-core]: https://www.npmjs.com/package/@agimon-ai/po-core