@softspark/ai-toolkit 2.12.0 → 3.0.1

package/kb/procedures/ecosystem-sync-sop.md

@@ -0,0 +1,255 @@
+---
+title: "SOP: Ecosystem Sync"
+category: procedures
+service: ai-toolkit
+tags: [sop, ecosystem, editors, generators, drift-detection, sync]
+version: "1.0.0"
+created: "2026-04-23"
+last_updated: "2026-04-23"
+description: "Quarterly (or event-triggered) sync procedure that detects documentation and capability drift in supported tools (Claude Code + 11 editors), analyses our generators and skills for missing features, and walks through the migration + generator-update workflow."
+---
+
+# SOP: Ecosystem Sync
+
+Keeps ai-toolkit aligned with the tools it integrates with. When an editor adds a new hook lifecycle, makes a feature globally available, changes a config path, or deprecates a flag, this SOP surfaces it before it surprises users.
+
+**When to run:**
+- **Every quarter** as a baseline health check (calendar reminder)
+- **Before every minor release** of ai-toolkit (Phase 0 of release prep)
+- **Whenever an editor ships a major version** (subscribe to their changelogs)
+- **On demand** if a user reports "feature X exists but toolkit doesn't support it"
+
+**Time:** 30 minutes for drift review + variable for any generator updates
+
+---
+
+## Quick Reference
+
+```bash
+# Full check (all 12 tools, online)
+python3 scripts/ecosystem_doctor.py --format text
+
+# Single tool
+python3 scripts/ecosystem_doctor.py --tool cursor --format text
+
+# First-ever run — baseline the snapshot
+python3 scripts/ecosystem_doctor.py --update > /dev/null
+
+# CI / gating mode
+python3 scripts/ecosystem_doctor.py --check
+
+# Offline (no network) — validates our side only
+python3 scripts/ecosystem_doctor.py --offline --format text
+```
+
+---
+
+## Inputs
+
+| File | Purpose |
+|------|---------|
+| `scripts/ecosystem_tools.json` | Authoritative registry: 12 tools with doc URLs, config paths, our generators, capability markers |
+| `benchmarks/ecosystem-doctor-snapshot.json` | Last-seen state (headings, content hash, markers, version) — updated via `--update` |
+| `scripts/ecosystem_doctor.py` | Drift detector |
+| `kb/reference/supported-tools-registry.md` | Human-readable view of the registry |
+
+---
+
+## Phase 1: Run the Doctor
+
+```bash
+python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
+cat /tmp/eco-report.txt
+```
+
+The report classifies every tool into:
+
+- **Clean** — doc page, headings, and markers match the last snapshot; no action
+- **Drift** — something changed upstream. Each drift entry has a `kind`:
+  - `headings_added` — the doc grew new sections (new features? reorg?)
+  - `headings_removed` — a section disappeared (deprecation? renaming?)
+  - `marker_flips` — an expected capability marker appeared (`+`) or vanished (`-`)
+  - `content_changed_no_heading_delta` — prose edits, reorder, minor rewrites, OR HTML churn (timestamps, ads, CSRF nonces). Reported but **not** treated as drift by `--check` — too noisy on dynamic pages.
+  - `version_changed` — the CLI version bumped (for tools that expose `--version`)
+- **Errored** — couldn't fetch docs (timeout, 404, auth wall). Doctor does not overwrite
+  the snapshot for errored tools; the last-known-good state persists.
+
+---
+
+## Phase 2: Classify Each Drift
+
+For every drifting tool, read its docs URL and classify the change into exactly one bucket:
+
+| Drift class | What it means | Action owner |
+|-------------|---------------|--------------|
+| **A. Cosmetic reword** | Prose edited, same feature set | Update snapshot (`--update`), no code change |
+| **B. New feature — we should integrate** | New hook event, new config key, new CLI flag, new rule surface | Update the relevant generator in `scripts/generate_<tool>_*.py`; extend `app/skills/*` or `app/agents/*` if the feature maps onto our skills; document in `kb/reference/supported-tools-registry.md` |
+| **C. New feature — not our concern** | Enterprise SSO, billing, proprietary UI-only features | Note in registry `capability_markers` as "not adopted"; update snapshot |
+| **D. Deprecation** | Flag or path removed / renamed | Open migration issue; coordinate with `ai-toolkit install` and generator output; add deprecation warning to CLAUDE.md rules if user-facing |
+| **E. Feature promoted to default** | Was behind a flag, now global | Remove the flag from generator output; simplify our installer |
+| **F. Global availability** | Was editor-only, now also available via CLI / hooks / settings.json | Map new config surface; may require a new generator or extending an existing one |
+
+Write one line per drift in `/tmp/eco-report.txt` with its class. Example:
+
+```
+cursor: headings_added [AGENTS.md support] -> class B (integrate: extend generate_cursor_mdc.py)
+aider:  version_changed 0.70 -> 0.72          -> class A (cosmetic, --update)
+windsurf: marker_flips +Cascade               -> class B (already supported, verify snapshot)
+```
+
+---
+
+## Phase 3: Execute Changes
+
+### For class B (new feature — integrate)
+
+1. Read the tool's docs section that introduced the feature. Note the exact config key / hook name / file path.
+2. Open the relevant generator (`scripts/generate_<tool>_*.py`) and add output for the new surface.
+3. If the feature is a **hook event**, also update:
+   - `app/hooks.json` (if Claude-Code-native)
+   - `app/skills/hook-creator/SKILL.md` — add the event to the Supported Hook Events table
+   - `scripts/inject_hook_cli.py` — if the hook target path differs
+4. If the feature is a **skill/agent schema extension**:
+   - Update `app/skills/skill-creator/SKILL.md` and `app/skills/command-creator/SKILL.md` templates
+   - Update `scripts/validate.py` field allowlists
+   - Update `kb/reference/agent-skills-spec.md` (if the change is an upstream spec change)
+5. Add a bats test under `tests/test_<tool>.bats` covering the new output.
+6. Regenerate artifacts: `npm run generate:all`.
+
+### For class D (deprecation)
+
+1. Open a migration issue in GitHub with "class: deprecation" and a link to the upstream changelog.
+2. In the generator, mark the deprecated output path as emitting a comment: `# DEPRECATED: <link>, removed in <version>`.
+3. If deprecation affects `ai-toolkit install --local --editors <tool>`, add a doctor check that warns when a user's repo still contains the deprecated file.
+
+### For class E / F (feature promotion)
+
+1. Simplify the generator to emit the new-default form; keep a fallback comment for users on older tool versions.
+2. Update `kb/reference/supported-tools-registry.md` config-paths column.
+
+### For class A / C (no code change)
+
+1. Run `python3 scripts/ecosystem_doctor.py --update --tool <id>` to refresh that tool's snapshot.
+
+---
+
+## Phase 4: Update the Registry
+
+If new capability markers, config paths, or doc URLs emerged during Phase 3, edit `scripts/ecosystem_tools.json`:
+
+```bash
+${EDITOR:-nvim} scripts/ecosystem_tools.json
+```
+
+Fields to consider updating:
+- `urls.docs` — if the vendor moved their docs
+- `urls.release_notes` — if the changelog location changed
+- `config_paths` — if new files now ship in our install output
+- `our_generators` — if a new generator was added
+- `capability_markers` — if a new feature was adopted
+- `version_probe.command` — if the CLI binary was renamed
+
+After editing, increment `last_updated` in the registry and save the snapshot:
+
+```bash
+python3 scripts/ecosystem_doctor.py --update
+```
+
+---
+
+## Phase 5: Validate
+
+```bash
+python3 scripts/validate.py --strict
+python3 scripts/audit_skills.py --ci
+python3 scripts/ecosystem_doctor.py --check              # exits 0 after --update
+npm test
+```
+
+All four must pass before committing generator / registry changes.
+
+---
+
+## Phase 6: Commit
+
+Use a structured commit per change class:
+
+```bash
+git add scripts/ecosystem_tools.json benchmarks/ecosystem-doctor-snapshot.json
+git add scripts/generate_<tool>_*.py                  # if class B/D/E/F
+git add app/skills/<skill>/SKILL.md                   # if templates touched
+git add kb/reference/supported-tools-registry.md
+git commit -m "chore(ecosystem): sync <tool> — <brief summary>"
+```
+
+Recommended commit messages by class:
+
+| Class | Template |
+|-------|----------|
+| A | `chore(ecosystem): refresh <tool> snapshot (cosmetic docs update)` |
+| B | `feat(<tool>): add support for <feature>` |
+| C | `chore(ecosystem): note <tool> <feature> as not-adopted` |
+| D | `feat(<tool>): deprecation warning for <old-path>` |
+| E | `refactor(<tool>): remove flag for <feature> (now default)` |
+| F | `feat(<tool>): add <new-surface> generator` |
+
+---
+
+## Gotchas
+
+- **First run has no baseline.** On a machine where `benchmarks/ecosystem-doctor-snapshot.json` does not exist, every tool shows as clean (no prior state to diff against). Run `--update` once to seed, then run again to see real drift.
+- **Documentation sites use client-side rendering.** Aider, opencode, and Antigravity serve most content via JavaScript. `urllib` fetches the bare HTML skeleton — the doctor only sees a few headings. Combine the automated check with a manual visit to the docs on these tools.
+- **Release notes pages change structure more often than docs.** Cursor and Windsurf refactor their changelog layouts periodically; a heading delta from a changelog page is often a presentation change, not a feature change. Classify as A when in doubt.
+- **Version probes require the CLI to be installed locally.** `gemini --version`, `aider --version`, etc. are skipped silently when the binary isn't on `$PATH`. The snapshot therefore omits version drift for tools you haven't installed — that is intentional, not a bug.
+- **GitHub release pages have anti-scraping.** `github.com/<org>/<repo>/releases` works via `urllib` but rate-limits aggressively. If the doctor errors on repeated runs, wait 10 minutes or manually review the release page.
+- **Marker list is intentionally small.** Capability markers are a "did we adopt this?" checklist, not a feature coverage map. Adding every sub-feature bloats the JSON and produces noisy flips — keep markers at the top-level-capability tier.
+- **`--check` only gates on structural drift.** Heading/marker/version changes and fetch errors exit `1`. Pure content-hash differences (`content_changed_no_heading_delta`) exit `0` — otherwise dynamic pages with timestamps or rotating ads would page you every run. If you want the strictest possible gate, grep for `Content changed` in the text report instead.
+
+---
+
+## Scheduling
+
+Recommended cadence:
+
+| Trigger | Action |
+|---------|--------|
+| Every Monday morning | `python3 scripts/ecosystem_doctor.py --format text` — scan during coffee |
+| Before a minor release | Full sync + clean snapshot before tagging |
+| After any drift report | Act within 1 week or record explicit "ignore, low priority" in the commit message |
+| New tool added to the registry | Baseline with `--update --tool <id>` |
+| Tool removed from support | Delete its entry from the registry AND from the snapshot JSON |
+
+An optional GitHub Action can run `--check` weekly and open an issue on drift. Template:
+
+```yaml
+# .github/workflows/ecosystem-doctor.yml  (proposed, not yet committed)
+on:
+  schedule:
+    - cron: '0 9 * * 1'        # Mondays 09:00 UTC
+  workflow_dispatch: {}
+jobs:
+  doctor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: python3 scripts/ecosystem_doctor.py --format text | tee /tmp/doctor.txt
+      - run: python3 scripts/ecosystem_doctor.py --check
+```
+
+---
+
+## When NOT to Use
+
+- For **runtime** user support (user hit a bug with an editor) — use `/debug` or `/triage-issue`
+- For **picking** an editor to add — that is a product decision, not a sync; use `/architecture-decision`
+- For **one-off** testing of a specific tool's install flow — use the release-verification SOP
+- For **scaling up** the supported-tools list — add the new tool to the registry, then run the SOP to baseline it
+
+---
+
+## Related Documentation
+
+- [Supported Tools Registry](../reference/supported-tools-registry.md) — human-readable per-tool breakdown
+- [MCP Editor Compatibility](../reference/mcp-editor-compatibility.md) — MCP-specific adapter table
+- [Maintenance SOP](maintenance-sop.md) — general toolkit upkeep
+- [Release Preparation SOP](release-preparation-sop.md) — run the doctor before tagging

