thepopebot 1.2.76-beta.19 → 1.2.76-beta.20

package/api/CLAUDE.md

@@ -4,9 +4,14 @@ This directory contains the route handlers for all `/api/*` endpoints. These rou
 
 ## Auth
 
-All routes (except `/telegram/webhook` and `/github/webhook`, which use their own webhook secrets) require a valid API key passed via the `x-api-key` header. API keys are stored in the SQLite database and managed through the admin UI — they are NOT environment variables.
+Most routes require a valid API key passed via the `x-api-key` header. API keys are stored in the SQLite database and managed through the admin UI — they are NOT environment variables.
 
-Auth flow: `x-api-key` header -> `verifyApiKey()` -> database lookup (hashed, timing-safe comparison).
+**Public routes** (no API key needed): `/ping`, `/telegram/webhook` (Telegram webhook secret), `/github/webhook` (GitHub webhook secret), `/oauth/callback` (validated via short-lived `state` token).
+
+Auth flow: `x-api-key` header → `verifyApiKey()` → DB lookup (hashed, timing-safe comparison). Two key types exist:
+
+- **User-owned API keys** — long-lived, created via the admin UI, used by external callers (cURL, GitHub Actions, Telegram register).
+- **Per-job agent API keys** (`agent_job_api_key`) — short-lived, auto-created when an agent-job container launches (`createAgentJobApiKey()` in `lib/db/api-keys.js`), tied to the container name, and cleaned up by the maintenance cron after expiry. Only this key type is allowed to call `/api/get-agent-job-secret` (the route rejects other types).
 
 ## Do NOT use these routes for browser UI
 
@@ -25,10 +30,12 @@ Browser-facing data fetching uses **fetch route handlers** colocated with pages
 |--------|------|------|---------|
 | GET | `/api/ping` | None | Health check |
 | POST | `/api/create-agent-job` | `x-api-key` | Create agent job |
-| GET | `/api/get-agent-job-secret` | `x-api-key` | Get an agent job secret; oauth2 credentials return only the access_token (auto-refreshed) |
+| GET | `/api/get-agent-job-secret` | `agent_job_api_key` only | Get an agent job secret. `oauth2` credentials return only the access_token (auto-refreshed under a lock; rotated refresh tokens are persisted back). Other secret types return the raw value. |
+| POST | `/api/set-agent-job-secret` | `agent_job_api_key` only | Create or update an agent-job secret from inside the container (used by the `set-secret` skill). |
 | GET | `/api/agent-job-list-secrets` | `x-api-key` | List agent job secret keys (no values); returns `{secrets: [{key, isSet, updatedAt, secretType}]}` |
 | GET | `/api/agent-jobs/status` | `x-api-key` | Agent job status (query: `?agent_job_id=`) |
-| POST | `/api/telegram/webhook` | Telegram webhook secret | Telegram message handler |
+| POST | `/api/telegram/webhook` | Telegram webhook secret | Telegram message handler (per-user routing via `user_channels`; verifies via `/verify <code>`, dispatches `/session` commands) |
 | POST | `/api/telegram/register` | `x-api-key` | Register bot token + webhook URL |
 | POST | `/api/github/webhook` | GitHub webhook secret | GitHub event handler |
 | POST | `/api/cluster/:clusterId/role/:roleId/webhook` | `x-api-key` | Trigger cluster role execution |
+| GET/POST | `/api/oauth/callback` | `state` token | OAuth provider redirect target. Exchanges `code` for tokens, persists via `setAgentJobSecret(name, stored, 'oauth')`. |

package/bin/CLAUDE.md

@@ -9,19 +9,23 @@ Entry point: `cli.js` (invoked via `npx thepopebot <command>`).
 | `init [--no-managed] [--no-install]` | Scaffold project from templates, sync managed files, create `.env`, install deps |
 | `setup` | Run interactive setup wizard (see `setup/CLAUDE.md`) |
 | `setup-telegram` | Reconfigure Telegram webhook |
+| `setup-ssl` | Configure SSL with Let's Encrypt wildcard cert |
 | `upgrade [@beta\|version]` | Upgrade package, run init, rebuild, commit, push, restart Docker |
 | `reset [file]` | Restore a template file to defaults |
+| `reset-all` | Nuclear reset — restore entire project to fresh init state |
+| `audit` | Show project state vs. package templates (modified / missing / unknown) |
 | `diff [file]` | Show diff between user file and package template |
 | `reset-auth` | Regenerate `AUTH_SECRET` (invalidates all sessions) |
-| `set-var <KEY> [VALUE]` | Set GitHub repository variable |
+| `set-var <KEY> [VALUE]` | Set GitHub repository variable (also reads piped stdin) |
 | `user:password <email>` | Change user password |
-| `sync <path>` | Dev helper — sync local package to test install |
+| `sync <path>` | Dev helper — pack, build, upload local package to test install |
+| `sync --fast <path>` | Fast variant — copy source into the running container and rebuild `.next` only |
 
 ## Managed Paths System
 
 `managed-paths.js` defines files auto-synced by `init`. These are overwritten on every init/upgrade — users should not edit them.
 
-**Managed paths**: `.github/workflows/`, `docker-compose.yml`, `.dockerignore`, `.gitignore`, `agent-job/CLAUDE.md`, `event-handler/CLAUDE.md`, `skills/CLAUDE.md`.
+**Managed paths**: `.github/workflows/`, `docker-compose.yml`, `.dockerignore`, `.gitignore`.
 
 `isManaged(relPath)` — returns true if a path is managed (exact match or directory prefix).
 

package/config/CLAUDE.md

@@ -1,9 +1,28 @@
-# config/ — Next.js Config Wrapper
+# config/ — Next.js Config + Server Bootstrap
 
 ## Next.js Config Wrapper (index.js)
 
-`withThepopebot()` wraps user's `next.config.mjs`. Adds `transpilePackages` and `serverExternalPackages` for the npm package's dependencies that need special bundling.
+`withThepopebot()` wraps the user's `next.config.mjs`. Adds `transpilePackages` and `serverExternalPackages` for npm-package dependencies that need special bundling (Drizzle, better-sqlite3, etc.).
 
-## Instrumentation (instrumentation.js)
+## Instrumentation Hook (instrumentation.js)
 
