soturail 0.2.3 → 0.3.1

package/docs/context-packs.md

@@ -0,0 +1,39 @@
+# Context Packs
+
+Context packs are target-aware Markdown payloads for AI coding agents.
+
+```bash
+soturail context pack --target claude
+soturail context pack --target codex
+soturail context pack --target gemini
+soturail context pack --target cursor
+soturail context pack --target generic
+soturail context explain
+soturail context doctor
+```
+
+Generated files live in `.soturail/context/`.
+
+Common generated files:
+
+- `.soturail/context/claude-context.md`
+- `.soturail/context/codex-context.md`
+- `.soturail/context/gemini-context.md`
+- `.soturail/context/cursor-context.md`
+- `.soturail/context/generic-context.md`
+
+Stable-cache order:
+
+1. Static SotuRail header.
+2. Governance files summary.
+3. Project config.
+4. Repo map summary.
+5. Approved rules.
+6. Approved specs.
+7. Approved memory.
+8. Skills summary.
+9. 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.

package/docs/examples/skills/README.md

@@ -0,0 +1,11 @@
+# Skill Examples
+
+Generate local examples with:
+
+```bash
+soturail skills init demo-skill
+soturail skills validate
+soturail skills export --target generic
+```
+
+Generated skills live in `.soturail/skills/` and exports live in `.soturail/exports/skills/`.

package/docs/first-real-workflow.md

@@ -0,0 +1,60 @@
+# First Real Workflow
+
+This guide starts from a clean folder and walks through the first useful SotuRail flow.
+
+## macOS, Linux, PowerShell
+
+```bash
+mkdir my-soturail-test
+cd my-soturail-test
+
+soturail init
+soturail index
+soturail context pack --target generic
+soturail skills init code-review
+soturail skills validate
+soturail skills export --target claude
+soturail mcp doctor
+soturail mcp manifest
+soturail run node --version
+soturail stats
+```
+
+## Windows CMD
+
+```bat
+mkdir my-soturail-test
+cd my-soturail-test
+soturail init
+soturail index
+soturail context pack --target generic
+soturail skills init code-review
+soturail skills validate
+soturail skills export --target claude
+soturail mcp doctor
+soturail mcp manifest
+soturail run node --version
+soturail stats
+```
+
+Do not paste Markdown fence labels such as `bat` into CMD. Paste only the command lines.
+
+## What should happen?
+
+- `.soturail/` is created without overwriting your files.
+- `docs/` and `examples/` starter files are created.
+- `.soturail/indexes/repo-map.json` and `tree.txt` are generated.
+- `.soturail/context/generic-context.md` is generated.
+- `.soturail/skills/code-review/` is created with a starter skill.
+- `soturail skills validate` should pass for the generated skill.
+- `.soturail/exports/skills/claude/` receives a reviewed export.
+- `soturail mcp doctor` reports stdio support and no arbitrary shell execution.
+- `soturail stats` reports local metrics.
+
+Stats may be zero in a fresh folder until you run commands through:
+
+```bash
+soturail run <command>
+```
+
+Raw command output can contain secrets. Keep `.soturail/raw` local and review logs before sharing them.

package/docs/hooks/claude.md

@@ -1,11 +1,13 @@
 # Claude Hooks
 
-SotuRail v0.2.1 includes a conservative Claude Code hook template.
+SotuRail v0.3.0 includes conservative Claude safe-hooks and MCP guidance.
 
 ```bash
-soturail hooks install claude --dry-run
-soturail hooks install claude
-soturail hooks uninstall claude
+soturail hooks install --agent claude --mode safe-hooks --dry-run
+soturail hooks install --agent claude --mode safe-hooks
+soturail hooks install --agent claude --mode mcp
+soturail hooks uninstall --agent claude
+soturail hooks export --agent claude
 soturail hooks prompt-only claude
 ```
 

package/docs/hooks/codex.md

@@ -7,9 +7,10 @@ SotuRail does not assume private Codex host hook APIs. The fallback rules descri
 Useful commands:
 
 ```bash
-soturail hooks install codex --dry-run
-soturail hooks install codex
-soturail hooks uninstall codex
+soturail hooks install --agent codex --mode prompt-only --dry-run
+soturail hooks install --agent codex --mode prompt-only
+soturail hooks uninstall --agent codex
+soturail hooks export --agent codex
 soturail hooks prompt-only codex
 ```
 

