thepopebot 1.2.75-beta.2 → 1.2.75-beta.21

package/templates/docker-compose.custom.yml

@@ -1,7 +1,19 @@
-# Custom Docker Compose configuration
+# Custom Docker Compose — SSL with Let's Encrypt wildcard cert
 # This file is NOT managed by thepopebot and won't be overwritten on upgrade.
-# To activate: set COMPOSE_FILE=docker-compose.custom.yml in .env
-# Make your customizations here (TLS, ports, volumes, extra services, etc.)
+#
+# Activate: set COMPOSE_FILE=docker-compose.custom.yml in .env
+# Setup:    npx thepopebot setup-ssl
+#
+# Requires these .env vars (set by setup-ssl):
+#   SSL_DOMAIN          — your domain (e.g., bot.example.com)
+#   SSL_EMAIL           — email for Let's Encrypt notifications
+#   SSL_DNS_PROVIDER    — Traefik DNS provider name (e.g., cloudflare)
+#
+# DNS provider API credentials are stored in .env.traefik (created by setup-ssl).
+# Only this file is passed to the Traefik container — not the main .env.
+#
+# DNS: *.${SSL_DOMAIN} must resolve to this server (A record or CNAME).
+# The setup-ssl command can create this record for you.
 
 services:
   traefik:
@@ -9,20 +21,22 @@ services:
     command:
       - --providers.docker=true
       - --providers.docker.exposedByDefault=false
+      - --providers.file.directory=/traefik-config/
       - --entrypoints.web.address=:80
       - --entrypoints.websecure.address=:443
-      ## Uncomment the following lines to enable TLS via Let's Encrypt
-      ## (requires LETSENCRYPT_EMAIL in .env):
-      # - --entrypoints.web.http.redirections.entrypoint.to=websecure
-      # - --entrypoints.web.http.redirections.entrypoint.scheme=https
-      # - --certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}
-      # - --certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json
-      # - --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web
+      - --entrypoints.web.http.redirections.entrypoint.to=websecure
+      - --entrypoints.web.http.redirections.entrypoint.scheme=https
+      - --certificatesresolvers.letsencrypt.acme.email=${SSL_EMAIL}
+      - --certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json
+      - --certificatesresolvers.letsencrypt.acme.dnschallenge.provider=${SSL_DNS_PROVIDER}
+      - --certificatesresolvers.letsencrypt.acme.dnschallenge.resolvers=8.8.8.8:53,8.8.4.4:53
+    env_file: .env.traefik
     ports:
       - "80:80"
       - "443:443"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./traefik-config:/traefik-config:ro
       - traefik_certs:/letsencrypt
     restart: unless-stopped
 
@@ -31,24 +45,24 @@ services:
     image: ${EVENT_HANDLER_IMAGE_URL:-stephengpope/thepopebot:event-handler-${THEPOPEBOT_VERSION:-latest}}
     volumes:
       - .:/project
-      - ./config:/app/config
+      - ./agent-job:/app/agent-job
+      - ./event-handler:/app/event-handler
       - ./skills:/app/skills
       - ./.env:/app/.env
       - ./data:/app/data
       - ./logs:/app/logs
-      - ./cron:/app/cron
-      - ./triggers:/app/triggers
-      - ./CLAUDE.md:/app/CLAUDE.md
+      - ./traefik-config:/traefik-config
       - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      - TRAEFIK_CONFIG_DIR=/traefik-config
     labels:
       - traefik.enable=true
-      # Set APP_HOSTNAME in .env to the domain from APP_URL (e.g., mybot.example.com)
       - traefik.http.routers.event-handler.rule=Host(`${APP_HOSTNAME}`)
-      - traefik.http.routers.event-handler.entrypoints=web
+      - traefik.http.routers.event-handler.entrypoints=websecure
+      - traefik.http.routers.event-handler.tls.certresolver=letsencrypt
+      - traefik.http.routers.event-handler.tls.domains[0].main=${SSL_DOMAIN}
+      - traefik.http.routers.event-handler.tls.domains[0].sans=*.${SSL_DOMAIN}
       - traefik.http.services.event-handler.loadbalancer.server.port=80
