@swarmcraftai/cli 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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.
+- Seeds and reconciles operational models, records, knowledge, and bounded automation guidance while preserving owner edits; initialization validates the result and creates a scoped local Git checkpoint without pushing.
+- Supports a private stdin session handoff from VS Code for Operate initialization, with session verification before workspace mutation and content-free, retryable activity reporting.
+- Validates approved operational formalisation and source digests when preparing Deep Discovery evidence, blocking stale or cancelled approvals.
+- Adds SwarmCraft-managed AI to one-shot workflows, including credit balance and stage estimates, measured per-call consumption, and resumable insufficient-credit outcomes. Customer-supplied Codex, Copilot, and custom providers remain supported.
+- Seeds versioned project environment requirements from structured build profiles and documents local-model execution through custom agent commands.
+- Requires the matching API credit, Managed AI, and Operate telemetry contracts; deploy the coordinated API and web release before publishing this client.
+
 ## 0.4.2
 
 - Reconciles generated repository skills through a monotonic, owner-preserving template-set contract before new one-shot runs, while retaining the recorded guidance for resumed runs.

package/README.md

@@ -1,121 +1,150 @@
 # SwarmCraft CLI
 
-SwarmCraft CLI prepares a local repository for a SwarmCraft project board and runs packet-based agent workflows from the terminal.
+[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.
 
-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.
+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.
 
-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.
+## Prerequisites
 
-## Package Shape
+- 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.
 
-- 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.
+On macOS and Windows, start with [SwarmCraft Setup](https://swarmcraft.ai/docs/set-up-and-connect/use-swarmcraft-setup) to prepare your environment.
 
-## Implemented Module Ownership
+## Install
 
-- `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/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.
+```bash
+npm install -g @swarmcraftai/cli
+swarmcraft --help
+```
 
-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.
+For one-off use, run `npx @swarmcraftai/cli --help`.
 
-## Distribution
+## Native Windows installation
 
-The first public distribution channel is npm:
+WSL is not required for the SwarmCraft CLI. In PowerShell:
 
-```bash
-npm install -g @swarmcraftai/cli
-swarmcraft --help
+```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
 ```
 
-One-off use is also supported:
+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.
 
-```bash
-npx @swarmcraftai/cli --help
+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.
+
+PowerShell uses different line continuation from Bash. Run the multiline examples below on one line, using `swarmcraft.cmd`, for example:
+
+```powershell
+swarmcraft.cmd one-shot --project YOUR_PROJECT_ID --workspace . --agent-provider codex --task-limit 1 --max-agent-requests 100 --commit-policy done
 ```
 
-Public publishing is owned by the release workflow in `.github/workflows/publish-cli.yml`. Run the local package smoke before publishing:
+## Run your first task
+
+Sign in and find your project ID:
 
 ```bash
-pnpm cli:release:smoke
+swarmcraft auth login --email you@example.com
+swarmcraft projects list
 ```
 
-## Local Development
+Login prompts for your password and any required verification code. Your CLI session is saved in `~/.swarmcraft/cli-session.json`; keep this file private.
 
-From the repo root:
+From your project's local Git repository, check your setup:
 
 ```bash
-pnpm cli:dev -- --help
-pnpm cli:check
+swarmcraft doctor --workspace . --agent-provider codex
 ```
 
-From this package:
+Replace `<project-id>` with an ID from the project list, then run one task:
 
 ```bash
-pnpm dev -- --help
-pnpm check
-pnpm release:smoke
+swarmcraft one-shot \
+  --project <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.
+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.
 
-## Current Commands
+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.
 
-Core commands:
+For preparation without running an agent:
 
 ```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 init --project <project-id> --workspace . --agent-provider codex
 ```
 
-Interactive login conceals password input. When MFA is enrolled, the same command securely prompts for the current authenticator code and offers a recovery-code fallback; secrets do not need to be placed in the command line.
+`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.
+
+Codex, Copilot, and custom providers use your own provider setup and are outside the Managed AI fee.
 
-`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.
+## Inspect and resume work
 
-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. The CLI leaves these repository changes uncommitted for normal review. New one-shot runs reconcile before agent execution; resumed runs retain their existing run guidance rather than reseeding midway through the run.
+Use the run ID printed by the CLI:
 
-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.
+```bash
+swarmcraft status --run <run-id> --workspace .
+swarmcraft resume --run <run-id> --workspace .
+```
+
+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.
+
+If a run reached its request limit, raise the total ceiling when resuming:
+
+```bash
+swarmcraft resume --run <run-id> --workspace . --max-agent-requests 200
+```
 
-`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.
+## Other workflows
 
-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.
+For local operational work, initialize Work, Automate, and Formalise skills:
 
-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.
+```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
+```
 
-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.
+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 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.
+For a workspace that has completed [Deep Discovery review](https://swarmcraft.ai/docs/discover-and-plan/complete-deep-discovery), prepare and validate its package:
 
-`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.
+```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).