@softspark/ai-toolkit 2.12.0 → 3.0.0

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.9.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-23"
+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, and the ecosystem-sync gate added in v1.9.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/):
@@ -338,13 +408,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/reference/global-install-model.md

@@ -3,9 +3,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "1.4.4"
+version: "3.0.0"
 created: "2026-03-26"
-last_updated: "2026-04-13"
+last_updated: "2026-04-23"
 description: "Reference description of the global install target, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -39,6 +39,19 @@ installed with `ai-toolkit plugin install --editor codex`.
 | `ai-toolkit plugin update --editor claude|codex|all <name>` | runtime-native config | re-apply plugin pack after toolkit updates |
 | `ai-toolkit plugin remove --editor claude|codex|all <name>` | runtime-native config | remove plugin pack from selected runtime(s) |
 
+## Install Profiles (v3.0.0)
+
+The `--profile` flag controls how much of each editor's native surface is activated.
+
+| Profile | What runs | Use when |
+|---------|-----------|----------|
+| `minimal` | Agents and skills only. No editor generators beyond pointer skills for editors that require them. | You want the smallest possible footprint, or you manage editor configs by hand. |
+| `standard` (default) | Claude Code + editor rule files. Includes **Gemini hooks** and the **Copilot directory layout** (v3.0.0 change from prior `standard`). | Day-to-day installs. Most users. |
+| `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks. | Solo dev or tight team with zero tolerance for drift. |
+| `full` | Every native surface across every editor: hooks, sub-agents, custom commands, skill pointers for Cursor / Windsurf / Gemini / Augment / Antigravity. | You want maximum coverage and understand that each editor will carry generated files under its own layout. |
+
+`--codex-skills` is an independent opt-in flag (not part of profile) that materializes the full `.claude/skills/` catalog under `.agents/skills/` for Codex. Other editors stay on compat-read or the per-editor pointer skill.
+
 ## Why global install is the default
 
 - less setup friction,