@softspark/ai-toolkit 4.32.3 → 4.32.4

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

@@ -3,10 +3,10 @@ title: "SOP: Post-Release Testing"
 category: procedures
 service: ai-toolkit
 tags: [sop, post-release, smoke-test, npm, sandbox, plugin-pack, provenance, isolation]
-version: "1.2.0"
+version: "1.2.1"
 created: "2026-07-26"
-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."
+last_updated: "2026-09-06"
+description: "Smoke-test a published @softspark/ai-toolkit npm artifact in a disposable container or VM with its default HOME, no host settings or credential mounts, host-side configuration fingerprints, and retained evidence. Covers provenance, CLI, doctor, installed skill scripts, scanner wiring, and the plugin-pack lifecycle."
 ---
 
 # SOP: Post-Release Testing
@@ -16,73 +16,147 @@ actually install, from npm, rather than the working tree.
 
 Sibling procedures exist for `jira-mcp` and `legal-pl-pack`; this is the
 ai-toolkit equivalent. It complements
-[Release Verification](sop-release-verification.md), which checks the toolkit
-from the maintainer's own installed copy. The difference that matters: this one
-never writes to the maintainer's `~/.claude` or `~/.softspark`.
+[Release Verification](sop-release-verification.md), whose cross-editor checks
+must use the same isolated published artifact. Neither procedure installs or
+updates the maintainer's working copy.
 
 **Time:** 10 minutes.
 
 ## Why isolation is the first step, not a detail
 
-The toolkit installs into `$HOME`. Testing a release against your own HOME
-means the test either pollutes your working setup or, worse, passes because of
-state your setup already had. Both make the result meaningless.
+The toolkit writes settings beneath the current user's home directory. Run the
+published artifact in a disposable Docker container or VM with its normal HOME.
+Do not override host HOME, CODEX_HOME, or another editor's configuration root as
+a substitute for isolation. Do not expose the host home, credentials, SSH agent,
+Docker socket, or existing toolkit installation to the test environment.
 
-Every command below runs against a throwaway HOME and a throwaway npm prefix.
-Nothing is global.
+## Phase 1: Create and verify an isolated test environment
 
-## Phase 1: Sandbox
+The recipe below uses Docker. A disposable VM is equivalent only when host shared
+folders and authentication forwarding are absent. The host needs Docker and
+Python 3; the container prerequisites are installed separately below.
+
+**Host terminal:** keep this terminal open for Phases 7 and 8. The fingerprint
+reads only these toolkit-managed settings files and records hashes and presence,
+never their contents. Add a path only after verifying that the tested installer
+actually manages it.
 
 ```bash
-SB=$(mktemp -d)
-mkdir -p "$SB/home" "$SB/npm"
-export HOME="$SB/home"
-AT="$SB/npm/bin/ai-toolkit"
-echo "sandbox: $SB"
+set -o pipefail
+VERSION="X.Y.Z"
+EVIDENCE=$(mktemp -d "${TMPDIR:-/tmp}/ai-toolkit-release-${VERSION}.XXXXXX")
+SMOKE_CONTAINER=$(python3 -c 'import uuid; print("ai-toolkit-smoke-" + uuid.uuid4().hex)')
+
+fingerprint_host() {
+  python3 - <<'PY'
+import hashlib
+import json
+import os
+from pathlib import Path
+
+home = Path.home()
+managed = [
+    ".claude/settings.json",
+    ".claude.json",
+    ".softspark/ai-toolkit/plugins.json",
+    ".codex/config.toml",
+    ".cursor/mcp.json",
+    ".gemini/settings.json",
+    ".config/opencode/opencode.json",
+]
+rows = {}
+for relative in managed:
+    path = home / relative
+    row = {"exists": path.exists() or path.is_symlink()}
+    if path.is_symlink():
+        row["link_sha256"] = hashlib.sha256(os.readlink(path).encode()).hexdigest()
+    if path.is_file():
+        row["sha256"] = hashlib.sha256(path.read_bytes()).hexdigest()
+    rows[relative] = row
+print(json.dumps({
+    "host_home_sha256": hashlib.sha256(str(home).encode()).hexdigest(),
+    "files": rows,
+}, sort_keys=True, indent=2))
+PY
+}
+
+fingerprint_host > "$EVIDENCE/host-before.json"
+docker run -d --name "$SMOKE_CONTAINER" \
+  --label "org.softspark.release-smoke=$SMOKE_CONTAINER" \
+  --env "VERSION=$VERSION" \
+  node:22-bookworm sleep infinity
+docker inspect "$SMOKE_CONTAINER" > "$EVIDENCE/container-before.json"
+python3 - "$EVIDENCE/container-before.json" <<'PY'
+import json
+import sys
+
+container = json.load(open(sys.argv[1], encoding="utf-8"))[0]
+assert container["Mounts"] == [], "Smoke container must have no mounts"
+host = container["HostConfig"]
+assert not host["Privileged"], "Privileged containers are forbidden"
+assert host["NetworkMode"] != "host", "Do not share the host network namespace"
+assert host["PidMode"] != "host", "Do not share host processes"
+PY
+docker exec "$SMOKE_CONTAINER" bash -lc \
+  'test "$HOME" = "$(getent passwd "$(id -u)" | cut -d: -f6)"'
+docker exec "$SMOKE_CONTAINER" bash -lc \
+  'apt-get update && apt-get install -y --no-install-recommends python3 python3-yaml git coreutils jq bats shellcheck ca-certificates curl util-linux' \
+  2>&1 | tee "$EVIDENCE/bootstrap.log"
 ```
 
