soturail 0.3.3 → 0.4.1

package/dist/core/worktree-manager.js

@@ -0,0 +1,55 @@
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { promisify } from "node:util";
+import { getWorkspacePaths, relativeToRoot } from "./config.js";
+const execFileAsync = promisify(execFile);
+export function safeBranchName(id) {
+    return `soturail/${id.replace(/[^a-zA-Z0-9._-]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase()}`;
+}
+export async function planWorktree(root, workflowId, dryRun = true) {
+    const paths = getWorkspacePaths(root);
+    const branch = safeBranchName(workflowId);
+    const worktreePath = path.join(paths.worktreesDir, workflowId);
+    const commands = [
+        `git worktree add -b ${branch} ${relativeToRoot(root, worktreePath)}`,
+        `git worktree remove ${relativeToRoot(root, worktreePath)}`
+    ];
+    const inGit = await isInsideGit(root);
+    if (!inGit) {
+        return {
+            available: false,
+            dryRun,
+            branch,
+            worktreePath,
+            commands,
+            message: dryRun
+                ? "Dry-run only; Git repository not detected, so no worktree would be created."
+                : "Git repository not detected; use non-worktree workflow state."
+        };
+    }
+    if (!dryRun) {
+        await fs.mkdir(paths.worktreesDir, { recursive: true });
+        await execFileAsync("git", ["worktree", "add", "-b", branch, worktreePath], { cwd: root, windowsHide: true });
+    }
+    return {
+        available: true,
+        dryRun,
+        branch,
+        worktreePath,
+        commands,
+        message: dryRun
+            ? "Dry-run only; no worktree created, pushed, merged or deleted."
+            : "Local worktree created. SotuRail will not push, merge or delete it automatically."
+    };
+}
+async function isInsideGit(root) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--is-inside-work-tree"], { cwd: root, windowsHide: true, timeout: 3000 });
+        return stdout.trim() === "true";
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=worktree-manager.js.map

package/dist/core/worktree-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worktree-manager.js","sourceRoot":"","sources":["../../src/core/worktree-manager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,QAAQ,IAAI,EAAE,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,MAAM,aAAa,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;AAW1C,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,OAAO,YAAY,EAAE,CAAC,OAAO,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;AAClG,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,IAAY,EAAE,UAAkB,EAAE,MAAM,GAAG,IAAI;IAChF,MAAM,KAAK,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IACtC,MAAM,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,UAAU,CAAC,CAAC;IAC/D,MAAM,QAAQ,GAAG;QACf,uBAAuB,MAAM,IAAI,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE;QACrE,uBAAuB,cAAc,CAAC,IAAI,EAAE,YAAY,CAAC,EAAE;KAC5D,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,SAAS,EAAE,KAAK;YAChB,MAAM;YACN,MAAM;YACN,YAAY;YACZ,QAAQ;YACR,OAAO,EAAE,MAAM;gBACb,CAAC,CAAC,6EAA6E;gBAC/E,CAAC,CAAC,+DAA+D;SACpE,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxD,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IAChH,CAAC;IACD,OAAO;QACL,SAAS,EAAE,IAAI;QACf,MAAM;QACN,MAAM;QACN,YAAY;QACZ,QAAQ;QACR,OAAO,EAAE,MAAM;YACb,CAAC,CAAC,+DAA+D;YACjE,CAAC,CAAC,mFAAmF;KACxF,CAAC;AACJ,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,IAAY;IACrC,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,aAAa,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QACvI,OAAO,MAAM,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/docs/agents.md

