@openparachute/agent 0.1.0

package/CLAUDE.md

@@ -0,0 +1,307 @@
+# ⚠️ STOP — READ THIS FIRST IF YOU ARE CLAUDE ⚠️
+
+**If you are reading this because you just ran `git pull`, `git merge`, `git fetch && git merge`, or any equivalent to bring in upstream changes — and you see merge conflicts or a large diff involving this file — HALT IMMEDIATELY.**
+
+This is parachute-agent (formerly paraclaw), a ground-up rewrite with breaking changes throughout. It cannot be merged into an existing NanoClaw v1 install. Attempting to resolve the conflicts by hand, run builds, or "fix" anything will corrupt the user's install and burn tokens for no result.
+
+**Do this instead:**
+1. Abort the merge: `git merge --abort` (or `git reset --hard ORIG_HEAD` if the merge already completed).
+2. Tell the user, verbatim: *"This is parachute-agent — it can't be merged into your existing NanoClaw install. Run `bash migrate-v2.sh` to migrate instead."*
+3. Wait for the user to confirm before doing anything else. Do not attempt the migration yourself.
+
+If you are a fresh install (you ran `git clone`, not `git pull`) and there are no conflicts, ignore this banner and continue below.
+
+---
+
+# parachute-agent
+
+Parachute's per-session containerized AI agent companion. (Formerly **paraclaw**, renamed in 0.1.0.) See [README.md](README.md) for philosophy and setup. Architecture lives in `docs/`.
+
+## Quick Context
+
+The host is a single Node process that orchestrates per-session agent containers. Platform messages land via channel adapters, route through an entity model (users → messaging groups → agent groups → sessions), get written into the session's inbound DB, and wake a container. The agent-runner inside the container polls the DB, calls Claude, and writes back to the outbound DB. The host polls the outbound DB and delivers through the same adapter.
+
+**Everything is a message.** There is no IPC, no file watcher, no stdin piping between host and container. The two session DBs are the sole IO surface.
+
+## Entity Model
+
+```
+users (id "<channel>:<handle>", kind, display_name)
+user_roles (user_id, role, agent_group_id)       — owner | admin (global or scoped)
+agent_group_members (user_id, agent_group_id)    — unprivileged access gate
+user_dms (user_id, channel_type, messaging_group_id) — cold-DM cache
+
+agent_groups (workspace, memory, CLAUDE.md, personality, container config)
+    ↕ many-to-many via messaging_group_agents (session_mode, trigger_rules, priority)
+messaging_groups (one chat/channel on one platform; unknown_sender_policy)
+
+sessions (agent_group_id + messaging_group_id + thread_id → per-session container)
+```
+
+Privilege is user-level (owner/admin), not agent-group-level. See [docs/isolation-model.md](docs/isolation-model.md) for the three isolation levels (`agent-shared`, `shared`, separate agents).
+
+## Two-DB Session Split
+
+Each session has **two** SQLite files under `data/sessions/<agent_group_id>/<session_id>/`:
+
+- `inbound.db` — host writes, container reads. `messages_in`, routing, destinations, pending_questions, processing_ack.
+- `outbound.db` — container writes, host reads. `messages_out`, session_state.
+
+Exactly one writer per file — no cross-mount lock contention. Heartbeat is a file touch at `/workspace/.heartbeat`, not a DB update. Host uses even `seq` numbers, container uses odd.
+
+## Central DB
+
+`data/v2.db` holds everything that isn't per-session: users, user_roles, agent_groups, messaging_groups, wiring, pending_approvals, user_dms, chat_sdk_* (for the Chat SDK bridge), schema_version. Migrations live at `src/db/migrations/`.
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/index.ts` | Entry point: init DB, migrations, channel adapters, delivery polls, sweep, shutdown |
+| `src/router.ts` | Inbound routing: messaging group → agent group → session → `inbound.db` → wake |
+| `src/delivery.ts` | Polls `outbound.db`, delivers via adapter, handles system actions (schedule, approvals, etc.) |
+| `src/host-sweep.ts` | 60s sweep: `processing_ack` sync, stale detection, due-message wake, recurrence |
+| `src/session-manager.ts` | Resolves sessions; opens `inbound.db` / `outbound.db`; manages heartbeat path |
+| `src/container-runner.ts` | Spawns per-agent-group Docker containers with session DB + outbox mounts, decrypts + injects assigned secrets |
+| `src/container-runtime.ts` | Runtime selection (Docker vs Apple containers), orphan cleanup |
+| `src/modules/permissions/access.ts` | `canAccessAgentGroup` — owner / global admin / scoped admin / member resolution against `user_roles` + `agent_group_members` |
+| `src/modules/approvals/primitive.ts` | `pickApprover`, `pickApprovalDelivery`, `requestApproval`, approval-handler registry |
+| `src/command-gate.ts` | Router-side admin command gate — queries `user_roles` directly (no env var, no container-side check) |
+| `src/secrets/` | AES-GCM secret store: master key on disk + ciphertext in central DB, scoped per agent group |
+| `src/user-dm.ts` | Cold-DM resolution + `user_dms` cache |
+| `src/group-init.ts` | Per-agent-group filesystem scaffold (CLAUDE.md, skills, agent-runner-src overlay) |
+| `src/db/` | DB layer — agent_groups, messaging_groups, sessions, user_roles, user_dms, pending_*, migrations |
+| `src/channels/` | Channel adapter infra (registry, Chat SDK bridge) plus the trunk-baked Discord and Telegram adapters; other channels are skill-installed from the `channels` branch |
+| `src/providers/` | Host-side provider container-config (`claude` baked in; `opencode` etc. installed from the `providers` branch) |
+| `container/agent-runner/src/` | Agent-runner: poll loop, formatter, provider abstraction, MCP tools, destinations |
+| `container/skills/` | Container skills mounted into every agent session |
+| `groups/<folder>/` | Per-agent-group filesystem (CLAUDE.md, skills, per-group `agent-runner-src/` overlay) |
+| `scripts/init-first-agent.ts` | Bootstrap the first DM-wired agent (used by `/init-first-agent` skill) |
+
+## Channels and Providers
+
+Trunk bakes in the two adapters needed for the `/channels/new` fast path — **Discord** (`src/channels/discord.ts`) and **Telegram** (`src/channels/telegram.ts`) — along with their token validators (`src/web/{discord,telegram}-validate.ts`) and the `POST /api/channels/{adapter}/test` route. Anything else lives on long-lived sibling branches and is copied in by skills:
+
+- **`channels` branch** — Slack, WhatsApp, Teams, Linear, GitHub, iMessage, Webex, Resend, Matrix, Google Chat, WhatsApp Cloud (+ helpers, tests, channel-specific setup steps). Installed via `/add-<channel>` skills.
+- **`providers` branch** — OpenCode (and any future non-default agent providers). Installed via `/add-opencode`.
+
+Each `/add-<name>` skill is idempotent: `git fetch origin <branch>` → copy module(s) into the standard paths → append a self-registration import to the relevant barrel → `pnpm install <pkg>@<pinned-version>` → build.
+
+## Self-Modification
+
+One tier of agent self-modification today:
+
+1. **`install_packages` / `add_mcp_server`** — changes to the per-agent-group container config only (apt/npm deps, wire an existing MCP server). Single admin approval per request; on approve, the handler in `src/modules/self-mod/apply.ts` rebuilds the image when needed (`install_packages` only) and restarts the container. `container/agent-runner/src/mcp-tools/self-mod.ts`.
+
+A second tier (direct source-level self-edits via a draft/activate flow) is planned but not yet implemented.
+
+## Secrets / Credentials
+
+parachute-agent owns its credential store. API keys, OAuth tokens, and auth credentials are stored locally as AES-GCM ciphertext in the central DB, with the master key at `~/.parachute/agent/master.key` (chmod 0600, generated on first boot — pre-0.1.0 installs auto-migrate from `~/.parachute/claw/master.key` on startup). Code in `src/secrets/` decrypts the rows assigned to a given agent group at container spawn and injects them as env vars; nothing goes through chat context.
+
+Surfaces:
+- **Web UI** — `/agent/secrets` lists, creates, updates, deletes secrets and assigns them to agent groups (mirrors the `selective` / `all` allow-list semantics).
+- **HTTP API** — `/api/secrets` (GET / POST / PATCH / DELETE) is the same code path the UI uses; scope-gated by `agent:admin`.
+- **Per-agent assignment** — every secret carries `assigned_mode` (`all` = injected into every group; `selective` = injected only into groups in `secret_assignments`).
+
+### Approval-gated credential use
+
+Approval flows for credential use are parachute-agent-native: a module (or self-mod handler) calls `requestApproval()` from `src/modules/approvals/primitive.ts`, which persists a `pending_approvals` row, picks an approver via `pickApprover` (scoped admins → global admins → owners, all from `user_roles` in the central DB), and routes a card via `pickApprovalDelivery`. The approver decides via either the chat card or `POST /api/approvals/:id/decide` from the UI; both go through `handleApprovalsResponse`.
+
+## Skills
+
+Four types of skills. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full taxonomy.
+
+- **Channel/provider install skills** — copy the relevant module(s) in from the `channels` or `providers` branch, wire imports, install pinned deps (e.g. `/add-discord`, `/add-slack`, `/add-whatsapp`, `/add-opencode`).
+- **Utility skills** — ship code files alongside `SKILL.md` (e.g. `/claw`).
+- **Operational skills** — instruction-only workflows (`/debug`, `/customize`, `/update-nanoclaw`).
+- **Container skills** — loaded inside agent containers at runtime (`container/skills/`: `welcome`, `self-customize`, `agent-browser`, `slack-formatting`).
+
+| Skill | When to Use |
+|-------|-------------|
+| `/customize` | Adding channels, integrations, behavior changes |
+| `/debug` | Container issues, logs, troubleshooting |
+| `/update-nanoclaw` | Bring upstream updates into a customized install |
+
+## MCP server
+
+parachute-agent exposes its host-side admin surface (the things `/api/*` and `/agent/*` mediate from the web UI: agent-groups, sessions, channel wires, secrets metadata, approvals) as MCP tools. The same registry serves both transports — handlers call internal helpers directly, not back through HTTP, so there's no extra round-trip and no second auth seam to keep in sync.
+
+| Transport | Endpoint | Auth | Effective scope |
+|-----------|----------|------|-----------------|
+| stdio | `bun src/mcp/stdio.ts` | ambient (filesystem trust) | `agent:admin` |
+| HTTP  | `POST /mcp` on port 1944 | hub-issued JWT (`Authorization: Bearer …`) | strongest `agent:*` scope on the JWT grant (legacy `claw:*` grants normalize to `agent:*` through 0.1.x) |
+
+Wire stdio into Claude Code:
+
+```bash
+claude mcp add parachute-agent bun /absolute/path/to/parachute-agent/src/mcp/stdio.ts
+```
+
+Tools advertise as `mcp__parachute_agent__<verb>-<noun>` client-side: `list-agent-groups`, `create-agent-group`, `attach-vault`, `detach-vault`, `list-sessions`, `close-session`, `list-channels`, `update-channel-wire`, `delete-channel-wire`, `list-secrets`, `put-secret`, `delete-secret`, `assign-secret`, `list-approvals`, `decide-approval`, `get-activity`. The remaining stubs (`start-oauth`, `revoke-integration`) are advertised but `disabled` until the matching server endpoints land — they're filtered out of `tools/list` and refused on `tools/call`.
+
+Secret values **never** traverse MCP. `list-secrets` and `put-secret` return row metadata only; the plaintext flows in once on `put-secret` and lands in the encrypted DB column. Container injection happens at session-spawn time, not over the tool surface.
+
+Stdio gotcha: parachute-agent's `log.ts` writes info-level messages to `process.stdout`, which corrupts JSON-RPC frames. `src/mcp/stdio.ts` promotes `LOG_LEVEL` to `warn` before any log-using import. Don't move that block below the dynamic imports.
+
+## Contributing
+
+Before creating a PR, adding a skill, or preparing any contribution, you MUST read [CONTRIBUTING.md](CONTRIBUTING.md). It covers accepted change types, the four skill types and their guidelines, `SKILL.md` format rules, and the pre-submission checklist.
+
+## Development
+
+Run commands directly — don't tell the user to run them.
+
+```bash
+# Host (Node + pnpm)
+pnpm run dev          # Host with hot reload
+pnpm run build        # Compile host TypeScript (src/)
+./container/build.sh  # Rebuild agent container image (parachute-agent-image-<slug>:latest)
+pnpm test             # Host tests (vitest)
+
+# Agent-runner (Bun — separate package tree under container/agent-runner/)
+cd container/agent-runner && bun install   # After editing agent-runner deps
+cd container/agent-runner && bun test      # Container tests (bun:test)
+```
+
+Container typecheck is a separate tsconfig — if you edit `container/agent-runner/src/`, run `pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit` from root (or `bun run typecheck` from `container/agent-runner/`).
+
+Service management is owned by the hub install path (`parachute install parachute-agent`), which generates the launchd plist / systemd unit. Existing pre-0.1.0 installs still use the old `computer.parachute.claw-<slug>` / `paraclaw-<slug>` labels until the operator re-runs the hub installer; the new label is `computer.parachute.agent-<slug>` / `parachute-agent-<slug>`. Substitute `<slug>` with the 8-char hash from `getInstallSlug()` — each checkout gets its own service so two installs on one host don't collide:
+```bash
+# macOS (launchd)
+launchctl load   ~/Library/LaunchAgents/computer.parachute.agent-<slug>.plist
+launchctl unload ~/Library/LaunchAgents/computer.parachute.agent-<slug>.plist
+launchctl kickstart -k gui/$(id -u)/computer.parachute.agent-<slug>  # restart
+
+# Linux (systemd)
+systemctl --user start|stop|restart parachute-agent-<slug>
+```
+
+Host logs: `logs/parachute-agent.log` (normal) and `logs/parachute-agent.error.log` (errors only — some delivery/approval failures only show up here). On 0.1.0 first boot, any pre-existing `logs/paraclaw{,.error}.log` are renamed in place so the historical file stays accessible under the new name. The supervisor unit (launchd plist / systemd unit, generated by `parachute install parachute-agent`) is what controls *where new entries are written*; until the operator re-runs the installer, the supervisor still routes stdout to `paraclaw.log` and a fresh file is recreated under the legacy name on each daemon respawn. Re-running the installer regenerates the unit so subsequent boots write to `parachute-agent.log`.
+
+## Supply Chain Security (pnpm)
+
+This project uses pnpm with `minimumReleaseAge: 4320` (3 days) in `pnpm-workspace.yaml`. New package versions must exist on the npm registry for 3 days before pnpm will resolve them.
+
+**Rules — do not bypass without explicit human approval:**
+- **`minimumReleaseAgeExclude`**: Never add entries without human sign-off. If a package must bypass the release age gate, the human must approve and the entry must pin the exact version being excluded (e.g. `package@1.2.3`), never a range.
+- **`onlyBuiltDependencies`**: Never add packages to this list without human approval — build scripts execute arbitrary code during install.
+- **`pnpm install --frozen-lockfile`** should be used in CI, automation, and container builds. Never run bare `pnpm install` in those contexts.
+
+## Docs Index
+
+| Doc | Purpose |
+|-----|---------|
+| [docs/architecture.md](docs/architecture.md) | Full architecture writeup |
+| [docs/api-details.md](docs/api-details.md) | Host API + DB schema details |
+| [docs/db.md](docs/db.md) | DB architecture overview: three-DB model, cross-mount rules, readers/writers map |
+| [docs/db-central.md](docs/db-central.md) | Central DB (`data/v2.db`) — every table + migration system |
+| [docs/db-session.md](docs/db-session.md) | Per-session `inbound.db` + `outbound.db` schemas + seq parity |
+| [docs/agent-runner-details.md](docs/agent-runner-details.md) | Agent-runner internals + MCP tool interface |
+| [docs/isolation-model.md](docs/isolation-model.md) | Three-level channel isolation model |
+| [docs/setup-wiring.md](docs/setup-wiring.md) | What's wired, what's open in the setup flow |
+| [docs/architecture-diagram.md](docs/architecture-diagram.md) | Diagram version of the architecture |
+| [docs/build-and-runtime.md](docs/build-and-runtime.md) | Runtime split (Node host + Bun container), lockfiles, image build surface, CI, key invariants |
+
+## Container Build Cache
+
+The container buildkit caches the build context aggressively. `--no-cache` alone does NOT invalidate COPY steps — the builder's volume retains stale files. To force a truly clean rebuild, prune the builder then re-run `./container/build.sh`.
+
+## Container Runtime (Bun)
+
+The agent container runs on **Bun**; the host runs on **Node** (pnpm). They communicate only via session DBs — no shared modules. Details and rationale: [docs/build-and-runtime.md](docs/build-and-runtime.md).
+
+**Gotchas — trigger + action:**
+
+- **Adding or bumping a runtime dep in `container/agent-runner/`** → edit `package.json`, then `cd container/agent-runner && bun install` and commit the updated `bun.lock`. Do not run `pnpm install` there — agent-runner is not a pnpm workspace.
+- **Bumping `@anthropic-ai/claude-agent-sdk`, `@modelcontextprotocol/sdk`, or any agent-runner runtime dep** → no `minimumReleaseAge` policy applies to this tree. Check the release date on npm, pin deliberately, never `bun update` blindly.
+- **Writing a new named-param SQL insert/update in the container** → use `$name` in both SQL and JS keys: `.run({ $id: msg.id })`. `bun:sqlite` does not auto-strip the prefix the way `better-sqlite3` does on the host. Positional `?` params work normally.
+- **Adding a test in `container/agent-runner/src/`** → import from `bun:test`, not `vitest`. Vitest runs on Node and can't load `bun:sqlite`. `vitest.config.ts` excludes this tree.
+- **Adding a Node CLI the agent invokes at runtime** (like `agent-browser`, `claude-code`, `vercel`) → put it in the Dockerfile's pnpm global-install block, pinned to an exact version via a new `ARG`. Don't use `bun install -g` — that bypasses the pnpm supply-chain policy.
+- **Changing the Dockerfile entrypoint or the dynamic-spawn command** (`src/container-runner.ts` line ~301) → keep `exec bun ...` so signals forward cleanly. The image has no `/app/dist`; don't reintroduce a tsc build step.
+- **Changing session-DB pragmas** (`container/agent-runner/src/db/connection.ts`) → `journal_mode=DELETE` is load-bearing for cross-mount visibility. Read the comment block at the top of the file first.
+
+## Web UI (mount-aware)
+
+The parachute-agent SPA in `web/ui/` is served at the origin root in dev (`/`) and under a mount prefix in prod (`/agent/` when running behind the parachute hub on tailnet). The hub owns `/`; an absolute `/api/...` from the browser goes to the hub origin, NOT parachute-agent — and the hub 404s on it. Anything the bundle sends to parachute-agent must include the mount prefix.
+
+**Rule:** every URL the UI builds for `fetch`, router basenames, or OAuth redirects must be derived from `import.meta.env.BASE_URL`, not hardcoded with a leading `/`. Same bundle has to work whether the deploy lands at `/`, `/agent/`, or `/some/other/mount/`.
+
+Pattern (BASE_URL has a trailing slash; trim it for joining):
+
+```ts
+const API_BASE = `${import.meta.env.BASE_URL.replace(/\/$/, "")}/api`;
+const cb       = `${window.location.origin}${import.meta.env.BASE_URL}oauth/callback`;
+<BrowserRouter basename={import.meta.env.BASE_URL.replace(/\/$/, "")}>
+```
+
+The server-side mirror lives in `web/server/src/server.ts`: `MOUNT` (from `PARACHUTE_AGENT_WEB_MOUNT`, with legacy `PARACLAW_WEB_MOUNT` accepted through 0.1.x) is stripped uniformly before dispatch so `/api/*` and static-serve both see paths without the prefix.
+
+### SPA build is wired into install
+
+`web/ui/dist/` is gitignored. The root `package.json` runs `build:spa` from a `postinstall` hook so a fresh `pnpm install` produces a working `/agent/*` without a manual rebuild step. If `static-serve` 503s with "UI bundle not found", the install most likely fired with `--ignore-scripts` (which suppresses `postinstall` lifecycle hooks) — fall back to `pnpm run build:spa` to rebuild manually.
+
+## CJK font support
+
+Agent containers ship without CJK fonts by default (~200MB saved). If you notice signals the user works with Chinese/Japanese/Korean content — conversing in CJK, CJK timezone (e.g., `Asia/Tokyo`, `Asia/Shanghai`, `Asia/Seoul`, `Asia/Taipei`, `Asia/Hong_Kong`), system locale hint, or mentions of needing to render CJK in screenshots/PDFs/scraped pages — offer to enable it:
+
+```bash
+# Ensure .env has INSTALL_CJK_FONTS=true (overwrite or append)
+grep -q '^INSTALL_CJK_FONTS=' .env && sed -i.bak 's/^INSTALL_CJK_FONTS=.*/INSTALL_CJK_FONTS=true/' .env && rm -f .env.bak || echo 'INSTALL_CJK_FONTS=true' >> .env
+
+# Rebuild and restart so new sessions pick up the new image
+./container/build.sh
+launchctl kickstart -k gui/$(id -u)/computer.parachute.agent-<slug>  # macOS
+# systemctl --user restart parachute-agent-<slug>                     # Linux
+```
+
+`container/build.sh` reads `INSTALL_CJK_FONTS` from `.env` and passes it through as a Docker build-arg. Without CJK fonts, Chromium-rendered screenshots and PDFs containing CJK text show tofu (empty rectangles) instead of characters.
+
+## ⚠ Sandbox isolation — DO NOT clobber the live install
+
+If you spin a parachute-agent sandbox **on the same host as a live install**, three things must be different from the live install or you will reap its containers and clobber its DB. This bit Aaron once (paraclaw#91); guard against repeating it.
+
+### What collides
+
+| Atom | Default | Why a same-host sandbox collides |
+|------|---------|----------------------------------|
+| `INSTALL_SLUG` | `sha1(cwd)[:8]` | Same project root → same slug → `cleanupOrphans` reaps live containers via the `parachute-agent-install=<slug>` label (and the legacy `paraclaw-install=<slug>` label, reaped through 0.1.x) |
+| Central DB + `master.key` | `~/.parachute/agent/` | Both installs share the operator-owned home dir |
+| Webhook port | `WEBHOOK_PORT` (default 3000) | Two listeners on one port → `EADDRINUSE` |
+| Web port | `PARACHUTE_AGENT_WEB_PORT` (default 1944) | Same. Legacy `PARACLAW_WEB_PORT` accepted through 0.1.x with a deprecation warning |
+
+### Safe sandbox pattern
+
+```bash
+# 1. New cwd → new INSTALL_SLUG. Use a worktree, not a fresh checkout —
+#    same-branch state, isolated filesystem.
+git worktree add /tmp/parachute-agent-sandbox <branch>
+cd /tmp/parachute-agent-sandbox
+
+# 2. Fresh PARACHUTE_HOME → fresh DB + fresh master.key. PARACHUTE_HOME is
+#    the canonical override (parachute-hub, vault, scribe all honor it);
+#    parachute-agent joined the convention as paraclaw#91. Both atoms
+#    reroute together so the sandbox's encrypted-secret reads stay
+#    self-consistent.
+export PARACHUTE_HOME=/tmp/parachute-agent-sandbox-home
+
+# 3. Different ports — pick anything free. Don't rely on default 1944/3000.
+export PARACHUTE_AGENT_WEB_PORT=2944
+export WEBHOOK_PORT=3944
+
+# 4. Bootstrap state programmatically (init-first-agent / API). Don't
+#    copy the live DB — defeats the isolation.
+pnpm install
+pnpm run dev
+```
+
+### Don't do
+
+- `cd <live-parachute-agent>` and run sandbox there with overrides — same INSTALL_SLUG, `cleanupOrphans` reaps live containers regardless of DB-path overrides.
+- Override only `PARACHUTE_AGENT_CENTRAL_DB_PATH` — `master.key` still lands at `~/.parachute/agent/master.key` if `PARACHUTE_HOME` is unset, and you'll cross-decrypt against the live key.
+- Set `HOME=/tmp/...` instead of `PARACHUTE_HOME` — affects every other tool's home-dir lookup. parachute-agent honors HOME for ergonomic compat, but `PARACHUTE_HOME` is the precise knob for "reroute parachute-agent's persistent state."
+- Combine `PARACHUTE_HOME` with `PARACHUTE_AGENT_CENTRAL_DB_PATH` unless you understand the split — the DB lands at the explicit override path but `master.key` still follows `PARACHUTE_HOME` (sits at `<PARACHUTE_HOME>/agent/master.key`). Exporting just the DB file alone yields unreadable ciphertext on the receiving side. The split is intentional — the override lets you put the DB on a different volume — but the two atoms only travel together when you let both default off `PARACHUTE_HOME`.
+
+### After the sandbox
+
+`git worktree remove /tmp/parachute-agent-sandbox && rm -rf /tmp/parachute-agent-sandbox-home` cleans up. Containers tagged with the sandbox's INSTALL_SLUG won't conflict with the live install's, but a long-lived sandbox accumulates them — `docker ps -a --filter label=parachute-agent-install=<sandbox-slug>` to see what's left.

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+community@nanoclaw.dev.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior,  harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+https://www.contributor-covenant.org/version/2/0/code_of_conduct.html.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq. Translations are available at
+https://www.contributor-covenant.org/translations.

package/CONTRIBUTING.md

@@ -0,0 +1,159 @@
+# Contributing
+
+## Before You Start
+
+1. **Check for existing work.** Search open PRs and issues before starting:
+   ```bash
+   gh pr list --repo ParachuteComputer/paraclaw --search "<your feature>"
+   gh issue list --repo ParachuteComputer/paraclaw --search "<your feature>"
+   ```
+   If a related PR or issue exists, build on it rather than duplicating effort.
+
+2. **Check alignment.** Read the [Philosophy section in README.md](README.md#philosophy). Source code changes should only be things 90%+ of users need. Skills can be more niche, but should still be useful beyond a single person's setup.
+
+3. **One thing per PR.** Each PR should do one thing — one bug fix, one skill, one simplification. Don't mix unrelated changes in a single PR.
+
+## Source Code Changes
+
+**Accepted:** Bug fixes, security fixes, simplifications, reducing code.
+
+**Not accepted:** Features, capabilities, compatibility, enhancements. These should be skills.
+
+## Skills
+
+parachute-agent uses [Claude Code skills](https://code.claude.com/docs/en/skills) — markdown files with optional supporting files that teach Claude how to do something. There are four types of skills in parachute-agent, each serving a different purpose.
+
+### Why skills?
+
+Every user should have clean and minimal code that does exactly what they need. Skills let users selectively add features to their fork without inheriting code for features they don't want.
+
+### Skill types
+
+#### 1. Feature skills (branch-based)
+
+Add capabilities to parachute-agent by merging a git branch. The SKILL.md contains setup instructions; the actual code lives on a `skill/*` branch.
+
+**Location:** `.claude/skills/` on `main` (instructions only), code on `skill/*` branch
+
+**Examples:** `/add-telegram`, `/add-slack`, `/add-discord`, `/add-gmail`
+
+**How they work:**
+1. User runs `/add-telegram`
+2. Claude follows the SKILL.md: fetches and merges the `skill/telegram` branch
+3. Claude walks through interactive setup (env vars, bot creation, etc.)
+
+**Contributing a feature skill:**
+1. Fork `ParachuteComputer/paraclaw` and branch from `main`
+2. Make the code changes (new files, modified source, updated `package.json`, etc.)
+3. Add a SKILL.md in `.claude/skills/<name>/` with setup instructions — step 1 should be merging the branch
+4. Open a PR. We'll create the `skill/<name>` branch from your work
+
+See `/add-telegram` for a good example. See [docs/skills-as-branches.md](docs/skills-as-branches.md) for the full system design.
+
+#### 2. Utility skills (with code files)
+
+Standalone tools that ship code files alongside the SKILL.md. The SKILL.md tells Claude how to install the tool; the code lives in the skill directory itself (e.g. in a `scripts/` subfolder).
+
+**Location:** `.claude/skills/<name>/` with supporting files
+
+**Examples:** `/claw` (Python CLI in `scripts/claw`)
+
+**Key difference from feature skills:** No branch merge needed. The code is self-contained in the skill directory and gets copied into place during installation.
+
+**Guidelines:**
+- Put code in separate files, not inline in the SKILL.md
+- Use `${CLAUDE_SKILL_DIR}` to reference files in the skill directory
+- SKILL.md contains installation instructions, usage docs, and troubleshooting
+
+#### 3. Operational skills (instruction-only)
+
+Workflows and guides with no code changes. The SKILL.md is the entire skill — Claude follows the instructions to perform a task.
+
+**Location:** `.claude/skills/` on `main`
+
+**Examples:** `/setup`, `/debug`, `/customize`, `/update-skills`
+
+**Guidelines:**
+- Pure instructions — no code files, no branch merges
+- Use `AskUserQuestion` for interactive prompts
+- These stay on `main` and are always available to every user
+
+#### 4. Container skills (agent runtime)
+
+Skills that run inside the agent container, not on the host. These teach the container agent how to use tools, format output, or perform tasks. They are synced into each group's `.claude/skills/` directory when a container starts.
+
+**Location:** `container/skills/<name>/`
+
+**Examples:** `agent-browser` (web browsing), `capabilities` (/capabilities command), `status` (/status command), `slack-formatting` (Slack mrkdwn syntax)
+
+**Key difference:** These are NOT invoked by the user on the host. They're loaded by Claude Code inside the container and influence how the agent behaves.
+
+**Guidelines:**
+- Follow the same SKILL.md + frontmatter format
+- Use `allowed-tools` frontmatter to scope tool permissions
+- Keep them focused — the agent's context window is shared across all container skills
+
+### SKILL.md format
+
+All skills use the [Claude Code skills standard](https://code.claude.com/docs/en/skills):
+
+```markdown
+---
+name: my-skill
+description: What this skill does and when to use it.
+---
+
+Instructions here...
+```
+
+**Rules:**
+- Keep SKILL.md **under 500 lines** — move detail to separate reference files
+- `name`: lowercase, alphanumeric + hyphens, max 64 chars
+- `description`: required — Claude uses this to decide when to invoke the skill
+- Put code in separate files, not inline in the markdown
+- See the [skills standard](https://code.claude.com/docs/en/skills) for all available frontmatter fields
+
+## Testing
+
+Test your contribution on a fresh clone before submitting. For skills, run the skill end-to-end and verify it works.
+
+### web/ui test harness
+
+The frontend bundle in `web/ui/` is intentionally outside the pnpm workspace (the `build:spa` script uses `--ignore-workspace`). A root-level `pnpm install` populates `web/ui/node_modules` and builds `web/ui/dist/` automatically via the `postinstall` hook — usually no extra step is needed.
+
+If you ran `pnpm install --ignore-scripts` (the postinstall is suppressed), or you want to run web/ui tests on their own, install its deps and run the test runner directly:
+
+```bash
+cd web/ui && pnpm install --frozen-lockfile --ignore-workspace && pnpm test
+```
+
+Otherwise the test runner exits with a missing-dependency error (the exact symptom — module-not-found on `@vitejs/plugin-react`, missing test framework, etc. — depends on which entry point your package manager hits first).
+
+## Pull Requests
+
+### Before opening
+
+1. **Link related issues.** If your PR resolves an open issue, include `Closes #123` in the description so it's auto-closed on merge.
+2. **Test thoroughly.** Run the feature yourself. For skills, test on a fresh clone.
+3. **Check the right box** in the PR template. Labels are auto-applied based on your selection:
+
+| Checkbox | Label |
+|----------|-------|
+| Feature skill | `PR: Skill` + `PR: Feature` |
+| Utility skill | `PR: Skill` |
+| Operational/container skill | `PR: Skill` |
+| Fix | `PR: Fix` |
+| Simplification | `PR: Refactor` |
+| Documentation | `PR: Docs` |
+
+### PR description
+
+Keep it concise. Remove any template sections that don't apply. The description should cover:
+
+- **What** — what the PR adds or changes
+- **Why** — the motivation
+- **How it works** — brief explanation of the approach
+- **How it was tested** — what you did to verify it works
+- **Usage** — how the user invokes it (for skills)
+
+Don't pad the description. A few clear sentences are better than lengthy paragraphs.

package/CONTRIBUTORS.md

@@ -0,0 +1,26 @@
+# Contributors
+
+Thanks to everyone who has contributed to NanoClaw!
+
+- [Alakazam03](https://github.com/Alakazam03) — Vaibhav Aggarwal
+- [tydev-new](https://github.com/tydev-new)
+- [pottertech](https://github.com/pottertech) — Skip Potter
+- [rgarcia](https://github.com/rgarcia) — Rafael
+- [AmaxGuan](https://github.com/AmaxGuan) — Lingfeng Guan
+- [happydog-intj](https://github.com/happydog-intj) — happy dog
+- [bindoon](https://github.com/bindoon) — 潕量
+- [taslim](https://github.com/taslim) — Taslim
+- [baijunjie](https://github.com/baijunjie) — BaiJunjie
+- [Michaelliv](https://github.com/Michaelliv) — Michael
+- [kk17](https://github.com/kk17) — Kyle Zhike Chen
+- [flobo3](https://github.com/flobo3) — Flo
+- [edwinwzhe](https://github.com/edwinwzhe) — Edwin He
+- [scottgl9](https://github.com/scottgl9) — Scott Glover
+- [cschmidt](https://github.com/cschmidt) — Carl Schmidt
+- [leonalfredbot-ship-it](https://github.com/leonalfredbot-ship-it) — Alfred-the-buttler
+- [moktamd](https://github.com/moktamd)
+- [gurixs-carson](https://github.com/gurixs-carson)
+- [MrBlaise](https://github.com/MrBlaise) — Balázs Rostás
+- [lbsnrs](https://github.com/lbsnrs) — Andreas Liebschner
+- [spencer-whitman](https://github.com/spencer-whitman)
+- [lazure-ocean](https://github.com/lazure-ocean) — Cyril Ionov

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gavriel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.