ops: upgrade Paperclip to v2026.512.0

Upgrade Paperclip production config/docs to v2026.512.0, move managed agents to Codex subscription-only auth, add routine revision baseRevisionId support, and switch Staff Engineer PR review triggering to Paperclip's native routine API trigger.

Author: ohld

.github/workflows/staff-engineer-trigger.yml

@@ -15,13 +15,41 @@ jobs:
     steps:
       - name: Trigger Staff Engineer review
         env:
-          PAPERCLIP_STAFF_ENGINEER_TRIGGER_URL: ${{ secrets.PAPERCLIP_STAFF_ENGINEER_TRIGGER_URL }}
-          PAPERCLIP_TRIGGER_SECRET: ${{ secrets.PAPERCLIP_TRIGGER_SECRET }}
+          PAPERCLIP_URL: ${{ secrets.PAPERCLIP_URL }}
+          PAPERCLIP_API_KEY: ${{ secrets.PAPERCLIP_API_KEY }}
+          PAPERCLIP_COMPANY_ID: 96ee7b2e-6df2-43c8-bbe3-53e19297308a
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          PR_SHA: ${{ github.event.pull_request.head.sha }}
         run: |
-          : "${PAPERCLIP_STAFF_ENGINEER_TRIGGER_URL:?missing PAPERCLIP_STAFF_ENGINEER_TRIGGER_URL secret}"
-          : "${PAPERCLIP_TRIGGER_SECRET:?missing PAPERCLIP_TRIGGER_SECRET secret}"
-          curl -sSf -X POST \
-            "$PAPERCLIP_STAFF_ENGINEER_TRIGGER_URL" \
-            -H "Authorization: Bearer $PAPERCLIP_TRIGGER_SECRET" \
-            -H "Content-Type: application/json" \
-            -d '{"pr_number": ${{ github.event.pull_request.number }}, "pr_url": "${{ github.event.pull_request.html_url }}"}'
+          : "${PAPERCLIP_URL:?missing PAPERCLIP_URL secret}"
+          : "${PAPERCLIP_API_KEY:?missing PAPERCLIP_API_KEY secret}"
+
+          ROUTINES_JSON="$(curl -sSf \
+            -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+            "$PAPERCLIP_URL/api/companies/$PAPERCLIP_COMPANY_ID/routines")"
+          ROUTINE_ID="$(printf '%s' "$ROUTINES_JSON" | jq -r '.[] | select(.title == "[pr:{{pr_number}}] Review") | .id' | head -1)"
+          : "${ROUTINE_ID:?missing Staff Engineer PR routine}"
+          API_TRIGGER_ID="$(printf '%s' "$ROUTINES_JSON" | jq -r --arg id "$ROUTINE_ID" '.[] | select(.id == $id) | (.triggers // [])[] | select(.kind == "api" and (.enabled != false)) | .id' | head -1)"
+          : "${API_TRIGGER_ID:?missing Staff Engineer API trigger}"
+
+          jq -n \
+            --arg trigger "$API_TRIGGER_ID" \
+            --arg pr "$PR_NUMBER" \
+            --arg url "$PR_URL" \
+            --arg idem "pr-$PR_NUMBER-$PR_SHA" \
+            '{
+              source: "api",
+              triggerId: $trigger,
+              payload: {
+                pr_number: $pr,
+                pr_url: $url,
+                variables: {pr_number: $pr, pr_url: $url}
+              },
+              variables: {pr_number: $pr, pr_url: $url},
+              idempotencyKey: $idem
+            }' | curl -sSf -X POST \
+              "$PAPERCLIP_URL/api/routines/$ROUTINE_ID/run" \
+              -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+              -H "Content-Type: application/json" \
+              --data @-

agents/.paperclip.yaml

@@ -1,5 +1,10 @@
 schema: "paperclip/v1"
 
+# Codex agents use ChatGPT/Codex subscription OAuth from the persistent
+# /paperclip/.codex auth volume. Do not bind OPENAI_API_KEY to codex_local
+# agents, and do not set it globally in the Paperclip host env: Codex CLI
+# 0.122+ treats that as API-key billing instead of subscription billing.
+
 # gstack skills source — Paperclip pulls skills from this repo at the recorded ref.
 # Bump `ref` only after `agents/deploy.sh --dry-run` shows the new catalog with
 # zero unknown-desired-skills failures.
@@ -12,11 +17,12 @@ agents:
   analyst:
     role: "researcher"
     adapter:
-      type: "claude_local"
+      type: "codex_local"
       config:
-        dangerouslySkipPermissions: true
+        dangerouslyBypassApprovalsAndSandbox: true
         maxTurnsPerRun: 200
-        model: "claude-sonnet-4-6"
+        model: "gpt-5.5"
+        modelReasoningEffort: "high"
     runtime:
       heartbeat:
         enabled: true
