@elmundi/ship-cli 0.11.2 → 0.12.0

package/lib/commands/help.mjs

@@ -1,85 +1,140 @@
 export function printHelp() {
-  console.log(`Ship CLI — artifacts protocol on ship.elmundi.com (or SHIP_API_BASE) + init.
+  console.log(`shipctl — adopt Ship in a repo, sync the catalog, run lanes, report Runs.
 
-ARTIFACTS PROTOCOL (RFC-0001)
-  1) shipctl search <query>          — vector search (POST /search) over docs + prompts
-  2) shipctl docs fetch <path>       — full markdown body by repo-relative path
-     shipctl pattern|tool|collection show|fetch <id>
-                                     — versioned artifact body (POST /fetch { kind, id, version? })
-  3) shipctl docs feedback …         — improvement / retro note (POST /feedback)
+Bootstrap a new or existing repo (init / new / doctor), pull the
+methodology catalog into .ship/cache (sync), execute one-shot lanes or
+emit prompts for the workspace runner (run / lanes / kickoff /
+callback). Talks to the methodology + orchestration APIs over HTTPS.
 
-Every consumed artifact should be recorded in the PR as \`<kind>:<id>@<version>\`.
+VOCABULARY
+  lanes:   (.ship/config.yml)  → operator console: Automations
+  pattern: (artifact kind)     → operator console: Plays
+  pipeline_runs (DB / API)     → operator console: Runs
+  attention surface            → operator console: Inbox
 
-COMMANDS
-  shipctl help
-  shipctl search <query> [--top-k N]
-
-  shipctl docs fetch <repo-relative-path>
-  shipctl docs feedback --title "..." --summary "..." [--recommendation "…"]... [--source-context "…"]
-
-  shipctl pattern list | shipctl pattern show <id> | shipctl pattern fetch <id> | shipctl pattern search <query> [--top-k N]
-  shipctl tool … | shipctl collection …   (same subcommands; plural aliases: patterns, tools, …)
-
-  shipctl init [--yes] [--force] [--dry-run] [--json] [--cwd <dir>]
-               [--agents <csv>]
-               [--tracker <name>] [--ci <name>] [--preset <name>]
-               [--language <name>] [--channel stable|edge]
-               [--copy-rules] [--copy-playbook] [--bootstrap]
-               [--telemetry on|off|ask]
-
-  shipctl doctor [--json] [--cwd <dir>] [--write-inventory] [--no-network]
-                                     — inspect the repo, propose a stack, optionally write
-                                       .ship/inventory.json for 'shipctl init --bootstrap'.
-
-  shipctl config init|get|set|validate|show|path     — .ship/config.yml management
-  shipctl sync [--check-only] [--only <kind:id>...] [--channel <c>] [--force-unpin]
-               [--dry-run] [--lock] [--json]
-                                     — fetch artifacts into .ship/cache. With --lock,
-                                       also writes .ship/shipctl.lock.json covering every
-                                       pattern the declared lanes depend on (Phase 4).
-
-  shipctl new <name> [--preset ...] [--tracker ...] [--ci ...] [--agents ...] [--here] [--yes]
-                                     — bootstrap a fresh repo: git init + README + .ship/config.yml
-  shipctl verify [--no-network] [--check <id,...>] [--severity warn|error|info] [--json]
-                                     — post-adoption liveness checks (local + config + network)
-  shipctl telemetry status|on|off|show-id|reset-id|flush|export|delete-my-data|buffer
-                                     — opt-in anonymous usage (RFC-0003); default OFF.
-                                       '--scope artifact_usage,improvement_drafts,errors' on 'on'
-                                       '--dry-run' on 'flush'; '--out <file>' on 'export'
-  shipctl feedback draft|list|show|edit|submit|remove
-                                     — local markdown drafts; submit creates a GitHub issue
-                                       via POST /feedback and moves the draft to sent/.
-  shipctl callback --status <ok|fail|cancelled> [--summary "..."] [--metric k=v]...
-                                     — report a pipeline run's terminal status to Ship.
-                                       Used inside workflow.yml 'if: always()' steps;
-                                       reads SHIP_RUN_TOKEN + SHIP_CALLBACK_URL from env.
-  shipctl kickoff [--pattern kickoff] [--version …] [--raw] [--json] [--cwd …]
-                                     — print the kickoff / workload pattern body for piping
-                                       into the customer's agent in CI (see artifacts/patterns/kickoff).
-  shipctl migrate [--dry-run] [--yes] [--json] [--cwd …]
-                                     — upgrade .ship/config.yml from v1 to v2 (lanes-as-config).
-  shipctl run --lane <id> [--trigger event|schedule|manual|once]
-              [--dry-run] [--offline] [--json] [--cwd …]
-              [--ship-run-id …] [--ship-callback-url …] [--ship-run-token …]
-                                     — RFC-0007 entry-point: resolve a lane from
-                                       .ship/config.yml, fetch its pattern, check idempotency,
-                                       emit the prompt, and report the callback.
-  shipctl lanes install [--only <csv>] [--ref <git-ref>] [--owner …] [--repo …]
-                        [--shipctl-version <v>] [--dry-run] [--force] [--json] [--cwd …]
-                                     — generate .github/workflows/ship-<lane>.yml thin
-                                       wrappers that delegate to the reusable run-agent.yml.
-  shipctl lanes list [--json] [--cwd …]
-                                     — print the lane map from .ship/config.yml.
-  shipctl lanes remove [--only <csv>] [--dry-run] [--json] [--cwd …]
-                                     — delete generated ship-<lane>.yml wrappers.
-  shipctl knowledge init [--workspace <id>] [--repo <id|owner/name>] [--only <csv>] [--json]
-                                     — open a PR that seeds .ship/knowledge/*.md starter
-                                       buckets (code-style, ui-runbook). Reads SHIP_API_TOKEN.
-  shipctl bootstrap   (stub)
+The protocol-stable terms (lanes:, pattern:, pipeline_runs) stay
+literal in YAML, CLI flags, and HTTP. Operator-facing prose uses the
+console nouns.
 
 GLOBAL FLAGS
-  --base-url URL   Methodology API (default: SHIP_API_BASE or https://ship.elmundi.com/api/methodology)
-  --json           Machine-readable JSON
+  --base-url URL   Methodology API (default: SHIP_API_BASE or
+                   https://ship.elmundi.com/api/methodology)
+  --json           Machine-readable JSON output where supported
+  --version, -v    Print shipctl version and exit
+  --help, -h       Print this help
+
+COMMANDS
+
+  Setup
+    shipctl init [--yes] [--force] [--dry-run] [--json] [--cwd <dir>]
+                 [--agents <csv>]
+                 [--tracker <name>] [--ci <name>] [--preset <name>]
+                 [--language <name>] [--channel stable|edge]
+                 [--copy-rules] [--copy-playbook] [--bootstrap]
+                 [--telemetry on|off|ask]
+                                       — bootstrap .ship/, fetch artifacts, install
+                                         agent rules in an existing repo.
+    shipctl new <name> [--preset ...] [--tracker ...] [--ci ...] [--agents ...]
+                       [--here] [--yes]
+                                       — bootstrap a fresh repo: git init + README +
+                                         .ship/config.yml.
+    shipctl doctor [--json] [--cwd <dir>] [--write-inventory] [--no-network]
+                                       — inspect the repo, propose a stack, optionally
+                                         write .ship/inventory.json for
+                                         'shipctl init --bootstrap'.
+    shipctl config init|get|set|validate|show|path
+                                       — .ship/config.yml management.
+
+  Catalog
+    shipctl search <query> [--top-k N]
+                                       — vector search over docs + prompts (POST /search).
+    shipctl docs fetch <repo-relative-path>
+    shipctl docs feedback --title "..." --summary "..." [--recommendation "..."]...
+                          [--source-context "..."]
+                                       — fetch markdown bodies; submit improvement /
+                                         retro notes (POST /feedback).
+    shipctl pattern list | shipctl pattern show <id> | shipctl pattern fetch <id>
+                                     | shipctl pattern search <query> [--top-k N]
+                                       — versioned artifact bodies (POST /fetch
+                                         { kind, id, version? }). 'pattern' is the
+                                         protocol-stable artifact kind; in the operator
+                                         console it shows up as a Play.
+    shipctl tool …       | shipctl collection …
+                                       — same subcommands; plural aliases:
+                                         patterns, tools, collections.
+    shipctl sync [--check-only] [--only <kind:id>]... [--channel <c>]
+                 [--force-unpin] [--dry-run] [--lock] [--json] [--cwd <dir>]
+                                       — fetch artifacts into .ship/cache. With --lock,
+                                         also writes .ship/shipctl.lock.json covering
+                                         every pattern the declared lanes depend on.
+
+  Run
+    shipctl trigger --event schedule --repo <id|owner/name> [--workspace <id>] [--json]
+                                       — ask Ship which configured lanes are
+                                         due for the current GitHub trigger.
+    shipctl run --lane <id> [--pattern <id>] [--fanout matrix|sequential|concurrent]
+                [--trigger event|schedule|manual|once]
+                [--dry-run] [--offline] [--json] [--cwd <dir>]
+                [--ship-run-id <uuid>] [--ship-callback-url <url>] [--ship-run-token <jwt>]
+                                       — one-shot dispatch entry point. 'kind: once'
+                                         lanes execute fully here; 'kind: lane / event /
+                                         schedule' lanes are queued for the workspace
+                                         runner via .github/workflows/run-agent.yml.
+                                         Reports its terminal status via the callback URL
+                                         Ship injected into the workflow.
+    shipctl lanes install [--only <csv>] [--ref <git-ref>] [--owner <gh>] [--repo <name>]
+                          [--shipctl-version <v>] [--dry-run] [--force] [--json] [--cwd <dir>]
+    shipctl lanes list   [--json] [--cwd <dir>]
+    shipctl lanes remove [--only <csv>] [--dry-run] [--json] [--cwd <dir>]
+                                       — generate / inspect / delete the
+                                         .github/workflows/ship-<lane>.yml thin wrappers
+                                         that delegate to the reusable run-agent.yml.
+    shipctl kickoff [--pattern <id>] [--version <v>] [--raw] [--json] [--cwd <dir>]
+                                       — print a pattern body for piping into the
+                                         customer's agent in CI.
+    shipctl callback --status <ok|fail|cancelled> [--summary "..."] [--metric k=v]...
+                     [--outcome-text "..."] [--findings-count N] [--severity high=N]...
+                     [--artifact pr:"..."]... [--escalation clarification:"..."]...
+                                       — report a Run's terminal status (and
+                                         RunSummary outcome) back to Ship so it can
+                                         render the outcome row and route any
+                                         escalations into the Inbox.
+
+  Knowledge
+    shipctl knowledge init [--workspace <id>] [--repo <id|owner/name>] [--only <csv>] [--json]
+                                       — compatibility: open a PR that seeds
+                                         .ship/knowledge starter docs.
+    shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]
+                                       — read Ship-owned bucket articles and
+                                         source sync state.
+    shipctl knowledge bootstrap [--workspace <id>] [--repo <id|owner/name>] [--json]
+                                       — post-merge action entry point: analyze
+                                         repo and open generated knowledge PR.
+    shipctl knowledge refresh-intel [--workspace <id>] [--repo <id|owner/name>] [--json]
+                                       — refresh the generated repository-context
+                                         bucket for an activated repo.
+                                         Reads SHIP_API_TOKEN.
+
+  Telemetry & feedback
+    shipctl telemetry status|on|off|show-id|reset-id|flush|export|delete-my-data|buffer
+                                       — opt-in anonymous usage (RFC-0003); default OFF.
+                                         '--scope artifact_usage,improvement_drafts,errors'
+                                         on 'on'; '--dry-run' on 'flush';
+                                         '--out <file>' on 'export'.
+    shipctl feedback draft|list|show|edit|submit|remove
+                                       — local markdown drafts; submit creates a
+                                         GitHub issue via POST /feedback and moves the
+                                         draft to sent/.
+
+  Misc
+    shipctl verify [--no-network] [--check <id,...>] [--severity warn|error|info] [--json]
+                                       — post-adoption liveness checks
+                                         (local + config + network).
+    shipctl migrate [--dry-run] [--yes] [--json] [--cwd <dir>]
+                                       — upgrade .ship/config.yml from v1 to v2
+                                         (lanes-as-config).
+    shipctl bootstrap   (stub)
+    shipctl help                       — show this help.
 
 LOCAL TREE
   pattern / tool / collection list|show|fetch scan
@@ -108,7 +163,12 @@ SUPPORTED AGENTS
   cursor, codex, claude, aider, cline, continue, windsurf, zed,
   gemini, opencode, copilot, cursor-cloud, agents-md, claude-md
 
-For HTTP schemas see artifacts/tools/methodology-api/ARTIFACT.md in the Ship repo.
+REFERENCE
+  Artifacts protocol: RFC-0001 (POST /search, POST /fetch). Every consumed
+  artifact should be recorded in the PR as \`<kind>:<id>@<version>\`.
+  HTTP schemas: artifacts/tools/methodology-api/ARTIFACT.md in the Ship repo.
+  Operator IA (Plays / Automations / Runs / Inbox): RFC-0010.
+
 Package: @elmundi/ship-cli (binary: shipctl).
 `);
 }

