@softspark/ai-toolkit 4.29.2 → 4.30.2

package/CHANGELOG.md

@@ -7,6 +7,88 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.30.2 - Portable Linux release gates (2026-09-02)
+
+### Fixed
+
+- **File-mode checks are cross-platform.** DSH package and plugin asset tests now
+  read POSIX modes through Python `stat.S_IMODE` instead of the macOS-only
+  `stat -f` syntax.
+- **Malformed ownership diagnostics are consistent.** Invalid `packages` and
+  `package_trees` records now fail with ownership-specific errors at the shared
+  state-validation boundary on both macOS and Linux.
+
+### Changed
+
+- **First published release of the 4.30 feature set.** Public tags `v4.30.0` and
+  `v4.30.1` failed their Linux GitHub Actions gates before npm publication.
+  Version `4.30.2` includes both portability corrections; neither earlier npm
+  artifact exists.
+
+---
+
+## v4.30.1 - Linux-portable DSH recovery diagnostics (2026-09-01)
+
+### Fixed
+
+- **Interrupted preset relocation keeps an actionable error.** A
+  `KeyboardInterrupt` has an empty string representation on Linux; recovery
+  output now normalizes it to an explicit interrupted message before naming the
+  preserved path.
+- **Recovery verification failures are never silent.** Package-preset hash
+  failures are included in deterministic recovery diagnostics while ownership
+  state restoration still runs.
+- **Recovery tests use platform-independent seams.** Backup restore and package
+  source verification injections now exercise the same secure helpers on macOS
+  and Linux.
+
+### Changed
+
+- **First published release of the 4.30 feature set.** The public `v4.30.0` tag
+  failed its GitHub Actions gate before npm publication. Version `4.30.1`
+  contains the same DSH and MCP features plus this cross-platform correction;
+  no `4.30.0` npm artifact exists.
+
+---
+
+## v4.30.0 - Managed DSH and plugin-owned MCP (2026-09-01)
+
+### Added
+
+- **Explicit DSH project target.** Added `install --local --editors dsh` for the
+  managed `.agents/skills` surface without implicit selection or `$DSH_HOME`
+  mutation.
+- **Managed DSH profile lifecycle.** Added `ai-toolkit dsh
+  install|update|doctor|uninstall --profile web` with exact DSH `0.1.1-rc.2`,
+  dsh-codex `1.0.0`, dsh-orchestrator `1.0.1`, preset ownership, dry-run, and
+  read-only diagnostics.
+- **Plugin-owned MCP and native rules.** Plugin packs can deliver MCP templates
+  and owned rule surfaces to Claude, Codex, Cursor, and Gemini.
+- **RAG MCP templates.** Added `rag-mcp` and `rag-mcp-legal` with concrete
+  localhost defaults and unauthenticated-endpoint warnings. The built-in MCP
+  catalogue now contains 28 templates.
+
+### Changed
+
+- **DSH remains explicit-only.** It stays outside editor defaults,
+  auto-detection, and `--editors all`; vendor CLIs retain authentication
+  ownership and no provider API key is accepted.
+- **Plugin lifecycle is transactional.** Install, update, and removal coordinate
+  MCP settings, rules, hook/script assets, and ownership state with pinned-path
+  CAS and last-consumer cleanup.
+- **Test count.** Increased from 1675 to 1920.
+
+### Fixed
+
+- **Cold DSH installs fail safely.** Added pnpm preflight, bounded probe and
+  mutation timeouts, full process-tree termination, exact executable identity,
+  directory-level lifecycle locking, and durable recovery gates.
+- **Concurrent plugin edits are preserved.** Atomic quarantine and rollback no
+  longer overwrite concurrent bytes, modes, inodes, marker sections, or
+  user-added assets.
+
+---
+
 ## v4.29.2 — The Codex dry-run stops hiding a surface (2026-08-21)
 
 ### Fixed

package/README.md

@@ -1,26 +1,33 @@
 # ai-toolkit
 
