@softspark/ai-toolkit 4.5.1 → 4.6.0

package/AGENTS.md

@@ -597,6 +597,56 @@ Derived from the immutable safety constitution (6 articles):
 - **Cite Sources**: Always reference `[PATH: ...]` when making decisions based on existing knowledge
 - **Read-Only Exploration**: Discovery agents never write; writing agents never explore blindly
 - **No Secrets in Code**: Never commit credentials, API keys, or sensitive configuration values
+
+## Coding Rules
+
+### Code Style
+
+* Follow language-specific conventions: PEP 8 (Python), StandardJS/Prettier (TypeScript), gofmt (Go), rustfmt (Rust)
+* Use descriptive names: functions as verbs (`calculateTotal`), booleans as questions (`isValid`), constants as UPPER_SNAKE
+* Keep functions short — single responsibility, max ~30 lines
+* Prefer immutability: use `const`/`final`/`let` over mutable variables where possible
+* No magic numbers — extract to named constants
+* Avoid deep nesting (max 3 levels) — use early returns and guard clauses
+* DRY: extract shared logic only when used 3+ times; premature abstraction is worse than duplication
+* YAGNI: do not build features or abstractions for hypothetical future requirements
+
+### Testing
+
+* Every new feature or bug fix must include tests
+* Use Arrange-Act-Assert pattern for unit tests
+* Test behavior, not implementation — tests should survive refactoring
+* Use descriptive test names: `test_<what>_<when>_<expected>`
+* Prefer real dependencies over mocks at integration boundaries
+* Target >70% code coverage for new code
+* Never skip or disable tests without a linked issue explaining why
+* Run the full test suite before marking work as done
+
+### Security
+
+* Never commit secrets, API keys, credentials, or tokens — use environment variables
+* Validate and sanitize all external input (user input, API responses, file uploads)
+* Use parameterized queries — never concatenate SQL strings
+* Escape output to prevent XSS in web contexts
+* Apply principle of least privilege for file permissions and API scopes
+* Keep dependencies updated — audit regularly for known CVEs
+* Use HTTPS for all external communication
+* Log security events without logging sensitive data (passwords, tokens, PII)
+
+### Output Mode
+
+`output-mode: concise`
+
+Default response mode is **concise**. The `brand-voice` skill (when present) auto-loads concise rules; assistants without that skill should still apply the directives below.
+
+* No preamble — skip "I'll now...", "Sure, let me...", "Great question!" Start with the answer.
+* Lead with the result — conclusion or output first; explanation only if asked or non-obvious.
+* Max 3 sentences per closed question — yes/no, single-fact, or "where is X" answers stay under three sentences.
+* Tables and lists over prose — when comparing options, listing steps, or showing values.
+* No trailing summaries — if the diff or output already shows what changed, do not restate it.
+* Drop filler adjectives — no "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+* Cite as `path:line` — instead of paragraphs describing where things live.
+* Escalate to verbose only for: architecture / RFC / ADR / trade-off documents, or when the user asks for detail.
 <!-- TOOLKIT:ai-toolkit END -->
 
 <!-- TOOLKIT:jira-mcp START -->

package/CHANGELOG.md

