soturail 0.2.3 → 0.3.0

package/dist/core/skill-store.js

@@ -0,0 +1,92 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { ensureWorkspace, getWorkspacePaths } from "./config.js";
+import { defaultForbiddenPatterns, defaultHumanApprovals, parseSkillYaml, SkillMetadataSchema, slugifySkillName, stableSkillHash, stringifySkillYaml } from "./skill-schema.js";
+export async function createSkill(name, root = process.cwd()) {
+    await ensureWorkspace(root);
+    const paths = getWorkspacePaths(root);
+    const id = slugifySkillName(name);
+    const dir = path.join(paths.skillsDir, id);
+    const markdown = [
+        `# ${name}`,
+        "",
+        "Use this skill when the task matches the description and the repository owner has approved it.",
+        "",
+        "## Safety",
+        "",
+        "- Do not run destructive shell commands.",
+        "- Do not exfiltrate secrets.",
+        "- Ask for human approval before remote writes or destructive actions.",
+        ""
+    ].join("\n");
+    const base = {
+        id,
+        name,
+        description: `Safe local-first workflow skill for ${name}.`,
+        version: "0.1.0",
+        author: "Rafael Ryan Ramos de Souza",
+        risk_level: "low",
+        targets: ["claude", "codex", "gemini", "cursor"],
+        allowed_tools: ["read", "search"],
+        forbidden_patterns: defaultForbiddenPatterns,
+        requires_human_approval: defaultHumanApprovals,
+        created_at: new Date().toISOString()
+    };
+    const metadata = { ...base, content_hash: stableSkillHash(base, markdown) };
+    await fs.mkdir(path.join(dir, "examples"), { recursive: true });
+    await fs.mkdir(path.join(dir, "validators"), { recursive: true });
+    await fs.writeFile(path.join(dir, "skill.yml"), stringifySkillYaml(metadata), "utf8");
+    await fs.writeFile(path.join(dir, "SKILL.md"), markdown, "utf8");
+    return { metadata, markdown, dir };
+}
+export async function readSkills(root = process.cwd()) {
+    const paths = getWorkspacePaths(root);
+    let entries = [];
+    try {
+        entries = await fs.readdir(paths.skillsDir);
+    }
+    catch {
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        const dir = path.join(paths.skillsDir, entry);
+        const stat = await fs.stat(dir).catch(() => null);
+        if (!stat?.isDirectory())
+            continue;
+        const yaml = await fs.readFile(path.join(dir, "skill.yml"), "utf8").catch(() => "");
+        const markdown = await fs.readFile(path.join(dir, "SKILL.md"), "utf8").catch(() => "");
+        const parsed = parseSkillYaml(yaml);
+        const result = SkillMetadataSchema.safeParse(parsed);
+        if (result.success) {
+            skills.push({ metadata: result.data, markdown, dir });
+        }
+        else {
+            skills.push({
+                metadata: {
+                    id: entry,
+                    name: entry,
+                    description: "Invalid skill metadata",
+                    version: "0.0.0",
+                    author: "unknown",
+                    risk_level: "high",
+                    targets: ["generic"],
+                    allowed_tools: [],
+                    forbidden_patterns: [],
+                    requires_human_approval: [],
+                    created_at: "invalid",
+                    content_hash: "0".repeat(64)
+                },
+                markdown,
+                dir
+            });
+        }
+    }
+    return skills.sort((left, right) => left.metadata.id.localeCompare(right.metadata.id));
+}
+export function renderSkillList(skills) {
+    if (skills.length === 0)
+        return "No skills found. Run soturail skills init <name> first.\n";
+    return skills.map((skill) => `${skill.metadata.id} [${skill.metadata.risk_level}] ${skill.metadata.name}`).join("\n") + "\n";
+}
+//# sourceMappingURL=skill-store.js.map

package/dist/core/skill-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-store.js","sourceRoot":"","sources":["../../src/core/skill-store.ts"],"names":[],"mappings":"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"}

package/dist/core/skill-validator.d.ts

