model-orchestrator 0.1.4

package/templates/README.md

@@ -0,0 +1,14 @@
+# templates/
+
+Everything the installer can write, organized by the level that adds it. Files are rendered with `{{PLACEHOLDERS}}` filled from `src/catalog.js` and the user's answers (`src/install.js` computes every value; templates contain no logic).
+
+| Folder | Written at | Contents |
+|---|---|---|
+| `common/` | every level | the start-here README, `TASK_BUNDLE.md`, `protocols/` (build, propagate, gap analysis, deep research, numbers and logic, memory and record) |
+| `beginner/` | every level | `ORCHESTRATOR.md`, the single-agent routing rules |
+| `agents/` | every level, one variant | the primary agent's loading surface: Claude Code subagents, Antigravity custom agents, or a paste snippet |
+| `intermediate/` | level 2+ | `ROUTING.md`, `TIERS.md`, `DELEGATION_MATRIX.md`, `RESEARCH_TRIAGE.md`, `CLI-RUN.md` |
+| `advanced/` | level 3 | `vm/`: gateway config, compose file, box rules, privacy gates, scheduled jobs |
+| `tools/` | when selected | companion tools the AIs call: `codecalc/` and `obsidian-tc/` (install doc + MCP snippets each). See `tools/README.md` |
+
+Agent definitions under `agents/claude-code/` and `agents/agy/` are written to the PROJECT root (`--project`), not `--dir`, because that is where those CLIs read them. A `README.md` at the root of a tier folder (like this one) documents the repo and is not installed. `common/README.md` is the exception: it is the user's start-here file. READMEs deeper in (`protocols/`, `vm/`, `vm/jobs/`) are installed as folder indexes.

package/templates/advanced/README.md

@@ -0,0 +1,14 @@
+# templates/advanced/
+
+Written at level 3 only, on top of everything below it. Everything lands under `vm/` in the user's install. This tier is documentation and config templates for a Linux box; the installer never touches a remote machine.
+
+| File | What it is |
+|---|---|
+| `vm/README.md` | start-here for the box: what runs where, the gateway-holds-the-keys rule, the closed loop |
+| `vm/setup-vm.sh` | idempotent setup for a fresh Ubuntu box: deps, the selected CLIs; prints every vendor script instead of running it |
+| `vm/docker-compose.yml` | the gateway (and a local model runtime if selected), bound to loopback |
+| `vm/gateway.config.yaml` | one lane per selected provider, keys referenced by environment variable NAME only |
+| `vm/ENVIRONMENT.md` | which variable names the gateway expects, and where to keep the values (a secrets manager, never a file in the repo) |
+| `vm/box-CLAUDE.md` | the rules a Claude Code session on the box inherits: cheapest tier that does the job, what never goes to the cheap tier, no public bind |
+| `vm/PRIVACY_GATES.md` | what data never leaves the machine, which lanes are barred by name |
+| `vm/jobs/` | a systemd timer + service pair for the weekly gap-analysis audit, plus an index |

package/templates/advanced/vm/ENVIRONMENT.md

@@ -0,0 +1,18 @@
+# ENVIRONMENT.md: names the gateway expects
+
+Generated {{DATE}} from the metered API keys you said you hold (asked separately from your subscription CLIs, because a Claude Code plan is not an Anthropic API key):
+
+{{APIS_LIST}}
+
+These are variable **names**. The values live in a secrets manager and are injected at start time (for example `<manager> run -- docker compose up -d`, or a systemd `EnvironmentFile=` that lives outside this folder with mode 600).
+
+{{ENV_NAMES}}
+
+`GATEWAY_MASTER_KEY` is the bearer every client presents to the gateway. Generate it once (`openssl rand -hex 32`), store it in the manager, never paste it into a file here. It must be a single token matching `^[A-Za-z0-9._-]+$`: the audit job interpolates it into curl's config grammar and refuses anything else.
+
+## Rules
+
+- Never print a value in a terminal or a log. Verify by length or by a hash prefix.
+- Never pass a value on a command line; argv is world-readable on Linux. Use `curl --config -` fed from `printf`, or a tool's own env-var option.
+- Never commit a file that contains a value. Add a secret scanner as a pre-push hook.
+- Subscription CLIs (`claude`, `codex`, `agy`, `grok`, `hermes`) keep their own sign-in state; they need none of these names.

package/templates/advanced/vm/PRIVACY_GATES.md

