@swarmcraftai/cli 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to the SwarmCraft CLI are documented in this file.
 
+## 0.5.1
+
+- Refreshes the npm README around customer installation and common workflows, with native PowerShell commands, Node/npm verification, managed-machine recovery and VS Code restart guidance.
+- Clarifies that WSL is not required for the SwarmCraft CLI and that AI-provider prerequisites are separate.
+- Command behavior and the editor/Setup capability contract remain unchanged from 0.5.0.
+
 ## 0.5.0
 
 - Adds deterministic `operate init`, `operate validate`, and `operate status` commands for local operational work, with Codex and Copilot guidance for Work, Automate, and Formalise.

package/README.md

@@ -1,190 +1,150 @@
 # SwarmCraft CLI
 
-When the reviewed discovery source selection includes `docs/discovery/sources/operation-formalisation.md`, package preparation also verifies the current operational approval, model identity and selected digests against that copied source. Missing, stale or cancelled approval blocks preparation with `DP_OPERATION_SOURCE_STALE`. This does not replace the existing curated-document, package-validation or upload-consent gates.
+[SwarmCraft](https://swarmcraft.ai) helps you use AI to get operational work done, automate repeatable tasks, and build applications. It gives your AI assistant shared skills and structured workflows while you keep control of your knowledge, records, and code.
 
-Editor integration: `operate init --session-stdin` accepts a bounded JSON object with `apiBaseUrl` and `accessToken` through a private stdin pipe. The VS Code extension uses this to reuse its browser session. The CLI verifies the session before mutation and neither reads nor writes its saved session file in this mode. Never put credentials in shell command text. Normal terminal use continues to use `swarmcraft auth login`.
+The CLI brings SwarmCraft workflows to your terminal. Use it to prepare a local repository for operational work or run implementation tasks from your SwarmCraft project board with an AI coding agent. You can inspect progress, resume interrupted runs, and collect support diagnostics.
 
-SwarmCraft CLI prepares a local repository for a SwarmCraft project board and runs packet-based agent workflows from the terminal.
+## Prerequisites
 
-Use it to authenticate with SwarmCraft, list available projects, seed workspace guidance files, materialize task packets, run one-shot implementation passes, resume or inspect runs, and create support bundles.
+- Node.js 20.19 or newer, npm, and Git.
+- A SwarmCraft account and a project with tasks ready to implement.
+- A local Git repository with unrelated changes committed or stashed.
+- Codex CLI or GitHub Copilot CLI installed and configured, or SwarmCraft Managed AI credits.
 
-Deep Discovery uses the provider-neutral `@swarmcraft/discovery-package-contract` for exact-text packaging, canonical hashing, and local validation. The CLI never asks an AI provider to generate transport JSON or tasks and never contains SwarmCraft's private server-side catalogue compiler.
+On macOS and Windows, start with [SwarmCraft Setup](https://swarmcraft.ai/docs/set-up-and-connect/use-swarmcraft-setup) to prepare your environment.
 
-## Package Shape
-
-- Package name: `@swarmcraftai/cli`
-- Installed command: `swarmcraft`
-- Supported runtime target: Node.js 20.19 or newer
-- Local run artifact location: `.swarmcraft/runs/<run-id>` inside the selected customer workspace
-- Public package contents: bundled CLI runtime, README, package metadata, and license
-- Shared workspace packages are bundled into the CLI artifact; customers do not install `@swarmcraft/packet-workflow` or `@swarmcraft/repo-seed` directly.
-
-## Implemented Module Ownership
-
-- `src/main.ts` is the executable composition root: it dispatches parsed commands, prompts where compatibility requires it, prints outcomes, and selects exit behavior.
-- `src/commands/command-catalog.ts` owns stable command names, usage text, and help lookup; `src/commands/arguments.ts` owns syntax-only argument parsing and repeated option access.
-- `src/apiClient.ts` maps API transport contracts; `src/sessionStore.ts` is the only owner of the owner-only local credential file.
-- `src/workspace.ts` owns workspace validation and contained file/git operations. `src/runtime/workspace-paths.ts` rejects absolute, traversal, escaped run, manifest, log, and support-artifact targets.
-- `src/runtime/process.ts` provides shell-free argument-array execution. Only `runTrustedShellAgentCommand` may invoke a shell for a deliberately supplied custom-agent template; API content and credentials must never be interpolated into it.
-- `src/bootstrap.ts`, `src/discovery.ts`, and `src/oneShot.ts` compose the seed, immutable discovery-package, and packet execution workflows.
-- `src/operation/` owns Operate filesystem/Git preflight, shared-seed reconciliation, local inspection, and content-safe status; `src/commands/operate-commands.ts` owns its session validation, cancellation, output, and exit codes.
-- `src/workflows/agent-execution.ts` owns approved credential injection, trusted template quoting, and optional cost capture. `src/artifacts/run-manifest.ts` owns contained paths and atomic resume-manifest persistence.
-- `src/supportBundle.ts` exposes only allow-listed delegation facts and recursively redacts secret-bearing keys.
-
-All customer run artifacts remain below `.swarmcraft/runs/<run-id>`. Workspace-relative reads, writes, removals, packet paths, discovery sources, logs, manifests, diagnostics, and support bundles are resolved through the containment boundary before access.
-
-## Distribution
-
-The first public distribution channel is npm:
+## Install
 
 ```bash
 npm install -g @swarmcraftai/cli
 swarmcraft --help
 ```
 
-One-off use is also supported:
+For one-off use, run `npx @swarmcraftai/cli --help`.
 
-```bash
-npx @swarmcraftai/cli --help
-```
+## Native Windows installation
 
-Public publishing is owned by the Azure pipeline in `azure-pipelines.cli-release.yml`, with staged npm publishing and final maintainer approval. See [the CLI release runbook](../../docs/runbooks/swarmcraft-cli-npm-release.md). Run the local package smoke before publishing:
+WSL is not required for the SwarmCraft CLI. In PowerShell:
 
-```bash
-pnpm cli:release:smoke
+```powershell
+node --version
+npm.cmd --version
+npm.cmd install -g @swarmcraftai/cli
+swarmcraft.cmd --version
+swarmcraft.cmd operate init --help
+Get-Command node, npm.cmd, swarmcraft.cmd
+npm.cmd prefix -g
 ```
 
-## Local Development
+Use a supported Node.js LTS release meeting the minimum above. Confirm the npm global prefix is on your user PATH, then fully quit and reopen VS Code. A window reload may retain the old PATH. Use `.cmd` commands instead of changing PowerShell execution policy. If software installation or the prefix is restricted, use your organisation's approved installation or user-writable prefix; preserve managed runtimes and npm registry/authentication settings.
 
-From the repo root:
-
-```bash
-pnpm cli:dev -- --help
-pnpm cli:check
-```
+The extension needs an installed CLI; one-off `npx` execution does not satisfy that requirement. See the [manual setup checklist](https://swarmcraft.ai/docs/set-up-and-connect/manual-setup-checklist). AI providers have separate platform and authentication requirements.
 
-From this package:
+PowerShell uses different line continuation from Bash. Run the multiline examples below on one line, using `swarmcraft.cmd`, for example:
 
-```bash
-pnpm dev -- --help
-pnpm check
-pnpm release:smoke
+```powershell
+swarmcraft.cmd one-shot --project YOUR_PROJECT_ID --workspace . --agent-provider codex --task-limit 1 --max-agent-requests 100 --commit-policy done
 ```
 
-`pnpm check` is the package ready-for-review gate and includes lint, type checking, unit tests, a production bundle, and the bundled help smoke. Before release, also run `pnpm release:smoke`; the root `pnpm standards:cli` alias runs both.
-
-## Current Commands
+## Run your first task
 
-Core commands:
+Sign in and find your project ID:
 
 ```bash
-swarmcraft auth login --email <email>
-swarmcraft delegation start --user <customer-email-or-id> --reason <text> --expires-in-minutes 600
-swarmcraft projects list --delegation <delegation-id>
-swarmcraft discovery prepare --workspace <path>
-swarmcraft discovery validate --workspace <path>
-swarmcraft discovery support-bundle --workspace <path> --run <run-id>
-swarmcraft init --project <project-id> --workspace <path> --agent-provider codex --delegation <delegation-id>
-swarmcraft one-shot --project <project-id> --workspace <path> --agent-provider codex --delegation <delegation-id>
-swarmcraft one-shot --project <project-id> --workspace <path> --agent-provider codex --run-id <known-run-id>
-swarmcraft resume --run <run-id> --workspace <path> --delegation <delegation-id>
-swarmcraft status --run <run-id> --workspace <path> --delegation <delegation-id>
-swarmcraft delegation end --delegation <delegation-id>
+swarmcraft auth login --email you@example.com
+swarmcraft projects list
 ```
 
-## Operate Locally
+Login prompts for your password and any required verification code. Your CLI session is saved in `~/.swarmcraft/cli-session.json`; keep this file private.
 
-Operate is a starting path for operational work, not a third application-generation route. The seeded `swarmcraft-work` skill completes useful work and maintains terminology, knowledge, systems, and domain records. `swarmcraft-automate` considers bounded repeatability, including after one suitable task; `swarmcraft-formalise` prepares a reviewed application opportunity. Seeding all three does not execute them, approve automation, upload evidence, or transfer record ownership to a generated app.
+From your project's local Git repository, check your setup:
 
 ```bash
-swarmcraft auth login
-swarmcraft operate init --workspace /path/to/repository --agent-provider codex
-swarmcraft operate init --workspace /path/to/existing-repository --agent-provider copilot --adopt
-swarmcraft operate validate --workspace /path/to/repository --json
-swarmcraft operate status --workspace /path/to/repository --json
+swarmcraft doctor --workspace . --agent-provider codex
 ```
 
-`operate init` creates a new directory/Git repository or reconciles an existing Operate seed. A nonempty unseeded directory requires `--adopt`. It previews the shared seed before writing, rejects nested Git roots, unsafe filesystem links, staged changes to affected files, owner-edited generated-file conflicts, and unsupported versions. Unrelated dirty and staged work is preserved. All three Operate skills are seeded; start with Work. After validation it commits only exact seed content and approved removals as `SwarmCraft: Initialize or reconcile Operate`. Owner-edited records and ignored data are excluded; unchanged retries create no empty commit. Git identity, signing or hook failures leave files available with `OPERATE_SEED_COMMIT_FAILED`; fix Git and rerun. It never pushes, executes an agent, or writes to third-party systems.
-
-Initialization validates the saved CLI session against `GET /auth/me` before creating or modifying the target. Expired sessions use the existing refresh flow. The API origin comes from the saved session; there is no workspace-controlled API override. Credentials remain in the existing owner-only session file. Initial session/connectivity failure leaves the target untouched.
-
-Seed activities are reported through `POST /telemetry/operate-events` with closed classifications and a random occurrence UUID. The UUID and new/adopted classification are stored in ignored `.swarmcraft/runs/operate-init.json` so rerunning initialization reuses the same occurrence. Reporting failure produces a visible warning and does not undo local work; rerun initialization to retry. There is no background uploader or server registration. `--client-surface vscode-extension` is available for extension delegation.
-
-Validation and status are offline and use `@swarmcraft/operation-contract` for model/record checks, reviewed knowledge links, and formalisation digests. They also report ignored authoritative files and tracked raw/scratch files without exposing file contents or ignore patterns. Inventory is capped at 20,000 paths, individual text reads at 2 MB, and loaded evidence at 20 MB. Output includes only safe codes, capabilities, version, and evidence states. Discovery/project presence indicates local artifacts, not verified server connectivity. Automation presence does not imply approved readiness; repeatability remains `NOT_ASSESSED`.
-
-Both commands accept `--json`. Exit codes are 0 for success, 2 for sign-in required, 3 for invalid/missing operation evidence, 4 for workspace/option/conflict failures, 5 for session-verification connectivity failure, and 130 for cancellation. After interruption, rerun initialization to reconcile; seed state is written last and owner edits are preserved.
-
-## Agent Providers And Local Models
-
-SwarmCraft does not require a particular hosted model. The CLI delegates each packet stage to the selected Codex or GitHub Copilot CLI, and `--agent-command` can override the default provider command to select any model that the underlying agent supports. This includes local models served by Ollama.
-
-Before starting a local-model run, start Ollama and pull an agent-capable coding model. Local models used through GitHub Copilot CLI must support tool calling and streaming; a large context window is strongly recommended. Model capability and output quality vary, so begin with one task and a bounded request count.
-
-Run GitHub Copilot CLI against a local Ollama model without a GitHub-hosted model request:
+Replace `<project-id>` with an ID from the project list, then run one task:
 
 ```bash
 swarmcraft one-shot \
   --project <project-id> \
-  --workspace <path> \
-  --agent-provider copilot \
-  --agent-command 'COPILOT_PROVIDER_BASE_URL=http://localhost:11434/v1 COPILOT_MODEL=qwen3-coder:30b COPILOT_OFFLINE=true copilot --allow-all-tools --no-ask-user -p {command}' \
+  --workspace . \
+  --agent-provider codex \
   --task-limit 1 \
-  --max-agent-requests 1
+  --max-agent-requests 100 \
+  --commit-policy done
 ```
 
-Run Codex CLI directly against Ollama:
+This prepares repository guidance and task files, runs the agent, and syncs task updates to SwarmCraft. Accepted tasks move to `done`; `--commit-policy done` creates a local commit for each completed task. Omit that option to leave changes uncommitted. Review the resulting changes before sharing them.
+
+The CLI refuses a dirty workspace by default. Use `--allow-dirty` only when you intend to include existing local changes in the run. The request limit bounds agent calls, not monetary cost.
+
+For preparation without running an agent:
 
 ```bash
-swarmcraft one-shot \
-  --project <project-id> \
-  --workspace <path> \
-  --agent-provider codex \
-  --agent-command 'codex exec --sandbox workspace-write --oss --local-provider ollama --model qwen3-coder:30b {command}' \
-  --task-limit 1 \
-  --max-agent-requests 1
+swarmcraft init --project <project-id> --workspace . --agent-provider codex
 ```
 
-Replace `qwen3-coder:30b` with a locally installed model name from `ollama list`. The CLI intentionally gives agent subprocesses a restricted environment, so local, non-secret provider settings are included in the trusted command template above. Never place API keys or other secrets in `--agent-command`; for authenticated providers, use `--agent-env-file` with `--agent-api-key-env-name`.
+`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.
+
+## Choose an agent
+
+- **Codex:** use `--agent-provider codex`.
+- **GitHub Copilot:** use `--agent-provider copilot`.
+- **SwarmCraft Managed AI:** use `--agent-provider managed` with `one-shot`. The CLI shows your credit balance and an estimated stage range before starting. If credits run out, add credits and resume the blocked run.
+- **Custom commands and local models:** `--agent-command` overrides the provider command and supports models available through your agent, including local models. The template is executed through a shell, so use only commands you trust. Keep secrets out of command text; use `--agent-env-file` with `--agent-api-key-env-name` for provider credentials.
 
-## Command Workflows
+Codex, Copilot, and custom providers use your own provider setup and are outside the Managed AI fee.
 
-SwarmCraft Setup is the supported macOS and Windows foundation path before using this experienced terminal client. Interactive CLI login remains the explicit AAA V2 email fallback: it conceals password input, prompts for optional policy-required TOTP step-up, and keeps the restricted recovery-code path out of command history. GitHub, Google, and passkey sign-in remain browser-owned web and VS Code flows.
+## Inspect and resume work
 
-`swarmcraft init` validates the workspace git state, seeds the shared SwarmCraft repo guidance files, materializes non-done task packets, links those packets back to SwarmCraft, and prints the next commands.
+Use the run ID printed by the CLI:
+
+```bash
+swarmcraft status --run <run-id> --workspace .
+swarmcraft resume --run <run-id> --workspace .
+```
 
-Repository seeding uses the same monotonic template-set contract as the VS Code extension. A newer CLI adds missing skills and updates unchanged generated guidance, preserves owner edits as conflicts, removes only unchanged retired files, and never downgrades guidance written by a newer client. Project seeding leaves these changes uncommitted for normal review; Operate initialization instead creates a scoped local checkpoint. New one-shot runs reconcile before agent execution; resumed runs retain their existing run guidance rather than reseeding midway through the run.
+Run records and agent logs are stored in `.swarmcraft/runs/<run-id>/`, including `manifest.json` and the `logs/` directory. Treat these files as potentially sensitive.
 
-The task contract is a clean cutover from the earlier project-ticket format. Upgrade the API, CLI, and VS Code extension together; old `ticketId` packet files and `--ticket` flags are not accepted. Preserve any owner-authored notes, remove the retired generated packet files, and run `swarmcraft init` again to materialize current `taskId` packets from the board.
+If a run reached its request limit, raise the total ceiling when resuming:
 
-`swarmcraft discovery prepare` is projectless and deterministic. It requires the versioned discovery binding, `.swarmcraft/discovery.sources.json`, current selected-source digests, and all nine curated documents to be reviewed or explicitly not applicable. Repeated `--source` arguments must exactly match the aggregate owner-confirmed text projection when supplied by the extension. Empty, draft, unresolved, stale-sidecar, binary, secret-bearing, oversized, or mismatched preparation is blocked before upload.
+```bash
+swarmcraft resume --run <run-id> --workspace . --max-agent-requests 200
+```
 
-Preparation prints content-safe milestones as review state is checked, selected inputs are frozen, safety checks pass, the immutable digest is created, and the preview becomes ready. It normally completes in seconds and does not show a provider timer or artificial percentage.
+## Other workflows
 
-The CLI freezes the nine reviewed curated documents plus the exact selected `.md`/`.txt` sources and valid Markdown sidecars. It preserves the exact text and records roles, review states, sizes, SHA-256 digests, and sidecar provenance, then publishes atomically under `.swarmcraft/discovery-packages/<digest>/`. The preview lists exactly what may leave the machine. Reviewed curated documents are authoritative; selected sources are supporting evidence.
+For local operational work, initialize Work, Automate, and Formalise skills:
 
-Run diagnostics contain only schema version, phase, error class, timestamps, counts, byte/token estimates, and support codes—never document text or source paths. Durable feedback distinguishes incomplete discovery, stale input, cancellation, invalid packages, and internal failures. Support bundles exclude paths and Discovery Package content.
+```bash
+swarmcraft operate init --workspace /path/to/repository --agent-provider codex
+swarmcraft operate validate --workspace /path/to/repository
+swarmcraft operate status --workspace /path/to/repository
+```
 
-`swarmcraft discovery validate` reruns deterministic package and local-staleness checks without launching a provider. Untracked and ignored owner-selected text is preserved and allowed but remains the owner's backup responsibility. A failed run never truncates, summarizes, or silently drops content: correct the reported review/source issue and prepare again.
+Use `--adopt` to initialize an existing nonempty repository. Initialization previews the files and creates a local commit containing the seed changes. It preserves owner edits and does not push or run an agent. Validation and status work offline; both accept `--json`.
 
-`swarmcraft one-shot` bootstraps the workspace, runs the doing lane through the selected agent provider, syncs packet updates back to SwarmCraft, writes `.swarmcraft/runs/<run-id>/manifest.json`, streams progress to the terminal, writes agent logs under `.swarmcraft/runs/<run-id>/logs/`, and moves accepted work to `done` by default. With checking off, the driver ignores the reusable implementation skill's normal checking handoff, syncs its evidence, moves the task directly to `done`, commits when requested, and continues. Before synchronization, the CLI reloads the server-authoritative board and retries bounded optimistic-revision conflicts, allowing one-shot to run while the VS Code extension is open and observing the same packets. Customer one-shots should normally pair this with `--commit-policy done` so each completed task creates a local commit. Use `--checking on` or `--reviewing on` only for internal validation runs that deliberately need those extra lanes.
+For a workspace that has completed [Deep Discovery review](https://swarmcraft.ai/docs/discover-and-plan/complete-deep-discovery), prepare and validate its package:
 
-Choose `--agent-provider managed` to use SwarmCraft-managed AI. The CLI shows the current
-credit balance and estimated stage range before starting, then consumes measured credits one
-provider call at a time. Provider credentials, model selection, prices, and settlement remain on
-the API; prompts, repository source, and provider responses are not written to billing records.
-If the next bounded call cannot be funded, the local run is marked blocked and can be resumed
-after credits are added. Codex, Copilot, and custom customer-supplied providers remain outside
-the Managed AI fee.
+```bash
+swarmcraft discovery prepare --workspace .
+swarmcraft discovery validate --workspace .
+```
 
-For interface-bearing packets, the generated `swarmcraft-do` contract owns design conformance even when checking is off: it resolves the owner-controlled locator, uses applicable system capabilities, covers relevant states, runs existing required design commands, and records exact evidence in packet notes. A failing required deterministic design gate must leave doing incomplete. One-shot does not install design tooling, infer authority to mutate the design system, or treat unavailable visual evidence as passing.
+Preparation requires reviewed discovery documents and confirmed source selections. It creates a local package and a preview of the selected content; upload requires separate consent. If review or source checks fail, correct the reported issue and prepare again.
 
-Useful safety and support commands:
+## Help and troubleshooting
 
 ```bash
-swarmcraft one-shot --project <project-id> --workspace <path> --agent-provider codex --max-agent-requests 100
-swarmcraft one-shot --project <project-id> --workspace <path> --agent-provider custom --agent-command '<command with {command}>' --agent-api-key-env-name MY_AGENT_KEY
-swarmcraft doctor --workspace <path> --agent-provider codex
-swarmcraft support-bundle --run <run-id> --workspace <path>
+swarmcraft --help
+swarmcraft one-shot --help
+swarmcraft doctor --workspace . --agent-provider codex
+swarmcraft support-bundle --run <run-id> --workspace .
 ```
 
-VS Code uses a 100-request default and checks the unfinished board before launch. When the selected lane policy could require more, it asks the operator to approve a sufficient limit before starting. A stopped run can extend its recorded ceiling with `swarmcraft resume --run <run-id> --workspace <path> --max-agent-requests <n>`.
+Run `swarmcraft auth login` again if your session has expired. For Discovery diagnostics, use `swarmcraft discovery support-bundle --workspace . --run <run-id>`.
+
+Support bundles redact credentials; Discovery bundles exclude source and package content. Review any diagnostic files before sharing them.
+
+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).

package/dist/main.cjs

@@ -66770,7 +66770,7 @@ var import_packet_workflow6 = __toESM(require_dist(), 1);
 // package.json
 var package_default = {
   name: "@swarmcraftai/cli",
-  version: "0.5.0",
+  version: "0.5.1",
   description: "Prepare repositories and run packet-based SwarmCraft agent workflows from the terminal.",
   license: "SEE LICENSE IN LICENSE.txt",
   type: "module",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmcraftai/cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Prepare repositories and run packet-based SwarmCraft agent workflows from the terminal.",
   "license": "SEE LICENSE IN LICENSE.txt",
   "type": "module",