@meffecta/agent 0.0.1

package/scripts/artifact-cleanup-policy.json

@@ -0,0 +1,17 @@
+[
+  {
+    "name": "keep-recent-versions",
+    "action": { "type": "Keep" },
+    "mostRecentVersions": { "keepCount": 5 }
+  },
+  {
+    "name": "delete-untagged",
+    "action": { "type": "Delete" },
+    "condition": { "tagState": "UNTAGGED", "olderThan": "1d" }
+  },
+  {
+    "name": "delete-superseded",
+    "action": { "type": "Delete" },
+    "condition": { "tagState": "ANY", "olderThan": "30d" }
+  }
+]

package/scripts/create-project.sh

@@ -0,0 +1,106 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Step 1 of IMPLEMENTATION.md: create the GCP project this deployment will live in.
+#
+# Give the agent a project of its own, separate from any product project it will read:
+# its service account gets project-wide secret access, and the mail tokens stored here
+# must not be readable by another system's machinery.
+#
+# Asks for a display name, suggests a project ID from it, and creates the project. The
+# ID is what every later command needs, and it is not always the one you asked for — if
+# it is taken you pick another here, so you learn it now rather than at the first failure.
+#
+# Usage:
+#   scripts/create-project.sh
+#   scripts/create-project.sh --name "Acme Agent" --id acme-agent
+#   ORGANIZATION=123456789 scripts/create-project.sh     # or FOLDER=...
+
+NAME=""
+PROJECT_ID=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --name) NAME="${2:?--name needs a value}"; shift 2 ;;
+    --id) PROJECT_ID="${2:?--id needs a value}"; shift 2 ;;
+    -h|--help) sed -n '4,18p' "$0"; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+command -v gcloud >/dev/null || { echo "gcloud is required." >&2; exit 1; }
+
+if ! gcloud auth list --filter=status:ACTIVE --format='value(account)' 2>/dev/null | grep -q .; then
+  echo "No active gcloud account. Run: gcloud auth login" >&2
+  exit 1
+fi
+
+# Google's rules: 6-30 chars, lowercase letters, digits and hyphens, starts with a
+# letter, does not end with one. Checked here so a typo fails instantly, not after a
+# round trip.
+valid_id() {
+  case "$1" in
+    [a-z]*[a-z0-9]) [ ${#1} -ge 6 ] && [ ${#1} -le 30 ] && [ -z "$(printf '%s' "$1" | tr -d 'a-z0-9-')" ] ;;
+    *) return 1 ;;
+  esac
+}
+
+suggest_id() {
+  printf '%s' "$1" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9' '-' | sed 's/^-*//; s/-*$//' | cut -c1-30
+}
+
+if [ -z "${NAME}" ]; then
+  if [ ! -t 0 ]; then
+    echo "No display name given and nothing to prompt with. Use --name." >&2
+    exit 2
+  fi
+  printf 'Display name for the project (e.g. "Acme Agent"): '
+  IFS= read -r NAME
+fi
+[ -n "${NAME}" ] || { echo "A display name is required." >&2; exit 2; }
+
+if [ -z "${PROJECT_ID}" ]; then
+  SUGGESTED=$(suggest_id "${NAME}")
+  if [ -t 0 ]; then
+    printf 'Project ID [%s]: ' "${SUGGESTED}"
+    IFS= read -r PROJECT_ID
+  fi
+  PROJECT_ID="${PROJECT_ID:-${SUGGESTED}}"
+fi
+
+if ! valid_id "${PROJECT_ID}"; then
+  echo "" >&2
+  echo "'${PROJECT_ID}' is not a valid project ID." >&2
+  echo "Rules: 6-30 characters, lowercase letters, digits and hyphens, starting with a" >&2
+  echo "letter and not ending with a hyphen." >&2
+  exit 2
+fi
+
+echo ""
+echo "▶ Creating project"
+echo "   id:   ${PROJECT_ID}"
+echo "   name: ${NAME}"
+[ -n "${ORGANIZATION:-}" ] && echo "   org:  ${ORGANIZATION}"
+[ -n "${FOLDER:-}" ] && echo "   folder: ${FOLDER}"
+echo ""
+
+ARGS=(projects create "${PROJECT_ID}" --name "${NAME}")
+[ -n "${ORGANIZATION:-}" ] && ARGS+=(--organization "${ORGANIZATION}")
+[ -n "${FOLDER:-}" ] && ARGS+=(--folder "${FOLDER}")
+
+if ! gcloud "${ARGS[@]}"; then
+  echo "" >&2
+  echo "Project creation failed. The usual cause is that the ID is already taken —" >&2
+  echo "globally, across all of Google Cloud, not just your organization. Re-run with" >&2
+  echo "a different one, e.g. --id ${PROJECT_ID}-$(od -An -N2 -tu2 </dev/urandom | tr -d ' ')" >&2
+  exit 1
+fi
+
+echo ""
+echo "✔ Created ${PROJECT_ID}"
+echo ""
+echo "Next: link a billing account (nothing else works without it) —"
+echo "    $(dirname "$0")/link-billing.sh --project ${PROJECT_ID}"
+echo ""
+echo "And in step 3, this goes in your content repo's deployment.env:"
+echo "    PROJECT=${PROJECT_ID}"

