@agent-compose/cli 0.2.2 → 0.3.1

package/README.md

@@ -102,11 +102,14 @@ Claude Code session running inside this repo:
 | Skill | What it does |
 |---|---|
 | `/ac:setup` | Walks first-time setup against an existing server |
-| `/ac:demo` | Guided first-run walkthrough |
+| `/ac:tutorial` | Hands-on tutorial — register, invoke, schedule, emit events, capture snapshots (~10 min) |
 | `/ac:register` | Bundle + register the current workflow |
 | `/ac:invoke` | Dispatch a registered workflow with input |
 | `/ac:register-invoke` | Register-then-invoke combo for fast iteration |
+| `/ac:schedule` | Create / list / delete cron schedules on a registered workflow |
 | `/ac:logs` | Tail logs for a running run |
+| `/ac:events` | Send / list run events |
+| `/ac:snapshots` | List / inspect / delete captured sandbox snapshots |
 | `/ac:secrets` | Manage per-workflow secrets |
 | `/ac:generate-workflow` | Scaffold a new workflow from a plain-English description |
 | `/ac:generate-agent` | Scaffold an agent prompt + iteration logic |

package/dist/index.js

@@ -3,8 +3,8 @@ import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/index.ts
-import { readFileSync as readFileSync5 } from "node:fs";
-import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { readFileSync as readFileSync6 } from "node:fs";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
 import { program } from "commander";
 
 // src/commands/register.ts
@@ -183,7 +183,7 @@ var registerCommand = new Command("register").description("Register a workflow w
     console.error(`Error: workflow not found at ${workflowPath}`);
     process.exit(1);
   }
-  const { source, manifest, networkPolicy, placeholders, snapshots, memory, postRunHooks, inputSchema, outputSchema, workflowPlan } = await bundleWorkflow(workflowPath);
+  const { source, manifest, description, networkPolicy, placeholders, snapshots, memory, postRunHooks, inputSchema, outputSchema, workflowPlan } = await bundleWorkflow(workflowPath);
   if (networkPolicy)
     console.log(`[register] Network policy detected — credentials will be brokered via Vercel firewall`);
   if (snapshots?.bootFrom)
@@ -200,6 +200,7 @@ var registerCommand = new Command("register").description("Register a workflow w
     factorySlug: opts.factory,
     ...opts.version ? { version: opts.version } : {},
     ...opts.schedule ? { schedule: opts.schedule } : {},
+    ...description ? { description } : {},
     ...networkPolicy ? { networkPolicy } : {},
     ...placeholders ? { placeholders } : {},
     ...snapshots !== undefined ? { snapshots } : {},
@@ -1159,14 +1160,95 @@ var listCommand2 = new Command13("list").description("List events for a run, or
 });
 var eventsCommand = new Command13("events").description("Send or list run events (Events API)").addCommand(sendCommand).addCommand(listCommand2);
 
-// src/update-check.ts
+// src/commands/schedule.ts
+import { Command as Command14 } from "commander";
+var sharedOpts2 = (cmd) => cmd.option("--factory <slug>", `Factory the schedule lives in (default: ${defaultFactory})`, defaultFactory).option("--url <url>", "Server URL", parseUrlFlag, defaultUrl).option("--api-key <key>", "API key", defaultApiKey);
+var scheduleCommand = new Command14("schedule").description("Manage cron schedules attached to registered workflows");
+sharedOpts2(scheduleCommand.command("create <name>").description("Create a new schedule for a workflow").requiredOption("--workflow <name>", "The registered workflow this schedule should fire").requiredOption("--cron <expr>", "Cron expression (UTC) — e.g. '0 9 * * *'")).action(async (name, opts) => {
+  const client = makeClient(opts);
+  const created = await client.createSchedule({
+    name,
+    workflow: opts.workflow,
+    cron: opts.cron,
+    factorySlug: opts.factory
+  });
+  console.log(`✓ Schedule "${created.name}" → workflow "${created.workflow}" @ "${created.cron}" (${created.id})`);
+});
+sharedOpts2(scheduleCommand.command("list").description("List schedules in a factory")).action(async (opts) => {
+  const client = makeClient(opts);
+  const rows = await client.listSchedules(opts.factory);
+  if (rows.length === 0) {
+    console.log(`No schedules in factory "${opts.factory}"`);
+    return;
+  }
+  console.log(`Schedules in factory "${opts.factory}":`);
+  for (const s of rows) {
+    const next = s.nextFireAt ? new Date(s.nextFireAt).toLocaleString() : "—";
+    console.log(`  ${s.name.padEnd(24)} ${s.workflowName.padEnd(20)} ${s.cron.padEnd(16)} next: ${next}  ${s.id}`);
+  }
+});
+sharedOpts2(scheduleCommand.command("delete <id>").description("Delete a schedule by id")).action(async (id, opts) => {
+  const client = makeClient(opts);
+  await client.deleteSchedule(id, opts.factory);
+  console.log(`✓ Schedule ${id} deleted from factory "${opts.factory}"`);
+});
+
+// src/commands/upgrade.ts
+import { Command as Command15 } from "commander";
 import { spawnSync } from "node:child_process";
