@softspark/ai-toolkit 4.25.0 → 4.26.0

package/CHANGELOG.md

@@ -7,6 +7,81 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.26.0 — Python floor is declared and enforced (2026-08-21)
+
+### Added
+
+- **Python preflight in the CLI.** `bin/ai-toolkit.js` now verifies `python3`
+  exists and reports at least 3.11 before spawning any script, and prints a
+  platform-specific fix (`brew install python@3.13` on macOS) instead of a
+  traceback from deep inside `scripts/`. The check is lazy and memoized, so
+  `help` and `--version` still run without a Python interpreter.
+- **Matching floor check in `scripts/_common.py`.** Every entry point imports
+  `_common` first, so `python3 scripts/install.py` run directly fails with the
+  same message rather than a `TypeError` from whichever module happens to use
+  3.11+ syntax.
+- **CI import sweep.** The `python-syntax` job now runs on a `['3.11', '3.13']`
+  matrix and imports every module under `scripts/` on each. `py_compile` only
+  catches syntax, which is exactly why a 3.10-only construct shipped: version-
+  gated runtime features surface on import, not on compile.
+
+### Fixed
+
+- **`ai-toolkit update --local` crashed on macOS system Python.** `/usr/bin/python3`
+  is 3.9 on every Mac, and `scripts/mcp_editors.py` uses
+  `@dataclass(frozen=True, slots=True)` (3.10+), so the install path died with
+  `TypeError: dataclass() got an unexpected keyword argument 'slots'` while
+  importing `install_steps/ai_tools.py`. The interpreter is now rejected up
+  front with instructions.
+
+### Changed
+
+- **`scripts/check_deps.py` declares Python >= 3.11**, up from a `min_version`
+  of `3.8` that never matched what the scripts actually needed, and its reason
+  string calls out the macOS 3.9 trap.
+- **Requirements are documented.** README gained a Requirements note above the
+  install snippet; `CLAUDE.md` records the three places the floor is declared
+  (`bin/ai-toolkit.js`, `scripts/_common.py`, `scripts/check_deps.py`) and the
+  CI matrix that guards it.
+
+### Ecosystem
+
+- Snapshot refreshed: 11 tools drifted, all class A (content reworded, no
+  heading delta). Claude Code 2.1.235 → 2.1.238 and Codex CLI 0.147.0 → 0.148.0
+  are upstream patch bumps with no new surface, so no generator changed.
+
+### Tests
+
+- Three CLI regression tests: a stale `python3` shim exits 1 with the version
+  message, a missing `python3` exits 1 instead of crashing, and `help` still
+  works with no interpreter on PATH. Test count: 1637 → 1640.
+
+---
+
+## v4.25.1 — npm advisories count again (2026-08-19)
+
+### Fixed
+
+- **`cve-scan` reported zero findings for a vulnerable npm project.** npm audit
+  can return the legacy `advisories` object as well as the current
+  `vulnerabilities` object. The scanner parsed only the latter, so five real
+  lodash advisories remained trapped in `raw_output` while `total_findings` was
+  zero and the process exited successfully. Both formats are now normalized,
+  and HIGH advisories restore the documented non-zero exit code.
+
+### Changed
+
+- **The published-package scanner smoke uses real per-scanner fixtures and
+  flags.** It now includes healthcare patterns and a deliberately vulnerable
+  locked npm dependency, invokes `cve-scan` with `--json`, and treats raw npm
+  advisories with no normalized findings as a parser failure.
+
+### Tests
+
+- Added a public-CLI regression test with a stubbed legacy npm audit response;
+  it asserts normalized severity, installed version, CVE, fixed range, finding
+  count, and exit status.
+
 ## v4.25.0 — editor-native integrations catch up (2026-08-19)
 
 ### Added

package/README.md

@@ -6,20 +6,19 @@
 [![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-1636%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1640%20passing-success)](tests/)
 
-## What's New in v4.25.0
+## What's New in v4.26.0
 
-**v4.25.0** brings the editor integrations onto their current native surfaces:
+**v4.26.0** declares and enforces the Python floor the scripts already needed:
 
