diff --git a/README.md b/README.md index dd5ea07..c11c048 100644 --- a/README.md +++ b/README.md @@ -232,6 +232,29 @@ export PATH="$HOME/.local/bin:$PATH" **If `install.sh` reports `Skipping — already exists`:** there's a leftover symlink or file at `~/.local/bin/` 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 && cd myconfigs && ./provision.sh --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 diff --git a/extensions/pi/README.md b/extensions/pi/README.md index 2ef6dc1..c2d919e 100644 --- a/extensions/pi/README.md +++ b/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