package/kb/procedures/maintenance-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "1.4.4"
+version: "3.0.0"
 created: "2026-03-23"
-last_updated: "2026-04-13"
+last_updated: "2026-04-23"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -91,6 +91,17 @@ What `install` and `update` do (merge-friendly — user content never overwritte
 
 Re-running updates only toolkit content. Old whole-directory symlinks are auto-upgraded to per-file on next run.
 
+### Install Profiles (v3.0.0)
+
+| Profile | Claude Code core | Editor rules | Gemini hooks | Copilot dir layout | Per-editor hooks / sub-agents / commands | Git hooks |
+|---------|:---------------:|:------------:|:------------:|:------------------:|:---------------------------------------:|:---------:|
+| `minimal` | yes | pointer only | no | no | no | no |
+| `standard` (default) | yes | yes | **yes** (new in v3) | **yes** (new in v3) | no | no |
+| `strict` | yes | yes | yes | yes | no | yes |
+| `full` | yes | yes | yes | yes | **yes, all editors** | optional |
+
+`--codex-skills` is orthogonal to `--profile` and materializes the full skill catalog under `.agents/skills/` for Codex. See `kb/reference/global-install-model.md` for the full semantic breakdown.
+
 ---
 
 ## Update Toolkit

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

@@ -2,11 +2,11 @@
 title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
-tags: [sop, release, version, publish, changelog, semver, provenance, sarif]
-version: "1.8.0"
+tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem]
+version: "1.10.0"
 created: "2026-04-10"