-- Codex gets its exact 11-event hook contract and a deterministic native plugin
-  exporter with offline verification.
-- Google Antigravity gets native hooks, agents, plugin packaging, MCP mapping,
-  and local/global install profiles.
-- Gemini gains native agents, OpenCode gains native skill directories, and Cline
-  gains native rules plus its exact 8-event hook lifecycle.
-- Claude Code validation now matches the current prompt, agent, HTTP hook, and
-  plugin contracts, with transactional symlink protections across new writers.
+- `ai-toolkit` now checks `python3` before running anything and requires 3.11+.
+- macOS `/usr/bin/python3` is 3.9, which used to crash `update --local` with a
+  raw `dataclass() got an unexpected keyword argument 'slots'` traceback. You
+  now get the version, the requirement, and `brew install python@3.13`.
+- `python3 scripts/*.py` run directly fails the same way, via `_common.py`.
+- CI runs the syntax check plus a full import sweep on both 3.11 and 3.13, so a
+  version-gated runtime feature cannot slip through `py_compile` again.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -42,6 +41,10 @@ See [CHANGELOG.md](CHANGELOG.md) for full history.
 
 ## Install
 
+**Requirements:** Node.js >= 18 and Python >= 3.11.
+
+> **macOS:** `/usr/bin/python3` is Python 3.9 and will not run the toolkit. Install a supported one with `brew install python@3.13` and make sure `which python3` no longer points at `/usr/bin/python3`.
+
 ```bash
 # Option A: install globally (once per machine)
 npm install -g @softspark/ai-toolkit
@@ -185,7 +188,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats and Python test suite (1636 tests)
+├── tests/               # Bats and Python test suite (1640 tests)
 └── CHANGELOG.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.25.0",
+  "version": "4.26.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/skills/cve-scan/scripts/cve_scan.py

@@ -9,7 +9,6 @@ Stdlib only. No external dependencies.
 """
 
 import json
-import os
 import shutil
 import subprocess
 import sys
@@ -141,7 +140,7 @@ def run_audit(eco: dict, root: Path, fix: bool = False) -> dict:
     except FileNotFoundError:
         result["error"] = f"Tool '{eco['tool']}' not found in PATH"
     except subprocess.TimeoutExpired:
-        result["error"] = f"Audit command timed out after 120s"
+        result["error"] = "Audit command timed out after 120s"
 
     return result
 
@@ -168,6 +167,21 @@ def parse_npm_audit(raw: str) -> list[dict]:
                     "url": via.get("url", ""),
                     "fixed_in": info.get("fixAvailable", {}).get("version", "unknown") if isinstance(info.get("fixAvailable"), dict) else "unknown",
                 })
+
+    for advisory in data.get("advisories", {}).values():
+        installed_versions = sorted({
+            finding.get("version", "unknown")
+            for finding in advisory.get("findings", [])
+        })
+        findings.append({
+            "severity": advisory.get("severity", "unknown").upper(),
+            "package": advisory.get("module_name", "unknown"),
+            "installed": ", ".join(installed_versions) or "unknown",
+            "cve": advisory.get("cves", []) or [advisory.get("github_advisory_id", "N/A")],
+            "title": advisory.get("title", "Unknown"),
+            "url": advisory.get("url", ""),
+            "fixed_in": advisory.get("patched_versions", "unknown"),
+        })
     return findings
 
 

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-08-19T14:01:09Z",
+  "last_run": "2026-08-21T08:34:52Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "0f7df1fdf4962938",
+      "docs_hash": "516d8db28cb3ec63",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "5bba2a625b109b69",
+      "docs_hash": "7e06a1985d5bb822",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -107,7 +107,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "3d4394d0bf5dd8c1",
+      "docs_hash": "2b3d6b11c4be766f",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -173,10 +173,10 @@
         "userConfig": false,
         "workflows": true
       },
-      "version": "2.1.235 (Claude Code)"
+      "version": "2.1.238 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "bf058b01d03e0455",
+      "docs_hash": "f93d3a8437c1165f",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -223,7 +223,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "61aea7a06c8c6355",
+      "docs_hash": "fc1c7e43bec9f748",
       "headings": [
         "API",
         "API Reference",
@@ -362,10 +362,10 @@
         "plugin marketplace": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.147.0"
+      "version": "codex-cli 0.148.0"
     },
     "cursor": {
-      "docs_hash": "793ca4e25e676e17",
+      "docs_hash": "2abfadb030c12d07",
       "headings": [
         "Agent",
         "CLI",
@@ -397,7 +397,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "f343c5f7c60fefcf",
+      "docs_hash": "a2c9759e0296670d",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -438,7 +438,7 @@
       "version": "0.55.1"
     },
     "github-copilot": {
-      "docs_hash": "79d741f4e3273f8d",
+      "docs_hash": "ab9b7f5b4b692e05",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -475,7 +475,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "8cbf9aaffb6b57bf",
+      "docs_hash": "9fe532d247c3e361",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -502,7 +502,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "b112229db465d2e4",
+      "docs_hash": "4287f7d767dda4a8",
       "headings": [
         "Add features",
         "Ask questions",
@@ -564,7 +564,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "fddce54b82ac479e",
+      "docs_hash": "60e25f8cb4c381be",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -12,6 +12,9 @@ const fs = require('fs');
 const TOOLKIT_DIR = path.dirname(__dirname);
 const CWD = process.cwd();
 
+/** Minimum Python the toolkit scripts require: [major, minor]. */
+const PYTHON_MIN = [3, 11];
+
 if (!process.env.HOME) {
   console.error('Error: HOME environment variable is not set');
   process.exit(1);
@@ -139,6 +142,60 @@ function scriptPath(scriptName) {
   return path.join(TOOLKIT_DIR, 'scripts', scriptName);
 }
 
+/** Memoized result of requirePython(); null until the first check runs. */
+let pythonOk = null;
+
+/**
+ * Verify `python3` exists and is >= PYTHON_MIN before any script is spawned.
+ * Without this the caller sees a raw traceback from deep inside scripts/
+ * (e.g. `dataclass() got an unexpected keyword argument 'slots'` on Python
+ * 3.9, which is what macOS ships as /usr/bin/python3).
+ * Exits with an actionable message when the interpreter is missing or too old.
+ */
+function requirePython() {
+  if (pythonOk) return;
+  const probe = spawnSync('python3', ['-c', 'import sys; sys.stdout.write("%d.%d.%d" % sys.version_info[:3])'], {
+    encoding: 'utf8',
+  });
+  const want = PYTHON_MIN.join('.');
+
+  if (probe.error || probe.status !== 0) {
+    console.error(`Error: python3 not found on PATH — ai-toolkit requires Python >= ${want}`);
+    console.error(pythonHint());
+    process.exit(1);
+  }
+
+  const found = probe.stdout.trim();
+  const [major, minor] = found.split('.').map(Number);
+  if (major < PYTHON_MIN[0] || (major === PYTHON_MIN[0] && minor < PYTHON_MIN[1])) {
+    console.error(`Error: ai-toolkit requires Python >= ${want}, found ${found}`);
+    console.error(pythonHint());
+    process.exit(1);
+  }
+  pythonOk = true;
+}
+
+/**
+ * Platform-specific instructions for installing a supported Python.
+ * @returns {string} Multi-line hint text
+ */
+function pythonHint() {
+  const lines = [];
+  if (process.platform === 'darwin') {
+    lines.push('macOS ships Python 3.9 as /usr/bin/python3. Install a newer one:');
+    lines.push('  brew install python@3.13');
+    lines.push('Then make sure it comes first on PATH (`which python3` should not be /usr/bin/python3).');
+  } else if (process.platform === 'win32') {
+    lines.push('Install Python 3.11+ and make sure `python3` resolves to it:');
+    lines.push('  winget install Python.Python.3.13');
+  } else {
+    lines.push('Install Python 3.11+ via your package manager, e.g.:');
+    lines.push('  sudo apt install python3.13    # Debian/Ubuntu');
+    lines.push('  sudo dnf install python3.13    # Fedora/RHEL');
+  }
+  return lines.join('\n');
+}
+
 /**
  * Execute a generator script synchronously via python3, returning its stdout.
  * Exits the process on failure.
@@ -147,6 +204,7 @@ function scriptPath(scriptName) {
  * @returns {Buffer} stdout output
  */
 function runGenerator(scriptName, extraArgs = []) {
+  requirePython();
   try {
     return execFileSync('python3', [scriptPath(scriptName), ...extraArgs], { cwd: TOOLKIT_DIR });
   } catch (err) {
@@ -162,6 +220,7 @@ function runGenerator(scriptName, extraArgs = []) {
  * @param {{ cwd?: string }} [opts={}] - Options (cwd override)
  */
 function run(script, args = [], opts = {}) {
+  requirePython();
   const result = spawnSync('python3', [script, ...args], {
     stdio: 'inherit',
     cwd: opts.cwd || CWD,
@@ -178,6 +237,7 @@ function run(script, args = [], opts = {}) {
  * @param {...string} flags - Flags to pass: --rules, --hooks, --mcp
  */
 function propagateGlobal(...flags) {
+  requirePython();
   const result = spawnSync('python3', [scriptPath('propagate_global.py'), ...flags], {
     stdio: 'inherit',
     cwd: CWD,

package/kb/best-practices/README.md

@@ -4,6 +4,7 @@ service: ai-toolkit
 category: best-practices
 tags: [best-practices, guidelines]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit best-practices. No documents are filed here yet; new ones follow the best-practices template."
 ---
 
 # Best Practices

package/kb/howto/README.md

@@ -4,6 +4,7 @@ service: ai-toolkit
 category: howto
 tags: [howto, guides]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit howto. No documents are filed here yet; new ones follow the howto template."
 ---
 
 # How-To Guides

package/kb/procedures/post-release-testing-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Post-Release Testing"
 category: procedures
 service: ai-toolkit
 tags: [sop, post-release, smoke-test, npm, sandbox, plugin-pack, provenance, isolation]
-version: "1.1.0"
+version: "1.2.0"
 created: "2026-07-26"
-last_updated: "2026-08-06"
+last_updated: "2026-08-19"
 description: "Smoke-test a published @softspark/ai-toolkit release from npm in an isolated HOME and npm prefix, without touching the maintainer's real install. Covers provenance, CLI, doctor, per-skill script resolution, scanner wiring, and the full plugin-pack lifecycle including the degraded-install path. Written for v4.18.0 and not run; v4.18.0 shipped a pack that broke every command it touched. First actually run on v4.22.0, which added Phases 4b and 4c after that release fixed four skills whose documented script path had never resolved and two that shipped a scanner nothing invoked."
 ---
 
@@ -159,21 +159,30 @@ cat > "$FX/index.html" <<'EOF'
 <!DOCTYPE html><html><head><title>t</title></head>
 <body><h1>A</h1><h3>skipped h2</h3><img src="x.png"><input type="text"><div onclick="go()">click</div></body></html>
 EOF
-printf '{"name":"fx","dependencies":{"react":"18"}}\n' > "$FX/package.json"
-
-for s in a11y-validate seo-validate hipaa-validate cve-scan; do
-  D="$HOME/.claude/skills/$s"
-  script=$(ls "$D"/scripts/*.py 2>/dev/null | head -1)
-  [ -n "$script" ] || continue
-  echo "=== $s ==="
-  CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$script" "$FX" --output json </dev/null 2>&1 | head -3
-done
+cat > "$FX/patient.py" <<'EOF'
+patient = {"ssn": "123-45-6789", "diagnosis": "fixture"}
+endpoint = "http://example.com/patient"
+encrypt = False
+EOF
+printf '{"name":"fx","dependencies":{"lodash":"4.17.20","react":"18"}}\n' > "$FX/package.json"
+npm install --package-lock-only --ignore-scripts --prefix "$FX"
+
+D="$HOME/.claude/skills/a11y-validate"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/a11y-scanner.py" "$FX" --output json </dev/null
+D="$HOME/.claude/skills/seo-validate"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/seo-scanner.py" "$FX" --output json </dev/null
+D="$HOME/.claude/skills/hipaa-validate"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/hipaa_scan.py" "$FX" --output json </dev/null
+D="$HOME/.claude/skills/cve-scan"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/cve_scan.py" "$FX" --json </dev/null
 ```
 
 **Verify:**
 - [ ] The scanner returns findings, not an empty set — the fixture has real defects
 - [ ] Findings span more than one category, proving the whole check set ran
 - [ ] A scanner that exits non-zero on findings is doing its job, not failing