@@ -7,6 +7,34 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.6.0 - Editor ecosystem sync + Codex rules in AGENTS.md (2026-06-05)
+
+Minor release. Syncs the editor registry with current upstream reality (Windsurf→Devin rebrand, Roo Code archive, Gemini CLI sunset, moved docs hosts) and fixes several generators that wrote to paths their editors never read. Headline: Codex now actually receives the universal coding rules.
+
+### Added
+- **Codex CLI: all 10 native hook events** — wired the 5 previously-missing events (`PostToolUse`, `PreCompact`, `PostCompact`, `SubagentStart`, `SubagentStop`) to the shared toolkit hook scripts, mirroring `app/hooks.json`. Was 5 of 10.
+
+### Changed
+- **Codex CLI: coding rules now in `AGENTS.md`** — the universal code-style/testing/security/output-mode rule bodies are inlined into `AGENTS.md`, the only instruction path Codex reads. They were previously emitted to `.agents/rules/`, which Codex never reads (confirmed against `developers.openai.com/codex`). Language rules continue via `.agents/skills/`.
+- **Google Antigravity: plural `.agents/`** — generators now emit `.agents/rules/` and `.agents/workflows/` (the Antigravity 2.0 default); singular `.agent/` is still read by Antigravity as a fallback.
+- **Conditional skill pointers** — Cursor/Cline/Augment skip the `ai-toolkit-skill-catalogue` pointer when real skills are discoverable at `.claude/skills/` (project or `~/.claude/skills/`), emitting it only as the editor-only fallback. Windsurf keeps its pointer unconditionally (its `.claude/skills` scan is gated behind a Devin "Claude Code config reading" setting).
+- **Cursor subagents** — emit `model: inherit`; dropped the undocumented `tools`/`color` fields to match the current Cursor schema.
+- **Augment subagents** — omit the `model` field (Augment uses the CLI default model; `inherit` is not a documented value).
+- **Ecosystem registry sync** — Windsurf → Devin Desktop (docs/changelog redirects); Roo Code repo archived + docs moved to `roocodeinc.github.io`; Claude Code docs host `code.claude.com`; Codex docs `developers.openai.com/codex`; Gemini CLI free/paid tier sunset 2026-06-18 (enterprise continues); Cline config-path corrections; stale Gemini `Stop` marker dropped.
+
+### Fixed
+- **opencode commands were empty** — the prompt now lives in the markdown body. Commands previously put it in a `template:` frontmatter block (JSON-config-only) with an empty body, so every generated opencode command was effectively blank.
+- **Cline global rules** — now written to `~/Documents/Cline/Rules/` (the documented Cline global path) instead of the never-read `~/.cline/rules/`.
+- **Augment commands** — dropped the undocumented `agent:` frontmatter field; fixed a false `generate_augment_hooks.py` docstring claim about per-workspace settings.
+
+### Removed
+- **`scripts/generate_codex_rules.py`** and the `ai-toolkit codex-rules` / `npm run generate:codex-rules` subcommands — Codex never read the `.agents/rules/` output. Coding rules now ship via `AGENTS.md` (universal) and `.agents/skills/` (language). Installs need no migration; if you scripted `ai-toolkit codex-rules`, the rules are now produced by `ai-toolkit codex-md`. Test count: 1181 → 1179 (dead-path tests removed).
+
+### Ecosystem
+- Class B (integrate): Codex 10 hook events. Class E (now-default): Antigravity plural `.agents/`, conditional skill pointers. Class D (deprecation): Windsurf→Devin, Roo Code archive, Gemini CLI tier sunset. Plus registry URL/version/config-path corrections across 9 tools.
+
+---
+
 ## v4.5.1 - ShellCheck fix for loop-guard hook (2026-06-02)
 
 Patch release. Clears two ShellCheck `SC2034` warnings in `loop-guard.sh` that turned the `main` CI ShellCheck job red after v4.5.0. The publish workflow does not run ShellCheck, so v4.5.0 published despite the red CI; this patch makes `main` green again. No runtime behavior change.

package/README.md