-Server startup hook loaded by Next.js. Sequence: loads `.env`, initializes database, starts cron scheduler, starts cluster runtime. Skipped during `next build` (checks `NEXT_PHASE`).
+Loaded by Next.js once on server start. The user's project re-exports it from their own `instrumentation.js`:
+
+```js
+export { register } from 'thepopebot/instrumentation';
+```
+
+### Boot sequence
+
+1. **Skip during `next build`** — checks `process.argv` for `'build'` to avoid keeping the event loop alive during build output.
+2. **Load `.env`** — `dotenv.config()` from project root.
+3. **Default `AUTH_URL` from `APP_URL`** — so NextAuth redirects to the correct host on sign-out.
+4. **Validate `AUTH_SECRET`** — throws if unset (required for session encryption).
+5. **`initDatabase()`** — `lib/db/index.js`. Opens SQLite, runs Drizzle migrations.
+6. **`migrateEnvToDb()`** — `lib/db/config.js`. Idempotent first-run migration of `.env` values into the settings table.
+7. **`loadCrons()`** — `lib/cron.js`. Reads `agent-job/CRONS.json`, schedules user-defined crons.
+8. **`startBuiltinCrons()`** — `lib/cron.js`. Starts internal crons (e.g., npm version check). Then warms the in-memory update flag from `lib/db/update-check.js`.
+9. **`startClusterRuntime()`** — `lib/cluster/runtime.js`. Registers cluster role triggers (cron + file watch + webhook).
+10. **`startMaintenanceCron()`** — `lib/maintenance.js`. Hourly cleanup of expired agent-job API keys and other housekeeping.
+
+`initialized` is module-scoped so the sequence runs exactly once even if `register()` is called more than once.

package/lib/channels/CLAUDE.md

@@ -27,6 +27,16 @@ Abstract interface for platform integrations. Methods:
 ## Telegram Adapter (telegram.js)
 
 - **Authorization**: per-user via the `user_channels` table. Unverified chats only accept `/verify <code>`; all other messages are dropped. See `lib/db/user-channels.js` and `lib/channels/commands/verify.js`.
-- **Session commands**: post-auth messages may be slash commands (`/session`, `/session list`, `/session <id>`) dispatched from `lib/channels/commands/`. Resolution chat.id → userId → activeThreadId lives in `api/index.js` `processChannelMessage`.
 - **Webhook auth**: Validates `x-telegram-bot-api-secret-token` header against `TELEGRAM_WEBHOOK_SECRET`.
-- **Streaming**: `supportsStreaming` returns `false` — sends complete responses only.
+- **Streaming**: `supportsStreaming` returns `false` — text + tool calls accumulate during streaming and are sent as complete messages once the turn ends. Progressive tool-call rendering (commit 740c734 / d9bf19a) inserts intermediate "→ used X" lines as tool calls land.
+
+## Slash Commands (`lib/channels/commands/`)
+
+Post-auth messages starting with `/` are dispatched here before reaching the LLM. Resolution chat.id → userId → activeThreadId happens in `api/index.js` `processChannelMessage`.
+
+| Command | Purpose | Source |
+|---------|---------|--------|
+| `/verify <code>` | Verify a Telegram account against a one-time code generated in the web UI (`/profile/telegram`). Code expires in 10 minutes. Sets `verifiedAt`. | `commands/verify.js` |
+| `/session` | List the user's recent chat threads (active thread marked) | `commands/session.js` |
+| `/session list` | Same as `/session` | `commands/session.js` |
+| `/session <id>` | Switch the user's `activeThreadId` so subsequent messages route to that chat | `commands/session.js` |

package/lib/chat/CLAUDE.md

@@ -38,10 +38,10 @@ export { getRepositoriesHandler as GET } from 'thepopebot/chat/api';
 ## Chat Streaming Flow
 
 1. Client sends message via AI SDK `DefaultChatTransport` → `POST /stream/chat`
-2. Handler validates session, extracts text + file attachments from message parts
-3. Calls `chatStream()` from `lib/ai/` which handles DB persistence and LLM invocation
-4. Streams response chunks (text deltas, tool calls, tool results) via `createUIMessageStream`
-5. After first message, client calls `/chat/finalize-chat` to generate auto-title
+2. Handler validates session, extracts text + file attachments from message parts. Images and PDFs pass through as vision content; text files are inlined into the prompt.
+3. Calls `chatStream()` from `lib/ai/` which handles DB persistence and LLM invocation. Two paths: SDK adapter (in-process, e.g. Claude Agent SDK) or direct headless container (other agents).
+4. Streams response chunks (text deltas, tool calls, tool results, thinking blocks) via `createUIMessageStream`. Tool call/tool result pairs and `{ type: 'error' }` chunks are persisted as JSON message parts.
+5. After the first user message streams, the client calls `/chat/finalize-chat` to generate the auto-title (helper LLM with truncated-description fallback).
 
 ## Server Actions (actions.js)
 

package/lib/chat/components/containers-page.js

@@ -3,7 +3,7 @@ import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { useState, useEffect, useCallback, useRef } from "react";
 import { createPortal } from "react-dom";
 import { PageLayout } from "./page-layout.js";