+- [ ] CVE output has `total_findings > 0`; raw npm advisories with an empty
+      normalized `findings` array are a parser failure, not a clean scan
 
 `a11y-validate` and `seo-validate` shipped working scanners that **no step in
 either skill invoked** for their entire life before v4.22.0. The model was told to

package/kb/reference/enterprise-config-guide.md

@@ -11,7 +11,7 @@ tags:
 doc_type: reference
 created: "2026-04-11"
 last_updated: "2026-07-26"
-description: "Comprehensive guide for setting up and using ai-toolkit configuration inheritance. Covers base config creation, project setup, enforcement rules, CI integration, and troubleshooting."
+description: "Configuration inheritance for ai-toolkit projects extends base settings from npm packages, Git URLs, or local paths. Defines merge semantics, enforcement rules, and CLI commands for validating and diffing configurations."
 ---
 
 # Enterprise Config Inheritance Guide

package/kb/troubleshooting/README.md

@@ -4,6 +4,7 @@ service: ai-toolkit
 category: troubleshooting
 tags: [troubleshooting, debugging]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit troubleshooting. No documents are filed here yet; new ones follow the troubleshooting template."
 ---
 
 # Troubleshooting

package/llms-full.txt

@@ -243,6 +243,7 @@ service: ai-toolkit
 category: best-practices
 tags: [best-practices, guidelines]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit best-practices. No documents are filed here yet; new ones follow the best-practices template."
 ---
 
 # Best Practices
