@agimon-ai/po 0.0.0-alpha.1 → 0.0.0-stage

package/README.md

@@ -1,755 +1,3 @@
-# Po
+# Temporary Holding Version
 
-**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
+This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.