@softspark/ai-toolkit 4.24.0 → 4.25.0

package/kb/reference/architecture-overview.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.7.0"
+version: "1.8.0"
 created: "2026-03-23"
-last_updated: "2026-08-06"
+last_updated: "2026-08-19"
 description: "Architecture of ai-toolkit: directory layout, Claude app export, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -61,7 +61,10 @@ ai-toolkit/
     generate_copilot.py      # Generates Copilot instructions, agents, and portable skills
     generate_copilot_hooks.py # Generates native Copilot hooks + self-contained runtime
     generate_gemini.py       # Generates GEMINI.md (sources _common.py)
-    generate_cline.py        # Generates .clinerules (sources _common.py)
+    generate_gemini_agents.py # Generates native .gemini/agents/*.md definitions
+    generate_cline.py        # Generates legacy .clinerules (sources _common.py)
+    generate_cline_rules.py  # Dual-emits .cline/rules + .clinerules compatibility
+    generate_cline_hooks.py  # Dual-emits .cline/hooks + .clinerules/hooks
     generate_roo_modes.py    # Generates .roomodes
     generate_aider_conf.py   # Generates .aider.conf.yml
     generate_llms_txt.py     # Generates llms.txt
@@ -123,7 +126,11 @@ also emits `.github/instructions`, `.github/prompts`, and native
 `.github/hooks`. The user target writes the supported personal surfaces below
 `$COPILOT_HOME` (default `~/.copilot`) and does not generate prompt files there.
 Full-profile installs also emit native skill pointer catalogues for Cursor,
-Windsurf, and Cline. Codex local install generates `AGENTS.md`,
+Windsurf, and Cline. Cline rules dual-emit to `.cline/rules/` and `.clinerules/`;
+profiles `standard`, `strict`, and `full` add executable hooks under both
+`.cline/hooks/<Event>` and `.clinerules/hooks/<Event>`. Gemini receives
+commands, a skill pointer, and native
+`.gemini/agents/*.md` definitions. Codex local install generates `AGENTS.md`,
 `.agents/skills/*`, `.codex/agents/*.toml`, `.codex/hooks.json`, and
 self-contained `.codex/hooks/*`. Global Codex install writes its user-owned
 surfaces below `$CODEX_HOME` (default `~/.codex`) while user skills remain in
@@ -162,7 +169,8 @@ project-scoped native MCP files: `.cursor/mcp.json`, `.github/mcp.json`,
 | `copilot-instructions` | `./` | Generates `.github/copilot-instructions.md` |
 | `gemini-md` | `./` | Generates `GEMINI.md` |
 | `cline-rules` | `./` | Generates `.clinerules` (legacy) |
-| `cline-dir-rules` | `./` | Generates `.clinerules/*.md` |
+| `cline-dir-rules` | `./` | Generates `.cline/rules/*.md` plus `.clinerules/*.md` compatibility |
+| `cline-hooks` | `./` | Generates eight executable files under `.cline/hooks/` and `.clinerules/hooks/` |
 | `roo-modes` | `./` | Generates `.roomodes` |
 | `roo-dir-rules` | `./` | Generates `.roo/rules/*.md` |
 | `aider-conf` | `./` | Generates `.aider.conf.yml` |

package/kb/reference/claude-ecosystem-expansion-foundations.md

@@ -3,9 +3,9 @@ title: "Claude Ecosystem Expansion Foundations"
 category: reference
 service: ai-toolkit
 tags: [benchmark, claude-code, ecosystem, hooks, plugins, architecture]
-version: "1.1.0"
+version: "1.2.0"
 created: "2026-03-27"
-last_updated: "2026-07-10"
+last_updated: "2026-08-19"
 description: "Reference summary of the ecosystem signals and implementation foundations adopted in ai-toolkit, including runtime-aware plugin packaging."
 ---
 
@@ -43,9 +43,21 @@ hooks and sub-agents are Cowork-only.
 
 ### 2. Broader lifecycle coverage
 
-The toolkit now covers prompt, edit, subagent, compaction, and session-end phases.
-
-Implemented events:
+The validator tracks the complete current Claude Code hook schema. Tracking an
+event means plugin manifests and hand-authored hook configuration can use it; it
+does not mean the default toolkit bundle registers a handler for that event.
+
+Tracked schema events:
+- `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `MessageDisplay`
+- `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`
+- `Stop`, `StopFailure`, `UserPromptExpansion`
+- `SubagentStart`, `SubagentStop`, `PreCompact`, `PostCompact`
+- `PermissionRequest`, `PermissionDenied`, `Elicitation`, `ElicitationResult`
+- `TaskCreated`, `TaskCompleted`, `TeammateIdle`
+- `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `DirectoryAdded`, `FileChanged`, `ConfigChange`
+- `Setup`, `InstructionsLoaded`
+
+Toolkit-wired events in `app/hooks.json`:
 - `SessionStart`
 - `Notification`
 - `PreToolUse`
@@ -58,6 +70,19 @@ Implemented events:
 - `SubagentStop`
 - `PreCompact`
 - `SessionEnd`