@@ -57,21 +63,19 @@ agents:
           kind: "plain"
           default: "/paperclip/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
           requirement: "optional"
-        OPENAI_API_KEY:
-          kind: "secret"
-          requirement: "optional"
         ANALYST_DATABASE_URL:
           kind: "secret"
           requirement: "optional"
 
   comms-manager:
     role: "cmo"
     adapter:
-      type: "claude_local"
+      type: "codex_local"
       config:
-        dangerouslySkipPermissions: true
+        dangerouslyBypassApprovalsAndSandbox: true
         maxTurnsPerRun: 100
-        model: "claude-sonnet-4-6"
+        model: "gpt-5.5"
+        modelReasoningEffort: "medium"
     runtime:
       heartbeat:
         enabled: true
@@ -95,9 +99,6 @@ agents:
         FFMEMES_PROD_TELEGRAM_BOT_TOKEN:
           kind: "secret"
           requirement: "required"
-        OPENAI_API_KEY:
-          kind: "secret"
-          requirement: "optional"
 
   cto:
     role: "cto"
@@ -121,9 +122,6 @@ agents:
           kind: "plain"
           default: "/paperclip/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
           requirement: "optional"
-        OPENAI_API_KEY:
-          kind: "secret"
-          requirement: "optional"
         ANALYST_DATABASE_URL:
           kind: "secret"
           requirement: "optional"
@@ -154,11 +152,12 @@ agents:
   qa-engineer:
     role: "qa"
     adapter:
-      type: "claude_local"
+      type: "codex_local"
       config:
-        dangerouslySkipPermissions: true
+        dangerouslyBypassApprovalsAndSandbox: true
         maxTurnsPerRun: 200
-        model: "claude-sonnet-4-6"
+        model: "gpt-5.5"
+        modelReasoningEffort: "high"
     runtime:
       heartbeat:
         intervalSec: 21600
@@ -176,18 +175,14 @@ agents:
         COOLIFY_BASE_URL:
           kind: "secret"
           requirement: "required"
-        COOLIFY_RESOURCE_UUID:
-          kind: "plain"
-          default: "k4w804sco4s8kc88kwcw0ow4"
-          requirement: "optional"
-        COOLIFY_CONTAINER_NAME:
-          kind: "plain"
-          default: "k4w804sco4s8kc88kwcw0ow4-131756368009"
-          requirement: "optional"
+        # Coolify resource UUID + container name are intentionally NOT pinned
+        # as plain defaults here. They are documented in agents/qa-engineer/
+        # AGENTS.md (the "Key Coolify UUIDs" table) and resolved dynamically
+        # from the Coolify API when needed. Hand-written UUID defaults rot
+        # the moment Coolify rebuilds the container.
         PREFECT_API_URL:
-          kind: "plain"
-          default: "http://65.108.127.32:4200/api"
-          requirement: "optional"
+          kind: "secret"
+          requirement: "required"
         ANALYST_DATABASE_URL:
           kind: "secret"
           requirement: "required"
@@ -227,11 +222,12 @@ agents:
   release-engineer:
     role: "devops"
     adapter:
-      type: "claude_local"
+      type: "codex_local"
       config:
-        dangerouslySkipPermissions: true
+        dangerouslyBypassApprovalsAndSandbox: true
         maxTurnsPerRun: 150
-        model: "claude-sonnet-4-6"
+        model: "gpt-5.5"
+        modelReasoningEffort: "medium"
     runtime:
       heartbeat:
         maxConcurrentRuns: 1
@@ -273,9 +269,6 @@ agents:
           kind: "plain"
           default: "/paperclip/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
           requirement: "optional"
-        OPENAI_API_KEY:
-          kind: "secret"
-          requirement: "optional"
         ANALYST_DATABASE_URL:
           kind: "secret"
           requirement: "optional"

agents/_sync_config.py

@@ -335,6 +335,34 @@ def stale_adapter_keys(adapter_type: str | None) -> set[str]:
     return set()
 
 
+def routine_latest_revision_id(routine: dict) -> str | None:
+    """Return the live routine revision id when the Paperclip API exposes one.
+
+    v2026.512.0 introduced routine revision history. Older servers simply omit
+    these fields, so callers can stay compatible by omitting baseRevisionId.
+    """
+    for key in ("latestRevisionId", "latest_revision_id", "currentRevisionId"):
+        value = routine.get(key)
+        if isinstance(value, str) and value:
+            return value
+
+    for key in ("latestRevision", "currentRevision", "revision"):
+        value = routine.get(key)
+        if isinstance(value, dict):
+            revision_id = value.get("id")
+            if isinstance(revision_id, str) and revision_id:
+                return revision_id
+    return None
+
+
+def routine_patch_payload(routine: dict, description: str) -> dict:
+    payload = {"description": description}
+    revision_id = routine_latest_revision_id(routine)
+    if revision_id:
+        payload["baseRevisionId"] = revision_id
+    return payload
+
+
 def sync_routine_descriptions(by_slug: dict[str, dict]) -> tuple[int, int, int]:
     specs = load_routine_description_specs()
     if not specs:
