@harbinger-ai/harbinger 0.1.0

package/templates/.gitignore.template

@@ -0,0 +1,45 @@
+# Credentials - NEVER commit these
+
+.env
+.env.local
+*.pem
+*.key
+
+.claude/*
+!.claude/skills
+
+# Pi system prompt (generated at runtime from SOUL.md)
+.pi/SYSTEM.md
+
+# Skills dependencies (installed at runtime in Docker for correct arch)
+skills/*/node_modules/
+
+# Node
+node_modules/
+
+# Next.js
+.next/
+.next-new/
+.next-old/
+out/
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Logs
+*.log
+
+# Temporary files
+tmp/
+temp/
+.tmp/
+
+# Data (SQLite memory, etc.)
+data/

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

@@ -0,0 +1,48 @@
+/**
+ * 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

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

package/templates/CLAUDE.md

@@ -0,0 +1,29 @@
+# Templates Directory — Scaffolding Only
+
+This directory contains files that get copied into user projects when they run `npx thepopebot init`. It is **not** where event handler logic, API routes, or core features live.
+
+## Rules
+
+- **NEVER** add event handler code, API route handlers, or core logic here. All of that belongs in the NPM package (`api/`, `lib/`, `config/`, `bin/`).
+- Templates exist solely to scaffold a new user's project folder with thin wiring and user-editable configuration.
+- Files here may be modified to fix wiring, update configuration defaults, or adjust scaffolding — but never to implement features.
+
+## What belongs here
+
+- **Next.js wiring**: `next.config.mjs`, `instrumentation.js`, catch-all route, middleware — thin re-exports from `thepopebot/*`
+- **User-editable config**: `config/SOUL.md`, `config/EVENT_HANDLER.md`, `config/CRONS.json`, `config/TRIGGERS.json`, etc.
+- **GitHub Actions workflows**: `.github/workflows/`
+- **Docker files**: `docker/`, `docker-compose.yml`
+- **UI page shells**: `app/` pages that import components from the package
+- **Client components**: `app/components/` for components that must live in the user's project (e.g., `login-form.jsx`, `setup-form.jsx`) because they depend on user-side packages like `next-auth/react`
+
+## What does NOT belong here
+
+- Route handlers with business logic
+- Library code (`lib/`)
+- Database operations
+- LLM/AI integrations
+- Tool implementations
+- Anything that should be shared across all users via `npm update thepopebot`
+
+If you're adding a feature to the event handler, put it in the package. Templates just wire into it.

package/templates/CLAUDE.md.template

@@ -0,0 +1,307 @@
+# My Agent
+
+## Overview
+
+This is an autonomous AI agent powered by [thepopebot](https://github.com/stephengpope/thepopebot). It uses a **two-layer architecture**:
+
+1. **Event Handler** — A Next.js server that orchestrates everything: web UI, Telegram chat, cron scheduling, webhook triggers, and job creation.
+2. **Docker Agent** — A container that runs the Pi coding agent for autonomous task execution. Each job gets its own branch, container, and PR.
+
+All core logic lives in the `thepopebot` npm package. This project is a scaffolded shell — thin Next.js wiring, user-editable configuration, GitHub Actions workflows, and Docker files.
+
+## Directory Structure
+
+```
+project-root/
+├── CLAUDE.md                          # This file (project documentation)
+├── next.config.mjs                    # Next.js config (wraps withThepopebot())
+├── instrumentation.js                 # Server startup hook (re-exports from package)
+├── middleware.js                       # Auth middleware (re-exports from package)
+├── .env                               # API keys and tokens (gitignored)
+├── package.json
+│
+├── app/                               # Next.js app directory (page shells + client components)
+│   ├── api/[...thepopebot]/route.js   # Catch-all API route (re-exports from package)
+│   ├── stream/chat/route.js           # Chat streaming endpoint (session auth)
+│   └── components/                    # Client-side components
+│
+├── config/                            # Agent configuration (user-editable)
+│   ├── SOUL.md                        # Personality, identity, and values
+│   ├── EVENT_HANDLER.md               # Event handler LLM system prompt
+│   ├── AGENT.md                       # Agent runtime environment docs
+│   ├── JOB_SUMMARY.md                 # Prompt for summarizing completed jobs
+│   ├── HEARTBEAT.md                   # Self-monitoring / heartbeat behavior
+│   ├── SKILL_BUILDING_GUIDE.md             # Guide for building agent skills
+│   ├── CRONS.json                     # Scheduled job definitions
+│   └── TRIGGERS.json                  # Webhook trigger definitions
+│
+├── .github/workflows/                 # GitHub Actions
+├── docker/                            # Docker files (job agent + event handler)
+├── skills/                            # All available agent skills
+│   └── active/                        # Symlinks to active skills (shared by Pi + Claude Code)
+├── .pi/skills → skills/active         # Pi reads skills from here
+├── .claude/skills → skills/active     # Claude Code reads skills from here
+├── cron/                              # Scripts for command-type cron actions
+├── triggers/                          # Scripts for command-type trigger actions
+├── logs/                              # Per-job output (logs/<JOB_ID>/job.md + session .jsonl)
+└── data/                              # SQLite database (data/thepopebot.sqlite)
+```
+
+## Two-Layer Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                                                                         │
+│  ┌──────────────────┐         ┌──────────────────┐                     │
+│  │  Event Handler   │ ──1──►  │     GitHub       │                     │
+│  │  (creates job)   │         │ (job/* branch)   │                     │
+│  └────────▲─────────┘         └────────┬─────────┘                     │
+│           │                            │                               │
+│           │                            2 (triggers run-job.yml)        │
+│           │                            │                               │
+│           │                            ▼                               │
+│           │                   ┌──────────────────┐                     │
+│           │                   │  Docker Agent    │                     │
+│           │                   │  (runs Pi, PRs)  │                     │
+│           │                   └────────┬─────────┘                     │
+│           │                            │                               │
+│           │                            3 (creates PR)                  │
+│           │                            │                               │
+│           │                            ▼                               │
+│           │                   ┌──────────────────┐                     │
+│           │                   │     GitHub       │                     │
+│           │                   │   (PR opened)    │                     │
+│           │                   └────────┬─────────┘                     │
+│           │                            │                               │
+│           │                            4a (auto-merge.yml)             │
+│           │                            4b (notify-pr-complete.yml)     │
+│           │                            │                               │
+│           5 (notification → web UI     │                               │
+│              and Telegram)             │                               │
+│           └────────────────────────────┘                               │
+│                                                                         │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+**Event Handler** (this Next.js server): Receives requests (web UI, Telegram, webhooks, cron timers), creates jobs by pushing a `job/<uuid>` branch to GitHub, and manages the web interface.
+
+**Docker Agent**: A container spun up by GitHub Actions (`run-job.yml`) that clones the job branch, runs the Pi coding agent with the job prompt, commits results, and opens a PR.
+
+## Job Lifecycle
+
+1. **Job created** — Event handler calls `createJob()` (via chat, cron, trigger, or API)
+2. **Branch pushed** — A `job/<uuid>` branch is created with `logs/<uuid>/job.md` containing the task prompt
+3. **Workflow triggers** — `run-job.yml` fires on `job/*` branch creation
+4. **Container runs** — Docker agent clones the branch, builds `SYSTEM.md` from `config/SOUL.md` + `config/AGENT.md`, runs Pi with the job prompt, and logs the session to `logs/<uuid>/`
+5. **PR created** — Agent commits results and opens a pull request
+6. **Auto-merge** — `auto-merge.yml` squash-merges the PR if all changed files fall within `ALLOWED_PATHS` prefixes (default: `/logs`)
+7. **Notification** — `notify-pr-complete.yml` sends job results back to the event handler, which creates a notification in the web UI and sends a Telegram message
+
+## Action Types
+
+Both cron jobs and webhook triggers use the same dispatch system. Every action has a `type` field:
+
+| | `agent` (default) | `command` | `webhook` |
+|---|---|---|---|
+| **Uses LLM** | Yes — spins up Pi in Docker | No | No |
+| **Runtime** | Minutes to hours | Milliseconds to seconds | Milliseconds to seconds |
+| **Cost** | LLM API calls + GitHub Actions | Free (runs on event handler) | Free (runs on event handler) |
+| **Use case** | Tasks that need to think, reason, write code | Shell scripts, file operations | Call external APIs, forward webhooks |
+
+If the task needs to *think*, use `agent`. If it just needs to *do*, use `command`. If it needs to *call an external service*, use `webhook`.
+
+### Agent action
+```json
+{ "type": "agent", "job": "Analyze the logs and write a summary report" }
+```
+Creates a Docker Agent job. The `job` string is passed as-is to the LLM as its task prompt.
+
+### Command action
+```json
+{ "type": "command", "command": "node cleanup.js --older-than 7d" }
+```
+Runs a shell command on the event handler. Working directory: `cron/` for crons, `triggers/` for triggers.
+
+### Webhook action
+```json
+{
+  "type": "webhook",
+  "url": "https://api.example.com/notify",
+  "method": "POST",
+  "headers": { "Authorization": "Bearer token" },
+  "vars": { "source": "my-agent" }
+}
+```
+Makes an HTTP request. `GET` skips the body. `POST` (default) sends `{ ...vars }` or `{ ...vars, data: <incoming payload> }` when triggered by a webhook.
+
+## Cron Jobs
+
+Defined in `config/CRONS.json`, loaded at server startup by `node-cron`.
+
+```json
+[
+  {
+    "name": "Daily Check",
+    "schedule": "0 9 * * *",
+    "type": "agent",
+    "job": "Review recent activity and summarize findings",
+    "enabled": true
+  }
+]
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name |
+| `schedule` | Yes | Cron expression (e.g., `0 9 * * *` = daily at 9am) |
+| `type` | No | `agent` (default), `command`, or `webhook` |
+| `job` | For agent | Task prompt passed to the LLM |
+| `command` | For command | Shell command (runs in `cron/` directory) |
+| `url` | For webhook | Target URL |
+| `method` | For webhook | `GET` or `POST` (default: `POST`) |
+| `headers` | For webhook | Custom request headers |
+| `vars` | For webhook | Key-value pairs merged into request body |
+| `enabled` | No | Set `false` to disable (default: `true`) |
+| `llm_provider` | No | Override LLM provider for this cron (agent type only) |
+| `llm_model` | No | Override LLM model for this cron (agent type only) |
+
+## Webhook Triggers
+
+Defined in `config/TRIGGERS.json`, loaded at server startup. Triggers fire on POST requests to watched paths (after auth, before route handler, fire-and-forget).
+
+```json
+[
+  {
+    "name": "GitHub Push",
+    "watch_path": "/webhook/github-push",
+    "enabled": true,
+    "actions": [
+      {
+        "type": "agent",
+        "job": "Review the push to {{body.ref}}: {{body.head_commit.message}}"
+      }
+    ]
+  }
+]
+```
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Display name |
+| `watch_path` | Yes | URL path to watch (e.g., `/webhook/github-push`) |
+| `actions` | Yes | Array of actions to fire (same fields as cron actions) |
+| `enabled` | No | Set `false` to disable (default: `true`) |
+
+**Template tokens** for `job` and `command` strings:
+
+| Token | Resolves to |
+|-------|-------------|
+| `{{body}}` | Entire request body as JSON |
+| `{{body.field}}` | Nested field from request body |
+| `{{query}}` | All query parameters as JSON |
+| `{{query.field}}` | Specific query parameter |
+| `{{headers}}` | All request headers as JSON |
+| `{{headers.field}}` | Specific request header |
+
+## API Endpoints
+
+All API routes are under `/api/`, handled by the catch-all route.
+
+| Endpoint | Method | Auth | Purpose |
+|----------|--------|------|---------|
+| `/api/create-job` | POST | `x-api-key` | Create a new autonomous agent job |
+| `/api/telegram/webhook` | POST | `TELEGRAM_WEBHOOK_SECRET` | Telegram bot webhook |
+| `/api/telegram/register` | POST | `x-api-key` | Register Telegram webhook URL |
+| `/api/github/webhook` | POST | `GH_WEBHOOK_SECRET` | Receive notifications from GitHub Actions |
+| `/api/jobs/status` | GET | `x-api-key` | Check status of running/queued jobs |
+| `/api/ping` | GET | Public | Health check |
+
+**`x-api-key`**: Database-backed API keys generated through the web UI (Settings > Secrets). Keys are SHA-256 hashed, verified with timing-safe comparison. Format: `tpb_` prefix + 64 hex characters.
+
+## Web Interface
+
+Accessible after login at `APP_URL`. Routes: `/` (chat), `/chats` (history), `/chat/[chatId]` (resume chat), `/settings/crons`, `/settings/triggers`, `/settings/secrets` (API keys), `/swarm` (job monitor), `/notifications`, `/login` (auth / first-time admin setup).
+
+## Authentication
+
+NextAuth v5 with Credentials provider (email/password), JWT in httpOnly cookies. First visit creates admin account. Browser UI uses Server Actions with `requireAuth()`. API routes use `x-api-key` header. Chat streaming uses a dedicated route at `/stream/chat` with `auth()` session check.
+
+## Database
+
+SQLite via Drizzle ORM at `data/thepopebot.sqlite`. Auto-initialized and auto-migrated on server startup. Tables: `users`, `chats`, `messages`, `notifications`, `subscriptions`, `settings` (key-value store, also stores API keys). Column naming: camelCase in JS → snake_case in SQL.
+
+## GitHub Actions Workflows
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| `run-job.yml` | `job/*` branch created | Runs the Docker agent container |
+| `rebuild-event-handler.yml` | Push to `main` | Rebuilds server (fast path or Docker restart) |
+| `upgrade-event-handler.yml` | Manual `workflow_dispatch` | Creates PR to upgrade thepopebot package |
+| `build-image.yml` | `docker/job-pi-coding-agent/**` changes | Builds Pi coding agent Docker image to GHCR |
+| `auto-merge.yml` | Job PR opened | Squash-merges if changes are within `ALLOWED_PATHS` |
+| `notify-pr-complete.yml` | After `auto-merge.yml` | Sends job completion notification |
+| `notify-job-failed.yml` | `run-job.yml` fails | Sends failure notification |
+
+## GitHub Secrets & Variables
+
+### Secrets (prefix-based naming)
+
+| Prefix | Purpose | Visible to LLM? | Example |
+|--------|---------|------------------|---------|
+| `AGENT_` | Protected credentials for Docker agent | No (filtered by env-sanitizer) | `AGENT_GH_TOKEN`, `AGENT_ANTHROPIC_API_KEY` |
+| `AGENT_LLM_` | LLM-accessible credentials for Docker agent | Yes | `AGENT_LLM_BRAVE_API_KEY` |
+| *(none)* | Workflow-only secrets (never passed to container) | N/A | `GH_WEBHOOK_SECRET` |
+
+`AGENT_*` secrets are collected into a `SECRETS` JSON object by `run-job.yml` (prefix stripped) and exported as env vars in the container. `AGENT_LLM_*` go into `LLM_SECRETS` and are not filtered from the LLM's bash environment.
+
+### Repository Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `APP_URL` | Public URL for the event handler | Required |
+| `AUTO_MERGE` | Set to `"false"` to disable auto-merge | Enabled |
+| `ALLOWED_PATHS` | Comma-separated path prefixes for auto-merge | `/logs` |
+| `JOB_IMAGE_URL` | Docker image for job agent (GHCR URLs trigger auto-builds) | Default thepopebot image |
+| `EVENT_HANDLER_IMAGE_URL` | Docker image for event handler | Default thepopebot image |
+| `RUNS_ON` | GitHub Actions runner label | `ubuntu-latest` |
+| `LLM_PROVIDER` | LLM provider for Docker agent | `anthropic` |
+| `LLM_MODEL` | LLM model name for Docker agent | Provider default |
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `APP_URL` | Public URL for webhooks and Telegram | Yes |
+| `AUTH_SECRET` | NextAuth session encryption (auto-generated) | Yes |
+| `GH_TOKEN` | GitHub PAT for creating branches/files | Yes |
+| `GH_OWNER` | GitHub repository owner | Yes |
+| `GH_REPO` | GitHub repository name | Yes |
+| `TELEGRAM_BOT_TOKEN` | Telegram bot token | For Telegram |
+| `TELEGRAM_WEBHOOK_SECRET` | Telegram webhook validation secret | No |
+| `TELEGRAM_CHAT_ID` | Default chat ID for notifications | For Telegram |
+| `GH_WEBHOOK_SECRET` | GitHub Actions webhook auth | For notifications |
+| `LLM_PROVIDER` | `anthropic`, `openai`, `google`, or `custom` | No (default: `anthropic`) |
+| `LLM_MODEL` | Model name override | No |
+| `LLM_MAX_TOKENS` | Max tokens for LLM responses | No (default: 4096) |
+| `ANTHROPIC_API_KEY` | Anthropic API key | For anthropic provider |
+| `OPENAI_API_KEY` | OpenAI API key / Whisper | For openai provider |
+| `OPENAI_BASE_URL` | Custom OpenAI-compatible base URL | For custom provider |
+| `GOOGLE_API_KEY` | Google API key | For google provider |
+| `CUSTOM_API_KEY` | Custom provider API key | For custom provider |
+| `DATABASE_PATH` | Override SQLite DB location | No |
+
+## Customization
+
+User-editable config files in `config/`: `SOUL.md` (personality), `EVENT_HANDLER.md` (LLM system prompt), `AGENT.md` (runtime docs), `JOB_SUMMARY.md` (job summaries), `HEARTBEAT.md` (self-monitoring), `SKILL_BUILDING_GUIDE.md` (skill guide), `CRONS.json` (scheduled jobs), `TRIGGERS.json` (webhook triggers).
+
+Skills in `skills/` are activated by symlinking into `skills/active/`. Both `.pi/skills` and `.claude/skills` point to `skills/active/`. Scripts for command-type actions go in `cron/` and `triggers/`.
+
+### Markdown includes and variables
+
+Config markdown files support includes and built-in variables (processed by the package's `render-md.js`):
+
+| Syntax | Description |
+|--------|-------------|
+| `{{ filepath.md }}` | Include another file (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 — never hardcode skill names, this is resolved at runtime |

package/templates/app/api/[...thepopebot]/route.js

@@ -0,0 +1 @@
+export { GET, POST } from 'thepopebot/api';

package/templates/app/api/auth/[...nextauth]/route.js

@@ -0,0 +1 @@
+export { GET, POST } from 'thepopebot/auth';

package/templates/app/chat/[chatId]/page.js

@@ -0,0 +1,8 @@
+import { auth } from 'thepopebot/auth';
+import { ChatPage } from 'thepopebot/chat';
+
+export default async function ChatRoute({ params }) {
+  const { chatId } = await params;
+  const session = await auth();
+  return <ChatPage session={session} needsSetup={false} chatId={chatId} />;
+}

package/templates/app/chats/page.js

@@ -0,0 +1,7 @@
+import { auth } from 'thepopebot/auth';
+import { ChatsPage } from 'thepopebot/chat';
+
+export default async function ChatsRoute() {
+  const session = await auth();
+  return <ChatsPage session={session} />;
+}

package/templates/app/components/ascii-logo.jsx

@@ -0,0 +1,10 @@
+export function AsciiLogo() {
+  return (
+    <pre className="text-foreground text-[clamp(0.45rem,1.5vw,0.85rem)] leading-snug text-left mb-8 select-none">{` _____ _          ____                  ____        _
+|_   _| |__   ___|  _ \\ ___  _ __   ___| __ )  ___ | |_
+  | | | '_ \\ / _ \\ |_) / _ \\| '_ \\ / _ \\  _ \\ / _ \\| __|
+  | | | | | |  __/  __/ (_) | |_) |  __/ |_) | (_) | |_
+  |_| |_| |_|\\___|_|   \\___/| .__/ \\___|____/ \\___/ \\__|
+                            |_|`}</pre>
+  );
+}

package/templates/app/components/login-form.jsx

@@ -0,0 +1,92 @@
+'use client';
+
+import { useState } from 'react';
+import { signIn } from 'next-auth/react';
+import { useRouter, useSearchParams } from 'next/navigation';
+import { Button } from './ui/button';
+import { Input } from './ui/input';
+import { Label } from './ui/label';
+import { Card, CardHeader, CardTitle, CardDescription, CardContent } from './ui/card';
+
+export function LoginForm() {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+  const justCreated = searchParams.get('created') === '1';
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  async function handleSubmit(e) {
+    e.preventDefault();
+    setError('');
+    setLoading(true);
+
+    try {
+      const result = await signIn('credentials', {
+        email,
+        password,
+        redirect: false,
+      });
+
+      if (result?.error) {
+        setError('Invalid email or password.');
+      } else {
+        router.push('/');
+      }
+    } catch {
+      setError('Something went wrong. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div className="w-full max-w-sm space-y-3">
+      {justCreated && (
+        <div className="rounded-lg border border-green-500/30 bg-green-500/5 p-4">
+          <p className="text-sm font-medium text-green-600 dark:text-green-400">
+            Account created. Sign in with your new credentials.
+          </p>
+        </div>
+      )}
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>Sign In</CardTitle>
+        <CardDescription>Log in to your agent dashboard.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              placeholder="admin@example.com"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              required
+            />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="password">Password</Label>
+            <Input
+              id="password"
+              type="password"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              required
+            />
+          </div>
+          {error && (
+            <p className="text-sm text-destructive">{error}</p>
+          )}
+          <Button type="submit" className="w-full" disabled={loading}>
+            {loading ? 'Signing in...' : 'Sign In'}
+          </Button>
+        </form>
+      </CardContent>
+    </Card>
+    </div>
+  );
+}

package/templates/app/components/setup-form.jsx

@@ -0,0 +1,82 @@
+'use client';
+
+import { useState } from 'react';
+import { useRouter } from 'next/navigation';
+import { Button } from './ui/button';
+import { Input } from './ui/input';
+import { Label } from './ui/label';
+import { Card, CardHeader, CardTitle, CardDescription, CardContent } from './ui/card';
+import { setupAdmin } from 'thepopebot/auth/actions';
+
+export function SetupForm() {
+  const router = useRouter();
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+  const [loading, setLoading] = useState(false);
+
+  async function handleSubmit(e) {
+    e.preventDefault();
+    setError('');
+    setLoading(true);
+
+    try {
+      const result = await setupAdmin(email, password);
+
+      if (result.error) {
+        setError(result.error);
+        setLoading(false);
+        return;
+      }
+
+      // Redirect to login with success indicator — admin must authenticate through the normal flow
+      router.push('/login?created=1');
+    } catch {
+      setError('Something went wrong. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <Card className="w-full max-w-sm">
+      <CardHeader>
+        <CardTitle>Create Admin Account</CardTitle>
+        <CardDescription>Set up your first admin account to get started.</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="email">Email</Label>
+            <Input
+              id="email"
+              type="email"
+              placeholder="admin@example.com"
+              value={email}
+              onChange={(e) => setEmail(e.target.value)}
+              required
+            />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="password">Password</Label>
+            <Input
+              id="password"
+              type="password"
+              placeholder="Min 8 characters"
+              value={password}
+              onChange={(e) => setPassword(e.target.value)}
+              required
+              minLength={8}
+            />
+          </div>
+          {error && (
+            <p className="text-sm text-destructive">{error}</p>
+          )}
+          <Button type="submit" className="w-full" disabled={loading}>
+            {loading ? 'Creating...' : 'Create Account'}
+          </Button>
+        </form>
+      </CardContent>
+    </Card>
+  );
+}

package/templates/app/components/theme-provider.jsx

@@ -0,0 +1,11 @@
+'use client';
+
+import { ThemeProvider as NextThemesProvider } from 'next-themes';
+
+export function ThemeProvider({ children }) {
+  return (
+    <NextThemesProvider attribute="class" defaultTheme="system" enableSystem>
+      {children}
+    </NextThemesProvider>
+  );
+}