Merge pull request #45 from edgehero/feat/easy-install

feat: easier install — pi-dispatch init + doctor, prebuilt GHCR image, and clearer 'add the panel via pi' docs

Author: edgehero

.env.example

@@ -1,11 +1,15 @@
 # Copy to .env and fill in. Never commit a real .env (it is gitignored).
 
-# --- Provider credential (required) ---
+# --- Provider credential ---
 # pi supports ~30 providers; set the key for the one you use, under the variable name pi expects.
 # The worker forwards ONLY the configured provider's key into the job container -- nothing else.
 #   Anthropic: ANTHROPIC_API_KEY  (or ANTHROPIC_OAUTH_TOKEN, which takes precedence)
 #   OpenAI:    OPENAI_API_KEY     Google: GEMINI_API_KEY     Groq: GROQ_API_KEY   ... etc.
+# You can LEAVE THIS BLANK if you are already logged into pi: when the env has no key, the worker reads the
+# API key from ~/.pi/agent/auth.json (host-side) and env-injects it -- on by default, nothing to set.
+# API-key logins only; an OAuth/subscription login is refused (it expires; use an API key for a service).
 ANTHROPIC_API_KEY=
+# PI_AUTH_FROM_PI=0   # uncomment to force env-only (fail loudly on a missing env key instead of using your pi login)
 
 # --- Which provider/model to run by default (override per job with --provider / --model) ---
 PI_PROVIDER=anthropic
@@ -28,7 +32,7 @@ PI_CONCURRENCY=3       # how many jobs run in parallel
 
 # --- Infrastructure ---
 VALKEY_URL=redis://127.0.0.1:6379
-PI_JOB_IMAGE=pi-job:latest          # the image you built:  docker build -f image/Dockerfile -t pi-job:latest .
+PI_JOB_IMAGE=pi-job:latest          # docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest  (or build image/Dockerfile)
 # PI_JOBS_DIR=                      # where per-job /job inputs live (default: your OS temp dir)
 # PI_LOGS_DIR=                      # where per-job status records (and optional raw logs) land (default: OS temp /pi-dispatch/logs)
 # PI_CAPTURE_JOB_LOGS=              # default 0; set 1 to ALSO write raw container output to logs/<jobId>.log -- PII-bearing (issue/comment text), host-only (never mounted into the container), off by default (opt-in)
@@ -37,6 +41,12 @@ PI_JOB_IMAGE=pi-job:latest          # the image you built:  docker build -f imag
                                     # Unset = cron disabled for the worker; the receiver REQUIRES it (it holds the label/comment/pull_request trigger config)
 # PI_PAUSE_WINDOWS_FILE=            # ABSOLUTE path to pause-windows.json — "quiet hours" per folder/repo (pause runs between certain times/days/dates, auto-resume). Unset = feature off. See docs/pause-windows.md
 # PI_SETTINGS_FILE=                 # ABSOLUTE path to the runtime settings overlay (default: OS temp /pi-dispatch/settings.json); edited by the admin extension, read by the worker per job
+
+# --- Reuse your existing pi setup in every job (see docs/global-pi-overlay.md) ---
+# PI_GLOBAL_PI_DIR=                  # dir with your host pi setup (models.json/skills/APPEND_SYSTEM.md), mounted /opt/pi-global:ro into every job, layered UNDER each repo's .pi/. Unset = off. Stage it with: pi-dispatch import-pi
+# PI_GLOBAL_ALLOW_EXTENSIONS=       # set 1 to LOAD the overlay's extensions (default off). They run code against adversarial input with open egress — vet each; never the admin extension.
+# PI_FORWARD_ENV=                   # comma-separated extra env var NAMES to forward into the container (e.g. a CUSTOM provider's key). Explicit allowlist, not a pass-through.
+
 PI_SCHEDULER_STALL_MAX=2            # tear down a scheduler after N consecutive stalls (money backstop)
 # PI_DISPATCH_RUN_ROOTS=            # OS-path-delimited allowlist (; on Windows, : elsewhere) of folders the model-callable dispatch_run may target; default empty = fail-closed (dispatch_run refuses every folder until you opt in)
 # PI_DISPATCH_RUN_PER_HOUR=3       # per-hour cap on model-invoked dispatch_run enqueues; 0 disables the tool

.github/workflows/image.yml