+- `InstructionsLoaded`
+- `ConfigChange`
+
+`MessageDisplay` and `DirectoryAdded` are tracked but intentionally have no
+default toolkit handler. `DirectoryAdded` runs asynchronously after `/add-dir`
+or SDK `register_repo_root` and cannot block the add. `MessageDisplay` can
+replace rendered text through `displayContent` without changing the transcript.
+
+Claude Code also recognizes native plugin workflows, output styles, LSP
+servers, experimental themes and monitors, MCP-backed channels, and root plugin
+settings. Those are documented class C surfaces rather than generated toolkit
+output; root plugin settings currently support only `agent` and
+`subagentStatusLine`.
 
 ### 3. Creator workflows
 

package/kb/reference/cli-reference.md

@@ -4,7 +4,7 @@ category: reference
 service: ai-toolkit
 tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
 created: "2026-04-13"
-last_updated: "2026-07-26"
+last_updated: "2026-08-19"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -31,6 +31,8 @@ Usage: ai-toolkit <command> [options]
 | `eject [dir]` | Export standalone config (no symlinks, no toolkit dependency) |
 | `claude-app export [--output FILE] [--no-custom-rules] [--verify]` | Build an uploadable Claude Chat/Desktop/Cowork plugin ZIP and global-instructions file |
 | `claude-app verify` | Validate a clean staged plugin with structural checks and the official Claude plugin validator |
+| `codex-plugin export [--output FILE]` | Build a deterministic native Codex plugin ZIP with skills and self-contained hooks |
+| `codex-plugin verify` | Validate a clean native Codex plugin stage without installing it or changing user configuration |
 
 ## Rule & Hook Injection
 
@@ -54,6 +56,9 @@ Usage: ai-toolkit <command> [options]
 
 ## Plugin Management
 
+`plugin ...` manages ai-toolkit's experimental runtime packs. Native Codex
+plugin packaging uses the separate `codex-plugin ...` command above.
+
 | Command | Description |
 |---------|-------------|
 | `plugin list` | Show available plugin packs with install status |
@@ -65,6 +70,23 @@ Usage: ai-toolkit <command> [options]
 | `plugin remove <name> [--editor claude\|codex\|all]` | Remove a plugin pack |
 | `plugin status [--editor claude\|codex\|all]` | Show installed plugins with runtime-specific details |
 
+### Native Codex plugin package
+
+```bash
+ai-toolkit codex-plugin export --output ai-toolkit-codex-plugin.zip
+ai-toolkit codex-plugin verify
+```
+
+Extract the ZIP to `<marketplace-root>/plugins/ai-toolkit/`, add an entry with
+`source.path: ./plugins/ai-toolkit` in
+`<marketplace-root>/.agents/plugins/marketplace.json`, then run
+`codex plugin marketplace add <marketplace-root>` for that non-default local
+marketplace. Open `/plugins` in Codex CLI, install the plugin, review/trust the
+bundled hooks, and start a new session. The ZIP includes plugin-local skill
+runtime resources, including the skill-audit helper and its Python imports.
+Export refuses symlinked output files and ancestors instead of resolving them
+to another destination. Codex IDE does not support plugins.
+
 ## Config Inheritance
 
 | Command | Description |
@@ -105,7 +127,8 @@ Usage: ai-toolkit <command> [options]
 | `copilot-instructions` | Generate `.github/copilot-instructions.md` |
 | `gemini-md` | Generate `GEMINI.md` for Gemini CLI |
 | `cline-rules` | Generate `.clinerules` (legacy) |
-| `cline-dir-rules` | Generate `.clinerules/*.md` (recommended) |
+| `cline-dir-rules` | Generate `.cline/rules/*.md` plus `.clinerules/*.md` compatibility |
+| `cline-hooks` | Generate eight executable `.cline/hooks/<Event>` files plus `.clinerules/hooks/<Event>` extension compatibility |
 | `roo-modes` | Generate `.roomodes` |
 | `roo-dir-rules` | Generate `.roo/rules/*.md` |
 | `aider-conf` | Generate `.aider.conf.yml` |
@@ -113,6 +136,8 @@ Usage: ai-toolkit <command> [options]
 | `augment-rules` | Generate `.augment/rules/ai-toolkit.md` (legacy) |
 | `augment-dir-rules` | Generate `.augment/rules/ai-toolkit-*.md` (recommended) |
 | `antigravity-rules` | Generate `.agents/rules/` and `.agents/workflows/` |
+| `antigravity-plugin export [output]` | Export deterministic native Antigravity plugin ZIP for `.agents/plugins/<name>/`, `~/.gemini/antigravity-cli/plugins/<name>/` (CLI), or `~/.gemini/config/plugins/<name>/` (IDE/shared product) |
+| `antigravity-plugin verify <archive-or-dir>` | Verify Antigravity plugin schema, paths, hooks, modes, and self-containment offline |
 | `llms-txt` | Generate `llms.txt` and `llms-full.txt` |
 
 ## Other Commands

package/kb/reference/codex-cli-compatibility.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Codex CLI Compatibility"
 category: reference
 service: ai-toolkit
 tags: [codex, compatibility, install, skills, hooks]
-version: "1.0.4"
+version: "1.1.0"
 created: "2026-04-12"
-last_updated: "2026-07-14"
+last_updated: "2026-08-19"
 description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
 ---
 
