nitm-ai-dev-toolkit 3.0.22 → 4.0.0

package/src/monorepo/.opencode/agents/red.md

@@ -1,10 +1,16 @@
 ---
 description: "Write failing tests that define expected behavior. Part of the TDD red-green-refactor cycle."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Red Agent (TDD — Write Failing Tests)

package/src/monorepo/.opencode/agents/refactor.md

@@ -1,10 +1,16 @@
 ---
 description: "Improve code quality and structure while keeping all tests passing. Part of the TDD red-green-refactor cycle."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: allow
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Refactor Agent (TDD — Improve Code Quality)

package/src/monorepo/.opencode/agents/researcher.md

@@ -1,10 +1,16 @@
 ---
 description: "Research codebase patterns, dependencies, and technical context. Analyze code structure, find relevant examples, and report findings without making changes."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: deny
-  bash: deny
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: deny
 ---
 
 # Researcher Agent

package/src/monorepo/.opencode/agents/reviewer.md

@@ -1,10 +1,16 @@
 ---
 description: "Review code changes for correctness, code quality, security, and adherence to project patterns. Provide actionable feedback with specific file and line references. Use immediately after writing or modifying code, or as a quality gate in orchestrated workflows."
 mode: subagent
-temperature: 0.1
-permission:
-  edit: deny
-  bash: allow
+request:
+  body:
+    temperature: 0.1
+permissions:
+  - action: edit
+    resource: "*"
+    effect: deny
+  - action: shell
+    resource: "*"
+    effect: allow
 ---
 
 # Reviewer Agent

package/src/monorepo/.opencode/agents/tdd.md

@@ -1,11 +1,19 @@
 ---
 description: "Implement a feature using test-driven development with red-green-refactor cycle. Coordinates specialized subagents for writing failing tests, implementing code, and refactoring."
 mode: subagent
-temperature: 0.3
-permission:
-  edit: allow
-  bash: allow
-  task: allow
+request:
+  body:
+    temperature: 0.3
+permissions:
+  - action: edit
+    resource: "*"
+    effect: allow
+  - action: shell
+    resource: "*"
+    effect: allow
+  - action: subagent
+    resource: "*"
+    effect: allow
 ---
 
 # TDD Coordinator Agent

package/src/monorepo/.opencode/opencode.jsonc

@@ -5,17 +5,15 @@
 		".opencode/rules/*.md",
 		".agents/skills/orient-to-recent-work/SKILL.md"
 	],
-	"skills": {
-		"paths": [
-			".agents/skills/**/*.md",
-			".claude/skills/**/*.md"
-		]
-	},
-	"plugin": [
+	"skills": [
+		".agents/skills",
+		".claude/skills"
+	],
+	"plugins": [
 		"opencode-mem",
 		"@tarquinen/opencode-dcp@latest",
-		"@dietrichgebert/ponytail",
-		"opentmux"
+		"@dietrichgebert/ponytail@4.12.0"
+		// "opentmux": V1-only; enable only after it supports V2.
 	],
 	"lsp": true
-}
+}

package/src/monorepo/AGENTS.md

@@ -102,8 +102,24 @@ Each app has its own `AGENTS.md` with detailed patterns:
 - `{{APP_DIR}}/{{APP_NAME_1}}/AGENTS.md` - {{APP_1_DESCRIPTION}} patterns
 - `{{APP_DIR}}/{{APP_NAME_2}}/AGENTS.md` - {{APP_2_DESCRIPTION}} patterns
 