package/lib/commands/kickoff.mjs

@@ -25,7 +25,7 @@ USAGE
   shipctl kickoff [--pattern <id>] [--version <semver>] [--raw] [--json] [--cwd <dir>]
 
 DEFAULTS
-  --pattern kickoff
+  --pattern common-kickoff
 
 FLAGS
   --pattern   Catalog pattern id (folder under artifacts/patterns/).
@@ -39,7 +39,7 @@ When .ship/config.yml sets stack.agent.provider, a one-line hint is written
 to stderr so logs show which agent the repo is wired for — unless --json.
 
 EXAMPLE (workflow step)
-  shipctl kickoff --pattern kickoff > kickoff.md
+  shipctl kickoff --pattern common-kickoff > kickoff.md
   # …concatenate workload pattern + kickoff.md into your agent invocation…
 `);
 }
@@ -64,7 +64,7 @@ function resolveMethodologyBase(ctx, config) {
 
 function parseKickoffArgs(rest) {
   const out = {
-    patternId: "kickoff",
+    patternId: "common-kickoff",
     version: null,
     raw: false,
     json: false,

package/lib/commands/knowledge.mjs

@@ -1,25 +1,18 @@
 /**
  * `shipctl knowledge` — manage workspace knowledge buckets.
  *
- * Today this is a thin wrapper around the backend's
- * ``POST /v1/workspaces/{ws}/repos/{repo}/knowledge_seed`` endpoint —
- * the same one the onboarding wizard's step 4 hits. It opens a single
- * PR in the tenant repo that drops starter markdown under
- * ``.ship/knowledge/``:
- *
- *   - ``code-style.md`` — languages, naming, imports, tests, review checklist
- *   - ``ui-runbook.md`` — design-system usage, states, perf budgets
- *
- * The CLI exists so CI pipelines (and re-adoption flows where the UI
- * wizard isn't the natural entry point) can wire the buckets without a
- * browser round-trip.
+ * The canonical knowledge surface is now Ship-owned:
+ * ``knowledge_buckets`` contain ``bucket_articles`` and
+ * ``knowledge_sources`` records where each article came from. The
+ * historical ``init`` command remains as a compatibility wrapper for
+ * starter PRs, while ``bootstrap`` is the GitHub Actions entry point
+ * that opens the generated knowledge PR after wizard seed merge.
  *
  * Usage:
  *
- *   shipctl knowledge init [--workspace <id>] [--repo <id>]
- *                          [--only code-style,ui-runbook]
- *                          [--base-url https://api.ship.example.com]
- *                          [--json]
+ *   shipctl knowledge fetch repository-context --workspace <id>
+ *   shipctl knowledge bootstrap --workspace <id> --repo <id|owner/name>
+ *   shipctl knowledge refresh-intel --workspace <id> --repo <id|owner/name>
  *
  * Auth: bearer token from ``SHIP_API_TOKEN`` (the same env var the
  * console docs describe for CLI sessions minted under Settings →
@@ -70,6 +63,18 @@ export async function knowledgeCommand(ctx, rest) {
     await knowledgeInitCommand(ctx, args);
     return;
   }
+  if (sub === "fetch") {
+    await knowledgeFetchCommand(ctx, args);
+    return;
+  }
+  if (sub === "bootstrap") {
+    await knowledgeBootstrapCommand(ctx, args);
+    return;
+  }
+  if (sub === "refresh-intel" || sub === "refresh-context") {
+    await knowledgeRefreshIntelCommand(ctx, args);
+    return;
+  }
   console.error(
     `Unknown 'shipctl knowledge' subcommand: ${sub}\nRun: shipctl knowledge --help`,
   );
@@ -82,6 +87,11 @@ function printKnowledgeHelp() {
 SUBCOMMANDS
   shipctl knowledge init [--workspace <id>] [--repo <id|owner/name>]
                          [--only <csv>] [--json]
+  shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]
+  shipctl knowledge bootstrap [--workspace <id>] [--repo <id|owner/name>]
+                             [--json]
+  shipctl knowledge refresh-intel [--workspace <id>] [--repo <id|owner/name>]
+                                 [--json]
 
 INIT FLAGS
   --workspace <id>   Workspace UUID. Defaults to the only workspace
@@ -154,9 +164,116 @@ async function knowledgeInitCommand(ctx, args) {
   }
   const files = Array.isArray(result.files) ? result.files : [];
   console.log(
-    `Seeded knowledge buckets for workspace ${workspaceId} / repo ${repoId}:\n` +
+    `Seeded compatibility knowledge files for workspace ${workspaceId} / repo ${repoId}:\n` +
       `  PR #${result.pr_number}: ${result.pr_url}\n` +
       `  Branch: ${result.branch}\n` +
