agent-control-plane 0.1.6 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-control-plane",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "Help a repo keep GitHub-driven coding agents running reliably without constant human babysitting",
   "homepage": "https://github.com/ducminhnguyen0319/agent-control-plane",
   "bugs": {
@@ -24,6 +24,7 @@
     "bin",
     "hooks",
     "npm/bin",
+    "references",
     "tools/bin",
     "tools/dashboard/app.js",
     "tools/dashboard/dashboard_snapshot.py",
@@ -39,7 +40,7 @@
   "scripts": {
     "doctor": "node ./npm/bin/agent-control-plane.js doctor",
     "smoke": "node ./npm/bin/agent-control-plane.js smoke",
-    "test": "bash tools/tests/test-agent-control-plane-npm-cli.sh && bash tools/tests/test-profile-adopt-skip-anchor-sync-creates-agent-repo-root.sh && bash tools/tests/test-vendored-codex-quota-claude-oauth-only.sh"
+    "test": "bash tools/tests/test-agent-control-plane-npm-cli.sh && bash tools/tests/test-profile-adopt-skip-anchor-sync-creates-agent-repo-root.sh && bash tools/tests/test-vendored-codex-quota-claude-oauth-only.sh && bash tools/tests/test-package-smoke-command.sh"
   },
   "keywords": [
     "agents",

package/references/architecture.md

@@ -0,0 +1,209 @@
+# Architecture Guide
+
+This document explains how `agent-control-plane` is put together as an
+operator-facing system, not just a collection of scripts.
+
+ACP has five practical layers:
+
+1. package entrypoint and staging
+2. profile installation and publication
+3. runtime supervision and heartbeat scheduling
+4. worker execution and reconcile
+5. dashboard and operator visibility
+
+If you are reading the repo for the first time, start with the system overview
+diagram below, then jump to the flow you care about most.
+
+## System Overview
+
+```mermaid
+flowchart LR
+  User[Operator] --> CLI["npm/bin/agent-control-plane.js"]
+
+  CLI --> Init["project-init.sh"]
+  CLI --> Sync["sync-shared-agent-home.sh"]
+  CLI --> RuntimeCtl["project-runtimectl.sh"]
+  CLI --> DashboardCmd["serve-dashboard.sh"]
+
+  Init --> Profiles["Profile registry\n~/.agent-runtime/control-plane/profiles/<id>"]
+  Sync --> RuntimeHome["Runtime home\n~/.agent-runtime/runtime-home"]
+
+  RuntimeCtl --> Supervisor["project-runtime-supervisor.sh"]
+  Supervisor --> Bootstrap["project-launchd-bootstrap.sh"]
+  Bootstrap --> Heartbeat["heartbeat-safe-auto.sh"]
+  Heartbeat --> Scheduler["agent-project-heartbeat-loop"]
+
+  Scheduler --> IssueWorkers["start-issue-worker.sh"]
+  Scheduler --> PRWorkers["start-pr-review-worker.sh\nstart-pr-fix-worker.sh\nstart-pr-merge-repair-worker.sh"]
+  IssueWorkers --> Router["run-codex-task.sh"]
+  PRWorkers --> Router
+
+  Router --> Codex["agent-project-run-codex-session"]
+  Router --> Claude["agent-project-run-claude-session"]
+  Router --> OpenClaw["agent-project-run-openclaw-session"]
+
+  Codex --> Artifacts["run.env / runner.env /\nresult.env / verification.jsonl"]
+  Claude --> Artifacts
+  OpenClaw --> Artifacts
+
+  Artifacts --> Reconcile["reconcile-issue-worker.sh\nreconcile-pr-worker.sh"]
+  Reconcile --> GitHub["GitHub issues / PRs / labels / comments"]
+  Reconcile --> History["runs/ + history/ + state/"]
+
+  DashboardCmd --> Snapshot["dashboard_snapshot.py"]
+  Snapshot --> Profiles
+  Snapshot --> History
+  Snapshot --> Browser["Local dashboard browser"]
+```
+
+The important architectural choice is that ACP separates:
+
+- package distribution from runtime execution
+- shared engine logic from per-profile config
+- worker execution from reconcile and GitHub side effects
+- operator visibility from the worker CLIs themselves
+
+## Install and Publication Flow
+
+This is the path from `npx agent-control-plane ...` to a usable runtime on disk.
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant CLI as agent-control-plane.js
+  participant Stage as staged shared-home
+  participant Init as project-init.sh
+  participant Scaffold as scaffold-profile.sh
+  participant Smoke as profile-smoke.sh
+  participant Adopt as profile-adopt.sh
+  participant Sync as sync-shared-agent-home.sh
+
+  User->>CLI: npx agent-control-plane init ...
+  CLI->>Stage: copy packaged skill into temp shared-home
+  CLI->>Init: forward command with staged env
+  Init->>Scaffold: write control-plane.yaml + profile docs
+  Init->>Smoke: validate profile contract
+  Init->>Adopt: create runtime roots / sync anchor repo / workspace
+  Init->>Sync: publish shared runtime into ~/.agent-runtime/runtime-home
+```
+
+Why this split exists:
+
+- the npm package is treated as a distribution artifact
+- the real runtime is copied into `~/.agent-runtime/runtime-home`
+- installed profiles live outside the package in
+  `~/.agent-runtime/control-plane/profiles/<id>`
+- upgrades are therefore explicit and repeatable instead of depending on a temp
+  `npx` cache directory
+
+## Runtime Scheduler Loop
+
+This is the heartbeat path ACP follows after `runtime start`.
+
+```mermaid
+flowchart TD
+  Start["runtime start"] --> RuntimeCtl["project-runtimectl.sh"]
+  RuntimeCtl --> Supervisor["project-runtime-supervisor.sh"]
+  Supervisor --> Bootstrap["project-launchd-bootstrap.sh"]
+  Bootstrap --> SyncCheck["sync runtime copy if needed"]
+  SyncCheck --> Heartbeat["heartbeat-safe-auto.sh"]
+  Heartbeat --> Preflight["locks / quota preflight /\nretained-worktree audit"]
+  Preflight --> SharedLoop["agent-project-heartbeat-loop"]
+
+  SharedLoop --> ReconcileCompleted["reconcile completed sessions"]
+  SharedLoop --> Capacity["compute capacity / cooldown / pending launches"]
+  SharedLoop --> Workflows["select workflow lane from issue + PR state"]
+
+  Workflows --> IssueImplementation["issue implementation"]
+  Workflows --> IssueScheduled["scheduled issue checks"]
+  Workflows --> IssueRecovery["blocked recovery"]
+  Workflows --> PRReview["PR review"]
+  Workflows --> PRFix["PR fix"]
+  Workflows --> PRMergeRepair["merge repair"]
+```
+
+Key detail: the shared scheduler owns the control logic around workers:
+
+- concurrency and heavy-worker limits
+- cooldown and retry gating
+- resident recurring and scheduled issue lanes
+- launch ordering
+- summary output and queue visibility
+
+That is why workers do not need to be "smart" about the entire system. The
+workflow around them carries a lot of the operational burden.
+
+## Worker Session Lifecycle
+
+This is the path from one chosen issue or PR to a reconciled outcome.
+
+```mermaid
+flowchart LR
+  Pick["heartbeat selects issue or PR"] --> Launch["start-issue-worker.sh\nor start-pr-*.sh"]
+  Launch --> Worktree["open or reuse managed worktree"]
+  Worktree --> Prompt["render prompt + context files"]
+  Prompt --> Route["run-codex-task.sh"]
+
+  Route --> Backend["Codex / Claude / OpenClaw adapter"]
+  Backend --> Session["backend session wrapper"]
+  Session --> Output["result.env / comments /\nverification.jsonl / runner.env"]
+
+  Output --> Reconcile["agent-project-reconcile-issue-session\nor agent-project-reconcile-pr-session"]
+  Reconcile --> Labels["update labels / retry state /\nresident metadata / cooldown"]
+  Reconcile --> Publish["comment on issue, open PR,\nor leave blocked report"]
+  Reconcile --> Archive["archive run into history root"]
+```
+
+The contract here is deliberate:
+
+- worker backends focus on producing work and result artifacts
+- reconcile scripts own the final interpretation and GitHub-facing outcome
+- resident metadata and history are updated by the host workflow, not by the
+  worker trying to infer the entire system state
+
+## Dashboard Snapshot Pipeline
+
+The dashboard is a read-only window into ACP state. It does not own scheduling.
+
+```mermaid
+flowchart LR
+  Browser["browser"] --> Server["tools/dashboard/server.py"]
+  Server --> API["GET /api/snapshot.json"]
+  API --> Snapshot["dashboard_snapshot.py"]
+
+  Snapshot --> Registry["profile registry"]
+  Snapshot --> Config["render-flow-config.sh"]
+  Snapshot --> WorkerStatus["agent-project-worker-status"]
+  Snapshot --> Runs["runs/ history/ state/"]
+
+  Registry --> JSON["snapshot payload"]
+  Config --> JSON
+  WorkerStatus --> JSON
+  Runs --> JSON
+
+  JSON --> UI["dashboard app.js + index.html"]
+```
+
+This means the dashboard reflects the current state of:
+
+- installed profiles
+- live and recent runs
+- resident controller metadata
+- provider cooldowns
+- scheduled issue state
+- runtime process status
+
+without introducing a second control path that could drift away from the real
+scheduler state.
+
+## Reading Order
+
+If you want the shortest path through the architecture:
+
+1. [System Overview](#system-overview)
+2. [Runtime Scheduler Loop](#runtime-scheduler-loop)
+3. [Worker Session Lifecycle](#worker-session-lifecycle)
+4. [Dashboard Snapshot Pipeline](#dashboard-snapshot-pipeline)
+
+If you are changing packaging or onboarding, also read
+[Install and Publication Flow](#install-and-publication-flow).

package/references/commands.md

@@ -0,0 +1,127 @@
+# Command Map
+
+Run commands from the current isolated checkout for the task.
+
+Profile-specific repo roots and repo-local dev/test commands belong in
+`~/.agent-runtime/control-plane/profiles/<id>/README.md`. Resolve the active
+profile first, then use the selected profile's notes for product-repo commands.
+
+## Profile Resolution
+
+```bash
+bash tools/bin/workflow-catalog.sh profiles
+tools/bin/workflow-catalog.sh context
+bash tools/bin/profile-activate.sh --profile-id <id>
+ACP_PROJECT_ID=<id> bash tools/bin/render-flow-config.sh
+```
+
+Use `render-flow-config.sh` when you need the effective repo root, worktree
+root, runtime root, worker backend, or profile-specific script bindings.
+When multiple available profiles exist, set `ACP_PROJECT_ID=<id>` first or use
+`profile-activate.sh --profile-id <id>` before running manual operator
+commands.
+
+## Dependency bootstrap
+
+Run dependency bootstrap only from the clean automation baseline for the
+selected profile when you explicitly need to refresh shared dependencies. Do not
+repair shared `node_modules` from inside a worker worktree.
+
+For control-plane changes in this repo, prefer focused shell tests over broad
+bootstrap unless the task actually changes dependency behavior.
+
+## Control-Plane Verification
+
+```bash
+bash tools/bin/check-skill-contracts.sh
+bash tools/bin/flow-runtime-doctor.sh
+bash tools/bin/profile-smoke.sh
+bash tools/bin/test-smoke.sh
+bash tools/tests/test-project-init.sh
+bash tools/tests/test-project-init-force-and-skip-sync.sh
+bash tools/tests/test-project-remove.sh
+bash tools/tests/test-project-runtimectl.sh
+bash tools/tests/test-project-runtimectl-missing-profile.sh
+bash tools/tests/test-project-runtimectl-stop-cancels-pending-kick.sh
+bash tools/tests/test-project-runtimectl-start-falls-back-to-bootstrap.sh
+bash tools/tests/test-project-runtimectl-status-supervisor-running.sh
+bash tools/tests/test-project-launchd-bootstrap.sh
+bash tools/tests/test-install-project-launchd.sh
+bash tools/tests/test-uninstall-project-launchd.sh
+bash tools/tests/test-project-runtimectl-launchd.sh
+bash tools/tests/test-dashboard-launchd-bootstrap.sh
+bash tools/tests/test-install-dashboard-launchd.sh
+bash tools/tests/test-render-dashboard-snapshot.sh
+bash tools/tests/test-serve-dashboard.sh
+bash tools/tests/test-control-plane-dashboard-runtime-smoke.sh
+bash tools/tests/test-workflow-catalog.sh
+bash tools/tests/test-render-flow-config.sh
+```
+
+Add or run targeted tests in `tools/tests/` for the changed surface.
+
+## Flow maintenance
+
+```bash
+tools/bin/flow-runtime-doctor.sh
+tools/bin/workflow-catalog.sh list
+tools/bin/workflow-catalog.sh show pr-review
+tools/bin/workflow-catalog.sh profiles
+tools/bin/workflow-catalog.sh context
+tools/bin/profile-activate.sh --profile-id <id>
+tools/bin/project-init.sh --profile-id <id> --repo-slug <owner/repo>
+tools/bin/render-flow-config.sh
+tools/bin/scaffold-profile.sh --profile-id <id> --repo-slug <owner/repo>
+tools/bin/profile-smoke.sh
+tools/bin/test-smoke.sh
+tools/bin/profile-adopt.sh --profile-id <id>
+tools/bin/project-runtimectl.sh status --profile-id <id>
+tools/bin/project-runtimectl.sh stop --profile-id <id>
+tools/bin/project-runtimectl.sh start --profile-id <id>
+tools/bin/project-runtimectl.sh restart --profile-id <id>
+tools/bin/install-project-launchd.sh --profile-id <id>
+tools/bin/uninstall-project-launchd.sh --profile-id <id>
+tools/bin/project-remove.sh --profile-id <id>
+tools/bin/project-remove.sh --profile-id <id> --purge-paths
+tools/bin/sync-shared-agent-home.sh
+python3 tools/bin/render-dashboard-snapshot.py --pretty
+bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
+bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
+```
+
+Installed profile prompts should live under
+`~/.agent-runtime/control-plane/profiles/<id>/templates/`; generic fallback
+prompts live under `tools/templates/`.
+
+## Dashboard
+
+```bash
+python3 tools/bin/render-dashboard-snapshot.py --pretty
+bash tools/bin/serve-dashboard.sh --host 127.0.0.1 --port 8765
+bash tools/bin/install-dashboard-launchd.sh --host 127.0.0.1 --port 8765
+```
+
+Use the snapshot command for CLI/debug output and the HTTP server for the live
+dashboard at `http://127.0.0.1:8765`. Use the LaunchAgent installer when you
+want the dashboard to come back automatically after macOS restart/login.
+
+## Project Autostart
+
+```bash
+bash tools/bin/install-project-launchd.sh --profile-id <id>
+bash tools/bin/uninstall-project-launchd.sh --profile-id <id>
+```
+
+Use the project installer when one profile should come back automatically after
+macOS restart/login. `project-runtimectl.sh start|stop|status` will detect that
+per-project LaunchAgent automatically once it is installed.
+
+## Repo-Specific Commands
+
+After choosing a profile, read `~/.agent-runtime/control-plane/profiles/<id>/README.md` for:
+
+- clean automation baseline and retained checkout roots
+- repo-local startup docs such as `AGENTS.md` and OpenSpec paths
+- app/package-specific dev commands
+- isolated smoke and release-rehearsal commands
+- project-specific operator runbooks

package/references/control-plane-map.md

@@ -0,0 +1,120 @@
+# Agent Control Plane Map
+
+This repository is the shared `agent-control-plane` package. It provides a
+generic engine that can host multiple installed profiles, each with its own repo
+roots, labels, worker preferences, prompts, and project-specific guardrails.
+
+## What Lives Here
+
+- `SKILL.md`
+  Canonical operating manual for the shared control plane.
+- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
+  Canonical installed project profile for repo paths, queue labels, limits,
+  and script bindings.
+- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
+  Repo-specific operator notes, startup docs, and command references for the
+  selected profile.
+- `~/.agent-runtime/control-plane/profiles/<id>/templates/`
+  Optional installed profile-specific prompt overrides.
+- `assets/workflow-catalog.json`
+  Declarative catalog of the workflow lanes this control plane exposes.
+- `bin/`
+  Queue, label, and risk logic shared by installed profiles.
+- `hooks/`
+  Heartbeat and reconcile hooks shared by installed profiles.
+- `tools/bin/flow-runtime-doctor.sh`
+  Reports whether the published source copy and runtime-home copy are in sync.
+- `tools/bin/workflow-catalog.sh`
+  Lists workflows, shows workflow details, or prints available profile ids.
+- `tools/bin/render-flow-config.sh`
+  Prints the effective operator/runtime config after environment overrides.
+- `tools/bin/run-codex-task.sh`
+  Routes the shared worker contract into the backend-specific session wrapper.
+- `tools/bin/agent-project-run-codex-session`
+  Launches Codex-backed worker sessions.
+- `tools/bin/agent-project-run-claude-session`
+  Launches Claude-backed worker sessions.
+- `tools/bin/agent-project-run-openclaw-session`
+  Launches OpenClaw-backed worker sessions.
+- `tools/bin/agent-project-run-opencode-session`
+  Placeholder adapter stub for the planned `opencode` backend.
+- `tools/bin/agent-project-run-kilo-session`
+  Placeholder adapter stub for the planned `kilo` backend.
+- `tools/bin/project-init.sh`
+  Runs scaffold + smoke + adopt + runtime sync for one installed profile.
+- `tools/bin/scaffold-profile.sh`
+  Scaffolds a new installed profile, profile notes, and prompt templates in the
+  local profile registry.
+- `tools/bin/project-runtimectl.sh`
+  Provides `status`, `start`, `stop`, and `restart` for one installed profile.
+- `tools/bin/project-launchd-bootstrap.sh`
+  Syncs the runtime copy and runs one profile-scoped heartbeat pass in a
+  launchd-safe foreground process for the runtime supervisor.
+- `tools/bin/install-project-launchd.sh`
+  Installs a per-user LaunchAgent for one installed profile so its runtime can
+  come back automatically after reboot/login.
+- `tools/bin/uninstall-project-launchd.sh`
+  Removes the per-project LaunchAgent wrapper and plist for one installed
+  profile.
+- `tools/bin/project-remove.sh`
+  Removes one installed profile plus ACP-owned runtime state, with optional
+  purge of ACP-managed repo/worktree/workspace paths.
+- `tools/bin/profile-smoke.sh`
+  Validates available profiles and catches session/branch prefix collisions
+  before scheduler use.
+- `tools/bin/test-smoke.sh`
+  Runs the main shared-package smoke gates in one operator-facing command.
+- `tools/bin/render-dashboard-snapshot.py`
+  Emits a JSON snapshot of active runs, resident controllers, cooldown state,
+  queue depth, and scheduled issues across installed profiles.
+- `tools/bin/serve-dashboard.sh`
+  Serves the live worker dashboard and `/api/snapshot.json` endpoint for local
+  browser-based monitoring.
+- `tools/bin/dashboard-launchd-bootstrap.sh`
+  Syncs the runtime copy and launches the dashboard server in a launchd-safe
+  foreground process.
+- `tools/bin/install-dashboard-launchd.sh`
+  Installs and bootstraps a per-user LaunchAgent so the dashboard returns after
+  reboot/login.
+- `tools/bin/profile-adopt.sh`
+  Creates runtime roots, installs the selected profile into the local profile
+  registry when needed, and syncs the anchor repo plus VS Code workspace for
+  live scheduler adoption.
+- `references/`
+  Control-plane docs, operator commands, and repository maps.
+
+## What Does Not Live Here
+
+- Repo-specific product code.
+- Local scheduler bootstrap and operator docs that belong to a particular
+  workstation. Those now live under:
+  `~/.agent-runtime/control-plane/workspace`
+
+## Vendored Runtime
+
+- Runtime engines are resolved from the current skill root first, then the
+  shared/runtime canonical copies when present, while active project profiles
+  are resolved from `~/.agent-runtime/control-plane/profiles/`.
+- Project-specific instructions should be loaded from the active profile's
+  `README.md` and templates instead of being hardcoded into the shared engine.
+
+## Published Artifacts
+
+- Source canonical package copy:
+  `$SHARED_AGENT_HOME/skills/openclaw/agent-control-plane`
+- Runtime canonical package copy:
+  `~/.agent-runtime/runtime-home/skills/openclaw/agent-control-plane`
+
+Published artifacts are rebuilt by `tools/bin/sync-shared-agent-home.sh` as
+concrete copied files, not symlink aliases. Canonical profile configs now live
+outside the repo in `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`.
+
+## Operational Rule
+
+When updating the control plane:
+
+1. Change the generic engine in this repo or the selected installed profile in the external registry.
+2. Keep workstation wrappers thin.
+3. Repair shared/runtime published copies with `tools/bin/sync-shared-agent-home.sh`.
+4. Prefer explicit profile docs and copied artifacts over hidden defaults and
+   symlink aliases.

package/references/docs-map.md

@@ -0,0 +1,73 @@
+# Docs Map
+
+Canonical documentation sources inside `agent-control-plane`:
+
+## Shared Control-Plane Docs
+
+- `SKILL.md`
+  Shared operating rules and startup sequence.
+- `README.md`
+  Public-facing install, usage, funding, contributing, and security entrypoint.
+- `CHANGELOG.md`
+  Public release history for the package and repository.
+- `ROADMAP.md`
+  Public product and backend-support roadmap, including current and planned
+  worker integrations.
+- `references/architecture.md`
+  Architecture walkthrough with system, runtime, worker, and dashboard diagrams.
+- `CONTRIBUTING.md`
+  Contributor workflow, legal model, and maintainer expectations.
+- `CLA.md`
+  Contributor license agreement used for incoming changes.
+- `CODE_OF_CONDUCT.md`
+  Community behavior and moderation expectations.
+- `SECURITY.md`
+  Security reporting path and disclosure expectations.
+- `references/control-plane-map.md`
+  Ownership map for profiles, scripts, publication copies, and operator tools.
+- `references/commands.md`
+  Control-plane operator commands and profile-management entrypoints.
+- `references/release-checklist.md`
+  Maintainer release checklist for public package publishing.
+- `.github/release-template.md`
+  Reusable markdown template for GitHub release notes.
+- `.github/workflows/ci.yml`
+  Public CI workflow used for the README status badge.
+- `.github/workflows/publish.yml`
+  Trusted npm publishing workflow used for tag-driven releases with provenance.
+- `references/repo-map.md`
+  Layout of the control-plane repository itself.
+
+## Profile-Scoped Docs
+
+- `~/.agent-runtime/control-plane/profiles/<id>/README.md`
+  Canonical repo-specific startup docs, repo roots, command map, and
+  high-risk notes.
+- `~/.agent-runtime/control-plane/profiles/<id>/control-plane.yaml`
+  Canonical machine-readable installed profile config.
+- `~/.agent-runtime/control-plane/profiles/<id>/templates/*.md`
+  Canonical prompt overrides for issue, PR fix, PR review, or scheduled issue flows.
+
+## Runtime and Publication Docs
+
+- `tools/bin/flow-runtime-doctor.sh`
+  Sync health for source and runtime copies.
+- `tools/bin/profile-smoke.sh`
+  Installed-profile validation before scheduler use.
+- `tools/bin/profile-adopt.sh`
+  Local workstation adoption helper.
+- `tools/bin/sync-shared-agent-home.sh`
+  Publication repair for shared/runtime copies.
+- `tools/bin/render-dashboard-demo-media.sh`
+  Regenerates the README dashboard screenshot and animated walkthrough from a
+  real local demo fixture.
+- `tools/bin/render-architecture-infographics.sh`
+  Regenerates the architecture infographic PNGs and PDF deck from the local
+  HTML source in `tools/architecture/`.
+
+## Rule of Thumb
+
+If a piece of guidance is specific to one repo, keep it in
+`~/.agent-runtime/control-plane/profiles/<id>/README.md` or
+`~/.agent-runtime/control-plane/profiles/<id>/templates/` instead of the shared
+control-plane docs.

package/references/release-checklist.md

@@ -0,0 +1,67 @@
+# Release Checklist
+
+Maintainer checklist for shipping a new public package release of
+`agent-control-plane`.
+
+## Pre-Release
+
+- confirm `git status` is clean
+- confirm `package.json` version is intentional
+- review `CHANGELOG.md` and prepare release notes from
+  `.github/release-template.md`
+- refresh README demo media if the dashboard UI changed:
+  `bash tools/bin/render-dashboard-demo-media.sh`
+- review `README.md`, `SECURITY.md`, `CONTRIBUTING.md`, and `CLA.md` for stale
+  links or policy text
+- if a public GitHub repo now exists, set or verify the `homepage`,
+  `repository`, and `bugs` URLs in `package.json`
+- make sure sponsor links still point to the intended maintainer identity
+- confirm the intended license is still `MIT`
+
+## Verification
+
+Run the core checks:
+
+```bash
+bash tools/tests/test-package-public-metadata.sh
+bash tools/tests/test-package-funding-metadata.sh
+bash tools/tests/test-contribution-docs.sh
+bash tools/tests/test-agent-control-plane-npm-cli.sh
+bash tools/bin/test-smoke.sh
+npm pack --dry-run
+```
+
+## Publish
+
+Recommended release flow uses npm trusted publishing from GitHub Actions, so you
+do not have to enter an OTP during every local publish.
+
+One-time setup:
+
+- configure `agent-control-plane` for npm trusted publishing from
+  `ducminhnguyen0319/agent-control-plane`
+- verify the publish workflow file is `.github/workflows/publish.yml`
+- keep npm package publishing policy on the stricter setting you want after
+  trusted publishing is working
+
+Per-release command flow:
+
+```bash
+npm version <patch|minor|major>
+git push origin main --follow-tags
+```
+
+Then:
+
+- watch `.github/workflows/publish.yml` for the npm publish run
+- create or update a GitHub release using `.github/release-template.md`
+- update `CHANGELOG.md` if the final shipped notes differ from the draft
+
+## Post-Release
+
+- verify `npx agent-control-plane@latest help` works from a clean shell
+- verify the npm package shows provenance for the new version
+- verify `npm fund` shows the expected sponsor link
+- verify the repo README, sponsor button, and package metadata all point to the
+  same maintainer identity
+- announce the release where relevant

package/references/repo-map.md

@@ -0,0 +1,36 @@
+# Repository Map
+
+This file maps the `agent-control-plane` repository itself.
+
+## Core Layout
+
+- `SKILL.md`
+  Shared operating manual for the control plane.
+- `assets/`
+  Workflow catalog and static non-profile assets.
+- `bin/`
+  Queue, label, and risk scripts shared by installed profiles.
+- `hooks/`
+  Heartbeat and reconcile hooks shared by installed profiles.
+- `tools/bin/`
+  Runtime wrappers, onboarding helpers, publication utilities, and doctor tools.
+- `tools/templates/`
+  Generic fallback prompts used when a profile does not override a template.
+- `tools/tests/`
+  Shell regression coverage for control-plane behavior.
+- `references/`
+  Control-plane docs, operator commands, and repository maps.
+
+## Operator Surfaces
+
+- `tools/bin/render-flow-config.sh`
+  Effective config viewer for the selected profile.
+- `tools/bin/profile-smoke.sh`
+  Installed-profile validation and collision detection.
+- `tools/bin/profile-adopt.sh`
+  Local runtime/bootstrap helper for onboarding a profile onto a workstation.
+- `tools/bin/sync-shared-agent-home.sh`
+  Publication repair for shared/runtime copies.
+
+Installed profiles live outside this repo under
+`~/.agent-runtime/control-plane/profiles/<id>/`.

package/tools/bin/test-smoke.sh

@@ -13,13 +13,14 @@ Run the main smoke gates for the shared agent-control-plane package in one comma
 
 Steps:
   1. check-skill-contracts.sh
-  2. tools/tests/test-profile-smoke.sh
-  3. tools/tests/test-project-runtimectl.sh
+  2. profile-smoke.sh against a temporary scaffolded profile registry
+  3. project-runtimectl.sh status against a temporary scaffolded profile
 
 Environment overrides:
   ACP_TEST_SMOKE_CHECK_CONTRACTS_SCRIPT
-  ACP_TEST_SMOKE_PROFILE_TEST_SCRIPT
-  ACP_TEST_SMOKE_RUNTIMECTL_TEST_SCRIPT
+  ACP_TEST_SMOKE_PROFILE_SMOKE_SCRIPT
+  ACP_TEST_SMOKE_RUNTIMECTL_SCRIPT
+  ACP_TEST_SMOKE_SCAFFOLD_PROFILE_SCRIPT
 EOF
 }
 
@@ -31,8 +32,9 @@ while [[ $# -gt 0 ]]; do
 done
 
 check_contracts_script="${ACP_TEST_SMOKE_CHECK_CONTRACTS_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/check-skill-contracts.sh}"
-profile_test_script="${ACP_TEST_SMOKE_PROFILE_TEST_SCRIPT:-${FLOW_SKILL_DIR}/tools/tests/test-profile-smoke.sh}"
-runtimectl_test_script="${ACP_TEST_SMOKE_RUNTIMECTL_TEST_SCRIPT:-${FLOW_SKILL_DIR}/tools/tests/test-project-runtimectl.sh}"
+profile_smoke_script="${ACP_TEST_SMOKE_PROFILE_SMOKE_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/profile-smoke.sh}"
+runtimectl_script="${ACP_TEST_SMOKE_RUNTIMECTL_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/project-runtimectl.sh}"
+scaffold_profile_script="${ACP_TEST_SMOKE_SCAFFOLD_PROFILE_SCRIPT:-${FLOW_SKILL_DIR}/tools/bin/scaffold-profile.sh}"
 
 run_step() {
   local label="${1:?label required}"
@@ -57,7 +59,56 @@ run_step() {
 }
 
 run_step "check-skill-contracts" bash "${check_contracts_script}"
-run_step "test-profile-smoke" bash "${profile_test_script}"
-run_step "test-project-runtimectl" bash "${runtimectl_test_script}"
+
+run_profile_smoke_fixture() (
+  set -euo pipefail
+  local tmpdir=""
+  local profile_home=""
+
+  tmpdir="$(mktemp -d)"
+  trap 'rm -rf "${tmpdir}"' EXIT
+  profile_home="${tmpdir}/profiles"
+
+  bash "${scaffold_profile_script}" \
+    --profile-home "${profile_home}" \
+    --profile-id smoke-alpha \
+    --repo-slug example/smoke-alpha >/dev/null
+
+  ACP_PROFILE_REGISTRY_ROOT="${profile_home}" \
+    bash "${profile_smoke_script}" --profile-id smoke-alpha >/dev/null
+)
+
+run_runtimectl_fixture() (
+  set -euo pipefail
+  local tmpdir=""
+  local profile_home=""
+  local runtime_root=""
+  local profile_id="smoke-runtime"
+  local output=""
+
+  tmpdir="$(mktemp -d)"
+  trap 'rm -rf "${tmpdir}"' EXIT
+  profile_home="${tmpdir}/profiles"
+  runtime_root="${tmpdir}/runtime/${profile_id}"
+
+  bash "${scaffold_profile_script}" \
+    --profile-home "${profile_home}" \
+    --profile-id "${profile_id}" \
+    --repo-slug example/${profile_id} \
+    --agent-root "${runtime_root}" \
+    --agent-repo-root "${runtime_root}/repo" \
+    --worktree-root "${runtime_root}/worktrees" >/dev/null
+
+  output="$(
+    ACP_PROFILE_REGISTRY_ROOT="${profile_home}" \
+      bash "${runtimectl_script}" status --profile-id "${profile_id}"
+  )"
+
+  grep -q "^PROFILE_ID=${profile_id}\$" <<<"${output}"
+  grep -q '^RUNTIME_STATUS=' <<<"${output}"
+)
+
+run_step "profile-smoke" run_profile_smoke_fixture
+run_step "project-runtimectl" run_runtimectl_fixture
 
 printf 'SMOKE_TEST_STATUS=ok\n'