-Record the real state now, so Phase 7 can prove it is unchanged:
+Install any additional prerequisite declared by the pack under test only inside
+the container. GNU coreutils supplies timeout; util-linux supplies the session
+recorder. Use docker cp for evidence transfer, not host temporary-directory bind
+mounts: a remote Docker daemon may not see the host's /private/tmp.
+
+**Enter the container, then run Phases 2 through 6 there:**
 
 ```bash
-python3 -c "
-import json, pathlib
-p = pathlib.Path('$SB/../real-before.json')
-import os
-home = pathlib.Path(os.path.expanduser('~'))
-" 2>/dev/null
-# Simpler: note what exists today.
-cat ~/.softspark/ai-toolkit/plugins.json 2>/dev/null
+docker exec -it "$SMOKE_CONTAINER" bash
 ```
 
+Inside that container shell:
+
+```bash
+SB=/tmp/ai-toolkit-smoke
+AT="$SB/npm/bin/ai-toolkit"
+mkdir -p "$SB/npm" "$SB/evidence"
+export SB AT
+exec script -q -e -a "$SB/evidence/session.log" -c 'bash --noprofile --norc'
+```
+
+Keep HOME at the container user's default. VERSION was passed when the container
+was created; SB and the npm prefix are disposable container paths. No command in
+Phases 2 through 6 runs in the host shell.
+
 ## Phase 2: Provenance
 
 Do this before installing anything: an unsigned publish is a release-blocking
 regression, and there is no point smoke-testing a build you would have to redo.
 
 ```bash
-VERSION="X.Y.Z"
-npm view "@softspark/ai-toolkit@${VERSION}" --json \
-  | python3 -c "
+npm view "@softspark/ai-toolkit@${VERSION}" --json > "$SB/evidence/npm-view.json"
+python3 -c "
 import json, sys
-d = json.load(sys.stdin); att = d['dist'].get('attestations', {})
+d = json.load(open(sys.argv[1], encoding='utf-8')); att = d['dist'].get('attestations', {})
 pt = att.get('provenance', {}).get('predicateType')
 assert pt == 'https://slsa.dev/provenance/v1', f'NO PROVENANCE: {pt}'
 print('PROVENANCE OK:', att['url'])
-"
+" "$SB/evidence/npm-view.json"
 ```
 
 ## Phase 3: Install from npm
 
 ```bash
 npm install -g --prefix "$SB/npm" "@softspark/ai-toolkit@${VERSION}"
-"$AT" --version    # must equal VERSION
+"$AT" --version | tee "$SB/evidence/version.txt"    # must equal VERSION
 "$AT" --help >/dev/null && echo "help OK"
 ```
 
 ## Phase 4: Core surfaces
 
 ```bash
-"$AT" install            # full global install into the sandbox HOME
+"$AT" install            # global install inside the container's default HOME
 "$AT" doctor             # must end: Errors: 0 | Warnings: 0
 "$AT" status
 "$AT" plugin list        # pack count must match app/plugins/
@@ -120,8 +194,13 @@ for D in "$HOME"/.claude/skills/*/; do
   rel=${ref##*\$\{CLAUDE_SKILL_DIR\}/}
   printf '%-22s %-10s %-26s ' "$s" "$interp" "$rel"
   [ -f "$D/$rel" ] || { echo 'PATH DOES NOT RESOLVE'; continue; }
-  out=$(CLAUDE_SKILL_DIR="$D" timeout 20 "$interp" "$D/$rel" --help </dev/null 2>&1 | head -1)
-  printf 'rc=%s %s\n' "$?" "$(echo "$out" | cut -c1-40)"
+  if out=$(CLAUDE_SKILL_DIR="$D" timeout 20 "$interp" "$D/$rel" --help </dev/null 2>&1); then
+    rc=0
+  else
+    rc=$?
+  fi
+  printf '%s\n' "$out" > "$SB/evidence/skill-$s.log"
+  printf 'rc=%s %s\n' "$rc" "$(printf '%s\n' "$out" | head -1 | cut -c1-40)"
 done
 ```
 