package/docs/hooks/cursor.md

@@ -7,9 +7,10 @@ Existing files are backed up before SotuRail adds its rules.
 Useful commands:
 
 ```bash
-soturail hooks install cursor --dry-run
-soturail hooks install cursor
-soturail hooks uninstall cursor
+soturail hooks install --agent cursor --mode prompt-only --dry-run
+soturail hooks install --agent cursor --mode prompt-only
+soturail hooks uninstall --agent cursor
+soturail hooks export --agent cursor
 soturail hooks prompt-only cursor
 ```
 

package/docs/hooks/gemini.md

@@ -7,9 +7,10 @@ The generated rules keep repository scans, progressive file reads and raw log re
 Useful commands:
 
 ```bash
-soturail hooks install gemini --dry-run
-soturail hooks install gemini
-soturail hooks uninstall gemini
+soturail hooks install --agent gemini --mode prompt-only --dry-run
+soturail hooks install --agent gemini --mode prompt-only
+soturail hooks uninstall --agent gemini
+soturail hooks export --agent gemini
 soturail hooks prompt-only gemini
 ```
 

package/docs/hooks/mcp.md

@@ -0,0 +1,10 @@
+# MCP Hook Integration
+
+Use MCP mode when an agent host supports reviewed local MCP server configuration.
+
+```bash
+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.

package/docs/hooks.md

@@ -1,26 +1,29 @@
 # Agent Hooks
 
-SotuRail hook support is cautious. Claude gets a conservative hook template first; Codex, Gemini and Cursor remain prompt-only fallbacks because host APIs are not all stable.
+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.
 
 ```bash
 soturail hooks list
 soturail hooks doctor
-soturail hooks install claude --dry-run
-soturail hooks install claude
-soturail hooks uninstall claude
-soturail hooks install all --dry-run
-soturail hooks prompt-only codex
+soturail hooks install --agent claude --mode safe-hooks --dry-run
+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 uninstall --agent claude
+soturail hooks export --agent claude
+soturail hooks export --agent codex
 ```
 
-Installers create backups before modifying existing files. If a host config location is uncertain, SotuRail generates prompt-only guidance instead of guessing.
+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.
 
-Claude install writes `.claude/settings.json` and hook scripts under `.claude/hooks/`. Dry-run prints every file that would change.
+Claude safe-hooks write `.claude/settings.json` and hook scripts under `.claude/hooks/`. The pre-tool hook blocks destructive command shapes and suggests `soturail run` for tests, builds and logs.
 
-Always review generated hooks before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts. Prompt-only fallback remains available for every host:
+Always review generated hooks before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.
 
-```bash
-soturail hooks prompt-only claude
-soturail hooks prompt-only codex
-soturail hooks prompt-only gemini
-soturail hooks prompt-only cursor
-```
+`soturail hooks doctor` prints safe modes and next commands:
+
+- Claude: `safe-hooks` and `mcp`.
+- Codex, Gemini and Cursor: `prompt-only`.
+- Start with `--dry-run`.
+- Export guidance with `soturail hooks export --agent claude`.

package/docs/mcp.md

@@ -0,0 +1,60 @@
+# MCP Server
+
+SotuRail includes a local MCP-compatible server over stdio using JSON-RPC 2.0 style messages. It is designed for local context access, not remote execution.
+
+```bash
+soturail mcp doctor
+soturail mcp manifest
+soturail mcp serve --transport stdio
+```
+
+The server exposes read-only resources such as the repo map, tree, rules, approved memory, self report, latest benchmarks and roadmap. It also exposes safe tools for indexing, progressive reads, formatting, rule checks, skill listing, context pack generation and raw log expansion.
+
+## Copyable JSON-RPC Examples
+
+Send one JSON object per line to `soturail mcp serve --transport stdio`.
+
+Initialize:
+
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"manual-smoke","version":"0.1.0"}}}
+```
+
+List resources:
+
+```json
+{"jsonrpc":"2.0","id":2,"method":"resources/list"}
+```
+
+Read the repo map:
+
+```json
+{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"soturail://repo-map"}}
+```
+
+List tools:
+
+```json
+{"jsonrpc":"2.0","id":4,"method":"tools/list"}
+```
+
+The same payloads are available under `examples/mcp/`.
+
+## Safe Tools
+
+Default tools include:
+
+- `soturail.index`
+- `soturail.read`
+- `soturail.format`
+- `soturail.rules.check`
+- `soturail.skills.list`
+- `soturail.context.pack`
+- `soturail.expand`
+
+Security defaults:
+
+- no arbitrary shell execution;
+- no `soturail.run` MCP tool by default;
+- raw log expansion redacts probable secrets unless `allow_raw=true`;
+- provider cache hits are never invented.