@@ -0,0 +1,33 @@
+# PRIVACY_GATES.md: what never leaves the machine
+
+A bar that is not named is not enforced. Fill in the names.
+
+## Data classes
+
+| Class | Examples | May go to |
+|---|---|---|
+| Public | published posts, open docs, public repos | any lane |
+| Working | your own notes, drafts, code you will publish | your primary vendor's lanes, subscription CLIs you trust with it |
+| Confidential | client data, other people's records, contracts | your primary vendor only, or the local lane |
+| Personal | health, identity, private journals | the local lane only, or nowhere |
+
+## Lanes barred by name for Confidential and Personal
+
+- metered third-party bulk lanes (the cheapest-tier API you use for volume)
+- concurrent fan-out lanes on a consumer subscription
+- any shared compute lane (free GPU tiers, notebook services)
+- any tool that stores conversation history on its own servers without a retention control you have read
+
+Write your own lane names here, in this file, so the bar is checkable:
+
+```
+BARRED: <lane>, <lane>, <lane>
+```
+
+## The local lane is a privacy lane, not a cost lane
+
+Route to a local model when confinement is the requirement. Never to save money: the accuracy gap is real, and pennies saved are not worth a wrong answer that looks right.
+
+## The check
+
+Before any bulk call: which class is this data, and is the lane in the barred list? If you cannot answer both, it is Confidential.

package/templates/advanced/vm/README.md