@@ -0,0 +1,12 @@
+export interface SkillValidationIssue {
+    skill_id: string;
+    severity: "error" | "warning";
+    message: string;
+}
+export interface SkillValidationResult {
+    ok: boolean;
+    skills_count: number;
+    issues: SkillValidationIssue[];
+}
+export declare function validateSkills(root?: string): Promise<SkillValidationResult>;
+export declare function formatSkillValidation(result: SkillValidationResult): string;

package/dist/core/skill-validator.js

@@ -0,0 +1,94 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { parseSkillYaml, SkillMetadataSchema, stableSkillHash } from "./skill-schema.js";
+import { readSkills } from "./skill-store.js";
+const destructivePatterns = [
+    /\brm\s+-[^"\n]*r[^"\n]*f\b/i,
+    /\bcurl\b[^|\n]*\|\s*(sh|bash)\b/i,
+    /\bwget\b[^|\n]*\|\s*(sh|bash)\b/i,
+    /\bgit\s+push\b/i,
+    /\bdd\s+[^"\n]*\bif=/i,
+    /\bdel\s+\/s\b/i
+];
+const promptInjectionPatterns = [
+    /ignore (all )?(previous|prior) instructions/i,
+    /disregard (all )?(previous|prior) instructions/i,
+    /you are no longer bound/i
+];
+const secretPatterns = [
+    /sk-[A-Za-z0-9_-]{20,}/,
+    /AKIA[0-9A-Z]{16}/,
+    /-----BEGIN (RSA |OPENSSH |EC )?PRIVATE KEY-----/,
+    /(password|api[_-]?key|secret)\s*[:=]\s*["']?[A-Za-z0-9_\-]{16,}/i
+];
+export async function validateSkills(root = process.cwd()) {
+    const skills = await readSkills(root);
+    const issues = [];
+    const seen = new Set();
+    for (const skill of skills) {
+        await validateSkillFiles(skill, issues);
+        if (seen.has(skill.metadata.id)) {
+            issues.push({ skill_id: skill.metadata.id, severity: "error", message: "Duplicate skill id." });
+        }
+        seen.add(skill.metadata.id);
+        const combined = `${skill.markdown}\n${JSON.stringify({ ...skill.metadata, forbidden_patterns: [] })}`;
+        for (const pattern of destructivePatterns) {
+            if (pattern.test(skill.markdown)) {
+                issues.push({ skill_id: skill.metadata.id, severity: "error", message: `Hidden destructive command pattern detected: ${pattern}` });
+            }
+        }
+        for (const pattern of promptInjectionPatterns) {
+            if (pattern.test(combined)) {
+                issues.push({ skill_id: skill.metadata.id, severity: "error", message: `Prompt-injection style instruction detected: ${pattern}` });
+            }
+        }
+        for (const pattern of secretPatterns) {
+            if (pattern.test(combined)) {
+                issues.push({ skill_id: skill.metadata.id, severity: "error", message: "Probable embedded secret detected." });
+            }
+        }
+        const { content_hash: _hash, ...withoutHash } = skill.metadata;
+        const actual = stableSkillHash(withoutHash, skill.markdown);
+        if (actual !== skill.metadata.content_hash) {
+            issues.push({ skill_id: skill.metadata.id, severity: "error", message: "content_hash does not match skill.yml and SKILL.md content." });
+        }
+    }
+    return {
+        ok: issues.every((issue) => issue.severity !== "error"),
+        skills_count: skills.length,
+        issues
+    };
+}
+export function formatSkillValidation(result) {
+    const lines = [
+        `Skill validation: ${result.ok ? "passed" : "failed"}`,
+        `skills_count: ${result.skills_count}`
+    ];
+    if (result.issues.length === 0) {
+        lines.push("issues: none");
+    }
+    else {
+        for (const issue of result.issues) {
+            lines.push(`- ${issue.severity.toUpperCase()} ${issue.skill_id}: ${issue.message}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+async function validateSkillFiles(skill, issues) {
+    const yamlPath = path.join(skill.dir, "skill.yml");
+    const markdownPath = path.join(skill.dir, "SKILL.md");
+    const rawYaml = await fs.readFile(yamlPath, "utf8").catch(() => "");
+    const parsed = parseSkillYaml(rawYaml);
+    const result = SkillMetadataSchema.safeParse(parsed);
+    if (!result.success) {
+        issues.push({
+            skill_id: skill.metadata.id,
+            severity: "error",
+            message: `Invalid skill.yml: ${result.error.issues.map((issue) => issue.path.join(".")).join(", ")}`
+        });
+    }
+    if (!await fs.access(markdownPath).then(() => true).catch(() => false)) {
+        issues.push({ skill_id: skill.metadata.id, severity: "error", message: "Missing SKILL.md." });
+    }
+}
+//# sourceMappingURL=skill-validator.js.map

package/dist/core/skill-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-validator.js","sourceRoot":"","sources":["../../src/core/skill-validator.ts"],"names":[],"mappings":"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"}

package/dist/core/version.d.ts

@@ -1 +1 @@
-export declare const SOTURAIL_VERSION = "0.2.3";
+export declare const SOTURAIL_VERSION = "0.3.0";

package/dist/core/version.js

@@ -1,3 +1,3 @@
 // Generated by scripts/sync-version.mjs from package.json. Do not edit manually.
-export const SOTURAIL_VERSION = "0.2.3";
+export const SOTURAIL_VERSION = "0.3.0";
 //# sourceMappingURL=version.js.map

package/docs/benchmarking.md

@@ -20,7 +20,12 @@ The suite groups results as:
 - agent response compression;
 - knowledge structuring;
 - cache stability;
-- native engine availability/performance when available.
+- native engine availability/performance when available;
+- skill rail validation/export;
+- MCP resource listing/reading;
+- context pack generation;
+- agent hook export;
+- memory approval workflow.
 
 Terminal compression includes npm install noise, Vitest failures, TypeScript diagnostics, git diff/status noise and JSON/tool payload output.
 

package/docs/comparisons.md

@@ -0,0 +1,35 @@
+# Comparison Philosophy
+
+SotuRail aims to unify these workflow ideas into one local-first, auditable, cache-friendly developer tool.
+
+SotuRail is an independent implementation. It does not vendor or depend on RTK, Squeez, Caveman, MemPalace, Spec Kit, agent-skills, SkillsMP, Compozy, Superpowers, OpenSpec or Istara.
+
+## Terminal Compression
+
+RTK-like terminal compression is conceptually related. SotuRail focuses on reversible raw logs, `raw_id` recovery and local safety policy. It does not claim to outperform RTK without reproducible benchmark evidence.
+
+## Hooks And Dedupe
+
+Squeez-like hooks and dedupe are adjacent ideas. SotuRail has prompt-only fallbacks, conservative Claude hooks, context packs and local dedupe as an independent implementation.
+
+## Response Compression
+
+Caveman-like response compression inspired the idea of shorter agent output. SotuRail implements professional deterministic modes that preserve code blocks, commands, paths and warnings.
+
+## Spec Workflows
+
+Spec Kit-like workflows are related to SotuRail specs. SotuRail integrates specs with logs, metrics, memory and context packs.
+
+## Local Memory
+
+MemPalace-like memory/evidence ideas are related. SotuRail uses local JSONL memory with approval workflow and stale marking, not full semantic memory yet.
+
+## Knowledge To Rules
+
+Nicole-style knowledge-to-rules workflows are related. SotuRail has `ingest` and `rules` with future hardened PDF extraction.
+
+## Skills 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.
+
+SotuRail should not be described as better than these projects unless a specific local benchmark proves a specific metric.

package/docs/context-packs.md

@@ -0,0 +1,29 @@
+# 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/`.
+
+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.

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/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,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,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,22 @@
 # 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.
 
-- 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.3.tgz
+npm install -g .\soturail-0.3.0.tgz
 soturail --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.x.
+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.