-import { mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync } from "node:fs";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import pc4 from "picocolors";
+var PACKAGE_NAME = "@agent-compose/cli";
+var upgradeCommand = new Command15("upgrade").description("Update the agentc CLI to the latest published version").option("--check", "Check for updates without installing", false).action(async (opts) => {
+  const pkg = JSON.parse(readFileSync4(fileURLToPath2(new URL("../../package.json", import.meta.url)), "utf8"));
+  const current = pkg.version;
+  const controller = new AbortController;
+  const timeout = setTimeout(() => controller.abort(), 5000);
+  let latest = null;
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+      signal: controller.signal,
+      headers: { Accept: "application/json" }
+    });
+    if (res.ok) {
+      const body = await res.json();
+      if (typeof body.version === "string")
+        latest = body.version;
+    }
+  } catch {} finally {
+    clearTimeout(timeout);
+  }
+  if (!latest) {
+    console.error(`${pc4.red("✗")} Couldn't reach the npm registry. Check your connection and try again.`);
+    process.exit(1);
+  }
+  if (latest === current) {
+    console.log(`${pc4.green("✓")} You're on the latest version (${pc4.bold(current)}).`);
+    return;
+  }
+  console.log(`${pc4.yellow("●")} agentc ${pc4.bold(latest)} is available (you have ${current}).`);
+  if (opts.check) {
+    console.log(`  Run ${pc4.cyan("agentc upgrade")} to install, or ${pc4.cyan("npm install -g " + PACKAGE_NAME + "@latest")} manually.`);
+    return;
+  }
+  console.log(`  Running ${pc4.cyan("npm install -g " + PACKAGE_NAME + "@latest")} …`);
+  const result = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], { stdio: "inherit" });
+  if (result.status !== 0) {
+    console.error(`${pc4.red("✗")} Install failed. Run the command above manually, or check for permission issues (npm prefix / sudo).`);
+    process.exit(1);
+  }
+  console.log(`${pc4.green("✓")} Installed ${pc4.bold(`agentc ${latest}`)}.`);
+});
+
+// src/update-check.ts
+import { spawnSync as spawnSync2 } from "node:child_process";
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync5, writeFileSync } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import { join as join3 } from "node:path";
 import { createInterface } from "node:readline/promises";