@@ -0,0 +1,60 @@
+# vm/: the box that runs it unattended
+
+Level 3 = levels 1 and 2 plus a machine that is always on. A small Linux VM (any cloud's free ARM tier is enough) that holds the CLIs, a model gateway, and the scheduled jobs. Your laptop stays the interactive driver; the box owns the schedule.
+
+Generated {{DATE}} for: `{{AI_IDS}}`. Installed at `{{INSTALL_DIR}}`; the systemd unit and the audit script carry that path.
+
+## The one architectural property
+
+**Only the gateway holds provider credentials.** Nothing else on the box does: not the orchestrator, not the scheduler, not a job. Every surface reaches models through the gateway, so rotating a key is a change in exactly one place. The gateway is bound to loopback (or a private mesh network), never to `0.0.0.0`.
+
+## What runs where
+
+| Surface | Role | Reaches models via |
+|---|---|---|
+| The orchestrator CLI ({{PRIMARY_NAME}}) | interactive driver when you SSH in; dispatch brain for jobs | its own subscription, off the gateway |
+| `cli-run` lanes ({{CLI_RUN_LANES}}) | the other agent CLIs, headless | their own subscriptions (Lane A) |
+| The gateway (`docker-compose.yml`) | one OpenAI-compatible endpoint fronting every metered provider | provider keys from the environment |
+| A local model runtime (if selected) | the privacy lane | nothing leaves the box |
+| Scheduled jobs (`jobs/`) | the weekly gap-analysis audit (lane: `{{AUDIT_LANE}}`), and anything else recurring | the gateway, or `cli-run` |
+| codecalc (if selected) | the calculator, code runner and logic checker every agent here calls; stdio, offline, no key | nothing; it computes locally |
+
+## Setup, in order
+
+1. Provision a box. Ubuntu, 2+ vCPU, 8 GB is comfortable. Put it on a private mesh network if you can; do not open ports to the internet.
+2. `bash setup-vm.sh`. It installs system deps and the npm-installable CLIs, then **prints** the vendor shell installers for the rest. Read those scripts before running them.
+3. Sign each CLI in with its device-code flow (`codex login --device-auth`, `grok login --device-auth`, `agy` on first run). Run these inside `tmux` so a dropped SSH session does not kill the prompt. Headless Linux has no keyring by default; `setup-vm.sh` installs one so the CLIs stop re-prompting.
+4. Put provider keys in your secrets manager and export the names listed in `ENVIRONMENT.md` into the gateway's environment at start time. Never write a value into a file in this folder. The gateway config was rendered from the API keys you said you hold, not from your CLI subscriptions: those are different entitlements.
+5. `docker compose up -d`, then list the lanes without putting the key in argv (the key must be a single token, `^[A-Za-z0-9._-]+$`, because it is interpolated into curl's config grammar):
+   ```bash
+   printf 'header = "Authorization: Bearer %s"\n' "$GATEWAY_MASTER_KEY" | curl -s --config - http://127.0.0.1:4000/v1/models
+   ```
+6. Install the weekly audit: `jobs/README.md`.
+7. Copy `box-CLAUDE.md` to `~/CLAUDE.md` on the box (or your agent's equivalent rules file) so a session there inherits the house rules without you present.
+
+## The dispatch shape
+
+1. **Deterministic pre-triage, zero tokens:** a keyword table sends the obvious cases (bulk patterns → the cheap lane, URLs and current events → the live lane, "review this" → the reviewer, "write this up" → the orchestrator).
+2. **Judgment dispatch:** everything else is routed by the orchestrator against `ROUTING.md` and `DELEGATION_MATRIX.md`, with a logged reason.
+3. **Free lane first, escalate on signal.** Every job starts on its $0 lane and climbs only on failure, low confidence, or an explicit "expensive to get wrong".
+4. **Unattended means no escalation to a human-gated tier.** An unresolved irreversible call is surfaced (a message, a ticket comment), never executed.
+5. **Writes stay locked to one writer.** Every other engine proposes; one writer records.
+
+## The closed loop (name what watches it)
+
+| Thing | Ran? | Watched by | On failure |
+|---|---|---|---|
+| gateway | `docker compose ps`, `/v1/models` | the weekly audit job | audit report names the dead lane |
+| weekly audit | `systemctl --user list-timers` | **nothing** unless you wire a notifier | write "nothing" here until you do; that line is the useful one |
+| each `cli-run` job | exit code + `~/.ai-orchestrator/cli-run.log.jsonl` | the job's own caller | rc 10/12/13 in the log |
+
+"Nothing watches it" is a valid answer and usually the valuable one. Writing it down turns an invisible gap into a tracked one.
+
+## Never on this box
+
+- Vendor scripts run blind. Read first.
+- An unpinned image or package. `docker-compose.yml` and `setup-vm.sh` pin versions; bump them on purpose, never by restarting.
+- A provider key in a file in this folder, in shell history, in argv, or in a container image.
+- A service bound to `0.0.0.0`.
+- Private notes, client data, or personal records sent to a metered bulk lane. See `PRIVACY_GATES.md`.
+- A payment card attached to a compute lane "to unlock a tier". Free credit only unless a human says otherwise.

package/templates/advanced/vm/box-CLAUDE.md

@@ -0,0 +1,28 @@
+# CLAUDE.md for the box
+
+Copy to `~/CLAUDE.md` on the machine (or your agent's equivalent rules file). A session here inherits these without a human present.
+
+## Cost rule
+Prefer the cheapest tier that does the job well. Delegate grunt work through the dispatch layer; keep the reasoning in-session.
+
+Send to the cheap tier via the gateway or `cli-run`: bulk classification and tagging, reformatting, extraction, first-pass summaries, mechanical transforms, explicit rough drafts.
+
+Never send to the cheap tier: anything that will be published in a person's own voice, code that gets committed, anything needing current vendor-specific knowledge, anything where being wrong is expensive, anything time-sensitive.
+
+## On dispatch failure
+Report it and fall back to doing the work in-session. Never silently retry the same lane.
+
+## Zero ingress
+Nothing binds to `0.0.0.0`. Nothing publishes a container port to the public interface. New services go on loopback or the private mesh.
+
+## Unattended means no human-gated escalation
+An unresolved call that is irreversible or rewrites a standing rule gets surfaced (a message, a ticket comment) and stops. It is never executed on the strength of a model's confidence.
+
+## One writer
+Scheduled jobs and other engines propose. One writer records. If you are not that writer, produce a file and name it in your report.
+
+## Secrets
+Names in the environment, values in the secrets manager. Never print one, never pass one in argv, never write one to disk here.
+
+## Routing
+`{{RULES_PATH}}/ROUTING.md` and `{{RULES_PATH}}/DELEGATION_MATRIX.md` are the rules. `{{RULES_PATH}}/protocols/` are the procedures.

package/templates/advanced/vm/docker-compose.yml

@@ -0,0 +1,19 @@
+# The gateway is the ONLY holder of provider credentials on this box.
+# It is bound to loopback. Put it behind a private mesh network if other
+# machines need it; never publish it on 0.0.0.0.
+services:
+  gateway:
+    image: {{LITELLM_IMAGE}}   # pinned on purpose; bump deliberately after reading the release notes
+    container_name: gateway
+    restart: unless-stopped
+    ports:
+      - "127.0.0.1:4000:4000"
+    volumes:
+      - ./gateway.config.yaml:/app/config.yaml:ro
+    command: ["--config", "/app/config.yaml", "--port", "4000"]
+    environment:
+      # Names only. Values come from the environment you start compose in
+      # (a secrets manager's `run` wrapper, or a systemd EnvironmentFile outside this repo).
+      - LITELLM_MASTER_KEY=${GATEWAY_MASTER_KEY}
+{{COMPOSE_ENV}}
+{{COMPOSE_OLLAMA}}

package/templates/advanced/vm/gateway.config.yaml

@@ -0,0 +1,12 @@
+# LiteLLM gateway config. One lane per provider you said you have.
+# Every key is `os.environ/<NAME>`: the value lives in the environment, never here.
+# Bind to ALIASES (model_name), not raw provider ids, so a vendor rename is a one-line repoint.
+model_list:
+{{GATEWAY_MODELS}}
+
+litellm_settings:
+  drop_params: true
+  set_verbose: false
+
+general_settings:
+  master_key: os.environ/LITELLM_MASTER_KEY

package/templates/advanced/vm/jobs/README.md

@@ -0,0 +1,39 @@
+# jobs/
+
+Scheduled work on the box, as user-level systemd timers. Each job is a timer + service pair and gets one line in the table below. **Each line names what watches it.** "nothing" is an honest answer and the one that tells you where to look.
+
+| Job | Schedule | Does | Lane | Watched by |
+|---|---|---|---|---|
+| `weekly-audit` | Monday 09:00 | collects live state (gateway lanes, timers, CLI versions), composes a brief with the protocol and `DELEGATION_MATRIX.md`, and asks a cli-run lane for the gap report | `{{AUDIT_LANE}}` (first enabled lane at install time; edit `AUDIT_LANE` in the script to change it) | nothing yet: wire a notifier and update this line |
+
+Paths in the service and the script were rendered for this install: `{{INSTALL_DIR}}`. If you move the folder, re-run the installer or edit both files.
+
+## Install a job
+
+```bash
+mkdir -p ~/.config/systemd/user
+cp weekly-audit.service weekly-audit.timer ~/.config/systemd/user/
+systemctl --user daemon-reload
+systemctl --user enable --now weekly-audit.timer
+systemctl --user list-timers        # it should be listed with a next-run time
+loginctl enable-linger "$USER"      # so user timers run without a login session
+```
+
+The service reads `GATEWAY_MASTER_KEY` from an `EnvironmentFile` that lives outside this folder (mode 600). Point the `EnvironmentFile=` line at yours before installing. The key must be a single token matching `^[A-Za-z0-9._-]+$`; the script refuses anything else.
+
+## Verify a job ran
+
+```bash
+systemctl --user status weekly-audit.service
+journalctl --user -u weekly-audit.service -n 50
+ls -la {{INSTALL_DIR}}/reports/
+```
+
+## What the job guarantees
+
+- **Bounded:** every probe (gateway, `systemctl`, each CLI `--version`) runs under a 10 s watchdog; the model call under 600 s; the unit under `TimeoutStartSec=900`, which kills the whole cgroup.
+- **Previous report preserved:** output goes to a temp file and is renamed over `audit-<date>.md` only on a clean, non-empty run. A failed run leaves `failed-audit-<stamp>-rc<N>.md` beside it and the last good report untouched.
+- **Boundary:** the lane runs with the strongest restriction it offers ({{AUDIT_LANE_BOUNDARY_NOTE}}). The brief's denied-actions list is an instruction, not an enforcement, for lanes without a sandbox flag.
+- **Honest unknowns:** a probe that times out writes an `UNVERIFIED` line, which the brief tells the lane to treat as unknown, never clean.
+
+A timer that has never been seen to fire is not known to work. Run `systemctl --user start weekly-audit.service` once by hand and read the journal before trusting the schedule.

package/templates/advanced/vm/jobs/weekly-audit.service

@@ -0,0 +1,17 @@
+[Unit]
+Description=ai-orchestrator weekly gap-analysis audit
+After=network-online.target
+
+[Service]
+Type=oneshot
+WorkingDirectory={{INSTALL_DIR_SYSTEMD}}
+# Names come from a file OUTSIDE this repo, mode 600. Edit the path.
+EnvironmentFile=%h/.config/ai-orchestrator/gateway.env
+ExecStart=/bin/bash "{{INSTALL_DIR_SYSTEMD}}/vm/jobs/weekly-audit.sh"
+# Whole-job deadline: collection probes (6 x 10 s) + the 600 s model call + cleanup.
+# On expiry systemd kills the whole cgroup, so nothing the job spawned survives.
+TimeoutStartSec=900
+KillMode=control-group
+
+[Install]
+WantedBy=default.target

package/templates/advanced/vm/jobs/weekly-audit.sh

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# weekly-audit.sh: collect live state, then let a cli-run lane draft the gap report.
+# Rendered at install time: the install directory and the audit lane came from your selection.
+#
+# Guarantees this script makes, and how:
+#   - every collection step is BOUNDED (a watchdog around curl and each --version probe)
+#   - the previous successful report is NEVER truncated: output goes to a temp file and is
+#     renamed into place only on a clean exit; failed output is kept beside it for diagnosis
+#   - the lane runs with the strongest boundary it offers ({{AUDIT_LANE_BOUNDARY_NOTE}})
+#   - rc 10/12/13 from cli-run means no report was produced; the timer's journal shows it
+set -uo pipefail
+INSTALL_DIR={{INSTALL_DIR_SH}}
+AUDIT_LANE="{{AUDIT_LANE}}"
+AUDIT_LANE_FLAGS="{{AUDIT_LANE_FLAGS}}"
+PROBE_SECS="${PROBE_SECS:-10}"      # per collection probe
+RUNNER_SECS="${RUNNER_SECS:-600}"   # the model call; TimeoutStartSec in the unit covers the whole job
+{{AUDIT_LANE_GUARD}}
+cd "$INSTALL_DIR" || { echo "weekly-audit: $INSTALL_DIR missing" >&2; exit 2; }
+mkdir -p reports
+
+# bounded SECS cmd...  : run cmd, and after SECS kill it AND every descendant
+# (a probe that forks, or a stub that ignores its own flags, must not hold a
+# pipe open). Process groups do not help here: bash disables job control inside
+# pipeline subshells, so `kill -- -pid` would kill nothing. A recursive tree
+# kill via pgrep works on macOS and Linux alike; `timeout(1)` is not on macOS.
+killtree() {
+  local p="$1" c
+  for c in $(pgrep -P "$p" 2>/dev/null); do killtree "$c"; done
+  kill -KILL "$p" 2>/dev/null
+}
+bounded() {
+  local secs="$1"; shift
+  ( "$@" ) & local pid=$!
+  ( sleep "$secs"; killtree "$pid" ) >/dev/null 2>&1 & local wd=$!
+  wait "$pid" 2>/dev/null; local rc=$?
+  killtree "$wd" >/dev/null 2>&1; wait "$wd" 2>/dev/null
+  return $rc
+}
+
+# The gateway key must be a single token: it is interpolated into curl's config
+# grammar, and a quote or newline in it would become a second directive.
+KEY="${GATEWAY_MASTER_KEY:-}"
+if [ -n "$KEY" ] && ! printf '%s' "$KEY" | grep -Eq '^[A-Za-z0-9._-]+$'; then
+  echo "weekly-audit: GATEWAY_MASTER_KEY must match ^[A-Za-z0-9._-]+$ (generate it with: openssl rand -hex 32)" >&2
+  exit 2
+fi
+
+DATE="$(date -u +%F)"
+STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
+{
+  echo "# live state $DATE"; echo
+  echo "## gateway lanes"
+  if [ -n "$KEY" ]; then
+    # The key never enters argv: curl reads the header from a 0600 config file that
+    # exists only for this probe. curl's own timeouts AND the watchdog bound it.
+    CFG="$(umask 077 && mktemp "${TMPDIR:-/tmp}/audit-curl-XXXXXX")"
+    printf 'header = "Authorization: Bearer %s"\n' "$KEY" > "$CFG"
+    if ! bounded "$PROBE_SECS" curl -s --connect-timeout 5 --max-time "$PROBE_SECS" --max-filesize 1048576 --config "$CFG" http://127.0.0.1:4000/v1/models \
+      | jq -r '.data[].id' 2>/dev/null; then
+      echo "UNVERIFIED: gateway unreachable or timed out within ${PROBE_SECS}s"
+    fi
+    rm -f "$CFG"
+  else
+    echo "UNVERIFIED: GATEWAY_MASTER_KEY not set; gateway not queried"
+  fi
+  echo; echo "## timers"
+  bounded "$PROBE_SECS" systemctl --user list-timers --no-pager 2>/dev/null || echo "UNVERIFIED: systemd user session unavailable or timed out"
+  echo; echo "## cli versions"
+  for b in claude codex agy grok hermes qwen; do
+    if command -v "$b" >/dev/null 2>&1; then
+      printf '%s ' "$b"
+      bounded "$PROBE_SECS" "$b" --version 2>/dev/null | head -1 || echo "UNVERIFIED: --version timed out after ${PROBE_SECS}s"
+    fi
+  done
+} > "reports/live-state-$STAMP.md"
+ln -sfn "live-state-$STAMP.md" reports/live-state.md
+
+# The brief the lane actually reads: the protocol, the intended configuration,
+# and the live state it is meant to diff against.
+BRIEF="reports/audit-brief-$STAMP.md"
+{
+  echo "## Task bundle"
+  echo "**Purpose.** Weekly gap analysis: compare the live state below with the intended configuration and name what is missing, dead, or drifted."
+  echo "**Task class.** read_only"
+  echo "**Denied actions.** Do not run commands, do not modify files, do not call any network service. Enforcement: {{AUDIT_LANE_BOUNDARY_NOTE}}."
+  echo "**Report contract.** A ranked list of gaps (what is missing, where it should be, evidence line), then a CLEAN line per area with no gap, then what you could not assess. Treat every UNVERIFIED line below as unknown, never as clean."
+  echo "**Exit parameters.** Stop after one pass over the three sections below."
+  echo; echo "# Protocol"; cat protocols/gap-analysis.md
+  echo; echo "# Intended configuration"; cat DELEGATION_MATRIX.md 2>/dev/null || cat ORCHESTRATOR.md
+  echo; echo "# Live state"; cat "reports/live-state-$STAMP.md"
+} > "$BRIEF"
+
+# Write to a temp file; the dated report is replaced only by a clean, non-empty run.
+FINAL="reports/audit-$DATE.md"
+TMP="$(mktemp "reports/.audit-$STAMP-XXXXXX")"
+# shellcheck disable=SC2086
+node bin/cli-run.mjs "$AUDIT_LANE" $AUDIT_LANE_FLAGS --brief "$BRIEF" --timeout "$RUNNER_SECS" --quiet < /dev/null > "$TMP"
+rc=$?
+if [ "$rc" -eq 0 ] && [ -s "$TMP" ]; then
+  mv -f "$TMP" "$FINAL"
+  echo "audit rc=0 lane=$AUDIT_LANE report=$FINAL"
+else
+  FAILED="reports/failed-audit-$STAMP-rc$rc.md"
+  mv -f "$TMP" "$FAILED" 2>/dev/null || rm -f "$TMP"
+  echo "audit rc=$rc lane=$AUDIT_LANE; previous report kept; partial output (if any) at $FAILED" >&2
+fi
+exit $rc

package/templates/advanced/vm/jobs/weekly-audit.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Run the ai-orchestrator weekly audit every Monday 09:00
+
+[Timer]
+OnCalendar=Mon *-*-* 09:00:00
+Persistent=true
+RandomizedDelaySec=300
+
+[Install]
+WantedBy=timers.target

package/templates/advanced/vm/setup-vm.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# setup-vm.sh: idempotent setup for a fresh Ubuntu box.
+# Installs system deps and the npm-installable agent CLIs.
+# PRINTS the vendor shell installers for the rest; never pipes a remote script into bash for you.
+# Never writes a secret. Sign-ins are the vendors' own device-code flows.
+set -euo pipefail
+
+say() { printf '\n[setup-vm] %s\n' "$*"; }
+have() { command -v "$1" >/dev/null 2>&1; }
+
+say "system packages"
+sudo apt-get update -y
+sudo apt-get install -y curl git tmux jq ca-certificates gnupg build-essential \
+  dbus-x11 libsecret-1-0 gnome-keyring   # a keyring, or headless CLIs re-prompt for auth on every launch
+
+if ! have node; then
+  say "node 22: download the NodeSource setup script, read it, then run it yourself:"
+  say "  curl -fsSL https://deb.nodesource.com/setup_22.x -o /tmp/nodesource.sh && less /tmp/nodesource.sh"
+  say "  sudo -E bash /tmp/nodesource.sh && sudo apt-get install -y nodejs"
+  exit 1
+fi
+say "node present: $(node -v)"
+
+if ! have docker; then
+  say "docker: follow https://docs.docker.com/engine/install/ubuntu/ (read the script before running it), then re-run this script"
+else
+  say "docker present: $(docker --version)"
+fi
+
+say "npm-installable CLIs (installed only if missing)"
+# Versions are pinned to what this installer was released with. Check for newer before trusting a pin forever.
+for pkg in {{NPM_PACKAGES}}; do
+  [ -z "$pkg" ] && continue   # nothing npm-installable was selected
+  case "$pkg" in
+    @anthropic-ai/claude-code*) bin=claude ;;
+    @openai/codex*) bin=codex ;;
+    @qwen-code/qwen-code*) bin=qwen ;;
+    *) bin="${pkg##*/}"; bin="${bin%%@*}" ;;
+  esac
+  if have "$bin"; then say "$bin present"; else say "npm install -g $pkg"; npm install -g "$pkg"; fi
+done
+
+say "vendor shell installers (read, then run yourself):"
+{{SCRIPT_INSTALLERS}}
+
+say "next: sign in to each CLI inside tmux (device-code flows), export the names in ENVIRONMENT.md, then: docker compose up -d"

