agent-control-plane 0.1.14 → 0.2.0

package/README.md

@@ -8,139 +8,196 @@
   <a href="https://github.com/sponsors/ducminhnguyen0319"><img alt="GitHub Sponsors" src="https://img.shields.io/badge/sponsor-GitHub%20Sponsors-ea4aaa?style=flat-square&logo=githubsponsors&logoColor=white"></a>
   <a href="https://socket.dev/npm/package/agent-control-plane"><img alt="Socket" src="https://img.shields.io/badge/Socket-79-f5a623?style=flat-square"></a>
 </p>
-`agent-control-plane` helps a repo keep coding agents running reliably without
-constant human babysitting.
 
-It is the operator layer for coding agents that need to keep running after the
-novelty wears off.
-
-License: `MIT`
-
-Changelog: [CHANGELOG.md](./CHANGELOG.md)
-
-Roadmap: [ROADMAP.md](./ROADMAP.md)
-
-Architecture: [references/architecture.md](./references/architecture.md)
-
-Commands: [references/commands.md](./references/commands.md)
-
-It turns a GitHub repo into a managed runtime with a repeatable setup, a stable
-place for state, a real status command, and a dashboard you can glance at
-without spelunking through temp folders, worktrees, or half-remembered `tmux`
-sessions.
+`agent-control-plane` (ACP) keeps your coding agents running reliably without
+you having to stare at them all day.
 
-ACP does not try to be the coding agent itself. It makes the surrounding system
-less fragile: profile setup, runtime start and stop, heartbeat scheduling,
+It is the operator layer for coding agents that need to keep running after the
+novelty wears off — and the responsible adult in the room that stops them from
+going completely off the rails.
+
+- License: [`MIT`](./LICENSE)
+- Changelog: [CHANGELOG.md](./CHANGELOG.md)
+- Roadmap: [ROADMAP.md](./ROADMAP.md)
+- Architecture: [references/architecture.md](./references/architecture.md)
+- Commands: [references/commands.md](./references/commands.md)
+
+## The Big Idea
+
+Here is the dirty secret nobody in the AI hype cycle wants to admit: **the free
+models are not that dumb.** They are just chaotic. Left alone to manage their
+own execution loop, retry logic, GitHub labels, and publish pipeline, they will
+reliably discover creative new ways to do absolutely nothing useful at 3am while
+you sleep. Give them a tight operating harness and a clear job description,
+however, and suddenly that "not smart enough" free model is grinding through
+your issue backlog like a junior developer who is weirdly enthusiastic about
+reading CI logs.
+
+That is what ACP does. It turns a GitHub repo into a managed runtime: a
+repeatable setup, a stable home for state, a heartbeat that keeps agents
+scheduled and supervised, and a dashboard you can actually glance at without
+spelunking through temp folders, worktrees, or half-remembered `tmux` sessions.
+
+ACP does not try to be the coding agent. It makes the surrounding system less
+fragile: profile setup, runtime start and stop, heartbeat scheduling,
 reconcile-owned outcomes, background execution, and operator visibility under
-`~/.agent-runtime`.
-
-The promise is intentionally boring in the best possible way: your agents stay
-busy, your runtime stays understandable, and the repo keeps moving even when
-you are not sitting there manually babysitting every loop, retry, or publish
-decision.
+`~/.agent-runtime`. The agent writes the code. ACP writes the boring
+infrastructure that keeps the agent from losing its own work.
+
+### Free models: surprisingly economical
+
+If you are using ACP for research, the economics are almost embarrassing.
+Running a free-tier model like `openrouter/qwen3.6-plus:free` continuously
+across multiple repos costs roughly what a large latte costs — per month, not
+per hour. ACP handles quota cooldowns, stall detection, provider failover, and
+retry backoff, so free-tier models become genuinely useful in a production-shaped
+loop instead of a toy demo. For researchers studying agent behavior, measuring
+output quality, or iterating on prompting strategies at scale: you can run
+hundreds of sessions for what you would otherwise spend on a single GPT-4
+afternoon.
+
+**The free model is not brilliant. ACP makes it relentless.**
+
+### Smarter models: powerful, and worth supervising
+
+ACP works equally well with Claude Sonnet, OpenAI Codex, and other
+high-capability backends. They produce better code, handle harder tasks, and
+generally understand the first time what the free model needed three attempts and
+a blocker comment to figure out.
+
+But here is the thing about powerful AI agents running autonomously against your
+GitHub repo: they are, in a very real sense, a slow-burning fuse. An agent with
+broad permissions, no supervision, and no circuit breakers will eventually push
+something broken, auto-merge a PR it should not have touched, burn through a
+monthly API budget in a long weekend, or enter a retry loop that only stops when
+the credit card does.
+
+ACP is the person standing next to the fuse. It enforces launch limits,
+reconciles outcomes before touching GitHub, validates before it publishes, and
+respects cooldowns instead of hammering a provider at full throttle. The agent
+gets to be smart and fast. ACP makes sure "smart and fast" does not also mean
+"unattended and irreversible."
+
+You would not hand a brilliant but impulsive junior developer the repository
+admin key and leave for a two-week vacation. ACP is the on-call rotation for
+your AI workforce — quiet when things go well, essential when they do not.
 
 ## Why people use it
 