package/scripts/deploy.sh

@@ -0,0 +1,169 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Roll a published engine image out to one deployment's Cloud Run service.
+#
+# The engine's CI publishes images to GHCR and stops there: choosing when to move to a
+# 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 Marcus's 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
+#
+# What it writes, and what it deliberately does not.
+#
+# The image and the **runtime shape** — scaling, CPU, memory, request timeout — are
+# asserted on every rollout, from deployment.env (SCALING, CPU, MEMORY, MAX_INSTANCES,
+# REQUEST_TIMEOUT, with the defaults in lib/deployment.sh). That is the point: a flag
+# changed by hand in the console would otherwise survive every deploy silently, and this
+# shape is not decoration — `scale-to-zero` only works because the service is driven from
+# outside, so a service that quietly drifted back to always-on would run every cron twice.
+#
+# Env vars, secrets, volumes and the service account are NOT touched. Those are supplied
+# by set-env.sh, set-secret.sh and setup-infrastructure.sh, and a wrong guess about a
+# bucket name or a service account breaks a deployment far worse than drift does.
+#
+# A deployment driven by Cloud Scheduler also gets its triggers re-synced afterwards
+# (scripts/setup-scheduler.sh): a deploy restarts the service, which is when new or renamed
+# `cron:` registrations from the content repo take effect, so it is also when the Scheduler
+# jobs mirroring them have to be brought up to date. An always-on deployment drives itself
+# and is left alone.
+#
+# Usage:
+#   scripts/deploy.sh                     # the newest published engine (--tag latest)
+#   scripts/deploy.sh --tag sha-556ca72   # a specific build, e.g. to roll back
+#   scripts/deploy.sh --image europe-west1-docker.pkg.dev/PROJECT/REPO/agent:sha-556ca72
+#   scripts/deploy.sh --dry-run           # print the target, image and shape; change nothing
+#   scripts/deploy.sh --no-scheduler      # roll out without re-syncing the triggers
+#
+# Which deployment: ./deployment.env, or --config <file>. See deployment.env.example.
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+
+TAG="latest"
+IMAGE=""
+DRY_RUN=false
+SYNC_SCHEDULER=true
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    --tag) TAG="${2:?--tag needs a value}"; shift 2 ;;
+    --image) IMAGE="${2:?--image needs a value}"; shift 2 ;;
+    --dry-run) DRY_RUN=true; shift ;;
+    --no-scheduler) SYNC_SCHEDULER=false; shift ;;
+    -h|--help) sed -n '3,49p' "$0"; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+require_gcloud
+resolve_deployment
+announce_target "Deploying ${SERVICE}"
+
+# --tag mirrors GHCR → this deployment's Artifact Registry; --image is taken as-is
+# (already in AR, or reachable through an AR remote repository).
+if [ -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 "Either install it, or set up an AR remote repository and pass --image." >&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 setup-scheduler.sh's triggers assume: no CPU
+# except while a request is open, which is only correct because nothing in the service
+# fires on its own. always-on is the other coherent pair, for a deployment that drives
+# itself with in-process timers instead.
+case "${SCALING}" in
+  scale-to-zero) SCALE_FLAGS=(--min-instances=0 --cpu-throttling --cpu-boost) ;;
+  always-on) SCALE_FLAGS=(--min-instances=1 --no-cpu-throttling) ;;
+  *)
+    echo "Unknown SCALING=\"${SCALING}\" — use scale-to-zero or always-on." >&2
+    exit 2
+    ;;
+esac
+
+echo "🧩 Rolling out ${IMAGE}"
+echo "   shape: ${SCALING}, cpu ${CPU}, memory ${MEMORY}, max ${MAX_INSTANCES} instance(s), timeout ${REQUEST_TIMEOUT}s"
+if [ "${DRY_RUN}" = true ]; then
+  echo "   (dry run: nothing was changed)"
+  exit 0
+fi
+gcloud run deploy "${SERVICE}" \
+  --project "${PROJECT}" \
+  --region "${REGION}" \
+  --platform managed \
+  --image "${IMAGE}" \
+  --cpu "${CPU}" \
+  --memory "${MEMORY}" \
+  --max-instances "${MAX_INSTANCES}" \
+  --timeout "${REQUEST_TIMEOUT}" \
+  --execution-environment gen2 \
+  "${SCALE_FLAGS[@]}"
+
+# Only for a deployment that has opted into external triggers — AGENT_TASKS_QUEUE on the
+# service is what says so. Creating Scheduler jobs for an always-on one would mean every
+# cron fires twice, once from outside and once from the in-process timer.
+if [ "${SYNC_SCHEDULER}" = true ] &&
+  gcloud run services describe "${SERVICE}" --project "${PROJECT}" --region "${REGION}" \
+    --format json 2>/dev/null | grep -q AGENT_TASKS_QUEUE; then
+  echo ""
+  "$(dirname "${BASH_SOURCE[0]}")/setup-scheduler.sh" ${CONFIG_FILE:+--config "${CONFIG_FILE}"}
+fi
+
+URL=$(gcloud run services describe "${SERVICE}" \
+  --project "${PROJECT}" --region "${REGION}" \
+  --format 'value(status.url)' 2>/dev/null || true)
+if [ -n "${URL}" ]; then
+  echo "🌍 ${SERVICE} → ${URL}"
+  echo "   Liveness: curl -fsS ${URL}/health"
+  echo "   Ask it:   ${URL}/ask   (any username, AGENT_WEBHOOK_SECRET as the password)"
+fi

