@swarmcraftai/cli 0.7.0 → 0.7.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,16 @@
2
2
 
3
3
  All notable changes to the SwarmCraft CLI are documented in this file.
4
4
 
5
+ ## 0.7.2
6
+
7
+ - Simplifies the npm README and consolidates detailed workflow and provider guidance into their owning references.
8
+ - Command behaviour and help are unchanged from 0.7.1.
9
+
10
+ ## 0.7.1
11
+
12
+ - Adds account-independent project guidance and packet upgrades with preview, saved-provider preservation, conflict reporting, and recoverable writes.
13
+ - Adds `swarmcraft upgrade` and detailed, side-effect-free help for every command.
14
+
5
15
  ## 0.7.0
6
16
 
7
17
  - Upgrades Operate to schema-based records and refreshed Work, Automate, Formalise, Import, and Handbook guidance.
package/README.md CHANGED
@@ -7,7 +7,7 @@ The CLI brings SwarmCraft workflows to your terminal. Use it to prepare a local
7
7
  ## Prerequisites
8
8
 
9
9
  - Node.js 20.19 or newer, npm, and Git.
10
- - A SwarmCraft account and a project with tasks ready to implement.
10
+ - For board-driven runs: a SwarmCraft account and a project with tasks ready to implement.
11
11
  - A local Git repository with unrelated changes committed or stashed.
12
12
  - Codex CLI, GitHub Copilot CLI, or Claude Code CLI installed and configured, or SwarmCraft Managed AI credits.
13
13
 
@@ -87,6 +87,20 @@ swarmcraft init --project <project-id> --workspace . --agent-provider codex
87
87
 
88
88
  `init` writes guidance and task files for review and leaves those changes uncommitted. Commit or otherwise resolve them before starting a run that requires a clean workspace. Updates preserve your edits to generated guidance and report conflicts that need attention.
89
89
 