package/templates/agents/README.md

@@ -0,0 +1,13 @@
+# templates/agents/
+
+Loading surfaces for the primary agent. The installer writes exactly one of these, based on `--primary`:
+
+| Primary | Written | Why |
+|---|---|---|
+| `claude-code` | `.claude/agents/*.md` + `CLAUDE.snippet.md` | Claude Code loads project-level subagents from that folder |
+| `agy` | `.agents/agents/*.md` + `GEMINI.snippet.md` | Antigravity custom agents live there |
+| `codex`, `qwen` | `AGENTS.snippet.md` / `QWEN.snippet.md` | those CLIs read a rules file but have no subagent folder |
+| `grok`, `hermes` | nothing agent-specific | rules travel with the prompt or the task bundle |
+| a chat app | `PASTE-INTO-YOUR-AGENT.md` | no files to load; paste into custom instructions |
+
+`snippets/` are rendered with the chosen agent's name and rules file. Nothing here is appended to a file the user already has.

package/templates/agents/agy/README.md

@@ -0,0 +1,5 @@
+# .agents/agents/
+
+Antigravity CLI custom agents, one per tier, in the `.agents/agents/<name>.md` format (YAML frontmatter + system prompt). `model` is a tier (`flash`, `pro`) or `inherit`. `subagent: true` lets a coordinator call them through `invoke_subagent`, which takes an array and launches concurrently; `mainAgent: true` lets you launch them directly with `agy --agent <name>`.
+
+`commandExecutionPolicy` is `auto` for `builder` (it has to run builds and tests; `auto` keeps deletes and other high-risk commands gated) and `off` for the read-only agents. `model` is a tier: `pro` for deep-planner, `flash` for the rest.

