diff --git a/AGENTS.md b/AGENTS.md
index a0681a8..9a24730 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -49,3 +49,13 @@ sigil unlink ~/.config/wezterm/wezterm.lua
 # Editing dotfiles
 
 When editing dotfiles, it is preferred to add/edit the files in this project directly, instead of going to the source. this way we can then use sigil apply --prune, and everything will be synced, even when there are new files.
+
+# pi extensions
+
+Extensions live in `pi/files/agent/extensions/`. 
+
+**Discovery quirk:** If `package.json` has a `pi.extensions` field, pi **only** loads those listed extensions and skips auto-discovery of `*.ts` files. To enable auto-discovery (load all `.ts` files including symlinks), either:
+- Remove the `extensions` field entirely: `"pi": {}`
+- Or delete `package.json` if you don't need npm dependencies
+
+Multi-file extensions (directories) need an `index.ts` entry point (or `package.json` with `pi.extensions` pointing to the entry file).
diff --git a/pi/files/agent/extensions/lsp/index.ts b/pi/files/agent/extensions/lsp/index.ts
new file mode 100644
index 0000000..ce6ec13
--- /dev/null
+++ b/pi/files/agent/extensions/lsp/index.ts
@@ -0,0 +1,8 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import lspHookFactory from "./lsp.js";
+import lspToolFactory from "./lsp-tool.js";
+
+export default function (pi: ExtensionAPI) {
+  lspHookFactory(pi);
+  lspToolFactory(pi);
+}
diff --git a/pi/files/agent/extensions/package.json b/pi/files/agent/extensions/package.json
index ee3e0d3..6a92635 100644
--- a/pi/files/agent/extensions/package.json
+++ b/pi/files/agent/extensions/package.json
@@ -19,17 +19,6 @@
     "@types/node": "^25.3.3",
     "typescript": "^5.7.0"
   },
-  "pi": {
-    "extensions": [
-      "./custom-provider-anthropic/index.ts",
-      "./lsp/lsp.ts",
-      "./lsp/lsp-tool.ts",
-      "./matugen-theme-watch/index.ts",
-      "./pi-web-access/index.ts"
-    ],
-    "skills": [
-      "./pi-web-access/skills"
-    ]
-  },
+  "pi": {},
   "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264"
 }