docs(pi): full 'new machine' deploy recipe in extensions/pi/README

Consolidates the step-by-step recipe that's been living in diary entries
and session chat into the canonical pi bring-up doc. Covers:

  0. Prerequisites (zsh+oh-my-zsh, uv, tmux 3.2+, AWS creds)
  1. Dotfiles: myconfigs provision (tmux CSI-u, ~/.config/pi/.env, zsh loader)
  2. pi install (upstream brew/npm)
  3. mempalace CLI (uv tool install) + mempalace-toolkit install.sh
  4. pi settings bootstrap (start without --model, region prefix table)
  5. AWS env verification (git-crypt unlock gotcha)
  6. Opencode MCP registration pointer (if applicable)
  7. First run + wake-up injection smoke test
  + Verification checklist + uninstall

Root README.md adds a short summary box in the Setup section pointing at
the full recipe, so readers coming in from the front door find the pi
path immediately but the details stay with the files they install.

Covers: macOS + Linux. Works for homelab / work-macos / any myconfigs
profile that ships .config/pi/ + pi-env.zsh.

README.md

@@ -232,6 +232,29 @@ export PATH="$HOME/.local/bin:$PATH"
 
 **If `install.sh` reports `Skipping <name> — already exists`:** there's a leftover symlink or file at `~/.local/bin/<name>` from a previous install (e.g. the pre-split `cli_utils` days). The installer prints the exact `rm && ./install.sh` command to fix it — remove the stale entry and re-run. It will never clobber an existing file without the user explicitly removing it first.
 
+### 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.
+
+Quick summary:
+
+```bash
+# 1. Dotfiles (tmux extended-keys, ~/.config/pi/.env, pi-env.zsh)
+git clone <myconfigs> && cd myconfigs && ./provision.sh --profile <profile>
+
+# 2. pi (upstream)         3. mempalace CLI
+brew install pi-coding-agent    uv tool install mempalace
+
+# 4. This repo's install.sh
+cd ~/mempalace-toolkit && ./install.sh
+
+# 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
+
+# 6. Open fresh shell, run `pi`. Wake-up auto-injection proves end-to-end.
+```
+
 ### First mine
 
 ```bash

extensions/pi/README.md

@@ -10,6 +10,148 @@ 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`).
 
+**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