-      ## Uncomment the following lines to enable TLS via Let's Encrypt:
-      # - traefik.http.routers.event-handler.entrypoints=websecure
-      # - traefik.http.routers.event-handler.tls.certresolver=letsencrypt
     stop_grace_period: 120s
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:80/api/ping"]
@@ -58,6 +72,13 @@ services:
       start_period: 30s
     restart: unless-stopped
 
+  litellm:
+    image: ghcr.io/berriai/litellm:main-latest
+    command: --config /litellm/main.yaml --port 4000
+    volumes:
+      - ./event-handler/litellm:/litellm:ro
+    restart: unless-stopped
+
   runner:
     image: myoung34/github-runner:latest
     deploy:
@@ -68,6 +89,7 @@ services:
       RUNNER_SCOPE: repo
       LABELS: self-hosted
       EPHEMERAL: "1"
+      DISABLE_AUTO_UPDATE: "true"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - .:/project
@@ -75,46 +97,3 @@ services:
 
 volumes:
   traefik_certs:
-
-# ──────────────────────────────────────────────────────────────────────
-# Tailscale TLS Example
-# ──────────────────────────────────────────────────────────────────────
-# To use Tailscale HTTPS certs instead of Let's Encrypt:
-#
-# 1. On your Tailscale machine, run:
-#      sudo tailscale cert <your-machine-name>.<tailnet>.ts.net
-#    This creates .crt and .key files in /var/lib/tailscale/certs/
-#
-# 2. Copy traefik-dynamic.yml.example to traefik-dynamic.yml and
-#    replace YOUR_HOSTNAME with your full Tailscale machine name.
-#
-# 3. Replace the traefik service above with:
-#
-#  traefik:
-#    image: traefik:v3
-#    command:
-#      - --providers.docker=true
-#      - --providers.docker.exposedByDefault=false
-#      - --providers.file.filename=/etc/traefik/dynamic.yml
-#      - --entrypoints.web.address=:80
-#      - --entrypoints.web.http.redirections.entrypoint.to=websecure
-#      - --entrypoints.web.http.redirections.entrypoint.scheme=https
-#      - --entrypoints.websecure.address=:443
-#    ports:
-#      - "80:80"
-#      - "443:443"
-#    volumes:
-#      - /var/run/docker.sock:/var/run/docker.sock:ro
-#      - ./traefik-dynamic.yml:/etc/traefik/dynamic.yml:ro
-#      - /var/lib/tailscale/certs:/certs:ro
-#    restart: unless-stopped
-#
-# 4. Update the event-handler labels:
-#
-#  event-handler:
-#    labels:
-#      - traefik.enable=true
-#      - traefik.http.routers.event-handler.rule=Host(`${APP_HOSTNAME}`)
-#      - traefik.http.routers.event-handler.entrypoints=websecure
-#      - traefik.http.routers.event-handler.tls=true
-#      - traefik.http.services.event-handler.loadbalancer.server.port=80

package/templates/docker-compose.yml

@@ -4,21 +4,13 @@ services:
     command:
       - --providers.docker=true
       - --providers.docker.exposedByDefault=false
+      - --providers.file.directory=/traefik-config/
       - --entrypoints.web.address=:80
-      - --entrypoints.websecure.address=:443
-      ## Uncomment the following lines to enable TLS via Let's Encrypt
-      ## (requires LETSENCRYPT_EMAIL in .env):
-      # - --entrypoints.web.http.redirections.entrypoint.to=websecure
-      # - --entrypoints.web.http.redirections.entrypoint.scheme=https
-      # - --certificatesresolvers.letsencrypt.acme.email=${LETSENCRYPT_EMAIL}
-      # - --certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json
-      # - --certificatesresolvers.letsencrypt.acme.httpchallenge.entrypoint=web
     ports:
       - "80:80"