-ACP is useful when you want agent workflows to feel operational instead of
-fragile, improvised, or tied to one lucky terminal session.
-
-- replace human babysitting with boring runtime ownership: supervisor,
-  heartbeat, reconcile, and status tooling
-- one profile per repo, so every project has a clear runtime identity
-- start, stop, restart, and status commands that behave like operator tooling
-- dashboard visibility instead of hunting through `tmux` panes and temp folders
-- smoke checks before you trust the runtime on real work
-- optional macOS autostart so a reboot does not reset your flow
-- room for multiple worker backends without changing how you operate the repo
-
 ACP is a good fit when your pain is not "the agent cannot code" but "the setup
-around the agent is too easy to break."
+around the agent is too easy to break" — or "I would trust this agent more if
+it had a supervisor."
+
+| Need | What ACP provides |
+| --- | --- |
+| Keep agent workflows running without babysitting | Supervisor, heartbeat loop, and reconcile scripts that manage the lifecycle automatically |
+| Get real value out of free-tier models | Quota cooldowns, stall detection, provider failover, and retry backoff that free-tier models need to be actually useful |
+| Manage multiple repos cleanly | One profile per repo with isolated runtime state, each with its own identity and status |
+| Observe what is happening without digging through files | Dashboard and `runtime status` that show the real state without spelunking through `tmux` or temp folders |
+| Compare worker backends on real workloads | Swap between `codex`, `claude`, `openclaw`, `ollama`, `pi`, `opencode`, and `kilo` without rebuilding your runtime habits |
+| Run reproducible agent research cheaply | Cost-controlled execution harness for studying agent behavior, output quality, or prompting strategies |
+| Enforce safety by architecture, not by hope | Launch limits, reconcile gates, and cooldowns that are built into the runtime, not left to chance |
 
 ## Use Cases
 
 Teams and solo builders usually reach for ACP when one of these starts to feel
 familiar:
 
-- you want issue-driven or PR-driven agent work to keep running in the
-  background, but still be inspectable
-- you are juggling more than one repo and want each one to have a clean,
-  separate runtime identity
-- you want to swap or compare worker backends without rebuilding your runtime
-  habits every time
-- you want one command to tell you whether automation is healthy instead of
-  inferring it from stale branches, dangling sessions, or mystery files
-- you want a dashboard and smoke checks before you trust the setup on real work
-- you want your local machine to behave more like a reliable operator box and
-  less like a pile of shell history
-
-If you have ever thought "the agent part basically works, but the runtime
-around it is messy," this tool is aimed directly at that problem.
+- Issue-driven or PR-driven agent work should keep running in the background,
+  but still be inspectable and recoverable when something goes wrong.
+- The project has more than one repo, and each one deserves a clean, separate
+  runtime identity instead of sharing state.
+- You want to swap or compare worker backends without rebuilding your runtime
+  setup from scratch every time.
+- You want one command to tell you whether automation is healthy, instead of
+  inferring it from stale branches, dangling sessions, or mystery files under
+  `/tmp`.
+- You are doing research on agent behavior, output quality, or prompt strategy
+  and need a reproducible, cost-controlled execution harness.
+- Your local machine should behave like a reliable operator box, not a pile of
+  shell history that breaks after a reboot.
 
 ## Roadmap
 
-ACP is moving toward a true multi-backend control plane.
+ACP is moving toward a true multi-backend control plane. The goal is one runtime
+and one dashboard for many coding-agent backends, across macOS, Linux, and
+Windows.
 
-- available now: `codex`, `claude`, `openclaw`
-- planned next: `opencode`, `kilo`, `gemini-cli`
-- platform roadmap now calls out Linux, Windows via WSL2, and the longer-term
-  native Windows story explicitly
-- adjacent ecosystem targets now include local-model and neighboring runtimes
-  such as `ollama`, `nanoclaw`, and `picoclaw`
-- roadmap matrix now distinguishes implemented backends from placeholder
-  scaffolds so users can see what is ready today versus what is being prepared
-- long-term direction: one runtime and dashboard for many coding-agent backends
+### Backend Status
 