-import { SpinnerIcon, RefreshIcon, StopIcon, PlayIcon, TrashIcon, XIcon } from "./icons.js";
+import { SpinnerIcon, RefreshIcon, StopIcon, PlayIcon, TrashIcon, XIcon, FileTextIcon } from "./icons.js";
 import { ConfirmDialog } from "./ui/confirm-dialog.js";
 import { CodeLogView } from "./code-log-view.js";
 import {
@@ -195,81 +195,99 @@ function ContainerRow({ container, onRequestStop, onShowLogs, isStopping, isStar
     /* @__PURE__ */ jsx("td", { className: "py-2.5 pr-3 text-xs text-right hidden md:table-cell whitespace-nowrap", children: isRunning && container.stats ? /* @__PURE__ */ jsx("span", { children: formatBytes(container.stats.memUsage) }) : /* @__PURE__ */ jsx("span", { className: "text-muted-foreground", children: "\u2014" }) }),
     /* @__PURE__ */ jsx("td", { className: "py-2.5 pr-3 text-xs text-muted-foreground hidden lg:table-cell whitespace-nowrap", children: container.status }),
     /* @__PURE__ */ jsx("td", { className: "py-2.5 text-right whitespace-nowrap", children: /* @__PURE__ */ jsxs("div", { className: "inline-flex items-center gap-1.5", children: [
-      isRunning && (isStopping ? /* @__PURE__ */ jsxs(
+      /* @__PURE__ */ jsx(
+        "button",
+        {
+          onClick: () => onShowLogs(container.name),
+          title: "Logs",
+          "aria-label": "Logs",
+          className: "inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors",
+          children: /* @__PURE__ */ jsx(FileTextIcon, { size: 14 })
+        }
+      ),
+      isRunning && (isStopping ? /* @__PURE__ */ jsx(
         "button",
         {
           disabled: true,
-          className: "inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors",
-          children: [
-            /* @__PURE__ */ jsx(SpinnerIcon, { size: 12 }),
-            "Stopping..."
-          ]
+          title: "Stopping...",
+          "aria-label": "Stopping",
+          className: "inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors",
+          children: /* @__PURE__ */ jsx(SpinnerIcon, { size: 14 })
         }
-      ) : /* @__PURE__ */ jsxs(
+      ) : /* @__PURE__ */ jsx(
         "button",
         {
           onClick: () => onRequestStop(container.name),
-          className: "inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors",
-          children: [
-            /* @__PURE__ */ jsx(StopIcon, { size: 12 }),
-            "Stop"
-          ]
+          title: "Stop",
+          "aria-label": "Stop",
+          className: "inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors",
+          children: /* @__PURE__ */ jsx(StopIcon, { size: 14 })
         }
       )),
-      isStopped && (isStarting ? /* @__PURE__ */ jsxs(
+      isStopped && (isStarting ? /* @__PURE__ */ jsx(
         "button",
         {
           disabled: true,
-          className: "inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors",
-          children: [
-            /* @__PURE__ */ jsx(SpinnerIcon, { size: 12 }),
-            "Starting..."
-          ]
+          title: "Starting...",
+          "aria-label": "Starting",
+          className: "inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors",
+          children: /* @__PURE__ */ jsx(SpinnerIcon, { size: 14 })
         }
-      ) : /* @__PURE__ */ jsxs(
+      ) : /* @__PURE__ */ jsx(
         "button",
         {
           onClick: () => onRequestStop(container.name, "start"),
-          className: "inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors",
-          children: [
-            /* @__PURE__ */ jsx(PlayIcon, { size: 12 }),
-            "Start"
-          ]
+          title: "Start",
+          "aria-label": "Start",
+          className: "inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors",
+          children: /* @__PURE__ */ jsx(PlayIcon, { size: 14 })
         }
       )),
       /* @__PURE__ */ jsx(
-        "button",
-        {
-          onClick: () => onShowLogs(container.name),
-          className: "inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors",
-          children: "Logs"
-        }
-      ),
-      /* @__PURE__ */ jsxs(
         "button",
         {
           onClick: () => handleAction("remove"),
           disabled: removingContainer,
-          className: `inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border transition-colors disabled:opacity-50 disabled:pointer-events-none ${confirmingRemove ? "border-destructive text-destructive hover:bg-destructive/10" : "border-border text-muted-foreground hover:bg-accent hover:text-foreground"}`,
-          children: [
-            removingContainer ? /* @__PURE__ */ jsx(SpinnerIcon, { size: 12 }) : /* @__PURE__ */ jsx(TrashIcon, { size: 12 }),
-            confirmingRemove ? "Confirm" : "Remove"
-          ]
+          title: confirmingRemove ? "Confirm remove" : "Remove",
+          "aria-label": confirmingRemove ? "Confirm remove" : "Remove",
+          className: `inline-flex items-center justify-center rounded-md p-1.5 border transition-colors disabled:opacity-50 disabled:pointer-events-none ${confirmingRemove ? "border-destructive text-destructive hover:bg-destructive/10" : "border-border text-muted-foreground hover:bg-accent hover:text-foreground"}`,
+          children: removingContainer ? /* @__PURE__ */ jsx(SpinnerIcon, { size: 14 }) : /* @__PURE__ */ jsx(TrashIcon, { size: 14 })
         }
       )
     ] }) })
   ] });
 }
 function DockerContainersSection({ containers, loading, onRequestStop, onShowLogs, pendingStop, pendingStart }) {
+  const [activeTab, setActiveTab] = useState("running");
   if (loading) {
     return /* @__PURE__ */ jsxs("div", { className: "space-y-4", children: [
       /* @__PURE__ */ jsx("h2", { className: "text-base font-medium", children: "Docker Containers" }),
       /* @__PURE__ */ jsx("div", { className: "flex flex-col gap-3", children: [...Array(3)].map((_, i) => /* @__PURE__ */ jsx("div", { className: "h-14 animate-pulse rounded-md bg-border/50" }, i)) })
     ] });
   }
+  const runningContainers = containers.filter((c) => c.state === "running");
+  const exitedContainers = containers.filter((c) => c.state !== "running");
+  const visibleContainers = activeTab === "running" ? runningContainers : exitedContainers;
+  const tabs = [
+    { id: "running", label: `Running (${runningContainers.length})` },
+    { id: "exited", label: `Exited (${exitedContainers.length})` }
+  ];
   return /* @__PURE__ */ jsxs("div", { className: "space-y-4", children: [
     /* @__PURE__ */ jsx("h2", { className: "text-base font-medium", children: "Docker Containers" }),
-    containers.length === 0 ? /* @__PURE__ */ jsx("div", { className: "rounded-lg border border-dashed border-border p-8 text-center text-sm text-muted-foreground", children: "No containers found on the compose network." }) : /* @__PURE__ */ jsx("div", { className: "overflow-x-auto", children: /* @__PURE__ */ jsxs("table", { className: "w-full text-left", children: [
+    /* @__PURE__ */ jsx("div", { className: "flex gap-1.5 overflow-x-auto scrollbar-hide max-w-full", children: tabs.map((tab) => {
+      const isActive = activeTab === tab.id;
+      return /* @__PURE__ */ jsx(
+        "button",
+        {
+          type: "button",
+          onClick: () => setActiveTab(tab.id),
+          className: `rounded-full px-3 py-1.5 min-h-[36px] inline-flex items-center text-xs font-medium transition-colors shrink-0 whitespace-nowrap ${isActive ? "bg-foreground text-background" : "text-muted-foreground hover:text-foreground hover:bg-accent"}`,
+          children: tab.label
+        },
+        tab.id
+      );
+    }) }),
+    visibleContainers.length === 0 ? /* @__PURE__ */ jsx("div", { className: "rounded-lg border border-dashed border-border p-8 text-center text-sm text-muted-foreground", children: activeTab === "running" ? "No running containers." : "No exited containers." }) : /* @__PURE__ */ jsx("div", { className: "overflow-x-auto", children: /* @__PURE__ */ jsxs("table", { className: "w-full text-left", children: [
       /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { className: "text-xs text-muted-foreground", children: [
         /* @__PURE__ */ jsx("th", { className: "pb-2 pr-3 font-medium", children: "State" }),
         /* @__PURE__ */ jsx("th", { className: "pb-2 pr-3 font-medium", children: "Container" }),
@@ -278,7 +296,7 @@ function DockerContainersSection({ containers, loading, onRequestStop, onShowLog
         /* @__PURE__ */ jsx("th", { className: "pb-2 pr-3 font-medium hidden lg:table-cell", children: "Status" }),
         /* @__PURE__ */ jsx("th", { className: "pb-2 font-medium text-right", children: "Actions" })
       ] }) }),
-      /* @__PURE__ */ jsx("tbody", { children: containers.map((c) => /* @__PURE__ */ jsx(
+      /* @__PURE__ */ jsx("tbody", { children: visibleContainers.map((c) => /* @__PURE__ */ jsx(
         ContainerRow,
         {
           container: c,

package/lib/chat/components/containers-page.jsx

@@ -3,7 +3,7 @@
 import { useState, useEffect, useCallback, useRef } from 'react';
 import { createPortal } from 'react-dom';
 import { PageLayout } from './page-layout.js';
-import { SpinnerIcon, RefreshIcon, StopIcon, PlayIcon, TrashIcon, XIcon } from './icons.js';
+import { SpinnerIcon, RefreshIcon, StopIcon, PlayIcon, TrashIcon, XIcon, FileTextIcon } from './icons.js';
 import { ConfirmDialog } from './ui/confirm-dialog.js';
 import { CodeLogView } from './code-log-view.js';
 import {
@@ -263,22 +263,32 @@ function ContainerRow({ container, onRequestStop, onShowLogs, isStopping, isStar
       </td>
       <td className="py-2.5 text-right whitespace-nowrap">
         <div className="inline-flex items-center gap-1.5">
+          <button
+            onClick={() => onShowLogs(container.name)}
+            title="Logs"
+            aria-label="Logs"
+            className="inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+          >
+            <FileTextIcon size={14} />
+          </button>
           {isRunning && (
             isStopping ? (
               <button
                 disabled
-                className="inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors"
+                title="Stopping..."
+                aria-label="Stopping"
+                className="inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors"
               >
-                <SpinnerIcon size={12} />
-                Stopping...
+                <SpinnerIcon size={14} />
               </button>
             ) : (
               <button
                 onClick={() => onRequestStop(container.name)}
-                className="inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+                title="Stop"
+                aria-label="Stop"
+                className="inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
               >
-                <StopIcon size={12} />
-                Stop
+                <StopIcon size={14} />
               </button>
             )
           )}
@@ -286,38 +296,35 @@ function ContainerRow({ container, onRequestStop, onShowLogs, isStopping, isStar
             isStarting ? (
               <button
                 disabled
-                className="inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors"
+                title="Starting..."
+                aria-label="Starting"
+                className="inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground disabled:opacity-50 disabled:pointer-events-none transition-colors"
               >
-                <SpinnerIcon size={12} />
-                Starting...
+                <SpinnerIcon size={14} />
               </button>
             ) : (
               <button
                 onClick={() => onRequestStop(container.name, 'start')}
-                className="inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
+                title="Start"
+                aria-label="Start"
+                className="inline-flex items-center justify-center rounded-md p-1.5 border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
               >
-                <PlayIcon size={12} />
-                Start
+                <PlayIcon size={14} />
               </button>
             )
           )}
-          <button
-            onClick={() => onShowLogs(container.name)}
-            className="inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border border-border text-muted-foreground hover:bg-accent hover:text-foreground transition-colors"
-          >
-            Logs
-          </button>
           <button
             onClick={() => handleAction('remove')}
             disabled={removingContainer}
-            className={`inline-flex items-center gap-1 rounded-md px-2.5 py-1.5 text-xs font-medium border transition-colors disabled:opacity-50 disabled:pointer-events-none ${
+            title={confirmingRemove ? 'Confirm remove' : 'Remove'}
+            aria-label={confirmingRemove ? 'Confirm remove' : 'Remove'}
+            className={`inline-flex items-center justify-center rounded-md p-1.5 border transition-colors disabled:opacity-50 disabled:pointer-events-none ${
               confirmingRemove
                 ? 'border-destructive text-destructive hover:bg-destructive/10'
                 : 'border-border text-muted-foreground hover:bg-accent hover:text-foreground'
             }`}
           >
-            {removingContainer ? <SpinnerIcon size={12} /> : <TrashIcon size={12} />}
-            {confirmingRemove ? 'Confirm' : 'Remove'}
+            {removingContainer ? <SpinnerIcon size={14} /> : <TrashIcon size={14} />}
           </button>
         </div>
       </td>
@@ -330,6 +337,8 @@ function ContainerRow({ container, onRequestStop, onShowLogs, isStopping, isStar
 // ─────────────────────────────────────────────────────────────────────────────
 
 function DockerContainersSection({ containers, loading, onRequestStop, onShowLogs, pendingStop, pendingStart }) {
+  const [activeTab, setActiveTab] = useState('running');
+
   if (loading) {
     return (
       <div className="space-y-4">
@@ -343,12 +352,42 @@ function DockerContainersSection({ containers, loading, onRequestStop, onShowLog
     );
   }
 
+  const runningContainers = containers.filter((c) => c.state === 'running');
+  const exitedContainers = containers.filter((c) => c.state !== 'running');
+  const visibleContainers = activeTab === 'running' ? runningContainers : exitedContainers;
+
+  const tabs = [
+    { id: 'running', label: `Running (${runningContainers.length})` },
+    { id: 'exited', label: `Exited (${exitedContainers.length})` },
+  ];
+
   return (
     <div className="space-y-4">
       <h2 className="text-base font-medium">Docker Containers</h2>
-      {containers.length === 0 ? (
+
+      <div className="flex gap-1.5 overflow-x-auto scrollbar-hide max-w-full">
+        {tabs.map((tab) => {
+          const isActive = activeTab === tab.id;
+          return (
+            <button
+              key={tab.id}
+              type="button"
+              onClick={() => setActiveTab(tab.id)}
+              className={`rounded-full px-3 py-1.5 min-h-[36px] inline-flex items-center text-xs font-medium transition-colors shrink-0 whitespace-nowrap ${
+                isActive
+                  ? 'bg-foreground text-background'
+                  : 'text-muted-foreground hover:text-foreground hover:bg-accent'
+              }`}
+            >
+              {tab.label}
+            </button>
+          );
+        })}
+      </div>
+
+      {visibleContainers.length === 0 ? (
         <div className="rounded-lg border border-dashed border-border p-8 text-center text-sm text-muted-foreground">
-          No containers found on the compose network.
+          {activeTab === 'running' ? 'No running containers.' : 'No exited containers.'}
         </div>
       ) : (
         <div className="overflow-x-auto">
@@ -364,7 +403,7 @@ function DockerContainersSection({ containers, loading, onRequestStop, onShowLog
               </tr>
             </thead>
             <tbody>
-              {containers.map((c) => (
+              {visibleContainers.map((c) => (
                 <ContainerRow
                   key={c.id}
                   container={c}

package/lib/cluster/CLAUDE.md

@@ -41,9 +41,15 @@ Roles support multiple concurrent triggers. All paths use `canRunRole()` as a sh
 
 ## Concurrency & Validation
 
-`canRunRole(roleIdOrData)` is the shared gate function. It checks cluster enabled status and concurrency limits. Returns `{ allowed, reason?, roleData? }`. All trigger paths call this before `runClusterRole()`.
+`canRunRole(roleIdOrData)` is the synchronous validation function. It checks cluster enabled status and concurrency limits. Returns `{ allowed, reason?, roleData? }`. Reasons: `disabled` (cluster off), `concurrency` (at max), `not_found`.
 
-Each role has `maxConcurrency` (default 1). `canRunRole()` counts running instances via `listContainers()`. Reasons: `disabled` (cluster off), `concurrency` (at max), `not_found`.
+`acquireAndRunRole(roleId, payload?)` is the **atomic gate** that all trigger paths actually use. It calls `canRunRole()` and `runClusterRole()` together so two simultaneous triggers can't both pass the concurrency check before either container is observable to `listContainers()`. Manual UI triggers, webhooks, cron, and file-watch all funnel through this.
+
+Each role has `maxConcurrency` (default 1). `canRunRole()` counts running instances via `listContainers()`.
+
+## Plan Mode (Roles)
+
+`cluster_roles.planMode` (default `0`) gates the worker into Claude's plan-mode (read-only). When set, the worker is launched with `PERMISSION=plan` so it cannot execute mutating tools. Useful for review/analysis roles.
 
 ## Prompt Architecture
 
@@ -75,6 +81,6 @@ Built by `buildTemplateVars()` → `buildWorkerSystemPrompt()` + `resolveCluster
 ## DB Tables
 
 - `clusters` — cluster metadata (name, system_prompt, folders, enabled)
-- `cluster_roles` — role definitions scoped to a cluster (role_name, role, prompt, trigger_config, max_concurrency, cleanup_worker_dir, folders)
+- `cluster_roles` — role definitions scoped to a cluster (role_name, role, prompt, trigger_config, max_concurrency, plan_mode, cleanup_worker_dir, folders)
 
 Workers are ephemeral containers, not database entities.

package/lib/code/CLAUDE.md

@@ -2,7 +2,9 @@
 
 ## Data Flow
 
-Chat agent's `coding_agent` tool → `runInteractiveContainer()` in `lib/tools/docker.js` → Docker container runs `coding-agent-claude-code` image (interactive runtime) with ttyd on port 7681 → browser navigates to `/code/{id}` → `TerminalView` (xterm.js) opens WebSocket → `ws-proxy.js` authenticates and proxies to container.
+Chat agent's synthetic `coding_agent` tool wrapper → `runInteractiveContainer()` in `lib/tools/docker.js` → Docker container runs `coding-agent-{agent}` image (interactive runtime) → ttyd on port 7681 fronts a tmux session that runs the agent CLI → browser navigates to `/code/{id}` → `TerminalView` (xterm.js) opens WebSocket → `ws-proxy.js` authenticates and proxies to container.
+
+The interactive container's entrypoint launches a tmux session via the per-agent `docker/coding-agent/scripts/agents/<agent>/start-coding-session.sh` script. Multiple terminal tabs can attach to the same tmux session and survive WebSocket reconnects. Tab close + reopen reattaches; container restart re-creates the session with the prior agent session resumed (see "Session Continuity" below).
 
 ## WebSocket Auth
 
@@ -23,12 +25,18 @@ All actions use `requireAuth()` with ownership checks: `getCodeWorkspaces()`, `c
 
 ## Multi-Agent Backends
 
-Code workspaces support multiple coding agent backends. Agent selection is **global** via the `CODING_AGENT` config key (DB-backed, defaults to `claude-code`). There is no per-workspace agent selection — all workspaces use the globally configured agent.
+Code workspaces support multiple coding agent backends. Selection is **per-workspace** via the `codingAgent` column on `code_workspaces`, falling back to the global `CODING_AGENT` config key, then to `claude-code`. See `lib/code/actions.js:410`: `const agent = workspace.codingAgent || getConfig('CODING_AGENT') || 'claude-code';`. The same fallback chain is used by `lib/ai/index.js` for chat-mode streaming.
 
-**Supported agents**: `claude-code`, `pi`, `gemini-cli`, `codex-cli`, `opencode`. Each uses a different Docker image variant (`docker/coding-agent/Dockerfile.*`) and agent-specific setup/auth scripts in `docker/coding-agent/scripts/`.
+**Supported agents**: `claude-code`, `pi-coding-agent`, `gemini-cli`, `codex-cli`, `opencode`, `kimi-cli`. Each uses a different Docker image variant (`docker/coding-agent/Dockerfile.*`) and agent-specific setup/auth scripts in `docker/coding-agent/scripts/`.
 
 **Configuration**: Users configure agents via `/admin/event-handler/coding-agents` — enable/disable agents, set per-agent auth mode (OAuth vs API key), provider, and model. `setCodingAgentDefault()` sets the global default. `buildAgentAuthEnv()` in `lib/tools/docker.js` resolves credentials from the settings DB at container launch time.
 
 **Container streaming**: `lib/containers/stream.js` provides an SSE endpoint (`/stream/containers`) that polls Docker for container stats every 3 seconds. Used by the Containers admin page for live monitoring.
 
 **Backend API in messages**: When an agent produces output, the `backendApi` field in message chunks identifies which agent backend generated the response.
+
+## Session Continuity
+
+Code workspaces, chat-mode (SDK adapter), and headless agent jobs share session continuity through `lib/ai/session-manager.js`. Session IDs are written to per-port files inside the workspace volume — `~/.{agent}-ttyd-sessions/${PORT}` (or scope-prefixed when `SCOPE` is set). The agent CLI captures its session ID via per-agent hooks (see `docker/coding-agent/CLAUDE.md` § Session Tracking for the 5 patterns). On the next launch the entrypoint reads the saved ID and passes the agent's resume flag (`--continue`, `--resume`, `--session`, depending on agent).
+
+Headless `run.sh` always reads from port `7681` — so SDK chat, manual chat tools, and code workspaces all converge on the same conversation when they share a workspace.

package/lib/containers/CLAUDE.md

@@ -1,9 +1,19 @@
 # lib/containers/ — Container Streaming
 
-`stream.js` exports `GET(request)` — an SSE route handler for real-time Docker container monitoring.
+Two SSE endpoints — both authenticated via `auth()` session.
 
-**Endpoint**: `/stream/containers` (actual SSE streaming, stays in `/stream/`)
-**Auth**: `auth()` session check
-**Events**: `containers` (every 3s with full container list + CPU/memory stats), `ping` (keepalive every 15s)
-**Data source**: `listNetworkContainers()` + `getContainerStats()` from `lib/tools/docker.js`
-**Client**: `ContainersPage` connects via `new EventSource('/stream/containers')`
+## `stream.js` — Container Status
+
+- **Endpoint**: `/stream/containers`
+- **Events**: `containers` (every 3s with full container list + CPU/memory stats), `ping` (keepalive every 15s)
+- **Data source**: `listNetworkContainers()` + `getContainerStats()` from `lib/tools/docker.js`. Filtered to containers on the event-handler's Docker network (auto-detected at boot).
+- **Client**: `ContainersPage` connects via `new EventSource('/stream/containers')`
+
+## `logs.js` — Container Log Tail
+
+- **Endpoint**: `/stream/containers/logs?name=<containerName>`
+- **Events**: raw log lines as SSE `data:` frames
+- **Data source**: Docker `containers/{id}/logs?follow=true&stdout=1&stderr=1` via the multiplexed-stream parser in `lib/tools/docker.js`
+- **Client**: `ContainerLogsView` (used from the Containers admin page when a row's logs are expanded)
+
+Both endpoints share the same network filter and frame-decoding logic so all SSE consumers see the same view.

package/lib/db/CLAUDE.md

@@ -25,11 +25,12 @@ Key files: `schema.js` (source of truth), `drizzle/` (generated migrations), `dr
 | `users` | Admin accounts (email, bcrypt password hash, role) |
 | `chats` | Chat sessions (user_id, title, starred, chat_mode, code_workspace_id, timestamps) |
 | `messages` | Chat messages (chat_id, role, content) |
-| `code_workspaces` | Code workspace containers (user_id, container_name, repo, branch, feature_branch, title, last_interactive_commit, starred, has_changes) |
+| `code_workspaces` | Code workspace containers (user_id, container_name, repo, branch, feature_branch, title, last_interactive_commit, coding_agent, scope, starred, has_changes) |
 | `notifications` | Job completion notifications (notification text, payload, read status) |
 | `subscriptions` | Channel subscriptions (platform, channel_id) |
+| `user_channels` | Per-user channel linking (user_id, channel, channel_chat_id, code, code_expires_at, verified_at, active_thread_id) — Telegram verification + active thread |
 | `clusters` | Worker clusters (user_id, name, system_prompt, folders, enabled, starred) |
-| `cluster_roles` | Role definitions scoped to a cluster (cluster_id, role_name, role, trigger_config, max_concurrency, cleanup_worker_dir, folders) |
+| `cluster_roles` | Role definitions scoped to a cluster (cluster_id, role_name, role, trigger_config, max_concurrency, plan_mode, cleanup_worker_dir, folders) |
 | `settings` | Key-value configuration store (also stores API keys and OAuth tokens via type/key/value) |
 
 ## OAuth Token Storage
@@ -64,3 +65,5 @@ OAuth tokens for coding agent backends are stored as `config_secret` with LRU ro
 - `chats.chatMode` — `'agent'` (default) or `'code'`. Determines which agent singleton and tools are used.
 - `codeWorkspaces.featureBranch` — tracks the git feature branch for the workspace session.
 - `codeWorkspaces.hasChanges` — flag set when workspace has uncommitted changes.
+- `codeWorkspaces.codingAgent` — per-workspace coding-agent override. Falls back to global `CODING_AGENT` config, then `claude-code` (`lib/code/actions.js:410`).
+- `codeWorkspaces.scope` — subdirectory scope within the repo (e.g., `agents/gary-vee`). Resolves the agent's working directory and skills (`lib/ai/scope.js`).

package/lib/tools/CLAUDE.md

@@ -12,7 +12,16 @@ Calls Docker Engine API directly through `/var/run/docker.sock` using Node's `ht
 
 **Image pull on demand**: Checks if image exists locally before pulling. Avoids pre-pulling at startup.
 
-**`buildAgentAuthEnv(agent)`**: Resolves coding agent type → auth environment variables from the settings DB. Handles OAuth vs API key auth modes, multi-provider resolution (builtin + custom), and model overrides. Each agent type (claude-code, pi, gemini-cli, codex-cli, opencode) has its own credential resolution path. OAuth tokens use LRU rotation via `getNextOAuthToken()`. All credentials come from the DB, not `.env` or GitHub secrets.
+**`buildAgentAuthEnv(agent)`**: Resolves coding agent type → auth environment variables from the settings DB. All credentials come from the DB (`getConfig`, `getCustomProvider`), never `.env` or GitHub secrets. Returns `{ env: string[], backendApi: string }`.
+
+Per-agent resolution paths:
+
+- **`claude-code`** — `CODING_AGENT_CLAUDE_CODE_BACKEND` selects backend. If `anthropic`, picks OAuth (`CLAUDE_CODE_OAUTH_TOKEN` via LRU rotation) or API key (`ANTHROPIC_API_KEY`). For Anthropic-compatible third parties (DeepSeek, MiniMax, Kimi, OpenRouter) sets `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_BASE_URL` to the provider's `anthropicEndpoint`. For OpenAI-only builtins or custom providers, routes through the LiteLLM sidecar at `http://litellm:4000` and prefixes the model with the provider key.
+- **`pi-coding-agent`, `opencode`, `kimi-cli`** — share a multi-provider pattern. `CODING_AGENT_{AGENT}_PROVIDER` picks anthropic/openai/google/deepseek/minimax/mistral/xai/openrouter/nvidia or a custom provider. Sets the matching `*_API_KEY` (or `CUSTOM_OPENAI_BASE_URL` + `CUSTOM_API_KEY` for custom).
+- **`gemini-cli`** — `GOOGLE_API_KEY` only. Backend is always `google`.
+- **`codex-cli`** — OAuth (`CODEX_OAUTH_TOKEN`) or API key (`OPENAI_API_KEY`). Backend always `openai`.
+
+OAuth tokens use LRU rotation via `getNextOAuthToken()` (in `lib/db/oauth-tokens.js`) — distributes load across multiple stored tokens and updates `lastUsedAt` on each pick. Refresh-token rotation is handled at retrieval time in `/api/get-agent-job-secret` (under a per-token lock).
 
 ## create-agent-job.js — Agent Job Creation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thepopebot",
-  "version": "1.2.76-beta.19",
+  "version": "1.2.76-beta.20",
   "type": "module",
   "description": "Create autonomous AI agents with a two-layer architecture: Next.js Event Handler + Docker Agent.",
   "bin": {

package/setup/CLAUDE.md

@@ -4,13 +4,19 @@ Entry point: `setup.mjs` (invoked via `thepopebot setup`).
 
 ## Wizard Steps
 
-1. **Prerequisites** — Checks Node.js (>=18), git, gh CLI (authenticated), Docker. Initializes git repo and GitHub remote if needed.
-2. **GitHub PAT** — Validates fine-grained token with required scopes (Actions, Admin, Contents, PRs, Secrets, Workflows).
-3. **App URL** — Prompts for public HTTPS URL (ngrok, VPS, PaaS). Generates webhook secret.
-4. **Sync Config** — Writes secrets/variables to GitHub and local DB via `syncConfig()`.
-5. **Build** — Runs `npm run build` with retry.
+1. **Load `.env`** — `dotenv.config()` runs first so existing values are available to subsequent steps.
+2. **Prerequisites** — Checks Node.js (>=18), git, gh CLI (authenticated), Docker. Initializes git repo and GitHub remote if needed.
+3. **GitHub PAT** — Validates fine-grained token with required scopes (Actions, Admin, Contents, PRs, Secrets, Workflows).
+4. **App URL** — Prompts for public HTTPS URL (ngrok, VPS, PaaS). Generates webhook secret.
+5. **Sync Config** — Writes secrets/variables to GitHub and local DB via `syncConfig()`.
 6. **Start Server** — Starts Docker containers, polls `/api/ping` to confirm.
 
+The setup wizard does NOT run `npm run build` — `.next` is baked into the event-handler Docker image at publish time.
+
+## Database
+
+Settings DB defaults to `data/db/thepopebot.sqlite` (relative to project root). Override via `DATABASE_PATH` in `.env`. Schema migrations run automatically on server start (`lib/db/index.js`).
+
 ## Sync Target Types
 
 Config values are synced to different targets via `lib/sync.mjs`:

package/templates/CLAUDE.md.template

@@ -20,16 +20,14 @@ This is a [thepopebot](https://github.com/stephengpope/thepopebot) project.
 
 ## Managed Files
 
-Some files are auto-synced by `npx thepopebot init` and will be overwritten on upgrade. Do not edit these:
+Some files are auto-synced by `npx thepopebot init` and will be overwritten on every init/upgrade. Do not edit these:
 
 - `.github/workflows/` — CI/CD workflows
 - `docker-compose.yml`
 - `.dockerignore`
 - `.gitignore`
-- `agent-job/CLAUDE.md`
-- `agents/CLAUDE.md`
-- `event-handler/CLAUDE.md`
-- `skills/CLAUDE.md`
+
+The `CLAUDE.md` files scattered through the project tree (e.g. `agent-job/CLAUDE.md`, `agents/CLAUDE.md`, `event-handler/CLAUDE.md`, `skills/CLAUDE.md`) are scaffolded by `init` from `*.template` sources but are **not** in the managed-paths list — they will not be overwritten if you have edited them. Run `npx thepopebot reset <path>` to restore one to its template default, or `npx thepopebot diff <path>` to see your local changes.
 
 ## Agent Scoping
 

package/templates/agents/CLAUDE.md.template

@@ -2,15 +2,20 @@
 
 ## Adding an Agent
 
-Each subdirectory defines an agent. Create a folder with a `SYSTEM.md` file:
+Each subdirectory defines an agent. At minimum create a folder with a `SYSTEM.md` file:
 
 ```
 agents/
 └── my-agent/
-    └── SYSTEM.md        # System prompt — identity, instructions, constraints
+    ├── SYSTEM.md        # System prompt — identity, instructions, constraints (required)
+    ├── CLAUDE.md        # Optional — guidance for AI assistants editing this agent's files
+    ├── skills/          # Optional — agent-specific skills (overrides root skills/ for this scope)
+    └── jobs/            # Optional — reusable task prompts referenced from CRONS.json
 ```
 
-`SYSTEM.md` is the agent's system prompt. Write it in markdown addressed to the agent (e.g. "You are a code reviewer...").
+`SYSTEM.md` is the agent's system prompt. Write it in markdown addressed to the agent (e.g. "You are a code reviewer..."). `CLAUDE.md` (if present) is read by AI assistants working in this directory — use it for non-obvious context only.
+
+**Skills resolution**: when a job runs with `scope: "agents/my-agent"`, the runtime checks `agents/my-agent/skills/` first; missing skills fall back to root `skills/`. To override a built-in skill for one agent, drop a same-named SKILL.md under that agent's `skills/`.
 
 > **Important:** `agents/<name>/SYSTEM.md` **replaces** `agent-job/SYSTEM.md` when the agent is scoped — it doesn't extend it. Use `agent-job/SYSTEM.md` as a starting template and adapt it: keep the runtime environment notes, the `/tmp` scratch directive, and add the `{{skills}}` token if you want skill descriptions injected. Then add the agent's identity-specific instructions on top.
 

package/templates/data/CLAUDE.md.template

@@ -1,5 +1,5 @@
 # Data Directory
 
-Runtime data including the SQLite database (`thepopebot.sqlite`) and cluster state. Created automatically on server start.
+Runtime data including the SQLite database (`db/thepopebot.sqlite`) and cluster state. Created automatically on server start. Override the DB path with `DATABASE_PATH` in `.env`.
 
 Not checked into git.

package/templates/event-handler/CLAUDE.md.template

@@ -0,0 +1,79 @@
+# event-handler/ — Event Handler Configuration
+
+This directory holds configuration for the event handler: webhook triggers, chat system prompts, cluster role definitions, LiteLLM proxy routing, and the job-summary prompt. Edit these to shape how your handler reacts to events.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `TRIGGERS.json` | Webhook trigger definitions — fires actions when matching paths receive HTTP requests |
+| `agent-chat/SYSTEM.md` | System prompt for the chat agent (default chat mode) |
+| `code-chat/SYSTEM.md` | System prompt for code mode chat (workspace-aware) |
+| `clusters/SYSTEM.md` | System prompt prepended to every cluster worker |
+| `clusters/ROLE.md` | Role-template snippet referenced by cluster role definitions |
+| `litellm/main.yaml` | LiteLLM proxy config — routes Claude Code through other providers |
+| `SUMMARY.md` | System prompt for the auto-summary that runs after agent jobs complete |
+
+## TRIGGERS.json
+
+JSON array of webhook trigger definitions. Loaded at server boot by `lib/triggers.js`.
+
+```json
+{
+  "name": "review-github-event",
+  "watch_path": "/github/webhook",
+  "actions": [
+    { "type": "agent", "job": "Summarize this GitHub event:\n{{body}}" }
+  ],
+  "enabled": true
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `name` | Yes | Unique within the file |
+| `watch_path` | Yes | Path to match (`/github/webhook`, `/webhook`, custom paths) |
+| `actions` | Yes | Array — runs in order, fire-and-forget after auth |
+| `enabled` | No | Defaults `true`. Set `false` to keep the entry but skip it |
+
+### Action types
+
+Three types — `agent`, `command`, `webhook`. `agent` accepts optional `scope`, `agent_backend`, `llm_model` overrides:
+
+```json
+{ "type": "agent", "job": "Process: {{body}}", "scope": "agents/triage", "agent_backend": "claude-code", "llm_model": "claude-sonnet-4-5-20250929" }
+{ "type": "command", "command": "echo 'webhook received: {{body}}' >> logs/webhook.log" }
+{ "type": "webhook", "url": "https://example.com/hook", "method": "POST", "headers": {}, "vars": { "source": "github" } }
+```
+
+`scope` resolves to a directory under `agents/` (see `agents/CLAUDE.md`). The agent runs with that directory as its working dir, picks up its `SYSTEM.md`, and uses the skills under `agents/<scope>/skills/` falling back to root `skills/`.
+
+### Template tokens (in `job` and `command` strings)
+
+`{{body}}`, `{{body.field}}`, `{{query}}`, `{{query.field}}`, `{{headers}}`, `{{headers.field}}`. Tokens are expanded when the trigger fires.
+
+## Chat System Prompts
+
+`agent-chat/SYSTEM.md` and `code-chat/SYSTEM.md` are the system prompts injected into chat sessions. They support `{{include path/to/file.md}}`, `{{datetime}}`, and `{{skills}}` variables (resolved by `lib/utils/render-md.js`).
+
+- **Agent chat** (`agent-chat/`) — default chat mode. Workspace-agnostic.
+- **Code chat** (`code-chat/`) — code-mode chat. Knows about the active code workspace, repo, branch, and feature branch.
+
+Both can be scoped: a chat tied to a workspace with `scope: "agents/foo"` will load `agents/foo/SYSTEM.md` instead of these defaults.
+
+## Cluster Configuration
+
+`clusters/SYSTEM.md` is prepended to every cluster worker's system prompt. `clusters/ROLE.md` is a reusable role-template snippet that individual cluster role definitions can reference. Cluster behavior is configured in the Admin UI; these files supply the prompt context.
+
+## LiteLLM Proxy
+
+`litellm/main.yaml` is read by the optional LiteLLM sidecar (`docker-compose.litellm.yml`). It routes Claude Code's Anthropic-protocol calls to other providers (OpenAI, Gemini, custom OpenAI-compatible endpoints). Edit when you want to use Claude Code with a non-Anthropic backend. Refer to [LiteLLM docs](https://docs.litellm.ai/) for the schema.
+
+## Summary Prompt
+
+`SUMMARY.md` is the prompt for the helper LLM call that auto-summarizes agent job results (PR link, status, files changed). Tweak its tone or formatting here.
+
+## Notes
+
+- These files are user-owned — edits are preserved across `thepopebot upgrade`.
+- The Admin UI (`/admin/event-handler/`) configures runtime defaults (LLM provider, coding agent backend, OAuth tokens). Trigger-level `agent_backend` / `llm_model` overrides those defaults.

package/templates/skills/CLAUDE.md.template

@@ -69,9 +69,14 @@ If a skill needs an API key, add it via the admin UI (Settings > Agent Jobs > Se
 
 Skills are active when present in the `skills/` directory. To deactivate, remove or move the skill directory out.
 
-All coding agents discover skills from the same `skills/` directory via symlink bridges:
-- `.claude/skills → ../skills`
-- `.pi/skills → ../skills`
+All coding agents discover skills from the same `skills/` directory via symlink bridges created by `npx thepopebot init`:
+
+- `.claude/skills → ../skills` (Claude Code)
+- `.pi/skills → ../skills` (Pi)
+- `.codex/skills → ../skills` (Codex CLI)
+- `.gemini/skills → ../skills` (Gemini CLI)
+- `.kimi/skills → ../skills` (Kimi CLI)
+- `.agents/skills → ../skills` (OpenCode and other plugin-style agents)
 
 ## Creating a Skill