@@ -0,0 +1,68 @@
+# Build and publish the pi-dispatch job image to GHCR so operators `docker pull` instead of the slow local
+# build (Chromium + Playwright + fonts, minutes). main is branch-protected (PR + 1 approving review), so a
+# push here is an already-approved merge — nothing in this workflow merges anything (CONST-MERGE-NEVER-AUTOMATIC).
+#
+# The pushed image is a snapshot of THIS repo's runner + guardrails at the built commit. Operators who bake
+# their own toolchain into image/Dockerfile still build locally; the pull is only the fast default path.
+#
+# No secret required: GHCR auth uses the built-in GITHUB_TOKEN (packages: write). One-time after the first
+# successful run: make the ghcr.io/edgehero/pi-job package Public in the org's package settings, otherwise
+# `docker pull` needs auth.
+
+name: image
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "image/**"
+      - ".github/workflows/image.yml"
+  # Manual re-run (available once this file is on the default branch).
+  workflow_dispatch: {}
+
+permissions:
+  contents: read
+  packages: write # push to ghcr.io/edgehero/*
+
+concurrency:
+  group: image
+  cancel-in-progress: false
+
+env:
+  IMAGE: ghcr.io/edgehero/pi-job
+
+jobs:
+  build-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/setup-qemu-action@v3 # arm64 emulation for the multi-arch build
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Tags + labels
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE }}
+          tags: |
+            type=raw,value=latest
+            type=sha
+
+      - name: Build + push (amd64 + arm64)
+        uses: docker/build-push-action@v6
+        with:
+          context: . # repo root — the Dockerfile copies image/runner + guardrails from here
+          file: image/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

README.md

@@ -32,15 +32,20 @@ system. **pi-dispatch is exactly that missing operational layer, and nothing els
 You need **Docker** and **Node ≥ 22.19**, and a provider API key (e.g. Anthropic).
 
 ```bash
-# 1. Build the job image (once)
-docker build -f image/Dockerfile -t pi-job:latest .
+# 1. Get the job image — pull the prebuilt one (fast)...
+docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest
+#    ...or bake your own toolchain into it instead (slower, fully yours):
+#    docker build -f image/Dockerfile -t pi-job:latest .
 
 # 2. Start Valkey (the durable job queue)
 docker compose -f deploy/docker-compose.yml up -d
 
-# 3. Configure
-cp .env.example .env         # then set ANTHROPIC_API_KEY (or your provider's key)
+# 3. Install, scaffold, and check your setup
 npm ci
+npx pi-dispatch init         # writes .env + triggers.json + pause-windows.json (never clobbers)
+#    edit .env — set ANTHROPIC_API_KEY (or your provider's key)
+#    already logged into pi? leave it blank — the worker reuses the key from ~/.pi/agent/auth.json by default
+npx pi-dispatch doctor       # ✓/✗ preflight: Docker, Valkey, the image, and your provider key
 
 # 4. Run the worker in one terminal
 npx pi-dispatch worker       # (or: npm --workspace worker start)
@@ -49,6 +54,9 @@ npx pi-dispatch worker       # (or: npm --workspace worker start)
 npx pi-dispatch run ./my-project --task "add type hints to utils.py" --flow tidy
 ```
 
