soturail 0.2.2 → 0.3.0

package/docs/hooks.md

@@ -1,26 +1,22 @@
 # 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:
-
-```bash
-soturail hooks prompt-only claude
-soturail hooks prompt-only codex
-soturail hooks prompt-only gemini
-soturail hooks prompt-only cursor
-```
+Always review generated hooks before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.

package/docs/mcp.md

@@ -0,0 +1,18 @@
+# MCP Server
+
+SotuRail v0.3.0 includes a local MCP-compatible server over stdio using JSON-RPC 2.0 style messages.
+
+```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.
+
+Security defaults:
+
+- no arbitrary shell execution;
+- no `soturail run` MCP tool in v0.3.0;
+- raw log expansion redacts probable secrets unless `allow_raw=true`;
+- provider cache hits are never invented.

package/docs/release-checklist.md

@@ -9,12 +9,27 @@ 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`.
 - [ ] Confirm docs mention limitations honestly.
 - [ ] Confirm no telemetry exists.
 - [ ] Confirm no `git push` is routed through `soturail run`.
 
+## Version Sync
+
+Check four separate release identifiers before publishing:
+
+- npm package version: `package.json` and `package-lock.json`.
+- CLI runtime version: `node dist/cli.js --version`.
+- Git tag: created only when the release process calls for it.
+- GitHub release: created only after npm publish succeeds.
+
+The package version and CLI runtime version must match. `npm run build` regenerates the CLI version source from `package.json`, and `npm run release:check` verifies the built CLI before publication.
+
 ## Audit Distinction
 
 `npm audit` checks all dependencies, including dev dependencies used for local tests and builds.
@@ -23,7 +38,35 @@ Before publishing:
 
 Runtime audit is clean with `npm audit --omit=dev`. Remaining audit findings, if any, are development dependency findings and should be upgraded safely without `--force`.
 
-For v0.2.2, the full audit findings are in the Vitest/Vite development test stack. npm's suggested fix is a semver-major Vitest upgrade, so do not run `npm audit fix --force` blindly.
+For v0.2.x, the full audit findings are in the Vitest/Vite development test stack when present. npm's suggested fix may be a semver-major Vitest upgrade, so do not run `npm audit fix --force` blindly.
+
+## npm Login And 2FA
+
+Use browser-based npm login before publishing:
+
+```bash
+npm login --auth-type=web
+npm whoami
+```
+
+If npm requires a one-time password during publish, provide a fresh authenticator code through `NPM_CONFIG_OTP` or `--otp`. Do not commit tokens, OTPs or npm credentials.
+
+PowerShell example:
+
+```powershell
+$env:NPM_CONFIG_OTP="<code>"
+npm run release:publish -- --version X.Y.Z
+Remove-Item Env:NPM_CONFIG_OTP
+```
+
+After npm publish succeeds, verify:
+
+```bash
+npm view soturail version
+npx --yes soturail@X.Y.Z --version
+```
+
+Create or update the GitHub release only after those npm checks pass.
 
 ## Windows Paste Safety
 

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
 
@@ -10,38 +10,61 @@ npm run release:check
 
 Runs install, build, tests, runtime audit, self-dogfooding, pack dry-run and npm version checks. It also reports whether full audit findings are development-only.
 
-## Prepare
+The check also verifies:
+
+- `package.json` and `package-lock.json` version sync;
+- `node dist/cli.js --version` matches the package version;
+- npm pack dry-run emits the matching tarball name;
+- `CHANGELOG.md` and `RELEASE_NOTES_vX.Y.Z.md` exist for the local version;
+- README install instructions and `LICENSE` exist.
+
+## Publish
 
 ```bash
-npm run release:prepare -- --version X.Y.Z
+npm run release:publish -- 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 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.
 
-## Publish
+For browser-based npm login:
 
 ```bash
-npm run release:publish -- --version X.Y.Z
+npm login --auth-type=web
+npm whoami
 ```
 
-Publish mode refuses to publish if build, tests or runtime audit fail, if the git tree is dirty, or if the version already exists on npm. If npm asks for 2FA or authentication, rerun the same command after completing the auth step.
+If npm asks for 2FA during publish, use a fresh authenticator code:
+
+```powershell
+$env:NPM_CONFIG_OTP="<code>"
+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:
+
+```bash
+npm view soturail version
+npx --yes soturail@X.Y.Z --version
+```
 
 Safety rules:
 

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,22 @@
 # Skill Rail
 
-Skill Rail is planned for v0.3.0. It is not implemented in v0.2.2.
-
-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.
 
-- 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.
+Validation checks required metadata, target names, duplicate IDs, deterministic content hashes, destructive shell patterns, prompt-injection style instructions and probable embedded secrets.
 
-Skill Rail should preserve SotuRail's local-first evidence model: generated skills must cite the spec, rule or workflow that produced them.
+Exports are written to `.soturail/exports/skills/<target>/`. Review every generated file before enabling it in Claude, Codex, Gemini, Cursor or another host.

package/docs/usage.md

@@ -62,3 +62,18 @@ soturail rules check
 soturail native doctor
 soturail bench compare-engines
 ```
+
+## v0.3.0 Workflows
+
+```bash
+soturail skills init demo-skill
+soturail skills validate
+soturail skills export --target claude
+soturail context pack --target generic
+soturail mcp doctor
+soturail mcp manifest
+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.

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.1.tgz
+npm install -g .\soturail-0.3.0.tgz
 soturail --version
 ```
 
@@ -74,3 +74,24 @@ npx soturail --help
 ## Safety
 
 SotuRail blocks destructive command shapes through `soturail run`, including `rm -rf`, `sudo`, `del /s`, downloaded script piping and automatic `git push`.
+
+## Release Checks On Windows
+
+Before publishing from Windows, run:
+
+```powershell
+npm run build
+node .\dist\cli.js --version
+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.
+
+Use browser-based npm login when needed:
+
+```powershell
+npm login --auth-type=web
+npm whoami
+```
+
+Only create the GitHub release after npm publish succeeds and `npx --yes soturail@X.Y.Z --version` prints the published version.

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.2.
+Workflow Rail is planned for v0.4.0. It is not implemented in v0.3.0.
 
 The goal is to describe repeatable engineering workflows as local, auditable artifacts that can later export into Skill Rail or an MCP server.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soturail",
-  "version": "0.2.2",
+  "version": "0.3.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": {
@@ -16,7 +16,8 @@
     "docs"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "sync:version": "node scripts/sync-version.mjs",
+    "build": "npm run sync:version && tsc -p tsconfig.json",
     "prepack": "npm run build",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit",
@@ -29,10 +30,11 @@
     "bench:report": "node dist/cli.js bench report",
     "bench:native": "node dist/cli.js bench run --engine native",
     "bench:compare": "node dist/cli.js bench compare-engines",
-    "release:check": "node scripts/release.mjs check",
-    "release:prepare": "node scripts/release.mjs prepare",
-    "release:publish": "node scripts/release.mjs publish",
-    "release:full": "node scripts/release.mjs full"
+    "release:check": "npm run build && node dist/cli.js release check",
+    "release:notes": "npm run build && node dist/cli.js release notes",
+    "release:publish": "npm run build && node dist/cli.js release publish",
+    "release:github": "npm run build && node dist/cli.js release github",
+    "release:full": "npm run build && node dist/cli.js release full"
   },
   "keywords": [
     "ai-agents",