-      - "443:443"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock:ro
-      - traefik_certs:/letsencrypt
+      - ./traefik-config:/traefik-config:ro
     restart: unless-stopped
 
   event-handler:
@@ -26,24 +18,21 @@ services:
     image: ${EVENT_HANDLER_IMAGE_URL:-stephengpope/thepopebot:event-handler-${THEPOPEBOT_VERSION:-latest}}
     volumes:
       - .:/project
-      - ./config:/app/config
+      - ./agent-job:/app/agent-job
+      - ./event-handler:/app/event-handler
       - ./skills:/app/skills
       - ./.env:/app/.env
       - ./data:/app/data
       - ./logs:/app/logs
-      - ./cron:/app/cron
-      - ./triggers:/app/triggers
-      - ./CLAUDE.md:/app/CLAUDE.md
+      - ./traefik-config:/traefik-config
       - /var/run/docker.sock:/var/run/docker.sock
+    environment:
+      - TRAEFIK_CONFIG_DIR=/traefik-config
     labels:
       - traefik.enable=true
-      # Set APP_HOSTNAME in .env to the domain from APP_URL (e.g., mybot.example.com)
       - traefik.http.routers.event-handler.rule=Host(`${APP_HOSTNAME}`)
       - traefik.http.routers.event-handler.entrypoints=web
       - traefik.http.services.event-handler.loadbalancer.server.port=80
-      ## Uncomment the following lines to enable TLS via Let's Encrypt:
-      # - traefik.http.routers.event-handler.entrypoints=websecure
-      # - traefik.http.routers.event-handler.tls.certresolver=letsencrypt
     stop_grace_period: 120s
     healthcheck:
       test: ["CMD", "curl", "-f", "http://localhost:80/api/ping"]
@@ -53,6 +42,13 @@ services:
       start_period: 30s
     restart: unless-stopped
 
+  litellm:
+    image: ghcr.io/berriai/litellm:main-latest
+    command: --config /litellm/main.yaml --port 4000
+    volumes:
+      - ./event-handler/litellm:/litellm:ro
+    restart: unless-stopped
+
   runner:
     image: myoung34/github-runner:latest
     deploy:
@@ -68,6 +64,3 @@ services:
       - /var/run/docker.sock:/var/run/docker.sock
       - .:/project
     restart: unless-stopped
-
-volumes:
-  traefik_certs:

package/templates/logs/CLAUDE.md.template

@@ -0,0 +1,5 @@
+# Logs Directory
+
+Agent job logs, organized by job ID. Each subdirectory contains the system prompt, task prompt, and agent output for a single job run.
+
+Not checked into git.

package/templates/skills/CLAUDE.md.template

@@ -1,6 +1,6 @@
 # skills/ — Agent Skills
 
-Skills are lightweight plugins that extend agent abilities. Each skill lives in `skills/<skill-name>/` and is activated by symlinking into `skills/active/`.
+Skills are lightweight plugins that extend agent abilities. Each skill lives in `skills/library/<skill-name>/` and is activated by symlinking into `skills/active/`.
 
 ## How Skills Work
 
@@ -10,7 +10,30 @@ Skills are lightweight plugins that extend agent abilities. Each skill lives in
 
 Both Pi and Claude Code discover skills from the same `skills/active/` directory (via `.pi/skills` and `.claude/skills` symlink bridges).
 
-## SKILL.md Format
+## Conventions
+
+### Language Preference
+
+**Bash first.** Skills are glue code — API calls, data piping, file manipulation. Bash + curl + python3 (for JSON) handles nearly everything. No module systems, no dependency management, no surprises.
+
+Use Node.js **only** when a required library has no alternative (e.g., `youtube-transcript-plus`). Never for new skills where bash + curl would work.
+
+### Bash Script Standards
+
+- Include `#!/bin/bash` and `set -euo pipefail` at the top
+- `chmod +x` after creating
+
+### Node.js Module Rules
+
+The root `package.json` has `"type": "module"`, which forces **all** `.js` files in the project tree to be treated as ESM. This silently breaks any script using `require()`.
+
+- **`.cjs`** — for CommonJS scripts (uses `require()`)
+- **`.mjs`** — for ESM scripts (uses `import`)
+- **Never use plain `.js`** for skill scripts. The behavior depends on the nearest `package.json` and will break unpredictably.
+
+If you encounter a broken `.js` script in a skill, rename it to `.cjs` or `.mjs` as appropriate and update SKILL.md references.
+
+### SKILL.md Format
 
 Every skill must have a `SKILL.md` with YAML frontmatter:
 