@@ -5081,6 +5082,7 @@ service: ai-toolkit
 category: howto
 tags: [howto, guides]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit howto. No documents are filed here yet; new ones follow the howto template."
 ---
 
 # How-To Guides
@@ -7041,9 +7043,9 @@ title: "SOP: Post-Release Testing"
 category: procedures
 service: ai-toolkit
 tags: [sop, post-release, smoke-test, npm, sandbox, plugin-pack, provenance, isolation]
-version: "1.1.0"
+version: "1.2.0"
 created: "2026-07-26"
-last_updated: "2026-08-06"
+last_updated: "2026-08-19"
 description: "Smoke-test a published @softspark/ai-toolkit release from npm in an isolated HOME and npm prefix, without touching the maintainer's real install. Covers provenance, CLI, doctor, per-skill script resolution, scanner wiring, and the full plugin-pack lifecycle including the degraded-install path. Written for v4.18.0 and not run; v4.18.0 shipped a pack that broke every command it touched. First actually run on v4.22.0, which added Phases 4b and 4c after that release fixed four skills whose documented script path had never resolved and two that shipped a scanner nothing invoked."
 ---
 
@@ -7197,21 +7199,30 @@ cat > "$FX/index.html" <<'EOF'
 <!DOCTYPE html><html><head><title>t</title></head>
 <body><h1>A</h1><h3>skipped h2</h3><img src="x.png"><input type="text"><div onclick="go()">click</div></body></html>
 EOF