package/docs/release-checklist.md

@@ -9,6 +9,9 @@ Before publishing:
 - [ ] `npm test`
 - [ ] `npm audit --omit=dev`
 - [ ] `node dist/cli.js self all`
+- [ ] `node dist/cli.js skills --help`
+- [ ] `node dist/cli.js mcp --help`
+- [ ] `node dist/cli.js context --help`
 - [ ] `npm pack --dry-run`
 - [ ] `npm run release:check`
 - [ ] `node dist/cli.js --version` matches `package.json`.

package/docs/release-workflow.md

@@ -1,6 +1,6 @@
 # Release Workflow
 
-SotuRail releases should be repeatable and evidence-backed. The release helper lives at `scripts/release.mjs`.
+SotuRail releases should be repeatable and evidence-backed. v0.3.0 exposes release helpers through `soturail release`.
 
 ## Check
 
@@ -18,27 +18,10 @@ The check also verifies:
 - `CHANGELOG.md` and `RELEASE_NOTES_vX.Y.Z.md` exist for the local version;
 - README install instructions and `LICENSE` exist.
 
-## Prepare
-
-```bash
-npm run release:prepare -- --version X.Y.Z
-```
-
-Prepare mode:
-
-- validates the version argument;
-- updates `package.json`, `package-lock.json` and CLI version text;
-- updates `CHANGELOG.md`;
-- creates `RELEASE_NOTES_vX.Y.Z.md`;
-- runs validation;
-- commits `chore(release): prepare vX.Y.Z`;
-- pushes `main`;
-- never publishes to npm.
-
 ## Publish
 
 ```bash
-npm run release:publish -- --version X.Y.Z
+npm run release:publish -- X.Y.Z
 ```
 
 Publish mode refuses to publish if build, tests, release preflight or runtime audit fail, if the git tree is dirty, or if the version already exists on npm.
@@ -54,17 +37,27 @@ If npm asks for 2FA during publish, use a fresh authenticator code:
 
 ```powershell
 $env:NPM_CONFIG_OTP="<code>"
-npm run release:publish -- --version X.Y.Z
+npm run release:publish -- X.Y.Z
 Remove-Item Env:NPM_CONFIG_OTP
 ```
 
 ## Full
 
 ```bash
-npm run release:full -- --version X.Y.Z
+npm run release:full -- X.Y.Z --publish-npm --github-release
+```
+
+Full mode runs release gates, then publishes to npm only when `--publish-npm` is supplied, and creates or updates the GitHub release only when `--github-release` is supplied.
+
+For explicit CLI usage:
+
+```bash
+soturail release publish X.Y.Z
+soturail release github X.Y.Z
+soturail release full X.Y.Z --publish-npm --github-release
 ```
 
-Full mode runs prepare, publish and then creates or updates the GitHub release using `gh` when available. If the npm version already exists, full mode skips npm publish and only creates or updates the GitHub release.
+Release commands also accept `--target-version X.Y.Z`. The older `--version X.Y.Z` form remains supported for npm scripts, but the positional form avoids confusion with the global `soturail --version` flag.
 
 Only create or update the GitHub release after npm publish succeeds and these checks pass:
 

package/docs/security-model.md

@@ -27,6 +27,12 @@ This is intentionally verbose so accidental bypasses are unlikely.
 
 Raw command logs remain on disk so compressed summaries can always be audited.
 