@@ -0,0 +1,46 @@
+# Agent Integrations
+
+SotuRail provides reviewed, project-local agent integration exports for Claude, Codex, Gemini, Cursor, Antigravity and generic agents.
+
+```bash
+soturail agents list
+soturail agents doctor
+soturail agents export --agent all
+soturail agents install --agent claude --mode mcp --dry-run
+soturail agents install --agent claude --mode safe-hooks --dry-run
+soturail agents install --agent codex --mode prompt-only --dry-run
+soturail agents install --agent cursor --mode rules --dry-run
+soturail agents uninstall --agent claude --dry-run
+```
+
+Exports are written under `.soturail/exports/agents/<agent>/`. They are meant to be reviewed before use.
+
+## Safe Defaults
+
+- Install commands support `--dry-run`.
+- Existing project files get `.soturail.bak` backups before modification.
+- Unknown global app config locations are not modified.
+- Antigravity support is prompt-only/context-pack unless a stable local config format is reviewed.
+- SotuRail does not enable arbitrary shell execution through MCP.
+
+## Doctor Guidance
+
+In a clean project, `soturail agents doctor` points users toward the safest setup order:
+
+```bash
+soturail context pack --target all
+soturail agents export --agent all
+soturail mcp smoke
+soturail workflow new "Implement feature"
+```
+
+If context packs or exports already exist, the doctor omits those setup steps and keeps the remaining checks visible.
+
+## Outputs
+
+- Claude: `CLAUDE.md`, `mcp-config.json`, `safe-hooks.md`, `context-pack.md`.
+- Codex: `AGENTS.md`, `context-pack.md`, `prompt-only.md`.
+- Gemini: `GEMINI.md`, `context-pack.md`, `prompt-only.md`.
+- Cursor: `cursor-rules.md`, `context-pack.md`, `prompt-only.md`.
+- Antigravity: `context-pack.md`, `prompt-only.md`.
+- Generic: `context-pack.md`, `prompt-only.md`.

package/docs/benchmarking.md

@@ -22,14 +22,15 @@ The suite groups results as:
 - cache stability;
 - native engine availability/performance when available;
 - skill rail validation/export;
-- MCP resource listing/reading;
+- MCP resource listing/reading/smoke;
 - context pack generation;
-- agent hook export;
+- agent hook and agent integration export;
+- Workflow Rail dry-run state;
 - memory approval workflow.
 
 Terminal reducer cases include npm install noise, npm test success, Vitest failures, TypeScript diagnostics, git diff/status noise, Docker logs, ESLint failures, Vite/Next build output, Java stack traces, Maven/Gradle failures, JSON/tool payload output, tiny-output overhead and dedupe fixtures.
 
-Each v0.3.2 reducer case reports:
+Each reducer and integration case reports:
 
 - `raw_tokens`;
 - `reduced_tokens`;

package/docs/comparisons.md

@@ -28,8 +28,10 @@ MemPalace-like memory/evidence ideas are related. SotuRail uses local JSONL memo
 
 Nicole-style knowledge-to-rules workflows are related. SotuRail has `ingest` and `rules` with future hardened PDF extraction.
 
-## Skills And Workflow Orchestration
+## Skills, Agent Integrations And Workflow Orchestration
 
-Agent-skills and SkillsMP-like ecosystems are related to Skill Rail exports. Compozy, Superpowers and OpenSpec-style orchestration are future Workflow Rail territory.
+Agent-skills and SkillsMP-like ecosystems are related to Skill Rail exports. SotuRail exports prompt/context files and MCP snippets for Claude, Codex, Gemini, Cursor, Antigravity and generic agents without claiming host-native superiority.
+
+Compozy, Superpowers and OpenSpec-style orchestration are related to Workflow Rail. SotuRail's Workflow Rail is a local state machine with optional Git worktree isolation; it does not push, merge or delete user work automatically.
 
 SotuRail should not be described as better than these projects unless a specific local benchmark proves a specific metric.

package/docs/context-packs.md

@@ -7,7 +7,9 @@ soturail context pack --target claude
 soturail context pack --target codex
 soturail context pack --target gemini
 soturail context pack --target cursor
+soturail context pack --target antigravity
 soturail context pack --target generic
+soturail context pack --target all
 soturail context explain
 soturail context doctor
 ```
@@ -20,6 +22,7 @@ Common generated files:
 - `.soturail/context/codex-context.md`
 - `.soturail/context/gemini-context.md`
 - `.soturail/context/cursor-context.md`
+- `.soturail/context/antigravity-context.md`
 - `.soturail/context/generic-context.md`
 
 Stable-cache order:
@@ -32,8 +35,12 @@ Stable-cache order:
 6. Approved specs.
 7. Approved memory.
 8. Skills summary.
-9. Dynamic footer with timestamps, current commit, raw IDs and recent command notes.
+9. Workflow summary.
+10. MCP resource list.
+11. Dynamic footer with timestamps, current commit, raw IDs and recent command notes.
 
 Dynamic data never appears before stable blocks.
 
 Review a generated pack before pasting it into an agent. Dynamic footer data can include recent command status, raw IDs or branch details.
+
+`soturail init` scaffolds context-pack examples under `examples/context-packs/`, and v0.4 agent examples can be paired with `soturail context pack --target all` for a clean first setup.

package/docs/hooks/claude.md

@@ -1,6 +1,6 @@
 # Claude Hooks
 
-SotuRail v0.3.0 includes conservative Claude safe-hooks and MCP guidance.
+SotuRail includes conservative Claude safe-hooks and MCP guidance.
 
 ```bash
 soturail hooks install --agent claude --mode safe-hooks --dry-run