90
+ ## Update repository guidance
91
+
92
+ For an existing project repository, preview the update before applying it:
93
+
94
+ ```bash
95
+ swarmcraft upgrade --workspace . --check
96
+ swarmcraft upgrade --workspace .
97
+ ```
98
+
99
+ This works offline, preserves your saved provider and local edits, and reports conflicts.
100
+ Review `git diff` before committing. Use `init` for first-time project setup and
101
+ `swarmcraft operate upgrade --help` for an Operate repository.
102
+ See the [project upgrade walkthrough](https://swarmcraft.ai/docs/build-and-ship/deliver-with-the-one-shot-cli).
103
+
90
104
  ## Choose an agent
91
105
 
92
106
  - **Claude Code subscription:** use `--agent-provider claude` after local Claude sign-in.
@@ -114,6 +128,11 @@ If a run reached its request limit, raise the total ceiling when resuming:
114
128
  swarmcraft resume --run <run-id> --workspace . --max-agent-requests 200
115
129
  ```
116
130
 
131
+ An already seeded repository and its packet skills remain usable with your own
132
+ assistant without an ongoing SwarmCraft account. Packet work and review can finish
133
+ locally. Hosted one-shot orchestration and Managed AI still require sign-in; optional
134
+ board syncing is provided by the SwarmCraft extension when connected.
135
+
117
136
  ## Other workflows
118
137
 
119
138
  For local operational work, initialize Work, Automate, and Formalise skills:
@@ -149,62 +168,3 @@ Run `swarmcraft auth login` again if your session has expired. For Discovery dia
149
168
  Support bundles redact credentials; Discovery bundles exclude source and package content. Review any diagnostic files before sharing them.
150
169
 
151
170
  See the [one-shot walkthrough](https://swarmcraft.ai/docs/build-and-ship/deliver-with-the-one-shot-cli), [troubleshooting guide](https://swarmcraft.ai/docs/help-and-reference/troubleshoot-swarmcraft), or [contact support](https://swarmcraft.ai/login?next=%2Fapp%2Fsupport).
152
-
153
- ### Claude Code subscription runs
154
-
155
- Select `--agent-provider claude` for bootstrap, Operate, or one-shot. Install the
156
- standalone Claude Code CLI, run `claude auth login`, and confirm subscription
157
- usage in `/status`. The VS Code extension alone does not install the terminal
158
- command. SwarmCraft checks the effective `claude.ai` login without retaining
159
- its output and rejects provider credential flags on this subscription path.
160
-
161
- One-shot invokes `/swarmcraft-do` and `/swarmcraft-check` with `dontAsk`:
162
- configure the necessary tool permissions in Claude before running; unapproved
163
- tools are denied. The default never enables permission bypass or API-only bare
164
- mode. Claude keeps ownership of login storage and sandbox settings. Use
165
- `--max-agent-requests` to bound invocations; subscription limits still apply.
166
- Cost telemetry remains unknown unless an explicit adapter supplies it; required
167
- cost telemetry fails when absent. Dollar estimates are not subscription bills.
168
- After correcting login, permissions, or a usage limit, resume the recorded run.
169
- Live subscription/platform verification is tracked in the implementation plan.
170
-
171
- `swarmcraft operate rebuild --workspace <path> [--json]` explicitly refreshes the
172
- knowledge index and derived status. It runs local structural and Git-policy inspection,
173
- preserves unrelated staged work, and neither commits nor contacts the API. `operate status`
174
- and `operate validate` remain read-only. A registered private source can be unavailable in
175
- this clone without being an unresolved source identity.
176
-
177
- `swarmcraft operate import --workspace <path> --source-id source.guidance --title "Reference guidance" --timezone Australia/Brisbane --input <file>`
178
- registers evidence locally and preserves a dated original snapshot. Add `--group <label>`
179
- for a confirmed, non-sensitive grouping. Omit `--input` to register an operator statement;
180
- retain the statement in knowledge. Use `--rebuild` without `--input` to regenerate a
181
- registered source's derivative after checking the original digest. New source versions
182
- require new IDs. Markdown/text and DOCX main-body text are supported; other formats
183
- remain registered with retrieval pending. No import command commits or uploads files.
184
-
185
- `swarmcraft operate handbook --workspace <path> --notes knowledge.review --title "Operations handbook" --timezone Australia/Brisbane`
186
- creates a dated Markdown snapshot from explicitly selected reviewed notes. Optional
187
- `--formats html,pdf` detects Pandoc and, for PDF, WeasyPrint. Format failures are recorded
188
- in the edition manifest; completed Markdown remains available. Explicitly reviewed images
189
- use `--reviewed-assets <comma-separated-repository-paths>`. Provisional notes require
190
- `--include-provisional` and remain visibly labelled. Editions preserve earlier runs.
191
-
192
- Exports remain ignored. `--track` declares approval to track this particular handbook;
193
- it does not change ignore rules or commit anything. Review exact edition-file exceptions
194
- before staging. Inspection only permits declared outputs whose bytes match their manifest,
195
- not arbitrary exports beside them. Source notes remain the maintained originals.
196
-
197
- ### Update an existing Operate repository
198
-
199
- Run `swarmcraft operate upgrade --workspace <path> --check` to check compatibility without changes. Run `swarmcraft operate upgrade --workspace <path>` to apply a supported update. Both commands work locally without sign-in or activity reporting.
200
-
201
- Finish your current Work checkpoint first. The upgrade requires clean tracked files and index, creates a pre-upgrade Git commit, validates the migration and managed-file reconciliation, then creates a separate upgrade commit. Nothing is pushed. Ignored and untracked files remain untouched; destination collisions stop the update. Custom skills, unsupported source catalogues and nonempty old rules tables require review before migration.
202
-
203
- Rerun the command after an interruption to recover unchanged upgrade writes and retry. Recovery stops if later edits or Git history changes would be overwritten. A folder without an Operate locator needs first-time adoption rather than migration. See [Use Operate](https://swarmcraft.ai/docs/start-here/use-operate) for the editor workflow.
204
-
205
- For source intake, `operate import --purpose workflow` preserves and registers an original without extracting it. Use `--purpose derived` for a searchable copy; when purpose is unclear, the Import skill selects workflow. To create a searchable copy later, use `--rebuild --purpose derived` with the same source ID and its verified original. Omitting `--purpose` retains the CLI's earlier derived-source behaviour.
206
-
207
- An already seeded repository and its packet skills remain usable with your own
208
- assistant without an ongoing SwarmCraft account. Packet work and review can finish
209
- locally. Hosted one-shot orchestration and Managed AI still require sign-in; optional
210
- board syncing is provided by the SwarmCraft extension when connected.
package/dist/main.cjs CHANGED
@@ -67545,6 +67545,265 @@ var require_upgradeOperation = __commonJS({
67545
67545
  }
67546
67546
  });
67547
67547
 
67548
+ // ../../packages/repo-seed/dist/projectUpgradeContract.js
67549
+ var require_projectUpgradeContract = __commonJS({
67550
+ "../../packages/repo-seed/dist/projectUpgradeContract.js"(exports2) {
67551
+ "use strict";
67552
+ Object.defineProperty(exports2, "__esModule", { value: true });
67553
+ exports2.projectUpgradeExitCode = projectUpgradeExitCode2;
67554
+ function projectUpgradeExitCode2(result) {
67555
+ return result.status === "failed" ? 1 : result.status === "conflict" ? 2 : 0;
67556
+ }
67557
+ }
67558
+ });
67559
+
67560
+ // ../../packages/repo-seed/dist/projectUpgrade.js
67561
+ var require_projectUpgrade = __commonJS({
67562
+ "../../packages/repo-seed/dist/projectUpgrade.js"(exports2) {
67563
+ "use strict";
67564
+ Object.defineProperty(exports2, "__esModule", { value: true });
67565
+ exports2.validateUpgradePath = validateUpgradePath;
67566
+ exports2.inspectProjectUpgradeState = inspectProjectUpgradeState;
67567
+ exports2.previewProjectUpgrade = previewProjectUpgrade2;
67568
+ exports2.applyProjectUpgrade = applyProjectUpgrade2;
67569
+ var packet_workflow_1 = require_dist();
67570
+ var seedProjectFiles_1 = require_seedProjectFiles();
67571
+ function validateUpgradePath(value) {
67572
+ if (!value || value.startsWith("/") || value.includes("\\") || value.includes("\0") || value.split("/").some((p) => !p || p === "." || p === "..") || /^[A-Za-z]:/.test(value))
67573
+ throw new Error("Unsafe repository path");
67574
+ }
67575
+ function inspectProjectUpgradeState(contents) {
67576
+ if (contents === null)
67577
+ throw new Error("Project seed state is missing; use init for initial setup.");
67578
+ const state = JSON.parse(contents);
67579
+ if (state.schemaVersion !== 2 || !Number.isInteger(state.templateSetVersion) || state.templateSetVersion < 0 || !["claude", "codex", "copilot"].includes(state.provider) || !state.files || typeof state.files !== "object" || Array.isArray(state.files))
67580
+ throw new Error("Unsupported or corrupt project seed state.");
67581
+ if (state.templateSetVersion > seedProjectFiles_1.PROJECT_TEMPLATE_SET_VERSION)
67582
+ throw new Error("Project guidance is newer than this client; install a compatible client.");
67583
+ if (state.projectId !== void 0 && (typeof state.projectId !== "string" || !state.projectId.trim()))
67584
+ throw new Error("Invalid saved project identity.");
67585
+ for (const [name, entry] of Object.entries(state.files)) {
67586
+ validateUpgradePath(name);
67587
+ const item = entry;
67588
+ if (!item || !["static", "dynamic"].includes(item.scope ?? "") || !["GENERATED_MANAGED", "CREATE_ONCE_HUMAN", "MANAGED_SECTION", "IMMUTABLE_MACHINE"].includes(item.ownership ?? "") || !/^[a-f0-9]{64}$/.test(item.expectedHash ?? "") || item.provider !== void 0 && item.provider !== state.provider)
67589
+ throw new Error("Invalid seed file ownership or provider metadata.");
67590
+ }
67591
+ return state;
67592
+ }
67593
+ async function previewProjectUpgrade2(files, options) {
67594
+ const result = { protocolVersion: 1, mode: "check", status: "current", sourceVersion: 0, targetVersion: seedProjectFiles_1.PROJECT_TEMPLATE_SET_VERSION, added: [], updated: [], removed: [], migratedPackets: [], preserved: [], contextPreserved: [], conflicts: [], blockers: [], applied: [], failed: [] };
67595
+ const observations = /* @__PURE__ */ new Map();
67596
+ const overlay = /* @__PURE__ */ new Map();
67597
+ const read = async (name) => {
67598
+ validateUpgradePath(name);
67599
+ if (!observations.has(name))
67600
+ observations.set(name, await files.read(name));
67601
+ return observations.get(name);
67602
+ };
67603
+ try {
67604
+ const originalState = await read(seedProjectFiles_1.PROJECT_SEED_STATE_PATH);
67605
+ const state = inspectProjectUpgradeState(originalState);
67606
+ result.sourceVersion = state.templateSetVersion;
67607
+ result.provider = state.provider;
67608
+ result.projectId = state.projectId;
67609
+ result.contextPreserved = Object.entries(state.files).filter(([, entry]) => entry.scope === "dynamic").map(([name]) => name);
67610
+ const seeded = await (0, seedProjectFiles_1.seedStaticProjectFiles)(state.provider, {
67611
+ fileExists: async (name) => (overlay.has(name) ? overlay.get(name) : await read(name)) !== null,
67612
+ readFile: async (name) => overlay.has(name) ? overlay.get(name) : await read(name),
67613
+ writeFile: async (name, contents) => {
67614
+ await read(name);
67615
+ overlay.set(name, contents);
67616
+ },
67617
+ removeFile: async (name) => {
67618
+ await read(name);
67619
+ overlay.set(name, null);
67620
+ }
67621
+ }, { producer: options.producer });
67622
+ result.conflicts = seeded.conflicts;
67623
+ result.preserved = seeded.unchanged;
67624
+ result.blockers.push(...seeded.failed.map((name) => `Cannot inspect managed file: ${name}`));
67625
+ const identities = /* @__PURE__ */ new Map();
67626
+ for (const name of (await files.listPackets()).sort()) {
67627
+ validateUpgradePath(name);
67628
+ if (!name.startsWith(".swarmcraft/projects/") || !name.endsWith(".md"))
67629
+ throw new Error("Invalid packet discovery path.");
67630
+ const contents = await read(name);
67631
+ if (contents === null)
67632
+ throw new Error("Packet changed during inspection; retry preview.");
67633
+ try {
67634
+ const packet = (0, packet_workflow_1.parsePacketFile)(contents);
67635
+ const id = (0, packet_workflow_1.localPacketId)(packet);
67636
+ if (identities.has(id))
67637
+ result.blockers.push(`Duplicate packet identity: ${identities.get(id)}, ${name}`);
67638
+ identities.set(id, name);
67639
+ if (packet.frontmatter.lane === "done" && !options.includeCompleted) {
67640
+ result.preserved.push(name);
67641
+ continue;
67642
+ }
67643
+ const migrated = (0, packet_workflow_1.migrateLocalPacket)(contents);
67644
+ if (contents !== migrated) {
67645
+ overlay.set(name, migrated);
67646
+ result.migratedPackets.push(name);
67647
+ } else
67648
+ result.preserved.push(name);
67649
+ } catch {
67650
+ result.blockers.push(`Malformed or unsupported packet: ${name}`);
67651
+ }
67652
+ }
67653
+ const proposed = overlay.get(seedProjectFiles_1.PROJECT_SEED_STATE_PATH);
67654
+ if (proposed && originalState) {
67655
+ const old = JSON.parse(originalState);
67656
+ const next = JSON.parse(proposed);
67657
+ next.producer = old.producer;
67658
+ if (JSON.stringify(old) === JSON.stringify(next))
67659
+ overlay.delete(seedProjectFiles_1.PROJECT_SEED_STATE_PATH);
67660
+ }
67661
+ } catch (error) {
67662
+ result.blockers.push(error instanceof Error ? error.message : "Cannot inspect repository.");
67663
+ }
67664
+ const changes = [...overlay].filter(([name, after]) => observations.get(name) !== after).map(([name, after]) => ({ path: name, before: observations.get(name), after })).sort((a, b) => a.path === seedProjectFiles_1.PROJECT_SEED_STATE_PATH ? 1 : b.path === seedProjectFiles_1.PROJECT_SEED_STATE_PATH ? -1 : a.path.localeCompare(b.path));
67665
+ for (const change of changes)
67666
+ (change.after === null ? result.removed : change.before === null ? result.added : result.updated).push(change.path);
67667
+ result.status = result.blockers.length ? "failed" : result.conflicts.length ? "conflict" : changes.length ? "available" : "current";
67668
+ return { result, changes, observations };
67669
+ }
67670
+ async function applyProjectUpgrade2(preview, files) {
67671
+ const result = { ...preview.result, mode: "apply", applied: [], failed: [], blockers: [...preview.result.blockers] };
67672
+ if (result.blockers.length)
67673
+ return result;
67674
+ try {
67675
+ for (const [name, expected] of preview.observations) {
67676
+ if (await files.read(name) !== expected) {
67677
+ result.failed.push(name);
67678
+ result.status = "failed";
67679
+ return result;
67680
+ }
67681
+ }
67682
+ const packets = [...preview.observations.keys()].filter((name) => name.startsWith(".swarmcraft/projects/") && name.endsWith(".md")).sort();
67683
+ if (JSON.stringify(packets) !== JSON.stringify((await files.listPackets()).sort()))
67684
+ throw new Error("Packet discovery changed; preview again.");
67685
+ for (const change of preview.changes) {
67686
+ try {
67687
+ if (!await files.compareAndWrite(change.path, change.before, change.after))
67688
+ throw new Error("File changed before write");
67689
+ result.applied.push(change.path);
67690
+ } catch {
67691
+ result.failed.push(change.path);
67692
+ result.status = "failed";
67693
+ return result;
67694
+ }
67695
+ }
67696
+ result.status = result.conflicts.length ? "conflict" : result.applied.length ? "applied" : "current";
67697
+ } catch (error) {
67698
+ result.status = "failed";
67699
+ result.blockers.push(error instanceof Error ? error.message : "Upgrade failed.");
67700
+ }
67701
+ return result;
67702
+ }
67703
+ }
67704
+ });
67705
+
67706
+ // ../../packages/repo-seed/dist/projectUpgradeFiles.js
67707
+ var require_projectUpgradeFiles = __commonJS({
67708
+ "../../packages/repo-seed/dist/projectUpgradeFiles.js"(exports2) {
67709
+ "use strict";
67710
+ var __importDefault = exports2 && exports2.__importDefault || function(mod) {
67711
+ return mod && mod.__esModule ? mod : { "default": mod };
67712
+ };
67713
+ Object.defineProperty(exports2, "__esModule", { value: true });
67714
+ exports2.createProjectUpgradeFiles = createProjectUpgradeFiles2;
67715
+ var promises_1 = require("node:fs/promises");
67716
+ var node_path_1 = __importDefault(require("node:path"));
67717
+ var node_crypto_1 = require("node:crypto");
67718
+ var projectUpgrade_1 = require_projectUpgrade();
67719
+ async function createProjectUpgradeFiles2(workspace, guard = () => {
67720
+ }) {
67721
+ const root = await (0, promises_1.realpath)(workspace);
67722
+ if (!(await (0, promises_1.lstat)(root)).isDirectory())
67723
+ throw new Error("Workspace must be a directory.");
67724
+ const resolve = async (relative2) => {
67725
+ (0, projectUpgrade_1.validateUpgradePath)(relative2);
67726
+ await guard(relative2);
67727
+ let current = root;
67728
+ for (const part of relative2.split("/")) {
67729
+ current = node_path_1.default.join(current, part);
67730
+ try {
67731
+ if ((await (0, promises_1.lstat)(current)).isSymbolicLink())
67732
+ throw new Error("Upgrade refuses symbolic links inside the workspace.");
67733
+ } catch (error) {
67734
+ if (error.code !== "ENOENT")
67735
+ throw error;
67736
+ }
67737
+ }
67738
+ return current;
67739
+ };
67740
+ const read = async (relative2) => {
67741
+ const absolute = await resolve(relative2);
67742
+ try {
67743
+ return await (0, promises_1.readFile)(absolute, "utf8");
67744
+ } catch (error) {
67745
+ if (error.code === "ENOENT")
67746
+ return null;
67747
+ throw error;
67748
+ }
67749
+ };
67750
+ return {
67751
+ read,
67752
+ async listPackets() {
67753
+ const found = [];
67754
+ const walk = async (relative2) => {
67755
+ const absolute = await resolve(relative2);
67756
+ let entries;
67757
+ try {
67758
+ entries = await (0, promises_1.readdir)(absolute, { withFileTypes: true });
67759
+ } catch (error) {
67760
+ if (error.code === "ENOENT")
67761
+ return;
67762
+ throw error;
67763
+ }
67764
+ for (const entry of entries) {
67765
+ const name = `${relative2}/${entry.name}`;
67766
+ if (entry.isSymbolicLink())
67767
+ throw new Error("Upgrade refuses symbolic links in packet discovery.");
67768
+ if (entry.isDirectory())
67769
+ await walk(name);
67770
+ else if (entry.isFile() && entry.name.endsWith(".md"))
67771
+ found.push(name);
67772
+ }
67773
+ };
67774
+ await walk(".swarmcraft/projects");
67775
+ return found.sort();
67776
+ },
67777
+ async compareAndWrite(relative2, expected, replacement) {
67778
+ if (await read(relative2) !== expected)
67779
+ return false;
67780
+ const absolute = await resolve(relative2);
67781
+ if (replacement === null) {
67782
+ await (0, promises_1.unlink)(absolute);
67783
+ return true;
67784
+ }
67785
+ await (0, promises_1.mkdir)(node_path_1.default.dirname(absolute), { recursive: true });
67786
+ const temporary = `${absolute}.upgrade-${(0, node_crypto_1.randomUUID)()}.tmp`;
67787
+ try {
67788
+ const mode = expected === null ? 420 : (await (0, promises_1.lstat)(absolute)).mode & 511;
67789
+ await (0, promises_1.writeFile)(temporary, replacement, { flag: "wx", mode });
67790
+ if (await read(relative2) !== expected)
67791
+ return false;
67792
+ await resolve(relative2);
67793
+ await (0, promises_1.rename)(temporary, absolute);
67794
+ return true;
67795
+ } finally {
67796
+ await (0, promises_1.unlink)(temporary).catch((error) => {
67797
+ if (error.code !== "ENOENT")
67798
+ throw error;
67799
+ });
67800
+ }
67801
+ }
67802
+ };
67803
+ }
67804
+ }
67805
+ });
67806
+
67548
67807
  // ../../packages/repo-seed/dist/index.js
67549
67808
  var require_dist4 = __commonJS({
67550
67809
  "../../packages/repo-seed/dist/index.js"(exports2) {
@@ -67595,6 +67854,9 @@ var require_dist4 = __commonJS({
67595
67854
  __exportStar(require_renderPlanning(), exports2);
67596
67855
  __exportStar(require_renderWorkspaceInstructions(), exports2);
67597
67856
  __exportStar(require_upgradeOperation(), exports2);
67857
+ __exportStar(require_projectUpgradeContract(), exports2);
67858
+ __exportStar(require_projectUpgrade(), exports2);
67859
+ __exportStar(require_projectUpgradeFiles(), exports2);
67598
67860
  }
67599
67861
  });
67600
67862
 
@@ -67950,7 +68212,7 @@ var import_packet_workflow6 = __toESM(require_dist(), 1);
67950
68212
  // package.json
67951
68213
  var package_default = {
67952
68214
  name: "@swarmcraftai/cli",
67953
- version: "0.7.0",
68215
+ version: "0.7.2",
67954
68216
  description: "Prepare repositories and run packet-based SwarmCraft agent workflows from the terminal.",
67955
68217
  license: "SEE LICENSE IN LICENSE.txt",
67956
68218
  type: "module",
@@ -69966,6 +70228,7 @@ function parseRunId(rawValue) {
69966
70228
  // src/commands/command-catalog.ts
69967
70229
  var import_packet_workflow5 = __toESM(require_dist(), 1);
69968
70230
  var COMMANDS = [
70231
+ { name: "upgrade", usage: "swarmcraft upgrade --workspace <path> [--check] [--include-completed] [--json]", summary: "Upgrade existing project guidance and packets locally without an account; preserves the saved provider (upgrade protocol 1).", implemented: true },
69969
70232
  { name: "operate upgrade", usage: "swarmcraft operate upgrade --workspace <path> [--check] [--json]", summary: "Check or upgrade an existing Operate repository with local Git checkpoints and recovery (upgrade protocol 1).", implemented: true },
69970
70233
  { name: "operate handbook", usage: "swarmcraft operate handbook --workspace <path> --notes <comma-separated-IDs> --title <title> --timezone <IANA-zone> [--formats html,pdf] [--reviewed-assets <comma-separated-paths>] [--include-provisional] [--track] [--json]", summary: "Create a dated local handbook snapshot from explicitly selected reviewed notes.", implemented: true },
69971
70234
  { name: "operate import", usage: "swarmcraft operate import --workspace <path> --source-id <id> --title <title> --timezone <IANA-zone> [--input <file>] [--group <label>] [--purpose workflow|derived] [--rebuild] [--json]", summary: "Register local evidence with immutable dated snapshots and bounded text extraction.", implemented: true },
@@ -70077,6 +70340,65 @@ function findCommand(positionals) {
70077
70340
  const commandKey = positionals[0] === "auth" || positionals[0] === "projects" || positionals[0] === "delegation" || positionals[0] === "discovery" || positionals[0] === "operate" ? positionals.slice(0, 2).join(" ") : positionals[0];
70078
70341
  return COMMANDS.find((command) => command.name === commandKey);
70079
70342
  }
70343
+ var COMMAND_INSTRUCTIONS = {
70344
+ upgrade: {
70345
+ requirements: ["Existing project.seed-state.json with a supported saved provider. No account, API, or installed AI tool required."],
70346
+ effects: ["Upgrades bundled static guidance and unfinished/provisional packets. Preserves saved provider/project, owner files (including existing CLAUDE.md), edited managed files, and completed history by default.", "Server-derived project context is preserved, not refreshed offline. No board task/link writes, Git commits, pushes, or telemetry. Separate running editor sync may act independently.", "Conflicts remain for owner review. Missing/corrupt/newer state, duplicate identities, malformed packets and symlink paths block apply. Rerun after resolving failures; never downgrade or regenerate owner work."],
70347
+ options: ["--workspace <path>: existing project repository (required).", "--check: preview only; no files or seed-state writes. Omit to apply.", "--include-completed: explicitly migrate completed packet metadata too; never changes progress.", "--json: print protocol-1 summary, without private file contents."],
70348
+ result: "Exit 0: current, changes available in preview, or applied. Exit 2: preserved conflicts. Exit 1: blocker/failure; applied lists only successful writes. Review git diff before committing.",
70349
+ example: "swarmcraft upgrade --workspace . --check"
70350
+ },
70351
+ init: {
70352
+ requirements: ["Signed-in CLI session, accessible READY project, network, and a local Git workspace."],
70353
+ effects: ["Creates initial guidance or reconciles an existing repo. Updates unchanged managed files; preserves edited managed files as conflicts and existing owner files such as CLAUDE.md.", "Creates or migrates selected unfinished board packets while preserving local progress. Completed board tasks and repo-only provisional packets are untouched. May create/update remote packet links.", "The explicit provider selects generated guidance; it does not change the extension preference. No agents run or Git commit is made. For an existing repo's offline upgrade use swarmcraft upgrade."],
70354
+ options: ["--project, --workspace and --agent-provider are required.", "--task <id>: repeat to select tasks; --task-limit <positive integer|all> defaults to all unfinished tasks.", "--delegation <id>: use authorised operator access."],
70355
+ result: "Prints seed/packet changes, conflicts and skipped tasks. Exit 0 on completion, 1 on error; inspect conflicts and git diff before committing.",
70356
+ example: "swarmcraft init --project <id> --workspace . --agent-provider claude"
70357
+ },
70358
+ "auth login": { requirements: ["Network and a SwarmCraft account; prompts for missing credentials."], effects: ["Authenticates and stores a private local CLI session. Does not seed a repo."], options: ["--api-base-url overrides SWARMCRAFT_API_BASE_URL; default https://swarmcraft.ai/api.", "Prefer interactive prompts to --password/--mfa-code flags to avoid shell history exposure."], result: "Exit 0 when the session is stored; 1 on failure.", example: "swarmcraft auth login" },
70359
+ "projects list": { requirements: ["Signed-in session and network."], effects: ["Lists accessible projects. May refresh the local session; optional on-behalf-of access starts an audited delegation."], options: ["--delegation selects existing access; --on-behalf-of requires --delegation-reason."], result: "Prints project ID, state, progress and title; exit 0 on success, 1 on failure.", example: "swarmcraft projects list" },
70360
+ "delegation start": { requirements: ["Signed-in authorised operator and network."], effects: ["Creates audited, temporary server-side access for the named user."], options: ["--user and --reason required; --support-ticket optional; --expires-in-minutes bounds 5\u2013600 (server default when omitted)."], result: "Prints delegation details; exit 0 on success, 1 on failure.", example: "swarmcraft delegation start --user <user> --reason <reason>" },
70361
+ "delegation end": { requirements: ["Signed-in authorised operator and network."], effects: ["Revokes the specified server-side delegation; local repo files are untouched."], options: ["--delegation <id> required."], result: "Prints the ended delegation; exit 0 on success, 1 on failure.", example: "swarmcraft delegation end --delegation <id>" },
70362
+ "one-shot": { requirements: ["Signed-in project access, network, Git workspace and selected provider prerequisites. Managed AI requires available credits."], effects: ["Runs agents, changes repository files and board state, and writes run artifacts under .swarmcraft/runs/<run-id>. Managed AI is metered; external providers use their own access.", "This executes delivery, not a guidance upgrade. Commit policy can create local commits; review outputs."], options: ["--project, --workspace, --agent-provider required. custom uses --agent-command or SWARMCRAFT_AGENT_COMMAND; managed rejects custom credentials/commands.", "Defaults: --checking off; --done-policy auto; --reviewing on only when done-policy is stop; --commit-policy none; --task-limit all; --max-checking-attempts 2.", "--max-agent-requests and --max-agent-spend-usd bound usage; --require-cost-telemetry requires cost evidence. --allow-dirty opts into existing changes.", "--run-id selects artifacts; --task selects tasks; --agent-env-file and --agent-api-key-env-name configure external providers; --delegation selects authorised access."], result: "Prints run/task outcomes. Exit 0 means command completion, not that every task succeeded; inspect outcomes. Execution errors exit 1.", example: "swarmcraft one-shot --project <id> --workspace . --agent-provider claude --done-policy stop --max-agent-requests 3" },
70363
+ resume: { requirements: ["Existing local run manifest, signed-in project access, network and original provider prerequisites."], effects: ["Continues the recorded execution, including agent writes and board updates. Uses the saved run policies."], options: ["--run and --workspace required; --max-agent-requests can extend the request limit; --allow-dirty explicitly permits existing changes."], result: "Prints resumed run outcomes; inspect task failures even when command exits 0. Errors exit 1.", example: "swarmcraft resume --run <id> --workspace ." },
70364
+ status: { requirements: ["Existing local run manifest; no sign-in or API required."], effects: ["Reads the recorded run summary without continuing execution or writing files."], options: ["--run and --workspace required. Delegation is not used for this local read."], result: "Prints local run/task outcomes; exit 0 on success, 1 when unreadable.", example: "swarmcraft status --run <id> --workspace ." },
70365
+ doctor: { requirements: ["No session required for local checks; an existing session enables an API reachability check."], effects: ["Checks Node, session, optional Git workspace and provider executable. May refresh session or use explicitly requested delegation; does not upgrade guidance."], options: ["--workspace and --agent-provider optional; custom skips provider executable lookup."], result: "Diagnostic text reports missing prerequisites; a completed diagnostic may exit 0 despite reported problems. Read the output.", example: "swarmcraft doctor --workspace . --agent-provider claude" },
70366
+ "support-bundle": { requirements: ["Existing local CLI run; no sign-in or API required."], effects: ["Writes a redacted support bundle from run artifacts. Does not upload it; review before sharing."], options: ["--run and --workspace required."], result: "Prints bundle path; exit 0 on success, 1 on failure.", example: "swarmcraft support-bundle --run <id> --workspace ." },
70367
+ "discovery prepare": { requirements: ["Reviewed local discovery documents and selected sources; no account or agent required."], effects: ["Freezes selected inputs and writes a deterministic Discovery Package, run evidence and validation feedback. No AI launch or upload."], options: ["--workspace required; repeat --source for owner-selected relative Markdown/text files. --run-id starts a named run; --resume-run resumes one. --discovery-workspace supplies identity."], result: "Prints progress/package evidence; exit 0 on completion, 1 on error. Review assessment before upload.", example: "swarmcraft discovery prepare --workspace ." },
70368
+ "discovery validate": { requirements: ["Existing local Discovery Package; no sign-in or API required."], effects: ["Validates the current package and local files; writes validation feedback without launching agents."], options: ["--workspace required."], result: "Prints READY or NEEDS_INPUT and feedback path; read assessment, not only exit 0. Errors exit 1.", example: "swarmcraft discovery validate --workspace ." },
70369
+ "discovery support-bundle": { requirements: ["Existing local discovery run; no sign-in or API required."], effects: ["Writes redacted diagnostics without raw sources or package content; no automatic upload."], options: ["--workspace and --run required."], result: "Prints bundle path; exit 0 on success, 1 on failure.", example: "swarmcraft discovery support-bundle --workspace . --run <id>" },
70370
+ "operate upgrade": { requirements: ["Existing Operate repository, supported local records and Git; no account or API required."], effects: ["Upgrades Operate guidance with scoped local Git checkpoints and recovery. Does not perform project-packet upgrades; use swarmcraft upgrade for project guidance."], options: ["--workspace required; --check previews without applying; --json requests structured errors/results."], result: "Prints upgrade/status evidence. Exit 0 valid, 3 invalid; command-specific nonzero errors identify blockers.", example: "swarmcraft operate upgrade --workspace . --check" },
70371
+ "operate init": { requirements: ["Account/session and network; Git and a selected AI provider."], effects: ["Seeds/reconciles Operate guidance with scoped Git handling and reports content-free activity. Preserves owner records; reporting failures do not discard local work."], options: ["--workspace and --agent-provider required; --adopt explicitly adopts a nonempty directory.", "--client-surface defaults to cli; --session-stdin is a protected integration input, never a token argument. --json selects structured output."], result: "Prints initialization/status evidence. Exit 0 valid, 3 invalid; command errors return specific nonzero codes.", example: "swarmcraft operate init --workspace . --agent-provider claude --adopt" },
70372
+ "operate status": { requirements: ["Local Operate repository; no sign-in or API required."], effects: ["Reads local capabilities and evidence without changing records."], options: ["--workspace required; --json supported."], result: "JSON status; exit 0 valid, 3 invalid, other nonzero for command errors.", example: "swarmcraft operate status --workspace ." },
70373
+ "operate validate": { requirements: ["Local Operate repository; no sign-in or API required."], effects: ["Inspects records, links, formalisation and Git policy without releasing a schema or running an agent."], options: ["--workspace required; --json supported."], result: "JSON validation; exit 0 valid, 3 invalid, other nonzero for command errors.", example: "swarmcraft operate validate --workspace ." },
70374
+ "operate rebuild": { requirements: ["Local Operate repository; no sign-in or API required."], effects: ["Refreshes derived navigation and status. Does not commit or rewrite owner authority records."], options: ["--workspace required; --json supported."], result: "JSON result; exit 0 valid, 3 invalid, other nonzero for command errors.", example: "swarmcraft operate rebuild --workspace ." },
70375
+ "operate import": { requirements: ["Local Operate repository and explicitly selected evidence; no account required."], effects: ["Registers a source with immutable dated snapshots and bounded extraction. No upload. --rebuild refreshes derived navigation."], options: ["--workspace, --source-id, --title and --timezone required; --input selects a file; --group is optional.", "--purpose workflow|derived controls intake (default derived); --json supported. Review source sensitivity before import."], result: "JSON intake evidence; exit 0 valid, 3 invalid, other nonzero for command errors.", example: "swarmcraft operate import --workspace . --source-id source.example --title Example --timezone Australia/Brisbane --input example.txt" },
70376
+ "operate handbook": { requirements: ["Local Operate repository and explicitly selected reviewed notes; no account required."], effects: ["Writes a dated handbook snapshot. Optional --track marks the manifest TRACKED; it does not stage, commit, or publish files."], options: ["--workspace, --notes (comma-separated IDs), --title and --timezone required; --formats html,pdf adds optional outputs to the default Markdown snapshot.", "--reviewed-assets lists approved paths; --include-provisional explicitly includes provisional material; --json supported."], result: "JSON snapshot evidence; exit 0 valid, 3 invalid, other nonzero for command errors.", example: "swarmcraft operate handbook --workspace . --notes note.example --title Handbook --timezone Australia/Brisbane --formats html" }
70377
+ };
70378
+ function renderCommandHelp(command) {
70379
+ const detail = COMMAND_INSTRUCTIONS[command.name];
70380
+ return `${command.usage}
70381
+
70382
+ ${command.summary}
70383
+
70384
+ Requirements:
70385
+ ${detail.requirements.map((line) => ` ${line}`).join("\n")}
70386
+
70387
+ Effects and preservation:
70388
+ ${detail.effects.map((line) => ` ${line}`).join("\n")}
70389
+
70390
+ Options and defaults:
70391
+ ${detail.options.map((line) => ` ${line}`).join("\n")}
70392
+
70393
+ Results:
70394
+ ${detail.result}
70395
+
70396
+ Example:
70397
+ ${detail.example}
70398
+
70399
+ Help is local and read-only; no authentication or command execution occurs.
70400
+ `;
70401
+ }
70080
70402
 
70081
70403
  // src/terminalPrompt.ts
70082
70404
  var import_node_process = require("node:process");
@@ -70118,11 +70440,32 @@ async function promptSecret(prompt, streams = DEFAULT_STREAMS) {
70118
70440
  }
70119
70441
  }
70120
70442
 
70443
+ // src/commands/upgrade-command.ts
70444
+ var import_repo_seed2 = __toESM(require_dist4(), 1);
70445
+ async function runProjectUpgrade(parsed, version2) {
70446
+ const allowed = /* @__PURE__ */ new Set(["workspace", "check", "json", "include-completed"]);
70447
+ for (const option of parsed.options.keys()) if (!allowed.has(option)) throw new Error(`Unsupported upgrade option --${option}. Upgrade preserves the saved provider and project.`);
70448
+ const files = await (0, import_repo_seed2.createProjectUpgradeFiles)(requireOption(parsed, "workspace"));
70449
+ const preview = await (0, import_repo_seed2.previewProjectUpgrade)(files, { producer: { surface: "cli", version: version2 }, includeCompleted: hasFlag(parsed, "include-completed") });
70450
+ const result = hasFlag(parsed, "check") ? preview.result : await (0, import_repo_seed2.applyProjectUpgrade)(preview, files);
70451
+ console.log(hasFlag(parsed, "json") ? JSON.stringify(result, null, 2) : formatProjectUpgrade(result));
70452
+ return (0, import_repo_seed2.projectUpgradeExitCode)(result);
70453
+ }
70454
+ function formatProjectUpgrade(result) {
70455
+ const lines = [`Project upgrade ${result.mode}: ${result.status}`, `Templates: ${result.sourceVersion} \u2192 ${result.targetVersion}; provider: ${result.provider ?? "unresolved"}`, "No board sync or Git commit performed."];
70456
+ for (const [label, paths] of Object.entries({ Added: result.added, Updated: result.updated, Removed: result.removed, "Packet migrations": result.migratedPackets, "Preserved project context": result.contextPreserved, Conflicts: result.conflicts, Blockers: result.blockers, Applied: result.applied, Failed: result.failed })) {
70457
+ if (paths.length) lines.push(`${label}:`, ...paths.map((p) => ` ${p}`));
70458
+ }
70459
+ if (result.mode === "check") lines.push("Preview only; no files changed.");
70460
+ else lines.push("Review git diff and any preserved conflicts before committing.");
70461
+ return lines.join("\n");
70462
+ }
70463
+
70121
70464
  // src/operation/upgrade.ts
70122
70465
  var import_promises11 = require("node:fs/promises");
70123
70466
  var import_node_path10 = __toESM(require("node:path"), 1);
70124
70467
  var import_node_crypto3 = require("node:crypto");
70125
- var import_repo_seed3 = __toESM(require_dist4(), 1);
70468
+ var import_repo_seed4 = __toESM(require_dist4(), 1);
70126
70469
  var import_operation_contract4 = __toESM(require_dist2(), 1);
70127
70470
 
70128
70471
  // src/operation/inspection.ts
@@ -70172,7 +70515,7 @@ async function approvedSourcePaths(files, sources) {
70172
70515
  }
70173
70516
 
70174
70517
  // src/operation/inspection.ts
70175
- var import_repo_seed2 = __toESM(require_dist4(), 1);
70518
+ var import_repo_seed3 = __toESM(require_dist4(), 1);
70176
70519
  async function loadOperationLocator(files) {
70177
70520
  const text = await files.read(".swarmcraft/operation.json");
70178
70521
  if (text === void 0) return void 0;
@@ -70251,7 +70594,7 @@ async function inspectOperation(workspace, signal) {
70251
70594
  const parsed = JSON.parse(state);
70252
70595
  if (parsed.schemaVersion !== 1 || !Number.isInteger(parsed.seedVersion) || !Array.isArray(parsed.conflicts)) {
70253
70596
  status.codes.push("OPERATE_SEED_STATE_INVALID");
70254
- } else if (parsed.seedVersion > import_repo_seed2.OPERATION_SEED_VERSION) {
70597
+ } else if (parsed.seedVersion > import_repo_seed3.OPERATION_SEED_VERSION) {
70255
70598
  status.codes.push("OPERATE_SEED_VERSION_UNSUPPORTED");
70256
70599
  }
70257
70600
  status.seedConflicts = Array.isArray(parsed.conflicts) && parsed.conflicts.length > 0;
@@ -70293,7 +70636,7 @@ async function rebuildOperationNavigation(workspace, signal) {
70293
70636
  }
70294
70637
 
70295
70638
  // src/operation/upgrade.ts
70296
- var MIGRATION_ID = "operate-to-2.0-seed-" + import_repo_seed3.OPERATION_SEED_VERSION;
70639
+ var MIGRATION_ID = "operate-to-2.0-seed-" + import_repo_seed4.OPERATION_SEED_VERSION;
70297
70640
  var JOURNAL = "swarmcraft-operate-upgrade.json";
70298
70641
  var LOCK = "swarmcraft-operate-upgrade.lock";
70299
70642
  var fail = (code, message) => {
@@ -70315,8 +70658,8 @@ async function checkOperationUpgrade(workspace) {
70315
70658
  try {
70316
70659
  const { legacyRoot } = (0, import_operation_contract4.upgradeLocator)(locator);
70317
70660
  const seed = JSON.parse(await files.read(".swarmcraft/operation.seed-state.json") ?? "null");
70318
- if (!seed || seed.schemaVersion !== 1 || !Number.isInteger(seed.seedVersion) || seed.seedVersion < 1 || seed.seedVersion > import_repo_seed3.OPERATION_SEED_VERSION) return result("UNSUPPORTED");
70319
- return result(legacyRoot || seed.seedVersion < import_repo_seed3.OPERATION_SEED_VERSION || Array.isArray(seed.conflicts) && seed.conflicts.length > 0 ? "AVAILABLE" : "CURRENT");
70661
+ if (!seed || seed.schemaVersion !== 1 || !Number.isInteger(seed.seedVersion) || seed.seedVersion < 1 || seed.seedVersion > import_repo_seed4.OPERATION_SEED_VERSION) return result("UNSUPPORTED");
70662
+ return result(legacyRoot || seed.seedVersion < import_repo_seed4.OPERATION_SEED_VERSION || Array.isArray(seed.conflicts) && seed.conflicts.length > 0 ? "AVAILABLE" : "CURRENT");
70320
70663
  } catch {
70321
70664
  return result("UNSUPPORTED");
70322
70665
  }
@@ -70367,7 +70710,7 @@ async function upgradeOperation(workspace, signal) {
70367
70710
  }
70368
70711
  let planned;
70369
70712
  try {
70370
- planned = await (0, import_repo_seed3.planOperationUpgrade)(input);
70713
+ planned = await (0, import_repo_seed4.planOperationUpgrade)(input);
70371
70714
  } catch (error) {
70372
70715
  const code = error instanceof Error && /^OPERATE_[A-Z_]+$/.test(error.message) ? error.message : "OPERATE_MIGRATION_INPUT_INVALID";
70373
70716
  fail(code, upgradeFailureMessage(code));
@@ -70575,7 +70918,7 @@ async function permitsSeededHandbook(root, files, name, exportsRoot, before, aft
70575
70918
  // src/operation/initialization.ts
70576
70919
  var import_node_crypto4 = require("node:crypto");
70577
70920
  var import_operation_contract5 = __toESM(require_dist2(), 1);
70578
- var import_repo_seed4 = __toESM(require_dist4(), 1);
70921
+ var import_repo_seed5 = __toESM(require_dist4(), 1);
70579
70922
 
70580
70923
  // src/operation/seed-commit.ts
70581
70924
  async function commitOperationSeed(root, expected) {
@@ -70637,9 +70980,9 @@ async function initializeOperation(options, deps) {
70637
70980
  );
70638
70981
  const before = /* @__PURE__ */ new Map();
70639
70982
  const owned = new Set([
70640
- ...(0, import_repo_seed4.buildOperationSeedFiles)(locator, "codex"),
70641
- ...(0, import_repo_seed4.buildOperationSeedFiles)(locator, "copilot"),
70642
- ...(0, import_repo_seed4.buildOperationSeedFiles)(locator, "claude")
70983
+ ...(0, import_repo_seed5.buildOperationSeedFiles)(locator, "codex"),
70984
+ ...(0, import_repo_seed5.buildOperationSeedFiles)(locator, "copilot"),
70985
+ ...(0, import_repo_seed5.buildOperationSeedFiles)(locator, "claude")
70643
70986
  ].map((file) => file.relativePath));
70644
70987
  owned.add(".swarmcraft/operation.seed-state.json");
70645
70988
  const requireOwned = (file) => {
@@ -70657,7 +71000,7 @@ async function initializeOperation(options, deps) {
70657
71000
  const dryRun = async () => {
70658
71001
  const planned = /* @__PURE__ */ new Map();
70659
71002
  const read = async (file) => planned.has(file) ? planned.get(file) : baseline(file);
70660
- return (0, import_repo_seed4.seedOperationFiles)(locator, options.provider, {
71003
+ return (0, import_repo_seed5.seedOperationFiles)(locator, options.provider, {
70661
71004
  fileExists: async (file) => await read(file) !== void 0,
70662
71005
  readFile: async (file) => await read(file) ?? "",
70663
71006
  writeFile: async (file, contents) => {
@@ -70716,7 +71059,7 @@ async function initializeOperation(options, deps) {
70716
71059
  clientSurface: options.clientSurface ?? "CLI",
70717
71060
  providerKind: { codex: "CODEX", copilot: "COPILOT", claude: "CLAUDE" }[options.provider],
70718
71061
  contractVersion: import_operation_contract5.OPERATION_CONTRACT_VERSION,
70719
- seedVersion: import_repo_seed4.OPERATION_SEED_VERSION,
71062
+ seedVersion: import_repo_seed5.OPERATION_SEED_VERSION,
70720
71063
  repositoryKind: state.repositoryKind
70721
71064
  });
70722
71065
  } catch {
@@ -70743,7 +71086,7 @@ async function initializeOperation(options, deps) {
70743
71086
  };
70744
71087
  let result;
70745
71088
  try {
70746
- result = await (0, import_repo_seed4.seedOperationFiles)(
71089
+ result = await (0, import_repo_seed5.seedOperationFiles)(
70747
71090
  locator,
70748
71091
  options.provider,
70749
71092
  dependencies,
@@ -70760,7 +71103,7 @@ async function initializeOperation(options, deps) {
70760
71103
  }
70761
71104
  const status = await inspectOperation(root, options.signal);
70762
71105
  if (status.valid) {
70763
- const expected = new Map((0, import_repo_seed4.buildOperationSeedFiles)(locator, options.provider).map((file) => [file.relativePath, file.contents]));
71106
+ const expected = new Map((0, import_repo_seed5.buildOperationSeedFiles)(locator, options.provider).map((file) => [file.relativePath, file.contents]));
70764
71107
  for (const path14 of result.removed) expected.set(path14, void 0);
70765
71108
  expected.set(".swarmcraft/operation.seed-state.json", await files.read(".swarmcraft/operation.seed-state.json"));
70766
71109
  checkCancelled(options.signal);
@@ -71121,6 +71464,7 @@ async function main(argv) {
71121
71464
  if (command) {
71122
71465
  printCommandHelp(command);
71123
71466
  } else {
71467
+ if (parsed.positionals.length && !["auth", "projects", "delegation", "discovery", "operate"].includes(parsed.positionals.join(" "))) throw new Error("Unknown help command. Run swarmcraft --help.");
71124
71468
  printGeneralHelp();
71125
71469
  }
71126
71470
  return 0;
@@ -71130,6 +71474,8 @@ async function main(argv) {
71130
71474
  if (helpCommand) {
71131
71475
  printCommandHelp(helpCommand);
71132
71476
  } else {
71477
+ const requested = parsed.positionals.slice(1).join(" ");
71478
+ if (requested && !["auth", "projects", "delegation", "discovery", "operate"].includes(requested)) throw new Error("Unknown help command. Run swarmcraft --help.");
71133
71479
  printGeneralHelp();
71134
71480
  }
71135
71481
  return 0;
@@ -71139,6 +71485,8 @@ async function main(argv) {
71139
71485
  Run "swarmcraft --help" for available commands.`);