@@ -262,37 +341,59 @@ again, pointing its source-override variable at a dead URL:
 - [ ] `plugin status` says the pack is inert and names the fix
 - [ ] Re-installing without the broken source recovers
 
-## Phase 7: Prove the real environment is untouched
+## Phase 7: Verify the host configuration
+
+Exit the recorded container shell. This returns to the unchanged host terminal
+from Phase 1. Run fingerprint_host there, not through docker exec and not in a
+shell that changed HOME:
 
 ```bash
-python3 -c "
-import json, pathlib
-d = json.loads(pathlib.Path.home().joinpath('.softspark/ai-toolkit/plugins.json').read_text())
-print('plugins.json:', d['targets']['claude'])
-p = pathlib.Path.home() / '.claude/settings.json'
-print('pack hook leaked into real settings:', '<pack>' in json.dumps(json.loads(p.read_text()).get('hooks', {})) if p.exists() else False)
-print('pack paths in real ~/.softspark:', len(list(pathlib.Path.home().joinpath('.softspark').rglob('*<pack>*'))))
-"
+fingerprint_host > "$EVIDENCE/host-after.json"
+cmp -s "$EVIDENCE/host-before.json" "$EVIDENCE/host-after.json" || {
+  diff -u "$EVIDENCE/host-before.json" "$EVIDENCE/host-after.json"
+  echo "Host configuration changed: investigate before accepting the release."
+  exit 1
+}
+docker inspect "$SMOKE_CONTAINER" > "$EVIDENCE/container-after.json"
 ```
 
-All three must show the pre-test state.
+The fingerprints must match. This proves the enumerated managed settings stayed
+unchanged; the recorded container configuration separately proves there were no
+host mounts or shared host namespaces. Do not claim to have hashed the whole
+home directory, or print settings contents to demonstrate isolation.
 
-## Phase 8: Clean up
+## Phase 8: Preserve evidence and remove only the owned container
 