package/docs/hooks/mcp.md

@@ -7,4 +7,4 @@ soturail hooks install --agent claude --mode mcp --dry-run
 soturail mcp serve --transport stdio
 ```
 
-Review generated instructions before enabling. SotuRail's MCP server exposes read-only resources and safe tools; it does not expose arbitrary shell execution in v0.3.0.
+Review generated instructions before enabling. SotuRail's MCP server exposes read-only resources and safe tools; it does not expose arbitrary shell execution.

package/docs/hooks.md

@@ -1,6 +1,6 @@
 # Agent Hooks
 
-SotuRail hook support is cautious. Claude gets conservative safe-hooks and MCP guidance first; Codex, Gemini and Cursor use prompt-only fallbacks when stable native hook APIs are unavailable.
+SotuRail hook support is cautious. Claude gets conservative safe-hooks and MCP guidance first; Codex, Gemini, Cursor and Antigravity use prompt-only fallbacks when stable native hook APIs are unavailable.
 
 ```bash
 soturail hooks list
@@ -10,9 +10,12 @@ soturail hooks install --agent claude --mode mcp
 soturail hooks install --agent codex --mode prompt-only
 soturail hooks install --agent gemini --mode prompt-only
 soturail hooks install --agent cursor --mode prompt-only
+soturail hooks install --agent antigravity --mode prompt-only --dry-run
 soturail hooks uninstall --agent claude
+soturail hooks uninstall --agent claude --dry-run
 soturail hooks export --agent claude
 soturail hooks export --agent codex
+soturail hooks export --agent antigravity
 ```
 
 Installers create backups before modifying existing files. Dry-run prints every file that would change. If a host config location is uncertain, SotuRail generates prompt-only guidance instead of guessing.
@@ -24,6 +27,6 @@ Always review generated hooks before enabling them. SotuRail should never auto-i
 `soturail hooks doctor` prints safe modes and next commands:
 
 - Claude: `safe-hooks` and `mcp`.
-- Codex, Gemini and Cursor: `prompt-only`.
+- Codex, Gemini, Cursor and Antigravity: `prompt-only`.
 - Start with `--dry-run`.
 - Export guidance with `soturail hooks export --agent claude`.

package/docs/mcp.md

@@ -5,6 +5,8 @@ SotuRail includes a local MCP-compatible server over stdio using JSON-RPC 2.0 st
 ```bash
 soturail mcp doctor
 soturail mcp manifest
+soturail mcp config --agent generic
+soturail mcp smoke
 soturail mcp serve --transport stdio
 ```
 
@@ -58,3 +60,19 @@ Security defaults:
 - no `soturail.run` MCP tool by default;
 - raw log expansion redacts probable secrets unless `allow_raw=true`;
 - provider cache hits are never invented.
+
+## Host Config Helpers
+
+`soturail mcp config --agent claude|cursor|generic` writes a reviewed stdio snippet under `.soturail/exports/mcp/<agent>/mcp-config.json`.
+
+The snippet runs:
+
+```bash
+soturail mcp serve --transport stdio
+```
+
+It does not assume a global application config path. Review it before adding it to an agent host.
+
+`soturail mcp smoke` verifies `initialize`, `resources/list`, `resources/read` and `tools/list` without starting a long-running process, and confirms `soturail.run` is not exposed by default.
+
+`soturail init` scaffolds copyable MCP JSON-RPC examples under `examples/mcp/`.

package/docs/metrics.md

@@ -29,13 +29,14 @@ SotuRail metrics are local, append-only and transparent.
 - real provider cache hits only if imported metadata exists.
 - response compression reduction and preservation counts;
 - rules ingestion and validation counts;
-- benchmark fixture measurements.
+- benchmark fixture measurements;
+- agent export, MCP smoke and Workflow Rail benchmark measurements.
 
 Small command outputs can be larger after SotuRail adds raw recovery metadata. When that happens, `compression_effective` is `false` and the CLI prints the small-output warning instead of hiding the overhead.
 
 ## Token Estimation
 
-v0.1.0 uses:
+SotuRail uses:
 
 ```text
 Math.ceil(text.length / 4)