+Raw logs may contain secrets. Do not commit `.soturail/raw/`. MCP raw-log expansion redacts probable secrets by default unless `allow_raw=true` is explicitly passed.
+
+## MCP And Skills
+
+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.
+
 ## Limitations
 
 SotuRail does not isolate processes, prevent all shell tricks or replace OS permissions. Treat it as a policy and evidence layer.

package/docs/skill-rail.md

@@ -1,28 +1,26 @@
 # Skill Rail
 
-Skill Rail is planned for v0.3.0. It is not implemented in v0.2.x.
-
-The goal is to turn approved SotuRail specs, rules and workflows into portable, reviewable agent skills without installing untrusted marketplace content automatically.
-
-Planned commands:
+Skill Rail exports safe local agent skills without depending on external skill ecosystems.
 
 ```bash
-soturail skills init <name>
-soturail skills from-spec <spec-id>
-soturail skills from-rules <rules-file>
-soturail skills validate <path>
-soturail skills export claude|codex|gemini|cursor
+soturail skills init demo-skill
+soturail skills list
+soturail skills validate
+soturail skills export --target claude
+soturail skills export --target codex
+soturail skills export --target gemini
+soturail skills export --target cursor
+soturail skills export --target generic
+soturail skills pack --format json
+soturail skills pack --format markdown
 ```
 
-## Security Requirements
+Skills live in `.soturail/skills/<skill-id>/` with `skill.yml`, `SKILL.md`, examples and validators.
+
+Validation checks required metadata, target names, duplicate IDs, deterministic content hashes, destructive shell patterns, prompt-injection style instructions and probable embedded secrets.
+
+Exports are written to `.soturail/exports/skills/<target>/`. Review every generated file before enabling it in Claude, Codex, Gemini, Cursor or another host.
 
-- No automatic marketplace install.
-- Validate `SKILL.md` before use.
-- Scan for prompt injection.
-- Scan for destructive shell commands.
-- Scan for secret exfiltration language.
-- Scan for `curl`/`wget` pipe execution.
-- Warn about untrusted scripts.
-- Require human approval before enabling generated skills.
+`soturail skills list` prints each skill ID, risk level, name, description, version, targets and local path. If there are no local skills, it prints the command to create one.
 
-Skill Rail should preserve SotuRail's local-first evidence model: generated skills must cite the spec, rule or workflow that produced them.
+The generated starter skill includes safe workflow steps, a verification checklist, example input/output, target metadata and human approval requirements for destructive commands, remote writes and dependency installation.

package/docs/usage.md

@@ -62,3 +62,26 @@ soturail rules check
 soturail native doctor
 soturail bench compare-engines
 ```
+
+## v0.3.0 Workflows
+
+```bash
+soturail skills init demo-skill
+soturail skills list
+soturail skills validate
+soturail skills export --target claude
+soturail context pack --target claude
+soturail context pack --target codex
+soturail context pack --target gemini
+soturail context pack --target cursor
+soturail context pack --target generic
+soturail mcp doctor
+soturail mcp manifest
+soturail mcp serve --transport stdio
+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.
+
+For a first clean-folder walkthrough, see [first-real-workflow.md](first-real-workflow.md).

package/docs/windows.md

@@ -26,7 +26,7 @@ From a source checkout:
 npm run build
 npm pack --dry-run
 npm pack
-npm install -g .\soturail-0.2.3.tgz
+npm install -g .\soturail-0.3.0.tgz
 soturail --version
 ```
 
@@ -71,6 +71,26 @@ node app.js
 npx soturail --help
 ```
 
