@meffecta/agent 0.0.1

package/ARCHITECTURE.md

@@ -0,0 +1,197 @@
+# How the agent is put together
+
+Orientation for someone about to run a deployment. The set-up steps themselves are in
+[IMPLEMENTATION.md](IMPLEMENTATION.md); this is what those steps are building and why.
+
+## The shape
+
+```
+  this engine repo  ──CI──▶  ghcr.io/meffecta/agent   (the image; never company-specific)
+                                      │
+                                      │  scripts/deploy.sh
+                                      ▼
+   your content repo  ──cloned every run──▶  Cloud Run service   (your project, your creds)
+   jobs/ worlds/ SYSTEM.md                    ↑
+                                              └─ credentials in Secret Manager
+```
+
+The engine is a job runner: it wakes on a schedule (or a webhook, or new mail), clones the
+content repo, and hands one job's prompt to the `claude` CLI with a working directory, a
+system prompt, a set of skills and a memory directory. What the agent *does* is entirely
+in the content repo and the credentials; the engine knows nothing about any company.
+
+## Two rules that explain most of the design
+
+**The engine is generic; the content repo is yours.** Every run re-clones the content repo,
+so a pushed prompt is live on the next run — no build, no deploy. Only moving to a new
+*engine version* is a deploy. This is also why the engine repo's CI publishes an image and
+stops: when a deployment takes a new version is that deployment's call.
+
+**The agent's power is exactly its credentials.** There is no other lever. Give it a GCP
+project of its own, and add one credential at a time — every skill degrades gracefully
+when its variables are unset, so a half-configured agent is a working agent with fewer
+abilities, not a broken one. Reviewing what an agent can do means reviewing what its
+service account is invited to and what tokens sit in its Secret Manager.
+
+## What needs what
+
+| Change | Effect |
+| --- | --- |
+| Job prompts, run settings, `SYSTEM.md`, worlds, content-repo skills | **Push** — live on the next run |
+| Adding, renaming, or retriggering a job (`cron`/`webhook`/`inbox` frontmatter) | **Restart** — triggers register from a boot-time clone, plus `scripts/setup-scheduler.sh` on Cloud Run |
+| A new engine version | `scripts/deploy.sh` (which re-syncs the triggers too) |
+
+Renaming a job also moves its identity: memory lives at `<MEMORY_DIR>/jobs/<name>/`, so
+copy that directory across or the job wakes up amnesiac, and pending spawns for the old
+name die with it.
+
+## Operating a deployment
+
+Operating a deployment is one command-line tool, **`npx @meffecta/agent`**, published to
+npm alongside the engine image it deploys. Installing it is all the access an operator
+needs; the engine's source is not involved. Each release of the tool records the engine
+build it was published with, so upgrading the tool is how you move to a new engine —
+deliberately, rather than by surprise.
+
+It reads this deployment's identity from a `deployment.env` in your content repo, committed
+beside `jobs/`. Which GCP project a set of jobs runs as is a fact about that deployment,
+and none of it is secret.
+
+That makes the working shape: stand in the content repo and run the tool.
+
+```bash
+cd /path/to/acme-agent-home
+npx @meffecta/agent status
+npx @meffecta/agent deploy
+```
+
+Nothing is read from exported shell variables, so a command cannot silently act on the
+wrong deployment; each script prints the project and service it is about to touch, and
+refuses to run when it cannot find them (`--config <file>` overrides the lookup).
+
+`deployment.env` also holds the **runtime shape** — `SCALING`, `CPU`, `MEMORY`,
+`MAX_INSTANCES`, `REQUEST_TIMEOUT` — which `deploy.sh` re-asserts on every rollout. So the
+file, not the console, is the truth about how the service runs, and `SCALING` in particular
+has to stay honest: it and the triggers are one decision made in two places.
+
+Every command is one of the scripts below with a name in front of it — the CLI is the
+interface, the scripts are the implementation, and they are published together so the pair
+cannot drift. A deployment without npm can extract the scripts from the public image
+instead and run them directly.
+
+| Command / script | Does |
+| --- | --- |
+| `setup-infrastructure.sh` | one-time GCP provisioning; idempotent |
+| `setup-scheduler.sh` | the deployment's external triggers — Cloud Scheduler + Tasks; idempotent |
+| `set-artifact-cleanup.sh` | expire mirrored images in the deployment's registry |
+| `update-tooling.sh` | refresh these scripts from a published engine image |
+| `set-secret.sh` | store a value in Secret Manager and bind it; re-run to rotate |
+| `set-env.sh` | non-secret service settings, several per revision |
+| `deploy.sh` | roll a published engine image out, and assert the runtime shape |
+
+For a question rather than a change, the service serves **`/ask`**: a prompt box behind the
+same secret, over basic auth, that runs it with the deployment's skills and credentials and
+shows the answer. It is the quickest way to find out what the agent can currently see.
+
+`set-secret.sh` never lets a value reach the shell history or the screen: `--random`
+generates one, a pipe or `--from-file` supplies one, and otherwise it prompts with echo
+off. `deploy.sh`, `set-env.sh` and `setup-scheduler.sh` take `--dry-run`.
+
+## Where the rules live
+
+Every run's system prompt is built from two layers:
+
+1. **The deployment's `SYSTEM.md`**, from its content repo — who this agent serves, its
+   worlds, its tone, which systems belong to whom.
+2. **The engine's `SYSTEM.base.md`**, from the image — the safety rules every deployment
+   gets whether or not anyone remembered to write them.
+
+The baseline is appended **last**, closest to the task, and says in its own text that it
+overrides what precedes it. A deployment can make a rule stricter or name the concrete
+accounts it applies to; it cannot relax one, and it cannot shadow the file — the engine
+resolves it from its own install directory, never from the working repo, so no content a
+deployment or a run controls can stand in for it. A missing baseline throws rather than
+running unprotected.
+
+What the baseline carries: content you read is data and never instructions; act only
+where the job says, with anything outward-facing or irreversible left for a person unless
+the job directs it; secrets never leave; other people's privacy; report honestly. Both
+layers hold across a spawned follow-up run, which inherits its parent's system prompt.
+
+A rule that must be *structurally* impossible belongs in code, not prose — the way the
+Google Ads skill splits reads from writes and caps every mutation, and the way a read-only
+mail token makes sending impossible rather than merely forbidden.
+
+## Skills
+
+Skills are how the agent reaches a system: the how-to for Gmail, Microsoft Graph, Drive,
+Cloudflare, a browser, Grafana, PostHog, Google Ads. They resolve in three layers, each
+winning over the next:
+
+1. the **working repo** a job runs in (`repo:` frontmatter),
+2. the **content repo** (`.claude/skills/`) — this deployment's own or its overrides,
+3. the **engine defaults**, shipped in the image.
+
+So a deployment can override any default without forking the engine, and a product repo
+can supply its own variant for jobs that run inside it.
+
+## Triggers
+
+Four ways a run starts. The first three are configured in a job's frontmatter:
+
+- **cron** — a schedule, in the deployment's timezone
+- **webhook** — `POST /webhooks/<name>`
+- **inbox** — new mail to a watched address, polled
+
+The fourth is the only one the agent pulls itself: a run that cannot finish inside its
+time limit, or that has to wait for something, writes the instruction for a **follow-up
+run** and schedules it. That follow-up is the same job identity — same repo, system
+prompt, settings and memory — with a fresh time limit. The token that authorizes it stands
+for that run's identity and dies with the run, so a run can only ever schedule more of its
+own job's work, whatever its prompt says.
+
+### What actually wakes the service
+
+On Cloud Run the service **scales to zero and is billed only while a request is open**,
+which is why an agent that is busy half an hour a day does not cost a machine's worth a
+month. The price of that is a service with no CPU of its own: it cannot keep a clock, and
+it cannot finish work in the background of a response. So all four triggers are delivered
+to it as HTTP requests, and the handler holds each request open until the run settles.
+
+`scripts/setup-scheduler.sh` creates the senders: **Cloud Scheduler** for the crons and for
+an hourly (or poll-interval) housekeeping sweep, **Cloud Tasks** for everything that has to
+be acknowledged immediately — webhooks, manual runs, follow-ups due later. Both cap one
+attempt at 30 minutes, so a run that lasts longer spans several: the handler answers 503,
+and the retry re-attaches to the same run instead of starting another. Nothing about
+durability rests on this — the queue journal and the spawn spool on the memory bucket stay
+the record, and the sweep re-drives anything a delivery lost.
+
+The alternative shape is a machine that is always awake — a Mac mini, or a service pinned
+to `min-instances=1`. There the process keeps its own timers and needs none of the above;
+leaving `AGENT_TASKS_QUEUE` unset is what selects it. Do not do half of each: a
+scaled-to-zero service without Scheduler jobs looks healthy and runs nothing, and an
+always-on service with them fires every cron twice.
+
+## Memory and audit
+
+Each job has a memory directory it reads at the start of a run and updates at the end —
+working state, not bulk content. It lives on a mounted bucket, so it survives restarts and
+deploys.
+
+Separately, every run writes to an **audit bucket** that is never mounted and never
+readable by the agent: the prompt, the trigger, the result, and the full transcript of
+every tool call. That is where you look when a run surprises you, and it is deliberately
+out of the agent's own reach.
+
+## Where it runs
+
+Cloud Run is the default and the only place where service-account authentication works for
+the metadata-server surfaces (domain-wide delegation, GA4, Search Console, Ads, deployment
+listing). The same image runs anywhere docker does, and the service also runs natively on
+a Mac or Linux box with Node 24+, `MEMORY_DIR` pointed at a real directory and
+`NODE_ENV=production` to enable crons — keep it alive with launchd or systemd. Off Cloud
+Run, the metadata-server surfaces degrade to their fallbacks.
+
+**Run it in exactly one place at a time.** Two instances mean every cron fires twice and
+both send email — and on Cloud Run, scaling to zero is what makes the second copy tempting,
+so check that the first one is actually stopped rather than merely idle.