+## OpenCode V2 Context
+
+OpenCode use with toolkit v4 requires native V2; Slim >=3.0.0 requires OpenCode >=2.0.7. Read [native setup](README.md#native-opencode-v2) before migration. All bootstrap flows run `opencode --version` before changes for confirmed OpenCode use: V1 must stop and upgrade OpenCode or remain on toolkit 3.x; missing/unparseable versions block OpenCode steps and toolkit 4.0.0 marking. Directory presence is not harness proof; other-harness-only setup is unaffected.
+
+Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`, `plugins`, directory-based `skills`, and `mcp.servers`. Preserve user models/providers/plugins and Slim's separate strict schema; do not host-migrate its `prompt`/`permission`/`variant` fields or silently upgrade the separate external starter. Templates register the author's native V2 `@dietrichgebert/ponytail@4.12.0` locally instead of a bundled Ponytail plugin; `opentmux` stays commented as V1-only. Remove only known obsolete toolkit Ponytail `.js`/`.mjs`/`.ts` copies after backup and approval, preserve unrelated local plugins, and merge/deduplicate upstream registration locally without editing global config. No local API port or bridge is used; plugin/runtime integration is untested.
+
+Ambient root/nested `AGENTS.md` works; config `instructions` entries do not load. `@refs` are ordinary text: explicitly read linked snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands, not unavailable V2 LSP diagnostics. Back up V1 before native conversion; converted files are incompatible with V1. Activate on the next run/restart.
+
 ## Detailed Instructions
 
+### Native Codex
+
+Codex-scoped installs include `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources. Read them as references when relevant, not as automatically loaded Codex rules or evidence of Copilot/Claude use; other harness command, agent, and config directories are excluded from `--env codex`.
+
+Codex uses root and more-specific app/package `AGENTS.md` instructions and `.agents/skills/` natively. Read linked standards when relevant rather than assuming tool-specific rules are auto-loaded. Optional `.codex/config.toml` is comment-only and preserves inherited defaults; project config loads only after explicit user trust. Do not grant self-trust, change security/model/feature defaults, translate Claude frontmatter into Codex agents, or activate MCP servers automatically. Codex MCP uses native `[mcp_servers.name]` TOML, not `.mcp.json`.
+
+For npm setup, read and follow `.nitm/BOOTSTRAP.md`. If manually copied and `.nitm/` is absent, read `.claude/prompt-snippets/bootstrap.md` as a task document; `/bootstrap` is not a native Codex command. Determine the actual harness from runtime information or ask; scaffold directories alone do not establish use. Named custom-agent examples below apply only to harnesses that support their formats; in Codex, use workflow skills and only available native delegation capabilities.
+
 Detailed standards are split into focused instruction files in `.github/instructions/`:
 
 | Instruction File                   | Description                                       |

package/src/monorepo/CLAUDE.md

@@ -59,5 +59,5 @@
 - Commands are in `.opencode/commands/`.
 - Rules are in `.opencode/rules/`.
 - Agents are in `.opencode/agents/`.
-- Instructions are loaded from `AGENTS.md`, `.github/instructions/`, and `.claude/rules/`.
+- Native V2 loads ambient `AGENTS.md`, not config `instructions` entries. Explicitly read referenced snippets (`@refs` are ordinary text, not attachments). See [OpenCode setup](README.md#native-opencode-v2).
 - Skills are loaded from `.agents/skills/` and `.claude/skills/`.

package/src/monorepo/README.md

@@ -50,6 +50,28 @@ This is a monorepo managed with {{BUILD_SYSTEM}}.
 
 ## Getting Started
 
+### Native OpenCode V2
+
+Toolkit v4 requires **OpenCode V2 (major >=2)** for OpenCode use; oh-my-opencode-slim >=3.0.0 requires OpenCode >=2.0.7. Bootstrap, patch, and upgrade run `opencode --version` before changes (optional leading `v` accepted). V1 must stop before OpenCode customization/migration or marking toolkit 4.0.0: upgrade OpenCode or remain on toolkit 3.x. A missing CLI or unparseable version stops OpenCode steps and version marking until confirmed/installed. Confirm harness use from runtime evidence or ask, not scaffold directories; other-harness-only setup is unaffected.
+
+The template's local `plugins` array registers the author's native V2 package `@dietrichgebert/ponytail@4.12.0`, alongside `opencode-mem` and `@tarquinen/opencode-dcp@latest`; `opentmux` remains commented as V1-only. The obsolete local Ponytail plugin is no longer bundled; no local API port or bridge is used. For existing projects, back up and obtain approval before removing only known toolkit `.opencode/plugins/ponytail.js`, `.mjs`, or `.ts` copies; preserve unrelated local plugins and merge/deduplicate upstream registration locally without editing global plugins. Native local plugins are discovered automatically; do not register them twice.
+
+With approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally without replacing other registrations. Slim's separate strict schema retains `prompt`, `permission`, and `variant`; do not host-migrate it. The external starter is a separate package, not automatically upgraded. Plugin/runtime integration has not been tested.
+
+Use native `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`. Follow the [V2 migration guide](https://opencode.ai/v2/docs/migrate-v1) and [plugin guide](https://opencode.ai/v2/docs/build/plugins); the published schema may describe V1 and is not V2 validation authority.
+
+Ambient root/nested `AGENTS.md` works; config `instructions` entries are not loaded. `@refs` are ordinary text: read linked snippets explicitly. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use workspace lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
+
+`--env opencode` supplies minimal shared references without activating other harnesses. Back up V1, merge rather than clobber models/providers/plugins, and activate on the next run/restart. Native-converted files are incompatible with V1. Verify with installed V2; `doctor` is not runtime validation. Toolkit 4.0.0 publishing has not been executed.
+
+### Native Codex
+
+`--env codex` includes `.codex/`, `.agents/`, and shared context, plus `.github/instructions/` and `.claude/rules-snippets/` solely to supply AGENTS-linked standards and their wrapper source content. No other harness command, agent, or config directories are installed; these references do not establish Copilot/Claude use or load automatically as Codex rules. Other harness scopes are unchanged.
+
+Codex reads root/nested `AGENTS.md` instructions and `.agents/skills/` natively. The optional comment-only `.codex/config.toml` preserves inherited defaults and is loaded only after explicit user trust; it does not grant trust or activate MCP servers. Codex MCP uses native `[mcp_servers.name]` TOML, not `.mcp.json`.
+
+For npm setup, ask Codex to read and follow `.nitm/BOOTSTRAP.md`. For manual copies without `.nitm/`, provide `.claude/prompt-snippets/bootstrap.md` as a task document (copy the shared snippets too). For AI-guided updates, provide `.claude/prompt-snippets/bootstrap-patch.md`. Toolkit slash commands and other tools' custom-agent formats are not native Codex commands or agent definitions. Bootstrap must identify the actual running harness or ask, not infer it from scaffolded directories.
+
 ### Prerequisites
 
 - Node.js {{NODE_VERSION}}

package/src/repo/.claude/agents/documenter.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Documenter"
 description: "Analyze codebases and create comprehensive documentation. Use for AGENTS.md, README files, API docs, architecture documentation, and onboarding guides."
-tools: ["Read", "Grep", "Write", "Edit", "Bash(*)"]
+tools: ["Read", "Grep", "Write"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/planner.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Planner"
 description: "Break down feature requests into implementation tasks. Read specifications, analyze codebase patterns, and produce structured plans with dependencies."
-tools: ["Read", "Grep", "Write", "Bash(*)"]
+tools: ["Read", "Grep", "Write"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/researcher.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Researcher"
 description: "Research codebase patterns, dependencies, and technical context. Analyze code structure, find relevant examples, and report findings without making changes."
-tools: ["Read", "Grep"]
+tools: ["Read", "Grep", "Write"]
 user-invocable: true
 ---
 

package/src/repo/.claude/agents/reviewer.agent.md

@@ -1,7 +1,7 @@
 ---
 name: "Reviewer"
 description: "Review code changes for correctness, code quality, security, and adherence to project patterns. Provide actionable feedback with specific file and line references. Use immediately after writing or modifying code, or as a quality gate in orchestrated workflows."
-tools: ["Read", "Grep", "Bash(*)"]
+tools: ["Read", "Grep", "Write", "Bash(*)"]
 user-invocable: true
 ---
 

package/src/repo/.claude/commands/ponytail-audit.md

@@ -1,15 +1,13 @@
 ---
-description: Audit the whole repo for over-engineering and identify what can be deleted
-allowed-tools: "Read, Grep, Bash"
+description: Audit the whole repo for over-engineering — find what can be deleted
+allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Audit
 
+## Agent Dispatch
 > **Recommended agent:** `oracle`
 > Whole-repo over-engineering analysis
 
-
-# Ponytail Audit
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-audit.md](../prompt-snippets/ponytail-audit.md).

package/src/repo/.claude/commands/ponytail-debt.md

@@ -1,15 +1,13 @@
 ---
 description: "Harvest ponytail: comments into a tracked debt ledger"
-allowed-tools: "Read, Grep, Bash"
+allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Debt
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Debt ledger harvesting
 
-
-# Ponytail Debt
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-debt.md](../prompt-snippets/ponytail-debt.md).

package/src/repo/.claude/commands/ponytail-gain.md

@@ -4,12 +4,10 @@ allowed-tools: "Read"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Gain
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Impact scoreboard display
 
-
-# Ponytail Gain
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-gain.md](../prompt-snippets/ponytail-gain.md).

package/src/repo/.claude/commands/ponytail-help.md

@@ -4,12 +4,10 @@ allowed-tools: "Read"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Help
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Quick-reference display
 
-
-# Ponytail Help
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-help.md](../prompt-snippets/ponytail-help.md).

package/src/repo/.claude/commands/ponytail-review.md

@@ -1,15 +1,13 @@
 ---
-description: Review changes for over-engineering and identify what can be deleted
+description: Review changes for over-engineering — find what can be deleted
 allowed-tools: "Read, Grep"
 argument-hint: "no arguments required"
 ---
 
-## Agent Dispatch
+# Ponytail Review
 
+## Agent Dispatch
 > **Recommended agent:** `oracle`
 > Diff-level over-engineering review
 
-
-# Ponytail Review
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail-review.md](../prompt-snippets/ponytail-review.md).