+      `  Files: ${files.join(", ") || "(none)"}\n` +
+      `\nShip-owned repository context is refreshed separately with:\n` +
+      `  shipctl knowledge refresh-intel --workspace ${workspaceId} --repo ${repoId}`,
+  );
+}
+
+async function knowledgeFetchCommand(ctx, args) {
+  const opts = parseFetchArgs(args);
+  const baseUrl = resolveBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const token = requireToken();
+  let workspaceId = opts.workspace;
+  if (!workspaceId) {
+    workspaceId = await resolveSoleWorkspace(baseUrl, token);
+  }
+
+  const [bucket, articles, sources] = await Promise.all([
+    apiGetJson(
+      baseUrl,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/buckets/${encodeURIComponent(opts.slug)}`,
+      token,
+    ),
+    apiGetJson(
+      baseUrl,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/buckets/${encodeURIComponent(opts.slug)}/articles`,
+      token,
+    ),
+    apiGetJson(
+      baseUrl,
+      `/v1/workspaces/${encodeURIComponent(workspaceId)}/buckets/${encodeURIComponent(opts.slug)}/sources`,
+      token,
+    ),
+  ]);
+
+  const result = { bucket, articles, sources };
+  if (ctx.json || opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`${bucket.name} (${bucket.slug})`);
+  console.log(`  scope: ${bucket.scope_kind}  source: ${bucket.source_kind}`);
+  console.log(`  articles: ${Array.isArray(articles) ? articles.length : 0}`);
+  console.log(`  sources: ${Array.isArray(sources) ? sources.length : 0}`);
+  for (const article of Array.isArray(articles) ? articles : []) {
+    console.log(`\n## ${article.title} (${article.slug})`);
+    console.log(String(article.body_md || "").trim());
+  }
+}
+
+async function knowledgeRefreshIntelCommand(ctx, args) {
+  const opts = parseRefreshArgs(args);
+  const baseUrl = resolveBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const token = requireToken();
+  let workspaceId = opts.workspace;
+  if (!workspaceId) {
+    workspaceId = await resolveSoleWorkspace(baseUrl, token);
+  }
+  const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
+  const result = await apiPostJson(
+    baseUrl,
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/intel/harvest`,
+    {},
+    token,
+  );
+  if (ctx.json || opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const where = result.enqueued
+    ? `queued as job ${result.job_id || "(unknown)"}`
+    : `completed inline, intel_id=${result.intel_id || "(none)"}`;
+  console.log(
+    `Repository context refresh for workspace ${workspaceId} / repo ${repoId}: ${where}\n` +
+      `Fetch it with: shipctl knowledge fetch repository-context --workspace ${workspaceId}`,
+  );
+}
+
+async function knowledgeBootstrapCommand(ctx, args) {
+  const opts = parseBootstrapArgs(args);
+  const baseUrl = resolveBaseUrl(opts.baseUrl || ctx.baseUrl);
+  const token = requireToken();
+  let workspaceId = opts.workspace;
+  if (!workspaceId) {
+    workspaceId = await resolveSoleWorkspace(baseUrl, token);
+  }
+  const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
+  const result = await apiPostJson(
+    baseUrl,
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/knowledge/bootstrap`,
+    {},
+    token,
+  );
+  if (ctx.json || opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  const files = Array.isArray(result.files) ? result.files : [];
+  if (result.status === "already_done") {
+    console.log(
+      `Knowledge bootstrap already completed for workspace ${workspaceId} / repo ${repoId}:\n` +
+        `  PR #${result.pr_number || "?"}: ${result.pr_url || "(unknown)"}`,
+    );
+    return;
+  }
+  console.log(
+    `Knowledge bootstrap opened PR #${result.pr_number} for workspace ${workspaceId} / repo ${repoId}:\n` +
+      `  ${result.pr_url}\n` +
       `  Files: ${files.join(", ") || "(none)"}`,
   );
 }
@@ -224,6 +341,83 @@ function parseInitArgs(args) {
   return out;
 }
 
+function parseFetchArgs(args) {
+  const out = parseCommonArgs(args, { slug: null });
+  if (!out.slug) {
+    console.error("Usage: shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]");
+    process.exit(1);
+  }
+  return out;
+}
+
+function parseRefreshArgs(args) {
+  return parseCommonArgs(args, { repo: null });
+}
+
+function parseBootstrapArgs(args) {
+  return parseCommonArgs(args, { repo: null });
+}
+
+function parseCommonArgs(args, extra) {
+  const out = {
+    workspace: null,
+    baseUrl: null,
+    json: false,
+    ...extra,
+  };
+  const copy = [...args];
+  const consume = (flag, key) => {
+    if (copy[0] === flag && copy[1] !== undefined) {
+      copy.shift();
+      out[key] = String(copy.shift());
+      return true;
+    }
+    const p = `${flag}=`;
+    if (copy[0] && copy[0].startsWith(p)) {
+      out[key] = copy[0].slice(p.length);
+      copy.shift();
+      return true;
+    }
+    return false;
+  };
+  while (copy.length) {
+    if (
+      consume("--workspace", "workspace") ||
+      consume("--repo", "repo") ||
+      consume("--base-url", "baseUrl")
+    ) {
+      continue;
+    }
+    if (copy[0] === "--json") {
+      out.json = true;
+      copy.shift();
+      continue;
+    }
+    if (!String(copy[0]).startsWith("-") && "slug" in out && out.slug === null) {
+      out.slug = String(copy.shift());
+      continue;
+    }
+    if (copy[0] === "--help" || copy[0] === "-h") {
+      printKnowledgeHelp();
+      process.exit(0);
+    }
+    console.error(`Unknown flag: ${copy[0]}`);
+    process.exit(1);
+  }
+  return out;
+}
+
+function requireToken() {
+  const token = process.env.SHIP_API_TOKEN || "";
+  if (!token) {
+    console.error(
+      "SHIP_API_TOKEN is required. Mint one at /settings in the Ship console.",
+    );
+    process.exit(1);
+  }
+  return token;
+}
+
 /**
  * @param {string|null|undefined} explicit
  * @returns {string}

package/lib/commands/lanes.mjs

@@ -24,7 +24,13 @@ import path from "node:path";
 import YAML from "yaml";
 
 import { findShipRoot, readConfig } from "../config/io.mjs";
-import { validateConfig, CONFIG_SCHEMA_VERSION } from "../config/schema.mjs";
+import {
+  validateConfig,
+  CONFIG_SCHEMA_VERSION,
+  lanePatterns,
+  lanePrimaryPattern,
+  laneFanout,
+} from "../config/schema.mjs";
 
 const EXIT_OK = 0;
 const EXIT_USAGE = 2;
@@ -41,7 +47,11 @@ const DEFAULT_REUSABLE_REPO = "ship";
 const DEFAULT_REUSABLE_PATH = ".github/workflows/run-agent.yml";
 
 function printHelp() {
-  console.log(`shipctl lanes — manage GitHub Actions caller workflows.
+  console.log(`shipctl lanes — manage GitHub Actions caller workflows for the
+lanes declared in .ship/config.yml (each lane shows up as an
+Automation in the operator console; one Run is recorded per dispatch).
+
+Aliases: shipctl automations <subcmd>  (operator-friendly name; both work)
 
 USAGE
   shipctl lanes install [--only <id,id>] [--ref <git-ref>] [--owner <gh-owner>]
@@ -174,14 +184,25 @@ async function installCmd(ctx, rest) {
 function listCmd(ctx, rest) {
   const args = parseListArgs(rest);
   const { config } = loadConfig(args.cwd);
-  const rows = Object.entries(config.lanes || {}).map(([id, lane]) => ({
-    lane: id,
-    kind: lane.kind,
-    pattern: lane.pattern || null,
-    on: lane.kind === "event" ? lane.on || null : null,
-    cron: lane.kind === "schedule" ? lane.cron || null : null,
-    idempotency_key: lane.kind === "once" ? lane.idempotency?.key || null : null,
-  }));
+  const rows = Object.entries(config.lanes || {}).map(([id, lane]) => {
+    const pats = lanePatterns(lane);
+    return {
+      lane: id,
+      kind: lane.kind,
+      // ``pattern`` keeps the single-string shape for humans/scripts
+      // that eyeball the first pattern; ``patterns`` always lists all
+      // so multi-pattern lanes (RFC-0008 C3.1) surface correctly.
+      pattern: pats[0] || null,
+      patterns: pats,
+      // ``fanout`` resolves to the runtime default (``matrix``) when
+      // the lane doesn't declare one, so the workflow plan step
+      // doesn't have to branch on "is this key missing?" (RFC-0008 C3.2).
+      fanout: laneFanout(lane),
+      on: lane.kind === "event" ? lane.on || null : null,
+      cron: lane.kind === "schedule" ? lane.cron || null : null,
+      idempotency_key: lane.kind === "once" ? lane.idempotency?.key || null : null,
+    };
+  });
   if (ctx.json || args.json) {
     console.log(JSON.stringify({ ok: true, lanes: rows }, null, 2));
     return;
@@ -197,8 +218,12 @@ function listCmd(ctx, rest) {
         : row.kind === "schedule"
           ? `cron ${JSON.stringify(row.cron)}`
           : `once ${row.idempotency_key || ""}`;
+    const patternLabel =
+      row.patterns.length > 1
+        ? `patterns=[${row.patterns.join(", ")}]`
+        : `pattern=${row.pattern || "-"}`;
     console.log(
-      `  ${row.lane.padEnd(28)} kind=${row.kind.padEnd(9)} ${trigger}  (pattern=${row.pattern || "-"})`,
+      `  ${row.lane.padEnd(28)} kind=${row.kind.padEnd(9)} ${trigger}  (${patternLabel})`,
     );
   }
 }

package/lib/commands/manifest-catalog.mjs

@@ -35,10 +35,10 @@ export async function resourceManifestCommand(resource, ctx, args) {
   if (!sub || sub === "help") {
     const plural = pluralFor(spec.fetchKind);
     console.log(`Usage:
-  ship ${resource} list
-  ship ${resource} show <id>
-  ship ${resource} fetch <id> [--version V] [--print]
-  ship ${resource} search <query> [--top-k N]
+  shipctl ${resource} list
+  shipctl ${resource} show <id>
+  shipctl ${resource} fetch <id> [--version V] [--print]
+  shipctl ${resource} search <query> [--top-k N]
 
 With a local Ship tree (cwd or SHIP_REPO): scans artifacts/${plural}/<id>/ARTIFACT.md on disk.
 Otherwise: methodology API (GET /${spec.apiPath}, POST /fetch for fetch, POST /search for search).
@@ -47,7 +47,7 @@ In a Ship workspace (.ship/config.yml), 'fetch' writes the artifact to
 .ship/cache/<kind>/<id>@<version>/ARTIFACT.md and prints a 'cached:' line. Pass
 --print to also echo the body on stdout.
 
-Plural alias: ship ${spec.apiPath} …
+Plural alias: shipctl ${spec.apiPath} …
 
 Global flags: --base-url URL  --json`);
     return;

package/lib/commands/patterns.mjs

@@ -132,15 +132,15 @@ export async function patternCommand(ctx, args) {
   const [sub, ...rest] = args;
   if (!sub || sub === "help") {
     console.log(`Usage:
-  ship pattern list
-  ship pattern show <id>
-  ship pattern fetch <id>
-  ship pattern search <query> [--top-k N]
+  shipctl pattern list
+  shipctl pattern show <id>
+  shipctl pattern fetch <id>
+  shipctl pattern search <query> [--top-k N]
 
 With a local Ship tree (cwd or SHIP_REPO): list/show/fetch scan artifacts/patterns/<id>/ARTIFACT.md on disk.
 Otherwise: methodology API (GET /patterns, POST /fetch for fetch, POST /search for search).
 
-Plural alias: ship patterns …
+Plural alias: shipctl patterns …
 
 Global flags: --base-url URL  --json`);
     return;