-### Backend Snapshot
+| Backend | Status | Notes |
+| --- | --- | --- |
+| `codex` | Production-ready | Full ACP workflow support today. |
+| `claude` | Production-ready | Full ACP workflow support today. |
+| `openclaw` | Production-ready | Full ACP workflow support, including resident-style runs. |
+| `ollama` | Experimental | Working adapter with Node.js agentic loop. Runs any model served by a local Ollama instance. Output quality depends on model size — 7–9B models handle exploration well but struggle with complex multi-step tasks. |
+| `pi` | Experimental | Working adapter using the [pi CLI](https://github.com/mariozechner/pi) in `--print --no-session` mode. Connects to any OpenRouter-compatible model. Useful as a lightweight alternative to openclaw for free-tier model testing. |
+| `opencode` | Experimental | Working adapter for [Crush](https://github.com/charmbracelet/crush) (formerly opencode). Non-interactive `crush run` with full tool execution. |
+| `kilo` | Experimental | Working adapter for [Kilo Code](https://github.com/Kilo-Org/kilocode). Non-interactive `kilo run --auto` with JSON event stream. |
+| `gemini-cli` | Roadmap | Strong future candidate; not wired into ACP yet. |
+| `nanoclaw` | Exploratory | Ecosystem reference for containerized and WSL2-friendly workflows. |
+| `picoclaw` | Exploratory | Ecosystem reference for lightweight Linux and edge-style runtimes. |
 
-| Backend | What You Can Expect Today |
-| --- | --- |
-| `codex` | Ready for real ACP workflows today. |
-| `claude` | Ready for real ACP workflows today. |
-| `openclaw` | Ready for real ACP workflows today, including resident-style runs. |
-| `opencode` | Scaffolded in the package so routing and docs can evolve, but not implemented for live execution yet. |
-| `kilo` | Scaffolded in the package so routing and docs can evolve, but not implemented for live execution yet. |
-| `gemini-cli` | Not wired into ACP yet, but on the public roadmap as a strong future worker candidate. |
+If you are trying ACP on a real repo right now, start with `codex`, `claude`,
+or `openclaw`. Use `ollama` to run local models — useful for research, offline
+workflows, or comparing local model output against cloud backends without
+incurring API costs. Use `pi` to experiment with OpenRouter-hosted free-tier
+models via the pi CLI. The remaining entries show the direction of travel, not
+finished support.
 
-### Support Matrix
+See [ROADMAP.md](./ROADMAP.md) for the fuller public roadmap.
 
-| Target | Kind | ACP Relationship Today | Current Status |
-| --- | --- | --- | --- |
-| `codex` | direct worker | First-class ACP worker backend | production-ready path today |
-| `claude` | direct worker | First-class ACP worker backend | production-ready path today |
-| `openclaw` | direct worker | First-class ACP worker backend with resident workflow support | production-ready path today |
-| `opencode` | direct worker | Planned future worker adapter | placeholder scaffold only |
-| `kilo` | direct worker | Planned future worker adapter | placeholder scaffold only |
-| `gemini-cli` | direct worker | Research target for a future worker adapter | roadmap candidate |
-| `ollama` | local model runtime | Candidate local-model substrate behind future ACP integrations | research target |
-| `nanoclaw` | adjacent agent shell | Ecosystem reference for containerized and WSL2-friendly workflows | exploratory interoperability target |
-| `picoclaw` | adjacent agent shell | Ecosystem reference for lightweight Linux and edge-style agent runtimes | exploratory interoperability target |
+### Using Ollama (local models)
 
-If you are trying ACP on a real repo right now, start with `codex`, `claude`,
-or `openclaw`. The other adapters are there to show the direction of travel,
-not to pretend support is already complete.
+To run ACP with a local model via [Ollama](https://ollama.com):
 
-See [ROADMAP.md](./ROADMAP.md) for the fuller public roadmap.
+```bash
+# 1. Install Ollama and pull a model
+ollama pull qwen3.5:9b
 
-## See It Running
+# 2. Init a profile with ollama backend
+npx agent-control-plane@latest init \
+  --profile-id my-repo \
+  --repo-slug owner/my-repo \
+  --repo-root ~/src/my-repo \
+  --agent-root ~/.agent-runtime/projects/my-repo \
+  --worktree-root ~/src/my-repo-worktrees \
+  --coding-worker ollama
+
+# 3. Configure the model in your profile YAML
+#    ~/.agent-runtime/control-plane/profiles/my-repo/control-plane.yaml
+#
+#    execution:
+#      coding_worker: "ollama"
+#      ollama:
+#        model: "qwen3.5:9b"
+#        base_url: "http://localhost:11434"
+#        timeout_seconds: 900
+```
 
-The dashboard media below is rendered from a real local ACP demo fixture using
-`bash tools/bin/render-dashboard-demo-media.sh`.
+The Ollama adapter runs a Node.js agentic loop that calls the Ollama API with
+tool-use support. It handles both native tool-call responses and models that
+return tool calls as JSON text in the content field.
 
-![ACP dashboard demo screenshot](./assets/readme/dashboard-demo.png)
+**Model guidance:** Models in the 7–14B range can explore codebases and run
+commands, but may struggle with complex multi-step repair tasks. Larger models
+(27B+) produce significantly better results if your hardware supports them.
+Thinking mode is disabled by default (`think: false`) and context is set to
+32K tokens to balance speed and capability.
 
-<details>
-<summary>Animated dashboard walkthrough</summary>
+## See It Running
 
-![ACP dashboard demo walkthrough](./assets/readme/dashboard-demo.gif)
+The dashboard gives you a single view across all active profiles — running
+sessions, recent history, provider cooldowns, scheduled issues, and queue state.
 
-</details>
+![ACP dashboard demo screenshot](./assets/readme/dashboard-demo.png)
 
 ## Architecture
 
-ACP is easiest to trust once you can see the moving pieces. The short version
-is: the npm package stages a shared runtime, installed profiles live outside
-the package, a shared heartbeat loop decides what to launch, worker adapters do
-the coding work, and reconcile scripts own the GitHub-facing outcome.
+ACP is easiest to trust once you can see the moving pieces. The npm package
+stages a shared runtime, installed profiles live outside the package, a shared
+heartbeat loop decides what to launch, worker adapters do the coding work, and
+reconcile scripts own the GitHub-facing outcome.
 
 ```mermaid
 flowchart LR
@@ -152,7 +209,7 @@ flowchart LR
   Supervisor --> Heartbeat["heartbeat-safe-auto.sh"]
   Heartbeat --> Scheduler["agent-project-heartbeat-loop"]
   Scheduler --> Workers["issue / PR worker launchers"]
-  Workers --> Backends["codex / claude / openclaw"]
+  Workers --> Backends["codex / claude / openclaw / ollama / pi / opencode / kilo"]
   Backends --> Reconcile["reconcile issue / PR session"]
   Reconcile --> GitHub["issues / PRs / labels / comments"]
   Scheduler --> State["runs + state + history"]
@@ -202,32 +259,28 @@ Visual assets:
 
 ## Prerequisites
 
-ACP is a shell-first operator tool. Most install problems become much easier to
+ACP is a shell-first operator tool. Most install problems become easier to
 debug once it is clear which dependency is responsible for which part of the
 system.
 
-| Tool | Required | Why ACP uses it | Notes |
+| Tool | Required | Purpose | Notes |
 | --- | --- | --- | --- |
-| Node.js `>= 18` | yes | Runs the npm package entrypoint and `npx agent-control-plane ...` wrapper. | ACP declares `>= 18`. CI currently runs on Node `22`, so newer maintained versions are expected to work too. If you are already on Node `20` or `22`, you do not need to downgrade. |
-| `bash` | yes | Most runtime, profile, and worker orchestration scripts are Bash-based. | Your login shell can be `zsh` or something else, but `bash` must exist on `PATH`. |
-| `git` | yes | ACP manages worktrees, checks branch state, and coordinates repo-local automation state. | Required even if you mainly interact through GitHub issues and PRs. |
-| `gh` | yes | ACP uses GitHub CLI auth and API access for issues, PRs, labels, and repo metadata. | Run `gh auth login` before first real use. |
-| `jq` | yes | Several runtime and GitHub flows parse JSON from `gh` and worker metadata. | If `jq` is missing, some operator flows will fail even though the npm package itself installs fine. |
-| `python3` | yes | Powers the dashboard server, snapshot renderer, and a few config/render helpers. | Required for both dashboard use and several internal helper scripts. |
-| `tmux` | yes | ACP runs long-lived worker sessions and captures status through `tmux`. | If `tmux` is missing, background worker workflows will not launch. |
-| Worker CLI: `codex`, `claude`, or `openclaw` | depends on backend | The actual coding worker for a profile. | You only need the backend you plan to choose via `--coding-worker`. Authenticate that backend before starting recurring or background runs. |
-| Bundled `codex-quota` plus ACP quota manager | automatic for Codex profiles | Improves Codex quota-aware failover and health signals. | ACP now ships a maintained `codex-quota` fork and a first-party manager script for Codex worker flows. You only need an external install if you intentionally override `ACP_CODEX_QUOTA_BIN` or `ACP_CODEX_QUOTA_MANAGER_SCRIPT`. |
-| `playwright` and `ffmpeg` | maintainer-only | Regenerate the README dashboard screenshot and GIF. | Needed for `bash tools/bin/render-dashboard-demo-media.sh`, not for everyday ACP use. |
-
-Before you start background runtimes, make sure `gh` and whichever worker
-backend you plan to use are already authenticated for the same OS user.
-
-For Codex-backed profiles, ACP will use the bundled quota tooling by default.
-That keeps quota-aware rotation inside the same package and avoids depending on
-an unmaintained external install. If you already have a custom `codex-quota`
-setup you want to keep, point ACP at it explicitly with
-`ACP_CODEX_QUOTA_BIN=/path/to/codex-quota` and optionally
-`ACP_CODEX_QUOTA_MANAGER_SCRIPT=/path/to/auto-switch.sh`.
+| Node.js `>= 18` | yes | Runs the npm package entrypoint and `npx` wrapper. | CI runs on Node `22`. Node `20` or `22` both work fine. |
+| `bash` | yes | All runtime, profile, and worker orchestration scripts are Bash. | Your login shell can be `zsh`; `bash` just needs to be on `PATH`. |
+| `git` | yes | Manages worktrees, checks branch state, and coordinates repo automation. | Required even if you interact only through GitHub issues and PRs. |
+| `gh` | yes | GitHub CLI auth and API access for issues, PRs, labels, and metadata. | Run `gh auth login` before first use. |
+| `jq` | yes | Parses JSON from `gh` output and worker metadata throughout. | Missing `jq` will break GitHub-heavy and runtime flows. |
+| `python3` | yes | Powers the dashboard server, snapshot renderer, and config helpers. | Required for both dashboard use and several internal scripts. |
+| `tmux` | yes | Runs long-lived worker sessions and captures their status. | Missing `tmux` means background worker workflows will not launch. |
+| Worker CLI (backend-specific) | depends on backend | The coding agent for a profile. Supported: `codex`, `claude`, `openclaw` (production); `ollama`, `pi`, `opencode`, `kilo` (experimental). | Install and authenticate your chosen backend before starting background runs. |
+| `ollama` | for `ollama` backend | Serves local models via OpenAI-compatible API at `http://localhost:11434`. | Install from [ollama.com](https://ollama.com) and pull a model (e.g. `ollama pull qwen3.5:9b`) before use. |
+| `pi` CLI | for `pi` backend | Lightweight coding agent using OpenRouter-compatible APIs. | Install via `npm i -g @mariozechner/pi-coding-agent`. Set `OPENROUTER_API_KEY` before use. |
+| `crush` (opencode) | for `opencode` backend | Go-based coding agent by Charm ([charmbracelet/crush](https://github.com/charmbracelet/crush)). | Install via `brew install charmbracelet/tap/crush`. |
+| `kilo` CLI | for `kilo` backend | TypeScript coding agent ([kilocode/cli](https://github.com/Kilo-Org/kilocode)). | Install via `npm i -g @kilocode/cli`. |
+| Bundled `codex-quota` + ACP quota manager | automatic for Codex | Quota-aware failover and health signals for Codex profiles. | Bundled by default. Override with `ACP_CODEX_QUOTA_BIN` only if you have a custom setup. |
+
+Make sure `gh` and your chosen worker backend are both authenticated for the
+same OS user before starting any background runtime.
 
 ## Install
 
@@ -247,127 +300,69 @@ agent-control-plane help
 The examples below use `npx agent-control-plane@latest ...`, but every command
 works the same way after a global install.
 
-## Support the Project
-
-If ACP saves you time, helps you keep agent workflows sane, or simply makes
-background automation less annoying, you can support the project.
+## First Run
 
-- sponsor the maintainer on GitHub:
-  `https://github.com/sponsors/ducminhnguyen0319`
-- use the npm `funding` metadata so `npm fund` points people to the same place
-- keep the open source core free, then layer in paid help or team features later
+### Option A — Guided setup (recommended)
 
-If you fork or republish this package under another maintainer account, update
-the sponsor links in `package.json` and `.github/FUNDING.yml`.
+The fastest path is the interactive wizard:
 
-### Sponsorship Policy
+```bash
+npx agent-control-plane@latest setup
+```
 
-Sponsorships for this repository are maintainer-managed project support.
+The wizard walks you through the full setup in one pass:
 
-- sponsorships go to the maintainer account linked in the sponsor button
-- sponsorship does not transfer ownership, copyright, patent rights, or control
-  over the project
-- contributors are not automatically entitled to sponsorship payouts
-- the maintainer may choose to use sponsorship funds for project maintenance,
-  infrastructure, contributor rewards, or other project-related work at their
-  discretion
+1. Detects the current repo and suggests sane defaults
+2. Installs missing dependencies and authenticates `gh`
+3. Checks backend readiness (API keys for openclaw/pi, local server for ollama)
+4. Scaffolds the profile, runs health checks, starts the runtime
+5. Launches the monitoring dashboard in the background
+6. Offers to create recurring starter issues so ACP starts working immediately
 
-## First Run
+After the wizard finishes, your repo has a running agent, a live dashboard,
+and a set of `agent-keep-open` issues that ACP will continuously work through.
 
-The shortest path is now a guided setup flow:
+To preview exactly what it would do before touching anything:
 
 ```bash
-npx agent-control-plane@latest setup
+npx agent-control-plane@latest setup --dry-run
 ```
 
-`setup` detects the current repo when it can, suggests sane managed paths under
-`~/.agent-runtime/projects/<profile-id>`, offers to install missing core tools
-when it knows how, can prompt to run `gh auth login`, runs `sync`, scaffolds
-the profile, checks doctor status, reports core tool and auth readiness, and
-can optionally start the runtime for you.
-
-Use it when you want ACP to walk you through the install instead of assembling
-the bootstrap sequence by hand.
-
-During `setup`, ACP can:
-
-- auto-detect the current repo root and GitHub slug when you run it inside a
-  checkout with `origin` configured
-- offer to install missing core tools like `gh`, `jq`, `python3`, or `tmux`
-  through supported package managers such as `brew`, `apt-get`, `dnf`, `yum`,
-  and `pacman`
-- prompt to run `gh auth login` before ACP tries to start background runtime
-  flows
-- offer to install supported worker backends like `codex`, `claude`, or
-  `openclaw` when ACP knows a safe install command, and otherwise show
-  backend-specific next steps, install/auth/verify examples, and a docs URL it
-  can open for you on interactive machines
-- defer anchor repo sync automatically when ACP can scaffold the profile but
-  cannot reach the repo remote yet, so setup can still finish with a clear
-  follow-up instead of failing half way through
-- run one final fix-up summary at the end so you can clear whatever is still
-  red instead of guessing which step to retry next
-- scaffold the profile, run doctor checks, and optionally start the runtime in
-  one guided pass
-
-The wizard now automates ACP's shell/runtime prerequisites and can also
-auto-install supported worker CLIs through npm. If ACP cannot or should not
-install the selected backend itself, it will tell you what is missing, print
-backend-specific next steps, and offer to open the right setup docs before ACP
-tries to launch it.
-
-If you want the same flow without prompts, use flags such as
-`--non-interactive`, `--install-missing-deps`, `--gh-auth-login`,
-`--start-runtime`, and `--json`.
-
-If you want to inspect the entire onboarding plan before ACP touches your
-machine, run:
+For non-interactive use (CI, scripted installs, GUI frontends):
 
 ```bash
-npx agent-control-plane@latest setup --dry-run
+npx agent-control-plane@latest setup \
+  --non-interactive \
+  --install-missing-deps \
+  --start-runtime \
+  --start-dashboard \
+  --create-starter-issues \
+  --json
 ```
 
-That mode renders the detected repo/profile values, dependency and backend
-install commands, auth steps, runtime/launchd intent, and a final fix-up plan
-without writing files, installing packages, or launching background services.
-
-If you are building a GUI installer, setup assistant, or another frontend
-around ACP, add `--json` to either the real run or the dry-run preview. ACP
-will emit exactly one JSON object on `stdout` and send progress logs to
-`stderr`, which keeps parsing stable.
+With `--json`, ACP emits a single structured object on `stdout` and sends
+progress logs to `stderr`, which keeps parsing stable.
 
-If you want the explicit manual path, the happy path is still:
+### Option B — Manual setup
 
-1. authenticate GitHub
-2. sync the packaged runtime into `~/.agent-runtime`
-3. create one profile for one repo
-4. run quick health checks
-5. start the runtime and confirm it answers to you
+If you prefer explicit control over each step:
 
-If that feels more like installing an operator tool than a toy demo, that is
-intentional.
-
-### 1. Authenticate GitHub first
+**1. Authenticate GitHub**
 
 ```bash
 gh auth login
 ```
 
-ACP assumes GitHub access is already in place before you ask it to manage repo
-automation. If `gh` cannot see the repo, the rest of the flow will feel broken
-for reasons that have nothing to do with ACP.
-
-### 2. Install or refresh the packaged runtime
+**2. Install the packaged runtime**
 
 ```bash
 npx agent-control-plane@latest sync
 ```
 
-This publishes the packaged ACP runtime into `~/.agent-runtime/runtime-home`.
-You can safely run it again after upgrades. Think of this as "put the operator
-tooling in place on disk" before you wire it to a specific repo.
+This stages the ACP runtime into `~/.agent-runtime/runtime-home`. Safe to
+re-run after upgrades.
 
-### 3. Create one profile for one repo manually
+**3. Create a profile for your repo**
 
 ```bash
 npx agent-control-plane@latest init \
@@ -379,217 +374,196 @@ npx agent-control-plane@latest init \
   --coding-worker openclaw
 ```
 
-That single command tells ACP what repo to manage, where its runtime state
-should live, where worktrees belong, and which worker backend you want ACP to
-orchestrate.
-
-What those flags mean:
-
-- `--profile-id` is the short name you will use in ACP commands
-- `--repo-slug` is the GitHub repo ACP should track
-- `--repo-root` points at your local checkout
-- `--agent-root` is where ACP keeps per-project runtime state
-- `--worktree-root` is where ACP can place repo worktrees
-- `--coding-worker` picks the backend ACP should orchestrate
+| Flag | Purpose |
+| --- | --- |
+| `--profile-id` | Short name used in all ACP commands |
+| `--repo-slug` | GitHub repo ACP should track |
+| `--repo-root` | Path to your local checkout |
+| `--agent-root` | Where ACP keeps per-project runtime state |
+| `--worktree-root` | Where ACP places repo worktrees |
+| `--coding-worker` | Backend to orchestrate (`codex`, `claude`, `openclaw`, `ollama`, `pi`, `opencode`, or `kilo`) |
 
-### 4. Validate before you trust it
+**4. Validate before trusting it**
 
 ```bash
 npx agent-control-plane@latest doctor
 npx agent-control-plane@latest profile-smoke --profile-id my-repo
 ```
 
-This is the "trust, but verify" step. `doctor` checks installation health, and
-`profile-smoke` gives one profile a fast confidence pass before you turn on
-background loops.
+`doctor` checks installation health. `profile-smoke` gives the profile a fast
+confidence pass before you turn on background loops.
 
-### 5. Start the runtime and make sure it answers back
+**5. Start the runtime**
 
 ```bash
 npx agent-control-plane@latest runtime start --profile-id my-repo
 npx agent-control-plane@latest runtime status --profile-id my-repo
 ```
 
-At this point ACP is no longer just installed. It is actively managing the
-runtime for that profile. If `runtime status` feels boring and readable, that
-is a good sign. That is exactly the point.
+Once `runtime status` returns clean output, ACP is actively managing the
+runtime for that profile. Per-profile state lives under `~/.agent-runtime`,
+grouped and inspectable without digging through scattered temp files.
+
+## Starter Issues
 
-## What Happens After `runtime start`
+The setup wizard can create a set of recurring `agent-keep-open` issues on your
+repo so ACP starts working immediately after installation. Each issue carries the
+`agent-ready` and `agent-keep-open` labels, and ACP picks them up on its next
+heartbeat cycle.
 
-ACP takes the profile you installed and runs it like an operator would:
+Built-in templates:
 
-- it uses the installed runtime layout under `~/.agent-runtime`
-- it keeps per-profile state grouped together instead of scattered everywhere
-- it gives you a stable `runtime status` command for health checks
-- it lets you inspect the system through the dashboard rather than memory
+| Issue | What ACP does |
+| --- | --- |
+| Code quality sweep | Fix lint warnings, type errors, and dead code |
+| Test coverage improvement | Add tests for critical untested modules |
+| Documentation refresh | Keep README and inline docs accurate |
+| Dependency audit | Fix vulnerabilities and update safe patches |
+| Refactoring sweep | Reduce complexity and duplication |
 
-That matters most when the setup grows beyond one-off experiments and becomes
-something you want to keep running.
+You can also create your own recurring issues — just add the `agent-ready` and
+`agent-keep-open` labels to any GitHub issue and ACP will work on it
+continuously.
 
-## Everyday Usage
+To skip this step during setup, pass `--no-create-starter-issues`.
 
-Check runtime state:
+## Everyday Usage
 
 ```bash
+# Check runtime state
 npx agent-control-plane@latest runtime status --profile-id my-repo
-```
-
-Restart the runtime:
 
-```bash
+# Restart the runtime
 npx agent-control-plane@latest runtime restart --profile-id my-repo
-```
 
-Stop the runtime:
-
-```bash
+# Stop the runtime
 npx agent-control-plane@latest runtime stop --profile-id my-repo
-```
 
-Run smoke checks:
-
-```bash
+# Run smoke checks
 npx agent-control-plane@latest profile-smoke --profile-id my-repo
 npx agent-control-plane@latest smoke
 ```
 
-This is the rhythm ACP is built for: install once, inspect often, restart when
-needed, and keep the runtime understandable.
-
 ## Dashboard
 
-Run the dashboard locally:
-
 ```bash
 npx agent-control-plane@latest dashboard --host 127.0.0.1 --port 8765
 ```
 
-Then open:
-
-```text
-http://127.0.0.1:8765
-```
-
-The dashboard is where ACP gets much more pleasant to use. Instead of treating
-automation like a black box, you can track profiles, runtime state, and system
-activity in one place.
-
-## Contributing
+Then open `http://127.0.0.1:8765`.
 
-Contributions are welcome, but this repo uses a contributor agreement so the
-project can stay easy to maintain and relicense if needed.
-
-- contribution guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
-- contributor agreement: [CLA.md](./CLA.md)
-
-## Security
-
-If you find a vulnerability, do not open a public issue first.
-
-- security policy: [SECURITY.md](./SECURITY.md)
-- code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
-
-## Releases
-
-- release history: [CHANGELOG.md](./CHANGELOG.md)
-- maintainer checklist: [references/release-checklist.md](./references/release-checklist.md)
+The dashboard shows all active profiles in one place: running sessions, recent
+run history, provider cooldowns, scheduled issues, and queue state — without
+having to dig through `tmux` panes or temp folders.
 
 ## macOS Autostart
 
-If you want a profile runtime to come back automatically after login or reboot:
+Install a per-profile LaunchAgent so the runtime survives reboots:
 
 ```bash
 npx agent-control-plane@latest launchd-install --profile-id my-repo
 ```
 
-Remove that autostart entry:
+Remove it:
 
 ```bash
 npx agent-control-plane@latest launchd-uninstall --profile-id my-repo
 ```
 
-These commands are macOS-only because they manage per-user `launchd` agents.
+These commands are macOS-only and manage per-user `launchd` agents.
 
 ## Update
 
-Refresh the installed runtime after upgrading the package:
+After upgrading the package, refresh the runtime and verify health:
 
 ```bash
 npx agent-control-plane@latest sync
 npx agent-control-plane@latest doctor
+npx agent-control-plane@latest smoke   # optional confidence check
 ```
 
-Optional confidence check:
-
-```bash
-npx agent-control-plane@latest smoke
-```
-
-This keeps the runtime on disk aligned with the packaged version you just
-installed.
-
 ## Remove a Profile
 
-Delete one installed profile and its ACP-managed runtime state:
+Remove one profile and its ACP-managed runtime state:
 
 ```bash
 npx agent-control-plane@latest remove --profile-id my-repo
 ```
 
-Also remove ACP-managed repo and worktree paths:
+Also remove ACP-managed repo and worktree directories:
 
 ```bash
 npx agent-control-plane@latest remove --profile-id my-repo --purge-paths
 ```
 
-Use `--purge-paths` only when you want ACP-managed directories removed too.
+Use `--purge-paths` only when you want ACP-managed directories deleted too.
 
 ## Troubleshooting
 
-- `profile not installed`
-  Run `init` first, then retry with the same `--profile-id`.
-- `explicit profile selection required`
-  Pass `--profile-id <id>` to `runtime`, `launchd-install`,
-  `launchd-uninstall`, and `remove`.
-- `gh` cannot access the repo
-  Re-run `gh auth login` and confirm the repo slug in the profile is correct.
-- setup deferred anchor repo sync
-  ACP could not reach the repo remote yet. Fix Git access or the remote URL,
-  then rerun `setup` or `init` without `--skip-anchor-sync`.
-- backend auth failures from `codex`, `claude`, or `openclaw`
-  Authenticate that backend before starting ACP in the background.
-- `node` is older than `18`
-  Upgrade Node first. ACP's package contract starts at `18+`.
-- you are already on Node `20` or `22`
-  That is fine. The package only has a minimum version, not a maximum.
-- missing `jq`
-  Install `jq`, then retry the GitHub- or runtime-heavy command that failed.
-- runtime or source drift after updates
-  Run `sync`, then `doctor`.
-- missing `tmux`, `gh`, or `python3`
-  Install the dependency, then retry `sync` or `runtime start`.
-- missing `codex-quota`
-  This is only an optional Codex enhancement. Core ACP installation and most
-  non-Codex flows do not require it.
+| Symptom | Fix |
+| --- | --- |
+| `profile not installed` | Run `init` first, then retry with the same `--profile-id`. |
+| `explicit profile selection required` | Pass `--profile-id <id>` to `runtime`, `launchd-install`, `launchd-uninstall`, and `remove`. |
+| `gh` cannot access the repo | Re-run `gh auth login` and confirm the repo slug in the profile is correct. |
+| Setup deferred anchor repo sync | ACP could not reach the repo remote. Fix Git access or the remote URL, then re-run `setup` or `init` without `--skip-anchor-sync`. |
+| Backend auth failures | Authenticate the backend before starting ACP. For `openclaw`/`pi`, set `OPENROUTER_API_KEY`. For `ollama`, ensure the server is running. For `opencode`/`kilo`, install and authenticate the CLI. |
+| Node older than `18` | Upgrade Node first. ACP's minimum version is `18+`. |
+| Missing `jq` | Install `jq`, then retry the failed command. |
+| Runtime or source drift after an update | Run `sync`, then `doctor`. |
+| Missing `tmux`, `gh`, or `python3` | Install the dependency, then retry `sync` or `runtime start`. |
+| Missing `codex-quota` warning | This is optional. Core ACP and all non-Codex flows do not require it. |
 
 ## Command Summary
 
-| Command | What it is for | Key args and parameters |
-| --- | --- | --- |
-| `npx agent-control-plane@latest help` | Show the public CLI surface. | No args. Good first command on a new machine. |
-| `npx agent-control-plane@latest version` | Print the package version you are actually running. | No args. Useful when comparing local output to docs or release notes. |
-| `npx agent-control-plane@latest setup` | Guided bootstrap for one repo profile. | Auto-detects repo details when possible, prompts for missing values, can install missing core tools, supported worker backends, and run `gh auth login`, then runs `sync`, `init`, health checks, optional runtime start, and a final fix-up pass. Add `--json` for one structured JSON result on `stdout`. |
-| `npx agent-control-plane@latest setup --dry-run` | Preview exactly what setup would do without changing the machine. | Also available as `--plan`. Prints detected paths, command previews, auth/runtime intentions, and final fix-up plan. Add `--json` for a machine-readable plan object. |
-| `npx agent-control-plane@latest sync` | Publish or refresh the packaged runtime into `~/.agent-runtime/runtime-home`. | No required args. Run this after install or upgrade. |
-| `npx agent-control-plane@latest install` | Alias for `sync`. | Same behavior as `sync`. |
-| `npx agent-control-plane@latest init ...` | Scaffold and adopt one repo profile. | Usually includes `--profile-id`, `--repo-slug`, `--repo-root`, `--agent-root`, `--worktree-root`, and `--coding-worker`. Helpful bootstrap flags include `--allow-missing-repo`, `--skip-anchor-sync`, and `--skip-workspace-sync`. |
-| `npx agent-control-plane@latest doctor` | Inspect runtime/source installation health. | No required args. Use after `sync` or when something feels off. |
-| `npx agent-control-plane@latest profile-smoke [--profile-id <id>]` | Validate one installed profile before you trust it. | `--profile-id` is recommended when more than one profile exists. |
-| `npx agent-control-plane@latest runtime <status|start|stop|restart> --profile-id <id>` | Operate one profile runtime. | `--profile-id` is required for real use. Subcommands are `status`, `start`, `stop`, and `restart`. |
-| `npx agent-control-plane@latest dashboard [--host 127.0.0.1] [--port 8765]` | Start the local monitoring dashboard. | `--host` and `--port` are optional; defaults are good for most local setups. |
-| `npx agent-control-plane@latest launchd-install --profile-id <id>` | Install a per-profile LaunchAgent on macOS. | macOS only. Requires `--profile-id`. |
-| `npx agent-control-plane@latest launchd-uninstall --profile-id <id>` | Remove a per-profile LaunchAgent on macOS. | macOS only. Requires `--profile-id`. |
-| `npx agent-control-plane@latest remove --profile-id <id> [--purge-paths]` | Remove an installed profile and ACP-managed state. | `--purge-paths` also deletes ACP-managed repo/worktree paths, so use it carefully. |
-| `npx agent-control-plane@latest smoke` | Run the packaged smoke suite for the shared control plane. | No required args. Best used after `sync` or before a public release. |
+| Command | Purpose |
+| --- | --- |
+| `help` | Show the full CLI surface. Good first command on a new machine. |
+| `version` | Print the running package version. |
+| `setup [--dry-run] [--json]` | Guided bootstrap wizard. Detects repo, installs deps, scaffolds profile, starts runtime and dashboard, creates starter issues. `--dry-run` previews. `--json` emits structured output. |
+| `sync` / `install` | Stage or refresh the packaged runtime into `~/.agent-runtime/runtime-home`. Run after install or upgrade. |
+| `init ...` | Scaffold one repo profile manually. Requires `--profile-id`, `--repo-slug`, `--repo-root`, `--agent-root`, `--worktree-root`, `--coding-worker`. |
+| `doctor` | Inspect runtime and source installation health. |
+| `profile-smoke [--profile-id <id>]` | Validate one profile before trusting it with real work. |
+| `runtime <status\|start\|stop\|restart> --profile-id <id>` | Operate one profile runtime. |
+| `dashboard [--host] [--port]` | Start the local monitoring dashboard. Defaults: `127.0.0.1:8765`. |
+| `launchd-install --profile-id <id>` | Install a per-profile LaunchAgent on macOS. |
+| `launchd-uninstall --profile-id <id>` | Remove a per-profile LaunchAgent on macOS. |
+| `remove --profile-id <id> [--purge-paths]` | Remove a profile and its ACP-managed state. `--purge-paths` also deletes managed directories. |
+| `smoke` | Run the packaged smoke suite for the shared control plane. |
 
 For a lower-level script map, see [references/commands.md](./references/commands.md).
+
+## Support the Project
+
+If ACP saves you time or keeps your agent workflows sane, you can support the
+project via [GitHub Sponsors](https://github.com/sponsors/ducminhnguyen0319).
+
+The open source core stays free. If you fork or republish this package under
+another maintainer account, update the sponsor links in `package.json` and
+`.github/FUNDING.yml`.
+
+**Sponsorship policy:** Sponsorships are maintainer-managed project support.
+They do not transfer ownership, copyright, patent rights, or control over the
+project. Contributors are not automatically entitled to sponsorship payouts. The
+maintainer may direct funds toward maintenance, infrastructure, contributor
+rewards, or other project-related work at their discretion.
+
+## Contributing
+
+Contributions are welcome. This repo uses a contributor agreement so the
+project can stay easy to maintain and relicense if needed.
+
+- Contribution guide: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Contributor agreement: [CLA.md](./CLA.md)
+
+## Security
+
+Do not open a public issue for vulnerabilities.
+
+- Security policy: [SECURITY.md](./SECURITY.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+
+## Releases
+
+- Release history: [CHANGELOG.md](./CHANGELOG.md)
+- Maintainer checklist: [references/release-checklist.md](./references/release-checklist.md)