+> **The prebuilt image is a snapshot** of this repo's runner + guardrails at its build. To bake a project's
+> toolchain in (the edge cron/visual flows rely on), build `image/Dockerfile` yourself — step 1's second form.
+
 > **Heads-up on the CLI name.** `pi-dispatch` here is *this repo's* workspace CLI (`worker/src/cli.mjs`),
 > which `npx` resolves from the local `node_modules/.bin` after `npm ci` — run these from the repo root. It
 > is **not** the unrelated npm package `pi-dispatch` (see [License](#license)); this project isn't published
@@ -77,6 +85,32 @@ A container boundary, spend bounded *before* a container starts, nothing dropped
 enforces. Read [`SECURITY.md`](SECURITY.md) before you rely on it: it states plainly what is and is not
 defended.
 
+## Reuse your existing pi setup
+
+Already run `pi`? Give every job your host setup — custom models, global skills, a global persona — **layered
+under each repo's own `.pi/`** (the repo still wins). Works with the pulled image; it's a read-only mount, not
+a rebuild.
+
+```bash
+pi-dispatch import-pi          # stage a credential-free copy of ~/.pi/agent into ./pi-global
+# then set PI_GLOBAL_PI_DIR=/abs/path/to/pi-global in .env, and:
+pi-dispatch doctor             # verifies the overlay carries no credential
+```
+
+The overlay is mounted `/opt/pi-global:ro` into every container. Skills merge with the repo's (a repo skill
+of the same name overrides the global one); the prompt layers `guardrails → global persona → repo persona`,
+the safety floor always first and unremovable. `import-pi` **refuses** a `models.json` with a literal key and
+**never** copies `auth.json` — your credential stays in the environment. Extensions are opt-in and armed
+separately (`--with-extensions` + `PI_GLOBAL_ALLOW_EXTENSIONS=1`) because they run code against adversarial
+input; the admin extension is hard-blocked. Full reference: [`docs/global-pi-overlay.md`](docs/global-pi-overlay.md).
+
+**Already logged into pi? The key just works — by default.** When the provider key is absent from the
+worker's environment, the worker reads it **host-side** from `~/.pi/agent/auth.json` and env-injects it into
+the job — a host-side read of a host-held secret, never a file mounted into the container. Nothing to set;
+`PI_AUTH_FROM_PI=0` forces env-only if you'd rather fail loudly on a missing env key. **API-key logins only**:
+an OAuth/subscription login (`pi login`) is refused — those tokens expire and can't be refreshed in the
+container, and a subscription isn't the credential for an unattended service; use an API key with a spend limit.
+
 ## Run as a service
 
 `pi-dispatch worker` is a long-running process — run it in a terminal, or hand it to your OS's service
@@ -161,9 +195,20 @@ worker's **boot reaper** clears on the next start, rather than draining cleanly.
 
 The admin surface — the dashboard and command transcript shown at the top of this README — is a **pi
 extension** in [`admin/`](admin/) that loads into *your own* interactive pi session — no daemon, no web
-app, **no network port at all**. Load it with `pi -e admin/src/index.ts` from this checkout, add that path
-to the `"extensions"` array in `~/.pi/agent/settings.json`, or just run pi inside this checkout: the
-in-repo `.pi/extensions` shim auto-loads once you've trusted the project.
+app, **no network port at all**.
+
+**Install it through pi** — the published package, then open the panel:
+
+```bash
+pi install npm:@edgehero/pi-dispatch-admin   # then, in pi:  /dispatch
+```
+
+Two other ways to load it: from a clone, the in-repo `.pi/extensions` shim auto-loads once you've trusted
+the project; or point pi at the source with `pi -e admin/src/index.ts` (add that path to the `"extensions"`
+array in `~/.pi/agent/settings.json` to make it permanent). To operate a **live** deployment, give the pi
+session the same `VALKEY_URL`, `PI_SETTINGS_FILE`, `PI_TRIGGERS_FILE`, `PI_PAUSE_WINDOWS_FILE`, and
+`PI_LOGS_DIR` the worker uses — the panel reads and writes those same files and queue, so both act on one
+deployment.
 
 Bare `/dispatch` opens the live dashboard overlay — one snapshot per second, `p`/`r` to pause/resume the
 queue in place, `↑`/`↓` to move across the triggers and runs, `Enter` to drill into either. **Triggers are

SECURITY.md

@@ -169,8 +169,22 @@ Stated openly rather than discovered later:
   provider needs. In particular `ANTHROPIC_OAUTH_TOKEN` silently takes precedence over
   `ANTHROPIC_API_KEY`, so a stray variable in the host environment can quietly redirect which credential
   a job spends.
+- **By default the worker sources the provider key from pi's `~/.pi/agent/auth.json` when the env has none.**
+  It is a host-side read env-injected into the container — never a credential file mounted in — and accepts
+  **API-key** logins only; an OAuth/subscription login is refused. The env always wins when set; set
+  `PI_AUTH_FROM_PI=0` to force env-only (fail loudly on a missing env key rather than fall back to a pi login).
+  Prefer an API key with a provider-side spend limit for an unattended service; a subscription token is
+  neither refreshable in the container nor intended for automation.
 - **Treat `.pi/` on your default branch as production code**, because it is: it goes into the agent's
   system prompt. Review changes to it with the same care as `.github/workflows/`.
+- **The global pi overlay (`PI_GLOBAL_PI_DIR`) is production code too**, and it must be credential-free. It
+  is mounted `:ro` into every job — a container that runs adversarial input — so a secret in it is a secret
+  in the box. Stage it with `pi-dispatch import-pi` (it refuses a `models.json` with a literal key and never
+  copies `auth.json`) and let `pi-dispatch doctor` re-check it; the provider key belongs in the environment,
+  never a mounted file. Overlay **extensions run arbitrary code against adversarial input with open network
+  egress** and are not scanned for secrets: keep `PI_GLOBAL_ALLOW_EXTENSIONS` unset until you have vetted
+  every one, and never place the admin extension in the overlay (it can enqueue paid jobs — a recursion
+  vector; `import-pi` blocks it).
 - **The admin surface is not a network service.** It is a pi extension in your own terminal session plus
   a `settings.json` file — it binds no port. Whoever can run pi with the extension loaded, or write
   `PI_SETTINGS_FILE`, holds operator power: the same trust as shell access on the host. Treat it that way.

docs/global-pi-overlay.md

@@ -0,0 +1,89 @@
+# Reuse your existing pi setup — the global overlay
+
+If you already run `pi`, you have a configured `~/.pi/agent`: custom models, global skills, a global persona.
+Point pi-dispatch at a **credential-free copy** of it and every job gets it — **layered under each repo's own
+`.pi/`**, so a repo can still override or add on top. It works with the **pulled** prebuilt image: this is a
+read-only mount, not an image rebuild.
+
+## Enable it
+
+```bash
+pi-dispatch import-pi          # stage the safe subset of ~/.pi/agent into ./pi-global
+# then in .env:
+PI_GLOBAL_PI_DIR=/absolute/path/to/pi-global
+pi-dispatch doctor             # verifies the overlay is credential-free
+```
+
+`import-pi` reads your host agent dir (`$PI_CODING_AGENT_DIR`, else `~/.pi/agent`) and copies a **curated,
+credential-free** subset into the overlay dir. Re-run it whenever you change your host setup. Flags:
+`--with-extensions` (see below), `--from <agentDir>`, `--to <overlayDir>`.
+
+## What layers, and who wins
+
+Four tiers, most-trusted first; each refines but never removes the one above:
+
+| Tier | Source | Trust | Mutable? |
+|---|---|---|---|
+| 1. Safety floor | baked `HARD_RULES.md` | image, root-owned | no (immutable) |
+| 2. **Global overlay** | `PI_GLOBAL_PI_DIR` → `/opt/pi-global:ro` | **operator, deploy-time** | re-run `import-pi` |
+| 3. Per-repo `.pi/` | repo's committed `.pi/` (default-branch SHA) | trusted-by-merge | per PR |
+| 4. Task/issue text | the webhook / CLI input | **adversarial — never instructions** | — |
+
+- **Skills**: repo skills are listed **first**, so a repo skill **overrides** a global one of the same name
+  (pi is first-path-wins); names that don't collide all load.
+- **Persona**: the assembled prompt is `guardrails → global persona → repo persona`. The floor is always
+  first and cannot be removed; global is your baseline; the repo's `.pi/APPEND_SYSTEM.md` is most specific.
+- **Models**: the overlay's `models.json` makes a **custom provider/model** resolvable. Definitions only —
+  the credential still comes from the environment, never the overlay.
+
+## What is copied — and what never is
+
+| Copied into the overlay | Never copied |
+|---|---|
+| `models.json` (definitions; **refused if it embeds a literal key**) | `auth.json` — your credential stays in env/auth.json |
+| `skills/<name>/` | `settings.json`, `sessions/`, `themes/`, `prompts/` |
+| `APPEND_SYSTEM.md` (global persona) | anything holding a secret |
+| `extensions/` — only with `--with-extensions` | the admin extension (hard-blocked) |
+
+The overlay is mounted **read-only** into a container that runs adversarial input, so it must hold **no
+secret**. `import-pi` refuses a `models.json` with a literal `apiKey` (move it to `auth.json`, or reference
+the environment as `"$MY_KEY"`), and `doctor` re-checks the overlay for `auth.json` and literal keys.
+
+### Custom providers
+
+If your model uses a provider whose key variable pi's built-in table doesn't know, forward it explicitly:
+
+```bash
+# .env
+PI_FORWARD_ENV=MY_PROVIDER_KEY      # comma-separated NAMES; forwarded by exact -e NAME=VALUE, never a pass-through
+```
+
+### The key is already in pi (on by default)
+
+Logged into pi already? You don't have to restate the key in `.env`. When the provider key is absent from
+the worker's environment, the worker reads it **host-side** from `~/.pi/agent/auth.json` and env-injects it
+under the variable pi expects — a host-side read of a host-held secret, injected via env exactly like `.env`,
+**never a file mounted into the container**. This is **on by default**; the environment still wins when
+present. Set `PI_AUTH_FROM_PI=0` to force env-only (fail loudly on a missing env key instead of falling back).
+
+**API-key logins only.** An OAuth/subscription login (`pi login`) is refused: those tokens expire and the
+container can't refresh them, and a subscription isn't the credential for an unattended paid service —
+configure an API key (with a spend limit) instead.
+
+## Extensions (the sharp edge — opt-in and armed separately)
+
+Extensions run **code against adversarial input with open network egress**, and host extensions often carry
+MCP-server credentials. They are therefore **doubly gated**:
+
+1. `pi-dispatch import-pi --with-extensions` copies them (verbatim — they are **not** scanned for secrets;
+   the admin extension is refused).
+2. They load **only** when you set `PI_GLOBAL_ALLOW_EXTENSIONS=1`. Unset = present but dormant.
+
+Vet every extension before arming, and never place the admin extension in the overlay (it can enqueue paid
+jobs — a recursion vector; `import-pi` blocks it, but treat it as a rule).
+
+## Reference
+
+`REQ-GLOBAL-PI-OVERLAY` ([requirements](../specs/requirements.md)),
+`DES-OPERATOR-GLOBAL-OVERLAY` ([design](../specs/design.md)),
+`INT-CONTAINER-RUNTIME-CONTRACT` / `INT-SDK-SESSION-OPTIONS` ([interfaces](../specs/interfaces.md)).