package/docs/mvp.md

@@ -1,6 +1,6 @@
 # MVP Scope
 
-SotuRail v0.1.0 validates the core foundation:
+SotuRail validates the core local-first foundation:
 
 - local workspace creation;
 - cross-platform file scanning with deny rules;

package/docs/release-workflow.md

@@ -1,6 +1,6 @@
 # Release Workflow
 
-SotuRail releases should be repeatable and evidence-backed. v0.3.0 exposes release helpers through `soturail release`.
+SotuRail releases should be repeatable and evidence-backed. Release helpers are exposed through `soturail release`.
 
 ## Check
 
@@ -19,6 +19,7 @@ The check also verifies:
 - expected package files are present and forbidden generated files are absent;
 - `CHANGELOG.md` and `RELEASE_NOTES_vX.Y.Z.md` exist for the local version;
 - README install instructions and `LICENSE` exist.
+- required GitHub CI and community files exist under `.github/`.
 
 You can run only the package verification gate with:
 
@@ -30,6 +31,8 @@ This catches stale generated version files that local source checks might miss.
 
 As of v0.3.3, release verification installs the packed `.tgz` into a clean temporary project and executes the CLI from `node_modules/soturail/dist/cli.js`. It does not call global `soturail`, `npx soturail` or `npm exec --package=soturail`, which avoids npm cache/global CLI false positives.
 
+Keep using this packed-package gate before publishing. `npm exec --package=soturail@<version>` is a post-publish registry verification, not the pre-publish source of truth.
+
 ## Publish
 
 ```bash

package/docs/security-model.md

@@ -41,9 +41,13 @@ soturail expand <raw_id> --allow-raw --yes
 
 MCP raw-log expansion also redacts probable secrets by default unless `allow_raw=true` is explicitly passed.
 
-## MCP And Skills
+## MCP, Skills, Agents And Workflows
 
-The v0.3.0 MCP server does not expose arbitrary shell execution. Skill Rail exports are local files for human review; SotuRail does not auto-install unreviewed third-party skills.
+The MCP server does not expose arbitrary shell execution. Skill Rail exports are local files for human review; SotuRail does not auto-install unreviewed third-party skills.
+
+Agent installs are dry-run-first and backup-first. Unknown global host config locations are not modified automatically.
+
+Workflow Rail does not push, merge or delete worktrees automatically. Worktree support is local and review-oriented.
 
 ## Limitations
 

package/docs/usage.md

@@ -8,6 +8,8 @@ soturail init
 
 Creates `.soturail/` and starter docs without overwriting existing files.
 
+The scaffold includes docs and examples for agents, MCP, context packs, hooks, skills and workflows.
+
 ## Index
 
 ```bash
@@ -63,7 +65,7 @@ soturail native doctor
 soturail bench compare-engines
 ```
 
-## v0.3.0 Workflows
+## Skill, MCP And Context Workflows
 
 ```bash
 soturail skills init demo-skill
@@ -82,6 +84,23 @@ soturail hooks install --agent claude --mode safe-hooks --dry-run
 soturail release check
 ```
 
-MCP is local stdio JSON-RPC style transport and does not expose arbitrary shell execution in v0.3.0.
+MCP is local stdio JSON-RPC style transport and does not expose arbitrary shell execution.
 
 For a first clean-folder walkthrough, see [first-real-workflow.md](first-real-workflow.md).
+
+## Agent And Workflow Rail Commands
+
+```bash
+soturail agents list
+soturail agents doctor
+soturail agents export --agent all
+soturail agents install --agent claude --mode mcp --dry-run
+soturail mcp config --agent generic
+soturail mcp smoke
+soturail context pack --target all
+soturail workflow new "Implement feature"
+soturail workflow list
+soturail workflow start <id> --worktree --dry-run
+```
+
+Agent exports are written to `.soturail/exports/agents/`. Workflow Rail stores local task state under `.soturail/workflows/`.

package/docs/windows.md

@@ -78,7 +78,10 @@ PowerShell examples:
 ```powershell
 soturail mcp doctor
 soturail mcp manifest
