@elmundi/ship-cli 0.14.1 → 0.15.3

package/README.md

@@ -1,6 +1,6 @@
 # @elmundi/ship-cli
 
-`shipctl` is the developer workbench for Ship. Product owners should start in the console and docs; use the CLI when you need local repo setup, config validation, artifact sync, agent rule installation, or reproducible diagnostics.
+`shipctl` is the developer workbench for a Ship-connected repo. The console is for the operator; the CLI is for the engineer. It runs locally for setup, sync, validation, and diagnostics — it does not orchestrate workflows, touch workspace state, or write to the audit log. The customer-side CI uses `shipctl trigger` (and the trigger-spawned `shipctl run`) as a thin entry-point that hands work to the workspace runner.
 
 Published package: `@elmundi/ship-cli`. Binary: `shipctl`.
 
@@ -25,11 +25,10 @@ Use `shipctl` to:
 - sync patterns, tools, and collections into `.ship/cache/`;
 - verify local repo wiring in CI or before a PR;
 - inspect detected stack signals with `doctor`;
-- fetch catalog or docs content for agents;
-- draft and submit feedback on artifacts;
-- run technical routines where the repo-level workflow requires it.
+- read workspace knowledge buckets from inside an agent run;
+- draft and submit feedback on catalog artifacts.
 
-Do not use the CLI as the main product onboarding story. The product setup path is workspace → repo → tracker → knowledge → dashboard/Inbox.
+The product setup path is workspace → repo → tracker → knowledge → dashboard/Inbox, all in the console wizard. The CLI does not duplicate that flow.
 
 ## First local setup
 
@@ -60,22 +59,24 @@ shipctl verify
 
 | Command | Use |
 | --- | --- |
-| `shipctl init` | Create config, infer stack, sync selected artifacts, optionally install agent rules. |
-| `shipctl doctor` | Inspect repo signals without changing files unless `--write-inventory` is passed. |
-| `shipctl verify` | Check config, cache, agent rules, generated files, and optional network/provider reachability. |
+| `shipctl doctor` | Cheap repo health checks: agent rule files installed, config valid, lock fresh, network reachable. |
+| `shipctl verify` | Heavier post-adoption checks (artefact contract, marker drift, network/provider reachability). |
 | `shipctl sync` | Refresh catalog artifacts into `.ship/cache/`; `--lock` writes a lockfile. |
-| `shipctl config` | Show, validate, get, and set `.ship/config.yml` fields. |
-| `shipctl pattern|tool|collection` | List, show, fetch, or search artifact bodies. |
-| `shipctl docs fetch` | Fetch documentation content for agent context. |
-| `shipctl knowledge init` | Seed starter `.ship/knowledge/*.md` files where supported. |
-| `shipctl feedback` | Draft and submit artifact or docs feedback. |
-| `shipctl telemetry` | Opt-in usage telemetry controls. |
+| `shipctl config` | `show / validate / get / set / init / path` for `.ship/config.yml`. |
+| `shipctl init` | Bootstrap `.ship/`, fetch artifacts, install agent rules in an existing repo. |
+| `shipctl pattern\|tool\|collection` | List, show, fetch, or search artifact bodies. |
+| `shipctl search` | Vector search over docs + prompts. |
+| `shipctl knowledge fetch` | Read a workspace bucket's articles + sync state (the agent's read path). |
+| `shipctl trigger` | CI entry-point: compute due routines and claim each schedule window in Ship. |
+| `shipctl run` | Spawned per routine by `shipctl trigger`: resolve pattern, fetch a ticket if FSM-staged, launch the agent runtime. |
+| `shipctl feedback` | Local markdown drafts; submit creates a GitHub issue against a cited artifact. |
+| `shipctl telemetry` | Opt-in usage telemetry controls (default OFF). |
 
 Run `shipctl help` and `shipctl <command> --help` for the exact flag surface.
 
 ## Configuration
 