package/scripts/lib/deployment.sh

@@ -0,0 +1,109 @@
+# Shared configuration for the operator scripts. Sourced, never run.
+#
+# One deployment = one config file, and that file belongs in the deployment's CONTENT
+# repo, committed: which GCP project and service a set of jobs runs as is a fact about
+# that deployment, not about the engine. None of it is secret (secrets live in Secret
+# Manager), so it is checked in, and a fresh clone of the content repo is enough to
+# operate the deployment.
+#
+# So the usual shape is: cd to the content repo, run the engine's scripts from there.
+#
+#   cd ~/work/acme-agent-home && ~/work/agent/scripts/deploy.sh
+#
+# Resolution order, first hit wins per value:
+#   1. a variable already set in the environment (one-off override)
+#   2. the config file: --config <file>, else $DEPLOYMENT_CONFIG, else ./deployment.env
+#      in the current directory
+#
+# Nothing is guessed beyond that: every script prints the project and service it is about
+# to touch and refuses to run without them, so being in the wrong directory is an error
+# rather than a command against the wrong deployment.
+#
+# Config file format is plain KEY=value lines, # comments allowed. See
+# deployment.env.example.
+
+# Consume --config <file> from a script's arguments before it parses its own.
+# Usage: eval "$(extract_config_flag "$@")" — sets CONFIG_FILE and rewrites "$@".
+CONFIG_FILE=""
+
+load_deployment_config() {
+  local file="${CONFIG_FILE:-${DEPLOYMENT_CONFIG:-}}"
+  if [ -z "${file}" ]; then
+    file="${PWD}/deployment.env" # i.e. the content repo you are standing in
+  fi
+  if [ ! -f "${file}" ]; then
+    if [ -n "${CONFIG_FILE}" ] || [ -n "${DEPLOYMENT_CONFIG:-}" ]; then
+      echo "Config file not found: ${file}" >&2
+      exit 1
+    fi
+    return 0 # no config file is fine as long as the environment supplies the values
+  fi
+  DEPLOYMENT_CONFIG_USED="${file}"
+  local key value
+  while IFS='=' read -r key value || [ -n "${key}" ]; do
+    key="${key%%#*}"                       # drop trailing comment on the key side
+    key="$(printf '%s' "${key}" | tr -d '[:space:]')"
+    [ -z "${key}" ] && continue
+    value="${value%$'\r'}"                 # tolerate CRLF
+    value="${value#"${value%%[![:space:]]*}"}"   # trim leading space
+    value="${value%"${value##*[![:space:]]}"}"   # trim trailing space
+    value="${value%\"}"; value="${value#\"}"     # strip surrounding quotes
+    value="${value%\'}"; value="${value#\'}"
+    # An environment variable already set wins — that is the one-off override.
+    if [ -z "$(eval "printf '%s' \"\${${key}:-}\"" 2>/dev/null)" ]; then
+      eval "${key}=\$value"
+    fi
+  done <"${file}"
+}
+
+# Fill in what the config file did not, then insist on the two that must never be guessed.
+resolve_deployment() {
+  load_deployment_config
+  REGION="${REGION:-europe-west1}"
+  ARTIFACT_REPO="${ARTIFACT_REPO:-${SERVICE:-agent}-images}"
+  GHCR_IMAGE="${GHCR_IMAGE:-ghcr.io/meffecta/agent}"
+  TIMEZONE="${TIMEZONE:-Europe/Stockholm}"
+
+  # The runtime shape, asserted by deploy.sh on every rollout so the deployed service
+  # matches this file rather than whatever was last done by hand in the console. Defaults
+  # are the shape setup-infrastructure.sh provisions; override any of them per deployment.
+  SCALING="${SCALING:-scale-to-zero}"
+  CPU="${CPU:-2}"
+  MEMORY="${MEMORY:-4Gi}"
+  MAX_INSTANCES="${MAX_INSTANCES:-1}"
+  REQUEST_TIMEOUT="${REQUEST_TIMEOUT:-3600}"
+
+  local missing=""
+  [ -z "${PROJECT:-}" ] && missing="${missing} PROJECT"
+  [ -z "${SERVICE:-}" ] && missing="${missing} SERVICE"
+  if [ -n "${missing}" ]; then
+    cat >&2 <<EOF
+Missing required setting(s):${missing}
+
+No deployment.env found in $(pwd).
+
+That file lives in the deployment's content repo (committed — none of it is
+secret), so the usual fix is to run this from there:
+
+    cd /path/to/your-content-repo && ${0}
+
+Creating one: copy scripts/deployment.env.example beside your jobs/. Or point
+at a file explicitly with --config /path/to/deployment.env.
+EOF
+    exit 2
+  fi
+}
+
+# Every script says what it is about to touch, before it touches it.
+announce_target() {
+  local action="$1"
+  echo "▶ ${action}"
+  echo "   project: ${PROJECT}"
+  echo "   service: ${SERVICE} (${REGION})"
+  [ -n "${DEPLOYMENT_CONFIG_USED:-}" ] && echo "   config:  ${DEPLOYMENT_CONFIG_USED}"
+  echo ""
+}
+
+require_gcloud() {
+  command -v gcloud >/dev/null || { echo "gcloud is required." >&2; exit 1; }
+}