+soturail mcp smoke
+soturail mcp config --agent generic
 soturail context pack --target generic
+soturail context pack --target all
 ```
 
 CMD examples:
@@ -86,11 +89,50 @@ CMD examples:
 ```bat
 soturail mcp doctor
 soturail mcp manifest
+soturail mcp smoke
+soturail mcp config --agent generic
 soturail context pack --target generic
+soturail context pack --target all
 ```
 
 When testing `soturail mcp serve --transport stdio`, send one JSON object per line. See `examples\mcp\` for payloads.
 
+## Agent And Workflow Commands
+
+PowerShell:
+
+```powershell
+soturail agents doctor
+soturail agents export --agent all
+soturail workflow new "Try SotuRail"
+```
+
+CMD:
+
+```bat
+soturail agents doctor
+soturail agents export --agent all
+soturail workflow new "Try SotuRail"
+```
+
+Quote workflow titles and paths with spaces.
+
+## Clean Project Flow
+
+PowerShell and CMD:
+
+```powershell
+soturail init
+soturail context pack --target all
+soturail agents doctor
+soturail agents export --agent all
+soturail mcp smoke
+soturail workflow new "Try SotuRail"
+soturail workflow list
+```
+
+`soturail init` creates agent and workflow examples without overwriting existing files.
+
 ## Safety
 
 SotuRail blocks destructive command shapes through `soturail run`, including `rm -rf`, `sudo`, `del /s`, downloaded script piping and automatic `git push`.
@@ -107,7 +149,7 @@ npm run release:check
 
 `package.json`, `package-lock.json`, `node dist/cli.js --version`, the npm tarball name, the changelog and the release notes must all agree on the same version.
 
-v0.3.2 also verifies the packed tarball by installing it in a temporary clean project and running the installed CLI. This helps catch stale generated version files before publish.
+SotuRail also verifies the packed tarball by installing it in a temporary clean project and running the installed CLI. This helps catch stale generated version files before publish.
 
 Use browser-based npm login when needed:
 

package/docs/workflow-rail.md

@@ -1,32 +1,59 @@
 # Workflow Rail
 
-Workflow Rail is planned for v0.4.0. It is not implemented in v0.3.x.
+Workflow Rail is a local task state system for SotuRail. It stores auditable workflow artifacts under `.soturail/workflows/` and can optionally plan or create local Git worktrees.
 
-The goal is to describe repeatable engineering workflows as local, auditable artifacts that can later export into Skill Rail or an MCP server.
+```bash
+soturail workflow new "Implement feature"
+soturail workflow list
+soturail workflow show <id>
+soturail workflow plan <id>
+soturail workflow start <id> --worktree --dry-run
+soturail workflow status <id>
+soturail workflow verify <id>
+soturail workflow close <id>
+soturail workflow cleanup --closed --dry-run
+```
 
-Planned commands:
+## State Machine
 
-```bash
-soturail workflow new <name>
-soturail workflow from-template <name>
-soturail workflow validate
-soturail workflow export skill
+Workflows use explicit states:
+
+- `draft`
+- `planned`
+- `active`
+- `verifying`
+- `ready_for_review`
+- `closed`
+- `blocked`
+
+## Storage
+
+Each workflow uses:
+
+```txt
+.soturail/workflows/<id>/
+├── workflow.yml
+├── plan.md
+├── tasks.md
+├── verification.md
+└── logs/
 ```
 
-## Security Requirements
+## Worktrees
+
+`soturail workflow start <id> --worktree --dry-run` prints a local worktree plan. If run without `--dry-run` inside a Git repository, SotuRail may create a local worktree under `.soturail/worktrees/<id>/`.
+
+Safety rules:
+
+- SotuRail does not push.
+- SotuRail does not merge.
+- SotuRail does not delete user work without explicit confirmation.
+- Rollback instructions are printed when worktrees are planned.
 