@@ -25,28 +48,46 @@ description: One sentence describing what the skill does and when to use it.
 ## Usage
 
 ```bash
-skills/skill-name/script.sh <args>
+skills/library/skill-name/script.sh <args>
 ```
 ```
 
 - The `description` field appears in the system prompt — keep it concise and action-oriented.
-- Use project-root-relative paths in documentation (e.g., `skills/skill-name/script.sh`).
+- Use project-root-relative paths in documentation (e.g., `skills/library/skill-name/script.sh`).
 
-## Skill Structure
+### Skill Structure
 
 - **`SKILL.md`** (required) — YAML frontmatter + markdown documentation
-- **Scripts** (optional) — prefer bash (`.sh`) for simplicity
+- **Scripts** — bash (`.sh`) by default, `.cjs`/`.mjs` only when necessary
 - **`package.json`** (optional) — only if Node.js dependencies are truly needed
 
+### Credential Setup
+
+If a skill needs an API key, add it via the admin UI (Settings > Agent Jobs > Secrets). The secret will be injected as an env var into Docker containers. The agent can discover available secrets via the `get-secret` skill.
+
+### Activation & Deactivation
+
+```bash
+# Activate
+ln -s ../library/skill-name skills/active/skill-name
+
+# Deactivate
+rm skills/active/skill-name
+```
+
+The `skills/active/` directory is shared by both agent backends via symlink bridges:
+- `.claude/skills → skills/active`
+- `.pi/skills → skills/active`
+
 ## Creating a Skill
 
 ### Simple bash skill (most common)
 
 ```bash
-mkdir skills/my-skill
+mkdir skills/library/my-skill
 ```
 
-**skills/my-skill/SKILL.md:**
+**skills/library/my-skill/SKILL.md:**
 ```markdown
 ---
 name: my-skill
@@ -60,13 +101,15 @@ Requires MY_API_KEY environment variable.
 
 ## Usage
 ```bash
-skills/my-skill/run.sh <args>
+skills/library/my-skill/run.sh <args>
 ```
 ```
 
-**skills/my-skill/run.sh:**
+**skills/library/my-skill/run.sh:**
 ```bash
 #!/bin/bash
+set -euo pipefail
+
 if [ -z "$1" ]; then echo "Usage: run.sh <args>"; exit 1; fi
 if [ -z "$MY_API_KEY" ]; then echo "Error: MY_API_KEY not set"; exit 1; fi
 # ... skill logic
@@ -74,31 +117,13 @@ if [ -z "$MY_API_KEY" ]; then echo "Error: MY_API_KEY not set"; exit 1; fi
 
 Then make it executable and activate:
 ```bash
-chmod +x skills/my-skill/run.sh
-ln -s ../my-skill skills/active/my-skill
+chmod +x skills/library/my-skill/run.sh
+ln -s ../library/my-skill skills/active/my-skill
 ```
 
 ### Node.js skill
 
-Use this pattern only when bash + curl isn't sufficient (e.g., HTML parsing, complex data processing). Add a `package.json` with dependencies — they're installed automatically in Docker.
-
-## Activation & Deactivation
-
-```bash
-# Activate
-ln -s ../skill-name skills/active/skill-name
-
-# Deactivate
-rm skills/active/skill-name
-```
-
-The `skills/active/` directory is shared by both agent backends via symlink bridges:
-- `.claude/skills → skills/active`
-- `.pi/skills → skills/active`
-
-## Credential Setup
-
-If a skill needs an API key, add it via the admin UI (Settings > Agent Jobs > Secrets). The secret will be injected as an env var into Docker containers. The agent can discover available secrets via the `get-secret` skill.
+Use only when a required library has no bash/curl alternative. Add a `package.json` with dependencies — they're installed automatically in Docker. Use `.cjs` for CommonJS or `.mjs` for ESM — never plain `.js`.
 
 ## Testing
 