-`guard-destructive.sh` blocks `rm -rf` on a `PreToolUse` hook, so removal goes
-through an enumerated delete that reports what it removed:
+Run on the host, after leaving the container shell. Confirm ownership before any
+cleanup, then copy the recorded session, npm provenance metadata, and CLI version.
+Keep the host evidence directory for the release record.
 
 ```bash
-python3 -c "
-import pathlib, shutil
-sb = pathlib.Path('$SB')
-assert sb.is_dir() and str(sb).startswith(('/tmp', '/var/folders')), sb
-n = sum(1 for _ in sb.rglob('*') if _.is_file())
-shutil.rmtree(sb)
-print(f'removed {sb} ({n} files)')
-"
+test "$(docker inspect --format '{{index .Config.Labels "org.softspark.release-smoke"}}' "$SMOKE_CONTAINER")" = "$SMOKE_CONTAINER" || {
+  echo "Container ownership does not match; refusing cleanup."
+  exit 1
+}
+docker logs "$SMOKE_CONTAINER" > "$EVIDENCE/container.log" 2>&1
+mkdir -p "$EVIDENCE/container"
+docker cp "$SMOKE_CONTAINER:/tmp/ai-toolkit-smoke/evidence/." "$EVIDENCE/container/" || {
+  echo "Evidence transfer failed; keep the container and investigate."
+  exit 1
+}
+test -f "$EVIDENCE/container/session.log" || {
+  echo "Session evidence is missing; refusing cleanup."
+  exit 1
+}
+docker stop "$SMOKE_CONTAINER"
+docker rm "$SMOKE_CONTAINER"
+printf 'Evidence retained: %s\n' "$EVIDENCE"
 ```
 
+There are no host bind mounts or named volumes to delete. Never bypass a
+destructive-command guard with Python, shutil.rmtree, another interpreter, or a
+different deletion tool. If a guard rejects cleanup, leave the owned container
+and evidence in place and report the rejection through the normal approval
+mechanism. Do not prune Docker resources or delete unrelated temporary files.
+
 ## Success criteria
 
 | Area | Criterion |
@@ -306,10 +407,10 @@ print(f'removed {sb} ({n} files)')
 | Pack update | Current version silent; stale version updates and re-records |
 | Pack removal | Zero residue in `~/.softspark` and `settings.json`; re-install works |
 | Degraded path | Fetch failure is inert, loud in status, and recoverable |
-| Isolation | Real `~/.claude` and `~/.softspark` byte-identical to pre-test |
+| Isolation | Host-side managed-settings fingerprints match; container has no host mounts or shared host namespaces |
 
 ## Related
 
 - [Release Preparation](sop-release.md) — run before tagging
-- [Release Verification](sop-release-verification.md) — the maintainer-install checks
+- [Release Verification](sop-release-verification.md) — cross-editor checks of the isolated npm artifact
 - [rtk-pack Retirement](../history/completed/rtk-pack-retirement-20260727.md) — what happened the one time this SOP was written and not run

package/kb/procedures/sop-release-verification.md

@@ -3,9 +3,9 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif, dsh]
-version: "1.8.0"
+version: "1.8.1"
 created: "2026-04-08"
-last_updated: "2026-09-01"
+last_updated: "2026-09-06"
 description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit. Verifies CLI, native Codex and GitHub Copilot surfaces, explicit DSH lifecycle, Claude app export, doctor, validation, tests, eject, provenance, SARIF, and per-skill permissions."
 ---
 
@@ -23,12 +23,30 @@ Verifies all critical paths from the user's perspective.
 
 **Prerequisites:**
 - Node.js >= 18, Python 3, `bats`, git
-- `@softspark/ai-toolkit` installed globally
+- The target version of `@softspark/ai-toolkit` installed in a disposable test environment
 
 **Time:** 10-15 minutes (full), 2 minutes (quick checklist)
 
 ---
 
+## Verification environment
+
+Run installation, update, eject and editor smoke checks in a disposable
+container or VM with its own OS user and default home directory. Do not
+reassign `HOME` or `CODEX_HOME`, mount the operator's home/authentication
+directories, or alter the global installation used by an active session.
+Use the packed release candidate before publication and the exact npm version
+after publication; the installed package must be the source of runtime checks.
+Source validation and test commands still run from the matching release checkout.
+
+A scratch project alone does not isolate home-scoped writes. In particular,
+the live Augment checks in Phase 9 write user settings. Execute them inside
+the disposable environment, retain logs outside it, and remove only resources
+created for this verification run. Do not treat a dry-run as proof that emitted
+files parse or that a second install is idempotent.
+
+---
+
 ## Quick Checklist (TL;DR)
 
 The 14 core commands below must pass. Releases that change DSH must also complete Phase 10.