-- Keep generated workflows local-first by default.
-- Validate workflow files before execution or export.
-- Scan for prompt injection.
-- Scan for destructive shell commands.
-- Scan for secret exfiltration.
-- Scan for downloaded script execution such as `curl ... | sh` and `wget ... | bash`.
-- Require human approval before enabling generated workflows or exported skills.
+## Verification
 
-Workflow Rail should complement, not replace, the existing SotuRail rails: `soturail run`, raw log recovery, Knowledge-to-Rules, benchmarks, cache-normalized payloads and self-dogfooding reports.
+`soturail workflow verify <id>` only runs configured safe checks when they are explicit. Without configured checks, it prints a checklist instead of inventing commands.
 
-## Current Road
+## Cleanup
 
-- v0.3.1: real usage polish, installed workflow examples and clean-folder smoke tests.
-- v0.3.2: stronger reducers and deduplication.
-- v0.4.0: real agent integrations and Workflow Rail.
+`soturail workflow cleanup --closed --dry-run` previews closed workflow records that could be removed. It does not delete anything unless rerun with `--closed --yes` after review.

package/examples/agents/README.md

@@ -0,0 +1,11 @@
+# Agent Examples
+
+These examples show how to use SotuRail exports without modifying global agent configuration.
+
+```bash
+soturail agents doctor
+soturail agents export --agent all
+soturail mcp config --agent generic
+```
+
+Review generated files under `.soturail/exports/agents/` before enabling them in any agent host.

package/examples/agents/antigravity.md

@@ -0,0 +1,8 @@
+# Antigravity Example
+
+```bash
+soturail agents export --agent antigravity
+soturail context pack --target antigravity
+```
+
+SotuRail uses prompt-only/context-pack support for Antigravity unless a stable local config format is reviewed.

package/examples/agents/claude.md

@@ -0,0 +1,9 @@
+# Claude Example
+
+```bash
+soturail agents export --agent claude
+soturail mcp config --agent claude
+soturail hooks install --agent claude --mode safe-hooks --dry-run
+```
+
+Review `CLAUDE.md`, `mcp-config.json` and `safe-hooks.md` before copying anything into Claude Code settings.

package/examples/agents/codex.md

@@ -0,0 +1,8 @@
+# Codex Example
+
+```bash
+soturail agents export --agent codex
+soturail context pack --target codex
+```
+
+Use the generated `AGENTS.md` and context pack as project-local guidance. Do not route `git push` through `soturail run`.

package/examples/agents/cursor.md

@@ -0,0 +1,8 @@
+# Cursor Example
+
+```bash
+soturail agents export --agent cursor
+soturail agents install --agent cursor --mode rules --dry-run
+```
+
+Cursor rule exports are project-local and should be reviewed before writing to `.cursor/rules/`.

package/examples/agents/gemini.md

@@ -0,0 +1,8 @@
+# Gemini Example
+
+```bash
+soturail agents export --agent gemini
+soturail context pack --target gemini
+```
+
+Review `GEMINI.md` before adding it to a repository.

package/examples/workflows/README.md

@@ -0,0 +1,13 @@
+# Workflow Examples
+
+Workflow Rail stores local task state under `.soturail/workflows/`.
+
+```bash
+soturail workflow new "Fix bug"
+soturail workflow list
+soturail workflow plan <id>
+soturail workflow start <id> --worktree --dry-run
+soturail workflow verify <id>
+```
+
+SotuRail does not push, merge or delete worktrees automatically.

package/examples/workflows/bugfix-workflow.md

@@ -0,0 +1,11 @@
+# Bugfix Workflow
+
+```bash
+soturail workflow new "Fix parser bug"
+soturail workflow plan <id>
+soturail context pack --target codex
+soturail run npm test
+soturail workflow verify <id>
+```
+
+Keep evidence local and include raw IDs in the final review notes when useful.

package/examples/workflows/release-workflow.md

@@ -0,0 +1,9 @@
+# Release Workflow
+
+```bash
+soturail self all
+soturail release check
+npm pack --dry-run
+```
+
+Only create a GitHub release after npm publish succeeds and the published CLI version is verified.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soturail",
-  "version": "0.3.3",
+  "version": "0.4.1",
   "description": "Local-first context rails for AI coding agents: reversible terminal compression, progressive repo reading, SDD workflows, hooks, benchmarks, memory and cache-friendly payloads.",
   "type": "module",
   "bin": {