package/templates/agents/agy/builder.md

@@ -0,0 +1,17 @@
+---
+name: builder
+description: Well-specified execution of a bounded sub-part of a build.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: auto   # standard build/test commands run unattended; high-risk commands stay gated
+---
+
+# builder
+
+Well-specified execution of a bounded sub-part of a build.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
+- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.

package/templates/agents/agy/bulk-worker.md

@@ -0,0 +1,17 @@
+---
+name: bulk-worker
+description: High-volume mechanical work: classify, tag, extract, reformat, summarize many items.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# bulk-worker
+
+High-volume mechanical work: classify, tag, extract, reformat, summarize many items.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
+- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.

package/templates/agents/agy/code-reviewer.md

@@ -0,0 +1,17 @@
+---
+name: code-reviewer
+description: Read-only code review; findings ranked by severity with a concrete failure scenario each.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# code-reviewer
+
+Read-only code review; findings ranked by severity with a concrete failure scenario each.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
+- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.

package/templates/agents/agy/deep-planner.md

@@ -0,0 +1,17 @@
+---
+name: deep-planner
+description: Ambiguous or high-stakes thinking: architecture, strategy, hard debugging. Returns a plan; never edits code.
+model: pro
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# deep-planner
+
+Ambiguous or high-stakes thinking: architecture, strategy, hard debugging. Returns a plan; never edits code.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
+- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.