package/src/repo/.claude/commands/ponytail.md

@@ -1,15 +1,13 @@
 ---
 description: Switch ponytail intensity level (lite/full/ultra/off)
-allowed-tools: "Read, Grep, Bash, Edit, Write"
+allowed-tools: "Read, Grep"
 argument-hint: "optional level (lite/full/ultra/off)"
 ---
 
-## Agent Dispatch
+# Ponytail
 
+## Agent Dispatch
 > **Recommended agent:** `fixer`
 > Apply YAGNI/stdlib discipline
 
-
-# Ponytail
-
 Follow the prompt defined in [.claude/prompt-snippets/ponytail.md](../prompt-snippets/ponytail.md).

package/src/repo/.claude/prompt-snippets/bootstrap-patch.md

@@ -1,11 +1,19 @@
 # Bootstrap Patch
 
-Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repository and apply any updated, new, or missing guidance to this project.
+Fetch supported toolkit v4.x templates from the ai-assisted-dev-toolkit repository's `v4.x` branch and merge updated, new, or missing guidance into this project.
+
+## OpenCode version preflight (before any changes)
+
+- Confirm OpenCode use from actual session/runtime evidence or ask the user; directory presence alone is not proof. If only other harnesses are used, skip this preflight and all OpenCode steps.
+- For confirmed OpenCode use, run `opencode --version` before any project writes. Trim output and parse numeric major/minor/patch components, accepting an optional leading `v`; toolkit 4.x requires `major >= 2`.
+- If OpenCode V1 (`major < 2`) is detected, **STOP** before customizing/migrating OpenCode files or writing `.toolkit-version` as `4.0.0`. Ask the user to upgrade OpenCode to V2 or remain on toolkit 3.x.
+- If the CLI is missing, fails, or output is unparseable, **STOP OpenCode steps** and leave the version marker unchanged; ask the user to confirm/install a supported OpenCode version, then rerun this check. Never assume V2.
+- If oh-my-opencode-slim >=3.0.0 is used or planned, require OpenCode >=2.0.7 (compare version components numerically); otherwise **STOP** before changes and ask to upgrade. Proceed only after this gate passes.
 
 ## Orchestrator Checkpoint
 
 > **🛑 Before starting**: This command involves fetching, diffing, and applying changes across many files.