package/IMPLEMENTATION.md

@@ -0,0 +1,292 @@
+# Setting up a new agent
+
+Every step from nothing to a first run, in order. For how the pieces fit and why, see
+[ARCHITECTURE.md](ARCHITECTURE.md).
+
+Everything here is one command-line tool, `npx @meffecta/agent`, run from **your content
+repo** — the directory step 3 creates, which holds this deployment's jobs and its settings.
+You never need the engine's source: the tool and the engine image it deploys are published
+together, and installing the tool is all the access you need.
+
+    npx @meffecta/agent steps     # this guide, condensed to the command for each step
+
+---
+
+## 1. Create a GCP project
+
+Give the agent a project of its own, separate from any product project it will read: this
+project's service account gets project-wide secret access, and the mail tokens stored here
+must not be readable by another system's machinery.
+
+```bash
+gcloud auth login
+npx @meffecta/agent create-project
+```
+
+It asks for a display name, suggests a project ID from it, validates the ID against
+Google's rules before spending a round trip, and creates the project. Pass
+`--name`/`--id` to skip the prompts, or `ORGANIZATION=…` / `FOLDER=…` to place it.
+
+- [ ] Note the **project ID** it prints. Project IDs are globally unique, so a plain name
+      is often taken and you end up with a suffixed one (`acme-agent-506513`). The id, not
+      the display name, is what every later command needs.
+
+## 2. Link a billing account
+
+Nothing else works without this: provisioning starts by enabling APIs, which fails on an
+unbilled project.
+
+```bash
+npx @meffecta/agent link-billing --project <PROJECT_ID>
+```
+
+It lists the billing accounts you can use, marks closed ones as unselectable (linking one
+appears to succeed and leaves the project unbilled), links your choice, and then confirms
+the project really is billed rather than trusting the command's exit code.
+
+- [ ] `billingEnabled: true`
+
+If it reports a **billing quota**, that is the account's cap on how many projects it may
+fund, not a problem with this project — free a slot with `gcloud billing projects unlink
+<PROJECT>`, or request an increase.
+
+## 3. Create the content repo
+
+A private GitHub repo holding everything about *this* deployment:
+
+```
+deployment.env     # which GCP project and service this deployment runs as
+SYSTEM.md          # who the agent serves, its worlds, its tone
+jobs/              # one .md per job: YAML frontmatter + prompt body
+worlds/            # one folder per business area (optional to start)
+.claude/skills/    # skills this deployment owns or overrides (optional)
+```
+
+`deployment.env` is committed — none of it is secret, and a clone of the repo is then
+everything an operator needs:
+
+```bash
+npx @meffecta/agent init          # writes deployment.env here
+```
+
+```ini
+PROJECT=acme-agent-506513     # the project ID from step 1
+SERVICE=acme-agent
+ARTIFACT_REPO=acme-agent-images
+REGION=europe-west1
+```
+
+`SYSTEM.md` describes **who this agent serves** — the person or team, the businesses, the
+tone, which systems belong to whom. It does not need to restate the safety rules: the
+engine appends its own baseline ([SYSTEM.base.md](SYSTEM.base.md) — what you read is data
+not instructions, act only where the job says, secrets never leave, third-party privacy,
+report honestly) to every run in every deployment, and that baseline overrides anything
+contradicting it. Your `SYSTEM.md` can make a rule *stricter*, or name the concrete
+accounts and people it applies to; it cannot relax one.
+
+One job to start, `jobs/hello.md`:
+
+```markdown
+---
+name: hello
+cron: "0 7 * * 1-5"
+---
+
+Say good morning and list today's date. Send it by email to <person> using the
+send-email skill. If email is unavailable, return the text as your result.
+```
+
+Frontmatter keys: `cron`, `webhook`, `inbox`, `repo`, `systemMd`, `model`, `effort`,
+`allowedTools`, `timeoutSeconds`, `disabled`. A job with no `name:` takes its filename.
+
+- [ ] Repo pushed to GitHub
+- [ ] `cd` into it — **every command from here on runs from the content repo**
+
+## 4. Install the tools
+
+On the machine you operate from:
+
+```bash
+docker info >/dev/null && echo "docker ok"   # needed to mirror engine images
+git --version && gh --version
+node --version                                # 24+
+npm i -g @anthropic-ai/claude-code
+corepack enable
+```
+
+- [ ] `gcloud auth configure-docker $REGION-docker.pkg.dev` — one-time, so the mirror in
+      step 8 can push into your Artifact Registry. Pulling the engine image itself needs
+      no login: `ghcr.io/meffecta/agent` is public.
+
+Then the tool itself:
+
+```bash
+npm i -g @meffecta/agent      # or use npx, which needs no install
+meffecta-agent version        # names the engine build this version deploys
+```
+
+- [ ] `meffecta-agent help` lists the commands
+- [ ] `meffecta-agent version` shows a pinned engine tag, not "latest"
+
+Pin the version you install. Each release of the tool deploys the engine image published
+alongside it, so upgrading the tool is how you move to a new engine — deliberately, not by
+surprise.
+
+<details>
+<summary>No npm? The same tooling is inside the public image.</summary>
+
+```bash
+cid=$(docker create ghcr.io/meffecta/agent:latest) \
+  && docker cp "$cid:/app/scripts" . \
+  && docker rm "$cid" >/dev/null
+```
+
+That drops `scripts/` into your content repo; run `scripts/deploy.sh` and friends directly,
+and `scripts/update-tooling.sh --tag <the tag you deploy>` to refresh them. Every CLI
+command is one of these scripts with a name in front of it.
+</details>
+
+## 5. Mint the credentials
+
+```bash
+claude setup-token       # → CLAUDE_CODE_OAUTH_TOKEN, pasted in step 7
+```
+
+- [ ] `CLAUDE_CODE_OAUTH_TOKEN` — this deployment bills its own runs
+- [ ] `GITHUB_TOKEN` — fine-grained PAT with **contents read on the content repo** (the
+      service cannot start without it), plus write on any repo whose jobs open PRs
+- [ ] `AGENT_WEBHOOK_SECRET` needs nothing here — step 7 generates it
+
+**Gmail + Calendar** (skip if the agent needs no mailbox). In the agent's GCP project:
+enable the Gmail and Calendar APIs; OAuth consent screen → **External**, then **publish to
+production** — an app left in "Testing" expires refresh tokens after 7 days; create an
+OAuth client of type **Desktop app**. Then per account:
+
+```bash
+npx @meffecta/agent mint-gmail \
+  --client-id <id> --client-secret <secret> [--account <NAME>] [--readonly]
+```
+
+Sign in as the account the token is for. Default → `GMAIL_REFRESH_TOKEN`; named →
+`GMAIL_<NAME>_REFRESH_TOKEN`. Use `--readonly` for any mailbox this company does not
+administer alone.
+
+**Microsoft 365** (only if a mailbox lives there): one Entra app registration, then
+`npx @meffecta/agent mint-graph --account <NAME> …`.
+
+## 6. Provision the infrastructure
+
+```bash
+npx @meffecta/agent setup-infra
+```
+
+Idempotent — re-run it after any change. It prints the project and service it is about to
+touch, then creates: the APIs, an Artifact Registry repo, the runtime service account, a
+memory bucket (mounted at `/memory`), an audit bucket (365-day retention, write-once,
+never mounted), and the Cloud Run service shell with a placeholder image and CPU always
+allocated.
+
+- [ ] The banner names the project from your `deployment.env` — if not, you are in the
+      wrong directory
+
+## 7. Wire up the configuration
+
+`set-secret.sh` stores a value in Secret Manager and binds it to the service in one step;
+the value never reaches your shell history or the screen. Re-running it rotates a value.
+
+```bash
+npx @meffecta/agent set-secret AGENT_WEBHOOK_SECRET --random   # generated for you
+npx @meffecta/agent set-secret CLAUDE_CODE_OAUTH_TOKEN         # prompts, hidden
+npx @meffecta/agent set-secret GITHUB_TOKEN
+```
+
+- [ ] `AGENT_WEBHOOK_SECRET`
+- [ ] `CLAUDE_CODE_OAUTH_TOKEN`
+- [ ] `GITHUB_TOKEN`
+
+Non-secret settings go through `set-env` (several at once become one revision; add
+`--dry-run` to see what it would do). **The service will not boot without `GIT_REPO_URL`:**
+
+```bash
+npx @meffecta/agent set-env GIT_REPO_URL=https://github.com/<owner>/<repo>.git
+```
+
+- [ ] `GIT_REPO_URL` points at the content repo from step 3
+
+Optional, one ability each: `GMAIL_*`, `MSGRAPH_*`, `GRAFANA_*`, `CLOUDFLARE_*`,
+`POSTHOG_*`, `GOOGLE_ADS_*`, `AHREFS_API_KEY`, `<WORLD>_GA4_PROPERTY_ID`. Full list with
+comments in the engine repo's `.env.example`. Tokens and keys go through `set-secret`;
+addresses, ids and URLs through `set-env`. `meffecta-agent env` and `meffecta-agent secrets`
+show what is set — the second never prints a value.
+
+Surfaces that authenticate as the **runtime service account** rather than a token — GA4,
+Search Console, Google Ads, Cloud Run deployment listing, and delegated Gmail/Drive/
+Calendar — additionally need that service account invited on each property, and
+domain-wide delegation granted in the Workspace admin console. Leave these for last; each
+degrades gracefully until granted.
+
+## 8. Deploy the engine
+
+```bash
+npx @meffecta/agent deploy             # --dry-run first to see the target
+```
+
+Mirrors the engine image this tool version was published with into your Artifact Registry,
+rolls it out, and asserts the runtime shape from `deployment.env`. `--tag <other>` pins or
+rolls back to a different build.
+
+## 9. Create the triggers
+
+The service scales to zero and has CPU only while it is answering a request, so nothing in
+it fires on its own. This is what sends it work:
+
+```bash
+npx @meffecta/agent setup-scheduler    # --dry-run first to see what it would create
+```
+
+It creates a Cloud Tasks queue, points the service at it, and creates one Cloud Scheduler
+job per `cron:` in your content repo plus a housekeeping sweep. It reads the job list from
+the running service, so step 8 has to have succeeded first.
+
+- [ ] It reports one trigger per cron job, plus `<service>-sweep`
+- [ ] `npx @meffecta/agent triggers` agrees, and shows the task queue running
+
+Re-run it whenever a job's `cron:` changes or a job is added or renamed — `deploy` does it
+for you on every rollout from here on. Check it any time with `meffecta-agent triggers`.
+
+## 10. Verify
+
+```bash
+npx @meffecta/agent status
+npx @meffecta/agent jobs
+```
+
+- [ ] `status` shows a ready revision, your triggers, and an idle queue
+- [ ] `jobs` lists your jobs — this proves the boot clone worked. An empty list means
+      `GIT_REPO_URL` is wrong or `GITHUB_TOKEN` cannot clone it.
+
+Then exercise every configured credential from inside the deployment:
+
+```bash
+npx @meffecta/agent ask "run node /app/scripts/verify-credentials.mjs and return its output"
+```
+
+- [ ] Each surface reports ok or skip; no FAIL (`skip` = not configured, which is fine)
+
+The same thing has a web page, for anyone who would rather not use a terminal: open
+`/ask` on the service URL that `status` printed. Any username, the secret as the password.
+
+- [ ] The page loads and an answer comes back
+
+## 11. First real run
+
+```bash
+npx @meffecta/agent run hello
+npx @meffecta/agent logs --limit 50
+```
+
+- [ ] Read what it produced before letting the cron take over
+
+Then add jobs one at a time — each push is live on the next run. `disabled: true` in
+frontmatter is the kill switch, effective on push. Every prompt, result and full
+transcript lands in the audit bucket.