@@ -106,4 +131,4 @@ Always build AND test a skill in the same job. Tell the agent to test with real
 
 ## Default Skills
 
-Check `skills/` for available built-in skills. Activate any you need by symlinking into `skills/active/`.
+Check `skills/library/` for available built-in skills. Activate any you need by symlinking into `skills/active/`.

package/templates/skills/library/agent-job-secrets/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: agent-job-secrets
+description: List and retrieve agent secrets. Plain secrets are also available as env vars. OAuth credentials are auto-refreshed on every get call.
+---
+
+## Usage
+
+```bash
+# List available secret keys (fetches current list from server)
+node skills/library/agent-job-secrets/agent-job-secrets.js
+
+# Get a secret value (OAuth credentials are auto-refreshed)
+node skills/library/agent-job-secrets/agent-job-secrets.js get MY_CREDENTIALS
+```
+
+## Notes
+
+- `AGENT_JOB_TOKEN` and `APP_URL` are injected automatically — no setup required
+- Plain (non-OAuth) secrets are also available directly as env vars (e.g. `echo $MY_KEY`)
+- OAuth credentials must be fetched via `get` — they are not available as env vars
+- `get` on an OAuth credential refreshes it server-side and returns a fresh access token
+- If a fetched credential stops working (expired token, 401 error), call `get` again to obtain a fresh one
+- `list` always fetches from the server, so it reflects secrets added after the container started

package/templates/skills/library/agent-job-secrets/agent-job-secrets.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+const [cmd, key] = process.argv.slice(2);
+
+const apiKey = process.env.AGENT_JOB_TOKEN;
+const appUrl = process.env.APP_URL;
+
+// Default to list
+if (!cmd || cmd === 'list') {
+  if (!apiKey || !appUrl) {
+    console.log('No agent secrets available (missing AGENT_JOB_TOKEN or APP_URL).');
+    process.exit(0);
+  }
+  const url = `${appUrl}/api/agent-job-list-secrets`;
+  const res = await fetch(url, {
+    headers: { 'x-api-key': apiKey },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`GET ${url} → ${res.status} ${body}`);
+    process.exit(1);
+  }
+  const json = await res.json();
+  const secrets = json.secrets;
+  if (!secrets || secrets.length === 0) {
+    console.log('No agent secrets configured.');
+  } else {
+    console.log('Available secrets:');
+    secrets.forEach(s => {
+      const hint = s.secretType === 'oauth2' ? '  (OAuth — use get to fetch access token)'
+                 : s.secretType === 'oauth_token' ? '  (OAuth token — use get to fetch)'
+                 : '';
+      console.log(`  - ${s.key}${hint}`);
+    });
+    console.log('\nUse: agent-job-secrets get KEY_NAME');
+    console.log('If a fetched value stops working, call get again for a fresh one.');
+  }
+  process.exit(0);
+}
+
+if (!apiKey) { console.error('AGENT_JOB_TOKEN not available'); process.exit(1); }
+if (!appUrl) { console.error('APP_URL not available'); process.exit(1); }
+
+if (cmd === 'get') {
+  if (!key) { console.error('Usage: agent-job-secrets get KEY_NAME'); process.exit(1); }
+  const url = `${appUrl}/api/get-agent-job-secret?key=${encodeURIComponent(key)}`;
+  const res = await fetch(url, {
+    headers: { 'x-api-key': apiKey },
+  });
+  if (!res.ok) {
+    const body = await res.text();
+    console.error(`GET ${url} → ${res.status} ${body}`);
+    process.exit(1);
+  }
+  const json = await res.json();
+  console.log(json.value);
+  process.exit(0);
+}
+
+console.error(`Unknown command: ${cmd}`);
+console.error('Available commands: list, get');
+process.exit(1);