-import pc4 from "picocolors";
-var PACKAGE_NAME = "@agent-compose/cli";
+import pc5 from "picocolors";
+var PACKAGE_NAME2 = "@agent-compose/cli";
 var CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
 var FETCH_TIMEOUT_MS = 2000;
 function cachePath() {
@@ -1201,7 +1283,7 @@ function isNewer(latest, current) {
 }
 function readCache() {
   try {
-    const raw = readFileSync4(cachePath(), "utf8");
+    const raw = readFileSync5(cachePath(), "utf8");
     const parsed = JSON.parse(raw);
     if (typeof parsed.checkedAt !== "number")
       return null;
@@ -1225,7 +1307,7 @@ async function fetchLatest() {
   const controller = new AbortController;
   const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
   try {
-    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME}/latest`, {
+    const res = await fetch(`https://registry.npmjs.org/${PACKAGE_NAME2}/latest`, {
       signal: controller.signal,
       headers: { Accept: "application/json" }
     });
@@ -1263,35 +1345,35 @@ async function checkForUpdate(currentVersion) {
   const latest = await resolveLatest();
   if (!latest || !isNewer(latest, currentVersion))
     return;
-  const headline = `${pc4.yellow("●")} agentc ${pc4.bold(latest)} is available (you have ${currentVersion}).`;
+  const headline = `${pc5.yellow("●")} agentc ${pc5.bold(latest)} is available (you have ${currentVersion}).`;
   process.stderr.write(`${headline}
 `);
   if (!process.stdin.isTTY) {
-    process.stderr.write(`  Run ${pc4.cyan("npm install -g " + PACKAGE_NAME + "@latest")} to update.
+    process.stderr.write(`  Run ${pc5.cyan("npm install -g " + PACKAGE_NAME2 + "@latest")} to update.
 `);
     return;
   }
-  const confirm = await promptYesNo(`  Install now? [y/${pc4.bold("N")}] `);
+  const confirm = await promptYesNo(`  Install now? [y/${pc5.bold("N")}] `);
   if (!confirm)
     return;
-  process.stderr.write(`  Running ${pc4.cyan("npm install -g " + PACKAGE_NAME + "@latest")} …
+  process.stderr.write(`  Running ${pc5.cyan("npm install -g " + PACKAGE_NAME2 + "@latest")} …
 `);
-  const result = spawnSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+  const result = spawnSync2("npm", ["install", "-g", `${PACKAGE_NAME2}@latest`], {
     stdio: "inherit"
   });
   if (result.status !== 0) {
-    process.stderr.write(`${pc4.red("✗")} Install failed. Run the command above manually.
+    process.stderr.write(`${pc5.red("✗")} Install failed. Run the command above manually.
 `);
     return;
   }
-  process.stderr.write(`${pc4.green("✓")} Installed ${pc4.bold(`agentc ${latest}`)}. ` + `Re-run your command to use the new version.
+  process.stderr.write(`${pc5.green("✓")} Installed ${pc5.bold(`agentc ${latest}`)}. ` + `Re-run your command to use the new version.
 `);
   process.exit(0);
 }
 
 // src/index.ts
-var pkg = JSON.parse(readFileSync5(fileURLToPath2(new URL("../package.json", import.meta.url)), "utf8"));
-program.name("agentc").description("CLI for agent-compose — register, invoke, and monitor workflows").version(pkg.version);
+var pkg = JSON.parse(readFileSync6(fileURLToPath3(new URL("../package.json", import.meta.url)), "utf8"));
+program.name("agentc").description("Coordinate agent production lines.").version(pkg.version);
 program.hook("preAction", async () => {
   try {
     await checkForUpdate(pkg.version);
@@ -1300,14 +1382,34 @@ program.hook("preAction", async () => {
 program.addCommand(registerCommand);
 program.addCommand(invokeCommand);
 program.addCommand(listCommand);
+program.addCommand(cancelCommand);
+program.addCommand(scheduleCommand);
 program.addCommand(logsCommand);
-program.addCommand(initCommand);
+program.addCommand(eventsCommand);
+program.addCommand(factoryCommand);
+program.addCommand(snapshotCommand);
+program.addCommand(secretsCommand);
 program.addCommand(keysCommand);
 program.addCommand(authCommand);
-program.addCommand(secretsCommand);
 program.addCommand(usageCommand);
-program.addCommand(snapshotCommand);
-program.addCommand(factoryCommand);
-program.addCommand(cancelCommand);
-program.addCommand(eventsCommand);
+program.addCommand(initCommand);
+program.addCommand(upgradeCommand);
+program.addHelpText("after", `
+Topics:
+  Workflows         register, invoke, list, cancel
+  Scheduling        schedule
+  Run inspection    logs, events
+  Resources         factory, snapshot, secrets
+  Account           keys, auth, usage
+  Setup             init, upgrade
+
+Examples:
+  $ agentc register ./workflows/pipeline.ts
+  $ agentc invoke pipeline --follow
+  $ agentc schedule create nightly --workflow pipeline --cron '0 9 * * *'
+  $ agentc logs <run-id>
+
+Docs:
+  https://github.com/Layr-Labs/agent-compose
+`);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-compose/cli",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Command-line interface for agent-compose — register, invoke, and monitor workflows from your terminal.",
   "license": "MIT",
   "repository": {
@@ -35,21 +35,21 @@
     "node": ">=20"
   },
   "scripts": {
-    "typecheck":      "tsc --noEmit",
-    "test":           "bun test src/__tests__",
-    "build":          "bun run clean && bun run build:js && bun run build:chmod",
-    "build:js":       "bun build src/index.ts --outdir dist --target node --format esm --packages external --banner='#!/usr/bin/env bun'",
-    "build:chmod":    "chmod +x dist/index.js",
-    "clean":          "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test src/__tests__",
+    "build": "bun run clean && bun run build:js && bun run build:chmod",
+    "build:js": "bun build src/index.ts --outdir dist --target node --format esm --packages external --banner='#!/usr/bin/env bun'",
+    "build:chmod": "chmod +x dist/index.js",
+    "clean": "rm -rf dist",
     "prepublishOnly": "bun run build"
   },
   "dependencies": {
-    "@agent-compose/sdk": "^0.3.0",
-    "commander":          "^12.0.0",
-    "picocolors":         "^1.1.1"
+    "@agent-compose/sdk": "^0.5.0",
+    "commander": "^12.0.0",
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
-    "bun-types":  "latest",
+    "bun-types": "latest",
     "typescript": "^5.8.0"
   },
   "publishConfig": {

package/skills/ac:generate-workflow.md

@@ -44,7 +44,13 @@ about "step-form vs run-form" — that's an internal call.
 6. **Should it run on a schedule?**
    If yes, ask for the cadence in plain English ("every weekday at 9am
    ET", "every hour", "the 1st of every month"). Convert to cron
-   yourself.
+   yourself (UTC). Schedules are *separate from workflow source*: you
+   don't put cron in `defineWorkflow(...)`. After register, run
+   `agentc schedule create <name> --workflow <wf> --cron '<expr>'`
+   (or, for the simple "one cron per workflow" case, pass
+   `--schedule '<expr>'` to `agentc register` and the CLI auto-creates
+   a same-named schedule). Read the cron expression back to the user
+   to confirm.
 
 7. **Anything else worth recording?**
    Optional. Most workflows are fine without this.
@@ -337,6 +343,10 @@ export default defineWorkflow({
    - (If you added a sandbox env companion: "First register the
      `playwright-env` workflow with `--build` so the snapshot is
      captured, then register and invoke `pr-triage`.")
+   - (If the user asked for a schedule at step 6:
+     "To run it on the schedule: `agentc schedule create pr-triage-daily
+     --workflow pr-triage --cron '<expr>'` — the cron pattern we
+     worked out earlier.")
 
 ## When the user asks for memory extraction
 

package/skills/ac:invoke.md

@@ -7,6 +7,13 @@ allowed-tools: Bash(agentc *)
 
 # Invoke Workflow
 
+A one-shot dispatch — the CLI POSTs to `/api/v1/factories/<slug>/templates/<name>/invoke`,
+the server creates a run row, the worker boots a sandbox, and the
+workflow runs. Scheduled runs go through the same dispatch path but
+are triggered by a cron tick instead; they're tagged with
+`_scheduleId` + `_scheduleName` on metadata so the dashboard shows
+"schedule by <name>" on the row. This skill is the manual path.
+
 ## Context
 
 Registered workflows:
@@ -18,7 +25,8 @@ Registered workflows:
 
 The user wants to invoke: **$ARGUMENTS**
 
-If the line above is blank, ask which workflow to invoke. Use the registered workflows list above as suggestions.
+If `$ARGUMENTS` is empty, ask which workflow to invoke. Use the
+registered workflows list above as suggestions.
 
 Once you have the workflow name, dispatch it:
 
@@ -26,17 +34,31 @@ Once you have the workflow name, dispatch it:
 agentc invoke <name> --follow
 ```
 
+Common extra flags:
+- `--input '{"k":"v"}'` — JSON input matching the workflow's `inputSchema`.
+- `--factory <slug>` — invoke into a non-default factory.
+- `--snapshot <snap_…>` — per-invocation `bootFrom` override (per `/ac:snapshots`).
+
 ## Output
 
 Stream events as they arrive. When complete, report:
-- Final outcome (success / failed)
-- Final wall time (`run_complete` includes elapsed seconds)
-- Any PR URL, plan URL, or artifact produced (visible in the streamed events
-  or via `agentc logs <run-id>` after the fact)
+- Final outcome (success / failed / cancelled / abandoned)
+- Wall time (`run_complete` includes elapsed seconds)
+- Any PR URL, plan URL, or artifact emitted (visible in the streamed
+  events or via `agentc logs <run-id>` after the fact)
 
 ## Next Steps
 
-- **Success** → Report the outcome and any output.
-- **Failed** → Show the failure reason. Offer to debug: "Run `/ac:logs <run-id>` for the full event log."
-- **Secrets missing** → "Run `/ac:secrets set <workflow> <KEY> <value>` to configure the required secret."
-- **Template not found** → "Run `/ac:register <workflow.ts>` to register it first."
+- **Success** → Report outcome + any output emitted.
+- **Failed** → Show the failure reason. Offer `/ac:logs <run-id>` for
+  the full event stream.
+- **Secrets missing** → "Run `/ac:secrets set <workflow> <KEY> <value>`
+  to configure the required secret."
+- **Template not found** → "Run `/ac:register <workflow.ts>` to
+  register it first."
+- **Snapshot missing (`bootFrom` 503)** → The snapshot id this
+  workflow boots from was deleted. List captured snapshots
+  (`/ac:snapshots`) and update the workflow's `snapshots: { bootFrom }`
+  with a current id, then re-register.
+- **Want it to run on a schedule?** → `/ac:schedule create <name>
+  --workflow <wf> --cron '<expr>'`.

package/skills/ac:register-invoke.md

@@ -7,22 +7,59 @@ allowed-tools: Bash(agentc *)
 
 # Register and Invoke
 
-Register the workflow at `$0`, then invoke it.
+Bundle + register a workflow, then dispatch it once and stream the run.
+Tight inner-loop for verifying source-level changes against the server.
+
+## Instructions
+
+The user passed: **$ARGUMENTS**
+
+If `$ARGUMENTS` is empty, ask for the workflow file path before
+proceeding.
+
+Parse out the workflow file (first positional arg, ends in `.ts`).
+Anything after it (`--input`, `--factory`, etc.) is passed through to
+`agentc invoke`.
 
 ## Plan
 
 ```bash
-agentc register $0
-agentc invoke $(basename "$0" .ts) --follow $1
+# Register the file:
+agentc register <workflow.ts>
+
+# Then invoke it by name (basename minus .ts) and stream:
+agentc invoke <workflow-name> --follow [...invoke flags]
+```
+
+If the user wants the workflow to run on a schedule instead of (or in
+addition to) the one-shot test, suggest `/ac:schedule create` AFTER the
+register completes — schedules live independently of register/invoke
+and shouldn't be mixed into this iteration loop.
+
+For the shorthand path (one schedule per workflow, named after the
+workflow), pass `--schedule '<cron>'` to `agentc register`:
+
+```bash
+agentc register <workflow.ts> --schedule '0 9 * * *'
 ```
 
-If `$ARGUMENTS` is empty, ask for the workflow path first.
+That creates + reconciles the schedule at register time; you still
+need a manual `agentc invoke` to test it without waiting for the next
+tick.
 
 ## Output
 
-Show register output, then stream the run. When complete, report outcome and any artifacts.
+Show register output, then stream the run live. When complete, report:
+- Final outcome (success / failed / abandoned)
+- Wall time (from `run_complete`)
+- Any PR URL, plan URL, or artifact emitted along the way
 
 ## Next Steps
 
-- **Registration failed** → Fix the error and re-run.
-- **Run failed** → Show failure reason from the final event. Offer `/ac:logs <run-id>`.
+- **Registration failed** → Re-read the bundler / validator error.
+  Usually a missing import path, malformed `defineWorkflow(...)`, or a
+  manifest mismatch. Fix and re-run.
+- **Run failed** → Show failure reason from the final event. Offer
+  `/ac:logs <run-id>` for the full event stream.
+- **Need a schedule** → `/ac:schedule create <name> --workflow <wf>
+  --cron '<expr>'` after this completes.

package/skills/ac:register.md

@@ -36,7 +36,10 @@ Confirm:
 
 ## Next Steps
 
-- **Success** → "Registered. Run `/ac:invoke <name>` to test it."
+- **Success** → "Registered. Run `/ac:invoke <name>` to test it.
+  Want it on a schedule? `/ac:schedule create <name> --workflow <wf>
+  --cron '<expr>'` (or pass `--schedule '<expr>'` next time you
+  register for the auto-shorthand)."
 - **Bundle failed** → Re-read the bundler error; usually a missing import path
   or a runtime that couldn't be resolved.
 - **Validation error** → Fix the reported issue in the source file and re-run.

package/skills/ac:schedule.md

@@ -0,0 +1,132 @@
+---
+name: ac:schedule
+description: Create, list, and delete cron schedules attached to registered workflows.
+argument-hint: <create|list|delete> [args]
+allowed-tools: Bash(agentc *)
+---
+
+# Schedules
+
+Cron schedules attached to a registered workflow. A workflow can have N
+named schedules with distinct cadences; each tick dispatches a fresh
+run tagged with the schedule's id + name so the dashboard attributes
+the run to its trigger and filters Runs by schedule.
+
+> **Mental model.** A schedule is a `(name, workflow, cron)` triple
+> scoped to a factory. Names are unique per factory; ids are stable
+> across re-registers (which makes "show me every run this schedule
+> ever fired" work even when the target template gets new versions).
+> Schedules are independent of workflow lifecycle — deleting a schedule
+> doesn't touch the workflow, deleting a workflow cascades to its
+> schedules.
+
+## Context
+
+Registered workflows:
+```
+!`agentc list 2>/dev/null | awk '{print $1}'`
+```
+
+Existing schedules:
+```
+!`agentc schedule list 2>/dev/null`
+```
+
+## Plan
+
+Based on `$ARGUMENTS`:
+
+| Arguments | Action |
+|---|---|
+| `create <name> --workflow <wf> --cron <expr>` | Create a schedule |
+| `list` | List schedules in the active factory |
+| `delete <id>` | Delete a schedule by id |
+| *(none)* | Ask which subcommand and walk through args |
+
+### Create
+
+```bash
+agentc schedule create <name> --workflow <wf> --cron '<expr>'
+```
+
+- `<name>` — kebab-case, unique per factory (e.g. `nightly-triage`).
+- `--workflow <wf>` — must be a registered workflow in the same factory.
+- `--cron '<expr>'` — UTC, standard 5-field cron. Quote it (shells eat
+  the wildcards otherwise). Common patterns:
+  - `'0 9 * * *'` — daily at 09:00 UTC
+  - `'*/15 * * * *'` — every 15 minutes
+  - `'0 * * * 1-5'` — hourly on weekdays
+- `--factory <slug>` — pin to a specific factory (default: active).
+
+Read `--cron` aloud back to the user to confirm — the symbol soup
+hides bugs. If unsure, use `cronstrue` (the dashboard renders the
+human form on the Schedules tab).
+
+### List
+
+```bash
+agentc schedule list
+agentc schedule list --factory my-factory
+```
+
+Output is one row per schedule:
+
+```
+<name>  <workflow>  <cron>  next: <ISO>  <schedule-id>
+```
+
+The dashboard's `/factories/<slug>/workflows` → **Schedules** tab is
+the richer view: human cadence (cronstrue), next/last fire times,
+delete button, click-through to the Runs view filtered by schedule.
+
+### Delete
+
+```bash
+agentc schedule delete <schedule-id>
+```
+
+Confirm with the user first — "Delete schedule `<name>`? It will stop
+firing immediately; existing runs are unaffected." Schedule ids come
+from `agentc schedule list` or the dashboard.
+
+## Shorthand on register
+
+`agentc register <file> --schedule '<cron>'` auto-creates a schedule
+**named after the workflow** at register time. Useful when a workflow
+has exactly one cadence and you don't need a separate name:
+
+```bash
+agentc register pipeline.ts --schedule '0 9 * * *'
+# → registers "pipeline" + creates schedule "pipeline" at 09:00 UTC
+```
+
+Re-registering with the same cron is a no-op; changing the cron
+updates the existing schedule's row. Drop `--schedule` (or pass
+`null`) to clear the auto-shorthand schedule. Schedules created via
+`agentc schedule create` with a different name are left alone.
+
+For workflows with multiple cadences (e.g. weekday + weekend), use
+`agentc schedule create` explicitly — the register shorthand only
+manages a single same-name schedule.
+
+## Filtering runs
+
+Every run dispatched by a schedule carries `_scheduleId` +
+`_scheduleName` on its metadata. The dashboard's Schedules tab makes
+the schedule name a link straight into a filtered Runs view; the
+chip on each row links back. From the CLI, the metadata is visible
+on `agentc logs <run-id>` and via the SDK's `getRunById`.
+
+## Next Steps
+
+- **Schedule created** → "Wait for the first tick (next fire shown in
+  `agentc schedule list`); the dispatched run shows up in the dashboard
+  Runs view with a `schedule by <name>` link."
+- **`workflow "..." not found`** → Register the target template first
+  (`/ac:register <file.ts>`) — schedules can only target workflows
+  that already exist.
+- **`schedule "..." already exists`** → Name collision. Either use
+  `agentc schedule delete <id>` first or pick a new name.
+- **Schedule never fires** → Check the workflow's `bootFrom`
+  (`/ac:snapshots`) — runs against a missing snapshot fail at
+  dispatch. The schedule still ticks; only the workflow run fails.

package/skills/ac:setup.md

@@ -86,6 +86,9 @@ This lists registered workflows. If it returns without error, setup is complete.
 
 > "You're all set. Here's what you can do now:"
 >
-> - `/ac:demo` — watch AI agents build a browser game end-to-end
+> - `/ac:tutorial` — hands-on walkthrough of register, invoke, schedule, events, and snapshots (~10 min)
 > - `agentc invoke <workflow> --follow` — run any registered workflow
 > - `/ac:generate-workflow` — build your own workflow from a description
+> - `/ac:schedule create <name> --workflow <wf> --cron '<expr>'` — fire
+>   a workflow on a cron schedule (each tick shows up in the Runs view
+>   with a `schedule by <name>` link)

package/skills/ac:tutorial.md

@@ -0,0 +1,375 @@
+---
+name: ac:tutorial
+description: Hands-on tutorial — register, invoke, schedule, emit events, capture snapshots. ~10 minutes against a running stack.
+effort: high
+allowed-tools: Bash(agentc *) Bash(git *) Bash(open *) Read Write Edit
+---
+
+# Tutorial — agent-compose
+
+A hands-on walkthrough of every surface that matters. Builds one tiny
+workflow and uses it to demonstrate the five things you'll actually
+care about in production:
+
+1. **Author + register** a workflow.
+2. **Invoke** it and watch the run live.
+3. **Schedule** it to fire on a cron.
+4. **Emit events** from inside the workflow + inspect them.
+5. **Snapshot** the sandbox state + boot another workflow from it.
+
+Should take ~10 minutes against the hosted server (a bit longer
+locally — the runner sandbox boots fresh each time).
+
+## Pre-flight
+
+```
+!`agentc auth status`
+```
+
+If the line above shows no API key, run `/ac:setup` first.
+
+## Mental model
+
+Three primitives. Read once, refer back when something doesn't make
+sense:
+
+> **Workflow** — the unit of work you author. Two shapes:
+> `async (ctx, sandbox) => T` (run-form, single body) or
+> `defineWorkflow({...}).step(s1).step(s2).build()` (step-form, typed
+> pipeline). This tutorial uses run-form because it's the smaller
+> mental load; step-form is the right shape when the work decomposes
+> into typed phases.
+
+> **Agent loop** — `agent({ runtime, prompt, ... })`. Lives inside the
+> workflow body. Drives one iteration of an LLM agent against the
+> runner sandbox until the model emits `exit_signal: true` or hits
+> the budget.
+
+> **Runtime** — `claudeRuntime` (built-in, wraps the Claude CLI).
+> `openAIDesktopRuntime` (computer-use). Write your own with
+> `defineRuntime`.
+
+Everything else — schedules, events, snapshots, secrets — wraps these
+three.
+
+## Step 1 — Scaffold
+
+Create `hello-agent.ts` next to where the user wants to work. Walk
+them through the file before writing — point at `ctx`, `sandbox`,
+`agent`, the prompt, the tool allowlist, the budget, and the
+`ctx.reportEvent` call (we'll use that in step 4). Confirm before
+saving.
+
+```ts
+// hello-agent.ts
+import { defineWorkflow, agent, claudeRuntime } from "@agent-compose/sdk";
+
+const PROMPT = `
+You're verifying agent-compose is wired up correctly.
+
+Run \`echo "hello from sandbox $(hostname)"\` once, then emit a
+<status> block with a summary describing what you observed and
+exit_signal: true.
+`;
+
+export default defineWorkflow({
+  async run(ctx, sandbox) {
+    const result = await agent({
+      sandbox,
+      runtime: claudeRuntime,
+      prompt:  PROMPT,
+      tools:   ["Bash"],
+      budget:  { turnsPerIteration: 6, maxIterations: 1 },
+    });
+
+    // Emit a custom event so step 4 has something to inspect.
+    await ctx.reportEvent("tutorial.verified", {
+      summary: result.status?.summary ?? "(no summary)",
+      attributes: { completed: !!result.status?.completed },
+    });
+
+    return { ok: !!result.status?.completed, summary: result.status?.summary };
+  },
+});
+```
+
+## Step 2 — Register and invoke
+
+```bash
+agentc register hello-agent.ts
+agentc invoke hello-agent --follow
+```
+
+> "The CLI bundles the workflow source + the runtime source via
+> `bundleWorkflow`, then POSTs to `/api/v1/factories/<slug>/templates`.
+> The server creates a runner sandbox, drops the bundle in, and starts
+> Node. Inside, our workflow runs `agent` once — Claude spawns, runs
+> the bash command, emits its `<status>`, and exits. Server marks the
+> run complete; the CLI prints elapsed time and the final outcome."
+
+Watch the SSE-streamed events live — point out:
+- `step_started` / `step_completed` (timeline phases).
+- `agent_event` lines (model output streaming live).
+- `event_reported` for the `tutorial.verified` event we emitted (step 4
+  picks this up).
+- `run_complete` with elapsed time.
+
+Copy the run id from the final output — needed for step 4.
+
+## Step 3 — Schedule it
+
+Schedules fire your workflow on a cron. Names are unique per factory
+and stable across re-registers, so historical runs stay attributed
+even when the target template gets new versions.
+
+```bash
+agentc schedule create hello-every-2min \
+  --workflow hello-agent \
+  --cron '*/2 * * * *'
+```
+
+Wait two minutes, then list runs (or open the dashboard's Runs view):
+
+```bash
+agentc list                                  # registered templates
+# In the dashboard, /factories/<slug>/workflows → Schedules tab shows
+# `hello-every-2min` with the cadence in plain English and the next
+# fire time. Clicking the name filters Runs to just this schedule.
+```
+
+When you're done, clean up:
+
+```bash
+agentc schedule list                         # find the id
+agentc schedule delete <schedule-id>
+```
+
+> "Schedules are independent of the workflow — deleting a schedule
+> doesn't touch the template, deleting the template cascades to its
+> schedules. A workflow can have N named schedules for different
+> cadences (weekday vs weekend, hourly vs daily, etc)."
+
+## Step 4 — Inspect events
+
+`ctx.reportEvent(...)` inside the workflow body emits structured
+events the dashboard timeline renders, downstream workflows subscribe
+to, and analytics queries scan. List the events on the run we did in
+step 2:
+
+```bash
+agentc events list <run-id>
+```
+
+You should see `tutorial.verified` with the summary we emitted.
+
+Send a synthetic event from the CLI to verify the write path (useful
+for testing downstream subscribers without re-running the workflow):
+
+```bash
+agentc events send <run-id> tutorial.poke \
+  --body '{"source":"tutorial"}' \
+  --summary "manual poke from /ac:tutorial"
+```
+
+List again — `tutorial.poke` is now there too.
+
+> "Events are idempotent on `(run, name, idempotency-key)`, propagate
+> to subscribers, and live in the same timeline as lifecycle events.
+> Production workflows emit them via `ctx.reportEvent` — the CLI form
+> is for testing + verification."
+
+## Step 5 — Snapshots
+
+A snapshot is the on-disk state of a runner VM at the end of a
+successful step. Other workflows boot from it instead of running
+their own setup. Useful for:
+
+- Pre-baked sandbox environments (Claude CLI installed, deps fetched,
+  caches warm).
+- Re-running a workflow with the same starting state every time.
+
+For the tutorial, capture one from the next `hello-agent` run by
+adding `snapshots: { saveLatest: true }` to the workflow:
+
+```ts
+export default defineWorkflow({
+  snapshots: { saveLatest: true },              // ← add this
+  async run(ctx, sandbox) { /* unchanged */ },
+});
+```
+
+Re-register and invoke:
+
+```bash
+agentc register hello-agent.ts
+agentc invoke hello-agent --follow
+```
+
+After the run completes, list captured snapshots:
+
+```bash
+agentc snapshot list --workflow hello-agent
+```
+
+Copy the `snap_…` id. Now author a *second* workflow that boots from
+it instead of starting from a blank sandbox:
+
+```ts
+// hello-consumer.ts
+import { defineWorkflow } from "@agent-compose/sdk";
+
+export default defineWorkflow({
+  snapshots: { bootFrom: { snapshotId: "snap_PASTE_ID_HERE" } },
+  async run(ctx, sandbox) {
+    const result = await sandbox.commands.run("ls -la /home/user");
+    return { listing: result.stdout };
+  },
+});
+```
+
+```bash
+agentc register hello-consumer.ts
+agentc invoke hello-consumer --follow
+```
+
+`hello-consumer` starts in the exact state `hello-agent` left the
+sandbox in — same files, same processes, same env. No setup re-runs.
+
+> "Snapshot ids are the unit of identity. There's no 'latest of
+> workflow X' resolution at dispatch time — operators pick an id from
+> `agentc snapshot list` (or the dashboard's snapshots page) and
+> paste it. Deleting a snapshot makes any workflow referencing it 503
+> at dispatch; the consuming workflow needs to be re-registered with
+> a different id."
+
+## Step 6 — From your own code (SDK)
+
+Everything you just did with the CLI is also available programmatically
+via `@agent-compose/sdk`. The CLI is a thin wrapper around the same
+`AgentComposeClient` — what you see in `agentc <verb>` is what your
+backend code does. Useful for:
+
+- Triggering workflows from another service (webhook handlers, queue
+  consumers, internal dashboards).
+- Listing runs / schedules from your own admin UI.
+- Wiring agent-compose into a CI pipeline without shelling out to
+  `agentc`.
+
+Install it as a dependency of the calling project (it's a public npm
+package):
+
+```bash
+npm install @agent-compose/sdk     # or bun add @agent-compose/sdk
+```
+
+Construct a client with an API key (mint one in the dashboard's
+Settings → API Keys; the CLI uses the same shape):
+
+```ts
+import { AgentComposeClient } from "@agent-compose/sdk";
+
+const client = new AgentComposeClient({
+  baseURL: process.env.AGENTC_URL ?? "http://localhost:8080",
+  apiKey:  process.env.AGENTC_API_KEY!,     // ac_…
+});
+```
+
+> "The SDK is Bearer-authed (Authorization: ac_…). It's the same
+> entry point the CLI uses — `agentc invoke foo` is literally
+> `client.invoke('foo', …)`. Browser code talks to the server via a
+> cookie-bound dashboard-internal fetch wrapper instead, but that's
+> a dashboard-only seam; server-to-server is the SDK."
+
+### Invoke a workflow + wait for the result
+
+```ts
+// Fire-and-forget — returns a runId you can stream later.
+const { runId } = await client.invoke("hello-agent", { input: {} });
+
+// Block until the run settles, return the typed output:
+const result = await client.invokeAndWait<{ ok: boolean; summary?: string }>(
+  "hello-agent",
+  { input: {}, timeoutMs: 120_000 },
+);
+console.log(result.outcome, result.output?.summary);
+```
+
+### Schedules (matches `agentc schedule …`)
+
+```ts
+const schedules = await client.listSchedules();          // → ScheduleRow[]
+await client.createSchedule({
+  name:     "nightly",
+  workflow: "hello-agent",
+  cron:     "0 9 * * *",                                 // UTC
+});
+await client.deleteSchedule(scheduleId);
+```
+
+### Events (matches `ctx.reportEvent` inside the workflow + `agentc events`)
+
+```ts
+// Read what a run emitted:
+const events = await client.listRunEvents(runId);
+
+// Or factory-wide (audit / cross-workflow analytics):
+const recent = await client.listFactoryEvents({ limit: 200 });
+
+// Send a synthetic event into a run from outside:
+await client.reportEvent(runId, {
+  name:    "deploy.completed",
+  summary: "deploy to prod succeeded",
+  body:    { sha: "abc123" },
+});
+```
+
+### Snapshots (matches `agentc snapshot list`)
+
+```ts
+const captured = await client.listSnapshots({ workflowName: "hello-agent" });
+const perRun   = await client.listRunSnapshots(runId);
+```
+
+To boot another workflow from a captured snapshot, set
+`snapshots: { bootFrom: { snapshotId: "snap_…" } }` in
+`defineWorkflow(...)` — same shape the CLI's register step writes.
+
+### Stream a run's logs
+
+```ts
+for await (const line of client.streamRunLogs(runId)) {
+  console.log(`[${line.stream}] ${line.line}`);
+}
+```
+
+The full set of methods is on `AgentComposeClient` — the same surface
+the dashboard playground and `/ac:logs` skill use. See the SDK's
+[`README`](../../sdk/README.md) for the type-checked reference.
+
+## Step 7 — Where to go next
+
+> "You've now used every primitive. To go further:"
+>
+> - `/ac:generate-workflow` — describe a multi-phase workflow in
+>   plain English; Claude scaffolds the file with `agent` blocks per
+>   phase and the right input/output schemas.
+> - `/ac:generate-agent` — scaffold one agent loop's prompt + snippet
+>   to slot into an existing workflow.
+> - `/ac:secrets` — wire up brokered network secrets (GCP Secret
+>   Manager → injected at the Vercel firewall).
+> - `/ac:schedule` — the dedicated schedules walkthrough.
+> - `/ac:snapshots` — list, inspect, delete captured snapshots.
+> - `/ac:events` — full events reference.
+> - Read [`docs/how-it-works.md`](../../docs/how-it-works.md) for the
+>   multi-agent example (plan + parallel implementers).
+
+## Cleanup
+
+```bash
+agentc schedule delete <hello-every-2min-id>   # if you created one
+agentc snapshot delete <run-id> <snap-id>      # if you captured one
+rm hello-agent.ts hello-consumer.ts            # local files
+```
+
+Or keep them as references — registered templates stay in the team
+factory until you `agentc factory ...` them out.

package/skills/ac:demo.md

@@ -1,138 +0,0 @@
----
-name: ac:demo
-description: First-run walkthrough — verify auth, scaffold a sample workflow, register it, invoke, and watch the agent run live.
-effort: high
-allowed-tools: Bash(agentc *) Bash(git *) Bash(open *) Read Write Edit
----
-
-# Demo — agent-compose
-
-A guided first-run walkthrough. Verify auth, generate a tiny sample
-workflow, register it, dispatch it, and watch a single agent loop run
-end-to-end. Should take ~5 minutes against the hosted server (a bit
-longer locally — the runner sandbox boots fresh).
-
-## Context
-
-```
-!`agentc auth status`
-```
-
-If the line above shows no API key, run `/ac:setup` first (sign in to
-the dashboard, mint an `ac_…` key, `agentc auth login <key>`). That
-skill walks the full bootstrap.
-
-## Steps
-
-### 1. Briefly explain the model
-
-Make sure the user understands the three primitives before you start
-typing. Keep it brief — they can read [`docs/how-it-works.md`](../../docs/how-it-works.md)
-for the full version.
-
-> **Workflow** — the unit of work you author. Two shapes are valid:
-> a single `async (ctx, sandbox) => T` body (run-form, agent-driven)
-> or a typed pipeline of `defineStep(...)` objects composed with
-> `defineWorkflow({...}).step(s1).step(s2).build()` (step-form). The
-> demo below uses run-form because the body is a single agent loop;
-> step-form is the right shape when the work decomposes into phases
-> with typed handoffs.
-
-> **Agent loop** — `agent({ runtime, prompt, ... })`. Embedded inside
-> the workflow body. Drives one iteration cycle of an LLM agent against
-> the runner sandbox until the model emits `exit_signal: true` (or
-> hits the iteration budget).
-
-> **Runtime** — `claudeRuntime` (built-in) wraps the Claude CLI.
-> `openAIDesktopRuntime` wraps OpenAI computer-use. You can write your
-> own with `defineRuntime`.
-
-### 2. Scaffold a sample workflow
-
-Create a temporary `hello-agent.ts` next to where the user wants to
-work. Keep it minimal — one phase, no fancy plumbing:
-
-```ts
-// hello-agent.ts
-import { defineWorkflow, agent, claudeRuntime } from "@agent-compose/sdk";
-
-const PROMPT = `
-You're verifying agent-compose is wired up correctly.
-
-Run \`echo "hello from sandbox $(hostname)"\` once, then emit a
-<status> block with summary describing what you observed and
-exit_signal: true.
-`;
-
-export default defineWorkflow({
-  async run(ctx, sandbox) {
-    const result = await agent({
-      sandbox,
-      runtime: claudeRuntime,
-      prompt:  PROMPT,
-      tools:   ["Bash"],
-      budget:  { turnsPerIteration: 6, maxIterations: 1 },
-    });
-    await ctx.setMetadata({ summary: result.status?.summary });
-    return { ok: !!result.status?.completed, summary: result.status?.summary };
-  },
-});
-```
-
-Walk the user through the file — point at `ctx`, `sandbox`,
-`agent`, the prompt, the tool allowlist, the budget. Confirm before
-writing.
-
-### 3. Register
-
-```bash
-agentc register hello-agent.ts
-```
-
-> "The CLI bundles the workflow source + the runtime source via
-> `bundleWorkflow`, then POSTs to `/api/v1/templates`. Once registered,
-> anyone with an `invoke`-scoped API key can call it."
-
-### 4. Invoke and watch live
-
-```bash
-agentc invoke hello-agent --follow
-```
-
-> "The server creates a runner sandbox, drops the bundle in, and starts
-> Node. Inside the sandbox, our workflow runs `agent` once — Claude
-> spawns, runs the bash command, emits its `<status>`, and exits.
-> Server marks the run complete; the CLI prints the final outcome and
-> elapsed time."
-
-Watch the SSE-streamed events together — point out:
-- `step_started` / `step_completed` (timeline phases).
-- `agent_event` lines (model output streaming live).
-- `run_complete` with elapsed time.
-
-### 5. Browse the run in the dashboard
-
-Once the run finishes, open the run detail page:
-
-```bash
-# pull the dashboard URL from auth status; substitute the run id
-open "$(agentc auth status | awk '/^Dashboard:/ {print $2}')/workflows/<run-id>"
-```
-
-The dashboard shows the same lifecycle events plus the captured
-artifacts (logs, metadata) the workflow emitted.
-
-### 6. What to build next
-
-> "That was the simplest possible workflow. To go further:"
->
-> - `/ac:generate-workflow` — describe a multi-phase workflow in plain
->   English; Claude scaffolds the full file with `agent` blocks per phase.
-> - `/ac:generate-agent` — scaffold one phase's prompt + `agent` snippet
->   to slot into an existing workflow.
-> - `/ac:generate-runtime` — write a custom runtime for a model the SDK
->   doesn't ship.
-> - Read [`docs/how-it-works.md`](../../docs/how-it-works.md) for the
->   multi-agent example (plan + parallel implementers).
-
-Clean up: `rm hello-agent.ts` (or keep it as a reference).