@@ -8,15 +8,15 @@
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
 [![Tests](https://img.shields.io/badge/tests-1179%20passing-success)](tests/)
 
-## What's New in v4.5.1
+## What's New in v4.6.0
 
-v4.5.1 is a patch that clears a ShellCheck lint in the loop-guard hook. The v4.5.0 feature set: hardens the security audit against invisible prompt injection, adds a repeated-action loop guard, fixes destructive-guard false positives, and makes the instinct system actually work.
+v4.6.0 syncs the editor ecosystem with current upstream reality and fixes several generators that were writing to paths their editors never read.
 
-- **Unicode-safety scanner**: the skill/agent audit now flags invisible and smuggled Unicode (tag-block ASCII smuggling, Trojan Source bidi controls) across all shipped prompt text — a prompt-injection vector regex checks never caught. Runs in the `--ci` gate.
-- **Loop guard**: a new advisory `PostToolUse` hook warns when the same action repeats, catching stuck loops that the `/repeat` failure-counter circuit breaker misses.
-- **`git push --force-with-lease` unblocked**: the destructive-command guard no longer false-positives on safe force-pushes or on commit messages that merely mention `DROP TABLE`/`rm -rf`.
-- **Instincts load by default**: hand-authored `.claude/instincts/*.md` now load at session start (previously dormant behind a verbose flag). The skill docs were corrected to drop a never-implemented auto-extractor claim.
-- **Editor honesty + secret scrubbing**: the platform matrix marks which editors get hook enforcement, and memory-pack now redacts secrets before storing session observations.
+- **Codex finally gets its coding rules**: the universal code-style/testing/security rules are now inlined into `AGENTS.md` (the only file Codex reads) instead of the never-read `.agents/rules/`. Codex also now wires all 10 native lifecycle hook events.
+- **opencode commands fixed**: the prompt now lives in the markdown body — it previously went into a `template:` frontmatter block that opencode ignores, producing empty commands.
+- **Cline global rules land where Cline reads them**: `~/Documents/Cline/Rules/` instead of the never-read `~/.cline/rules/`.
+- **Smarter skill pointers**: Cursor/Cline/Augment skip the catalogue pointer when real skills are already discoverable at `.claude/skills/`, emitting it only as the editor-only fallback.
+- **Registry sync**: Windsurf → Devin Desktop, Roo Code archived, Antigravity `.agents/` plural default, Gemini CLI free/paid sunset (2026-06-18), corrected docs URLs across the board.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -106,12 +106,12 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | Windsurf | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.windsurf/rules/*.md` | ✅ | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | ✅ | global |
 | GitHub Copilot | `.github/copilot-instructions.md` | — | project |
-| Cline | `~/.cline/rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | — | global + project |
+| Cline | `~/Documents/Cline/Rules/*.md` + `~/.cline/skills/*` + `.clinerules/*.md` | — | global + project |
 | Roo Code | `~/.roo/rules/*.md` + `.roomodes` + `.roo/rules/*.md` | — | global rules + project |
 | Aider | `~/.aider.conf.yml` + `.aider.conf.yml` + `CONVENTIONS.md` | — | global + project |
 | Augment | `~/.augment/rules/*.md` + `.augment/rules/ai-toolkit-*.md` | ✅ | global + project |
-| Google Antigravity | `.agent/rules/*.md` + `.agent/workflows/*.md` | — | project |
-| Codex CLI | `AGENTS.md` + `.agents/rules/*.md` + `.agents/skills/*` + `.codex/hooks.json` | ✅ | project + global plugin |
+| Google Antigravity | `.agents/rules/*.md` + `.agents/workflows/*.md` | — | project |
+| Codex CLI | `AGENTS.md` (coding rules inlined) + `.agents/skills/*` + `.codex/hooks.json` | ✅ | project + global plugin |
 | opencode | `AGENTS.md` + `.opencode/{agents,commands,plugins}/*` + `opencode.json` | ✅ | project + global (`~/.config/opencode/`) |
 
 > Claude Code is always installed (primary platform). Other editors on demand with `--editors`. Every platform receives the agent/skill catalog, guidelines, and registered custom rules as text. The **Hooks** column marks platforms that also get lifecycle hook enforcement — the machine-enforced constitution (guard-destructive, quality gates, search-first discipline). Platforms marked — receive those rules as guidance only, without blocking hooks.

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

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.5.1",
+  "version": "4.6.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-05-30T19:51:17Z",
+  "last_run": "2026-06-05T09:16:41Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "46ef1d20d537234f",
+      "docs_hash": "544c8cce7baacb2e",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -65,7 +65,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "b2ee6850b58cee40",
+      "docs_hash": "f84eb6cd31b39797",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -120,10 +120,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.158 (Claude Code)"
+      "version": "2.1.165 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "9ec25e5132332d2f",
+      "docs_hash": "d94f88d02b733ee6",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -164,37 +164,51 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "f7a6a5144e0f61a2",
+      "docs_hash": "b86ae1b6bda0e071",
       "headings": [
-        "About",
-        "Contributing",
-        "Contributors",
-        "Docs",
-        "Folders and files",
-        "Footer",
-        "Footer navigation",
-        "Forks",
-        "History",
-        "Installing and running Codex CLI",
-        "Languages",
-        "Latest commit",
-        "License",
-        "Navigation Menu",
-        "Packages 0",
-        "Provide feedback",
+        "API",
+        "API Reference",
+        "Administration",
+        "Advertiser API",
+        "Agents SDK",
+        "Automation",
+        "Build",
+        "Categories",
+        "Codex",
+        "Codex for Open Source",
+        "Community",
+        "Configuration",
+        "Contribute",
+        "Conversion apps",
+        "Core Concepts",
+        "Core concepts",
+        "Deploy",
+        "Docs agent",
+        "Evaluation",
+        "Events",
+        "Explore use cases",
+        "File Upload",
+        "Get started",
+        "Getting Started",
+        "Going live",
+        "Guides",
+        "Learn",
+        "Legacy APIs",
+        "Measurement",
+        "Plan",
+        "Programs",
         "Quickstart",
-        "Releases 804",
-        "Repository files navigation",
+        "Realtime and audio",
+        "Recent",
+        "Releases",
         "Resources",
-        "Saved searches",
-        "Search code, repositories, users, issues, pull requests...",
-        "Security policy",
-        "Stars",
-        "Uh oh!",
-        "Use saved searches to filter your results more quickly",
-        "Using Codex with your ChatGPT plan",
-        "Watchers",
-        "openai/codex"
+        "Run and scale",
+        "Search the Codex docs",
+        "Specialized models",
+        "Suggested",
+        "Tools",
+        "Topics",
+        "Using Codex"
       ],
       "markers": {
         ".agents/skills": false,
@@ -213,14 +227,14 @@
         "hook handler: agent": false,
         "hook handler: command": false,
         "hook handler: prompt": false,
-        "hooks": false,
+        "hooks": true,
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.134.0"
+      "version": "codex-cli 0.136.0"
     },
     "cursor": {
-      "docs_hash": "6aa8a8d7cc046f13",
+      "docs_hash": "aee861b1ed20480d",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -236,7 +250,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "5569709cc2e463a8",
+      "docs_hash": "0bbd00c009a9357b",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -265,7 +279,6 @@
         "SKILL.md": false,
         "SessionEnd": false,
         "SessionStart": false,
-        "Stop": true,
         "activate_skill": false,
         "custom commands": false,
         "gemini-extension.json": false,
@@ -275,16 +288,17 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "56ac2d5768f930b5",
+      "docs_hash": "2314ef6e31c223a1",
       "headings": [
         "About Copilot auto model selection",
+        "About Copilot automations",
         "About Copilot integrations",
+        "About agent apps",
         "About agent management",
         "About agent skills",
         "About billing for GitHub Copilot in organizations and enterprises",
+        "About cloud and local sandboxes for GitHub Copilot",
         "About custom agents",
-        "About customizing GitHub Copilot responses",
-        "About enterprise accounts for Copilot Business",
         "Articles",
         "Did you find what you needed?",
         "GitHub Copilot",
@@ -307,7 +321,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "f933b31ac7414c29",
+      "docs_hash": "5ea5426c4445e746",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -323,7 +337,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "fe7f7590e4553574",
+      "docs_hash": "0e54c8a8f59b6474",
       "headings": [
         "Add features",
         "Ask questions",
@@ -383,45 +397,44 @@
       }
     },
     "windsurf": {
-      "docs_hash": "a30041baf564742f",
+      "docs_hash": "3405457d501ab760",
       "headings": [
-        "Accounts",
         "Advanced",
         "Agent Command Center",
         "App Deploys",
-        "Cascade",
         "Context Awareness",
+        "Devin Desktop",
+        "Devin Local",
         "Documentation Index",
-        "Editor",
         "MCP",
         "Memories",
         "On this page",
         "Recommended Plugins",
-        "Security",
+        "Releases",
         "Terminal",
-        "Troubleshooting",
         "Usage",
-        "Welcome to Windsurf",
+        "Welcome to Devin Desktop",
+        "Windsurf Plugins",
         "Workflows",
         "\u200b1. Select setup flow",
         "\u200b2. Choose editor theme",
         "\u200b3. Sign up / Log in",
         "\u200b4. Let\u2019s Surf!",
         "\u200bCustom App Icons (beta)",
+        "\u200bDevin Desktop Next",
         "\u200bForgot to Import VS Code Configurations?",
         "\u200bIncompatible Extensions",
         "\u200bOnboarding",
         "\u200bSet Up",
         "\u200bThings to Try",
-        "\u200bUninstall Windsurf",
-        "\u200bUpdate Windsurf",
-        "\u200bWindsurf Next"
+        "\u200bUninstall Devin Desktop",
+        "\u200bUpdate Devin Desktop"
       ],
       "markers": {
         "AGENTS.md": true,
         "Cascade": true,
         "MCP": true,
-        "SKILL.md": false,
+        "SKILL.md": true,
         "always_on": false,
         "glob": true,
         "hooks": true,

package/bin/ai-toolkit.js

@@ -98,9 +98,8 @@ const COMMANDS = {
   'conventions-md': 'Generate CONVENTIONS.md for Aider (auto-loaded)',
   'augment-rules': 'Generate .augment/rules/ai-toolkit.md for Augment (legacy)',
   'augment-dir-rules': 'Generate .augment/rules/ai-toolkit-*.md for Augment (recommended)',
-  'antigravity-rules': 'Generate .agent/rules/ and .agent/workflows/ for Google Antigravity',
-  'codex-md': 'Generate AGENTS.md for OpenAI Codex CLI',
-  'codex-rules': 'Generate .agents/rules/ for OpenAI Codex CLI',
+  'antigravity-rules': 'Generate .agents/rules/ and .agents/workflows/ for Google Antigravity',
+  'codex-md': 'Generate AGENTS.md (coding rules inlined) for OpenAI Codex CLI',
   'codex-hooks': 'Generate .codex/hooks.json for OpenAI Codex CLI',
   'opencode-md': 'Generate AGENTS.md for opencode',
   'opencode-agents': 'Generate .opencode/agents/ for opencode (subagents)',
@@ -504,7 +503,6 @@ function handleGenerateAll(_args) {
   run(scriptPath('generate_cline_rules.py'), [CWD]);
   run(scriptPath('generate_roo_rules.py'), [CWD]);
   run(scriptPath('generate_augment_rules.py'), [CWD]);
-  run(scriptPath('generate_codex_rules.py'), [CWD]);
   run(scriptPath('generate_codex_hooks.py'), [CWD]);
   run(scriptPath('generate_opencode_agents.py'), [CWD]);
   run(scriptPath('generate_opencode_commands.py'), [CWD]);
@@ -617,7 +615,6 @@ const SPECIAL_HANDLERS = {
   'roo-dir-rules': (_args) => run(scriptPath('generate_roo_rules.py'), [CWD]),
   'conventions-md': (_args) => { const out = runGenerator('generate_conventions.py'); fs.writeFileSync(path.join(CWD, 'CONVENTIONS.md'), out); console.log('Generated: CONVENTIONS.md'); },
   'augment-dir-rules': (_args) => run(scriptPath('generate_augment_rules.py'), [CWD]),
-  'codex-rules': (_args) => run(scriptPath('generate_codex_rules.py'), [CWD]),
   'codex-hooks': (_args) => run(scriptPath('generate_codex_hooks.py'), [CWD]),
   'opencode-agents': (_args) => run(scriptPath('generate_opencode_agents.py'), [CWD]),
   'opencode-commands': (_args) => run(scriptPath('generate_opencode_commands.py'), [CWD]),

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, ecosystem]
-version: "1.10.1"
+tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem, shellcheck]
+version: "1.11.0"
 created: "2026-04-10"
-last_updated: "2026-04-28"
-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."
+last_updated: "2026-06-02"
+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, the registry-vs-generators drift gate added in v1.10.0, and the mandatory pre-tag ShellCheck gate added in v1.11.0 (publish.yml does not run ShellCheck, so a hook lint failure can publish while reddening main CI — see the v4.5.1 postmortem in Phase 5)."
 ---
 
 # SOP: Release Preparation
@@ -51,12 +51,11 @@ python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
 # 3. Write CHANGELOG.md entry
 # 4. Regenerate artifacts
 python3 scripts/generate_agents_md.py > AGENTS.md
-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 + ecosystem check
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && npm test
+# 5. Validate + audit + SARIF + shellcheck + test + ecosystem check
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && shellcheck --severity=warning app/hooks/*.sh && npm test
 
 # 5a. Supply-chain standard (v2.8.0+) — non-negotiable
 grep -q -- '--provenance' .github/workflows/publish.yml || { echo "MISSING --provenance"; exit 1; }
@@ -253,7 +252,6 @@ Add entry at the top of `CHANGELOG.md` (after the header, before previous releas
 
 ```bash
 python3 scripts/generate_agents_md.py > AGENTS.md
-python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 ```
@@ -278,6 +276,12 @@ 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
 
+# ShellCheck on hooks (added in 1.11.0). Mirrors the ci.yml "ShellCheck hooks"
+# job. NOT run by validate.py, npm test, OR publish.yml — so a hook with a
+# ShellCheck warning passes every other gate AND still publishes on tag while
+# turning main CI red. Run it here, before tagging.
+shellcheck --severity=warning app/hooks/*.sh && echo "OK: shellcheck clean"
+
 # Registry / generator drift (added in 1.10.0). Meta-generators excluded.
 META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
 diff \
@@ -299,12 +303,15 @@ 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
+- `shellcheck --severity=warning app/hooks/*.sh`: no output, exit 0. A common false positive is `SC2034` on `INPUT` or env vars (e.g. `AI_TOOLKIT_HOOK_FORMAT`) that a *sourced* helper (`_hook-io.sh`) consumes — ShellCheck cannot see cross-file use. Fix with a `# shellcheck disable=SC2034` directive or `export`, matching `guard-destructive.sh`. Never tag with a red ShellCheck.
 - 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)
 
+> **Why this matters (v4.5.1 postmortem):** `publish.yml` runs only `validate.py` + `npm test`, so it published v4.5.0 even though the `main` CI `ShellCheck hooks` job was red on two `SC2034` warnings in a new hook. The publish workflow does **not** depend on the CI workflow. Until that is fixed, ShellCheck is a manual pre-tag gate — run it here every time.
+
 **One-liner:**
 ```bash
-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|generate_language_rules_skills\.py' | sort -u) && npm test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && shellcheck --severity=warning app/hooks/*.sh && 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|generate_language_rules_skills\.py' | sort -u) && npm test
 ```
 
 **If tests fail:** Fix the issue, do NOT skip. Common failures:
@@ -427,14 +434,15 @@ git push origin --delete vX.Y.Z
 | 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 (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 |
+| 8 | Regenerate artifacts | `generate_agents_md.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 |
 | 11 | Security audit (SARIF) | `audit_skills.py --sarif` | Valid SARIF 2.1.0 JSON |
 | 12 | Per-skill permissions | `audit_skills.py --permissions` | New broad-access skills justified in CHANGELOG |
-| 13 | Provenance flag check | `grep -- '--provenance' .github/workflows/publish.yml` | Present |
-| 14 | Checksum-pin backfill | `sources.json` entries all have `sha256` | No unpinned URL sources |
-| 15 | Tests | `npm test` | All pass |
-| 16 | Commit | `git commit` | Clean working tree |
-| 17 | Tag | `git tag vX.Y.Z` | Tag exists |
-| 18 | Push | `git push origin main --tags` | CI triggered with `id-token: write` |
+| 13 | ShellCheck hooks | `shellcheck --severity=warning app/hooks/*.sh` | Exit 0, no output (mirrors ci.yml; publish.yml does NOT run it) |
+| 14 | Provenance flag check | `grep -- '--provenance' .github/workflows/publish.yml` | Present |
+| 15 | Checksum-pin backfill | `sources.json` entries all have `sha256` | No unpinned URL sources |
+| 16 | Tests | `npm test` | All pass |
+| 17 | Commit | `git commit` | Clean working tree |
+| 18 | Tag | `git tag vX.Y.Z` | Tag exists |
+| 19 | Push | `git push origin main --tags` | CI triggered with `id-token: write` |

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

@@ -36,9 +36,8 @@ Verifies all critical paths from the user's perspective.
 ```bash
 # Pre-commit (Phase 0)
 python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGENTS.md
-python3 scripts/generate_codex_rules.py .                   # 2. Refresh standard Codex rules
-python3 scripts/generate_llms_txt.py > llms.txt             # 3. Regenerate llms.txt
-python3 scripts/validate.py --strict                        # 4. Validation passed?
+python3 scripts/generate_llms_txt.py > llms.txt             # 2. Regenerate llms.txt
+python3 scripts/validate.py --strict                        # 3. Validation passed?
 npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 5. All tests passed? (single run, cached)
 
 # Post-install verification (Phases 1-7)
@@ -68,7 +67,6 @@ counts but does NOT auto-regenerate — you must do it locally.
 ```bash
 # 1. Regenerate generated artifacts
 python3 scripts/generate_agents_md.py > AGENTS.md
-python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
@@ -93,7 +91,7 @@ by the developer as part of their PR.
 
 **One-liner (copy-paste):**
 ```bash
-python3 scripts/generate_agents_md.py > AGENTS.md && python3 scripts/generate_codex_rules.py . && python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
+python3 scripts/generate_agents_md.py > AGENTS.md && python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt && python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && npm test
 ```
 
 ---

package/kb/reference/architecture-overview.md

@@ -109,7 +109,7 @@ Machine (global)                              Project (local)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agent/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agents/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md` (universal coding rules inlined — Codex reads only AGENTS.md, not `.agents/rules/`), `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
 
 If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
 
@@ -143,9 +143,8 @@ If a project already has `.mcp.json`, local install mirrors its `mcpServers` ent
 | `aider-conf` | `./` | Generates `.aider.conf.yml` |
 | `conventions-md` | `./` | Generates `CONVENTIONS.md` (Aider auto-loaded) |
 | `augment-dir-rules` | `./` | Generates `.augment/rules/ai-toolkit-*.md` |
-| `antigravity-rules` | `./` | Generates `.agent/rules/` + `.agent/workflows/` |
+| `antigravity-rules` | `./` | Generates `.agents/rules/` + `.agents/workflows/` |
 | `codex-md` | `./` | Generates Codex-facing `AGENTS.md` |
-| `codex-rules` | `./` | Generates `.agents/rules/*.md` |
 | `codex-hooks` | `./` | Generates `.codex/hooks.json` |
 | `agents-md` | toolkit | Regenerates `AGENTS.md` |
 | `llms-txt` | `./` | Generates `llms.txt` |

package/kb/reference/cli-reference.md

@@ -87,8 +87,7 @@ Usage: ai-toolkit <command> [options]
 |---------|-------------|
 | `generate-all` | Generate all platform configs at once |
 | `agents-md` | Regenerate `AGENTS.md` from agent definitions |
-| `codex-md` | Generate `AGENTS.md` with marker injection for Codex CLI |
-| `codex-rules` | Generate `.agents/rules/*.md` for Codex CLI |
+| `codex-md` | Generate `AGENTS.md` (coding rules inlined) with marker injection for Codex CLI |
 | `codex-hooks` | Generate `.codex/hooks.json` for Codex CLI |
 | `cursor-rules` | Generate `.cursorrules` (legacy single file) |
 | `cursor-mdc` | Generate `.cursor/rules/*.mdc` (recommended) |
@@ -104,7 +103,7 @@ Usage: ai-toolkit <command> [options]
 | `conventions-md` | Generate `CONVENTIONS.md` for Aider |
 | `augment-rules` | Generate `.augment/rules/ai-toolkit.md` (legacy) |
 | `augment-dir-rules` | Generate `.augment/rules/ai-toolkit-*.md` (recommended) |
-| `antigravity-rules` | Generate `.agent/rules/` and `.agent/workflows/` |
+| `antigravity-rules` | Generate `.agents/rules/` and `.agents/workflows/` |
 | `llms-txt` | Generate `llms.txt` and `llms-full.txt` |
 
 ## Other Commands

package/kb/reference/global-install-model.md

@@ -63,10 +63,10 @@ with documented, file-based config surfaces:
 - `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `gemini`: `~/.gemini/GEMINI.md`
 - `augment`: `~/.augment/rules/ai-toolkit.md`
-- `cline`: `~/.cline/rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
+- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
 - `roo`: `~/.roo/rules/ai-toolkit-*.md`
 - `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
-- `codex`: `~/AGENTS.md`, `~/.agents/rules/*`, `~/.agents/skills/*`, `~/.codex/hooks.json`
+- `codex`: `~/AGENTS.md` (coding rules inlined), `~/.agents/skills/*`, `~/.codex/hooks.json`
 - `opencode`: `~/.config/opencode/*`
 
 Cursor, GitHub Copilot, and Google Antigravity rule installs stay project-local.
@@ -99,7 +99,7 @@ These files still stay local to a repository as part of the core install model:
 - `.roomodes`
 - `.aider.conf.yml`
 - `.augment/rules/ai-toolkit-*.md`
-- `.agent/rules/*.md` and `.agent/workflows/*.md` (Google Antigravity)
+- `.agents/rules/*.md` and `.agents/workflows/*.md` (Google Antigravity; singular `.agent/` still read as fallback)
 - `.git/hooks/pre-commit` (fallback)
 - project-specific documentation or safety overlays
 

package/kb/reference/opencode-compatibility.md

@@ -23,7 +23,7 @@ opencode also reads `CLAUDE.md` as a fallback, so a user without the native inte
 
 - `AGENTS.md` (shared with Codex CLI via distinct marker sections)
 - `.opencode/agents/ai-toolkit-*.md` (one per ai-toolkit agent, `mode: subagent`)
-- `.opencode/commands/ai-toolkit-*.md` (one per user-invocable skill, required `template: |` frontmatter field)
+- `.opencode/commands/ai-toolkit-*.md` (one per user-invocable skill; the prompt lives in the markdown body)
 - `.opencode/plugins/ai-toolkit-hooks.js` (JS plugin bridging Bash hooks)
 - `opencode.json` (MCP key merged from `.mcp.json`, user keys preserved)
 
@@ -71,7 +71,7 @@ Opencode treats these files as auto-completable with `@` and can delegate to the
 
 Only user-invocable skills (`user-invocable: true` or no `disable-model-invocation`) emit to `.opencode/commands/`. Knowledge skills (`user-invocable: false`) are intentionally skipped — they are not intended as commands.
 
-Each command file carries opencode's required `template: |` frontmatter field, built from the SKILL.md body.
+Each command file carries the prompt in its markdown body (built from the SKILL.md body). opencode reads the body as the prompt; the `template` field is JSON-config-only and is ignored in `.md` command files.
 
 ## Hook Bridge (JS Plugin)