package/templates/.pi/extensions/env-sanitizer/index.ts

@@ -1,48 +0,0 @@
-/**
- * Env Sanitizer Extension - Protects credentials from AI agent access
- *
- * Uses Pi's spawnHook to filter sensitive env vars from bash subprocess calls
- * while keeping them available in the main process for:
- * - Anthropic SDK (needs ANTHROPIC_API_KEY at init)
- * - GitHub CLI (needs GH_TOKEN)
- * - Other extensions that may need credentials
- *
- * Dynamically filters all keys defined in the SECRETS JSON env var.
- */
-
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { createBashTool } from "@mariozechner/pi-coding-agent";
-
-// Parse SECRETS JSON to get list of keys to filter
-function getSecretKeys(): string[] {
-  const keys: string[] = [];
-  if (process.env.SECRETS) {
-    try {
-      const secrets = JSON.parse(process.env.SECRETS);
-      keys.push(...Object.keys(secrets));
-    } catch {
-      // Invalid JSON, ignore
-    }
-  }
-  // Always filter SECRETS itself
-  keys.push("SECRETS");
-  return [...new Set(keys)]; // Dedupe
-}
-
-export default function (pi: ExtensionAPI) {
-  const secretKeys = getSecretKeys();
-
-  // Override bash tool with filtered environment for subprocesses
-  const bashTool = createBashTool(process.cwd(), {
-    spawnHook: ({ command, cwd, env }) => {
-      // Filter all secret keys from subprocess environment
-      const filteredEnv = { ...env };
-      for (const key of secretKeys) {
-        delete filteredEnv[key];
-      }
-      return { command, cwd, env: filteredEnv };
-    },
-  });
-
-  pi.registerTool(bashTool);
-}

package/templates/.pi/extensions/env-sanitizer/package.json

@@ -1,5 +0,0 @@
-{
-  "name": "env-sanitizer",
-  "private": true,
-  "type": "module"
-}

package/templates/README.md