package/README.md

@@ -0,0 +1,64 @@
+# @meffecta/agent
+
+Set up and operate a **Meffecta Agent** deployment — a self-hosted Claude Code job runner
+that wakes on a schedule, a webhook, or new mail, and runs a job against a fresh clone of
+your own content repo.
+
+The agent itself is a container image (`ghcr.io/meffecta/agent`). This package is the tool
+that stands one up and runs it, and it is all you need: the engine's source is private,
+and nothing here depends on it.
+
+```bash
+npx @meffecta/agent steps      # the whole set-up, in order
+npx @meffecta/agent help       # every command
+```
+
+## What it does
+
+Run it from your **content repo** — the directory holding `deployment.env`, `jobs/`,
+`worlds/` and `SYSTEM.md`. That file says which GCP project and Cloud Run service this
+deployment is, so a command can never quietly act on the wrong one.
+
+```bash
+npx @meffecta/agent create-project        # a GCP project
+npx @meffecta/agent link-billing          # attach billing
+npx @meffecta/agent setup-infra           # registry, buckets, service account, service
+npx @meffecta/agent set-secret AGENT_WEBHOOK_SECRET --random
+npx @meffecta/agent set-env GIT_REPO_URL=https://github.com/you/your-content-repo.git
+npx @meffecta/agent deploy                # roll out the engine
+npx @meffecta/agent setup-scheduler       # give it its triggers
+```
+
+Then, day to day:
+
+```bash
+npx @meffecta/agent status                # revision, shape, triggers, queue
+npx @meffecta/agent jobs                  # what is registered, and what triggers it
+npx @meffecta/agent env                   # every setting (secret values never printed)
+npx @meffecta/agent secrets               # what is stored, and what the service reads
+npx @meffecta/agent triggers              # the Cloud Scheduler jobs and task queue
+npx @meffecta/agent logs --limit 100
+npx @meffecta/agent run morning-brief
+npx @meffecta/agent ask "how did search do last week"
+```
+
+## Two things worth knowing
+
+**The version you install is the engine you deploy.** Each release records the engine build
+published alongside it, and `deploy` defaults to that image. Tooling and engine move
+together, so a script can never provision the wrong shape for the engine it is aimed at.
+`meffecta-agent version` tells you which pair you have.
+
+**Secret values are never printed.** `secrets` lists what exists and whether the service
+reads it; `env` names secret-backed settings without resolving them. Setting one takes the
+value from a pipe, a file, or a hidden prompt — never from your shell history.
+
+## Requirements
+
+`gcloud` (authenticated), `docker` (to mirror engine images into your registry), `git`,
+and Node 20+. macOS or Linux.
+
+## Documentation
+
+`IMPLEMENTATION.md` and `ARCHITECTURE.md` ship inside this package — the full set-up, and
+how the pieces fit.