package/scripts/link-billing.sh

@@ -0,0 +1,143 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Step 2 of IMPLEMENTATION.md: link a billing account to the project.
+#
+# Nothing else works without this — provisioning starts by enabling APIs, which fails on
+# an unbilled project, and the failure does not mention billing.
+#
+# Lists the billing accounts you can use, lets you pick one, links it, and verifies the
+# result. Closed accounts are shown but cannot be selected: linking one silently leaves
+# the project unbilled.
+#
+# The project comes from --project, else PROJECT in ./deployment.env or the environment,
+# else a prompt.
+#
+# Usage:
+#   scripts/link-billing.sh
+#   scripts/link-billing.sh --project acme-agent-506513
+#   scripts/link-billing.sh --project acme-agent-506513 --billing-account 0X0X0X-...
+
+. "$(dirname "${BASH_SOURCE[0]}")/lib/deployment.sh"
+
+BILLING_ACCOUNT=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --config) CONFIG_FILE="${2:?--config needs a file}"; shift 2 ;;
+    --project) PROJECT="${2:?--project needs a value}"; shift 2 ;;
+    --billing-account) BILLING_ACCOUNT="${2:?--billing-account needs a value}"; shift 2 ;;
+    -h|--help) sed -n '4,20p' "$0"; exit 0 ;;
+    *) echo "Unknown argument: $1" >&2; exit 2 ;;
+  esac
+done
+
+require_gcloud
+# Soft load: at this point in the set-up a content repo may not exist yet, so a missing
+# deployment.env is normal — unlike the later scripts, this one only needs PROJECT.
+load_deployment_config
+
+if [ -z "${PROJECT:-}" ]; then
+  if [ ! -t 0 ]; then
+    echo "No project given. Use --project, or run from a content repo with deployment.env." >&2
+    exit 2
+  fi
+  printf 'Project ID: '
+  IFS= read -r PROJECT
+fi
+[ -n "${PROJECT}" ] || { echo "A project ID is required." >&2; exit 2; }
+
+gcloud projects describe "${PROJECT}" --format='value(projectId)' >/dev/null 2>&1 || {
+  echo "Cannot see project '${PROJECT}' — check the ID with: gcloud projects list" >&2
+  exit 1
+}
+
+CURRENT=$(gcloud billing projects describe "${PROJECT}" --format='value(billingEnabled)' 2>/dev/null || echo "")
+if [ "${CURRENT}" = "True" ]; then
+  ACCOUNT=$(gcloud billing projects describe "${PROJECT}" --format='value(billingAccountName)' 2>/dev/null || echo "")
+  echo "✔ ${PROJECT} already has billing enabled (${ACCOUNT#billingAccounts/})."
+  exit 0
+fi
+
+if [ -z "${BILLING_ACCOUNT}" ]; then
+  echo "Billing accounts you can use:"
+  echo ""
+  IDS=()
+  INDEX=0
+  # displayName can contain spaces, so split on tabs rather than whitespace.
+  while IFS=$'\t' read -r id display open; do
+    [ -n "${id}" ] || continue
+    if [ "${open}" = "True" ]; then
+      INDEX=$((INDEX + 1))
+      IDS+=("${id}")
+      printf '  %d) %-24s %s\n' "${INDEX}" "${id}" "${display}"
+    else
+      printf '     %-24s %s  (closed — cannot be linked)\n' "${id}" "${display}"
+    fi
+  done < <(gcloud billing accounts list --format='value[separator="	"](name.basename(),displayName,open)' 2>/dev/null)
+
+  if [ ${#IDS[@]} -eq 0 ]; then
+    echo "  (none open)" >&2
+    echo "" >&2
+    echo "No open billing account is available to this login. Create one at" >&2
+    echo "https://console.cloud.google.com/billing, or ask whoever administers billing" >&2
+    echo "to grant you Billing Account User on theirs." >&2
+    exit 1
+  fi
+
+  echo ""
+  if [ ${#IDS[@]} -eq 1 ]; then
+    BILLING_ACCOUNT="${IDS[0]}"
+    echo "Only one open account — using ${BILLING_ACCOUNT}."
+  else
+    if [ ! -t 0 ]; then
+      echo "Several accounts available; pass --billing-account <id>." >&2
+      exit 2
+    fi
+    printf 'Select [1-%d]: ' "${#IDS[@]}"
+    IFS= read -r CHOICE
+    case "${CHOICE}" in
+      ''|*[!0-9]*) echo "Not a number: '${CHOICE}'" >&2; exit 2 ;;
+    esac
+    if [ "${CHOICE}" -lt 1 ] || [ "${CHOICE}" -gt ${#IDS[@]} ]; then
+      echo "Out of range: ${CHOICE}" >&2
+      exit 2
+    fi
+    BILLING_ACCOUNT="${IDS[$((CHOICE - 1))]}"
+  fi
+fi
+
+echo ""
+echo "▶ Linking ${BILLING_ACCOUNT} to ${PROJECT}"
+LINK_ERR=$(mktemp)
+trap 'rm -f "${LINK_ERR}"' EXIT
+if ! gcloud billing projects link "${PROJECT}" --billing-account="${BILLING_ACCOUNT}" >/dev/null 2>"${LINK_ERR}"; then
+  cat "${LINK_ERR}" >&2
+  if grep -qi 'quota' "${LINK_ERR}"; then
+    cat >&2 <<EOF
+
+That is the billing account's project quota, not a problem with this project: a
+billing account may only fund so many projects, and yours is full. Either free a
+slot —
+
+    gcloud projects list                       # find one you no longer need
+    gcloud billing projects unlink <PROJECT>   # or delete the project outright
+
+— or request an increase at
+https://support.google.com/code/contact/billing_quota_increase
+EOF
+  fi
+  exit 1
+fi
+
+# Linking can report success while leaving the project unbilled (a closed account), so
+# confirm the state rather than the command's exit code.
+if [ "$(gcloud billing projects describe "${PROJECT}" --format='value(billingEnabled)' 2>/dev/null)" = "True" ]; then
+  echo "✔ billingEnabled: true"
+  echo ""
+  echo "Next: create the content repo (step 3), then provision from inside it —"
+  echo "    $(dirname "$0")/setup-infrastructure.sh"
+else
+  echo "✖ Linked, but billingEnabled is still false — check the account is open and funded." >&2
+  exit 1
+fi

package/scripts/mint-gmail-token.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// One-time, local: mint the OAuth refresh token the agent uses for the private
+// Gmail account. Opens a browser consent flow via the loopback redirect and
+// prints the refresh token — store it as the GMAIL_REFRESH_TOKEN secret.
+//
+// Prerequisites (once, in the agent's GCP project):
+//   1. Enable the Gmail API and Google Calendar API.
+//   2. OAuth consent screen: External, then PUBLISH TO "In production" —
+//      an app left in "Testing" expires refresh tokens after 7 days.
+//   3. Create an OAuth client of type "Desktop app"; note client id + secret.
+//
+// Usage:
+//   node scripts/mint-gmail-token.mjs --client-id <id> --client-secret <secret>
+//                                     [--account <NAME>] [--readonly]
+//
+// Sign in as WHICHEVER account the token is for when the browser opens — run once
+// per account (private Gmail → GMAIL_REFRESH_TOKEN; additional accounts →
+// --account NAME → GMAIL_<NAME>_REFRESH_TOKEN). --readonly mints read scopes only,
+// which is the right level for an account Marcus doesn't administer alone (a
+// company mailbox: read the mail, never send from that identity).
+// Gmail scopes are "restricted", so an unverified app
+// shows a warning — Advanced → continue is fine for your own account. A Workspace
+// account you don't control only works if that tenant's admin policy allows
+// third-party OAuth apps; a refusal at consent means their admin has to allowlist
+// this client id.
+
+import { createServer } from "node:http";
+import { parseArgs } from "node:util";
+
+const { values: args } = parseArgs({
+  options: {
+    "client-id": { type: "string" },
+    "client-secret": { type: "string" },
+    account: { type: "string" },
+    readonly: { type: "boolean", default: false },
+  },
+});
+
+const accountName = args.account?.toUpperCase();
+if (accountName && !/^[A-Z0-9]+$/.test(accountName)) {
+  console.error("--account must be a single alphanumeric word (it becomes GMAIL_<NAME>_REFRESH_TOKEN)");
+  process.exit(1);
+}
+const tokenVar = accountName ? `GMAIL_${accountName}_REFRESH_TOKEN` : "GMAIL_REFRESH_TOKEN";
+
+const clientId = args["client-id"] ?? process.env.GMAIL_CLIENT_ID;
+const clientSecret = args["client-secret"] ?? process.env.GMAIL_CLIENT_SECRET;
+if (!clientId || !clientSecret) {
+  console.error("usage: mint-gmail-token.mjs --client-id <id> --client-secret <secret>");
+  process.exit(1);
+}
+
+const READ_SCOPES = [
+  "https://www.googleapis.com/auth/gmail.readonly",
+  "https://www.googleapis.com/auth/calendar.readonly",
+  "https://www.googleapis.com/auth/drive.readonly",
+];
+const SCOPES = args.readonly
+  ? READ_SCOPES
+  : [
+      "https://www.googleapis.com/auth/gmail.readonly",
+      "https://www.googleapis.com/auth/gmail.send",
+      "https://www.googleapis.com/auth/gmail.compose",
+      "https://www.googleapis.com/auth/calendar",
+      "https://www.googleapis.com/auth/drive",
+      "https://www.googleapis.com/auth/spreadsheets",
+      "https://www.googleapis.com/auth/documents",
+      "https://www.googleapis.com/auth/presentations",
+    ];
+
+const server = createServer();
+await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+const redirectUri = `http://127.0.0.1:${server.address().port}`;
+
+const authUrl = new URL("https://accounts.google.com/o/oauth2/v2/auth");
+authUrl.search = new URLSearchParams({
+  client_id: clientId,
+  redirect_uri: redirectUri,
+  response_type: "code",
+  scope: SCOPES.join(" "),
+  access_type: "offline",
+  // Force a fresh consent so Google returns a refresh token even if one was granted before.
+  prompt: "consent",
+}).toString();
+
+console.error(
+  `Open this URL in a browser and sign in as ${accountName ? `the ${accountName} account` : "the private account"}` +
+    ` (scopes: ${args.readonly ? "read-only" : "full"}):\n`,
+);
+console.error(authUrl.toString());
+console.error("\nWaiting for the redirect...");
+
+const code = await new Promise((resolve, reject) => {
+  server.on("request", (req, res) => {
+    const url = new URL(req.url, redirectUri);
+    const err = url.searchParams.get("error");
+    const c = url.searchParams.get("code");
+    res.writeHead(200, { "content-type": "text/html" });
+    res.end(err ? `<h3>Failed: ${err}</h3>` : "<h3>Done — you can close this tab.</h3>");
+    if (err) reject(new Error(err));
+    else if (c) resolve(c);
+  });
+});
+server.close();
+
+const res = await fetch("https://oauth2.googleapis.com/token", {
+  method: "POST",
+  headers: { "content-type": "application/x-www-form-urlencoded" },
+  body: new URLSearchParams({
+    client_id: clientId,
+    client_secret: clientSecret,
+    code,
+    grant_type: "authorization_code",
+    redirect_uri: redirectUri,
+  }),
+});
+const json = await res.json();
+if (!res.ok || !json.refresh_token) {
+  console.error(`token exchange failed (${res.status}): ${JSON.stringify(json)}`);
+  process.exit(1);
+}
+
+// Refresh token to stdout (pipe straight into gcloud), everything else to stderr.
+console.error(`\nRefresh token minted — it is ${tokenVar}. Store it without it touching your shell history:`);
+console.error(`  node scripts/mint-gmail-token.mjs ... | gcloud secrets create ${tokenVar} --data-file=-\n`);
+console.log(json.refresh_token);