@@ -1,75 +0,0 @@
-# My Agent
-
-An autonomous AI agent powered by [thepopebot](https://github.com/stephengpope/thepopebot).
-
-## Quick Start
-
-1. **Open the web UI** — Visit your `APP_URL` in a browser
-2. **Create an account** — First visit creates the admin account
-3. **Start chatting** — The AI streams responses, supports file uploads and voice input
-4. **Create a job** — Ask the AI to make code changes, or use the API
-
-## What You Can Do
-
-- **Chat** — Web chat with streaming responses, file uploads, voice input, and chat history
-- **Telegram** — Chat on the go via a Telegram bot (`npm run setup-telegram`)
-- **Jobs** — Autonomous coding tasks: the agent creates a branch, works in Docker, and opens a PR
-- **Code Workspaces** — Browser-based interactive coding with Claude Code (`/code/{id}`)
-- **Cluster Workspaces** — Multi-role agent teams with shared directories (`/clusters`)
-- **Crons** — Scheduled recurring jobs (`config/CRONS.json`)
-- **Triggers** — Webhook-activated automations (`config/TRIGGERS.json`)
-- **Skills** — Extensible agent capabilities via `skills/active/`
-
-## Config Files
-
-| File | Purpose |
-|------|---------|
-| `config/agent-chat/SYSTEM.md` | Agent chat system prompt |
-| `config/code-chat/SYSTEM.md` | Code workspace planning system prompt |
-| `config/agent-job/SOUL.md` | Agent personality and identity |
-| `config/agent-job/AGENT_JOB.md` | Agent runtime environment docs |
-| `config/CRONS.json` | Scheduled job definitions |
-| `config/TRIGGERS.json` | Webhook trigger definitions |
-| `.env` | API keys, tokens, and settings |
-
-See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the complete list.
-
-## Documentation
-
-| Guide | Description |
-|-------|-------------|
-| [Getting Started](docs/GETTING_STARTED.md) | First steps: web UI, first chat, first job, Telegram |
-| [Configuration](docs/CONFIGURATION.md) | All config files, env vars, LLM providers, GitHub setup |
-| [Crons and Triggers](docs/CRONS_AND_TRIGGERS.md) | Action types, scheduling, webhooks, template tokens |
-| [Skills](docs/SKILLS.md) | Bundled skills, activate/deactivate, build custom skills |
-| [Clusters](docs/CLUSTERS.md) | Multi-role agent teams, triggers, shared directories |
-| [CLI](docs/CLI.md) | All CLI commands reference |
-| [Upgrading](docs/UPGRADING.md) | How to upgrade, managed files, recovery |
-| [Security](docs/SECURITY.md) | API keys, secret filtering, auto-merge restrictions |
-
-## Managed vs. User Files
-
-**Managed files** are auto-updated by `thepopebot init` and `thepopebot upgrade` to stay in sync with the package version. Do not edit them — changes will be overwritten:
-
-- `.github/workflows/`
-- `docker-compose.yml`
-- `.dockerignore`
-- `.gitignore`
-- `CLAUDE.md`
-
-**Your files** (`config/`, `skills/`, `cron/`, `triggers/`, `docs/`, `README.md`) are yours to customize. They are scaffolded once and never overwritten.
-
-To customize Docker Compose, set `COMPOSE_FILE=docker-compose.custom.yml` in `.env`.
-
-## Updating
-
-```bash
-npx thepopebot upgrade
-```
-
-Or trigger the **"Upgrade Event Handler"** workflow from the GitHub Actions tab.
-
-## Help
-
-- [thepopebot documentation](https://github.com/stephengpope/thepopebot)
-- [Report an issue](https://github.com/stephengpope/thepopebot/issues)

package/templates/config/CLAUDE.md.template

@@ -1,40 +0,0 @@
-# config/ — Agent Configuration
-
-This directory contains all user-editable configuration files. These files are **not managed** — your changes are preserved across upgrades.
-
-## File Reference
-
-### System Prompts
-
-| File | Used By | Purpose |
-|------|---------|---------|
-| `agent-chat/SYSTEM.md` | Event handler | System prompt for the agent chat (job planning from web/Telegram). |
-| `code-chat/SYSTEM.md` | Code workspaces | System prompt for the planning chat in interactive code workspaces. |
-| `agent-job/SOUL.md` | Docker agent | Agent personality, identity, and values. Included in agent job system prompts. |
-| `agent-job/AGENT_JOB.md` | Docker agent | Runtime environment documentation injected into the agent's context. |
-| `agent-job/SUMMARY.md` | Docker agent | Prompt template for summarizing completed job results. |
-| `cluster/SYSTEM.md` | Cluster workers | Shared system prompt for all cluster worker agents. |
-| `cluster/ROLE.md` | Cluster workers | Per-role prompt template (receives role-specific variables). |
-| `HEARTBEAT.md` | Heartbeat cron | Self-monitoring prompt for the agent's periodic heartbeat job. |
-
-### Scheduling & Triggers
-
-| File | Purpose |
-|------|---------|
-| `CRONS.json` | Scheduled job definitions — loaded at server startup by `node-cron`. |
-| `TRIGGERS.json` | Webhook trigger definitions — loaded at server startup. |
-
-## Template Variables
-
-Config markdown files support includes and built-in variables (processed by `render-md.js` at runtime):
-
-| Syntax | Description |
-|--------|-------------|
-| `{{ filepath.md }}` | Include another file (path relative to project root, recursive with circular detection) |
-| `{{datetime}}` | Current ISO timestamp |
-| `{{skills}}` | Dynamic bullet list of active skill descriptions from `skills/active/*/SKILL.md` frontmatter |
-
-## When Changes Take Effect
-
-- **Prompt files** (`.md`) — Changes take effect immediately on the next LLM call. No restart needed.
-- **CRONS.json / TRIGGERS.json** — Require a server restart to reload schedules and trigger watchers.