soturail 0.3.2 → 0.4.0

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 v0.4.0 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,7 +35,9 @@ 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.
 

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,17 @@ 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.

package/docs/metrics.md

@@ -29,7 +29,8 @@ 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.
 

package/docs/release-workflow.md

@@ -28,6 +28,10 @@ soturail release verify-package
 
 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.
+
+For v0.4.0 and later, 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

@@ -85,3 +85,20 @@ soturail release check
 MCP is local stdio JSON-RPC style transport and does not expose arbitrary shell execution in v0.3.0.
 
 For a first clean-folder walkthrough, see [first-real-workflow.md](first-real-workflow.md).
+
+## v0.4.0 Workflows
+
+```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,34 @@ 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.
+
 ## Safety
 
 SotuRail blocks destructive command shapes through `soturail run`, including `rm -rf`, `sudo`, `del /s`, downloaded script piping and automatic `git push`.
@@ -107,7 +133,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.
+v0.4.0 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,54 @@
 # 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 v0.4.0. 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>
+```
 
-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>/`.
 
-- 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.
+Safety rules:
 
-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 does not push.
+- SotuRail does not merge.
+- SotuRail does not delete user work without explicit confirmation.
+- Rollback instructions are printed when worktrees are planned.
 
-## Current Road
+## Verification
 
-- 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 verify <id>` only runs configured safe checks when they are explicit. Without configured checks, it prints a checklist instead of inventing commands.

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 v0.4.0 uses prompt-only/context-pack support for Antigravity. It does not assume a stable local config format.

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.2",
+  "version": "0.4.0",
   "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": {