-The CLI reads `.ship/config.yml` from the repo root. It records stack hints, API settings, artifact pins, telemetry preference, cache behavior, and technical routine wiring.
+The CLI reads `.ship/config.yml` from the repo root. It records stack hints, API settings, artifact pins, telemetry preference, cache behavior, and `process.routines` wiring.
 
 See [`../documentation/configuration.md`](../documentation/configuration.md) for the maintained field reference.
 
@@ -131,4 +132,4 @@ npm run shipctl -- help
 npm test --prefix cli
 ```
 
-Catalog commands read `artifacts/**/ARTIFACT.md` directly when run inside this repo. Search and docs fetch still use the configured HTTP API.
+Catalog commands read `artifacts/**/ARTIFACT.md` directly when run inside this repo. Search still uses the configured HTTP API.

package/bin/shipctl.mjs

@@ -1,9 +1,5 @@
 #!/usr/bin/env node
 import { extractGlobalArgv } from "../lib/config.mjs";
-import { docsCommand } from "../lib/commands/docs.mjs";
-import { searchCommand } from "../lib/commands/search.mjs";
-import { patternCommand } from "../lib/commands/patterns.mjs";
-import { resourceManifestCommand } from "../lib/commands/manifest-catalog.mjs";
 import { printHelp } from "../lib/commands/help.mjs";
 import { initCommand } from "../lib/commands/init.mjs";
 import { doctorCommand } from "../lib/commands/doctor.mjs";
@@ -39,31 +35,6 @@ try {
     process.exit(0);
   }
 
-  if (cmd === "search") {
-    await searchCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "docs") {
-    await docsCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "pattern" || cmd === "patterns") {
-    await patternCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "tool" || cmd === "tools") {
-    await resourceManifestCommand("tool", ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "collection" || cmd === "collections") {
-    await resourceManifestCommand("collection", ctx, rest);
-    process.exit(0);
-  }
-
   if (cmd === "init") {
     await initCommand(ctx, rest);
     process.exit(0);
@@ -80,12 +51,6 @@ try {
     process.exit(0);
   }
 
-  if (cmd === "sync") {
-    const { syncCommand } = await import("../lib/commands/sync.mjs");
-    await syncCommand(ctx, rest);
-    process.exit(0);
-  }
-
   if (cmd === "verify") {
     const { verifyCommand } = await import("../lib/commands/verify.mjs");
     await verifyCommand(ctx, rest);
@@ -104,68 +69,27 @@ try {
     process.exit(0);
   }
 
-  if (cmd === "new") {
-    const { newCommand } = await import("../lib/commands/new.mjs");
-    await newCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "bootstrap") {
-    const { bootstrapCommand } = await import("../lib/commands/bootstrap.mjs");
-    await bootstrapCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "callback") {
-    const { callbackCommand } = await import("../lib/commands/callback.mjs");
-    await callbackCommand(ctx, rest);
-    process.exit(0);
-  }
-
   if (cmd === "trigger") {
     const { triggerCommand } = await import("../lib/commands/trigger.mjs");
     await triggerCommand(ctx, rest);
     process.exit(0);
   }
 
-  if (cmd === "kickoff") {
-    const { kickoffCommand } = await import("../lib/commands/kickoff.mjs");
-    await kickoffCommand(ctx, rest);
-    process.exit(0);
-  }
-
   if (cmd === "knowledge") {
     const { knowledgeCommand } = await import("../lib/commands/knowledge.mjs");
     await knowledgeCommand(ctx, rest);
     process.exit(0);
   }
 
-  if (cmd === "process") {
-    const { processCommand } = await import("../lib/commands/process.mjs");
-    await processCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "migrate") {
-    const { migrateCommand } = await import("../lib/commands/migrate.mjs");
-    await migrateCommand(ctx, rest);
-    process.exit(0);
-  }
-
-  if (cmd === "run" || cmd === "agent-run") {
-    // ``agent-run`` is a back-compat alias for ``run`` — older trigger
-    // workflows still spell it that way until they re-seed.
+  if (cmd === "run") {
     const { runCommand } = await import("../lib/commands/run.mjs");
     await runCommand(ctx, rest);
     process.exit(0);
   }
 
-  /* `lanes` is the protocol-stable name; `automations` is the
-   * operator-friendly soft alias. Both dispatch to the same handler
-   * indefinitely — we are not deprecating the original. */
-  if (cmd === "lanes" || cmd === "automations") {
-    const { lanesCommand } = await import("../lib/commands/lanes.mjs");
-    await lanesCommand(ctx, rest);
+  if (cmd === "preflight") {
+    const { preflightCommand } = await import("../lib/commands/preflight.mjs");
+    await preflightCommand(ctx, rest);
     process.exit(0);
   }
 

package/lib/commands/feedback.mjs

@@ -17,7 +17,7 @@ import {
 import { postFeedback } from "../http.mjs";
 import { appendEvent } from "../telemetry/outbox.mjs";
 
-const ALLOWED_KINDS = ["pattern", "tool", "collection", "doc"];
+const ALLOWED_KINDS = ["collection"];
 
 function parseArgs(rest) {
   const out = {

package/lib/commands/help.mjs

@@ -1,167 +1,89 @@
 export function printHelp() {
-  console.log(`shipctl — adopt Ship in a repo, sync the catalog, run routines, report outcomes.
+  console.log(`shipctl — local workbench for a Ship-connected repo.
 
-Bootstrap a new or existing repo (init / new / doctor), pull the
-methodology catalog into .ship/cache (sync), execute one-shot routines or
-emit prompts for the workspace runner (trigger / run / kickoff /
-callback). Talks to the methodology + orchestration APIs over HTTPS.
-
-VOCABULARY
-  process.routines: (.ship/config.yml) → repo-local scheduled/manual work
-  pattern:          (artifact kind)    → cached role/playbook prompt body
-  routine claim:    (Ship API)         → idempotent schedule-window claim
-  attention surface                    → operator console: Inbox
-
-Legacy 'lanes:' configs and '--lane' flags are still accepted as aliases
-so already-seeded repositories keep working while new repos use
-'process.routines'.
+The console is for the operator. The CLI is for the engineer. shipctl
+runs locally for setup, validation, and diagnostics. It does not
+orchestrate workflows, does not touch workspace state, and does not
+write to the audit log. The customer-side CI uses 'shipctl trigger'
+(and the trigger-spawned 'shipctl run') as a thin entry-point that
+hands work to the workspace runner; everything else is local.
 
 GLOBAL FLAGS
-  --base-url URL   Methodology API (default: SHIP_API_BASE or
-                   https://ship.elmundi.com/api/methodology)
+  --base-url URL   Workspace API (default: SHIP_API_BASE or
+                   https://api.ship.elmundi.com)
   --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.
+  Daily-use (local)
     shipctl doctor [--json] [--cwd <dir>] [--write-inventory] [--no-network]
-                                       — inspect the repo, propose a stack, optionally
-                                         write .ship/inventory.json for
-                                         'shipctl init --bootstrap'.
+                                       — cheap repo health checks: agent rule
+                                         files installed, config valid,
+                                         credentials present, network reachable.
+    shipctl verify [--no-network] [--check <id,...>] [--severity warn|error|info] [--json]
+                                       — heavier post-adoption checks
+                                         (config schema, agent rule presence,
+                                         tracker / CI wiring).
     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 routines depend on.
+  Setup
+    shipctl init [--yes] [--force] [--dry-run] [--json] [--cwd <dir>]
+                 [--agents <csv>] [--tracker <name>] [--ci <name>]
+                 [--preset <name>] [--language <name>] [--channel stable|edge]
+                 [--copy-playbook] [--bootstrap]
+                 [--telemetry on|off|ask]
+                                       — bootstrap .ship/ in an existing repo.
+                                         Agent rule files are baked into the
+                                         wizard's seed PR — Phase 2.5 retired
+                                         the local --copy-rules + sync flow.
 
-  Run
-    shipctl trigger --event schedule --repo <id|owner/name> [--workspace <id>] [--json]
-                                       — compute due routines locally, then claim
-                                         the schedule window in Ship.
+  Knowledge (read-only)
+    shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]
+                                       — read a Ship-owned bucket's articles
+                                         and source sync state. Bucket
+                                         authoring + ingestion live server-side;
+                                         this is the agent's read path.
+
+  CI entry-point (used by the seed workflow)
+    shipctl trigger --event schedule [--workspace <id>] [--repo <id|owner/name>] [--json]
+                                       — compute due routines from
+                                         .ship/config.yml and claim each
+                                         schedule window in Ship.
     shipctl run --routine <id> [--dry-run] [--json] [--cwd <dir>]
                                        — execute one routine end-to-end:
-                                         resolve pattern, fetch a ticket
+                                         resolve specialist, fetch a ticket
                                          (if FSM-staged), launch the agent
                                          runtime, exit on terminal status.
-                                         'shipctl agent-run' is a back-compat
-                                         alias.
-    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.
-    shipctl process prompt --state <id> [--ticket-json <json>] [--policies-file <path>]
-                           [--cwd <dir>] [--json]
-                                      — assemble a Process/FSM specialist prompt
-                                        bundle with ticket context, allowed
-                                        transitions, policies, and mandatory
-                                        knowledge-first guardrails.
-    shipctl process tickets --workspace <id> [--query <text>] [--tracker <kind>] [--json]
-                                      — read-only tracker picker for selecting
-                                        ticket context before building a process
-                                        prompt. Does not create, comment, or
-                                        transition tickets.
-
-  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.
+                                         Spawned per routine by 'shipctl trigger'
+                                         in the seed workflow.
 
   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/.
+                                         GitHub issue against the cited artifact
+                                         (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
-  artifacts/<plural>/<id>/ARTIFACT.md on disk when cwd or SHIP_REPO is inside
-  the Ship monorepo (search always uses HTTP).
-
 INIT FLAGS
   --yes              Non-interactive apply (use --dry-run first)
   --force            Replace existing rule blocks and overwrite generated files
   --dry-run          Preview only
   --json             Emit a JSON summary suitable for CI
-  --agents <csv>     Comma-separated agent ids. See list below.
+  --agents <csv>     Comma-separated agent ids (informational; the wizard's
+                     seed PR is the install path now)
   --tracker <name>   Stack tracker: linear|jira|github-issues|azure-boards|clickup|spreadsheet|none
   --ci <name>        Stack CI: gh-actions|gitlab-ci|buildkite|circleci|azure-pipelines|jenkins|manual
   --preset <name>    Stack preset: web-app|api-backend|mobile-app|cli|monorepo|adoption-minimum
   --language <name>  Stack language: ts|js|py|go|rust|java|kotlin|swift|dart|multi
   --channel <name>   Override api.channel: stable|edge
-  --copy-rules       Install collection/agent-rules-<agent> files at their install_target
-  --copy-playbook    Fetch collection/adoption-playbook into .ship/cache/ (skipped on 404)
+  --copy-playbook    (no-op after Phase 2.5; flag retained for back-compat)
   --bootstrap        Render CI/tracker scaffolding (mobile-app+gh-actions+linear skeletons today;
                      other combos emit SHIP_BOOTSTRAP_PLAN.md)
   --telemetry        on|off|ask — override the interactive telemetry prompt
@@ -171,12 +93,6 @@ SUPPORTED AGENTS
   cursor, codex, claude, aider, cline, continue, windsurf, zed,
   gemini, opencode, copilot, cursor-cloud, agents-md, claude-md
 
-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).
 `);
 }