package/templates/agents/agy/live-researcher.md

@@ -0,0 +1,17 @@
+---
+name: live-researcher
+description: Fresh information through search_web and read_url_content; cites sources and retrieval time.
+model: flash
+subagent: true
+mainAgent: true
+commandExecutionPolicy: off
+---
+
+# live-researcher
+
+Fresh information through search_web and read_url_content; cites sources and retrieval time.
+
+Rules:
+- Stay inside the task bundle you were given. Anything not granted is denied.
+- Report what you did, what you did not do, and what you could not verify. "Unverified" is acceptable; a confident guess is not.
+- Token discipline: read only what the task needs, never re-read, hand back deliverables not narration.

package/templates/agents/claude-code/README.md

@@ -0,0 +1,13 @@
+# .claude/agents/
+
+Five subagents, one per tier. Claude Code loads project-level agents from this folder automatically.
+
+| Agent | Tier | Model alias | Effort | Job |
+|---|---|---|---|---|
+| deep-planner | deep | opus | xhigh | judges every build twice; never retrieves |
+| builder | standard | sonnet | high | bounded sub-parts of a build |
+| code-reviewer | standard | sonnet | high | read-only findings |
+| live-researcher | standard | sonnet | medium | fresh data through tools |
+| bulk-worker | fast | haiku | low | mechanical volume |
+
+Aliases resolve to the newest model in each family, so a version bump needs no edit here. Each agent carries its own token-discipline rule; the `effort` field is the third cost lever.