-> Professional-grade AI coding toolkit with multi-platform support. Machine-enforced safety, 109 skills, 44 agents, expanded lifecycle hooks, persona presets, experimental opt-in plugin packs, and benchmark tooling — works with Claude Code, Claude Chat/Cowork, Cursor, Devin, Copilot, Gemini, Cline, Roo/Zoo Code, Aider, Augment, Google Antigravity, Codex CLI, and opencode.
+> AI coding toolkit with machine-enforced safety, 109 skills, 44 agents, lifecycle hooks, persona presets, opt-in plugin packs, and benchmark tooling. DSH is available as a separate explicit developer-preview target.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1675%20passing-success)](tests/)
-
-## What's New in v4.29.2
-
-**v4.29.2** makes `install --dry-run` tell the truth about Codex hooks:
-
-- Selecting `codex` always installs Codex lifecycle hooks -- `.codex/hooks.json`
-  plus the scripts under `.codex/hooks/` -- at every profile. The dry-run branch
-  listed only agents and skills, so the preview silently omitted a whole surface,
-  and the one you are asked to review and trust with `/hooks`.
-- Both previews now name it: project installs announce
-  `.codex/hooks.json + .codex/hooks/`, global installs add
-  `$CODEX_HOME/ai-toolkit-hooks/` next to `$CODEX_HOME/hooks.json`.
-- Four tests pin the preview against what the live install actually writes, so a
-  surface cannot go missing from the dry-run again. Test count: 1671 -> 1675.
+[![Tests](https://img.shields.io/badge/tests-1920%20passing-success)](tests/)
+
+## What's New in v4.30.2
+
+**v4.30.2** publishes the managed DSH and plugin-owned MCP release with Linux-portable recovery gates:
+
+- `install --local --editors dsh` emits the managed `.agents/skills` surface,
+  while `ai-toolkit dsh install|update|doctor|uninstall --profile web` owns the
+  exact DSH `0.1.1-rc.2`, dsh-codex `1.0.0`, dsh-orchestrator `1.0.1`, and preset
+  lifecycle. DSH remains explicit-only and never handles vendor credentials.
+- Plugin packs can ship MCP templates and native rules for Claude, Codex, Cursor,
+  and Gemini. Two localhost RAG templates are included, bringing the built-in MCP
+  catalogue to 28.
+- Cross-file plugin operations and DSH package mutations now use ownership CAS,
+  pinned paths, process-tree teardown, durable recovery gates, and conservative
+  rollback that preserves concurrent or user-authored data.
+- Recovery verification and interrupted preset relocation now emit deterministic,
+  non-empty diagnostics on both macOS and Linux. File-mode assertions and malformed
+  ownership diagnostics also use the same portable contract. The public `v4.30.0`
+  and `v4.30.1` workflows stopped before npm publication; neither registry artifact
+  was created.
+- Test count: 1675 -> 1920.
 
 ## Table of Contents
 
@@ -74,6 +81,23 @@ ai-toolkit install --local --editors cursor,aider # + specific editors
 ai-toolkit update --local                         # auto-detects editors
 ```
 
+### DSH Developer Preview
+
+DSH has separate project and profile ownership:
+
+```bash
+# Generic local outputs plus DSH-specific .agents/skills. No DSH_HOME write.
+ai-toolkit install --local --editors dsh
+
+# Explicit profile lifecycle.
+ai-toolkit dsh install --profile web
+ai-toolkit dsh update --profile web
+ai-toolkit dsh doctor --profile web
+ai-toolkit dsh uninstall --profile web --yes
+```
+
+DSH is excluded from `--editors all`, auto-detection, and defaults. Its only DSH-specific project output is `.agents/skills`; the normal `--local` Claude files, detected language rules, and other generic project outputs still apply. Project and profile `--dry-run` commands are read-only. The reviewed pins are DSH `0.1.1-rc.2`, `@softspark/dsh-codex@1.0.0`, and `@softspark/dsh-orchestrator@1.0.1`. Codex, Claude Code, and GitHub Copilot own their logins. ai-toolkit accepts no provider API keys, and GitHub AI credits apply to the Copilot Gemini route. Isolated pre-tag and exact-registry post-release qualification completed both Claude Code and Copilot Gemini marker roundtrips through the Codex parent. See [DSH Compatibility](kb/reference/dsh-compatibility.md).
+
 ### Plugin Management
 
 ```bash
@@ -151,6 +175,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Google Antigravity | Project `.agents/{rules,workflows,skills,agents,hooks}/`; user `~/.gemini/config/{skills,agents,hooks}/`; opt-in native plugin export | ✅ | project + user |
 | Codex CLI | Project: `AGENTS.md` + `.agents/skills/*` + `.codex/{agents,hooks}/` + `.codex/{hooks.json,config.toml}`; user: `$CODEX_HOME/{AGENTS.md,agents,hooks.json,config.toml}` + `$HOME/.agents/skills/*` | ✅ | project + user |
 | opencode | `AGENTS.md` + `.opencode/{agents,commands,plugins,skills}/*` + `opencode.{json,jsonc}` | ✅ | project + global (`~/.config/opencode/`) |
+| DeepSeek Harness | Project `.agents/skills/*`; explicit profile packages and `$DSH_HOME/.agent-presets/softspark-orchestrator` | no bridge | project + explicit named profile |
 
 > Claude Code is always installed (primary platform). Other editors are selected with `--editors`; the Claude app uses the separate `claude-app export` flow because its customization store is UI/plugin-managed, except for MCP servers, which `ai-toolkit mcp install --editor claude-app --scope global` writes straight to `claude_desktop_config.json`. The **Hooks** column marks platforms with lifecycle enforcement. Platforms marked — receive guidance without blocking hooks.
 
@@ -188,7 +213,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats and Python test suite (1659 tests)
+├── tests/               # Bats and Python test suite
 └── CHANGELOG.md
 ```
 
@@ -222,7 +247,7 @@ ai-toolkit/
 
 **70 language rules** — 13 languages + common, 5 categories each. Auto-detected or explicit `--lang`. See [Language Rules](kb/reference/language-rules.md).
 
-**26 MCP templates** — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, and more. See [MCP Templates](kb/reference/mcp-templates.md).
+**28 MCP templates** — Ready-to-use configs for GitHub, PostgreSQL, Slack, Jira, Sentry, general RAG, and Polish legal RAG. See [MCP Templates](kb/reference/mcp-templates.md).
 
 See [Unique Features](kb/reference/unique-features.md) for detailed descriptions of all differentiators.
 
@@ -316,6 +341,7 @@ Need multi-agent coordination?
 | Codex CLI Compatibility | [kb/reference/codex-cli-compatibility.md](kb/reference/codex-cli-compatibility.md) |
 | opencode Compatibility | [kb/reference/opencode-compatibility.md](kb/reference/opencode-compatibility.md) |
 | GitHub Copilot Compatibility | [kb/reference/copilot-compatibility.md](kb/reference/copilot-compatibility.md) |
+| DSH Compatibility | [kb/reference/dsh-compatibility.md](kb/reference/dsh-compatibility.md) |
 | Maintenance SOP | [kb/procedures/maintenance-sop.md](kb/procedures/maintenance-sop.md) |
 
 ---

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.29.2",
+  "version": "4.30.2",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/ARCHITECTURE.md

@@ -348,8 +348,8 @@ Lead Session (You)
 
 ## Extension Points
 
-### MCP Templates (26)
-`app/mcp-templates/` ships 26 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
+### MCP Templates (28)
+`app/mcp-templates/` ships 28 ready-to-use MCP server config templates (filesystems, databases, GitHub, Slack, RAG, etc.). Opt-in via `ai-toolkit install --modules mcp-templates` or activated automatically with `--profile strict|full`.
 
 ### Language Rules (68 files, 13 languages)
 `app/rules/` contains per-language coding rules. Supported languages: TypeScript, Python, Go, Rust, Java, Kotlin, Swift, Dart, C#, PHP, C++, Ruby, and common (shared). Auto-detected from project files via `--auto-detect` or selected with `--modules rules-<lang>`.

package/app/mcp-templates/README.md

@@ -4,7 +4,7 @@ Ready-to-use MCP (Model Context Protocol) server configurations for Claude Code
 
 ## What are these?
 
-Each JSON file contains a preconfigured MCP server definition that can be merged into your `.mcp.json` (project-level) or `~/.claude/settings.json` (global). Templates use `${ENV_VAR}` placeholders for secrets -- set the corresponding environment variables before use.
+Each JSON file contains a preconfigured MCP server definition that can be merged into your `.mcp.json` (project-level) or an editor-native global configuration such as `~/.claude.json`. Templates use `${ENV_VAR}` placeholders for secrets -- set the corresponding environment variables before use.
 
 ## Quick start
 
@@ -31,7 +31,7 @@ ai-toolkit mcp remove github
 
 1. Open the template file (e.g., `github.json`)
 2. Copy the `mcpServers` block
-3. Merge it into your `.mcp.json` or `~/.claude/settings.json`
+3. Merge it into your `.mcp.json` or install it through the CLI into the editor-native global configuration
 
 Example -- adding GitHub to `.mcp.json`:
 
@@ -78,8 +78,13 @@ Example -- adding GitHub to `.mcp.json`:
 | `datadog` | Datadog monitoring and metrics |
 | `grafana` | Grafana dashboards and alerting |
 | `jira` | Jira multi-instance routing, ADF, caching, comment templates |
+| `rag-mcp` | General knowledge-base RAG over HTTP MCP (localhost port 8081 by default) |
+| `rag-mcp-legal` | Polish legal RAG over HTTP MCP (localhost port 8082 by default) |
 | `custom-template` | Empty template for custom servers |
 
+The two RAG endpoints are unauthenticated by design. Keep their default
+localhost binding, use a VPN, or place them behind a restricted reverse proxy.
+
 ## Contributing a new template
 
 1. Create `app/mcp-templates/<name>.json` following this structure:

package/app/mcp-templates/rag-mcp-legal.json

@@ -0,0 +1,11 @@
+{
+  "name": "rag-mcp-legal",
+  "description": "Dedicated Polish legal RAG for statutes, contracts, firm knowledge and matter documents via HTTP MCP",
+  "mcpServers": {
+    "rag-mcp-legal": {
+      "type": "http",
+      "url": "http://localhost:8082/mcp/sse"
+    }
+  },
+  "postInstall": "Run make up-legal from the rag-mcp repository before connecting. The default endpoint is http://localhost:8082/mcp/sse. It is unauthenticated by design: keep it on localhost or behind a trusted VPN/reverse-proxy network boundary, never expose it directly to an untrusted network. Edit the installed editor config for a protected non-default deployment."
+}

package/app/mcp-templates/rag-mcp.json

@@ -0,0 +1,11 @@
+{
+  "name": "rag-mcp",
+  "description": "Multi-tenant RAG over knowledge bases — semantic, hybrid, CRAG and multi-hop search via HTTP MCP",
+  "mcpServers": {
+    "rag-mcp": {
+      "type": "http",
+      "url": "http://localhost:8081/mcp/sse"
+    }
+  },
+  "postInstall": "Make sure the rag-mcp server is running on the configured URL (default http://localhost:8081). The /mcp/sse endpoint is unauthenticated by design — restrict access at the network/proxy layer (localhost, VPN, or a reverse-proxy IP allowlist). Edit the installed editor config for a protected non-default deployment. See https://github.com/softspark/rag-mcp for setup."
+}

package/app/surface.json

@@ -265,6 +265,7 @@
     "cursor-mdc",
     "cursor-rules",
     "doctor",
+    "dsh",
     "eject",
     "evaluate",
     "gemini-md",

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-08-21T18:54:11Z",
+  "last_run": "2026-09-01T07:58:08Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "fda8f5ca2c114b30",
+      "docs_hash": "83f1458d1a2060e9",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -51,7 +51,7 @@
         "Auggie CLI": true,
         "MCP": true,
         "Next Edit": false,
-        "Notification": false,
+        "Notification": true,
         "PostToolUse": false,
         "PreToolUse": false,
         "SKILL.md": false,
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "73b44d89c7b771d9",
+      "docs_hash": "273703f5030fd2ab",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -108,7 +108,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "1666675fbb24aaad",
+      "docs_hash": "eea5867f24e1ed91",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -133,7 +133,7 @@
         "LSP servers": false,
         "MCP server": true,
         "MessageDisplay": false,
-        "Notification": false,
+        "Notification": true,
         "PermissionDenied": false,
         "PermissionRequest": false,
         "PostCompact": false,
@@ -174,10 +174,10 @@
         "userConfig": false,
         "workflows": true
       },
-      "version": "2.1.238 (Claude Code)"
+      "version": "2.1.252 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "a0753bb220f610ba",
+      "docs_hash": "13a2b874f0e0173c",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -224,7 +224,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "61d85bae5c0cf885",
+      "docs_hash": "f7df4a0b9f583a2e",
       "headings": [
         "API",
         "API Reference",
@@ -363,10 +363,10 @@
         "plugin marketplace": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.148.0"
+      "version": "codex-cli 0.151.0"
     },
     "cursor": {
-      "docs_hash": "189e666436c73107",
+      "docs_hash": "8665fb50dce5f322",
       "headings": [
         "Agent",
         "CLI",
@@ -375,6 +375,7 @@
         "Cursor Documentation",
         "Customize",
         "Get Started",
+        "Grok Bot",
         "Integrations",
         "Models",
         "More resources",
@@ -397,8 +398,19 @@
         "subagents": true
       }
     },
+    "dsh": {
+      "docs_hash": "265ff3799848801e",
+      "headings": [],
+      "markers": {
+        "Agent Preset": false,
+        "Developer preview": false,
+        "dsh plugin": false,
+        "profiles": false,
+        "skills": true
+      }
+    },
     "gemini-cli": {
-      "docs_hash": "547969f433375d0c",
+      "docs_hash": "02285d342536bdeb",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -436,10 +448,10 @@
         "settings.json": false,
         "tools": true
       },
-      "version": "0.55.1"
+      "version": "0.57.0"
     },
     "github-copilot": {
-      "docs_hash": "a313606be316fada",
+      "docs_hash": "fd80b4ec446cec3f",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -476,7 +488,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "8cbf9aaffb6b57bf",
+      "docs_hash": "9fe532d247c3e361",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -503,7 +515,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "3e9f45631e71a28c",
+      "docs_hash": "154885af5c7de582",
       "headings": [
         "Add features",
         "Ask questions",
@@ -565,7 +577,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "8bf9d2e8b6d36350",
+      "docs_hash": "4a3e8dc19dfdedd6",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -83,6 +83,7 @@ const COMMANDS = {
   'remove-mcp': 'Remove injected MCP servers by source name from ~/.mcp.json and all editor configs',
   validate: 'Verify toolkit integrity',
   doctor: 'Check install health, hooks, and artifact drift',
+  dsh: 'Manage the explicit DeepSeek Harness profile integration',
   eject: 'Export standalone config (no symlinks, no toolkit dependency)',
   benchmark: 'Benchmark toolkit (--my-config to compare your setup vs defaults vs ecosystem)',
   'benchmark-ecosystem': 'Generate ecosystem benchmark snapshot (GitHub metadata + offline fallback)',
@@ -307,6 +308,7 @@ function showHelp() {
   console.log('  --modules <list>  Install specific modules (e.g. core,agents,rules-typescript)');
   console.log('  --lang <list>   Explicitly select language rules (e.g. typescript, go,python)');
   console.log('  --editors <list> Install editor configs: cursor,windsurf,cline,roo,aider,augment,copilot,antigravity,codex,opencode (or "all")');
+  console.log('                  dsh (explicit project target; requires --local; excluded from "all")');
   console.log('                  Default with --local: auto-detect from existing project files');
   console.log('  --auto-detect   Detect project languages and install matching rule modules');
   console.log('  --list, --dry-run  Dry-run: show what would be applied');
@@ -378,6 +380,11 @@ function showHelp() {
   console.log('                                Remove from .mcp.json or native editor configs');
   console.log('\nOptions for doctor:');
   console.log('  --fix           Auto-repair detected issues');
+  console.log('\nOptions for dsh:');
+  console.log('  dsh install --profile web [--dry-run]');
+  console.log('  dsh update --profile web [--dry-run]');
+  console.log('  dsh doctor --profile web');
+  console.log('  dsh uninstall --profile web [--dry-run] [--yes]');
   console.log('\nOptions for stats:');
   console.log('  --summary       Show aggregated product telemetry (usage coverage, top skills, unused catalog)');
   console.log('  --json          Emit raw stats, or machine-readable telemetry when combined with --summary');
@@ -718,6 +725,7 @@ const SPECIAL_HANDLERS = {
   'sync':         handleSync,
   'mcp':          handleMcp,
   'config':       handleConfig,
+  'dsh':          (args) => run(path.join(TOOLKIT_DIR, 'scripts', 'install_steps', 'dsh.py'), args),
   'projects':     (args) => run(scriptPath('projects_cli.py'), args),
   'plugin':       (args) => run(scriptPath('plugin.py'), args),
   'remove-rule':  handleRemoveRule,