package/bin/meffecta-agent.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { COMMANDS, cliVersion, engineTag, GROUPS } from "../lib/commands.js";
+import { loadDeployment, UserError } from "../lib/config.js";
+
+/**
+ * One entry point for everything an operator does to a Meffecta Agent deployment.
+ *
+ * The engine itself is a container image; this is the tool that stands one up and runs it.
+ * Most commands are the shipped shell scripts with a name in front of them — the CLI is
+ * the interface, those scripts are the implementation, and they travel together in this
+ * package so the pair cannot drift.
+ *
+ * No runtime dependencies, on purpose: `npx @meffecta/agent` should be one download, and
+ * a tool that holds someone's cloud credentials is a poor place for a supply chain.
+ */
+
+const STEPS = [
+  ["create-project", "A new GCP project."],
+  ["link-billing", "Attach a billing account, or nothing can run."],
+  ["", "Create your content repo — jobs/, worlds/, SYSTEM.md, deployment.env."],
+  ["", "Install gcloud, docker, git, node 24+, and the claude CLI."],
+  ["mint-gmail", "Credentials: claude setup-token, then a token per mail account."],
+  ["setup-infra", "Provision GCP and the Cloud Run service shell."],
+  ["set-secret", "AGENT_WEBHOOK_SECRET --random, CLAUDE_CODE_OAUTH_TOKEN, GITHUB_TOKEN."],
+  ["set-env", "GIT_REPO_URL=… — the service will not boot without it."],
+  ["deploy", "Roll out the engine image."],
+  ["setup-scheduler", "Give it its triggers. Scaled to zero, it fires nothing without them."],
+  ["status", 'Check it. Then: jobs, run <job>, ask "…".'],
+];
+
+function help() {
+  const { tag, pinned } = engineTag();
+  console.log("meffecta-agent — set up and operate a Meffecta Agent deployment\n");
+  console.log("Usage: meffecta-agent <command> [options]");
+  console.log("       npx @meffecta/agent <command> [options]\n");
+  console.log("Run it from your content repo — the directory holding deployment.env and jobs/.\n");
+  for (const group of GROUPS) {
+    console.log(`${group.title}:`);
+    const width = Math.max(...group.commands.map(([name]) => name.length));
+    for (const [name, summary] of group.commands) {
+      console.log(`  ${name.padEnd(width)}  ${summary}`);
+    }
+    console.log("");
+  }
+  console.log("  steps                 The whole set-up, in order, with the command for each");
+  console.log("  version               This CLI and the engine build it deploys\n");
+  console.log("Every command takes --help, and passes its options through to the underlying");
+  console.log("script — so `meffecta-agent deploy --dry-run` and `--tag <sha>` work as documented.\n");
+  console.log(`Engine: ghcr.io/meffecta/agent:${tag}${pinned ? " (pinned to this release)" : ""}`);
+}
+
+function steps() {
+  console.log("Setting up a deployment, in order. The full text is IMPLEMENTATION.md.\n");
+  STEPS.forEach(([command, note], index) => {
+    const label = `${String(index + 1).padStart(2)}.`;
+    console.log(`${label} ${note}`);
+    if (command) {
+      console.log(`    meffecta-agent ${command}`);
+    }
+    console.log("");
+  });
+  console.log("Each step is checkable: `meffecta-agent status` after the last one should show");
+  console.log("your triggers, and `meffecta-agent jobs` your jobs.");
+}
+
+function version() {
+  const { tag, pinned } = engineTag();
+  const deployment = loadDeployment();
+  console.log(`@meffecta/agent ${cliVersion()}`);
+  console.log(
+    `engine          ghcr.io/meffecta/agent:${tag}${pinned ? "" : " (not pinned — a checkout, not a release)"}`,
+  );
+  if (deployment.PROJECT) {
+    console.log(`deployment      ${deployment.SERVICE} in ${deployment.PROJECT} (${deployment.REGION})`);
+  }
+}
+
+const [name, ...args] = process.argv.slice(2);
+
+if (!name || name === "help" || name === "--help" || name === "-h") {
+  help();
+  process.exit(0);
+}
+if (name === "steps") {
+  steps();
+  process.exit(0);
+}
+if (name === "version" || name === "--version" || name === "-v") {
+  version();
+  process.exit(0);
+}
+
+const command = COMMANDS.get(name);
+if (!command) {
+  const near = [...COMMANDS.keys()].filter((candidate) => candidate.startsWith(name.slice(0, 3)));
+  console.error(`Unknown command: ${name}`);
+  if (near.length > 0) {
+    console.error(`Did you mean: ${near.join(", ")}?`);
+  }
+  console.error("Run `meffecta-agent help` for the list.");
+  process.exit(2);
+}
+
+try {
+  // deploy defaults to the engine built alongside this release, so tooling and engine
+  // match unless the operator deliberately asks for something else.
+  if (name === "deploy" && !args.includes("--tag") && !args.includes("--image")) {
+    const { tag, pinned } = engineTag();
+    if (pinned) {
+      args.push("--tag", tag);
+    }
+  }
+  process.exit((await command.handler(args)) ?? 0);
+} catch (err) {
+  if (err instanceof UserError) {
+    console.error(err.message);
+    process.exit(1);
+  }
+  throw err;
+}