package/templates/agents/claude-code/builder.md

@@ -0,0 +1,17 @@
+---
+name: builder
+description: Well-specified execution of a bounded sub-part. Use for writing code, editing files, wiring configs, and implementing a plan that already exists. Do not use for open-ended architecture questions, bulk classification, or the main build itself.
+model: sonnet
+effort: high
+---
+
+You are the execution tier of the model router.
+
+You implement specs and plans: write code, edit files, run commands.
+
+Rules:
+- Follow the spec you were given. If the spec has a real gap, state the assumption you chose and proceed; do not redesign the architecture.
+- Lightweight, concise code. No heavy dependencies.
+- Verify your work runs (typecheck, test, or dry-run) before reporting done.
+- Report plainly: what you changed, file paths, and proof it works.
+- Token discipline: read only the files you will touch; never dump full file contents into replies, reference paths and the changed lines instead; do not re-read files you just wrote.

package/templates/agents/claude-code/bulk-worker.md

@@ -0,0 +1,18 @@
+---
+name: bulk-worker
+description: Cheap high-volume work. Use for classifying, tagging, extracting, reformatting, or summarizing many items such as posts, rows, files, or notes. Fast and low cost. Do not use for tasks needing deep judgment or code changes.
+tools: Read, Glob, Grep, Write
+model: haiku
+effort: low
+---
+
+You are the fast tier of the model router.
+
+You do high-volume mechanical work: classify, tag, extract, reformat, summarize lists.
+
+Rules:
+- Be consistent. Define your categories or format once, then apply uniformly to every item.
+- Output structured results: a markdown table or list, one row per item.
+- Do not editorialize per item. One short summary line at the end is enough.
+- If more than roughly 20 percent of items do not fit the given categories, stop and report that instead of forcing them.
+- Token discipline: identify items by index or a short stub, never echo full item text back; output the table and the one summary line, nothing else.

package/templates/agents/claude-code/code-reviewer.md

@@ -0,0 +1,19 @@
+---
+name: code-reviewer
+description: Code review. Use when asked to review code, a diff, or a repo for bugs, security issues, or quality. Read-only, returns findings. Do not use for writing or fixing code.
+tools: Read, Glob, Grep, Bash
+model: sonnet
+effort: high
+---
+
+You are the review tier of the model router.
+
+You review code for real bugs, security problems, and correctness issues.
+
+Rules:
+- Report only findings you can defend with a concrete failure scenario. No style nitpicks unless asked.
+- Rank by severity. For each: file, line, what breaks, and the fix in one or two sentences.
+- Security findings (auth, secrets, injection, exposed endpoints) always rank first. Treat every endpoint as internet-facing.
+- You are read-only. Suggest fixes; do not apply them.
+- If the code is clean, say so plainly. Do not invent findings.
+- Token discipline: read only the files under review, targeted sections where possible; report findings without restating the code; quote at most the few lines a finding needs.