Scaffold isolated Pi instance

README.md

@@ -0,0 +1,67 @@
+# Isolated Pi instance
+
+This directory is the user/config directory for an isolated [Pi coding agent](https://pi.dev) instance. The `launch` script sets `PI_CODING_AGENT_DIR` to this directory before invoking the installed `pi` executable.
+
+## Start Pi
+
+From this directory:
+
+```bash
+./launch
+```
+
+The launcher is relocatable and can be called while working in another project:
+
+```bash
+/path/to/kimiko-agent/launch
+```
+
+Pi keeps that project's working directory while storing this instance's credentials, settings, sessions, packages, and global resources here.
+
+To use the environment variable directly instead:
+
+```bash
+export PI_CODING_AGENT_DIR="$(pwd -P)"
+pi
+```
+
+To make the setting directory-local with `direnv`, create an untracked `.envrc` containing:
+
+```bash
+export PI_CODING_AGENT_DIR="$PWD"
+```
+
+## Authenticate and configure
+
+```text
+/login       Manage credentials; writes auth.json here
+/settings    Change common settings
+/model       Select a model
+```
+
+Or use provider API-key environment variables before starting Pi. `auth.json`, trust decisions, sessions, generated model metadata, and installed package contents are intentionally ignored by Git.
+
+## Layout
+
+- `settings.json` — instance-wide Pi settings
+- `models.json` — custom providers/models
+- `keybindings.json` — keybinding overrides
+- `extensions/` — global extensions for this instance
+- `skills/` — global skills for this instance
+- `prompts/` — global prompt templates for this instance
+- `themes/` — global themes for this instance
+- `sessions/` — generated conversation history
+- `npm/`, `git/` — Pi-managed package installations
+- `auth.json` — generated credentials (secret; never commit)
+- `trust.json` — generated project trust decisions
+
+Install a package into only this instance by using the launcher:
+
+```bash
+./launch install npm:<package>
+./launch list
+```
+
+## Isolation boundary
+
+`PI_CODING_AGENT_DIR` isolates Pi's user config, credentials, sessions, model config, and managed packages from `~/.pi/agent`. It is not an OS sandbox. Pi can still use inherited environment variables and shell/user configuration, and—when trusted—load project-local `.pi` resources. Pi also discovers the cross-agent global skill location `~/.agents/skills`; use `--no-skills` when you need to suppress all automatic skill discovery for a run.