soturail 0.2.1 → 0.2.3

package/docs/hooks/claude.md

@@ -5,6 +5,8 @@ SotuRail v0.2.1 includes a conservative Claude Code hook template.
 ```bash
 soturail hooks install claude --dry-run
 soturail hooks install claude
+soturail hooks uninstall claude
+soturail hooks prompt-only claude
 ```
 
 Generated files:
@@ -19,6 +21,8 @@ The pre-tool hook inspects incoming tool payload text when Claude Code provides
 
 The hook never routes `git push` through `soturail run`.
 
+Review generated settings and scripts before relying on them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.
+
 ## Limitation
 
 Claude Code hook schemas may vary by installed version. SotuRail writes a conservative documented template; if your Claude Code release expects a different schema, copy the generated command into the supported hook slot manually.

package/docs/hooks/codex.md

@@ -3,3 +3,14 @@
 Codex prompt-only integration uses `AGENTS.md`.
 
 SotuRail does not assume private Codex host hook APIs. The fallback rules describe when to index, read progressively, run through SotuRail and avoid `git push`.
+
+Useful commands:
+
+```bash
+soturail hooks install codex --dry-run
+soturail hooks install codex
+soturail hooks uninstall codex
+soturail hooks prompt-only codex
+```
+
+Existing `AGENTS.md` content is backed up before install. Review generated prompt rules before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.

package/docs/hooks/cursor.md

@@ -3,3 +3,14 @@
 Cursor prompt-only integration writes `.cursor/rules/soturail.mdc` when installed.
 
 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 prompt-only cursor
+```
+
+Review generated prompt rules before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.

package/docs/hooks/gemini.md

@@ -3,3 +3,14 @@
 Gemini prompt-only integration uses `GEMINI.md`.
 
 The generated rules keep repository scans, progressive file reads and raw log recovery visible to Gemini CLI sessions.
+
+Useful commands:
+
+```bash
+soturail hooks install gemini --dry-run
+soturail hooks install gemini
+soturail hooks uninstall gemini
+soturail hooks prompt-only gemini
+```
+
+Existing `GEMINI.md` content is backed up before install. Review generated prompt rules before enabling them. SotuRail should never auto-install unreviewed third-party skills, hooks or scripts.

package/docs/hooks.md

@@ -6,6 +6,8 @@ SotuRail hook support is cautious. Claude gets a conservative hook template firs
 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
 ```
@@ -13,3 +15,12 @@ soturail hooks prompt-only codex
 Installers create backups before modifying existing files. 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.
+
+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
+```

package/docs/release-checklist.md

@@ -2,12 +2,82 @@
 
 Before publishing:
 
+- [ ] Confirm `npm whoami` works for the publishing account.
+- [ ] Confirm npm 2FA requirements and have the authenticator ready.
 - [ ] `npm install`
 - [ ] `npm run build`
 - [ ] `npm test`
-- [ ] Verify `soturail --help`
-- [ ] Verify `soturail init` in a clean temp repo
-- [ ] Confirm docs mention limitations honestly
-- [ ] Confirm no telemetry exists
-- [ ] Confirm no `git push` was run automatically
-- [ ] Tag release manually after review
+- [ ] `npm audit --omit=dev`
+- [ ] `node dist/cli.js self all`
+- [ ] `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.
+
+`npm audit --omit=dev` checks runtime/public dependency risk for published package users.
+
+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.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
+
+Do not paste Markdown prose or code-fence labels directly into `cmd.exe` as commands. For example, do not paste ```` ```bat ````. Copy only the command lines themselves.
+
+See [docs/windows.md](windows.md) for CMD and PowerShell quoting notes.
+
+## Automation
+
+Use:
+
+```bash
+npm run release:check
+npm run release:prepare -- --version X.Y.Z
+npm run release:publish -- --version X.Y.Z
+npm run release:full -- --version X.Y.Z
+```

package/docs/release-workflow.md

@@ -0,0 +1,84 @@
+# Release Workflow
+
+SotuRail releases should be repeatable and evidence-backed. The release helper lives at `scripts/release.mjs`.
+
+## Check
+
+```bash
+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.
+
+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.
+
+## 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
+```
+
+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.
+
+For browser-based npm login:
+
+```bash
+npm login --auth-type=web
+npm whoami
+```
+
+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
+Remove-Item Env:NPM_CONFIG_OTP
+```
+
+## Full
+
+```bash
+npm run release:full -- --version X.Y.Z
+```
+
+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.
+
+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:
+
+- Never run `npm audit fix --force`.
+- Never publish if tests fail.
+- Never publish if build fails.
+- Never publish if runtime audit fails.
+- Never publish if the requested package version already exists on npm.
+- Never create a GitHub release before npm publish succeeds.
+- Never hide errors.

package/docs/skill-rail.md

@@ -0,0 +1,28 @@
+# 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:
+
+```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
+```
+
+## Security Requirements
+
+- 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.
+
+Skill Rail should preserve SotuRail's local-first evidence model: generated skills must cite the spec, rule or workflow that produced them.

package/docs/windows.md

@@ -0,0 +1,97 @@
+# Windows Notes
+
+SotuRail supports Windows through Node.js and uses cross-platform path handling internally. The main practical differences are shell quoting and how commands are pasted.
+
+## Install Globally
+
+PowerShell and CMD:
+
+```powershell
+npm install -g soturail
+soturail --help
+```
+
+## Run With npx
+
+```powershell
+npx soturail --help
+npx soturail init
+```
+
+## Test a Local Tarball
+
+From a source checkout:
+
+```powershell
+npm run build
+npm pack --dry-run
+npm pack
+npm install -g .\soturail-0.2.3.tgz
+soturail --version
+```
+
+If the tarball name changes, use the exact file that `npm pack` created.
+
+## CMD vs PowerShell
+
+PowerShell accepts commands like:
+
+```powershell
+node .\dist\cli.js read ".\README.md" --query "quick start"
+```
+
+CMD uses similar quoting, but it does not understand Markdown code-fence labels. Do not paste the literal fence label:
+
+```text
+```bat
+```
+
+into CMD. CMD will try to execute it and report an error.
+
+## Paths With Spaces
+
+Quote paths that contain spaces:
+
+```powershell
+soturail read "C:\Users\rafael\Documents\My Project\README.md" --query "install"
+```
+
+## Avoid Accidental Command Concatenation
+
+When copying examples, keep commands on separate lines. This is wrong:
+
+```text
+node app.jsnpx soturail --help
+```
+
+Run them separately:
+
+```powershell
+node app.js
+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

@@ -0,0 +1,26 @@
+# Workflow Rail
+
+Workflow Rail is planned for v0.4.0. It is not implemented in v0.2.x.
+
+The goal is to describe repeatable engineering workflows as local, auditable artifacts that can later export into Skill Rail or an MCP server.
+
+Planned commands:
+
+```bash
+soturail workflow new <name>
+soturail workflow from-template <name>
+soturail workflow validate
+soturail workflow export skill
+```
+
+## Security Requirements
+
+- 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.
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "soturail",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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,9 @@
     "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",
     "build:native": "cargo build --manifest-path native/soturail-native/Cargo.toml --release",
@@ -27,7 +29,11 @@
     "bench": "node dist/cli.js bench run --engine ts",
     "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"
+    "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"
   },
   "keywords": [
     "ai-agents",