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.
refactor: split pi-generic config into pi-toolkit repo
2026-05-05 17:50:13 +02:00 · 2026-05-05 17:26:53 +02:00 · 2026-05-05 17:14:32 +02:00 · 2026-05-05 16:58:56 +02:00
6 changed files with 259 additions and 354 deletions
@@ -19,11 +19,9 @@ bin/
  mempalace-pi-session  # pi session → MemPalace bridge (bash + inline Python)
 contrib/                # systemd / launchd / cron templates for scheduling feeders
 extensions/
-  pi/                   # pi coding-agent bring-up: MCP bridge, keybindings, settings template
+  pi/                   # pi↔mempalace MCP bridge (bridge-only; pi's own config is in the pi-toolkit repo)
    mempalace.ts        # Symlinked into ~/.pi/agent/extensions/ (MCP <→ pi glue)
-    keybindings.json    # Symlinked into ~/.pi/agent/ (mosh/tmux newline fix)
-    settings.example.json # Template; user copies + edits (pi rewrites settings.json at runtime)
-    README.md           # Extension internals, schema-passthrough gotcha, env setup
+    README.md           # Bridge internals, Type.Unsafe gotcha, pi+mempalace deploy recipe
 ```

 ## What `install.sh` does
@@ -36,19 +34,25 @@ Idempotent, safe to re-run. Always:
 Gated on pi being installed (`~/.pi/agent/extensions/` exists):

 - Symlinks `extensions/pi/mempalace.ts` into `~/.pi/agent/extensions/`. Backs up any real file in the way.
- Symlinks `extensions/pi/keybindings.json` into `~/.pi/agent/`. Backs up any real file in the way.
- `settings.example.json` is **not** symlinked — pi rewrites `settings.json` at runtime, so we'd dirty the repo. Installer warns if `settings.json` is missing and prints the `cp` command.

 Probes (never halt, `warn` + `return 0`):

 - `~/.local/bin` is on `$PATH`.
 - `~/.config/opencode/instructions/mempalace.md` exists (opencode wake-up protocol).
 - `mempalace` is registered as an MCP server in `~/.config/opencode/opencode.json`.
- `~/.pi/agent/settings.json` exists (if pi is installed).
- `AWS_PROFILE`/`AWS_REGION` set, but only if `settings.json` exists *and* selects `amazon-bedrock`. Silent otherwise.
+- If pi is installed: pi-toolkit artifacts (`~/.pi/agent/keybindings.json` symlink, `~/.oh-my-zsh/custom/pi-env.zsh`) exist. Warns with a `git clone ssh://...pi-toolkit.git` pointer if missing.

 All non-destructive: if something is already in place and points into this repo, prints "already linked" and moves on. If a non-symlink real file is in the way, backs it up with a timestamp.

+**Not handled here any more** (split to [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) on 2026-05-05):
+
+- `keybindings.json` symlink into `~/.pi/agent/`
+- `pi-env.zsh` cp into `~/.oh-my-zsh/custom/`
+- `settings.example.json` template + `check_pi_settings` probe
+- `check_aws_env` probe
+
+Those are pi-generic concerns. This toolkit installs **only** the pi↔mempalace MCP bridge on top of whatever pi-toolkit set up.
+

 ## Conventions

@@ -75,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