-> Dispatch parallel subagents for independent file groups (rules, commands, prompts, instructions, skills, agents).
+> Complete Step 1's source/version gates before dispatching parallel diff agents for independent file groups (rules, commands, prompts, instructions, skills, agents).
 > See `.claude/rules-snippets/subagent-workflow.md` for patterns.
 
 ## Usage
@@ -19,15 +27,22 @@ Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repos
 
 ## Process
 
+**Codex invocation and scope:** `/bootstrap-patch` is not a native Codex command. Ask Codex to read and follow this snippet as a task document. Identify the actual harness from session/runtime evidence or ask; scaffold directories do not prove use. Codex targets `AGENTS.md`, relevant nested instructions, `.agents/skills/`, and optional `.codex/config.toml`. Include `.github/instructions/` and `.claude/rules-snippets/` solely as AGENTS-linked standards and their wrapper sources for Codex-scoped installs, not automatically loaded rules or evidence of Copilot/Claude use. Only include other harness command, agent, and config categories when those harnesses are confirmed in use.
+
+**Codex merge guardrails:** preserve existing TOML and inherited user defaults. The shipped `.codex/config.toml` is comment-only; parse it as TOML, do not add model/provider, approval, sandbox, security, feature, self-trust, or active MCP settings. Project config is loaded only after explicit user trust. MCP uses native `[mcp_servers.name]` TOML, not `.mcp.json`; do not migrate or activate servers automatically. Claude/Copilot frontmatter and OpenCode permission blocks are not Codex agent definitions; no Codex custom-agent format is shipped here.
+
 1.  **Fetch Latest Templates**:
 