+## MCP And Context Packs
+
+PowerShell examples:
+
+```powershell
+soturail mcp doctor
+soturail mcp manifest
+soturail context pack --target generic
+```
+
+CMD examples:
+
+```bat
+soturail mcp doctor
+soturail mcp manifest
+soturail context pack --target generic
+```
+
+When testing `soturail mcp serve --transport stdio`, send one JSON object per line. See `examples\mcp\` for payloads.
+
 ## Safety
 
 SotuRail blocks destructive command shapes through `soturail run`, including `rm -rf`, `sudo`, `del /s`, downloaded script piping and automatic `git push`.

package/docs/workflow-rail.md

@@ -1,6 +1,6 @@
 # Workflow Rail
 
-Workflow Rail is planned for v0.4.0. It is not implemented in v0.2.x.
+Workflow Rail is planned for v0.4.0. It is not implemented in v0.3.x.
 
 The goal is to describe repeatable engineering workflows as local, auditable artifacts that can later export into Skill Rail or an MCP server.
 
@@ -24,3 +24,9 @@ soturail workflow export skill
 - Require human approval before enabling generated workflows or exported skills.
 
 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.
+
+## Current Road
+
+- 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.

package/examples/README.md

@@ -0,0 +1,22 @@
+# SotuRail Examples
+
+These examples are small starting points for real local usage:
+
+- `skills/`: reviewable Skill Rail YAML examples.
+- `context-packs/`: context pack workflows.
+- `mcp/`: JSON-RPC messages for the stdio MCP server.
+- `hooks/`: prompt-only and hook guidance.
+
+Run examples in a disposable folder first:
+
+```bash
+soturail init
+soturail index
+soturail context pack --target generic
+```
+
+Safety notes:
+
+- Review generated files before enabling them in an agent.
+- Do not paste raw logs into public issues without checking for secrets.
+- MCP does not expose arbitrary shell execution by default.

package/examples/context-packs/README.md

@@ -0,0 +1,17 @@
+# Context Pack Examples
+
+Context packs are Markdown payloads with stable project context before dynamic session data.
+
+```bash
+soturail init
+soturail index
+soturail context pack --target generic
+```
+
+Generated files:
+
+- `.soturail/context/claude-context.md`
+- `.soturail/context/codex-context.md`
+- `.soturail/context/gemini-context.md`
+- `.soturail/context/cursor-context.md`
+- `.soturail/context/generic-context.md`

package/examples/context-packs/generic-workflow.md

@@ -0,0 +1,9 @@
+# Generic Context Pack Workflow
+
+```bash
+soturail init
+soturail index
+soturail context pack --target generic
+```
+
+Open `.soturail/context/generic-context.md` and review it before sending it to an agent.

package/examples/hooks/README.md

@@ -0,0 +1,11 @@
+# Hook Examples
+
+Start with dry-run:
+
+```bash
+soturail hooks doctor
+soturail hooks install --agent claude --mode safe-hooks --dry-run
+soturail hooks install --agent codex --mode prompt-only --dry-run
+```
+
+Review every generated file before enabling hooks.

package/examples/hooks/prompt-only-codex.md

@@ -0,0 +1,7 @@
+# Prompt-only Codex Rules
+
+- Use `soturail index` before large repository changes.
+- Use `soturail read <file> --query "goal"` instead of reading giant files directly.
+- Use `soturail run` for tests, builds and logs so raw output is recoverable.
+- Use `soturail expand <raw_id>` only when the compressed summary lacks needed information.
+- Never use `soturail run` for `git push`.

package/examples/mcp/README.md

@@ -0,0 +1,17 @@
+# MCP Examples
+
+These files are one-message JSON-RPC examples for `soturail mcp serve --transport stdio`.
+
+Run:
+
+```bash
+soturail mcp serve --transport stdio
+```
+
+Then paste one JSON object per line. The server responds with one JSON-RPC response per line.
+
+Safety notes:
+
+- MCP does not expose arbitrary shell execution by default.
+- `soturail.run` is not listed as an MCP tool.
+- Raw log expansion redacts probable secrets unless `allow_raw=true`.

package/examples/mcp/initialize.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"clientInfo":{"name":"manual-smoke","version":"0.1.0"}}}

package/examples/mcp/resources-list.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":2,"method":"resources/list"}

package/examples/mcp/resources-read-repo-map.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":3,"method":"resources/read","params":{"uri":"soturail://repo-map"}}

package/examples/mcp/tools-list.json

@@ -0,0 +1 @@
+{"jsonrpc":"2.0","id":4,"method":"tools/list"}

package/examples/skills/README.md

@@ -0,0 +1,13 @@
+# Skill Examples
+
+Use these YAML files as references for `soturail skills init <name>` output.
+
+Recommended flow:
+
+```bash
+soturail skills init code-review
+soturail skills validate
+soturail skills export --target claude
+```
+
+The example YAML files are documentation templates. A real local skill also needs a matching `SKILL.md` and deterministic `content_hash`.