-last_updated: "2026-04-21"
-description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, and the single-run npm test discipline added in v1.8.0."
+last_updated: "2026-04-24"
+description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, and the registry-vs-generators drift gate added in v1.10.0."
 ---
 
 # SOP: Release Preparation
@@ -17,20 +17,33 @@ Run this **before** tagging. After tagging and publishing, run the
 
 **Pipeline:**
 ```
-Release Preparation (this SOP) → git tag → CI publish → Release Verification SOP
+Ecosystem Sync SOP (drift check + generator updates)
+      ↓
+Release Preparation (this SOP)
+      ↓
+git tag → CI publish → Release Verification SOP
 ```
 
-**Time:** 5-10 minutes
+**Time:** 10-20 minutes (includes ecosystem sync review)
 
 ---
 
 ## Quick Checklist (TL;DR)
 
 ```bash
+# 0. Ecosystem sync (mandatory for minor/major releases; optional for patch)
+#    Full procedure: kb/procedures/ecosystem-sync-sop.md
+python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
+cat /tmp/eco-report.txt
+# If drift detected: stop here, follow ecosystem-sync-sop.md Phase 2-4 to
+# classify each drift (A-F), update generators as needed, refresh snapshot,
+# THEN resume this SOP.
+python3 scripts/ecosystem_doctor.py --update    # after all drift resolved
+
 # 1. Decide version bump
 #    patch (1.4.2 → 1.4.3): bugfix, typo, doc fix
-#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag
-#    major (1.4.2 → 2.0.0): breaking change
+#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag, any ecosystem-class-B/F change
+#    major (1.4.2 → 2.0.0): breaking change, any ecosystem-class-D removed path
 
 # 2. Sync version across all files
 python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
@@ -42,7 +55,7 @@ python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
-# 5. Validate + audit + SARIF + test
+# 5. Validate + audit + SARIF + test + ecosystem check
 python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && npm test
 
 # 5a. Supply-chain standard (v2.8.0+) — non-negotiable
@@ -50,6 +63,9 @@ grep -q -- '--provenance' .github/workflows/publish.yml || { echo "MISSING --pro
 grep -q 'id-token: write'   .github/workflows/publish.yml || { echo "MISSING id-token: write"; exit 1; }
 python3 scripts/audit_skills.py --permissions   # review Bash/Write/Edit footprint
 
+# 5b. Ecosystem gate — snapshot must be current before tag
+python3 scripts/ecosystem_doctor.py --offline --check || { echo "STALE ecosystem snapshot — re-run doctor"; exit 1; }
+
 # 6. Commit + tag + push
 git add -A && git commit -m "chore: release vX.Y.Z"
 git tag vX.Y.Z
@@ -58,6 +74,60 @@ git push origin main --tags
 
 ---
 
+## Phase 0: Ecosystem Sync (MANDATORY for minor/major)
+
+Before touching version numbers, confirm the toolkit is aligned with the current state of every editor / platform it integrates with. Skipping this phase ships a release whose generators may lag a month-old CLI refactor, a rename of `.cursorrules` to `.cursor/rules/`, or a new hook event we do not yet emit.
+
+**When this phase is mandatory:**
+- Minor release (X.Y.0) — always
+- Major release (X.0.0) — always
+- Patch release (X.Y.Z) — only if the patch touches a generator or install flow
+
+**When to skip:** pure doc-only patches, SOP edits, internal refactors that do not touch `scripts/generate_*` or `app/skills/*/SKILL.md`.
+
+### 0.1 Run the doctor
+
+```bash
+python3 scripts/ecosystem_doctor.py --format text | tee /tmp/eco-report.txt
+```
+
+Output classifies every registered tool as **Clean**, **Drift**, or **Errored**.
+
+### 0.2 Act on drift
+
+For each drifting tool, follow [ecosystem-sync-sop.md](ecosystem-sync-sop.md) Phase 2-4:
+
+| Drift class | Release impact |
+|-------------|----------------|
+| A (cosmetic reword) | No version impact — refresh snapshot, continue |
+| B (new feature — integrate) | **Minor** version bump at minimum; new generator or extended generator |
+| C (new feature — not adopted) | No impact — note in registry |
+| D (deprecation) | **Minor** or **major** depending on user impact; add migration warning |
+| E (feature promoted to default) | **Minor**; simplify generator, keep fallback comment |
+| F (feature newly globally available) | **Minor**; may require new generator or new config path |
+
+If any B/D/E/F changes land in this preparation pass, mention them explicitly in the CHANGELOG entry (Phase 3) under a `Ecosystem` subsection.
+
+### 0.3 Refresh snapshot
+
+Once every drift is resolved (either by code change or by re-classifying as acceptable):
+
+```bash
+python3 scripts/ecosystem_doctor.py --update
+```
+
+This writes the new baseline to `benchmarks/ecosystem-doctor-snapshot.json`. Commit it as part of the release commit.
+
+### 0.4 Gate
+
+```bash
+python3 scripts/ecosystem_doctor.py --offline --check
+```
+
+Must exit `0`. If it exits `1`, the snapshot is stale — rerun Phase 0.3 or review the remaining drift.
+
+---
+
 ## Phase 1: Determine Version Bump
 
 Follow [Semantic Versioning](https://semver.org/):
@@ -208,7 +278,15 @@ python3 scripts/audit_skills.py --ci
 python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS ingest
 python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint
 
-# Run npm test ONCE, cache output, parse from file. The suite is 669+ bats
+# Registry / generator drift (added in 1.10.0). Meta-generators excluded.
+META="generate_agents_md.py|generate_llms_txt.py"
+diff \
+  <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
+  <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
+  && echo "OK: registry matches filesystem" \
+  || { echo "DRIFT: update supported-tools-registry.md before tagging"; exit 1; }
+
+# Run npm test ONCE, cache output, parse from file. The suite is 900+ bats
 # cases — rerunning it per check wastes minutes. Do not pipe npm test into
 # tail/grep multiple times in the same session.
 npm test > /tmp/npm-test.log 2>&1
@@ -221,11 +299,12 @@ echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp
 - `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
 - `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
 - `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
+- Registry drift: `OK: registry matches filesystem`. If `DRIFT:` appears, add the missing `scripts/generate_*.py` rows to `kb/reference/supported-tools-registry.md` before tagging.
 - `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
 
 **One-liner:**
 ```bash
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && npm test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py' | sort -u) && npm test
 ```
 
 **If tests fail:** Fix the issue, do NOT skip. Common failures:
@@ -338,13 +417,16 @@ git push origin --delete vX.Y.Z
 
 | # | Step | Command / Action | Pass Criteria |
 |---|------|-----------------|---------------|
+| 0a | Ecosystem drift check | `ecosystem_doctor.py --format text` | All tools Clean, or drift classified and resolved |
+| 0b | Ecosystem snapshot refresh | `ecosystem_doctor.py --update` | `benchmarks/ecosystem-doctor-snapshot.json` updated |
+| 0c | Ecosystem gate | `ecosystem_doctor.py --offline --check` | Exit 0 |
 | 1 | Version bump type | Decide patch/minor/major | — |
 | 2 | `package.json` version | Edit `"version"` | Matches target |
 | 3 | `manifest.json` version | Edit `"version"` | Matches target |
 | 4 | `plugin.json` version | Edit `"version"` | Matches target |
 | 5 | `package-lock.json` | `npm install --package-lock-only` | Matches target |
 | 6 | Count sync | Check `package.json` description, README | `validate.py` passes |
-| 7 | CHANGELOG.md | Add release entry | Entry exists for vX.Y.Z |
+| 7 | CHANGELOG.md | Add release entry (incl. `Ecosystem` subsection if any B/D/E/F drift) | Entry exists for vX.Y.Z |
 | 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_codex_rules.py`, `generate_llms_txt.py` | No unexpected diff |
 | 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
 | 10 | Security audit (CI mode) | `audit_skills.py --ci` | 0 HIGH |

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

@@ -3,10 +3,10 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.3.0"
+version: "1.4.0"
 created: "2026-04-08"
-last_updated: "2026-04-21"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 adds the single-run npm test discipline (cache to file, parse ok/not-ok once)."
+last_updated: "2026-04-24"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds."
 ---
 
 # SOP: Release Verification
@@ -52,6 +52,10 @@ python3 scripts/audit_skills.py --ci                        # 10. Security audit
 python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')"   # 11. SARIF 2.1.0 well-formed?
 python3 scripts/audit_skills.py --permissions | head -30    # 12. Broad-access skills reviewed?
 npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 13. Provenance attested on npm?
+
+# Deep-coverage verification (Phase 9, v3.0.0+)
+META="generate_agents_md.py|generate_llms_txt.py"
+diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 14. Registry <-> generators drift?
 ```
 
 ---
@@ -117,8 +121,8 @@ ai-toolkit status
 ```
 
 **Verify `--dry-run`:**
-- [ ] Agents >= 40
-- [ ] Skills >= 80
+- [ ] Agents >= 44
+- [ ] Skills >= 99
 - [ ] Hooks merged into settings.json
 - [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
 
@@ -168,7 +172,7 @@ cd - && rm -rf /tmp/ai-toolkit-verify
 - [ ] Would create: CLAUDE.md
 - [ ] Would create: .claude/settings.local.json
 - [ ] Would inject: .claude/constitution.md
-- [ ] Editors: all 8 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity)
+- [ ] Editors: all 11 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity, codex, gemini, opencode)
 - [ ] Would generate configs for each editor (legacy + directory-based)
 - [ ] Would install: .git/hooks/pre-commit
 - [ ] Would inject language rules (auto-detected)
@@ -189,7 +193,7 @@ python3 scripts/audit_skills.py --ci
 ```
 
 **Verify validate.py:**
-- [ ] Agents >= 40, Skills >= 80, Tests >= 350
+- [ ] Agents >= 44, Skills >= 99, Tests >= 900
 - [ ] Hook events: 12, Hook scripts: >= 20
 - [ ] Plugin packs >= 10, KB documents >= 20
 - [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
@@ -217,7 +221,7 @@ echo "exit:   $exit"
 
 **Verify:**
 - [ ] `exit == 0`
-- [ ] `ok == expected test count` (e.g., 669)
+- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
 - [ ] `not ok == 0`
 - [ ] Bats runs tests in parallel (4 jobs)
 - [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
@@ -322,6 +326,101 @@ AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
 
 ---
 
+## Phase 9: Deep-Coverage Checks (v3.0.0+)
+
+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.
+
+### 9.1 `--profile full` emits every native surface
+
+```bash
+D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
+  --profile full --codex-skills --dry-run 2>&1 \
+  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.windsurf/hooks\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/skills"
+```
+
+**Verify** — at least the following lines appear:
+- [ ] `.cursor/hooks.json` and `.cursor/agents/`
+- [ ] `.windsurf/hooks.json`
+- [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
+- [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
+- [ ] `.codex/skills/` (opt-in via `--codex-skills`)
+
+### 9.2 `--codex-skills` is orthogonal to `--profile`
+
+```bash
+D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
+  | grep -q "Would generate: .codex/skills" && echo "OK: --codex-skills works without --profile full"
+ai-toolkit install --local --editors codex --profile full --dry-run 2>&1 \
+  | grep -q "Would generate: .codex/skills" && echo "FAIL: --profile full should NOT auto-emit .codex/skills" \
+  || echo "OK: --profile full alone does not auto-emit .codex/skills (correct — opt-in only)"
+```
+
+**Verify:**
+- [ ] `--codex-skills` emits `.codex/skills/` at any profile
+- [ ] `--profile full` alone does NOT emit `.codex/skills/` (must be opt-in)
+
+### 9.3 Breaking-change surfaces land on `--profile standard`
+
+v3.0.0 moved two surfaces from opt-in to default:
+- Copilot directory layout (`.github/instructions/`, `.github/prompts/`)
+- Gemini hooks (`.gemini/settings.json`)
+
+```bash
+D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
+  | tee /tmp/aitk-breaking.log
+grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
+grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
+```
+
+**Verify both lines print `OK:`**. If either is missing, a regression has unwound the v3.0.0 breaking change.
+
+### 9.4 Install is idempotent
+
+```bash
+D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
+SHA1=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
+SHA2=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+[ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
+```
+
+**Verify:** prints `OK: idempotent`. A second run must produce byte-identical files in every managed path.
+
+### 9.5 Live-install JSON outputs parse
+
+The bats suite validates JSON shape at generation time. This re-checks that what actually landed on disk after a live install parses without errors.
+
+```bash
+D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment --profile full >/dev/null 2>&1
+for f in .cursor/hooks.json .windsurf/hooks.json .gemini/settings.json $HOME/.augment/settings.json; do
+  [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
+done
+```
+
+**Verify:** each emitted file prints `OK: <path>`. Any `json.decoder.JSONDecodeError` means the merge logic corrupted the output.
+
+### 9.6 Registry / generator drift check
+
+`kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.
+
+```bash
+META="generate_agents_md.py|generate_llms_txt.py"
+REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
+FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
+diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"
+```
+
+**Verify:** prints `OK: registry matches filesystem`. If not, add the missing rows to the registry before tagging the next release.
+
+---
+
 ## Troubleshooting
 
 ### `ai-toolkit: command not found`
@@ -376,3 +475,8 @@ ai-toolkit eject /tmp/test # retry
 | Tests | `npm test`: N/N passed, 0 failures |
 | Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
 | Guards | Destructive commands blocked |
+| Deep coverage | `--profile full` emits all 9 v3.0.0 native surfaces; `--codex-skills` works orthogonally |
+| Breaking changes | Copilot directory layout + Gemini hooks emit at `--profile standard` (v3.0.0 contract) |
+| Idempotence | Second `install` run produces byte-identical output in every managed path |
+| Live JSON | Every generated `.json` file on disk parses as valid JSON |
+| Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |