@meffecta/agent 1.0.10 → 1.0.11

package/README.md

@@ -92,7 +92,6 @@ not consent. Secret values are never printed, by any command.
 ## Operating it
 
 ```bash
-npx @meffecta/agent steps      # the set-up, in order
 npx @meffecta/agent help       # every command — each also takes --help
 npx @meffecta/agent doctor     # the one to run when something feels wrong
 ```

package/bin/meffecta-agent.js

@@ -18,40 +18,14 @@ import { installMethod } from "../lib/version.js";
 
 // Tools first: every command below needs gcloud, and the very first one already does. The
 // claude CLI is the odd one out — it is used once, to mint the token, and never again.
-const STEPS = [
-  [
-    "",
-    "Install gcloud, docker, node 24+ and git. Also the claude CLI — it is\n    used once, for the token two steps down, and not after that.",
-  ],
-  [
-    "create-project",
-    "A new GCP project. This and the next step are per GCP account, not\n    per deployment — skip both if you are adding a second agent to a project you\n    already have.",
-  ],
-  ["link-billing", "Attach a billing account, or nothing can run."],
-  [
-    "mint-gmail",
-    "Credentials: `claude setup-token`, a GitHub token that can clone your repos,\n    and — only if this agent reads or sends mail — one token per mailbox.",
-  ],
-  [
-    "init",
-    "Create your content repo — jobs/, SYSTEM.md, systems/, and a deployment.env in it.\n    Run everything from there; it is what says which deployment you mean.",
-  ],
-  ["setup-infra", "Provision GCP, the run queue, and the Cloud Run service shell.\n    --dry-run shows it first."],
-  ["set-secret", "AGENT_API_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, then create its triggers — scaled to zero it fires\n    nothing without them, and only the running engine knows which jobs exist.",
-  ],
-  ["doctor", '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");
+  console.log("Run it from your content repo — the directory holding deployment.env and jobs/.");
+  console.log("Setting one up for the first time: https://agent.meffecta.com\n");
   for (const group of GROUPS) {
     console.log(`${group.title}:`);
     const width = Math.max(...group.commands.map(([name]) => name.length));
@@ -63,7 +37,6 @@ function help() {
     }
     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");
   console.log("  upgrade               Whether a newer one is out, and what to run\n");
   console.log("Every command takes --help, and every option it documents — so");
@@ -71,20 +44,6 @@ function help() {
   console.log(`Engine: ghcr.io/meffecta/agent:${tag}${pinned ? " (pinned to this release)" : ""}`);
 }
 
-function steps() {
-  console.log("Setting up a deployment, in order.\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 doctor` after the last one should come");
-  console.log("back clean, and `meffecta-agent jobs` should list your jobs.");
-}
-
 function version() {
   const { tag, pinned } = engineTag();
   const deployment = loadDeployment();
@@ -104,7 +63,7 @@ const { analytics, firstRun } = openAnalytics({ version: cliVersion() });
 // The name is matched against the known commands before it is ever recorded. Whatever an
 // operator actually typed is theirs — a mistyped command could be anything, including
 // something they would not want leaving the machine.
-const BUILT_IN = new Set(["help", "steps", "version"]);
+const BUILT_IN = new Set(["help", "version"]);
 function recorded(candidate) {
   if (!candidate) {
     return "help";
@@ -146,10 +105,6 @@ if (!name || name === "help" || name === "--help" || name === "-h") {
   help();
   await finish(0, "ok");
 }
-if (name === "steps") {
-  steps();
-  await finish(0, "ok");
-}
 if (name === "version" || name === "--version" || name === "-v") {
   version();
   await finish(0, "ok");

package/deployment.env.example

@@ -20,20 +20,12 @@ PROJECT=acme-agent-123456
 # The Cloud Run service.
 SERVICE=acme-agent
 
-# Docker repo in that project, holding images mirrored from GHCR.
+# A repository in that project standing in front of ghcr.io. Cloud Run can only pull from
+# Artifact Registry, so this is how it reaches the engine image: AR fetches the public
+# image itself, on demand, and caches it. Nothing is copied by hand and no docker is
+# needed on your machine at any point.
 ARTIFACT_REPO=acme-agent-images
 
-# How the engine image reaches Cloud Run, which can only pull from Artifact Registry.
-#   proxy  (default) ARTIFACT_REPO is a remote repository in front of ghcr.io. AR fetches
-#          the public engine image on demand — nothing is copied, and no docker is needed
-#          on your machine at any point.
-#   mirror the older path: pull from ghcr.io here, retag, push. Needs docker running and
-#          `gcloud auth configure-docker <region>-docker.pkg.dev`, and pushes several GB
-#          per engine version. Use it only if your policy forbids AR reaching the internet.
-# A repository's mode is fixed when it is created, so changing this means a new
-# ARTIFACT_REPO name and another setup-infrastructure run.
-REGISTRY_MODE=proxy
-
 REGION=europe-west1
 
 # Optional. Unset = whichever account gcloud is logged in as. Set it when you work across
@@ -43,9 +35,6 @@ REGION=europe-west1
 # Optional. The service's TIMEZONE env var, which is what cron schedules are read in.
 # TIMEZONE=Europe/Stockholm
 
-# Optional. Where published engine images come from.
-# GHCR_IMAGE=ghcr.io/meffecta/agent
-
 # Optional. The runtime shape asserted on every rollout, so the deployed service
 # matches this file rather than whatever was last changed by hand. The defaults below are
 # what `meffecta-agent setup-infra` provisions, so leaving them out is the same as setting

package/engine.json

@@ -1,4 +1,4 @@
 {
-  "engineTag": "1.0.10",
-  "builtFrom": "36d54c192cfa454f2e4485414ac854b3be86c8f7"
+  "engineTag": "1.0.11",
+  "builtFrom": "c0f07973f25a4d8872a3e4dd28c44cd94f2e87a7"
 }

package/lib/commands.js

@@ -52,8 +52,8 @@ export function engineTag() {
     const { engineTag: tag, builtFrom } = JSON.parse(readFileSync(file, "utf8"));
     // Only a release is pinned. `npm pack` run by hand writes this file into the working
     // tree with builtFrom "local", where it would otherwise survive and pin `deploy` to a
-    // version that was never published — the image is not there and the mirror fails with
-    // nothing to say why that tag was chosen.
+    // version that was never published, where the pull fails with nothing to say why that
+    // tag was chosen.
     if (!tag || builtFrom === "local" || existsSync(resolve(packageRoot, "..", "src", "index.ts"))) {
       return { tag: "latest", pinned: false };
     }
@@ -584,13 +584,65 @@ Set the values with \`meffecta-agent set-secret <NAME>\` (credentials) or
 systems the engine already has skills for and walks through each.
 `;
 
+/**
+ * The deployment prompt, put in front of every job's own prompt. A starter rather than an
+ * empty file, because the engine's baseline already states how a run works, what a run may
+ * act on and what it may never say — so what is left is the half only this organisation can
+ * write, and a blank file gives no hint which half that is.
+ */
+const SYSTEM_EXAMPLE = `# Who you work for
+
+Replace all of this. It goes in front of every job's prompt, so it is for what holds across
+all of them and only that — rules, not facts. What the agent should KNOW about a business
+belongs in \`worlds/\`.
+
+You work for **Acme AB**. You report to **Alex Doe, alex@acme.com**, and your output is for
+Alex unless the job you are running names someone else.
+
+## How to write
+
+- Lead with what you found. No preamble, and do not restate the task.
+- Short. This gets read between meetings.
+- One thing you are unsure of, said plainly, is worth more than three you are not.
+
+## People
+
+- Alex Doe, alex@acme.com — runs the company. Everything comes here by default.
+`;
+
+/**
+ * A first job that proves the whole path — clone, system prompt, register, memory — and
+ * reaches nothing real while doing it. Named to match \`systems/example.md\`: both are the
+ * shape of the thing, shown once, and deleted when a real one exists.
+ *
+ * No \`cron:\`, deliberately. A scaffolded job that started firing on a schedule the moment
+ * the service booted would be the wrong first impression of what these files do.
+ */
+const JOB_EXAMPLE = `---
+model: sonnet
+---
+
+A first run, to prove the plumbing. It reaches no real system and changes nothing.
+
+Report, in under ten lines:
+
+1. Who you work for — one line, from \`SYSTEM.md\`.
+2. What you can reach — every file in \`systems/\`, and for each one whether the variables it
+   requires are set. **Names and set/unset only, never a value.** A system whose variables
+   are missing is one you would report as unavailable.
+3. Where your memory directory is, and whether \`MEMORY.md\` is in it yet.
+
+Then add one dated line to your \`MEMORY.md\` saying this ran.
+
+When you have a real job, write it in a file of its own and delete this one. The frontmatter
+above the \`---\` is the settings; everything below it is what you would have said to a
+colleague.
+`;
+
 async function init(args) {
-  const { copyFileSync, existsSync: exists, writeFileSync } = await import("node:fs");
-  const target = resolve(process.cwd(), "deployment.env");
-  if (exists(target) && !args.includes("--force")) {
-    console.log(`deployment.env already exists here. Leaving it alone (--force to replace).`);
-    return 0;
-  }
+  const { copyFileSync, existsSync: exists, mkdirSync, writeFileSync } = await import("node:fs");
+  const force = args.includes("--force");
+
   const template = [
     resolve(packageRoot, "deployment.env.example"),
     resolve(packageRoot, "..", "deployment.env.example"),
@@ -598,28 +650,55 @@ async function init(args) {
   if (!template) {
     throw new UserError("The deployment.env template is missing from this install — reinstall @meffecta/agent.");
   }
-  copyFileSync(template, target);
-  console.log("✅ Wrote deployment.env here.\n");
-  console.log("Fill in PROJECT and SERVICE — those two are never guessed — then commit it.");
-  console.log("It belongs in your content repo, beside jobs/, because which GCP project a");
-  console.log("set of jobs runs as is a fact about the deployment and none of it is secret.\n");
-
-  // The register is read by the agent itself at run time, not just by people: the skills
-  // are shared across deployments and name no deployment's variables, so without it a run
-  // knows how a system works and not which variable holds its credential.
-  const { mkdirSync } = await import("node:fs");
-  const registerDir = resolve(process.cwd(), "systems");
-  if (exists(registerDir)) {
-    console.log("systems/ already exists here. Leaving it alone.\n");
-  } else {
-    mkdirSync(registerDir, { recursive: true });
-    writeFileSync(resolve(registerDir, "example.md"), REGISTER_EXAMPLE);
-    console.log("✅ Wrote systems/example.md — the register of what this agent can reach.\n");
-    console.log("One file per system, added as you connect each one. The agent reads them at");
-    console.log("run time to find out which variable holds which credential, so a system with");
-    console.log("no file here is one it will report as unavailable.\n");
-  }
-  console.log("Next: meffecta-agent steps");
+
+  // Four artifacts, each decided on its own. `init` is run in a repo that already holds
+  // some of them — after an upgrade, or because a first attempt stopped halfway — and one
+  // file being present must not decide the fate of the other three.
+  const SCAFFOLD = [
+    ["deployment.env", "which GCP project and service this deployment is", (to) => copyFileSync(template, to)],
+    [
+      "SYSTEM.md",
+      "who the agent works for — read at the start of every run",
+      (to) => writeFileSync(to, SYSTEM_EXAMPLE),
+    ],
+    [
+      "systems/example.md",
+      "one file per system it may reach, and the variables for each",
+      (to) => writeFileSync(to, REGISTER_EXAMPLE),
+    ],
+    ["jobs/example.md", "one file per job: a few settings, then the prompt", (to) => writeFileSync(to, JOB_EXAMPLE)],
+  ];
+
+  const wrote = [];
+  const kept = [];
+  for (const [name, purpose, produce] of SCAFFOLD) {
+    const to = resolve(process.cwd(), name);
+    if (exists(to) && !force) {
+      kept.push([name, purpose]);
+      continue;
+    }
+    mkdirSync(dirname(to), { recursive: true });
+    produce(to);
+    wrote.push([name, purpose]);
+  }
+
+  const pad = Math.max(...SCAFFOLD.map(([name]) => name.length)) + 2;
+  for (const [name, purpose] of wrote) {
+    console.log(`✅ ${name.padEnd(pad)}${purpose}`);
+  }
+  for (const [name, purpose] of kept) {
+    console.log(`•  ${name.padEnd(pad)}${purpose} — already here, left alone`);
+  }
+  if (kept.length && !force) {
+    console.log("\n--force replaces the ones already here.");
+  }
+
+  console.log("\nFill in PROJECT and SERVICE in deployment.env — those two are never guessed —");
+  console.log("and say who the agent works for in SYSTEM.md. Both example files are the shape of");
+  console.log("the thing: rename them after something real, and delete what is left.");
+  console.log("\nThen commit all of it. None of it is secret, and a clone of this repo is");
+  console.log("everything an operator needs.");
+  console.log("\nThe set-up in order, with the command for each part: https://agent.meffecta.com");
   return 0;
 }
 
@@ -640,7 +719,7 @@ export const GROUPS = [
     // next group so a first deployment is not a shopping list.
     title: "Stand one up (once, in order)",
     commands: [
-      ["init", "Start a deployment.env here, from the template", init],
+      ["init", "Scaffold a content repo here: deployment.env, SYSTEM.md, systems/, jobs/", init],
       [
         "setup-infra",
         "Provision GCP: registry, buckets, service account, run queue, service shell",
@@ -668,7 +747,7 @@ export const GROUPS = [
         script("mint-gmail-token.mjs"),
       ],
       ["mint-graph", "A Microsoft Graph refresh token, per mailbox", script("mint-graph-token.mjs")],
-      ["artifact-cleanup", "Expire mirrored images in the deployment's registry", script("set-artifact-cleanup.sh")],
+      ["artifact-cleanup", "Expire cached images in the deployment's registry", script("set-artifact-cleanup.sh")],
     ],
     note: [
       "A new credential is `set-secret` again, plus `set-env` for whatever names the",

package/lib/doctor.js

@@ -439,7 +439,7 @@ export async function doctor() {
     } else {
       r.warn(
         "No registry cleanup policy",
-        "Mirrored engine images accumulate; they are a cache of GHCR and can be expired freely.",
+        "Cached engine images accumulate; they are a copy of GHCR and can be expired freely.",
         "meffecta-agent artifact-cleanup",
       );
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meffecta/agent",
-  "version": "1.0.10",
+  "version": "1.0.11",
   "description": "Set up and operate a Meffecta Agent deployment — a self-hosted Claude Code job runner.",
   "type": "module",
   "bin": {

package/scripts/deploy.sh

@@ -7,18 +7,10 @@ set -euo pipefail
 # new engine version is the deployment's call, not the engine repo's. This script is
 # that call, and it is the same script for the vendor's own instance and for a client's.
 #
-# Cloud Run can only pull from Artifact Registry, never from GHCR directly, so an image
-# has to reach the deployment's own AR first. Two ways:
-#
-#   1. Mirror (default here): pull from GHCR, retag, push to AR. Needs docker locally,
-#      plus `gcloud auth configure-docker <region>-docker.pkg.dev` once, and — for a
-#      private GHCR package — `docker login ghcr.io` with a PAT that has read:packages.
-#   2. AR remote repository: a one-time pull-through proxy of GHCR in the deployment's
-#      project, after which no local docker is involved. Then point --image straight at
-#      the proxied path and skip the mirror:
-#        gcloud artifacts repositories create ghcr-remote --repository-format=docker \
-#          --mode=remote-repository --location=<region> \
-#          --remote-docker-repo=https://ghcr.io   # + upstream creds for a private package
+# Cloud Run can only pull from Artifact Registry, never from GHCR directly. ARTIFACT_REPO
+# is a remote repository standing in front of ghcr.io, so a tag resolves to a path inside
+# it and Artifact Registry fetches the public engine image itself, on demand. Nothing is
+# copied by hand and no docker is involved — not here, not in CI.
 #
 # What it writes, and what it deliberately does not.
 #
@@ -71,62 +63,14 @@ require_gcloud
 resolve_deployment
 announce_target "Deploying ${SERVICE}"
 
-# --image is taken as-is. Otherwise --tag resolves against this deployment's registry, and
-# how it gets there depends on REGISTRY_MODE: `proxy` names the image inside a remote
-# repository and lets Artifact Registry fetch it on demand; `mirror` pulls and pushes it
-# from here, which is the only path that needs docker.
-if [ -z "${IMAGE}" ] && [ "${REGISTRY_MODE}" = "proxy" ]; then
-  # A remote repository preserves the upstream path, so ghcr.io/meffecta/agent is served at
-  # <repo>/meffecta/agent. Nothing is copied and nothing is pushed: the first pull populates
-  # AR's cache, and Cloud Run's own pull is what triggers it.
+# --image is taken as-is. Otherwise --tag resolves to a path inside the deployment's own
+# remote repository, which preserves the upstream one: ghcr.io/meffecta/agent is served at
+# <repo>/meffecta/agent. Nothing is copied and nothing is pushed — Cloud Run's own pull is
+# what populates the cache.
+if [ -z "${IMAGE}" ]; then
   IMAGE="${REGION}-docker.pkg.dev/${PROJECT}/${ARTIFACT_REPO}/${GHCR_PATH}:${TAG}"
   echo "🔗 Through the registry proxy: ${IMAGE}"
   echo "   (Artifact Registry fetches ${GHCR_IMAGE}:${TAG} on demand — no local docker)"
-elif [ -z "${IMAGE}" ]; then
-  SOURCE="${GHCR_IMAGE}:${TAG}"
-  IMAGE="${REGION}-docker.pkg.dev/${PROJECT}/${ARTIFACT_REPO}/${SERVICE}:${TAG}"
-  command -v docker >/dev/null || {
-    echo "docker is required to mirror ${SOURCE} into Artifact Registry." >&2
-    echo "REGISTRY_MODE=proxy in deployment.env avoids it entirely — Artifact Registry" >&2
-    echo "fetches from ghcr.io itself. After changing it, re-run:" >&2
-    echo "  $(cmd setup-infra)" >&2
-    exit 1
-  }
-  echo "📥 Mirroring ${SOURCE} → ${IMAGE}"
-  if [ "${DRY_RUN}" = true ]; then
-    echo "   (dry run: would pull, retag and push)"
-  else
-    if ! docker pull "${SOURCE}"; then
-      cat >&2 <<EOF
-
-Could not pull ${SOURCE}.
-
-The published engine image is public, so this needs no login — check the tag exists
-and that the host can reach ghcr.io:
-
-    curl -sS "https://ghcr.io/token?scope=repository:meffecta/agent:pull&service=ghcr.io"
-
-If you are pointing GHCR_IMAGE at a private package of your own instead, that one does
-need a token with the read:packages scope, which the gh CLI does not request by default:
-
-    gh auth refresh -h github.com -s read:packages
-    gh auth token | docker login ghcr.io -u <your-github-username> --password-stdin
-EOF
-      exit 1
-    fi
-    docker tag "${SOURCE}" "${IMAGE}"
-    if ! docker push "${IMAGE}"; then
-      cat >&2 <<EOF
-
-Could not push to ${IMAGE}.
-
-Artifact Registry needs docker configured for this region once:
-
-    gcloud auth configure-docker ${REGION}-docker.pkg.dev
-EOF
-      exit 1
-    fi
-  fi
 fi
 
 # scale-to-zero is the default and what sync-triggers.sh's triggers assume: no CPU

package/scripts/lib/deployment.sh

@@ -64,13 +64,11 @@ resolve_deployment() {
   load_deployment_config
   REGION="${REGION:-europe-west1}"
   ARTIFACT_REPO="${ARTIFACT_REPO:-${SERVICE:-agent}-images}"
+  # Where the published engine images are. An environment override exists for building
+  # against a fork of the engine, and is deliberately not a deployment.env setting: a
+  # deployment points at the engine, and choosing a different one is not a thing to
+  # configure by editing a committed file.
   GHCR_IMAGE="${GHCR_IMAGE:-ghcr.io/meffecta/agent}"
-  # How the engine image reaches Cloud Run, which can only ever pull from Artifact
-  # Registry. `proxy` makes ARTIFACT_REPO a remote repository in front of ghcr.io, so AR
-  # fetches on demand and no local docker is involved at all. `mirror` is the older path:
-  # pull from ghcr.io on the operator's machine, retag, push — which needs docker, and
-  # pushes several gigabytes for every engine version.
-  REGISTRY_MODE="${REGISTRY_MODE:-proxy}"
   GHCR_PATH="${GHCR_IMAGE#*/}"   # ghcr.io/meffecta/agent → meffecta/agent
   TIMEZONE="${TIMEZONE:-Europe/Stockholm}"
 

package/scripts/set-artifact-cleanup.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 # Stop a deployment's Artifact Registry filling up with engine images it will never use
 # again.
 #
-# The images there are a **cache**, not an archive: deploy.sh mirrors them from
+# The images there are a **cache**, not an archive: Artifact Registry fetches them from
 # ghcr.io/meffecta/agent because Cloud Run cannot pull from GHCR directly. GHCR keeps the
 # real copies, so anything deleted here comes back on the next `deploy.sh --tag <that one>`.
 # That is what makes an aggressive policy correct for this repo and wrong for a repo whose

package/scripts/setup-infrastructure.sh

@@ -119,33 +119,26 @@ run ${GC} services enable \
   analyticsdata.googleapis.com \
   iam.googleapis.com
 
-echo "🐳 Artifact Registry repo (${REGISTRY_MODE})..."
+echo "🐳 Artifact Registry repo..."
 if ! ${GC} artifacts repositories describe "${ARTIFACT_REPO}" --location="${REGION}" &>/dev/null; then
-  if [ "${REGISTRY_MODE}" = "proxy" ]; then
-    # A remote repository standing in front of ghcr.io. Cloud Run can only pull from
-    # Artifact Registry, and this is how that requirement is met without a local docker:
-    # AR fetches the public engine image itself, on demand, and caches it. No upstream
-    # credentials — the engine package is public, which is what makes this the simple path.
-    run ${GC} artifacts repositories create "${ARTIFACT_REPO}" --location="${REGION}" \
-      --repository-format=docker --mode=remote-repository \
-      --remote-docker-repo="https://${GHCR_IMAGE%%/*}" \
-      --description="Proxy of ${GHCR_IMAGE%%/*} — the engine image is fetched on demand"
-  else
-    run ${GC} artifacts repositories create "${ARTIFACT_REPO}" --location="${REGION}" --repository-format=docker
-  fi
+  # A remote repository standing in front of ghcr.io. Cloud Run can only pull from
+  # Artifact Registry, and this is how that requirement is met without any docker: AR
+  # fetches the public engine image itself, on demand, and caches it. No upstream
+  # credentials, because the engine package is public.
+  run ${GC} artifacts repositories create "${ARTIFACT_REPO}" --location="${REGION}" \
+    --repository-format=docker --mode=remote-repository \
+    --remote-docker-repo="https://${GHCR_IMAGE%%/*}" \
+    --description="Proxy of ${GHCR_IMAGE%%/*} — the engine image is fetched on demand"
 else
   ACTUAL_MODE=$(${GC} artifacts repositories describe "${ARTIFACT_REPO}" --location="${REGION}" --format='value(mode)')
-  case "${ACTUAL_MODE}:${REGISTRY_MODE}" in
-    REMOTE_REPOSITORY:proxy|STANDARD_REPOSITORY:mirror) ;;
-    *)
-      # A repository's mode is fixed at creation, so this is not something to "fix" here —
-      # deploy.sh would resolve an image path the repository cannot serve, and the failure
-      # would arrive as a Cloud Run pull error with nothing pointing back to this.
-      echo "⚠ ${ARTIFACT_REPO} is a ${ACTUAL_MODE} but REGISTRY_MODE=${REGISTRY_MODE}." >&2
-      echo "  A repository's mode cannot be changed. Either set REGISTRY_MODE to match, or" >&2
-      echo "  name a different ARTIFACT_REPO in deployment.env and re-run this." >&2
-      ;;
-  esac
+  if [ "${ACTUAL_MODE}" != "REMOTE_REPOSITORY" ]; then
+    # A repository's mode is fixed at creation, so this is not something to "fix" here —
+    # deploy.sh would resolve an image path the repository cannot serve, and the failure
+    # would arrive as a Cloud Run pull error with nothing pointing back to this.
+    echo "⚠ ${ARTIFACT_REPO} is a ${ACTUAL_MODE}, which cannot serve the engine image." >&2
+    echo "  A repository's mode cannot be changed. Name a different ARTIFACT_REPO in" >&2
+    echo "  deployment.env and re-run this." >&2
+  fi
 fi
 # The images here are a cache of ghcr.io/meffecta/agent, not an archive, so they are worth
 # expiring — see set-artifact-cleanup.sh for why that is safe and what the policy keeps.
@@ -198,8 +191,8 @@ if ! ${GC} iam service-accounts describe "${DEPLOY_SA}" &>/dev/null; then
     sleep 5
   done
 fi
-# What a DEPLOY needs, and nothing a BUILD would: roll out a revision, pull (or in mirror
-# mode push) the engine image, and read this project's enabled services.
+# What a DEPLOY needs, and nothing a BUILD would: roll out a revision, pull the engine
+# image, and read this project's enabled services.
 #
 # Deliberately NOT granted: secretmanager.secretAccessor. deploy.sh re-syncs the Cloud
 # Scheduler triggers, and that step reads the API secret — so a CI deploy runs
@@ -334,7 +327,7 @@ if has_cli; then
   echo ""
   echo "     ${MEFFECTA_CLI} connect            # lists them; connect <name> walks through one"
   echo ""
-  echo "   ${MEFFECTA_CLI} steps     the whole set-up, in order"
+  echo "   The whole set-up, in order: https://agent.meffecta.com"
   echo "   ${MEFFECTA_CLI} doctor    what is still missing, once something is running"
 fi
 if [ "${SETUP_CI_DEPLOY}" = "true" ]; then

package/scripts/update-tooling.sh

@@ -6,8 +6,8 @@ set -euo pipefail
 # The engine's source repo is private; the image is not. The operator tooling — these
 # scripts and the config template — ships inside ghcr.io/meffecta/agent, so a deployment run
 # by someone outside Meffecta gets its tooling from the same public artifact it gets its
-# engine from, and never needs the source. What a deployment is documented by is the CLI's
-# own help: `meffecta-agent help` and `meffecta-agent steps`.
+# engine from, and never needs the source. A deployment is documented by
+# https://agent.meffecta.com and by the CLI's own `meffecta-agent help`.
 #
 # The tooling belongs in your content repo, committed next to jobs/ and deployment.env.
 # That is what makes a fresh clone of that repo enough to operate the deployment, and it
@@ -26,9 +26,8 @@ set -euo pipefail
 #   scripts/update-tooling.sh --tag sha-558a144  # match a specific one, e.g. what you run
 #   scripts/update-tooling.sh --dry-run        # show what would change, touch nothing
 #
-# Needs docker, which the default deploy path needs anyway (it mirrors the image into your
-# Artifact Registry). A deployment using an AR remote repository instead still needs it
-# here — once per engine version, rather than once per deploy.
+# Needs docker, and is the only thing here that does: the files are lifted out of the
+# published image with `docker cp`. Once per engine version, and never during a deploy.
 
 . "$(dirname "${BASH_SOURCE[0]}")/lib/cli-names.sh"