-    Clone or fetch the latest ai-assisted-dev-toolkit templates:
+    Fetch only the supported `v4.x` source branch:
 
     ```bash
+    set -e
     TOOLKIT_TEMP=$(mktemp -d)
-    git clone --depth 1 https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
+    git clone --depth 1 --branch v4.x https://github.com/ninjasitm/ai-assisted-dev-toolkit.git "$TOOLKIT_TEMP"
     ```
 
+    **Source availability gate:** If the clone fails or `v4.x` is unavailable (for example, not yet published), **STOP** before diff/apply/version marking. Do not fall back to the default branch or V3, and do not push/publish a branch to unblock this task; ask for an approved available v4.x source.
+
     Determine the correct source path based on project structure:
     - **Single repo**: Use `$TOOLKIT_TEMP/src/repo/`
     - **Monorepo**: Use `$TOOLKIT_TEMP/src/monorepo/`
@@ -40,9 +55,11 @@ Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repos
 
     Check for a `.toolkit-version` file in the project root:
     - If exists: Read the version string (e.g., `2.0.10`, `3.0.0`)
-    - If missing: Assume legacy version (pre-3.0.0)
+    - If missing: Verify the installed version or legacy state with the user; absence alone does not prove a pre-3.0 installation
+
+    Read the toolkit's version from the `version` field in `$TOOLKIT_TEMP/package.json` to compare; `.toolkit-version` tracks the target project's installed version.
 
-    Read the toolkit's version from `$TOOLKIT_TEMP/.toolkit-version` to compare.
+    **Source version guard (before diff/apply/version marking):** Parse source/target versions as SemVer and compare them (major/minor/patch numerically). If the fetched package's major is not `4`, or its version is older than the target `.toolkit-version`, **STOP** without diffing, applying changes, or updating the marker. Unknown/unparseable versions must also **STOP** and ask rather than guess. Never auto-downgrade.
 
     **Version Comparison:**
     - **Same version**: No structural changes expected
@@ -65,6 +82,7 @@ Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repos
     | **Claude Agents**          | `.claude/agents/*.agent.md`              | `src/{type}/.claude/agents/*.agent.md`              |
     | **Skills**                 | `.agents/skills/*/SKILL.md`              | `src/{type}/.agents/skills/*/SKILL.md`              |
     | **AGENTS.md**              | `AGENTS.md`                              | `src/{type}/AGENTS.md`                              |
+    | **Codex Config**           | `.codex/config.toml`                     | `src/{type}/.codex/config.toml`                     |
     | **CLAUDE.md**              | `CLAUDE.md`                              | `src/{type}/CLAUDE.md`                              |
     | **Claude Rules Snippets**  | `.claude/rules-snippets/*.md`            | `src/{type}/.claude/rules-snippets/*.md`            |
     | **Claude Prompt Snippets** | `.claude/prompt-snippets/*.md`           | `src/{type}/.claude/prompt-snippets/*.md`           |
@@ -73,20 +91,20 @@ Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repos
     | **OpenCode Commands**      | `.opencode/commands/*.md`                | `src/{type}/.opencode/commands/*.md`                |
     | **OpenCode Rules**         | `.opencode/rules/*.md`                   | `src/{type}/.opencode/rules/*.md`                   |
     | **OpenCode Agents**        | `.opencode/agents/*.md`                  | `src/{type}/.opencode/agents/*.md`                  |
-    | **OpenCode Plugins**       | `.opencode/plugins/*.mjs`                | `src/{type}/.opencode/plugins/*.mjs`                |
+    | **OpenCode Local Plugins** | `.opencode/plugins/*.{js,mjs,ts}`        | Inventory only; preserve unrelated plugins         |
     | **Hooks**                  | `hooks/*.{js,sh,ps1}`                    | `src/{type}/hooks/*.{js,sh,ps1}`                    |
     | **Agent Rules**            | `.agents/rules/*.md`                     | `src/{type}/.agents/rules/*.md`                     |
-    | **Toolkit Version**        | `.toolkit-version`                       | `.toolkit-version` (root of toolkit)                |
-
-    **⚠️ OpenCode `opencode.jsonc` Schema Validation:**
-
-    When patching `.opencode/opencode.jsonc`, **only add or modify supported top-level keys**. The schema is defined at `https://opencode.ai/config.json`. Do NOT add unsupported keys.
+    | **Toolkit Version**        | `.toolkit-version`                       | `package.json` `version` (toolkit root)             |
 
