docs: add Ecosystem diagram to README + update harness-extension conventions post-split

Two small doc updates consolidating the session's architectural arc: 1. README.md gets a new 'Ecosystem' section (after the contents list, before 'Why this exists') showing the five-repo composition: myconfigs -> opencode-toolkit + pi-toolkit -> mempalace-toolkit Plus an ownership table clarifying which scope lives where. The diagram makes the opt-out pattern visible \u2014 opencode-devbox's slim container path skips mempalace-toolkit and still gets a functional stack. 2. AGENTS.md 'Adding a new harness extension' section was still written for the pre-split extensions/pi/ which had keybindings.json + settings.example.json + pi-env.zsh. Rewrote to reflect: - Bridge-only scope (harness-generic config goes in <harness>-toolkit). - 'Probe for the sibling toolkit' step replaces the old symlink-keybindings and template-settings steps. - Worked example now points at install_pi_extension + check_pi_toolkit rather than the four functions that moved out. - Explicitly names the pattern: opencode-toolkit + pi-toolkit as the two existing examples of the sibling-toolkit convention.
2026-05-05 17:50:13 +02:00
parent 16915f0e55
commit 90e70fff61
2 changed files with 77 additions and 27 deletions
@@ -79,38 +79,47 @@ Three wrappers live happily as standalone scripts — no shared helper library y

 ## 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:
+`extensions/<harness>/` is the home for **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.
+2. **Bridge-only scope.** This toolkit owns the mempalace-side wiring;
+   harness-generic config (keybindings, env loaders, settings templates)
+   belongs in a sibling `<harness>-toolkit` repo, following the pattern
+   established by [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit)
+   and [`opencode-toolkit`](https://gitea.jordbo.se/joakimp/opencode-toolkit).
+   That boundary is load-bearing for `opencode-devbox`'s slim container
+   path (mempalace opt-out, ~300 MB saved).
+3. **A `README.md`** covering: what the bridge does, harness-specific
+   install path, debug knobs, and any gotchas (e.g. the pi `Type.Unsafe`
+   schema passthrough). May also hold the "Deploying <harness> with
+   mempalace" recipe since that straddles the two repos.
 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`).
+   a well-known path (pi uses `~/.pi/agent/extensions/`). Skip silently
+   on machines without that harness. Never force-install.
+5. **Symlink the bridge code.** `mempalace.ts` (or equivalent) gets
+   symlinked into the harness's extensions directory so edits flow
+   through git. Back up any pre-existing real file to
+   `<path>.bak.YYYYMMDD-HHMMSS` before linking.
+6. **Probe for the sibling toolkit.** After installing the bridge, check
+   whether the harness's own base config is in place (e.g. for pi-toolkit:
+   `~/.pi/agent/keybindings.json` symlink, `~/.oh-my-zsh/custom/pi-env.zsh`).
+   Warn with a `git clone` pointer if missing. `warn` + `return 0`, never
+   halt.
 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.
+   a matching removal step guarded by `link_if_into_repo`. Do **not**
+   touch sibling-toolkit-owned files — point the user at
+   `<harness>-toolkit/install.sh --uninstall` instead.
+8. **Update the root `README.md`** — repo-contents list + Ecosystem
+   diagram's "Who owns what" table + Setup section's deploy summary.
+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.
+See `extensions/pi/README.md` and the `install_pi_extension` +
+`check_pi_toolkit` functions in `install.sh` for a worked example.

 ## Testing

@@ -15,6 +15,47 @@ Producer-side tooling for [MemPalace](https://github.com/MemPalace/mempalace)

 ---

+## Ecosystem
+
+This repo is the memory-layer hub in a family of composable toolkits.
+Each `install.sh` is independent and idempotent; install only what you
+need. MemPalace can be opted out entirely (the `opencode-devbox` slim
+container path exercises this).
+
+```
+                 ┌──────────────────┐
+                 │     myconfigs    │  dotfiles: ~/.config/pi/.env, ~/.config/opencode/.env,
+                 └────────┬─────────┘  tmux CSI-u, zsh loaders, … (git-crypt encrypted)
+                          │ provision
+           ┌──────────────┼──────────────┐
+           ▼              ▼              ▼
+    ┌──────────┐   ┌──────────┐   ┌──────────────┐
+    │opencode- │   │pi-toolkit│   │ (pi/opencode │
+    │ toolkit  │   │          │   │  installed   │
+    │          │   │          │   │   upstream)  │
+    └─────┬────┘   └─────┬────┘   └──────────────┘
+         │              │
+         │ (optional)   │ (optional)
+         └──────┬───────┘
+                ▼
+       ┌─────────────────┐
+       │mempalace-toolkit│  ← this repo
+       └─────────────────┘     detects pi / opencode and installs bridges
+                                for whichever are present
+```
+
+Who owns what:
+
+| Repo | Scope |
+|---|---|
+| [`myconfigs`](https://gitea.jordbo.se/joakimp/myconfigs) | Dotfiles (git-crypt encrypted). Ships `.env` files each toolkit below sources. |
+| [`opencode-toolkit`](https://gitea.jordbo.se/joakimp/opencode-toolkit) | Opencode's own shell glue (env loader for `~/.config/opencode/.env`). No mempalace dep. |
+| [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) | Pi's own base config (keybindings, env loader, `settings.example.json`). No mempalace dep. |
+| **`mempalace-toolkit` (this)** | Memory layer. Mining wrappers in `bin/`, `opencode-mempalace-bridge` skill, pi↔mempalace MCP extension. Probes for the other toolkits' artifacts; installs bridges where relevant. |
+| [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox) | Docker containers that compose any subset via independent `install.sh` invocations. |
+
+---
+
 ## Why this exists

 MemPalace is the agent memory layer. Its stock CLI has two gaps that bite on a machine running opencode with a docs-first palace policy: