docs: add tool exposure requirement for agent manifests

morph_edit routing policy requires both the always-on instruction AND
tool manifest exposure. Document this in instructions/morph-tools.md,
README installation section, and test assertions.

Also gitignore ADV plugin artifacts and lockfiles.

Author: JRedeker

.gitignore

@@ -16,6 +16,14 @@ logs/
 .vscode/
 .idea/
 
+# Lockfiles (bun/pnpm — npm uses package-lock.json)
+bun.lock
+pnpm-lock.yaml
+
+# ADV plugin state
+.specdb/
+project.json
+
 # OS
 .DS_Store
 Thumbs.db

README.md

@@ -45,7 +45,7 @@ Or pin to a specific version:
     "~/.config/opencode/instructions/morph-tools.md"
   ],
   "plugin": [
-    "github:JRedeker/opencode-morph-fast-apply#v1.8.1"
+    "github:JRedeker/opencode-morph-fast-apply#v1.8.2"
   ]
 }
 ```
@@ -76,6 +76,10 @@ tool selection you should also load the packaged always-on instruction file
 shown above. This avoids agents defaulting to native `edit` when `morph_edit`
 is the better fit for large, scattered, or whitespace-sensitive edits.
 
+Important: the active agent must also expose `morph_edit` in its tool manifest.
+If an agent profile marks `morph_edit: false`, the model cannot choose Morph
+even when the plugin is installed and the always-on instruction is present.
+
 ### 2. Set your Morph API key
 
 Get an API key at [morphllm.com/dashboard](https://morphllm.com/dashboard/api-keys), then add to your shell profile:
@@ -187,6 +191,12 @@ The `morph_edit` tool is disabled in readonly agent modes (`plan`, `explore`). S
 
 ## Changelog
 
+### v1.8.2
+
+- **Tool exposure requirement docs** — `instructions/morph-tools.md` now documents that agent profiles must expose `morph_edit: true` in their tool manifest for the routing policy to take effect
+- **README alignment** — Installation section notes the tool manifest requirement alongside the always-on instruction
+- **Test coverage** — Tests verify the tool exposure section exists in the instruction file and README
+
 ### v1.8.1
 
 - **Stable instruction path guidance** - README now prefers `~/.config/opencode/instructions/morph-tools.md` and keeps the packaged `node_modules/...` path as a fallback for direct installs

index.test.ts

@@ -40,6 +40,8 @@ describe("packaged tool-selection instructions", () => {
     expect(content).toContain("`edit`");
     expect(content).toContain("New file creation");
     expect(content).toContain("`write`");
+    expect(content).toContain("Tool Exposure Requirement");
+    expect(content).toContain("morph_edit: true");
   });
 
   test("README documents packaged instruction path", () => {
@@ -52,6 +54,7 @@ describe("packaged tool-selection instructions", () => {
       "~/.config/opencode/node_modules/opencode-morph-fast-apply/instructions/morph-tools.md",
     );
     expect(content).toContain("always-on instruction file");
+    expect(content).toContain("tool manifest");
   });
 });
 

instructions/morph-tools.md

@@ -44,6 +44,17 @@ faster or more reliable than exact-string replacement.
 - Packaged fallback path: `~/.config/opencode/node_modules/opencode-morph-fast-apply/instructions/morph-tools.md`
 - The `morph_edit` tool description is self-contained, but loading this file as an always-on instruction makes tool choice more reliable
 
+### Tool Exposure Requirement
+
+Instruction policy is necessary but not sufficient. The active agent or
+sub-agent must also expose `morph_edit` in its tool manifest.
+
+- If an agent profile sets `morph_edit: false` or omits the tool, the model
+  cannot choose Morph even when this instruction is loaded.
+- Enable `morph_edit: true` for write-capable agents that should use Morph for
+  large or scattered edits.
+- Keep readonly agents blocked unless you explicitly want them to edit files.
+
 ### Anti-Patterns
 
 - Do NOT use `edit` first for large, scattered, or whitespace-sensitive edits

package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-morph-fast-apply",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "OpenCode plugin for Morph Fast Apply - 10x faster code editing",
   "type": "module",
   "main": "index.ts",