-    **Supported top-level keys:** `$schema`, `instructions`, `skills`, `agent`, `default_agent`, `model`, `small_model`, `provider`, `mcp`, `tools`, `permission`, `lsp`, `formatter`, `server`, `shell`, `command`, `plugin`, `watcher`, `snapshot`, `share`, `autoupdate`, `compaction`, `attachment`, `logLevel`, `disabled_providers`, `enabled_providers`, `tool_output`, `enterprise`, `experimental`
+    **OpenCode native V2 merge checks (confirmed OpenCode use only):**
 
-        **Do NOT add** keys like `rules`, `agents`, `commands`, `prompts` as top-level keys — OpenCode uses the `.opencode/` directory structure and `instructions` array instead.
+    Follow official V2 [migration](https://opencode.ai/v2/docs/migrate-v1), [config](https://opencode.ai/v2/docs/config), [agents](https://opencode.ai/v2/docs/agents), and [plugins](https://opencode.ai/v2/docs/build/plugins) docs. The published schema may describe V1; neither it nor a V1 API fetch validates native V2. Plural keys are intentional.
 
-    > **Watch out:** the ponytail template uses the `plugin` key (singular). If you see `plugins` (plural) in your `opencode.jsonc`, that's a typo and the plugin won't load.
+    - Use `agents`/`system`, `request.body.temperature`, ordered `permissions` (`action`/`resource`/`effect`, `shell`/`subagent`, last match wins), `commands`/`subagent`, `plugins` with `{ "package": "…", "options": {} }`, skill-directory arrays, and `mcp.servers` with inverse `disabled` and `timeout.catalog`/`timeout.execution`.
+    - The version preflight must pass before changes. Back up V1 before native conversion (converted files are incompatible with V1). Preserve models/providers/user-global plugins. Only with approval, merge `"plugins": ["oh-my-opencode-slim@3.0.0"]` locally. Slim's separate strict schema keeps `prompt`/`permission`/`variant`; do not host-migrate it or silently upgrade the separate external starter.
+    - **Ponytail replacement (plan here; apply after backup and approval in Step 5):** Remove only known obsolete toolkit-owned `.opencode/plugins/ponytail.js`, `.opencode/plugins/ponytail.mjs`, and `.opencode/plugins/ponytail.ts` copies. Preserve unrelated local plugins. Merge/deduplicate the author's native V2 `@dietrichgebert/ponytail@4.12.0` registration in the local `plugins` array where appropriate, retaining other registrations/options; do not edit global config. Keep `opentmux` commented as V1-only. Do not port local APIs or add bridges; runtime integration is untested. Native local discovery needs no duplicate registration.
+    - `instructions` entries are accepted but not loaded; ambient `AGENTS.md` works. `@refs` are ordinary text: explicitly read snippets. `request.body.temperature` remains in config, but the current runner does not send it. Preserve `lsp: true`; use project lint/typecheck/compiler commands (no V2 LSP tools/diagnostics currently).
+    - `--env opencode` supplies minimal shared references without other harness activation. Activate on the next run/restart and report only installed-V2 checks actually run, not assumed runtime validation. Publishing 4.0.0 has not been executed.
 
 3.  **Diff Analysis** (parallelizable — dispatch one subagent per category):
 
@@ -97,7 +115,7 @@ Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repos
     - **📝 Updated**: Exists in both but template has newer content → candidate for merge
     - **✅ Current**: Exists in both and content matches → no action needed
     - **🔧 Customized**: Exists in both, project version has non-placeholder customizations → careful merge
-    - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is
+    - **⚠️ Missing in Template**: Exists in project but not in template → project-specific, keep as-is except the approved obsolete toolkit Ponytail removal above
 
     b. **For updated files, generate a structured diff**:
     - Preserve project-specific `{{PLACEHOLDER}}` replacements (already-bootstrapped values)
@@ -157,7 +175,9 @@ Fetch the latest AI instruction templates from the ai-assisted-dev-toolkit repos
       a. **New files**: Copy directly from template
       b. **Updated files (no customization)**: Replace with template version
       c. **Updated files (customized)**: Apply structural additions while preserving project values
-      d. **Git commit**: Stage and commit all changes with message:
+      d. **OpenCode plugins**: Apply only the approved Ponytail replacement above after backing up the known obsolete toolkit copies and local config; preserve all unrelated local/global plugins.
+      e. **Toolkit version**: Update `.toolkit-version` to the fetched toolkit version (`4.0.0` for this migration) only after the approved migration and OpenCode preflight pass (or OpenCode is confirmed out of scope).
+      f. **Git commit**: Stage and commit all changes with message:
       ```bash
       git add -A
       git commit -m "chore: patch AI instructions from toolkit [$(date +%Y-%m-%d)]"