@@ -74,6 +74,72 @@ Codex base. Codex hooks no longer depend on executable paths under
 `~/.softspark/ai-toolkit/`; project assets live beside `.codex/hooks.json`, and
 user assets live under `$CODEX_HOME/ai-toolkit-hooks/`.
 
+## Native Codex Plugin Export
+
+The separate native distribution command packages the toolkit for Codex's
+plugin marketplace flow without writing user configuration:
+
+```bash
+ai-toolkit codex-plugin export --output ai-toolkit-codex-plugin.zip
+ai-toolkit codex-plugin verify
+```
+
+The deterministic archive has this root layout:
+
+```text
+.codex-plugin/plugin.json
+skills/*/SKILL.md
+skills/persona/personas/*.md
+skills/briefing/scripts/session_token_stats.py
+scripts/audit_skills.py
+scripts/{_common,frontmatter,injection,emission,instruction_core}.py
+hooks/hooks.json
+hooks/*
+constitution.md
+LICENSE
+```
+
+The manifest name is `ai-toolkit`, its version comes from `package.json`, and
+`skills` points to `./skills/`. It intentionally omits a `hooks` field because
+Codex discovers the default `hooks/hooks.json` file. Every bundled hook command
+uses `${PLUGIN_ROOT}/hooks/...`; no command depends on a git root, `CODEX_HOME`,
+or the toolkit's global-install hook directory. Executable modes, archive order,
+and timestamps are fixed so identical sources produce identical ZIP bytes.
+Skill references are adapted to plugin-local paths. Validation covers every
+intentionally bundled cross-skill/runtime dependency, including persona
+definitions, the briefing helper, the documentation standards skill, and the
+constitution referenced by the security skill. Bare `scripts/...` references
+are classified as plugin runtime, target-workspace, skill-local, or
+source-toolkit references; unclassified paths fail validation. The skill-audit
+command uses the staged helper, whose local imports are bundled at plugin root.
+
+`verify` stages a clean plugin under a temporary directory and checks the
+manifest, component paths, skills, exact canonical command-only hooks,
+executable assets, `SessionEnd` timeout, and symlink safety. The check is
+self-contained: it does not execute mutable validators selected from `$HOME`
+or environment-provided paths, add a marketplace, install a plugin, or write
+under `~/.agents` or `~/.codex`.
+Archive output uses the shared pinned-directory transaction and rejects a
+symlink at the destination or in any requested ancestor, so a redirected path
+cannot write outside the lexical destination.
+
+To test the exported archive through a non-default local marketplace:
+
+1. Extract it to `<marketplace-root>/plugins/ai-toolkit/`.
+2. Add an `ai-toolkit` entry to
+   `<marketplace-root>/.agents/plugins/marketplace.json` with
+   `source.path: ./plugins/ai-toolkit`.
+3. Run `codex plugin marketplace add <marketplace-root>` once for that
+   non-default marketplace.
+4. Open `/plugins` in Codex CLI, install `ai-toolkit`, review/trust its hooks,
+   and start a new session.
+
+Codex IDE does not support plugins. Use Codex CLI or the ChatGPT desktop app for
+plugin browsing and installation.
+
+Sources: [Codex plugin packaging](https://developers.openai.com/plugins/build/plugins),
+[plugin availability](https://learn.chatgpt.com/docs/plugins).
+
 ## Skill Translation Model
 
 Two delivery modes are used for Codex:
@@ -123,9 +189,8 @@ even when its tool list is otherwise portable. Examples include:
 
 ## Hook Compatibility
 
-Codex does not expose the full Claude hook event surface. Codex's
-`HookEventName` enum defines 10 events; the Codex hook generator wires 9 of
-them:
+Codex does not expose the full Claude hook event surface. The current native
+contract defines 11 events; the Codex hook generator wires 10 of them:
 
 - `SessionStart`
 - `PreToolUse`
@@ -135,13 +200,34 @@ them:
 - `SubagentStart`
 - `SubagentStop`
 - `PreCompact`
+- `SessionEnd`
 - `Stop`
 
 `PostCompact` is the one enum event left unwired (its only hook was the removed
 environment-snapshot probe). Claude-only events such as `TaskCompleted`,
-`TeammateIdle`, `SessionEnd`, and `Notification` have no Codex equivalent and
-are not available in `.codex/hooks.json`. Handler types: only `command` runs;
-`prompt` and `agent` are parsed by Codex but not yet executed.
+`TeammateIdle`, and `Notification` have no Codex equivalent and are not
+available in `.codex/hooks.json`.
+
+The generated `SessionEnd` handler runs the self-contained `session-end.sh`
+asset with `timeout: 3`, Codex's documented maximum. It runs only for the main
+thread, always synchronously, and is advisory: its output cannot steer Codex or
+keep the thread open. The asset therefore stays silent, cleans the session's
+toolkit state when available, and writes the handoff snapshot outside the
+repository with Codex-native `AGENTS.md` restart guidance.
+
+Existing native hook documents may include an optional top-level string
+`description`; merges preserve it unchanged. Command handlers may include a
+non-negative integer `additionalContextLimit`, including zero, and valid user
+values are also preserved. Booleans, negative values, and non-integers are
+rejected before any file is changed. `SessionEnd` timeouts above three seconds
+are rejected.
+
+Only executable `type: "command"` handlers are accepted. The current official
+hooks page says `prompt` and `agent` handlers are parsed but skipped, and does
+not establish an executable `mcp_tool` handler schema. Codex CLI 0.148.0 release
+notes mention MCP hooks, which conflicts with that page. Toolkit support stays
+command-only until OpenAI confirms the native config schema and execution
+semantics in the canonical hooks documentation.
 
 The generator merges these Codex-compatible events into project or user
 `hooks.json`, preserving unrelated user handlers and replacing only commands
@@ -159,10 +245,12 @@ After installation or any hook change, open `/hooks` in Codex and review/trust
 the exact definitions. Project hooks additionally require a trusted `.codex`
 project layer. The installer never bypasses hook trust.
 
+Source: [Codex hooks](https://learn.chatgpt.com/docs/hooks).
+
 Generated Codex hook commands include `AI_TOOLKIT_HOOK_QUIET=1`. Native
-`SessionStart`, `PreCompact`, and MCP-health adapters use Codex instruction and
-config terminology (`AGENTS.md`, `.codex/config.toml`) instead of Claude-only
-paths. The generated
+`SessionStart`, `SessionEnd`, `PreCompact`, and MCP-health adapters use Codex
+instruction and config terminology (`AGENTS.md`, `.codex/config.toml`) instead
+of Claude-only paths. The generated
 `UserPromptSubmit` governance hook does not set `AI_TOOLKIT_HOOK_FORMAT=json`
 by default because Codex currently renders `additionalContext` as visible hook
 context in the TUI. This keeps prompt-submit output quiet while preserving hook
@@ -234,6 +322,8 @@ The Codex compatibility path is verified by:
 2. Local install tests for `.agents/skills/` and `.codex/hooks.json`
 3. Plugin install tests for global Codex rules, hooks, and cleanup paths
 4. CLI tests for `codex-md` and `codex-hooks`
+5. Native plugin export tests for layout, hooks, determinism, validation, CLI
+   dispatch, and no-home-mutation behavior
 
 ## Related
 

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: "3.3.1"
+version: "3.4.0"
 created: "2026-03-26"
-last_updated: "2026-07-15"
+last_updated: "2026-08-19"
 description: "Reference description of Claude Code global install, Claude app plugin export, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -55,7 +55,7 @@ The `--profile` flag controls how much of each editor's native surface is activa
 | Profile | What runs | Use when |
 |---------|-----------|----------|
 | `minimal` | Smallest editor surface. Copilot still receives its root instructions, native agents, and self-contained skills; Codex still receives instructions, agents, skills, and native safety hooks. | You want the smallest supported footprint. |
-| `standard` (default) | Claude Code + editor rule files. Includes Gemini hooks and native Copilot instructions, agents, portable skills, and hooks. | Day-to-day installs. Most users. |
+| `standard` (default) | Claude Code + editor rule files. Includes Gemini and Antigravity hooks plus native Copilot instructions, agents, portable skills, and hooks. | 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. |
 
@@ -98,20 +98,20 @@ store, so toolkit updates require re-export and re-upload.
 with documented, file-based config surfaces:
 
 - `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md` plus `~/.config/devin/AGENTS.md` (Devin CLI global rules — the Desktop `global_rules.md` path is not imported by `read_config_from.windsurf`)
-- `gemini`: `~/.gemini/GEMINI.md`; hooks at `~/.gemini/settings.json` (profile ≥ standard); `~/.gemini/commands/` and `~/.gemini/skills/` pointer (profile full)
+- `gemini`: `~/.gemini/GEMINI.md`; hooks at `~/.gemini/settings.json` (profile ≥ standard); `~/.gemini/commands/`, `~/.gemini/skills/` pointer, and native `~/.gemini/agents/*.md` (profile full)
 - `augment`: `~/.augment/rules/ai-toolkit.md`; `~/.augment/agents/`, `~/.augment/commands/`, and hooks in `~/.augment/settings.json` (profile full)
-- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
+- `cline`: `~/.cline/rules/ai-toolkit-*.md` plus `~/Documents/Cline/Rules/ai-toolkit-*.md` compatibility; profiles `standard`, `strict`, and `full` add the exact eight executable hooks under both `~/.cline/hooks/` and `~/Documents/Cline/Hooks/`; a `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md` pointer is used only when Cline cannot discover real Claude skills
 - `roo`: `~/.roo/rules/ai-toolkit-*.md` plus `~/.agents/skills/*` (Roo/Zoo native skill discovery; skipped when `codex` is also selected, which fills the same dir)
 - `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
 - `codex`: `$CODEX_HOME/AGENTS.md`, `$CODEX_HOME/agents/*.toml`, `$CODEX_HOME/hooks.json`, `$CODEX_HOME/ai-toolkit-hooks/*`, plus `$HOME/.agents/skills/*`; `CODEX_HOME` defaults to `~/.codex`, and `~/AGENTS.md` is not Codex's user-instruction file
-- `opencode`: `~/.config/opencode/*`
+- `opencode`: `~/.config/opencode/{AGENTS.md,agents/,commands/,plugins/,opencode.json}`; `profile=full` also copies complete native skills to `~/.config/opencode/skills/<name>/`
 
 Cursor, GitHub Copilot, and Google Antigravity now have partial global support,
 scoped to whatever documented HOME file surface each exposes:
 
 - `cursor`: `~/.cursor/hooks.json` (safety/quality hooks; profile ≥ standard). Cursor RULES stay project-local — their only global surface is the Settings UI.
 - `copilot`: instructions, native agents, portable skills, and native hooks under `$COPILOT_HOME` when set or `~/.copilot` otherwise. The hook config is `hooks/ai-toolkit.json`; its self-contained runtime is `hooks/ai-toolkit/copilot_hook.py`. VS Code and GitHub.com still use repo `.github/` files, which local install emits.
-- `antigravity`: skill pointer at `~/.gemini/config/skills/` and `~/.gemini/antigravity-cli/skills/`. Antigravity RULES stay project-local.
+- `antigravity`: current canonical skill pointers at `~/.gemini/antigravity-cli/skills/` for CLI and `~/.gemini/config/skills/` for the IDE/shared product; native hooks at `~/.gemini/config/hooks.json` for standard/strict/full; native agents at `~/.gemini/config/agents/` for full. Only workspace `.agent/skills/` is legacy. Antigravity rules stay project-local. Native plugins are opt-in exports installed manually under `~/.gemini/antigravity-cli/plugins/<name>/` for CLI or `~/.gemini/config/plugins/<name>/` for the IDE/shared product.
 
 Their global MCP support, where available, is handled by `ai-toolkit mcp
 install`, not by the rule installer.
@@ -146,7 +146,9 @@ These files still stay local to a repository as part of the core install model:
 - `.github/agents/ai-toolkit-*.agent.md`
 - `.github/skills/ai-toolkit-*/SKILL.md` plus required assets and helper scripts
 - `.github/hooks/ai-toolkit.json` plus `.github/hooks/ai-toolkit/copilot_hook.py` (profile ≥ `standard`)
-- `.clinerules`
+- `.cline/rules/ai-toolkit-*.md` plus `.clinerules/ai-toolkit-*.md` compatibility
+- `.cline/hooks/<Event>` plus `.clinerules/hooks/<Event>` compatibility for Cline profiles `standard`, `strict`, and `full`
+- `.clinerules/workflows/ai-toolkit-*.md`
 - `.roomodes`
 - `.aider.conf.yml`
 - `.augment/rules/ai-toolkit-*.md`

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.9.0"
+version: "1.11.0"
 created: "2026-03-27"
-last_updated: "2026-07-26"
+last_updated: "2026-08-19"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -607,12 +607,47 @@ Beyond the global Claude Code hooks above, editor profiles emit native hook file
 |--------|------|-----------|--------|
 | Cursor | `.cursor/hooks.json` | `generate_cursor_hooks.py` | Cursor hooks schema |
 | Devin CLI | `.devin/hooks.v1.json` | `generate_devin_hooks.py` | Claude-compatible (the replacement for Cascade) |
-| Gemini CLI | `.gemini/settings.json` (hooks block) | `generate_gemini_hooks.py` | Gemini `BeforeTool`/`AfterTool` events |
+| Gemini CLI | `.gemini/settings.json` (hooks block) | `generate_gemini_hooks.py` | Native 11-event contract: `BeforeTool`, `AfterTool`, `BeforeToolSelection`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `Notification`, `PreCompress`, `SessionStart`, `SessionEnd`; toolkit handlers use the applicable subset and never emit `Stop` |
 | Augment | `.augment/settings.json` (hooks block) | `generate_augment_hooks.py` | Claude-style events |
+| Cline | `.cline/hooks/<Event>` plus `.clinerules/hooks/<Event>`; user `~/.cline/hooks/<Event>`; extension compatibility `~/Documents/Cline/Hooks/<Event>` | `generate_cline_hooks.py` | Eight extensionless executable files using Cline's native stdin/stdout contract (profile ≥ `standard`) |
 | GitHub Copilot | `.github/hooks/ai-toolkit.json`; user `$COPILOT_HOME/hooks/ai-toolkit.json` | `generate_copilot_hooks.py` | GitHub version 1, camelCase events (profile ≥ `standard`) |
 | Codex CLI | `.codex/hooks.json`; user `$CODEX_HOME/hooks.json` | `generate_codex_hooks.py` | Native Codex schema, PascalCase events, command ownership markers |
+| Google Antigravity | `.agents/hooks.json`; user `~/.gemini/config/hooks.json` | `generate_antigravity_hooks.py` | Native five-event schema plus adjacent Python adapter |
 | OpenCode | `.opencode/plugins/ai-toolkit-hooks.js`; user `~/.config/opencode/plugins/ai-toolkit-hooks.js` | `generate_opencode_plugin.py` | Native JavaScript plugin hooks |
 
+### Cline hooks (`.cline/hooks/<Event>` and `.clinerules/hooks/<Event>`)
+
+Cline CLI/SDK loads `.cline/hooks`, while the VS Code and JetBrains extension
+loads project hooks from `.clinerules/hooks`; project generation emits both.
+Cline loads extensionless executable files named `TaskStart`, `TaskResume`,
+`TaskCancel`, `TaskComplete`, `PreToolUse`, `PostToolUse`, `UserPromptSubmit`,
+and `PreCompact`. The toolkit adapter is self-contained, reads bounded JSON
+from stdin, and emits only Cline's documented `cancel`, `contextModification`,
+and `errorMessage` keys. `PreToolUse` validates the documented
+`preToolUse.toolName` plus `parameters` shape and cancels recognized destructive
+shell operations, including `run_commands` arrays; start, resume, prompt, and compaction events may inject safe
+context. Input size and runtime are bounded, and regeneration replaces only
+marked toolkit files while preserving user-owned hooks.
+
+### Google Antigravity hooks (`.agents/hooks.json`)
+
+The toolkit owns only the top-level `ai-toolkit` namespace and preserves
+unrelated namespaces. The exact event set is `PreToolUse`, `PostToolUse`,
+`PreInvocation`, `PostInvocation`, and `Stop`. Tool events use matcher groups;
+the other events use direct command-handler lists. Every handler has a bounded
+timeout.
+
+The adjacent Python runtime maps `.toolCall.name` and
+`.toolCall.args.CommandLine` to native camelCase responses. `PreToolUse`
+returns `allow`, `deny`, or `ask`; `PostToolUse` returns `{}`; invocation events
+use object-shaped `injectSteps` and a native `terminationBehavior`; `Stop`
+reads the official `executionNum`, `terminationReason`, optional `error`, and
+`fullyIdle` inputs. It returns `decision: continue` only when the invocation is
+not fully idle and has not passed its first execution; later executions and
+fully idle invocations stop, which bounds re-entry.
+Project commands use `.agents/hooks/`; exported plugin commands resolve through
+`${extensionPath}`.
+
 ### Cursor hooks (`.cursor/hooks.json`)
 
 Cursor hooks follow the native [version-1 hooks contract](https://cursor.com/docs/hooks):
@@ -641,10 +676,11 @@ Codex hooks follow the native [Codex hooks contract](https://learn.chatgpt.com/d
 
 - **Locations:** repository hooks live in `.codex/hooks.json`; user hooks live in `$CODEX_HOME/hooks.json` (default `~/.codex/hooks.json`). Project hooks load only for a trusted `.codex` layer.
 - **Assets:** repository commands use self-contained `.codex/hooks/*`; user commands use `$CODEX_HOME/ai-toolkit-hooks/*`. They do not call Claude's `~/.softspark/ai-toolkit/hooks/` paths.
-- **Events:** Codex documents 10 events. ai-toolkit wires 9: `SessionStart`, `PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `PreCompact`, and `Stop`. `PostCompact` is intentionally unwired.
+- **Events:** Codex documents 11 events. ai-toolkit wires 10: `SessionStart`, `SessionEnd`, `PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `PreCompact`, and `Stop`. `PostCompact` remains a valid event for injected command hooks but is intentionally unwired in the base bundle.
+- **Session end:** `SessionEnd` runs the self-contained `session-end.sh` asset with a three-second timeout. Its result is advisory, so the adapter records the handoff without emitting steering output.
 - **Compaction:** `PreCompact` runs `codex-pre-compact.sh`, a Codex-native reminder that refers to the active `AGENTS.md` chain, plan, and git state. It does not run Claude's `pre-compact.sh` or `pre-compact-save.sh` payload adapters.
 - **Ownership:** native JSON contains no private `_source` keys. Core handlers carry `AI_TOOLKIT_HOOK_OWNER=ai-toolkit` in their command; plugin and external handlers use exact source-specific command markers.
-- **Preservation:** generation replaces only toolkit-owned handlers and assets. Unrelated user handlers and plugin-owned handlers remain intact.
+- **Preservation:** generation replaces only toolkit-owned handlers and assets. Unrelated user handlers, plugin-owned handlers, an optional top-level `description`, and valid handler-level `additionalContextLimit` values remain intact.
 - **Trust:** installation never bypasses trust. Review the active definitions with `/hooks` after install or update.
 
 ### Devin CLI hooks (`.devin/hooks.v1.json`)

package/kb/reference/mcp-editor-compatibility.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - MCP Editor Compatibility"
 category: reference
 service: ai-toolkit
 tags: [mcp, editors, compatibility, codex, cursor, antigravity]
-version: "1.3.0"
+version: "1.3.1"
 created: "2026-04-12"
-last_updated: "2026-07-14"
+last_updated: "2026-08-19"
 description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
 ---
 
@@ -23,7 +23,7 @@ ai-toolkit keeps `.mcp.json` as the project-level canonical template format and
 | Cursor | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors `mcpServers` directly |
 | GitHub Copilot | project + global | `.github/mcp.json`, `$COPILOT_HOME/mcp-config.json` (default `~/.copilot/mcp-config.json`) | Adds Copilot-required `type` and `tools` fields |
 | Gemini CLI | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Merges `mcpServers` into settings JSON |
-| Google Antigravity | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Preserves documented `command`, `serverUrl`, and `url` transports plus optional authentication, disablement, and tool-filter fields |
+| Google Antigravity | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Emits current `command` or `serverUrl` transports; consumes portable `transport` metadata, normalizes legacy input `url` to `serverUrl`, rejects `httpUrl`, and preserves optional authentication, disablement, and tool-filter fields |
 | Roo Code | project | `.roo/mcp.json` | Mirrors `mcpServers` into the documented project-level MCP file |
 | Windsurf | global | `~/.codeium/windsurf/mcp_config.json` | Global-only JSON config |
 | Cline | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only JSON config |

package/kb/reference/mcp-templates.md

@@ -3,9 +3,9 @@ title: "MCP Server Templates"
 category: reference
 service: ai-toolkit
 tags: [mcp, templates, servers, configuration, editors, inject-mcp, external-templates]
-version: "1.4.0"
+version: "1.4.1"
 created: "2026-04-07"
-last_updated: "2026-07-14"
+last_updated: "2026-08-19"
 description: "Reference for 26 built-in MCP server templates, external template injection via inject-mcp, and native editor MCP installation support."
 ---
 
@@ -51,7 +51,7 @@ When `install` runs with `--scope project`, ai-toolkit also updates the project'
 | `cursor` | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors canonical `mcpServers` |
 | `copilot` | project + global | `.github/mcp.json`, `$COPILOT_HOME/mcp-config.json` (default `~/.copilot/mcp-config.json`) | Adds `type` and `tools: ["*"]` automatically |
 | `gemini` | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Uses Gemini CLI `mcpServers` format |
-| `antigravity` | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Preserves `url` or `serverUrl` remote transports and Antigravity authentication/tool-control fields |
+| `antigravity` | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Emits `serverUrl` for remote transports, consumes portable `transport` metadata, normalizes legacy input `url`, rejects `httpUrl`, and preserves Antigravity authentication/tool-control fields |
 | `roo` | project | `.roo/mcp.json` | Mirrors canonical `mcpServers` into Roo's project MCP file |
 | `windsurf` | global | `~/.codeium/windsurf/mcp_config.json` | Global-only official config |
 | `cline` | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only official config |

package/kb/reference/opencode-compatibility.md

@@ -3,17 +3,17 @@ title: "AI Toolkit - opencode Compatibility"
 category: reference
 service: ai-toolkit
 tags: [opencode, compatibility, install, skills, hooks, mcp, plugins]
-version: "1.0.1"
+version: "1.1.0"
 created: "2026-04-16"
-last_updated: "2026-07-14"
-description: "Reference for how ai-toolkit integrates with opencode — AGENTS.md, subagents, slash commands, JS plugin hook bridge, and MCP merge into opencode.json."
+last_updated: "2026-08-19"
+description: "Reference for how ai-toolkit integrates with opencode — AGENTS.md, Agent Skills, subagents, slash commands, JS plugin hooks, and MCP config."
 ---
 
 # AI Toolkit - opencode Compatibility
 
 ## Summary
 
-opencode (https://opencode.ai) is the 11th supported editor. `ai-toolkit install --editors opencode` (or `--editors all`) lays down a full native integration: shared `AGENTS.md`, per-agent `.opencode/agents/` files, per-command `.opencode/commands/` files, a JS plugin bridging toolkit Bash hooks to opencode lifecycle events, and MCP server merge into `opencode.json`.
+opencode (https://opencode.ai) is the 11th supported editor. `ai-toolkit install --editors opencode` (or `--editors all`) lays down shared `AGENTS.md`, per-agent `.opencode/agents/` files, per-command `.opencode/commands/` files, a JS plugin bridging toolkit Bash hooks to opencode lifecycle events, and MCP server merge into `opencode.json`. The `full` profile also installs complete native Agent Skills.
 
 opencode also reads `CLAUDE.md` as a fallback, so a user without the native integration still gets baseline rules. The native path adds subagents, slash commands, hooks, and MCP.
 
@@ -24,6 +24,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; the prompt lives in the markdown body)
+- `.opencode/skills/<name>/SKILL.md` plus its resources (`profile=full`)
 - `.opencode/plugins/ai-toolkit-hooks.js` (JS plugin bridging Bash hooks)
 - `opencode.json` (MCP key merged from `.mcp.json`, user keys preserved)
 
@@ -34,6 +35,7 @@ opencode also reads `CLAUDE.md` as a fallback, so a user without the native inte
 - `~/.config/opencode/AGENTS.md`
 - `~/.config/opencode/agents/ai-toolkit-*.md`
 - `~/.config/opencode/commands/ai-toolkit-*.md`
+- `~/.config/opencode/skills/<name>/SKILL.md` plus resources (`profile=full`)
 - `~/.config/opencode/plugins/ai-toolkit-hooks.js`
 - `~/.config/opencode/opencode.json` (MCP merge, user keys preserved)
 
@@ -46,6 +48,7 @@ Files land directly under `~/.config/opencode/` (no `.opencode/` nesting) becaus
 | Rules file         | `CLAUDE.md` | `AGENTS.md`     | `AGENTS.md` + `CLAUDE.md` fallback        |
 | Subagents          | Yes         | Yes (`.codex/agents/*.toml`) | Yes (`mode: subagent`)          |
 | Slash commands     | Skills      | Adapted skills  | Native commands with frontmatter          |
+| Agent Skills       | Yes         | Yes             | Yes (`.opencode/skills/*/SKILL.md`)        |
 | MCP                | Yes         | Yes             | Yes (`opencode.json`)                     |
 | Lifecycle hooks    | JSON config | `.codex/hooks`  | JS/TS plugins (~30+ events)               |
 | Global config dir  | `~/.claude` | `$CODEX_HOME` (default `~/.codex`) | `~/.config/opencode`       |
@@ -79,6 +82,31 @@ OpenCode while translating Claude-only skill-directory variables and runtime
 APIs. Codex output uses a separate renderer and converts prompt placeholders to
 durable user-input prose.
 
+## Native Agent Skills
+
+OpenCode's stable Agent Skills surface discovers one directory per skill at
+`.opencode/skills/<name>/SKILL.md` or
+`~/.config/opencode/skills/<name>/SKILL.md`. The `full` profile copies each
+complete ai-toolkit skill directory so relative scripts, references,
+templates, and assets remain available. Lower profiles use OpenCode's
+documented `.claude/skills/` and `.agents/skills/` compatibility discovery and
+remove only toolkit-managed native copies when downgrading.
+
+`generate_opencode_skills.py` preserves the stable portable fields `name`,
+`description`, `license`, `compatibility`, and `metadata`. Claude-only runtime
+fields and orchestration primitives are not emitted. The adapter maps
+`user-invocable: false` to the v2-compatible `slash: false` hint and
+`disable-model-invocation: true` to metadata
+`opencode/autoinvoke: false`. Stable OpenCode ignores unknown frontmatter and
+loads Agent Skills on demand through the `skill` tool; slash commands continue
+to come only from `.opencode/commands/`.
+
+Managed manifests let profile downgrade and uninstall remove generated files
+while preserving user-owned skill directories and files added beside managed
+resources. Source and destination symlinks are rejected before writes. Pinned
+destination descriptors remain active through generation, cleanup, and
+rollback, so an ancestor swap cannot redirect mutations outside the target.
+
 ## Hook Bridge (JS Plugin)
 
 `.opencode/plugins/ai-toolkit-hooks.js` is a single-file plugin that maps opencode events to the shared Bash hooks in `~/.softspark/ai-toolkit/hooks/`:
@@ -126,12 +154,31 @@ The installer detects opencode as configured when any of these markers exist:
 
 - Generated `.opencode/agents/ai-toolkit-*.md`
 - Generated `.opencode/commands/ai-toolkit-*.md`
+- Manifest-owned files under generated `.opencode/skills/<name>/` directories
 - Generated `.opencode/plugins/ai-toolkit-hooks.js`
 - Managed markers from `AGENTS.md`
 - `mcp` key entries injected by the toolkit (user keys preserved)
 
 User-authored opencode files and user-authored `opencode.json` keys are never deleted.
 
+Native skill cleanup removes only manifest-owned files. A user-owned skill or
+an extra file inside a formerly managed directory is preserved. The native
+skills tree participates in the uninstall transaction, so a later cleanup
+failure restores managed files without discarding those user additions.
+
+## Current Config and v2 Beta Surfaces
+
+Stable OpenCode supports both `opencode.json` and `opencode.jsonc`. Its current
+config directory uses plural `agents/`, `commands/`, `plugins/`, and `skills/`
+subdirectories. The v2 plugin API is still beta and additionally recognizes
+root-package `skills/*.md`, nested `skills/**/SKILL.md`, and a `skills` config
+array containing local paths or HTTP URLs.
+
+There is no migration in ai-toolkit for v2 yet. The existing stable JavaScript
+plugin generator remains the supported path until the v2 API stabilizes; the
+beta surfaces are tracked in the ecosystem registry so a later sync cannot
+silently miss their promotion.
+
 ## Behavioral Limits
 
 - opencode does not expose the full Claude hook event surface; only the events in the mapping table above are bridged. Claude-only events (`TaskCompleted`, `TeammateIdle`, `SubagentStart`, `SubagentStop`, `PreCompact`) are silently skipped.
@@ -141,7 +188,7 @@ User-authored opencode files and user-authored `opencode.json` keys are never de
 
 The opencode integration is verified by:
 
-1. Generator contract tests for the five `generate_opencode*.py` scripts (bats)
+1. Generator contract tests for the six `generate_opencode*.py` scripts (bats)
 2. MCP merge idempotency and user-key preservation tests
 3. Plugin export shape and event coverage tests
 4. Auto-detection tests for install / update flow
@@ -154,6 +201,7 @@ The opencode integration is verified by:
 | `ai-toolkit opencode-md` | Generate `AGENTS.md` body for opencode |
 | `ai-toolkit opencode-agents` | Generate `.opencode/agents/ai-toolkit-*.md` |
 | `ai-toolkit opencode-commands` | Generate `.opencode/commands/ai-toolkit-*.md` |
+| `ai-toolkit opencode-skills` | Generate complete `.opencode/skills/<name>/` directories |
 | `ai-toolkit opencode-plugin` | Generate `.opencode/plugins/ai-toolkit-hooks.js` |
 | `ai-toolkit opencode-json` | Merge MCP servers into `opencode.json` |