@@ -123,9 +141,11 @@ ai-toolkit status
 ```
 
 **Verify `--dry-run`:**
-- [ ] Agents: 44
-- [ ] Skills: 108
-- [ ] Hooks merged into settings.json
+- [ ] Agent and skill totals match the target package's `app/agents/` and
+      `app/skills/*/SKILL.md` inventory; compare with that release's validator
+      output and README badges, not a number copied from an older release
+- [ ] Dry-run describes the planned hook merge; the isolated installed copy
+      contains the expected hooks in settings.json
 - [ ] "Other AI Tools" lists documented global targets (with `--editors`): aider, antigravity, augment, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf. Scope varies: Codex uses `$CODEX_HOME` (default `~/.codex`) plus `$HOME/.agents/skills`; Copilot uses `$COPILOT_HOME` (default `~/.copilot`); cursor has only `~/.cursor/hooks.json`; antigravity has the `~/.gemini/*/skills` pointer. Cursor and Antigravity rules remain project-only.
 
 **Verify `status`:**
@@ -195,9 +215,12 @@ python3 scripts/audit_skills.py --ci
 ```
 
 **Verify validate.py:**
-- [ ] Agents: 44, Skills: 108, Tests: exactly the current README badge count
-- [ ] Hook events: 14, Hook scripts: >= 30
-- [ ] Plugin packs >= 10, KB documents >= 20
+- [ ] Agent, skill and Bats test totals match the current release inventory
+      and README badges, as checked by the validator's metadata contracts
+- [ ] Hook events/scripts match `app/hooks.json` and the shipped hook files
+- [ ] Every shipped plugin pack and KB document passes its validator; compare
+      inventory with the release checkout rather than requiring an obsolete
+      fixed minimum number of packs or documents
 - [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
 
 **Verify audit_skills.py:**
@@ -210,7 +233,7 @@ python3 scripts/audit_skills.py --ci
 ## Phase 6: Tests (3-5 min)
 
 ```bash
-# Run ONCE, capture to file, then parse. Full suite is 669+ bats cases —
+# Run ONCE, capture to file, then parse. Use the current release's Bats count;
 # re-running it per check (tail / grep ok / grep not ok piped separately)
 # wastes minutes every release. Always cache the output.
 npm test > /tmp/npm-test.log 2>&1
@@ -223,7 +246,7 @@ echo "exit:   $exit"
 
 **Verify:**
 - [ ] `exit == 0`
-- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
+- [ ] `ok == expected test count` from the current release's metadata contracts
 - [ ] `not ok == 0`
 - [ ] Bats runs tests in parallel (4 jobs)
 - [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
@@ -334,7 +357,7 @@ AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
 
 These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.
 
-> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.
+> Run this phase inside the disposable verification environment. `--profile full` with `augment` writes to `$HOME/.augment/settings.json`, so a temporary project on the operator's machine is insufficient. Dry-run checks cover the planned paths; Phases 9.4 and 9.5 must also exercise actual writes in isolation.
 
 ### 9.1 `--profile full` emits every native surface
 
@@ -411,7 +434,9 @@ The bats suite validates JSON shape at generation time. This re-checks that what
 D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
 ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex,copilot --profile full >/dev/null 2>&1
 for f in .cursor/hooks.json .devin/hooks.v1.json .gemini/settings.json .codex/hooks.json .github/hooks/ai-toolkit.json "$HOME/.augment/settings.json"; do
-  [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
+  [ -f "$f" ] || { echo "MISSING: $f"; exit 1; }
+  python3 -c 'import json, sys; json.load(open(sys.argv[1]))' "$f" || exit 1
+  echo "OK: $f"
 done
 ```
 

package/kb/procedures/sop-release.md

@@ -3,9 +3,9 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
-version: "1.15.0"
+version: "1.15.1"
 created: "2026-04-10"
-last_updated: "2026-09-02"
+last_updated: "2026-09-06"
 description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, branch CI, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, checksum-pin, ShellCheck, licensing, exact-tag assertions, and a green Ubuntu/macOS branch-CI gate before any release tag is created."
 ---
 
@@ -15,6 +15,13 @@ Complete checklist for preparing a new `@softspark/ai-toolkit` release.
 Run this **before** tagging. After tagging and publishing, run the
 [Release Verification SOP](sop-release-verification.md) to smoke-test.
 
+Installation smoke uses a disposable container or VM with its own default
+home directory, as described in the verification SOP. Test the packed release
+candidate before publishing and the exact npm version afterward. Keep the
+operator's installed toolkit, editor settings and authentication directories
+outside that environment. Compare component counts with the current release
+inventory and validator output instead of historical constants in a checklist.
+
 **Pipeline:**
 ```
 Ecosystem Sync SOP (drift check + generator updates)

package/kb/reference/architecture-overview.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.10.0"
+version: "1.10.1"
 created: "2026-03-23"
-last_updated: "2026-09-01"
+last_updated: "2026-09-06"
 description: "Architecture of ai-toolkit: install ownership, runtime adapters, the explicit DSH target, skill tiers, and project integration."
 ---
 
@@ -315,7 +315,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 ## Quality Hooks
 
-29 entries across 14 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
+28 entries across 14 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
 
 | Hook | Trigger | Script | Action |
 |------|---------|--------|--------|

package/kb/reference/language-rules.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [rules, languages, coding-style, testing, patterns, security]
 version: "2.2.0"
 created: "2026-04-07"
-last_updated: "2026-09-04"
+last_updated: "2026-09-06"
 description: "Reference for the language-specific rules system: 13 per-language rule sets shipped as knowledge skills, plus common rules installed as Claude Code path-scoped project rules."
 ---
 
@@ -78,6 +78,12 @@ app/rules/
 
 ## Rule Categories
 
+The common security rules distinguish safe, actionable failure messages from
+private diagnostics. Common testing rules cover API error contracts and prohibit
+overlapping runners that reset a shared database. The `api-patterns` skill carries
+the focused error-contract guidance; the `review` checklist checks the same
+failure boundaries. These are content rules, not new hooks or runtime permissions.
+
 | Category | Filename | Content |
 |----------|----------|---------|
 | `coding-style` | `coding-style.md` | Naming, formatting, idiomatic constructs, linter config |

package/kb/reference/skills-catalog.md

@@ -5,7 +5,7 @@ service: ai-toolkit
 tags: [skills, domain-knowledge, catalog, task-skills, hybrid-skills]
 version: "1.5.0"
 created: "2026-03-23"
-last_updated: "2026-08-06"
+last_updated: "2026-09-06"
 description: "Complete skills catalog with task, hybrid, and knowledge skills. Includes Codex adaptation notes, effort levels, skill-scoped hooks, executable scripts, security auditor, and persona presets."
 ---
 
@@ -123,7 +123,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | Skill | Directory | Domain |
 |-------|-----------|--------|
 | **app-builder** | `skills/app-builder/` | Full-stack application architecture |
-| **api-patterns** | `skills/api-patterns/` | REST/GraphQL design, versioning, error handling |
+| **api-patterns** | `skills/api-patterns/` | API design, versioning, actionable error contracts and safe retries; focused `reference/error-contracts.md` |
 | **database-patterns** | `skills/database-patterns/` | Schema design, indexing, query optimization |
 | **flutter-patterns** | `skills/flutter-patterns/` | Flutter/Dart architecture, state management |
 | **ecommerce-patterns** | `skills/ecommerce-patterns/` | E-commerce: catalog, cart, checkout, payments |