@@ -373,15 +401,19 @@ def sync_routine_descriptions(by_slug: dict[str, dict]) -> tuple[int, int, int]:
             print(f"  skip routine {spec['name']} (no description drift)")
             skipped += 1
             continue
+        payload = routine_patch_payload(routine, spec["description"])
         if DRY:
-            print(f"  WOULD PATCH routine {spec['name']}: description")
+            change = "description"
+            if "baseRevisionId" in payload:
+                change += " with baseRevisionId"
+            print(f"  WOULD PATCH routine {spec['name']}: {change}")
             patched += 1
             continue
         try:
             api(
                 "PATCH",
                 f"/api/routines/{routine['id']}",
-                {"description": spec["description"]},
+                payload,
             )
         except Exception as e:
             print(

agents/analyst/AGENTS.md

@@ -35,7 +35,8 @@ delegated subtasks instead of comment-only handoffs.
 
 Every issue you create must start with a stable bracket slug. Use
 `[report:YYYY-MM-DD]` for scheduled reports and update/comment on an existing
-open issue with that slug instead of creating duplicates.
+open issue with that slug instead of creating duplicates. Use native Paperclip
+company search / issue search before creating a recurrent slug.
 
 Only the CEO may open strategic issues. As Analyst, create only execution
 tickets from your explicit workflow; put strategic findings in your report for

agents/ceo/AGENTS.md

@@ -46,6 +46,10 @@ Use the native `paperclip` skill for wake context, task selection, checkout,
 structured confirmations, blockers/subtasks, documents/attachments, concise
 comments, and task completion.
 
+Use Paperclip planning work mode for strategic, experiment, architecture, and
+proposal issues. Keep standard mode for execution tickets delegated to CTO,
+Analyst, or Comms.
+
 For blocked work, set status `blocked` with a clear comment and use
 `blockedByIssueIds` when another issue must finish first. Use child issues for
 delegated subtasks instead of comment-only handoffs.
@@ -58,8 +62,8 @@ across recurrences:
   `[post:YYYY-MM-DD-slug]`, `[maintenance:<slug>]`, `[postmortem:<slug>]`,
   `[strategy:weekly-outcomes-YYYY-MM-DD]`
 
-Search/update an existing open issue with the same slug before creating another
-one.
+Use native company search / issue search to find an existing issue with the same
+slug before creating another one.
 
 Only the CEO may open strategic issues. Other agents may open execution issues
 from their explicit workflows and should route strategic ideas through you.

agents/comms-manager/AGENTS.md

@@ -39,8 +39,8 @@ For blocked work, set status `blocked` with a clear comment and use
 Every post draft issue must use `[post:YYYY-MM-DD-slug]` as the stable title
 prefix.
 
-Search/update an existing open draft with the same slug before creating another
-one.
+Use native Paperclip company search / issue search and update an existing open
+draft with the same slug before creating another one.
 
 You may create only execution tickets from the comms workflow. Strategic or
 planning tickets belong to CEO.
@@ -161,10 +161,9 @@ For exact data, use `src/comms/visuals.py` primitives ONLY. Do not write raw mat
 - Pie charts, 3D, dual-axis → banned
 
 These primitives return PNG bytes. Pass them directly as `photo_bytes=png` to
-`publish_editorial_post`. For illustrative/editorial art, use
-`src.comms.image_generation.generate_editorial_image()` with a precise prompt
-built by `build_editorial_image_prompt(...)`, then pass
-`photo_bytes=image.image_bytes`.
+`publish_editorial_post`. Under Codex subscription-only runtime, do not use
+`OPENAI_API_KEY` or GPT image generation inside this agent. If editorial art is
+required, create a CEO/ops task for a separate non-Codex image pipeline.
 
 See `docs/comms/brand-guide.md` for the full decision tree and constraints.
 
@@ -278,16 +277,16 @@ See full brand guide: `docs/comms/brand-guide.md`
 4. **Diagrams** — for engineering posts (simple, clean, brand colors)
 5. **Stat cards** — for daily pulse (big number + context)
 
-When generating charts/images, verify the result looks good by feeding it back through the browse skill.
+When creating charts or local visuals, verify the result looks good by feeding
+it back through the browse skill.
 Never send editorial visuals to the moderator chat just to get a Telegram `file_id`.
 
 ### Image Review Before Posting (MANDATORY)
 
 Before attaching ANY image to a channel post, you MUST:
 
 1. **Visually inspect** the image. For Telegram `file_id` memes, download via
-   the Telegram Bot API first; for local/generated images, inspect the local
-   PNG directly.
+   the Telegram Bot API first; for local images, inspect the local PNG directly.
 ```bash
 # Get file path
 FILE_PATH=$(curl -s "https://api.telegram.org/bot${FFMEMES_PROD_TELEGRAM_BOT_TOKEN}/getFile?file_id=<file_id>" | python3 -c "import json,sys; print(json.load(sys.stdin)['result']['file_path'])")

agents/cto/AGENTS.md

@@ -24,6 +24,9 @@ Use the native `paperclip` skill for wake context, task selection, checkout,
 structured confirmations, blockers/subtasks, documents/attachments, concise
 comments, and task completion.
 
+When CEO asks for architecture or implementation planning rather than immediate
+execution, keep that work in Paperclip planning mode until the plan is accepted.
+
 For blocked work, set status `blocked` with a clear comment and use
 `blockedByIssueIds` when another issue must finish first. Use child issues for
 delegated subtasks instead of comment-only handoffs.
@@ -34,8 +37,8 @@ Every issue you create must start with a stable bracket slug, reused across
 recurrences: `[pr:NNN]`, `[incident:<slug>]`, `[deploy:<branch-or-pr>]`,
 `[maintenance:<slug>]`, `[postmortem:<slug>]`.
 
-Search/update an existing open issue with the same slug before creating another
-one; this collapses repeated incidents onto one tracking issue.
+Use native Paperclip company search / issue search for the same slug before
+creating another one; this collapses repeated incidents onto one tracking issue.
 
 You may create only execution tickets from your implementation workflow.
 Strategic/planning tickets belong to CEO.

agents/qa-engineer/AGENTS.md

@@ -46,12 +46,16 @@ recurrences:
 - `[incident:<slug>]` — production bugs (e.g. `[incident:db-pool]`, `[incident:describe-memes-timeout]`, `[incident:webhook-502]`)
 - `[deploy:<branch-or-pr>]`, `[report:YYYY-MM-DD]`, `[maintenance:<slug>]`, `[postmortem:<slug>]`
 
-Search/update an existing open issue with the same slug before creating another
-one; add new evidence as a comment instead of opening duplicates.
+Use native Paperclip company search / issue search and update an existing open
+issue with the same slug before creating another one; add new evidence as a
+comment instead of opening duplicates.
 
 As QA, create only execution tickets from scan workflows. Planning and strategic
 tickets belong to CEO.
 
+For delayed verification, post-deploy waits, or "retry after logs settle" work,
+use native issue monitors / retry-now rather than comment-only due timestamps.
+
 ## Every Scheduled Log Scan
 
 ### 1. Scan All Log Sources
@@ -169,6 +173,9 @@ outcomes. There are two distinct layers and you should not duplicate them:
   zombie-run, and no-comment classification belong here. Read these from the
   Paperclip dashboard / native routine tooling — do NOT reimplement them in
   the FFmemes audit script.
+- **Paperclip v2026.512 issue monitor signals** — delayed checks and retry-now
+  belong to the native monitor surface. Use it before inventing a custom
+  follow-up comment format.
 - **FFmemes outcome-contract checks**, run via
   `scripts/paperclip_routine_audit.py`. This is narrow and business-specific:
   channel post publication markers, update-check content (changelog, version,

agents/release-engineer/AGENTS.md

@@ -32,8 +32,8 @@ delegated subtasks instead of comment-only handoffs.
 Every issue you create must start with a stable bracket slug. For release work
 this is usually `[pr:NNN]`, `[deploy:<branch-or-pr>]`, or `[qa:<pr-number>]`.
 
-Search/update an existing open issue with the same slug before creating another
-one.
+Use native Paperclip company search / issue search for the same slug before
+creating another one.
 
 You may create only execution tickets from your release workflow. Strategic or
 planning tickets belong to CEO.
@@ -54,6 +54,9 @@ You do **NOT** merge PRs. Staff Engineer owns the review → approve → squash-
 2. **Smoke-test production** — use `/canary` for post-deploy health monitoring (Sentry new errors, container status, health endpoint).
 3. **Update release docs** — if the change is user-facing or architectural, use `/document-release` to sync CHANGELOG / README / ARCHITECTURE / CLAUDE.md.
 4. **Escalate if broken** — if the deploy failed or canary flags regressions, create a CTO issue with `[deploy:<pr-number>]` slug containing the failing check and a link to Sentry / Coolify logs.
+5. **Schedule delayed checks natively** — if logs, metrics, or deploy state need
+   time to settle, use Paperclip issue monitors / retry-now instead of leaving
+   a comment-only due timestamp.
 
 ## Merge Policy (reminder, not your job)