thepopebot 1.2.76-beta.38 → 1.2.76-beta.39

package/README.md

@@ -1,194 +1,217 @@
-# ThePopeBot
+# thepopebot
 
-Build autonomous AI agents that work for you 24/7, individually or in teams.
+Your personal agent, coding environment, and communication platform — all in
+one app. Works with any LLM or coding agent. Designed to be simple, unified,
+secure, and easy.
 
-### What You Get
+- 💬 **Smart chat integrations** — Telegram today; Slack and Discord coming soon. Plus the built-in web chat.
+- 🧠 **Any LLM** — Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter, NVIDIA, or any OpenAI-compatible endpoint.
+- 🤖 **Any coding agent** — Claude Code, Codex, Gemini, OpenCode, Pi, or Kimi.
+- 💻 **Live coding workspaces** — open a terminal in your browser, attach to a running container, share the same session as your chat.
+- 🔧 **Real work, not just chat** — agent writes code, opens a PR, auto-merges, DMs you when it's done.
+- 🔐 **Yours, fully** — runs on your hardware, your repo, your tokens.
 
-- **Runs 24/7** — set up tasks and your agent handles them around the clock, no babysitting
-- **Does real work** — writes code, opens pull requests, completes multi-step tasks end to end
-- **Agent clusters** — build teams of agents that coordinate and work together on bigger jobs
-- **Full visibility** — every action is a commit you can review, approve, or undo
-
-<a href="https://www.skool.com/ai-architects"><img src="docs/hero.png" width="100" alt="ThePopeBot" /></a>
+<a href="https://www.skool.com/ai-architects"><img src="docs/hero.png" width="100" alt="thepopebot" /></a>
 
 [Get priority support HERE](https://www.skool.com/ai-architects)
 
 ---
 
-## How It Works
+## How it works
+
+Three doors, one brain:
 
 ```
-┌──────────────────────────────────────────────────────────────────────┐
-│                                                                      │
-│  ┌─────────────────┐         ┌─────────────────┐                     │
-│  │  Event Handler  │ ──1──►  │     GitHub      │                     │
-│  │ (creates branch)│         │(agent-job/* br) │                     │
-│  └────────▲────────┘         └─────────────────┘                     │
-│           │                                                          │
-│           │  2 (launches Docker container locally)                   │
-│           │                                                          │
-│           ▼                                                          │
-│  ┌─────────────────┐                                                 │
-│  │  Docker Agent   │                                                 │
-│  │ (coding agent)  │                                                 │
-│  └────────┬────────┘                                                 │
-│           │                                                          │
-│           │  3 (commits, pushes, creates PR)                         │
-│           │                                                          │
-│           ▼                                                          │
-│  ┌─────────────────┐                                                 │
-│  │     GitHub      │                                                 │
-│  │   (PR opened)   │                                                 │
-│  └────────┬────────┘                                                 │
-│           │                                                          │
-│           │  4a (auto-merge.yml)                                     │
-│           │  4b (rebuild-event-handler.yml)                          │
-│           │                                                          │
-│           5 (notify-pr-complete.yml →                                │
-│           │  webhook to event handler)                               │
-│           └──────────────────────────►  Event Handler                │
-│                                                                      │
-└──────────────────────────────────────────────────────────────────────┘
+      ┌── Browser chat ──┐                  ┌── Telegram (verified per-user)
+      │                  ▼                  ▼
+      │            ┌──────────────────────────────────┐
+      │  attach    │           The Brain              │
+      │  a live    │     (your event handler)         │
+      │  terminal  │                                  │
+      │            │   • picks the coding agent       │
+      │            │   • picks the coding agent       │
+      │            │   • remembers the session        │
+      │            │   • runs Docker for you          │
+      └── Code ────┤                                  │
+        workspace  └──────────────┬───────────────────┘
+                                  │
+                         ┌────────┴────────┐
+                         ▼                 ▼
+                  ┌─────────────┐   ┌─────────────────┐
+                  │  Live chat  │   │   Agent job     │
+                  │ (right now) │   │  (background)   │
+                  │             │   │                 │
+                  │ same coding │   │ same coding     │
+                  │ agent runs  │   │ agent runs in   │
+                  │ in-process  │   │ a fresh Docker  │
+                  │ or in a     │   │ container,      │
+                  │ headless    │   │ opens a PR,     │
+                  │ container   │   │ DMs you back    │
+                  └─────────────┘   └─────────────────┘
 ```
 
-You interact with your bot via the web chat interface or Telegram (optional). The Event Handler creates an agent-job branch and launches a Docker container locally with the coding agent. The agent does the work, commits the results, pushes, and opens a PR. Auto-merge handles the rest. You get a notification when it's done.
+### Live chat vs. agent job
 
----
+| Path           | When                          | What happens                                       |
+|----------------|-------------------------------|----------------------------------------------------|
+| **Live chat**  | Quick questions, small edits  | Coding agent runs now, streams to your screen      |
+| **Agent job**  | "Build it. DM me when done."  | Background worker opens a PR, auto-merges, DMs you |
 
-## Star History
+### Two flavors of chat (`chatMode`)
 
-[![Star History Chart](https://api.star-history.com/svg?repos=stephengpope/thepopebot&type=date&legend=top-left)](https://www.star-history.com/#stephengpope/thepopebot&type=date&legend=top-left)
+| `chatMode` | Repo & branch              | Use it for                                  |
+|------------|----------------------------|---------------------------------------------|
+| `agent`    | Your bot's own repo        | Talking *to* your bot — config, skills, ops |
+| `code`     | Any repo + branch you pick | Real coding sessions on a project           |
+
+### Live coding workspaces
+
+Open a workspace from any code-mode chat and the browser attaches a terminal
+to a persistent container running your coding agent of choice. Workspace and
+chat share the same session — fire a question in chat, hop into the terminal,
+the agent already knows what you were just talking about.
+
+### When you ask for a job
+
+```
+  you ──► chat ──► event handler ──► creates `agent-job/<id>` branch
+                                              │
+                                              ▼
+                                    launches a Docker container
+                                    locally (your chosen agent)
+                                              │
+                                              ▼
+                                    agent commits, pushes,
+                                    opens a PR
+                                              │
+                                              ▼
+                                    auto-merge.yml ──► merged
+                                              │
+                                              ▼
+                                    notify-pr-complete.yml ──► DM to you
+```
 
 ---
 
-## Get Started
+## Install
 
 ### Prerequisites
 
 | Requirement | Install |
 |-------------|---------|
 | **Node.js 18+** | [nodejs.org](https://nodejs.org) |
-| **npm** | Included with Node.js |
 | **Git** | [git-scm.com](https://git-scm.com) |
 | **GitHub CLI** | [cli.github.com](https://cli.github.com) |
-| **Docker + Docker Compose** | [docker.com](https://docs.docker.com/get-docker/) (installer requires admin password) |
-| **ngrok*** | [ngrok.com](https://ngrok.com/download) (free account + authtoken required) |
+| **Docker + Docker Compose** | [docker.com](https://docs.docker.com/get-docker/) |
+| **ngrok*** | [ngrok.com](https://ngrok.com/download) (free account + authtoken) |
 
-*\*ngrok is only required for local installs without port forwarding. VPS/cloud deployments don't need it. [Sign up](https://dashboard.ngrok.com/signup) for a free ngrok account, then run `ngrok config add-authtoken <YOUR_TOKEN>` before starting setup.*
+*\*ngrok is only needed for local installs without port forwarding. VPS/cloud deployments don't need it.*
 
 ### Two steps
 
-**Step 1** — Scaffold a new project:
-
 ```bash
 mkdir my-agent && cd my-agent
-npx thepopebot@latest init
+npx thepopebot@latest init   # scaffold project
+npm run setup                 # interactive wizard
 ```
 
-This creates a Next.js project with configuration files, GitHub Actions workflows, and agent templates. You don't need to create a GitHub repo first — the setup wizard handles that.
+The wizard checks prerequisites, creates a GitHub repo, generates a PAT, configures your URL, and starts Docker. Visit your APP_URL when it finishes.
+
+> **Local installs**: your server needs to be reachable from the internet for GitHub webhooks and Telegram. Use [ngrok](https://ngrok.com) (`ngrok http 80`). If your ngrok URL changes, run `npx thepopebot set-var APP_URL <new-url>` and re-register the Telegram webhook from `/admin/event-handler/telegram`.
 
-**Step 2** — Run the setup wizard:
+---
+
+## Upgrade
 
 ```bash
-npm run setup
+npx thepopebot upgrade          # latest stable
+npx thepopebot upgrade @beta    # latest beta
+npx thepopebot upgrade 1.2.72   # specific version
+```
+
+Installs the new package, syncs managed files, rebuilds, restarts Docker.
+
+### What's protected, what gets updated
+
+Two kinds of files behave differently — by design, so an upgrade never blows
+away your customizations.
+
+```
+   ┌─ Managed files ──────────────┐   ┌─ Your files ─────────────────┐
+   │  .github/workflows/          │   │  agent-job/SYSTEM.md         │
+   │  docker-compose.yml          │   │  agent-job/CRONS.json        │
+   │  .gitignore                  │   │  event-handler/TRIGGERS.json │
+   │                              │   │  agents/                     │
+   │  Always replaced with the    │   │  skills-library/, skills/    │
+   │  latest version on every     │   │  .env, secrets               │
+   │  init / upgrade.             │   │  Never touched by upgrade.   │
+   └──────────────────────────────┘   └──────────────────────────────┘
 ```
 
-The wizard walks you through everything:
-- Checks prerequisites (Node.js, Git, GitHub CLI, Docker)
-- Creates a GitHub repository and pushes your initial commit
-- Creates a GitHub Personal Access Token (scoped to your repo)
-- Configures your public URL and webhook secret
-- Syncs settings to `.env`, database, and GitHub secrets/variables
-- Starts Docker for you
+So you never lose your work — but you might miss a useful template change.
+Three commands let you pull updates in deliberately:
 
-**That's it.** Visit your APP_URL when the wizard finishes.
+```bash
+npx thepopebot audit          # show what's drifted from the templates
+npx thepopebot diff <file>    # show the diff for one file
+npx thepopebot reset <file>   # replace one file with the latest template
+npx thepopebot reset-all      # ⚠ nuclear: wipe local edits, restore everything
+```
 
-- **Web Chat**: Visit your APP_URL to chat with your agent, create jobs, upload files
-- **Telegram** (optional): Connect a Telegram bot from `/admin/event-handler/telegram`
-- **Webhook**: Send a POST to `/api/create-agent-job` with your API key to create jobs programmatically
-- **Cron**: Edit `agent-job/CRONS.json` to schedule recurring jobs
+Use them when release notes mention a SYSTEM.md or workflow improvement you want.
 
-### Chat vs Agent LLM
+> **Upgrade failed?** See [Recovering from a Failed Upgrade](docs/UPGRADE.md#recovering-from-a-failed-upgrade).
 
-Your bot has two sides — a **chat** side and an **agent** side.
+---
 
-**Chat** is the conversational part. When you talk to your bot in the web UI or Telegram, it uses the chat LLM. This runs on your server and responds in real time.
+## How LLMs are wired
 
-**Agent** is the worker. When your bot needs to write code, modify files, or do a bigger task, it spins up a separate job that runs in a Docker container on GitHub. That job uses the agent LLM.
+Two slots, you pick whether they share a model.
 
-By default, both use the same model. But during setup, you can choose different models for each — for example, a faster model for chat and a more capable one for agent jobs. The wizard asks "Would you like agent jobs to use different LLM settings?" and lets you pick.
+- **Coding agent** — drives **everything you actually talk to**: live chat in the browser/Telegram, code workspaces, and background agent jobs. One agent, one model. For Claude Code the chat runs in-process via the Claude Agent SDK; for any other agent (Pi, Codex, Gemini, OpenCode, Kimi) it runs in an ephemeral headless container — same chunk shape either way. Configured at `/admin/event-handler/coding-agents`.
+- **Helper LLM** — small one-shot calls only: chat auto-titles, agent-job titles, PR-merge summaries. Independent provider/model from the coding agent. Configured at `/admin/event-handler/helper-llm`.
 
-### Using a Claude Subscription (OAuth Token)
+A coding-agent task can override its model per-run via `agent_backend` + `llm_model` on a cron, trigger, or chained agent job.
 
-If you have a Claude Pro ($20/mo) or Max ($100+/mo) subscription, you can use it to power your agent jobs instead of paying per API call. During setup, choose Anthropic as your agent provider and say yes when asked about a subscription.
+### Using a Claude subscription
 
-You'll need to generate a token:
+If you have Claude Pro or Max, you can power Claude Code with your subscription instead of API billing. Generate a token:
 
 ```bash
-# Install Claude Code CLI (if you don't have it)
 npm install -g @anthropic-ai/claude-code
-
-# Generate your token (opens browser to log in)
 claude setup-token
 ```
 
-Paste the token (starts with `sk-ant-oat01-`) into the setup wizard. Your agent jobs will now run through your subscription. Note that usage counts toward your Claude.ai limits, and you still need an API key for the chat side.
-
-See [Coding Agents](docs/CODING_AGENTS.md) for details on all five agent backends.
+Paste it (starts with `sk-ant-oat01-`) into Admin > Event Handler > Coding Agents > Claude Code (auth mode: OAuth). The same token drives live chat *and* background agent jobs — no separate API key needed for chat. Add multiple tokens and they rotate LRU on each container launch.
 
-> **Local installs**: Your server needs to be reachable from the internet for GitHub webhooks and Telegram. On a VPS/cloud server, your APP_URL is just your domain. For local development, use [ngrok](https://ngrok.com) (`ngrok http 80`) or port forwarding to expose your machine.
->
-> **If your ngrok URL changes** (it changes every time you restart ngrok on the free plan), you must update APP_URL everywhere:
->
-> ```bash
-> # Update .env and GitHub variable in one command:
-> npx thepopebot set-var APP_URL https://your-new-url.ngrok.io
-> ```
->
-> If Telegram is configured, click **Re-register webhook** at `/admin/event-handler/telegram` after the URL change.
+See [Coding Agents](docs/CODING_AGENTS.md) for details on all six agent backends.
 
 ---
 
-## Updating
+## Connect Telegram (optional)
 
-```bash
-npx thepopebot upgrade          # latest stable
-npx thepopebot upgrade @beta    # latest beta
-npx thepopebot upgrade 1.2.72   # specific version
-```
-
-Saves your local changes, syncs with GitHub, installs the new version, rebuilds, pushes, and restarts Docker.
-
-**What it does:**
+Talk to your bot from your phone. Two steps:
 
-1. Saves any local changes you've made
-2. Pulls the latest from GitHub (stops if there are conflicts)
-3. Installs the new version and updates project files
-4. Rebuilds your project
-5. Pushes everything to GitHub
-6. Restarts Docker containers (if running)
+1. **Wire up the bot** — at `/admin/event-handler/telegram`, paste the bot token from [@BotFather](https://t.me/BotFather) and click **Register webhook**.
+2. **Verify your account** — at `/profile/telegram`, generate a one-time code and send `/verify <code>` to your bot. The bot only responds to verified users; unbound chats are silently dropped.
 
-Pushing to `main` triggers the `rebuild-event-handler.yml` workflow on your server. It detects the version change, runs `thepopebot init`, updates `THEPOPEBOT_VERSION` in the server's `.env`, pulls the new Docker image, restarts the container, rebuilds `.next`, and reloads PM2 — no manual `docker compose` needed.
+Once verified: `/session` lists your active threads, `/session <id>` switches the thread your messages route to. Voice notes are transcribed when an `ASSEMBLYAI_API_KEY` is set in `/admin/event-handler/voice`.
 
-> **Upgrade failed?** See [Recovering from a Failed Upgrade](docs/UPGRADE.md#recovering-from-a-failed-upgrade).
-
-See [CLI Reference](docs/CLI.md) for full details on `init`, managed vs user files, template conventions, and all CLI commands.
+See [Chat Integrations](docs/CHAT_INTEGRATIONS.md) for the channel adapter pattern and how to add new channels (Slack, Discord coming soon).
 
 ---
 
 ## Security
 
-thepopebot includes API key authentication, webhook secret validation (fail-closed), session encryption, secret filtering in the Docker agent, and auto-merge path restrictions. However, all software carries risk — thepopebot is provided as-is, and you are responsible for securing your own infrastructure. If you're running locally with a tunnel (ngrok, Cloudflare Tunnel, port forwarding), be aware that your dev server endpoints are publicly accessible with no rate limiting and no TLS on the local hop.
+thepopebot includes API key authentication, webhook secret validation (fail-closed), session encryption (AES-256-GCM keyed off `AUTH_SECRET`), per-job API keys with maintenance-cron expiry, and auto-merge path restrictions. All software carries risk — thepopebot is provided as-is, and you are responsible for securing your own infrastructure. If you're running locally with a tunnel, your dev server endpoints are publicly accessible with no rate limiting and no TLS on the local hop.
 
-See [Security](docs/SECURITY.md) for full details on what's exposed, the risks, and recommendations.
+See [Security](docs/SECURITY.md) for full details.
 
 ---
 
-## Different Models
-
-thepopebot supports 9 built-in LLM providers (Anthropic, OpenAI, Google, DeepSeek, MiniMax, Mistral, xAI, Kimi, OpenRouter) plus custom OpenAI-compatible endpoints. The chat layer and coding agents are independent — use Claude for interactive chat and a different model for code tasks, or run everything on a single provider.
+## Star History
 
-See [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) for the full provider reference, admin UI configuration, per-job overrides, and custom provider setup.
+[![Star History Chart](https://api.star-history.com/svg?repos=stephengpope/thepopebot&type=date&legend=top-left)](https://www.star-history.com/#stephengpope/thepopebot&type=date&legend=top-left)
 
 ---
 
@@ -198,8 +221,8 @@ See [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) for the full provider r
 
 SQLite can't create or open its shared-memory (`.shm`) file. Common causes:
 
-- **Antivirus** (Windows Defender, etc.) locking the database files — add your project folder to the exclusion list
-- **Cloud-synced folders** (OneDrive, Dropbox, Google Drive) — move your project to a non-synced directory like `C:\Projects\`
+- **Antivirus** locking the database — add your project folder to the exclusion list
+- **Cloud-synced folders** (OneDrive, Dropbox, Google Drive) — move your project to a non-synced directory
 
 ---
 
@@ -209,13 +232,13 @@ SQLite can't create or open its shared-memory (`.shm`) file. Common causes:
 |----------|-------------|
 | [Architecture](docs/ARCHITECTURE.md) | Two-layer design, file structure, API endpoints, GitHub Actions, Docker agent |
 | [CLI Reference](docs/CLI.md) | `init`, managed vs user files, template conventions, all CLI commands |
-| [Configuration](docs/CONFIGURATION.md) | Admin UI, DB-backed config, infrastructure variables, GitHub secrets, Docker Compose |
-| [Customization](docs/CUSTOMIZATION.md) | Personality, skills, operating system files, using your bot, security details |
+| [Configuration](docs/CONFIGURATION.md) | Admin UI, DB-backed config, infrastructure variables, Docker Compose |
+| [Customization](docs/CUSTOMIZATION.md) | Personality, skills, operating system files, using your bot |
 | [Chat Integrations](docs/CHAT_INTEGRATIONS.md) | Web chat, Telegram, adding new channels |
-| [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) | 9 built-in LLM providers, chat vs coding agent config, per-job overrides, custom providers |
+| [Different Models](docs/RUNNING_DIFFERENT_MODELS.md) | 10 built-in LLM providers, helper LLM vs coding agent split, per-job overrides, custom providers |
 | [Auto-Merge](docs/AUTO_MERGE.md) | Auto-merge controls, ALLOWED_PATHS configuration |
 | [Deployment](docs/DEPLOYMENT.md) | VPS setup, Docker Compose, HTTPS with Let's Encrypt |
-| [Coding Agents](docs/CODING_AGENTS.md) | 5 coding agent backends, OAuth tokens, LiteLLM proxy, per-agent config |
+| [Coding Agents](docs/CODING_AGENTS.md) | 6 coding agent backends, OAuth tokens, LiteLLM proxy, per-agent config |
 | [How to Build Skills](docs/HOW_TO_BUILD_SKILLS.md) | Guide to building and activating agent skills |
 | [Pre-Release](docs/PRE_RELEASE.md) | Installing beta/alpha builds |
 | [Code Workspaces](docs/CODE_WORKSPACES.md) | Interactive Docker containers with in-browser terminal |

package/bin/cli.js

@@ -129,6 +129,11 @@ async function init(options = {}) {
 
   console.log('\nScaffolding thepopebot project...\n');
 
+  // Capture pre-init state of skills/ so we know whether to populate
+  // first-init activation symlinks below. Must be checked BEFORE scaffolding,
+  // since templates/skills/CLAUDE.md.template will create skills/ as a side effect.
+  const isFreshSkillsInstall = !fs.existsSync(path.join(cwd, 'skills'));
+
   const templateFiles = getTemplateFiles(templatesDir);
   const created = [];
   const skipped = [];
@@ -292,6 +297,23 @@ async function init(options = {}) {
     }
   }
 
+  // First-init activation: populate skills/<X> → ../skills-library/<X> symlinks
+  // for every bundled skill. Only runs when skills/ did not pre-exist, so users
+  // who deactivate a skill (rm skills/<X>) don't get it auto-reactivated on upgrade.
+  if (isFreshSkillsInstall) {
+    const libraryDir = path.join(cwd, 'skills-library');
+    if (fs.existsSync(libraryDir)) {
+      const entries = fs.readdirSync(libraryDir, { withFileTypes: true });
+      fs.mkdirSync(path.join(cwd, 'skills'), { recursive: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const link = path.join(cwd, 'skills', entry.name);
+        if (fs.existsSync(link)) continue;
+        createDirLink(`../skills-library/${entry.name}`, link);
+        console.log(`  Activated skills/${entry.name} → ../skills-library/${entry.name}`);
+      }
+    }
+  }
 
   // Report backed-up files
   if (backedUp.length > 0) {

package/lib/chat/components/code-mode-toggle.js

@@ -212,7 +212,17 @@ function WorkspaceBar({
   return /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-2 text-xs min-w-0 px-1 py-0.5", children: [
     /* @__PURE__ */ jsxs("div", { className: "flex items-center gap-1.5 text-muted-foreground min-w-0", children: [
       /* @__PURE__ */ jsx(GitBranchIcon, { size: 12, className: "shrink-0" }),
-      repoName && /* @__PURE__ */ jsx("span", { className: "shrink-0 cursor-default hidden md:inline", title: repo, children: repoName }),
+      repoName && /* @__PURE__ */ jsx(
+        "a",
+        {
+          href: `https://github.com/${repo}`,
+          target: "_blank",
+          rel: "noopener noreferrer",
+          title: repo,
+          className: "shrink-0 hidden md:inline font-medium text-foreground hover:text-primary transition-colors",
+          children: repoName
+        }
+      ),
       branch && /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx("span", { className: "shrink-0 text-muted-foreground/30 hidden md:inline", children: "/" }),
         /* @__PURE__ */ jsx("div", { className: "min-w-0", children: /* @__PURE__ */ jsx(

package/lib/chat/components/code-mode-toggle.jsx

@@ -235,7 +235,17 @@ export function WorkspaceBar({
     <div className="flex items-center gap-2 text-xs min-w-0 px-1 py-0.5">
       <div className="flex items-center gap-1.5 text-muted-foreground min-w-0">
         <GitBranchIcon size={12} className="shrink-0" />
-        {repoName && <span className="shrink-0 cursor-default hidden md:inline" title={repo}>{repoName}</span>}
+        {repoName && (
+          <a
+            href={`https://github.com/${repo}`}
+            target="_blank"
+            rel="noopener noreferrer"
+            title={repo}
+            className="shrink-0 hidden md:inline font-medium text-foreground hover:text-primary transition-colors"
+          >
+            {repoName}
+          </a>
+        )}
         {branch && (
           <>
             <span className="shrink-0 text-muted-foreground/30 hidden md:inline">/</span>

package/package.json

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

package/setup/setup.mjs

@@ -435,24 +435,33 @@ async function main() {
   // ─── Step 5: Start Server ─────────────────────────────────────────────
   clack.log.step(`[${++currentStep}/${TOTAL_STEPS}] Start Server`);
 
-  let serverRunning = false;
-  try {
-    await fetch('http://localhost:80/api/ping', {
-      method: 'GET',
-      signal: AbortSignal.timeout(3000),
-    });
-    serverRunning = true;
-  } catch {
-    // Server not reachable
+  // Probe /login (not /api/ping) to confirm Next.js can actually render
+  // the page, not just answer API routes. /login serves SetupForm on a
+  // fresh install; LoginForm once a user exists. Either way it's HTML.
+  async function isLoginPageReady(timeoutMs = 2000) {
+    try {
+      const res = await fetch('http://localhost:80/login', {
+        method: 'GET',
+        signal: AbortSignal.timeout(timeoutMs),
+        redirect: 'manual',
+      });
+      if (!res.ok) return false;
+      const ct = res.headers.get('content-type') || '';
+      return ct.includes('text/html');
+    } catch {
+      return false;
+    }
   }
 
-  if (serverRunning) {
+  let serverUp = await isLoginPageReady(3000);
+
+  if (serverUp) {
     if (await confirm('Server is already running. Restart?')) {
       clack.log.info('Restarting server...');
       try {
         execSync('docker compose down && docker compose up -d', { stdio: 'inherit' });
         clack.log.success('Server restarted');
-        serverRunning = false; // Need to wait for it to come back up
+        serverUp = false; // Need to wait for it to come back up
       } catch (err) {
         const output = (err.stderr || err.stdout || err.message || '').toString().trim();
         clack.log.warn('Failed to restart.');
@@ -474,32 +483,25 @@ async function main() {
   }
 
   // Poll for the server to come up (max 60 seconds)
-  if (!serverRunning) {
+  if (!serverUp) {
     const pollSpinner = clack.spinner();
     pollSpinner.start('Waiting for server to come up...');
 
     const startTime = Date.now();
     const timeout = 60_000;
-    let detected = false;
 
     while (Date.now() - startTime < timeout) {
-      try {
-        await fetch('http://localhost:80/api/ping', {
-          method: 'GET',
-          signal: AbortSignal.timeout(2000),
-        });
-        detected = true;
+      if (await isLoginPageReady()) {
+        serverUp = true;
         break;
-      } catch {
-        await new Promise((r) => setTimeout(r, 2000));
       }
+      await new Promise((r) => setTimeout(r, 2000));
     }
 
-    if (detected) {
+    if (serverUp) {
       pollSpinner.stop('Server is up!');
     } else {
       pollSpinner.stop('Could not detect the server after 60 seconds.');
-      clack.log.warn(`Check docker logs and visit ${appUrl}/admin manually to finish setup.`);
     }
   }
 
@@ -512,18 +514,23 @@ async function main() {
 
   clack.note(summary, 'Configuration');
 
-  clack.log.info('Configure your LLM provider, API keys, and agent settings in /admin.');
-
-  // Offer to open /admin in browser
-  const adminUrl = `${appUrl}/admin`;
-  if (canOpenBrowser()) {
-    const open = (await import('open')).default;
-    const shouldOpen = await confirm(`Open ${adminUrl} in your browser?`, true);
-    if (shouldOpen) {
-      await open(adminUrl);
+  // Only offer the link once the server is actually serving the login page.
+  // /admin would 401 — a fresh install has no users yet, so the root sends
+  // them to /login where the first-user setup form is shown.
+  if (serverUp) {
+    clack.log.info('Create your admin account, then configure your LLM provider, API keys, and agent settings under Admin.');
+
+    if (canOpenBrowser()) {
+      const open = (await import('open')).default;
+      const shouldOpen = await confirm(`Open ${appUrl} in your browser?`, true);
+      if (shouldOpen) {
+        await open(appUrl);
+      }
+    } else {
+      clack.log.info(`Visit ${appUrl} to create your admin account.`);
     }
   } else {
-    clack.log.info(`Visit ${adminUrl} to finish setup.`);
+    clack.log.warn(`Server didn't respond. Check docker logs, then visit ${appUrl} to create your admin account.`);
   }
 
   clack.outro('Setup complete!');

package/templates/CLAUDE.md.template

@@ -8,7 +8,8 @@ This is a [thepopebot](https://github.com/stephengpope/thepopebot) project.
 - **`coding-workspace/`** — Optional system prompt (`SYSTEM.md`) for code mode workspaces. Empty by default.
 - **`agents/`** — Custom agent definitions. Each subdirectory defines an agent (see Managing Agents below).
 - **`event-handler/`** — Event handler configuration: chat system prompts, trigger definitions (`TRIGGERS.json`), cluster templates, and LiteLLM proxy config.
-- **`skills/`** — Skill plugins. Each subdirectory with a `SKILL.md` is an active skill.
+- **`skills-library/`** — Canonical skill source. All `SKILL.md` files and scripts live here.
+- **`skills/`** — Activation surface. Each entry is a symlink to `../skills-library/<name>` — present means active, absent means deactivated. Coding agents only see skills symlinked here.
 - **`data/`** — Runtime data (SQLite database, cluster state). Not checked into git.
 - **`logs/`** — Agent job logs, organized by job ID. Not checked into git.
 
@@ -27,7 +28,7 @@ Some files are auto-synced by `npx thepopebot init` and will be overwritten on e
 - `.dockerignore`
 - `.gitignore`
 
-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.
+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`, `skills-library/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
 
@@ -40,15 +41,15 @@ agents/
   gary-vee/
     CLAUDE.md         ← agent-specific context (optional)
     SYSTEM.md         ← agent-specific system prompt (optional)
-    skills/           ← agent-specific skills (optional, overrides root skills/)
-      agent-job-secrets → ../../../skills/agent-job-secrets  (symlink)
+    skills/           ← agent-specific skills (optional, overrides root skills/ for this scope)
+      agent-job-secrets → ../../../skills-library/agent-job-secrets  (symlink)
       custom-skill/
 ```
 
 ### How Scoping Works
 
 - **Working directory** — The agent's cwd is set to the scoped directory. It still has access to the full repo.
-- **Skills** — If the scoped directory has a `skills/` folder, those skills are used. If not, the root `skills/` folder is used as a fallback. Sub-agent skills can symlink back to root skills they need.
+- **Skills** — If the scoped directory has a `skills/` folder, those skills are used. If not, the root `skills/` folder is used as a fallback. Sub-agent skills can symlink back to entries in the canonical `skills-library/` (e.g. `agents/<name>/skills/agent-job-secrets → ../../../skills-library/agent-job-secrets`).
 - **CLAUDE.md** — The coding agent automatically picks up `.claude/` and `CLAUDE.md` files relative to its working directory.
 - **Default scope** — When no scope is selected, the agent runs from the repository root with root-level skills.
 

package/templates/agent-job/SYSTEM.md

@@ -16,14 +16,16 @@ Everything in the workspace `/home/coding-agent/workspace` is automatically comm
 - `agents/` — Agent definitions. Each subdirectory defines an agent with its own prompts.
 - `agent-job/` — Runtime config: system prompt (`SYSTEM.md`), cron schedules (`CRONS.json`), heartbeat prompt.
 - `event-handler/` — Event handler config. Do not edit — managed by the event handler.
-- `skills/` — Skill plugins. Each subdirectory with a `SKILL.md` is an active skill.
+- `skills-library/` — Canonical skill source. All `SKILL.md` files and scripts live here.
+- `skills/` — Activation surface. Each entry is a symlink to `../skills-library/<name>` — only symlinked skills are visible to you.
 - `data/`, `logs/` — Runtime data and job logs.
 
 ## What You Can Edit
 
 - `agent-job/CRONS.json` — Add, remove, or change scheduled jobs
 - `agents/` — Create or remove agent definitions
-- `skills/` — Add or remove skill directories
+- `skills-library/` — Add or remove skill source directories
+- `skills/` — Activate/deactivate skills via symlinks
 - Agent prompt files (`.md`) in `agent-job/` and `agents/`
 - Reports and output files
 
@@ -37,7 +39,8 @@ Everything in the workspace `/home/coding-agent/workspace` is automatically comm
 
 Agents can be scoped to subdirectories under `agents/`. When scoped, the agent's working directory is set to that subdirectory (e.g., `agents/gary-vee/`). The full repo is still accessible.
 
-- **Skills fallback** — If the scoped directory has a `skills/` folder, those are used. Otherwise, the root `skills/` folder applies. Sub-agents can symlink individual skills from root: `skills/agent-job-secrets → ../../../skills/agent-job-secrets`.
+- **Skills fallback** — If the scoped directory has a `skills/` folder, those are used. Otherwise, the root `skills/` folder applies. Sub-agents can symlink individual skills from the canonical `skills-library/`: `agents/<name>/skills/agent-job-secrets → ../../../skills-library/agent-job-secrets`.
+- **Add a new skill** — Create the source in `skills-library/<name>/SKILL.md` (the canonical store), then symlink it to activate: `ln -s ../skills-library/<name> skills/<name>`. Removing the symlink deactivates without deleting the source.
 - **No skills folder needed** — If you don't create a `skills/` directory in the agent scope, it inherits all root skills automatically.
 
 ## Self-Modification
@@ -48,9 +51,9 @@ Agents can be scoped to subdirectories under `agents/`. When scoped, the agent's
 
 **Change a schedule** — Edit `agent-job/CRONS.json` (cron expressions, enable/disable).
 
-**Add a skill** — Create a directory in `skills/` with a `SKILL.md`, update root `CLAUDE.md`.
+**Add a skill** — Create the source directory in `skills-library/<name>/` with a `SKILL.md`, then activate with `ln -s ../skills-library/<name> skills/<name>`. Update root `CLAUDE.md`.
 
-**Remove a skill** — Delete the directory from `skills/`, update root `CLAUDE.md`.
+**Remove a skill** — Delete the symlink from `skills/<name>` (deactivates without losing source). To delete permanently, also `rm -rf skills-library/<name>/`. Update root `CLAUDE.md`.
 
 **Keep CLAUDE.md files current** — When you change the structure of the instance (add/remove agents, change schedules, activate skills), update the root `CLAUDE.md` and any affected folder-level `CLAUDE.md` files so the next agent has an accurate picture.
 

package/templates/agents/CLAUDE.md.template

@@ -9,13 +9,13 @@ agents/
 └── my-agent/
     ├── 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)
+    ├── skills/          # Optional — agent-specific skills (overrides root skills/ for this scope; symlink entries from ../../skills-library/)
     └── 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..."). `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/`.
+**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, create the override in `skills-library/<override-name>/` and symlink it from `agents/my-agent/skills/`. To inherit a root skill into a scope, symlink it: `ln -s ../../../skills-library/agent-job-secrets agents/my-agent/skills/agent-job-secrets`.
 
 > **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/skills/CLAUDE.md.template

@@ -1,132 +1,27 @@
-# skills/ — Agent Skills
+# skills/ — Activation Surface
 
-Skills are lightweight plugins that extend agent abilities. Each skill lives in `skills/<skill-name>/`.
+This directory is **not** where skills live. It's where active skills are turned on.
 
-## How Skills Work
+The real skill files (SKILL.md, scripts, package.json, etc.) live in `skills-library/`. Each entry here is a **symlink** pointing at a skill in `skills-library/`. The coding agents discover skills by walking into this directory through their per-agent bridges (`.claude/skills`, `.pi/skills`, `.codex/skills`, `.gemini/skills`, `.kimi/skills` → `../skills`).
 
-1. **Discovery** — The system scans `skills/` for directories containing `SKILL.md`.
-2. **Frontmatter loaded** — The `description` from YAML frontmatter is included in the system prompt under "Active skills" (via the `{{skills}}` template variable).
-3. **Full SKILL.md read on demand** — When the agent decides to use a skill, it reads the full `SKILL.md` for detailed usage instructions.
-
-All coding agents discover skills from the same `skills/` directory (via `.pi/skills`, `.claude/skills`, etc. symlink bridges).
-
-## 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:
-
-```markdown
----
-name: skill-name-in-kebab-case
-description: One sentence describing what the skill does and when to use it.
----
-
-# Skill Name
-
-## Usage
-
-```bash
-skills/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`).
-
-### Skill Structure
-
-- **`SKILL.md`** (required) — YAML frontmatter + markdown documentation
-- **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
-
-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 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
-
-### Simple bash skill (most common)
+## Activate a skill
 
 ```bash
-mkdir skills/my-skill
+ln -s ../skills-library/<skill-name> skills/<skill-name>
 ```
 
-**skills/my-skill/SKILL.md:**
-```markdown
----
-name: my-skill
-description: Does X when the agent needs to Y.
----
-
-# My Skill
+## Deactivate a skill
 
-## Setup
-Requires MY_API_KEY environment variable.
-
-## Usage
-```bash
-skills/my-skill/run.sh <args>
-```
-```
-
-**skills/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
+rm skills/<skill-name>
 ```
 
-Then make it executable:
-```bash
-chmod +x skills/my-skill/run.sh
-```
-
-### Node.js 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`.
+This only removes the symlink — the skill source in `skills-library/<skill-name>/` is untouched and can be re-activated later.
 
-## Testing
+## Add a new skill
 
-Always build AND test a skill in the same job. Tell the agent to test with real input after creating the skill and fix any issues before committing.
+Don't put real files here. Create the skill in `skills-library/<your-skill>/`, then symlink it into this directory. See `skills-library/CLAUDE.md` for the full guide.
 
-## Default Skills
+## First-init activation
 
-Check `skills/` for available built-in skills (e.g., `agent-job-secrets`, `agent-job-dm`, `agent-job-background`, `playwright-cli`).
+`npx thepopebot init` populates this directory with a symlink for every skill in `skills-library/` **only on first install** (when this directory does not yet exist). Subsequent `init` / `upgrade` runs leave it alone — new bundled skills land in `skills-library/` un-activated, and you choose whether to symlink them.

package/templates/skills-library/CLAUDE.md.template

@@ -0,0 +1,151 @@
+# skills-library/ — Canonical Skill Store
+
+All skill source files live here. This is the canonical location for SKILL.md files, scripts, package.json, etc.
+
+Skills in this directory are **inactive by default**. To make a skill available to coding agents, create a symlink in `skills/` pointing here:
+
+```bash
+ln -s ../skills-library/<skill-name> skills/<skill-name>
+```
+
+The agents discover active skills through their per-agent bridges (`.claude/skills → ../skills`, etc.) — those bridges target `skills/`, which is just a curated set of symlinks back to here.
+
+## Why two directories?
+
+- **`skills-library/`** — the package. Source of truth, never deleted by deactivation.
+- **`skills/`** — the activation surface. Add a symlink to turn a skill on; remove the symlink to turn it off without losing the skill source.
+
+This makes it cheap to toggle skills on/off (especially when narrowing what a particular install exposes to agents) without copying, archiving, or version-controlling deletions.
+
+## How Skills Work
+
+1. **Discovery** — At system-prompt build time, the renderer scans `skills/` for entries with a `SKILL.md` (real or symlinked).
+2. **Frontmatter loaded** — The `description` from YAML frontmatter is included in the system prompt under "Active skills" (via the `{{skills}}` template variable).
+3. **Full SKILL.md read on demand** — When the agent decides to use a skill, it reads the full `SKILL.md` for detailed usage instructions.
+
+All coding agents use the same activation set (`skills/`) 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)
+
+## 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:
+
+```markdown
+---
+name: skill-name-in-kebab-case
+description: One sentence describing what the skill does and when to use it.
+---
+
+# Skill Name
+
+## Usage
+
+```bash
+skills/skill-name/script.sh <args>
+```
+```
+
+- The `description` field appears in the system prompt — keep it concise and action-oriented.
+- Use `skills/<skill-name>/...` paths in documentation (the symlink path the agent sees), not `skills-library/...`.
+
+### Skill Structure
+
+- **`SKILL.md`** (required) — YAML frontmatter + markdown documentation
+- **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 `agent-job-secrets` skill.
+
+## Creating a Skill
+
+### Simple bash skill (most common)
+
+1. Create the skill in `skills-library/`:
+
+```bash
+mkdir skills-library/my-skill
+```
+
+2. Add `skills-library/my-skill/SKILL.md`:
+
+```markdown
+---
+name: my-skill
+description: Does X when the agent needs to Y.
+---
+
+# My Skill
+
+## Setup
+Requires MY_API_KEY environment variable.
+
+## Usage
+```bash
+skills/my-skill/run.sh <args>
+```
+```
+
+3. Add `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
+```
+
+4. Make it executable and activate:
+
+```bash
+chmod +x skills-library/my-skill/run.sh
+ln -s ../skills-library/my-skill skills/my-skill
+```
+
+### Node.js 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
+
+Always build AND test a skill in the same job. Tell the agent to test with real input after creating the skill and fix any issues before committing.
+
+## Default Skills
+
+Bundled in this directory and activated by default on first install:
+
+- `agent-job-secrets` — list/get agent-job secrets and OAuth credentials
+- `agent-job-dm` — list users + send DMs/broadcasts via the recipient's default channel
+- `agent-job-background` — spawn/check background agent jobs (defaults `--user-id` to the running container's `USER_ID`)
+- `playwright-cli` — browser automation via Playwright CLI