71140
71486
  }
71141
71487
  switch (command.name) {
71488
+ case "upgrade":
71489
+ return runProjectUpgrade(parsed, VERSION);
71142
71490
  case "operate upgrade":
71143
71491
  return runOperateCommand(parsed, "upgrade", VERSION);
71144
71492
  case "operate init":
@@ -71535,6 +71883,13 @@ function parseOneShotOptions(parsed) {
71535
71883
  async function readRunManifest(workspacePath, runId) {
71536
71884
  return JSON.parse(await (0, import_promises13.readFile)(resolveManifestPath(import_node_path13.default.resolve(workspacePath), runId), "utf8"));
71537
71885
  }
71886
+ function commandGroup(name) {
71887
+ if (["init", "upgrade"].includes(name)) return "Setup and upgrade";
71888
+ if (["one-shot", "resume", "status"].includes(name)) return "Delivery";
71889
+ if (name.startsWith("operate ")) return "Operate";
71890
+ if (name.startsWith("discovery ")) return "Discovery";
71891
+ return "Account and support";
71892
+ }
71538
71893
  function printGeneralHelp() {
71539
71894
  console.log(`SwarmCraft CLI ${VERSION}
71540
71895
 
@@ -71542,22 +71897,29 @@ Usage:
71542
71897
  swarmcraft <command> [options]
71543
71898
 
71544
71899
  Commands:
71545
- ${COMMANDS.map((command) => ` ${command.usage}
71546
- ${command.summary}${command.implemented ? "" : " (planned)"}`).join("\n")}
71900
+ ${["Setup and upgrade", "Delivery", "Operate", "Discovery", "Account and support"].map((group) => `${group}:
71901
+ ${COMMANDS.filter((command) => commandGroup(command.name) === group).map((command) => ` ${command.usage}
71902
+ ${command.summary}`).join("\n")}`).join("\n\n")}
71547
71903
 
71548
71904
  Options:
71549
71905
  -h, --help Show help.
71550
71906
  -v, --version Show version.
71551
71907
 
71908
+ Examples:
71909
+ swarmcraft upgrade --workspace . --check
71910
+ swarmcraft init --project <id> --workspace . --agent-provider claude
71911
+ swarmcraft operate upgrade --workspace . --check
71912
+ swarmcraft help init
71913
+
71914
+ Use project upgrade for existing project guidance; operate upgrade is for Operate records.
71915
+ Subcommand help explains defaults, side effects and requirements without executing the command.
71916
+
71552
71917
  Artifacts:
71553
71918
  Customer run manifests will live under .swarmcraft/runs/<run-id> in the selected workspace.
71554
71919
  `);
71555
71920
  }
71556
71921
  function printCommandHelp(command) {
71557
- console.log(`${command.usage}
71558
-
71559
- ${command.summary}${command.implemented ? "" : "\n\nThis command is planned but not implemented yet."}
71560
- `);
71922
+ console.log(renderCommandHelp(command));
71561
71923
  }
71562
71924
  function parseTaskLimit(rawValue) {
71563
71925
  if (rawValue === "all") {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@swarmcraftai/cli",
3
- "version": "0.7.0",
3
+ "version": "0.7.2",
4
4
  "description": "Prepare repositories and run packet-based SwarmCraft agent workflows from the terminal.",
5
5
  "license": "SEE LICENSE IN LICENSE.txt",
6
6
  "type": "module",