@@ -8,13 +8,54 @@ Producer-side tooling for [MemPalace](https://github.com/MemPalace/mempalace)
 - `bin/mempalace-docs` — mines project directories into MemPalace while excluding source code, keeping the palace signal-dense.
 - [`ARCHITECTURE.md`](ARCHITECTURE.md) — **canonical spec**: architecture diagram, component details, setup recipe, operational notes, upstream-retirement roadmap.
 - [`SKILL.md`](SKILL.md) — the companion agent skill, symlinked into `~/.agents/skills/opencode-mempalace-bridge/` on install.
- [`extensions/pi/`](extensions/pi/) — pi coding-agent bridge: the MemPalace MCP extension (symlinked), a mosh/tmux-friendly keybindings file (symlinked), and a `settings.example.json` template for starting pi without `--model`. `install.sh` also probes for `AWS_PROFILE`/`AWS_REGION` (needed by pi's Bedrock provider) and points at the recommended `~/.config/pi/.env` layout if missing.
+- [`extensions/pi/`](extensions/pi/) — the pi↔mempalace MCP bridge (a TypeScript extension symlinked into `~/.pi/agent/extensions/`). Pi's own base config (keybindings, env loader, settings template) is in the sibling [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) repo — split out 2026-05-05 so `opencode-devbox` can build slim containers without mempalace.

 **If you're just trying to get this working on a new machine → jump to [Setup](#setup).**
 **If you want the full architecture story → read [`ARCHITECTURE.md`](ARCHITECTURE.md).**

 ---

+## 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:
@@ -234,25 +275,25 @@ export PATH="$HOME/.local/bin:$PATH"

 ### Deploying pi on a new machine (full recipe)

-If the target machine also runs [pi](https://github.com/mariozechner/pi-coding-agent), there's a longer multi-step recipe covering dotfiles provisioning (tmux CSI-u keys, `~/.config/pi/.env`, zsh loader), mempalace install, pi settings bootstrap (starting pi without `--model`), and the AWS env verification. It lives in **[`extensions/pi/README.md` § Deploying pi on a new machine](extensions/pi/README.md#deploying-pi-on-a-new-machine)** so the step-by-step stays next to the files it installs.
+If the target machine also runs [pi](https://github.com/mariozechner/pi-coding-agent), the recipe is: install [`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) first (pi's own base config), then this toolkit (adds the pi↔mempalace MCP bridge). Full step-by-step: **[`extensions/pi/README.md` § Deploying pi with mempalace on a new machine](extensions/pi/README.md#deploying-pi-with-mempalace-on-a-new-machine)**.

 Quick summary:

 ```bash
-# 1. Dotfiles (tmux extended-keys, ~/.config/pi/.env, pi-env.zsh)
+# 1. Dotfiles (tmux extended-keys, ~/.config/pi/.env, ...)
 git clone <myconfigs> && cd myconfigs && ./provision.sh --profile <profile>

-# 2. pi (upstream)         3. mempalace CLI
-brew install pi-coding-agent    uv tool install mempalace
+# 2. pi upstream          3. pi-toolkit (pi base config)
+brew install pi-coding-agent    git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git
+                                cd pi-toolkit && ./install.sh

-# 4. This repo's install.sh
-cd ~/mempalace-toolkit && ./install.sh
+# 4. settings bootstrap
+cp ~/pi-toolkit/settings.example.json ~/.pi/agent/settings.json && $EDITOR !$

-# 5. pi settings (one-time bootstrap, region-specific)
-cp extensions/pi/settings.example.json ~/.pi/agent/settings.json
-$EDITOR ~/.pi/agent/settings.json   # adjust eu./us./anthropic: prefix
+# 5. mempalace CLI        6. This repo (adds the bridge)
+uv tool install mempalace       cd ~/mempalace-toolkit && ./install.sh

-# 6. Open fresh shell, run `pi`. Wake-up auto-injection proves end-to-end.
+# 7. Open fresh shell, run `pi`. Wake-up auto-injection proves end-to-end.
 ```

 ### First mine
@@ -1,156 +1,23 @@
-# pi ↔ MemPalace extension
+# pi ↔ MemPalace MCP bridge

-The canonical source of `~/.pi/agent/extensions/mempalace.ts` — the bridge
-that wires the [MemPalace](https://github.com/MemPalace/mempalace) MCP
+The canonical source of `~/.pi/agent/extensions/mempalace.ts` — the TypeScript
+extension that wires [MemPalace](https://github.com/MemPalace/mempalace)'s MCP
 server into the [pi coding-agent](https://github.com/mariozechner/pi-coding-agent)
-harness.
+harness. Installs wake-up context injection, per-tool schema passthrough,
+and a `/mempalace-diary` slash-command.

-`install.sh` at the repo root symlinks `mempalace.ts` from this directory
-into `~/.pi/agent/extensions/` so the live file on every machine tracks
-version control. Works on macOS and Linux (the extension itself is plain
-Node / TypeScript; the symlink is a POSIX `ln -s`).
+This directory **only** holds the bridge. Pi's own base config (keybindings,
+environment loader, settings template) lives in the sibling
+[`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) repo — split out
+2026-05-05 so [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox)
+can build slim containers that include pi without dragging in mempalace's
+dependencies (~300 MB).

 **Jump to:**
- [Deploying pi on a new machine](#deploying-pi-on-a-new-machine) — step-by-step recipe.
- [Keybindings (mosh/tmux newline fix)](#keybindings-moshtmux-newline-fix)
- [Settings template](#settings-template-start-pi-without---model)
- [Environment setup](#environment-setup)
-
---
-
-## Deploying pi on a new machine
-
-Full recipe from a clean macOS or Linux box to a working pi+MemPalace
-install with all modifications shipped by this repo and by
-[`myconfigs`](https://gitea.jordbo.se/joakimp/myconfigs). Follow in order.
-
-### 0. Prerequisites
-
- Shell: **zsh + oh-my-zsh** (the env loader is `~/.oh-my-zsh/custom/pi-env.zsh`).
-  On bash-only hosts, adapt by sourcing `~/.config/pi/.env` from `~/.bashrc`.
- `git`, `node` ≥ 20, `uv` (for installing mempalace), `tmux` ≥ 3.2.
- AWS credentials reachable via `AWS_PROFILE` (either `aws configure sso`
-  cache or static keys in `~/.aws/credentials`) — **only if** you'll use
-  `amazon-bedrock` as pi's provider.
-
-### 1. Clone your dotfiles repo and provision
-
-Brings `~/.tmux.conf` with CSI-u extended keys, `~/.config/pi/.env`
-(git-crypt encrypted), and `~/.oh-my-zsh/custom/pi-env.zsh`:
-
-```bash
-git clone ssh://git@gitea.jordbo.se:2222/joakimp/myconfigs.git ~/src/src_local/myconfigs
-cd ~/src/src_local/myconfigs
-
-# Unlock git-crypt so ~/.config/pi/.env decrypts (skip on a box that has
-# never held your git-crypt key; see myconfigs/GIT-CRYPT.md to set up).
-git-crypt unlock ~/path/to/git-crypt-key
-
-# Provision — choose the profile matching the box (homelab, work-macos, ...).
-./provision.sh --dry-run --profile homelab   # preview
-./provision.sh --profile homelab             # apply
-```
-
-### 2. Install pi (upstream)
-
-```bash
-brew install pi-coding-agent          # macOS
-# or: follow https://github.com/mariozechner/pi-coding-agent for Linux
-```
-
-First run creates `~/.pi/agent/`.
-
-### 3. Install mempalace + the toolkit
-
-```bash
-# MemPalace CLI (isolated venv via uv, shim in ~/.local/bin)
-uv tool install mempalace
-
-# mempalace-toolkit (this repo) — the bin/ wrappers, the pi extension,
-# keybindings, settings template, and install probes.
-git clone ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git ~/mempalace-toolkit
-cd ~/mempalace-toolkit
-./install.sh
-```
-
-`install.sh` detects pi, symlinks `mempalace.ts` + `keybindings.json` into
-`~/.pi/agent/`, installs the companion skill, and runs five probes. The
-AWS probe stays quiet until step 4 selects `amazon-bedrock`.
-
-### 4. Bootstrap pi settings (start pi without `--model`)
-
-```bash
-cp ~/mempalace-toolkit/extensions/pi/settings.example.json \
-   ~/.pi/agent/settings.json
-$EDITOR ~/.pi/agent/settings.json
-```
-
-Adjust the inference-profile prefix to match your AWS region:
-
-| Region | Prefix | Example model ID |
-|---|---|---|
-| eu-west-1 | `eu.` | `eu.anthropic.claude-sonnet-4-6` |
-| us-east-1 | `us.` | `us.anthropic.claude-sonnet-4-6` |
-| non-Bedrock | (none) | `anthropic:claude-sonnet-4-6` |
-
-Run `pi --list-models` to confirm what your credentials can actually invoke.
-
-### 5. Ensure AWS env vars are live in your shell
-
-If you provisioned via step 1, `~/.config/pi/.env` exists and
-`~/.oh-my-zsh/custom/pi-env.zsh` sources it on every new shell. Verify:
-
-```bash
-exec zsh
-echo "$AWS_PROFILE  $AWS_REGION"   # should print your values
-```
-
-If empty, check that `~/.config/pi/.env` decrypted (`head ~/.config/pi/.env`
-should show plain text, not binary). `git-crypt unlock` in step 1 is the
-usual culprit when this is empty.
-
-### 6. Register mempalace MCP with opencode (if using opencode too)
-
-Skip if this box is pi-only. Otherwise see
-[root README § Registering mempalace with opencode](../../README.md#registering-mempalace-with-opencode-or-other-mcp-clients).
-
-### 7. First run
-
-```bash
-pi   # should start with the default model, no --model needed
-```
-
-Inside pi, the wake-up auto-injection should print a `mempalace-wakeup`
-system message with palace status and recent diary entries. If it doesn't,
-run `MEMPALACE_EXT_DEBUG=1 pi` to surface `mempalace-mcp` stderr.
-
-### Verification checklist
-
-```bash
-# Symlinks in place
-ls -la ~/.pi/agent/mempalace.ts ~/.pi/agent/keybindings.json   # → repo
-ls -la ~/.agents/skills/opencode-mempalace-bridge/SKILL.md      # → repo
-
-# Env loaded
-zsh -ic 'echo $AWS_PROFILE $AWS_REGION'
-
-# tmux extended keys
-tmux show-options -g | grep extended-keys   # csi-u
-
-# Palace reachable
-mempalace status
-
-# Installer re-run is idempotent
-cd ~/mempalace-toolkit && ./install.sh --yes   # all rows should say "already linked"
-```
-
-### Uninstall
-
-```bash
-cd ~/mempalace-toolkit && ./install.sh --uninstall --yes
-# Leaves mempalace CLI, pi binary, and ~/.config/pi/.env alone —
-# only removes symlinks this repo created.
-```
+- [What it does](#what-it-does)
+- [The `Type.Unsafe` gotcha](#the-typeunsafe-gotcha)
+- [Deploying pi with mempalace on a new machine](#deploying-pi-with-mempalace-on-a-new-machine)
+- [Fail-soft, identity, debugging](#fail-soft)

 ---

@@ -215,57 +82,113 @@ If you ever need to re-loosen the schema for debugging, fall back to
 the `Type.Object({}, { additionalProperties: true })` default only for
 that specific tool, not globally.

-## Keybindings (mosh/tmux newline fix)
+---

-`keybindings.json` is symlinked so edits flow through git. Default:
+## Deploying pi with mempalace on a new machine

-```json
-{
-  "tui.input.newLine": ["shift+enter", "ctrl+j", "alt+j"]
-}
-```
+This is the "pi + memory" recipe. For pi without mempalace, see
+[`pi-toolkit`'s README](https://gitea.jordbo.se/joakimp/pi-toolkit/src/branch/main/README.md#deploying-pi-on-a-new-machine).

-Rationale: when pi runs over `kitty → mosh → tmux`, shift+enter doesn't
-forward cleanly (mosh uses vt220-ish emulation, no kitty-keyboard-protocol
-or csi-u extended keys). `ctrl+j` and `alt+j` pass through as plain
-control/meta bytes and give you reliable newline insertion.
+### 0. Prerequisites

-## Settings template (start pi without `--model`)
+- Shell: zsh + oh-my-zsh recommended (both toolkits install loaders into
+  `~/.oh-my-zsh/custom/`; bash works too, installers print the manual
+  `source` snippet).
+- `git`, `node` ≥ 20, `uv`, `tmux` ≥ 3.2, pi installed upstream.
+- AWS credentials reachable via `AWS_PROFILE` — only if using
+  `amazon-bedrock` as pi's provider.

-`settings.example.json` is a template — **not symlinked**. pi rewrites
-its `settings.json` at runtime (`lastChangelogVersion` bumps on upgrade),
-which would dirty a symlinked repo file. Instead, bootstrap with:
+### 1. Dotfiles (if you keep one)
+
+Brings `~/.config/pi/.env` (AWS creds, git-crypt encrypted), tmux CSI-u
+extended keys, and other machine state:

 ```bash
-cp /path/to/mempalace-toolkit/extensions/pi/settings.example.json \
-   ~/.pi/agent/settings.json
-$EDITOR ~/.pi/agent/settings.json
+git clone <your-dotfiles> ~/src/dotfiles
+cd ~/src/dotfiles
+git-crypt unlock <key>
+./provision.sh --profile <profile>    # or your equivalent tool
 ```

-The Bedrock inference-profile prefix on model IDs (`eu.`, `us.`) is
-**region-specific** and must match `AWS_REGION` in `~/.config/pi/.env`.
-For a bare Anthropic provider (non-Bedrock) drop the prefix entirely
-and use `anthropic:claude-...`. Run `pi --list-models` to confirm what
-your credentials can actually invoke.
+### 2. Install pi upstream

-`install.sh` warns (non-fatal) if `settings.json` is missing.
-
-## Environment setup
-
-pi with `defaultProvider=amazon-bedrock` needs `AWS_PROFILE` and
-`AWS_REGION` exported into the shell that launches it. Recommended
-layout (matches the tor-ms22 dotfiles pattern):
-
-```
-~/.config/pi/.env               ← AWS_PROFILE=..., AWS_REGION=...
-                                  (git-crypt encrypted in dotfiles repo)
-~/.oh-my-zsh/custom/pi-env.zsh  ← set -a; source ~/.config/pi/.env; set +a
+```bash
+brew install pi-coding-agent       # macOS
+# or see https://github.com/mariozechner/pi-coding-agent for Linux
+pi --help                          # creates ~/.pi/agent/
 ```

-Historical note: these vars used to live under a `# Environment variables
-for pi` block inside `~/.config/opencode/.env`. Split out 2026-05-05 so
-each tool owns its own env file. `install.sh` runs a `check_aws_env`
-probe that warns if the vars are missing and points back here.
+### 3. Install pi-toolkit (base pi config)
+
+```bash
+git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git ~/pi-toolkit
+cd ~/pi-toolkit && ./install.sh
+```
+
+Symlinks `keybindings.json`, copies `pi-env.zsh` into
+`~/.oh-my-zsh/custom/`, and prints the `settings.json` bootstrap command.
+
+### 4. Bootstrap pi settings
+
+```bash
+cp ~/pi-toolkit/settings.example.json ~/.pi/agent/settings.json
+$EDITOR ~/.pi/agent/settings.json   # eu./us./anthropic: prefix
+```
+
+### 5. Install mempalace CLI + this toolkit
+
+```bash
+uv tool install mempalace
+git clone ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git ~/mempalace-toolkit
+cd ~/mempalace-toolkit && ./install.sh
+```
+
+Detects pi, symlinks `mempalace.ts` into `~/.pi/agent/extensions/`.
+Also detects pi-toolkit artifacts and prints a green check (or a warning
+telling you to install pi-toolkit first if you skipped step 3).
+
+### 6. Register mempalace MCP with opencode (if applicable)
+
+Skip if this box is pi-only. Otherwise:
+- Install [`opencode-toolkit`](https://gitea.jordbo.se/joakimp/opencode-toolkit) so `~/.config/opencode/.env` is sourced into every shell (GitHub / Gitea / other MCP server tokens).
+- Register the mempalace MCP server in `~/.config/opencode/opencode.json` — see [root README § Registering mempalace with opencode](../../README.md#registering-mempalace-with-opencode-or-other-mcp-clients).
+
+### 7. First run
+
+```bash
+exec zsh
+pi   # should start with defaults; wake-up injection shows palace status
+```
+
+If the wake-up doesn't print, run `MEMPALACE_EXT_DEBUG=1 pi` to surface
+`mempalace-mcp` stderr.
+
+### Verification checklist
+
+```bash
+# MCP bridge in place
+ls -la ~/.pi/agent/extensions/mempalace.ts    # → this repo
+
+# pi-toolkit artifacts also in place
+ls -la ~/.pi/agent/keybindings.json           # → pi-toolkit
+ls -la ~/.oh-my-zsh/custom/pi-env.zsh         # cp from pi-toolkit
+
+# Env loaded
+zsh -ic 'echo $AWS_PROFILE $AWS_REGION'
+
+# Palace reachable
+mempalace status
+```
+
+### Uninstall
+
+```bash
+cd ~/mempalace-toolkit && ./install.sh --uninstall --yes   # bridge only
+cd ~/pi-toolkit        && ./install.sh --uninstall --yes   # pi base config
+# Leaves pi itself, mempalace CLI, and ~/.config/pi/.env alone.
+```
+
+---

 ## File layout

@@ -273,13 +196,11 @@ probe that warns if the vars are missing and points back here.
 mempalace-toolkit/
 └── extensions/
    └── pi/
-        ├── README.md               ← this file
-        ├── mempalace.ts            ← symlinked into ~/.pi/agent/extensions/
-        ├── keybindings.json        ← symlinked into ~/.pi/agent/
-        └── settings.example.json   ← template; copy + edit into ~/.pi/agent/
+        ├── README.md        ← this file
+        └── mempalace.ts     ← symlinked into ~/.pi/agent/extensions/
 ```

-`install.sh` detects pi by probing for `~/.pi/agent/extensions/` and
-only creates symlinks when that directory exists. On machines without
-pi the files stay dormant in the repo. Re-runs are idempotent (same
-pattern as `bin/` and `SKILL.md`).
+Pi base config (keybindings, env loader, settings template) lives in
+[`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit). `install.sh`
+detects pi via `~/.pi/agent/extensions/` and runs a `check_pi_toolkit`
+probe that warns if pi-toolkit's artifacts are missing.
@@ -1,3 +0,0 @@
-{
-  "tui.input.newLine": ["shift+enter", "ctrl+j", "alt+j"]
-}
@@ -1,12 +0,0 @@
-{
-  "_comment": "Template for ~/.pi/agent/settings.json. Copy to that path and adjust for your region/account — this file is NOT symlinked by install.sh because pi rewrites settings.json at runtime (lastChangelogVersion bumps), which would dirty the repo. This template exists so a fresh machine can start pi without --model by copying + editing.",
-  "_comment_models": "The 'eu.' prefix on Bedrock model IDs is an inference-profile prefix tied to the AWS region. Must match AWS_REGION in ~/.config/pi/.env. For us-east use 'us.anthropic.*'; for bare Anthropic provider (non-Bedrock) use the raw 'anthropic:claude-*' IDs. Run `pi --list-models` to see what your credentials can actually invoke.",
-
-  "defaultProvider": "amazon-bedrock",
-  "defaultModel": "eu.anthropic.claude-sonnet-4-6",
-  "enabledModels": [
-    "eu.anthropic.claude-sonnet-4-6",
-    "eu.anthropic.claude-opus-4-7",
-    "eu.anthropic.claude-haiku-4-5-20251001-v1:0"
-  ]
-}
@@ -16,19 +16,13 @@ SKILL_SRC="${SCRIPT_DIR}/SKILL.md"
 SKILL_DEST_DIR="${HOME}/.agents/skills/opencode-mempalace-bridge"
 SKILL_DEST="${SKILL_DEST_DIR}/SKILL.md"

-# pi coding-agent extension (optional — only linked if pi is installed)
+# pi coding-agent MCP bridge extension (optional — only linked if pi is installed)
+# Pi-generic config (env loader, keybindings, settings template) lives in
+# the pi-toolkit repo; install it separately for the base pi bring-up.
 PI_EXT_SRC="${SCRIPT_DIR}/extensions/pi/mempalace.ts"
 PI_EXT_DEST_DIR="${HOME}/.pi/agent/extensions"
 PI_EXT_DEST="${PI_EXT_DEST_DIR}/mempalace.ts"

-# pi keybindings (generic mosh/tmux newline fix — safe on any machine)
-PI_KEYS_SRC="${SCRIPT_DIR}/extensions/pi/keybindings.json"
-PI_KEYS_DEST="${HOME}/.pi/agent/keybindings.json"
-
-# pi settings template (NOT symlinked — pi rewrites this file at runtime)
-PI_SETTINGS_EXAMPLE="${SCRIPT_DIR}/extensions/pi/settings.example.json"
-PI_SETTINGS_DEST="${HOME}/.pi/agent/settings.json"
-
 # ── args ─────────────────────────────────────────────
 ACTION="install"
 ASSUME_YES="no"
@@ -52,23 +46,22 @@ What install does:
    (auto-discovered by opencode; run agents-sync from cli_utils to also
    reach Claude Code and Kiro)
  - If pi (~/.pi/agent/extensions/) exists, symlinks extensions/pi/mempalace.ts
-    into ~/.pi/agent/extensions/mempalace.ts (pi bridge). Skipped otherwise.
-  - If pi exists, symlinks extensions/pi/keybindings.json into
-    ~/.pi/agent/keybindings.json (generic mosh/tmux newline fix).
-  - If pi exists, warns if ~/.pi/agent/settings.json is missing and points
-    at extensions/pi/settings.example.json as a template (NOT symlinked —
-    pi rewrites this file at runtime).
-  - Warns if AWS_PROFILE / AWS_REGION are unset (only relevant to users
-    whose pi settings.json selects amazon-bedrock as defaultProvider).
+    into ~/.pi/agent/extensions/mempalace.ts (the pi↔mempalace MCP bridge).
+    Skipped on machines without pi.
+  - Warns if pi is installed but pi-toolkit doesn't appear to be (i.e. the
+    keybindings, env loader, and settings template are missing). pi-toolkit
+    is a separate repo owning pi's own config: split out 2026-05-05.
+    Clone: ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git
  - Drops a .skill-source marker in the skill dir so sibling tooling
    (deploy-skills.sh, agents-sync.zsh) knows the dir is externally owned

 What uninstall does:
  - Removes symlinks in ~/.local/bin/ that point into this repo
  - Removes the skill symlink if it points into this repo
-  - Removes the pi extension symlink if it points into this repo
-  - Removes the pi keybindings symlink if it points into this repo
+  - Removes the pi↔mempalace MCP bridge symlink if it points into this repo
  - Removes the .skill-source marker and empty skill dir
+  - Does NOT touch pi-toolkit-owned artifacts (keybindings, env loader).
+    Run pi-toolkit/install.sh --uninstall for those.
 EOF
            exit 0 ;;
        *) echo "Unknown flag: $1" >&2; exit 2 ;;
@@ -273,77 +266,38 @@ install_pi_extension() {
    printf '        at startup only).\n'
 }

-install_pi_keybindings() {
-    # Generic mosh/tmux newline fix. Non-destructive: if a real
-    # keybindings.json exists we back it up rather than clobber.
-    [[ -d "$PI_EXT_DEST_DIR" ]] || return 0   # no pi → no keybindings

-    note "Linking pi keybindings → $PI_KEYS_DEST"
-    if [[ -e "$PI_KEYS_DEST" || -L "$PI_KEYS_DEST" ]]; then
-        if link_if_into_repo "$PI_KEYS_DEST"; then
-            ok "pi keybindings already linked"
-            return 0
-        fi
-        local backup="${PI_KEYS_DEST}.bak.$(date +%Y%m%d-%H%M%S)"
-        mv "$PI_KEYS_DEST" "$backup"
-        warn "Existing $PI_KEYS_DEST backed up to $backup"
-    fi
-    ln -s "$PI_KEYS_SRC" "$PI_KEYS_DEST"
-    ok "Linked keybindings.json → $PI_KEYS_SRC"
-}
+# ── Pi-toolkit detection ─────────────────────────────────────────
+# Pi-generic config (keybindings, settings template, shell env loader) lives
+# in the sibling pi-toolkit repo. This file used to own those; the split
+# happened 2026-05-05 so opencode-devbox can build slim containers that
+# include pi without dragging in mempalace. We don't install those artifacts
+# here — we only print a pointer when pi is detected but pi-toolkit isn't.
+check_pi_toolkit() {
+    [[ -d "$PI_EXT_DEST_DIR" ]] || return 0   # no pi → nothing to say

-# ── Verify ~/.pi/agent/settings.json exists ──────────────────────────
-# If pi is installed but settings.json is missing, `pi` refuses to start
-# without `--provider ... --model ...` on every invocation. The toolkit
-# ships extensions/pi/settings.example.json as a template with a working
-# Bedrock (eu-west-1) stanza — copy + edit for your region/account.
-#
-# NOT symlinked: pi rewrites settings.json at runtime (lastChangelogVersion
-# bumps on upgrade), which would dirty the repo and cause merge noise.
-# Template-only install is the right trade-off.
-check_pi_settings() {
-    [[ -d "$PI_EXT_DEST_DIR" ]] || return 0   # no pi → nothing to check
+    # Best-effort detection: pi-toolkit installs keybindings.json as a
+    # symlink and copies pi-env.zsh into ~/.oh-my-zsh/custom/. We don't
+    # know where the pi-toolkit repo is cloned, so just check whether the
+    # downstream artifacts exist.
+    local has_keys="no"
+    local has_env="no"
+    [[ -L "$HOME/.pi/agent/keybindings.json" ]] && has_keys="yes"
+    [[ -f "$HOME/.oh-my-zsh/custom/pi-env.zsh" ]] && has_env="yes"

-    if [[ -f "$PI_SETTINGS_DEST" ]]; then
-        ok "pi settings.json present at $PI_SETTINGS_DEST"
+    if [[ "$has_keys" == "yes" || "$has_env" == "yes" ]]; then
+        ok "pi-toolkit artifacts detected (keybindings=$has_keys env-loader=$has_env)"
        return 0
    fi

-    warn "pi settings.json NOT found at $PI_SETTINGS_DEST"
-    printf '       Without it, pi must be invoked with --provider/--model on every run.\n'
-    printf '       Bootstrap from the shipped template:\n'
-    printf '           cp %q %q\n' "$PI_SETTINGS_EXAMPLE" "$PI_SETTINGS_DEST"
-    printf '           $EDITOR %q   # adjust region prefix + model IDs\n' "$PI_SETTINGS_DEST"
-    printf '       See extensions/pi/README.md for the eu./us./anthropic: prefix rules.\n'
-    return 0
-}
-
-# ── Verify AWS env vars are present for Bedrock-backed pi ────────────
-# Only meaningful if pi's settings.json selects amazon-bedrock. We do a
-# best-effort grep rather than parsing JSON — false positives are cheap
-# (one extra probe) and the check is gated on pi being installed at all.
-check_aws_env() {
-    [[ -d "$PI_EXT_DEST_DIR" ]] || return 0   # no pi → nothing to check
-
-    # Only warn if settings.json selects amazon-bedrock. If pi uses a
-    # non-Bedrock provider (bare anthropic, openai, ...) AWS creds are
-    # irrelevant and this probe would be noise. If settings.json doesn't
-    # exist yet, check_pi_settings already told the user to bootstrap it
-    # — we can't know which provider they'll pick, so stay quiet here.
-    [[ -f "$PI_SETTINGS_DEST" ]] || return 0
-    grep -q '"amazon-bedrock"' "$PI_SETTINGS_DEST" 2>/dev/null || return 0
-
-    if [[ -n "${AWS_PROFILE:-}" && -n "${AWS_REGION:-}" ]]; then
-        ok "AWS env present (AWS_PROFILE=$AWS_PROFILE, AWS_REGION=$AWS_REGION)"
-        return 0
-    fi
-
-    warn "AWS_PROFILE and/or AWS_REGION not set in this shell"
-    printf '       pi with defaultProvider=amazon-bedrock needs both to invoke Bedrock.\n'
-    printf '       Recommended layout (matches the tor-ms22 dotfiles pattern):\n'
-    printf '           ~/.config/pi/.env              # AWS_PROFILE=..., AWS_REGION=...\n'
-    printf '           ~/.oh-my-zsh/custom/pi-env.zsh # set -a; source ~/.config/pi/.env; set +a\n'
-    printf '       See extensions/pi/README.md#environment-setup for the template.\n'
+    warn "pi detected but pi-toolkit doesn't appear installed"
+    printf '       pi-toolkit ships pi'"'"'s own config (keybindings, env loader,\n'
+    printf '       settings template) — formerly part of this repo, split out\n'
+    printf '       2026-05-05. Install it separately for the full pi bring-up:\n'
+    printf '           git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git\n'
+    printf '           cd pi-toolkit && ./install.sh\n'
+    printf '       This toolkit'"'"'s install still does the pi↔mempalace MCP bridge\n'
+    printf '       (mempalace.ts extension) regardless — that part is mempalace-side.\n'
    return 0
 }

@@ -357,7 +311,7 @@ do_install() {
    echo "   Symlink SKILL.md into $SKILL_DEST"
    if [[ -d "$PI_EXT_DEST_DIR" ]]; then
        echo "   Symlink extensions/pi/mempalace.ts into $PI_EXT_DEST"
-        echo "   Symlink extensions/pi/keybindings.json into $PI_KEYS_DEST"
+        echo "   (install pi-toolkit separately for keybindings + env loader + settings template)"
    fi
    echo
    confirm || { echo "Aborted."; exit 0; }
@@ -368,17 +322,13 @@ do_install() {
    echo
    install_pi_extension
    echo
-    install_pi_keybindings
-    echo
    check_path
    echo
    check_wake_up_protocol
    echo
    check_opencode_mcp
    echo
-    check_pi_settings
-    echo
-    check_aws_env
+    check_pi_toolkit
    echo
    ok "Done."
    echo
@@ -427,14 +377,9 @@ do_uninstall() {
        ok "No pi extension symlink to remove"
    fi

-    echo
-    note "Removing pi keybindings symlink"
-    if link_if_into_repo "$PI_KEYS_DEST"; then
-        rm "$PI_KEYS_DEST"
-        ok "Removed pi keybindings symlink"
-    else
-        ok "No pi keybindings symlink to remove"
-    fi
+    # Note: pi keybindings + pi-env.zsh loader are owned by pi-toolkit now
+    # (split 2026-05-05). Run `pi-toolkit/install.sh --uninstall` to remove
+    # those artifacts. We deliberately do not touch them here.

    # Remove the marker and the now-empty skill directory, but only if
    # the marker was written by us and the directory has nothing else in it.
Author	SHA1	Message	Date
joakimp	90e70fff61	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
joakimp	16915f0e55	refactor: split pi-generic config into pi-toolkit repo Parallel to the opencode-toolkit split earlier today. Pi's own config (keybindings, shell env loader, settings template) moves to a new sibling repo so opencode-devbox's mempalace opt-out can build slim containers that include pi without dragging in chromadb + embedding models (~300 MB). What moved to pi-toolkit (https://gitea.jordbo.se/joakimp/pi-toolkit): - extensions/pi/keybindings.json (mosh/tmux newline fix) - extensions/pi/pi-env.zsh (sources ~/.config/pi/.env) - extensions/pi/settings.example.json (Bedrock template) - install.sh::install_pi_keybindings (symlink step) - install.sh::install_pi_env_loader (cp step + bash fallback) - install.sh::check_pi_settings (probe) - install.sh::check_aws_env (probe) What stays here (this is the pi\u2194mempalace bridge, mempalace-side): - extensions/pi/mempalace.ts (the MCP extension) - install.sh::install_pi_extension (symlink step) - NEW: install.sh::check_pi_toolkit (probe: warns if pi is installed but pi-toolkit's artifacts are missing, with git-clone pointer) install.sh shrank from 520 to 403 lines. Uninstall mirror correctly does NOT touch pi-toolkit-owned files (explicit comment). Docs updated: - extensions/pi/README.md: rewritten as 'pi\u2194MemPalace MCP bridge', recipe becomes 'Deploying pi with mempalace' (pi-toolkit step 3, this repo step 5). - AGENTS.md: Structure block + 'What install.sh does' section reflect the narrower scope and list the four things that moved out. - README.md: repo-contents line + Setup section's deploy summary. Verified on tor-ms22: full install\u2192uninstall\u2192reinstall lifecycle clean. After mempalace-toolkit uninstall, pi-toolkit artifacts (~/.pi/agent/keybindings.json, ~/.oh-my-zsh/custom/pi-env.zsh) remain intact \u2014 correctly untouched. check_pi_toolkit probe fires green when both exist.	2026-05-05 17:26:53 +02:00
joakimp	3d3a0fb125	docs(pi): add opencode-toolkit pointer in deploy recipe step 6 Cross-reference the newly-extracted opencode-toolkit repo, which owns ~/.config/opencode/.env loading. The recipe now distinguishes between registering mempalace in opencode.json (still this repo's concern) and ensuring opencode's own env loader is in place (opencode-toolkit's).	2026-05-05 17:14:32 +02:00
joakimp	118bd20fec	feat(extensions/pi): ship pi-env.zsh shell loader The loader that sources ~/.config/pi/.env into every shell was only living in the myconfigs tor-ms22 backup \u2014 a fresh machine had nowhere to get it from except copying by hand. Now canonical here. - extensions/pi/pi-env.zsh: 20-line POSIX-compatible loader (set -a; source ~/.config/pi/.env; set +a). Works in bash and zsh. - install.sh install_pi_env_loader: * oh-my-zsh detected (~/.oh-my-zsh/custom/ exists) \u2192 cp into that dir (NOT symlink \u2014 that dir is typically part of a dotfiles backup, and a symlink to mempalace-toolkit would break when restored on another host). \u2192 Idempotent: if target content matches repo, says 'already installed'. If it differs, leaves user edits alone and points at diff for manual reconcile. * No oh-my-zsh \u2192 prints source-this-line snippet for ~/.zshrc or ~/.bashrc (derived from $SHELL). Does NOT auto-edit rc files. - install.sh uninstall: only removes the copy if content still matches repo. Local edits preserved. - Docs: * extensions/pi/README.md Environment setup section rewritten with both install paths, step 5 of deploy recipe updated. * AGENTS.md Structure block lists pi-env.zsh. * Root README repo-contents line mentions it. Verified on tor-ms22: install fresh \u2192 uninstall (content match \u2192 remove) \u2192 reinstall \u2192 zsh -ic loads AWS vars correctly. Also tested bash fallback path via HOME=/tmp/fake-home SHELL=/bin/bash \u2014 prints right .bashrc snippet.	2026-05-05 16:58:56 +02:00