-printf '{"name":"fx","dependencies":{"react":"18"}}\n' > "$FX/package.json"
-
-for s in a11y-validate seo-validate hipaa-validate cve-scan; do
-  D="$HOME/.claude/skills/$s"
-  script=$(ls "$D"/scripts/*.py 2>/dev/null | head -1)
-  [ -n "$script" ] || continue
-  echo "=== $s ==="
-  CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$script" "$FX" --output json </dev/null 2>&1 | head -3
-done
+cat > "$FX/patient.py" <<'EOF'
+patient = {"ssn": "123-45-6789", "diagnosis": "fixture"}
+endpoint = "http://example.com/patient"
+encrypt = False
+EOF
+printf '{"name":"fx","dependencies":{"lodash":"4.17.20","react":"18"}}\n' > "$FX/package.json"
+npm install --package-lock-only --ignore-scripts --prefix "$FX"
+
+D="$HOME/.claude/skills/a11y-validate"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/a11y-scanner.py" "$FX" --output json </dev/null
+D="$HOME/.claude/skills/seo-validate"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/seo-scanner.py" "$FX" --output json </dev/null
+D="$HOME/.claude/skills/hipaa-validate"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/hipaa_scan.py" "$FX" --output json </dev/null
+D="$HOME/.claude/skills/cve-scan"
+CLAUDE_SKILL_DIR="$D" timeout 60 python3 "$D/scripts/cve_scan.py" "$FX" --json </dev/null
 ```
 
 **Verify:**
 - [ ] The scanner returns findings, not an empty set — the fixture has real defects
 - [ ] Findings span more than one category, proving the whole check set ran
 - [ ] A scanner that exits non-zero on findings is doing its job, not failing
+- [ ] CVE output has `total_findings > 0`; raw npm advisories with an empty
+      normalized `findings` array are a parser failure, not a clean scan
 
 `a11y-validate` and `seo-validate` shipped working scanners that **no step in
 either skill invoked** for their entire life before v4.22.0. The model was told to
@@ -11046,7 +11057,7 @@ tags:
 doc_type: reference
 created: "2026-04-11"
 last_updated: "2026-07-26"
-description: "Comprehensive guide for setting up and using ai-toolkit configuration inheritance. Covers base config creation, project setup, enforcement rules, CI integration, and troubleshooting."
+description: "Configuration inheritance for ai-toolkit projects extends base settings from npm packages, Git URLs, or local paths. Defines merge semantics, enforcement rules, and CLI commands for validating and diffing configurations."
 ---
 
 # Enterprise Config Inheritance Guide
@@ -16120,6 +16131,7 @@ service: ai-toolkit
 category: troubleshooting
 tags: [troubleshooting, debugging]
 last_updated: "2026-03-25"
+description: "Section index for ai-toolkit troubleshooting. No documents are filed here yet; new ones follow the troubleshooting template."
 ---
 
 # Troubleshooting

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.25.0",
+  "version": "4.26.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.25.0",
+  "version": "4.26.0",
   "description": "AI coding toolkit: 109 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/_common.py

@@ -20,8 +20,35 @@ from __future__ import annotations
 import os
 import platform
 import shutil
+import sys
 from pathlib import Path
 
+# ---------------------------------------------------------------------------
+# Python version floor
+# ---------------------------------------------------------------------------
+# Kept in sync with PYTHON_MIN in bin/ai-toolkit.js and the python3 entry in
+# scripts/check_deps.py. Checked here because _common is imported first by
+# every entry point, so a stale interpreter fails with this message instead of
+# a traceback from whichever module happens to use 3.11+ syntax.
+PYTHON_MIN = (3, 11)
+
+if sys.version_info < PYTHON_MIN:
+    _want = ".".join(str(n) for n in PYTHON_MIN)
+    _found = ".".join(str(n) for n in sys.version_info[:3])
+    sys.stderr.write(
+        "Error: ai-toolkit requires Python >= {}, found {} ({})\n".format(
+            _want, _found, sys.executable
+        )
+    )
+    if sys.platform == "darwin":
+        sys.stderr.write(
+            "macOS ships Python 3.9 as /usr/bin/python3. Install a newer one:\n"
+            "  brew install python@3.13\n"
+        )
+    else:
+        sys.stderr.write("Install Python 3.11+ via your package manager.\n")
+    sys.exit(1)
+
 # ---------------------------------------------------------------------------
 # Re-exports from frontmatter module
 # ---------------------------------------------------------------------------

package/scripts/check_deps.py

@@ -33,7 +33,7 @@ REQUIRED = [
     {
         "name": "python3",
         "check": "python3",
-        "min_version": "3.8",
+        "min_version": "3.11",
         "packages": {
             "brew": "python3",
             "apt": "python3",
@@ -45,7 +45,7 @@ REQUIRED = [
             "choco": "python",
             "scoop": "python",
         },
-        "reason": "All toolkit scripts run on Python 3 (stdlib only, no pip needed)",
+        "reason": "All toolkit scripts run on Python 3.11+ (stdlib only, no pip needed). macOS /usr/bin/python3 is 3.9 and will not work.",
     },
     {
         "name": "git",