diff --git a/AGENTS.md b/AGENTS.md
index 73a3bed..c17b2fd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## What this is
 
-Producer-side tooling for [MemPalace](https://github.com/MemPalace/mempalace). Two thin wrappers in `bin/` plus the companion agent skill. Pairs with the consumer-side `mempalace` skill.
+Producer-side tooling for [MemPalace](https://github.com/MemPalace/mempalace). Three thin wrappers in `bin/` (opencode + pi session feeders, a docs miner), a companion agent skill, and an `extensions/` tree with per-harness bridges (currently `pi/`). Pairs with the consumer-side `mempalace` skill.
 
 Read [`ARCHITECTURE.md`](ARCHITECTURE.md) first — it's the canonical spec for what this repo does and why.
 
@@ -61,7 +61,7 @@ All non-destructive: if something is already in place and points into this repo,
 
 ## Adding a new wrapper
 
-A third wrapper would justify factoring a shared helper library. Until then, copy the pattern from `mempalace-session` (richest example):
+Three wrappers live happily as standalone scripts — no shared helper library yet, because each one's stage-to-cache logic differs enough that the common surface is thin (arg parsing + `mempalace mine` invocation). A fourth wrapper might tip the balance; re-evaluate then. Until then, copy the pattern from `mempalace-session` (richest example):
 
 1. Create `bin/<name>` with `#!/usr/bin/env bash` + `chmod +x`.
 2. Implement `--help`, `--dry-run`, `--repair` flags (repair is opt-in; `--no-repair` kept as deprecated alias).
@@ -73,6 +73,41 @@ A third wrapper would justify factoring a shared helper library. Until then, cop
 8. Update `ARCHITECTURE.md` if the wrapper fills a new architectural gap.
 9. Update `SKILL.md` if agents should know when to invoke it.
 
+## Adding a new harness extension
+
+`extensions/<harness>/` is the home for per-agent-harness bridges — code that
+lives inside an agent runtime (pi, claude-code, kiro, …) and talks to the
+mempalace MCP server. Currently only `extensions/pi/` exists. If you add
+a second one (e.g. `extensions/claude-code/`), follow the same shape:
+
+1. **One directory per harness.** Never mix harnesses in one dir.
+2. **A `README.md`** covering: what it does, harness-specific install path,
+   debug knobs, and any gotchas (e.g. the pi `Type.Unsafe` schema passthrough).
+3. **Symlink what's safe to symlink, template what the harness rewrites.**
+   Pi rewrites `~/.pi/agent/settings.json` at runtime — shipped as
+   `settings.example.json` with a `cp` instruction, not a symlink, to avoid
+   dirtying the repo. Whereas `mempalace.ts` and `keybindings.json` are
+   pure config, safe to symlink.
+4. **Gate `install.sh` steps on the harness being present.** Detect via
+   a well-known path (pi uses `~/.pi/agent/extensions/`). Skip silently on
+   machines without that harness. Never force-install.
+5. **Back up real files, never clobber.** If a destination exists and isn't
+   our symlink, `mv` it to `<path>.bak.YYYYMMDD-HHMMSS` before linking.
+6. **Probe, don't halt.** Any harness-specific env / config checks use
+   `warn` + `return 0`, never exit non-zero. Gate on evidence the user
+   actually opted into the affected path (e.g. AWS probe only fires if
+   `settings.json` selects `amazon-bedrock`).
+7. **Mirror in `--uninstall`.** Every symlink this repo creates must have
+   a matching removal step guarded by `link_if_into_repo`.
+8. **Update the root `README.md`** — add to the "What this repo contains"
+   list and to Setup with a one-line pointer to the extension's own README.
+9. **Update this file's Structure block** to list the new `extensions/<harness>/`
+   contents.
+
+See `extensions/pi/README.md` and the `install_pi_extension` /
+`install_pi_keybindings` / `check_pi_settings` / `check_aws_env` functions
+in `install.sh` for a full worked example.
+
 ## Testing
 
 Manual only. Integration-shaped: