acpus 0.0.1 → 0.0.2

package/README.md

@@ -5,25 +5,28 @@
 <h1 align="center">Acpus</h1>
 <p align="center" font-style="italic">Every run is an opus.</p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/acpus"><img src="https://img.shields.io/npm/v/acpus?label=npm" alt="npm version"></a>
+  <a href="https://github.com/kelvinschen/acpus/actions/workflows/publish.yml"><img src="https://img.shields.io/github/actions/workflow/status/kelvinschen/acpus/publish.yml?label=publish" alt="Publish workflow status"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/npm/l/acpus?label=license" alt="License"></a>
+  <img src="https://img.shields.io/node/v/acpus?label=node" alt="Node version">
+</p>
+
+> [!WARNING]
+> Acpus is currently in alpha. CLI/runtime interfaces will change frequently.
+
 Acpus is a runtime-driven workflow orchestrator for ACP agents, built on the acpx agent runtime. You hand it a *workflow spec*; Acpus validates it, compiles a deterministic execution plan, conducts heterogeneous fanout across lanes, and tracks every run as a numbered, replayable execution, or say, an *opus*.
 
 ## Quick Start
 
 ```bash
-# Install
 npm install -g acpus
 
-# Validate a workflow spec
-acpus validate --spec workflows/examples/simple-feature.workflow.spec.json
+acpus plan workflows/examples/simple-feature.workflow.spec.yaml
 
-# Preview the execution plan
-acpus preview --spec workflows/examples/simple-feature.workflow.spec.json
+acpus run workflows/examples/simple-feature.workflow.spec.yaml
 
-# Run the workflow
-acpus run --spec workflows/examples/simple-feature.workflow.spec.json
-
-# Follow a running workflow in real time
-acpus follow <logical-run-id>
+acpus monitor
 ```
 
 ## Skill
@@ -34,39 +37,49 @@ npx skills add kelvinschen/acpus --skill acpus
 
 ## Commands
 
-Acpus commands are grouped by four verbs.
+Acpus commands are grouped by workflow phase. Optional parameters are shown in brackets.
 
-### Compose — validate, preview, save, generate
+### Compose — plan, save
 
-| Command | Purpose |
-|---|---|
-| `acpus validate --spec <path>` | Validate a workflow spec against the schema |
-| `acpus preview --spec <path>` | Render the compiled execution plan without running |
-| `acpus save <name> --spec <path>` | Save a spec to the local store |
-| `acpus generate` | Scaffold a new workflow spec from a template |
+| Command | Options | Purpose |
+|---|---|---|
+| `acpus plan <spec>` | `--global`, `--quiet`, `--json` | Validate a spec file or saved workflow name and preview the compiled execution plan |
+| `acpus save <name> <spec>` | `--overwrite`, `--global`, `--json` | Save a workflow spec to the workflow store |
+
+`plan --json` emits a structured plan preview for automation. `save --json` emits `{ok, workflow, path}` so scripts can capture the saved workflow path.
 
 ### Conduct — run, follow, monitor, resume
 
-| Command | Purpose |
-|---|---|
-| `acpus run --spec <path>` | Execute a workflow spec end-to-end |
-| `acpus follow <run-id>` | Attach to a running workflow and stream output |
-| `acpus monitor <run-id>` | Open the terminal UI for run inspection |
-| `acpus resume <run-id>` | Resume an interrupted or failed run from last checkpoint |
+| Command | Options | Purpose |
+|---|---|---|
+| `acpus run [spec]` | `--global`, `--input <json-or-yaml-or-path>`, `--wait`, `--json` | Prepare and start a workflow from a spec file or saved workflow name |
+| `acpus follow [run]` | `--json` | Select or attach to a run and stream events in real time |
+| `acpus monitor [run]` | `--json` | Select or open a run in the terminal UI, or print the monitor view as JSON |
+| `acpus monitor detail <run> <task-id>` | `--json` | Show bounded detail for one stage task |
+| `acpus resume <run>` | `--allow-partial-fanout <stage...>`, `--max-fanout-items <stage=count...>`, `--skip-fanout-item <stage=index...>`, `--force`, `--wait`, `--json` | Resume a blocked or failed run, or recover a stale running/pending run with `--force` |
 
-### Recover — recover, diagnose
+`--input` accepts an inline JSON object or a JSON/YAML file path, for example `--input input.yaml`.
 
-| Command | Purpose |
-|---|---|
-| `acpus recover <run-id>` | Attempt automatic repair of a failed run |
-| `acpus diagnose <run-id> [--wait]` | Produce a structured diagnosis of a completed or running run |
+<figure align="center">
+  <img src="page/img/monitor_basic.webp" alt="Acpus monitor TUI — real-time run inspection with stage progress, lane status, and event stream" width="720">
+  <br>
+  <sup><em>Real-time run inspection — stages, lanes, and the event stream at a glance.</em></sup>
+</figure>
 
 ### Catalogue — list, show
 
+| Command | Options | Purpose |
+|---|---|---|
+| `acpus list workflows` | `--global`, `--json` | List saved workflows |
+| `acpus list runs` | `--json` | List project runs |
+| `acpus show workflow <name>` | `--global`, `--json` | Display a saved workflow |
+| `acpus show run <id>` | `--json` | Display a run by logical run id or run directory |
+
+### Internal
+
 | Command | Purpose |
 |---|---|
-| `acpus list` | List saved specs and historical runs |
-| `acpus show <id>` | Display details of a saved spec or past run |
+| `acpus _run-worker <run>` | Hidden background worker entry point used by `run` and `resume`; not intended for direct use |
 
 ## Architecture
 
@@ -74,7 +87,7 @@ Acpus sits between the author and the acpx runtime. The main agent produces a *w
 
 Run directories live under `.acpus/runs/<id>/`. Each contains:
 
-- `workflow.spec.json` — the original workflow spec
+- `workflow.spec.yaml` — the original workflow spec
 - `execution-plan.json` — the compiled plan
 - `input.json` — resolved inputs at launch time
 - `outputs/` — stage outputs and final artefacts