# Web App (Telegram-Free Pivot) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`) syntax for tracking. UI component implementation tasks (Phases D–F) should be executed with assistance from the **frontend-design:frontend-design** skill — invoke it when a task says "use frontend-design".

**Goal:** Replace the Telegram bot with a Next.js PWA at `wabot.04080616.xyz`. Operator installs the web app on their phone and uses it for everything: pairing accounts (live QR in browser), browsing groups, sending test messages, scheduling reminders. Telegram code is fully removed.

**Architecture:** `apps/bot` shrinks (no more `grammy`/menus/wizard); a new `ipc/command-consumer.ts` listens to Postgres `LISTEN bot.command` and dispatches to existing Baileys/sender/sync logic. New `apps/web` is a Next.js 16 App Router app with Server Components for reads, Server Actions for mutations, an SSE endpoint for live updates, and `@serwist/next` for PWA.

**Tech Stack:** Next.js 16, React 19, TypeScript, Tailwind CSS v4, shadcn/ui, react-hook-form + zod, Drizzle, `pg` (for LISTEN), `@serwist/next`, Geist font, Sonner toast.

**Spec reference:** `docs/superpowers/specs/2026-05-09-web-app-design.md`

**Phase guide:**
- A — Telegram removal (Tasks 1-4)
- B — Web app skeleton (Tasks 5-9)
- C — Foundation: layout, SSE, middleware (Tasks 10-12)
- D — Read-only pages (Tasks 13-16)
- E — Mutations: pair, unpair, send-test (Tasks 17-19)
- F — Reminder wizard (Tasks 20-21)
- G — PWA (Task 22)
- H — Verify + push (Tasks 23-24)

---

## File structure produced by this plan

```
apps/
├── bot/
│   └── src/
│       ├── ipc/
│       │   ├── notify.ts            (NEW) typed pgNotify wrapper
│       │   ├── command-consumer.ts  (NEW) replaces telegram/bot.ts
│       │   ├── pair-handler.ts      (NEW) pair flow without Telegram
│       │   ├── unpair-handler.ts    (NEW)
│       │   ├── send-test-handler.ts (NEW)
│       │   └── sync-groups-handler.ts (NEW)
│       ├── telegram/                (DELETED — entire directory)
│       └── index.ts                 (MODIFIED)
│
└── web/                              (NEW)
    ├── package.json
    ├── tsconfig.json
    ├── next.config.ts
    ├── tailwind.config.ts
    ├── postcss.config.mjs
    ├── components.json               shadcn-ui config
    ├── public/
    │   ├── icon-192.png
    │   ├── icon-512.png
    │   └── apple-touch-icon.png
    └── src/
        ├── env.ts                    zod env validation
        ├── middleware.ts             rate limit + 404 for /api/* except events
        ├── lib/
        │   ├── db.ts                 server-only Drizzle client
        │   ├── operator.ts           getSeededOperator() helper
        │   ├── notify.ts             pgNotify('bot.command', ...) helper
        │   └── logger.ts             pino on server
        ├── hooks/
        │   └── use-events.ts         SSE hook
        ├── actions/                  Server Actions
        │   ├── accounts.ts           pair, unpair, sync-groups
        │   ├── groups.ts             send-test
        │   ├── reminders.ts          create, delete, edit
        │   └── media.ts              upload
        ├── components/
        │   ├── app-shell.tsx         responsive layout (bottom nav / sidebar)
        │   ├── theme-provider.tsx
        │   ├── ui/                   shadcn components installed here
        │   └── (feature-specific components)
        ├── app/
        │   ├── layout.tsx            root layout, theme provider, app shell
        │   ├── page.tsx              dashboard
        │   ├── accounts/
        │   │   ├── page.tsx          list
        │   │   ├── new/page.tsx      pair (live QR)
        │   │   └── [id]/
        │   │       ├── page.tsx      detail
        │   │       ├── pairing/page.tsx (live QR sub-route)
        │   │       └── groups/page.tsx
        │   ├── groups/[id]/page.tsx  detail + send-test
        │   ├── reminders/
        │   │   ├── page.tsx          list
        │   │   ├── new/page.tsx      wizard (URL-state, ?step=1..5)
        │   │   └── [id]/page.tsx     detail + history + delete
        │   ├── settings/page.tsx
        │   ├── manifest.webmanifest/route.ts (PWA)
        │   └── api/
        │       ├── events/route.ts   SSE
        │       └── health/route.ts
        └── pwa/
            └── sw.ts                 serwist service worker entry

docker/web.Dockerfile                 (REPLACED — currently a placeholder)
docker-compose.base.yml               (MODIFIED — add web service)
docker-compose.dev.yml                (MODIFIED — add web overrides)
docs/superpowers/specs/manual-test-web.md (NEW manual runbook)
```

---

# Phase A — Telegram removal

## Task 1: Add IPC notify helper + command consumer skeleton in `bot`

**Files:**
- Create: `apps/bot/src/ipc/notify.ts`
- Create: `apps/bot/src/ipc/command-consumer.ts` (skeleton)

- [ ] **Step 1: Create `apps/bot/src/ipc/notify.ts`**

```typescript
import { sql } from "drizzle-orm";
import { db } from "../db.js";
import { logger } from "../logger.js";

export type WebEvent =
  | { type: "session.qr"; accountId: string; qrPng: string /* base64 */ }
  | { type: "session.connected"; accountId: string; phoneNumber: string | null }
  | { type: "session.disconnected"; accountId: string }
  | { type: "session.timeout"; accountId: string }
  | { type: "groups.synced"; accountId: string; count: number }
  | { type: "reminder.fired"; reminderId: string; runId: string; status: string }
  | { type: "reminder.failed"; reminderId: string; error: string };

export async function pgNotifyWeb(event: WebEvent): Promise<void> {
  const json = JSON.stringify(event);
  // pg_notify takes a literal channel name as 1st arg.
  await db.execute(sql`SELECT pg_notify('web.event', ${json})`);
  logger.debug({ event: event.type }, "ipc: web.event published");
}
```

- [ ] **Step 2: Create `apps/bot/src/ipc/command-consumer.ts` (skeleton)**

```typescript
import { Client } from "pg";
import { logger } from "../logger.js";
import { env } from "../env.js";

export type BotCommand =
  | { type: "account.start_pairing"; accountId: string }
  | { type: "account.unpair"; accountId: string }
  | { type: "account.sync_groups"; accountId: string }
  | { type: "group.send_test"; groupId: string; text: string };

type Handler = (cmd: BotCommand) => Promise<void>;
const handlers: { [K in BotCommand["type"]]?: (cmd: Extract<BotCommand, { type: K }>) => Promise<void> } = {};

export function registerHandler<T extends BotCommand["type"]>(
  type: T,
  fn: (cmd: Extract<BotCommand, { type: T }>) => Promise<void>,
): void {
  // eslint-disable-next-line @typescript-eslint/no-explicit-any
  (handlers as any)[type] = fn;
}

export async function startCommandConsumer(): Promise<() => Promise<void>> {
  const client = new Client({ connectionString: env.DATABASE_URL });
  await client.connect();
  await client.query("LISTEN \"bot.command\"");

  client.on("notification", (msg) => {
    if (msg.channel !== "bot.command" || !msg.payload) return;
    let cmd: BotCommand;
    try {
      cmd = JSON.parse(msg.payload) as BotCommand;
    } catch (err) {
      logger.warn({ err, payload: msg.payload }, "ipc: bad command payload");
      return;
    }
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
    const fn: Handler | undefined = (handlers as any)[cmd.type];
    if (!fn) {
      logger.warn({ cmd }, "ipc: no handler for command type");
      return;
    }
    fn(cmd).catch((err) => logger.error({ err, cmd }, "ipc: handler failed"));
  });

  client.on("error", (err) => logger.error({ err }, "ipc: consumer client error"));
  logger.info("ipc: command consumer started");

  return async () => {
    try {
      await client.query("UNLISTEN \"bot.command\"");
    } catch (err) {
      logger.warn({ err }, "ipc: UNLISTEN failed (continuing shutdown)");
    }
    await client.end();
    logger.info("ipc: command consumer stopped");
  };
}
```

- [ ] **Step 3: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/bot typecheck
```

Expected: no errors.

- [ ] **Step 4: Commit**

```bash
git add apps/bot/src/ipc
git -c commit.gpgsign=false commit -m "feat(bot): add IPC notify helper + command consumer skeleton"
```

---

## Task 2: Move pair / unpair / send-test / sync-groups handlers into `ipc/`

**Files:**
- Create: `apps/bot/src/ipc/pair-handler.ts`
- Create: `apps/bot/src/ipc/unpair-handler.ts`
- Create: `apps/bot/src/ipc/send-test-handler.ts`
- Create: `apps/bot/src/ipc/sync-groups-handler.ts`

- [ ] **Step 1: Create `apps/bot/src/ipc/pair-handler.ts`**

```typescript
import { eq, and, lt } from "drizzle-orm";
import { rm } from "node:fs/promises";
import { join } from "node:path";
import { whatsappAccounts } from "@cmbot/db";
import { db } from "../db.js";
import { env } from "../env.js";
import { logger } from "../logger.js";
import { sessionManager } from "../whatsapp/session-manager.js";
import { renderQrPng } from "../whatsapp/qr-renderer.js";
import { syncGroupsForAccount } from "../whatsapp/group-sync.js";
import { writeAuditLog } from "../audit.js";
import { pgNotifyWeb } from "./notify.js";

const PAIR_TIMEOUT_MS = 5 * 60 * 1000;
const offByAccount = new Map<string, () => void>();
const lastQrPayload = new Map<string, string>();
const pairTimeouts = new Map<string, NodeJS.Timeout>();

async function abandonPair(accountId: string): Promise<{ existed: boolean; label: string | null }> {
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq }) => eq(a.id, accountId),
  });
  if (!account || account.status !== "pending") {
    return { existed: false, label: account?.label ?? null };
  }
  const off = offByAccount.get(accountId);
  if (off) {
    off();
    offByAccount.delete(accountId);
  }
  const t = pairTimeouts.get(accountId);
  if (t) {
    clearTimeout(t);
    pairTimeouts.delete(accountId);
  }
  lastQrPayload.delete(accountId);
  if (sessionManager.hasSession(accountId)) {
    await sessionManager.stop(accountId);
  }
  await rm(join(env.SESSIONS_DIR, accountId), { recursive: true, force: true });
  await db.delete(whatsappAccounts).where(eq(whatsappAccounts.id, accountId));
  return { existed: true, label: account.label };
}

export async function handleStartPairing(accountId: string): Promise<void> {
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq }) => eq(a.id, accountId),
  });
  if (!account) {
    logger.warn({ accountId }, "pair: account row missing");
    return;
  }

  // Wire up event listener for this account
  const off = sessionManager.on(async (id, _state, event) => {
    if (id !== accountId) return;
    try {
      if (event.type === "qr") {
        if (lastQrPayload.get(id) === event.payload) return;
        lastQrPayload.set(id, event.payload);
        const png = await renderQrPng(event.payload);
        await pgNotifyWeb({
          type: "session.qr",
          accountId: id,
          qrPng: png.toString("base64"),
        });
      } else if (event.type === "open") {
        const t = pairTimeouts.get(id);
        if (t) {
          clearTimeout(t);
          pairTimeouts.delete(id);
        }
        lastQrPayload.delete(id);
        offByAccount.delete(id);
        const session = sessionManager.getSession(id);
        let synced = 0;
        if (session) {
          const r = await syncGroupsForAccount(id, session.socket);
          synced = r.synced;
        }
        await writeAuditLog(db, {
          operatorId: account.operatorId,
          source: "web",
          action: "account.paired",
          targetType: "whatsapp_account",
          targetId: id,
          payload: { label: account.label },
        });
        await pgNotifyWeb({
          type: "session.connected",
          accountId: id,
          phoneNumber: event.phoneNumber ?? null,
        });
        await pgNotifyWeb({
          type: "groups.synced",
          accountId: id,
          count: synced,
        });
        off();
      } else if (event.type === "close" && event.loggedOut) {
        const t = pairTimeouts.get(id);
        if (t) {
          clearTimeout(t);
          pairTimeouts.delete(id);
        }
        lastQrPayload.delete(id);
        offByAccount.delete(id);
        await pgNotifyWeb({ type: "session.timeout", accountId: id });
        off();
      }
    } catch (err) {
      logger.error({ err, accountId: id }, "pair: handler error");
    }
  });
  offByAccount.set(accountId, off);

  try {
    await sessionManager.start(accountId);
  } catch (err) {
    logger.error({ err, accountId }, "pair: start failed");
    off();
    offByAccount.delete(accountId);
    await pgNotifyWeb({ type: "session.timeout", accountId });
    return;
  }

  const timeoutId = setTimeout(() => {
    void (async () => {
      try {
        const r = await abandonPair(accountId);
        if (r.existed) {
          await pgNotifyWeb({ type: "session.timeout", accountId });
        }
      } catch (err) {
        logger.error({ err, accountId }, "pair: timeout cleanup failed");
      }
    })();
  }, PAIR_TIMEOUT_MS);
  pairTimeouts.set(accountId, timeoutId);
}

/** Sweep stale pending accounts on bot startup. Same as before. */
export async function sweepStalePendingAccounts(): Promise<void> {
  const cutoff = new Date(Date.now() - 60 * 60 * 1000);
  const stale = await db
    .select({ id: whatsappAccounts.id, label: whatsappAccounts.label })
    .from(whatsappAccounts)
    .where(and(eq(whatsappAccounts.status, "pending"), lt(whatsappAccounts.createdAt, cutoff)));
  for (const row of stale) {
    await rm(join(env.SESSIONS_DIR, row.id), { recursive: true, force: true });
    await db.delete(whatsappAccounts).where(eq(whatsappAccounts.id, row.id));
    logger.info({ accountId: row.id, label: row.label }, "sweep: removed stale pending account");
  }
}
```

- [ ] **Step 2: Create `apps/bot/src/ipc/unpair-handler.ts`**

```typescript
import { eq } from "drizzle-orm";
import { rm } from "node:fs/promises";
import { join } from "node:path";
import { whatsappAccounts } from "@cmbot/db";
import { db } from "../db.js";
import { env } from "../env.js";
import { sessionManager } from "../whatsapp/session-manager.js";
import { writeAuditLog } from "../audit.js";
import { pgNotifyWeb } from "./notify.js";
import { logger } from "../logger.js";

export async function handleUnpair(accountId: string): Promise<void> {
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq }) => eq(a.id, accountId),
  });
  if (!account) {
    logger.warn({ accountId }, "unpair: account row missing");
    return;
  }
  await sessionManager.stop(accountId);
  await rm(join(env.SESSIONS_DIR, accountId), { recursive: true, force: true });
  await db
    .update(whatsappAccounts)
    .set({ status: "logged_out", phoneNumber: null })
    .where(eq(whatsappAccounts.id, accountId));
  await writeAuditLog(db, {
    operatorId: account.operatorId,
    source: "web",
    action: "account.unpaired",
    targetType: "whatsapp_account",
    targetId: accountId,
    payload: { label: account.label },
  });
  await pgNotifyWeb({ type: "session.disconnected", accountId });
}
```

- [ ] **Step 3: Create `apps/bot/src/ipc/sync-groups-handler.ts`**

```typescript
import { whatsappAccounts } from "@cmbot/db";
import { db } from "../db.js";
import { sessionManager } from "../whatsapp/session-manager.js";
import { syncGroupsForAccount } from "../whatsapp/group-sync.js";
import { pgNotifyWeb } from "./notify.js";
import { logger } from "../logger.js";

export async function handleSyncGroups(accountId: string): Promise<void> {
  const session = sessionManager.getSession(accountId);
  if (!session) {
    logger.warn({ accountId }, "sync-groups: account not connected");
    return;
  }
  const result = await syncGroupsForAccount(accountId, session.socket);
  await pgNotifyWeb({ type: "groups.synced", accountId, count: result.synced });
}
```

- [ ] **Step 4: Create `apps/bot/src/ipc/send-test-handler.ts`**

```typescript
import { sessionManager } from "../whatsapp/session-manager.js";
import { sendTextToGroup } from "../whatsapp/sender.js";
import { writeAuditLog } from "../audit.js";
import { db } from "../db.js";
import { logger } from "../logger.js";

export async function handleSendTest(groupId: string, text: string): Promise<void> {
  const group = await db.query.whatsappGroups.findFirst({
    where: (g, { eq }) => eq(g.id, groupId),
  });
  if (!group) {
    logger.warn({ groupId }, "send-test: group missing");
    return;
  }
  const session = sessionManager.getSession(group.accountId);
  if (!session) {
    logger.warn({ groupId, accountId: group.accountId }, "send-test: account not connected");
    return;
  }
  try {
    const result = await sendTextToGroup(session.socket, group.waGroupJid, text);
    await writeAuditLog(db, {
      operatorId: null,
      source: "web",
      action: "group.send_test",
      targetType: "whatsapp_group",
      targetId: groupId,
      payload: { groupName: group.name, length: text.length, waMessageId: result.messageId ?? null },
    });
  } catch (err) {
    logger.error({ err, groupId }, "send-test: failed");
  }
}
```

- [ ] **Step 5: Wire handlers into `command-consumer.ts`**

Replace the bottom of `apps/bot/src/ipc/command-consumer.ts` (the `startCommandConsumer` function) with the version that registers handlers on startup. Add this BEFORE `startCommandConsumer`:

```typescript
import { handleStartPairing } from "./pair-handler.js";
import { handleUnpair } from "./unpair-handler.js";
import { handleSyncGroups } from "./sync-groups-handler.js";
import { handleSendTest } from "./send-test-handler.js";
```

Then at the bottom, after the existing `startCommandConsumer` function, append:

```typescript
export function registerDefaultHandlers(): void {
  registerHandler("account.start_pairing", async (cmd) => {
    await handleStartPairing(cmd.accountId);
  });
  registerHandler("account.unpair", async (cmd) => {
    await handleUnpair(cmd.accountId);
  });
  registerHandler("account.sync_groups", async (cmd) => {
    await handleSyncGroups(cmd.accountId);
  });
  registerHandler("group.send_test", async (cmd) => {
    await handleSendTest(cmd.groupId, cmd.text);
  });
}
```

- [ ] **Step 6: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/bot typecheck
```

- [ ] **Step 7: Commit**

```bash
git add apps/bot/src/ipc
git -c commit.gpgsign=false commit -m "feat(bot): add IPC handlers for pair / unpair / sync / send-test"
```

---

## Task 3: Replace `apps/bot/src/index.ts` to use IPC consumer instead of Telegram

**Files:**
- Modify: `apps/bot/src/index.ts`

- [ ] **Step 1: Replace `apps/bot/src/index.ts` with**

```typescript
import { logger } from "./logger.js";
import { pool } from "./db.js";
import { startHealthServer, setSessionCountsProvider } from "./health.js";
import { sessionManager } from "./whatsapp/session-manager.js";
import { startBoss, stopBoss } from "./scheduler/pgboss-client.js";
import { registerReminderJobs } from "./scheduler/reminder-jobs.js";
import {
  startCommandConsumer,
  registerDefaultHandlers,
} from "./ipc/command-consumer.js";
import { sweepStalePendingAccounts } from "./ipc/pair-handler.js";

async function main(): Promise<void> {
  logger.info("bot starting");
  const health = startHealthServer();
  setSessionCountsProvider(() => sessionManager.getCounts());

  const boss = await startBoss();
  await registerReminderJobs(boss);

  registerDefaultHandlers();
  const stopConsumer = await startCommandConsumer();

  await sweepStalePendingAccounts();
  await sessionManager.resumeFromDb();

  const shutdown = async (signal: string): Promise<void> => {
    logger.info({ signal }, "shutting down");
    await stopConsumer();
    await sessionManager.stopAll();
    await stopBoss();
    health.close();
    await pool.end();
    process.exit(0);
  };

  process.on("SIGINT", () => void shutdown("SIGINT"));
  process.on("SIGTERM", () => void shutdown("SIGTERM"));

  logger.info("bot ready");
}

main().catch((err) => {
  logger.fatal({ err }, "bot failed to start");
  process.exit(1);
});
```

- [ ] **Step 2: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/bot typecheck
```

Expected: errors about deleted Telegram imports (we delete the Telegram code in Task 4).

- [ ] **Step 3: Don't commit yet** — Task 4 finishes the deletion. The repo is in a transient state.

---

## Task 4: Delete `apps/bot/src/telegram/` and remove `grammy` + Telegram env keys

**Files:**
- Delete: `apps/bot/src/telegram/` (entire directory)
- Delete: `apps/bot/src/media/ingest.ts` (Telegram-side download — web uploads media now)
- Modify: `apps/bot/src/env.ts` (remove TELEGRAM_* keys)
- Modify: `apps/bot/package.json` (remove `grammy`)
- Modify: `envs/.env.example` (remove TELEGRAM_* keys)
- Modify: `.env.development` (remove TELEGRAM_* keys)
- Modify: `apps/bot/src/whatsapp/qr-renderer.ts` (no change — but ensure it stays since the bot still renders QR for the web path)

- [ ] **Step 1: Delete the Telegram directory**

```bash
rm -rf apps/bot/src/telegram
rm -f apps/bot/src/media/ingest.ts
```

(`apps/bot/src/media/` directory becomes empty — leave the dir or delete it; both are fine.)

- [ ] **Step 2: Update `apps/bot/src/env.ts`** — remove `TELEGRAM_BOT_TOKEN`, `TELEGRAM_OPERATOR_WHITELIST`, `TELEGRAM_QR_CHAT_ID`

```typescript
import { z } from "zod";

const numberFromString = z.string().regex(/^\d+$/).transform((s) => Number(s));

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  DATA_DIR: z.string().min(1),
  SESSIONS_DIR: z.string().min(1),
  MEDIA_DIR: z.string().min(1),
  BOT_HEALTH_PORT: numberFromString,
  BOT_LOG_LEVEL: z.enum(["fatal", "error", "warn", "info", "debug", "trace"]).default("info"),
});

export type Env = z.infer<typeof envSchema>;

export function parseEnv(input: Record<string, string | undefined>): Env {
  return envSchema.parse(input);
}

export const env = parseEnv(process.env);
```

- [ ] **Step 3: Update `apps/bot/src/env.test.ts`** to remove deleted keys from the valid fixture

```typescript
import { describe, expect, it } from "vitest";
import { parseEnv } from "./env.js";

const valid = {
  DATABASE_URL: "postgres://u:p@h:5432/db",
  DATA_DIR: "/data",
  SESSIONS_DIR: "/data/sessions",
  MEDIA_DIR: "/data/media",
  BOT_HEALTH_PORT: "8081",
  BOT_LOG_LEVEL: "info",
};

describe("parseEnv", () => {
  it("parses a valid env", () => {
    const env = parseEnv(valid);
    expect(env.BOT_HEALTH_PORT).toBe(8081);
  });

  it("rejects missing DATABASE_URL", () => {
    const { DATABASE_URL: _, ...rest } = valid;
    expect(() => parseEnv(rest)).toThrow();
  });

  it("rejects malformed port", () => {
    expect(() => parseEnv({ ...valid, BOT_HEALTH_PORT: "notanumber" })).toThrow();
  });
});
```

- [ ] **Step 4: Remove `grammy` from `apps/bot/package.json` deps**

Edit `apps/bot/package.json`, delete the `"grammy": "^1.31.0",` line.

- [ ] **Step 5: Run install to update lockfile**

```bash
NO_SUDO=1 scripts/dev.sh pnpm install
```

- [ ] **Step 6: Update env files** — remove `TELEGRAM_BOT_TOKEN`, `TELEGRAM_OPERATOR_WHITELIST`, `TELEGRAM_QR_CHAT_ID`, `SEED_OPERATOR_TELEGRAM_ID`, `SEED_OPERATOR_NAME` from both `envs/.env.example` and `.env.development`. Keep `WEB_PORT` and `AUTH_SECRET` (we'll use them in Phase B).

`.env.development` after edit (replace the keys you remove with web-relevant ones — `WEB_PORT` already there):

```bash
DATABASE_URL=postgres://waBot:cJe3SGjHHAitNBE4@192.168.0.210:5432/wabot
DATA_DIR=/data
SESSIONS_DIR=/data/sessions
MEDIA_DIR=/data/media
BOT_HEALTH_PORT=8081
BOT_LOG_LEVEL=debug
WEB_PORT=3000
AUTH_SECRET=86f656580a58f03b6ccb43d257e0e801ecd5356e042e8886b3c7c569e29ff13c
```

`envs/.env.example` similarly cleaned.

- [ ] **Step 7: Update `docker-compose.base.yml`** — remove the `TELEGRAM_*`, `SEED_*` env entries from the `tools` service environment block. Keep DATABASE_URL etc.

- [ ] **Step 8: Update `docker-compose.dev.yml`** for the bot service — remove `TELEGRAM_BOT_TOKEN`, `TELEGRAM_OPERATOR_WHITELIST`, `TELEGRAM_QR_CHAT_ID` from the `bot` service's `environment:` block.

- [ ] **Step 9: Typecheck and run tests**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/bot typecheck
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/bot test
```

Expected: typecheck clean, tests pass (env tests pass, deleted Telegram tests gone).

- [ ] **Step 10: Restart bot and verify clean startup**

```bash
NO_SUDO=1 scripts/dev.sh restart-bot
sleep 6
docker compose --env-file .env.development -f docker-compose.base.yml -f docker-compose.dev.yml logs --tail=15 bot
```

Expected log lines (no Telegram references):
```
bot starting
health server listening
pg-boss started
reminder.fire: handler registered
ipc: command consumer started
bot ready
```

- [ ] **Step 11: Commit**

```bash
git add -A
git -c commit.gpgsign=false commit -m "feat(bot): remove Telegram code; switch to IPC consumer"
```

---

# Phase B — Web app skeleton

## Task 5: Initialize `apps/web` Next.js project

**Files:**
- Create: `apps/web/package.json`
- Create: `apps/web/tsconfig.json`
- Create: `apps/web/next.config.ts`
- Create: `apps/web/postcss.config.mjs`
- Create: `apps/web/src/app/layout.tsx`
- Create: `apps/web/src/app/page.tsx`
- Create: `apps/web/src/app/globals.css`
- Create: `apps/web/src/env.ts`

- [ ] **Step 1: Create `apps/web/package.json`**

```json
{
  "name": "@cmbot/web",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "next dev --hostname 0.0.0.0",
    "build": "next build",
    "start": "next start --hostname 0.0.0.0",
    "lint": "next lint",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": {
    "@cmbot/db": "workspace:*",
    "@cmbot/shared": "workspace:*",
    "next": "^16.0.0",
    "pg": "^8.13.0",
    "pino": "^9.5.0",
    "pino-pretty": "^11.3.0",
    "qrcode": "^1.5.4",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@tailwindcss/postcss": "^4.0.0",
    "@types/node": "^22.7.0",
    "@types/pg": "^8.11.10",
    "@types/qrcode": "^1.5.5",
    "@types/react": "^19.0.0",
    "@types/react-dom": "^19.0.0",
    "tailwindcss": "^4.0.0",
    "typescript": "^5.5.0"
  }
}
```

- [ ] **Step 2: Create `apps/web/tsconfig.json`**

```json
{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["dom", "dom.iterable", "ES2022"],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "jsx": "preserve",
    "incremental": true,
    "noEmit": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": false,
    "plugins": [{ "name": "next" }],
    "paths": {
      "@/*": ["./src/*"]
    }
  },
  "include": ["next-env.d.ts", ".next/types/**/*.ts", "src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules"]
}
```

- [ ] **Step 3: Create `apps/web/next.config.ts`**

```typescript
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  reactStrictMode: true,
  // Standalone output for the production Docker image
  output: "standalone",
  // Trust the workspace packages so Drizzle/luxon don't break in RSC
  transpilePackages: ["@cmbot/db", "@cmbot/shared"],
  experimental: {
    typedRoutes: true,
  },
};

export default nextConfig;
```

- [ ] **Step 4: Create `apps/web/postcss.config.mjs`**

```javascript
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
```

- [ ] **Step 5: Create `apps/web/src/app/globals.css`**

```css
@import "tailwindcss";

@theme {
  --font-sans: "Geist", system-ui, sans-serif;
}

:root {
  color-scheme: light dark;
}

body {
  @apply bg-background text-foreground;
}
```

- [ ] **Step 6: Create `apps/web/src/app/layout.tsx`**

```typescript
import type { Metadata, Viewport } from "next";
import { GeistSans } from "geist/font/sans";
import "./globals.css";

export const metadata: Metadata = {
  title: "cm WhatsApp Bot",
  description: "Self-hosted WhatsApp reminder bot",
  applicationName: "cm WhatsApp Bot",
  appleWebApp: {
    capable: true,
    title: "cm WA Bot",
    statusBarStyle: "default",
  },
};

export const viewport: Viewport = {
  themeColor: [
    { media: "(prefers-color-scheme: light)", color: "#ffffff" },
    { media: "(prefers-color-scheme: dark)", color: "#0a0a0a" },
  ],
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={GeistSans.className}>
      <body>{children}</body>
    </html>
  );
}
```

- [ ] **Step 7: Create `apps/web/src/app/page.tsx`**

```typescript
export default function Page() {
  return (
    <main className="p-8">
      <h1 className="text-2xl font-semibold">cm WhatsApp Bot</h1>
      <p className="text-muted-foreground">
        Web app skeleton — wired up. Real dashboard arrives in Task 13.
      </p>
    </main>
  );
}
```

- [ ] **Step 8: Create `apps/web/src/env.ts`**

```typescript
import { z } from "zod";

const envSchema = z.object({
  DATABASE_URL: z.string().url(),
  DATA_DIR: z.string().min(1).default("/data"),
  MEDIA_DIR: z.string().min(1).default("/data/media"),
  WEB_PORT: z.string().regex(/^\d+$/).transform((s) => Number(s)).default("3000"),
});

export type Env = z.infer<typeof envSchema>;
export const env = envSchema.parse(process.env);
```

- [ ] **Step 9: Add `geist` dependency**

```bash
NO_SUDO=1 scripts/dev.sh pnpm add geist --filter @cmbot/web
```

- [ ] **Step 10: Install workspace deps**

```bash
NO_SUDO=1 scripts/dev.sh pnpm install
```

Expected: `next`, `react`, `tailwindcss` etc. all resolved.

- [ ] **Step 11: Commit**

```bash
git add apps/web pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "feat(web): scaffold Next.js 16 app with Tailwind 4 + Geist"
```

---

## Task 6: shadcn/ui setup + base components

**Files:**
- Create: `apps/web/components.json`
- Create: `apps/web/src/components/ui/` (populated by shadcn CLI)

- [ ] **Step 1: Create `apps/web/components.json`**

```json
{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "slate",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}
```

- [ ] **Step 2: Run shadcn init via the tools container**

```bash
NO_SUDO=1 scripts/dev.sh exec sh -c "cd apps/web && pnpm dlx shadcn@latest init --yes"
```

This creates `src/lib/utils.ts`, updates `globals.css` with shadcn theme tokens, and installs `tailwindcss-animate`, `class-variance-authority`, `clsx`, `tailwind-merge`, `lucide-react`.

- [ ] **Step 3: Install base shadcn components**

```bash
NO_SUDO=1 scripts/dev.sh exec sh -c "cd apps/web && pnpm dlx shadcn@latest add button card form input textarea label dialog sheet dropdown-menu sonner skeleton tabs badge separator avatar table --yes"
```

- [ ] **Step 4: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
```

- [ ] **Step 5: Commit**

```bash
git add apps/web pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "feat(web): shadcn/ui init + base components"
```

---

## Task 7: Drizzle client, operator helper, notify helper

**Files:**
- Create: `apps/web/src/lib/db.ts`
- Create: `apps/web/src/lib/operator.ts`
- Create: `apps/web/src/lib/notify.ts`
- Create: `apps/web/src/lib/logger.ts`

- [ ] **Step 1: Create `apps/web/src/lib/db.ts`**

```typescript
import "server-only";
import { createClient, type DB } from "@cmbot/db";
import { env } from "@/env";

const { db, pool } = createClient(env.DATABASE_URL);

export { db, pool };
export type { DB };
```

- [ ] **Step 2: Create `apps/web/src/lib/operator.ts`**

```typescript
import "server-only";
import { db } from "./db";

/**
 * Returns the single seeded operator row. Since the app has no auth,
 * every action is attributed to this operator.
 */
export async function getSeededOperator() {
  const op = await db.query.operators.findFirst({
    orderBy: (o, { asc }) => [asc(o.createdAt)],
  });
  if (!op) {
    throw new Error("No operator row seeded. Run scripts/db.sh seed.");
  }
  return op;
}
```

- [ ] **Step 3: Create `apps/web/src/lib/notify.ts`**

```typescript
import "server-only";
import { sql } from "drizzle-orm";
import { db } from "./db";

export type BotCommand =
  | { type: "account.start_pairing"; accountId: string }
  | { type: "account.unpair"; accountId: string }
  | { type: "account.sync_groups"; accountId: string }
  | { type: "group.send_test"; groupId: string; text: string };

export async function pgNotifyBot(cmd: BotCommand): Promise<void> {
  const json = JSON.stringify(cmd);
  await db.execute(sql`SELECT pg_notify('bot.command', ${json})`);
}
```

- [ ] **Step 4: Create `apps/web/src/lib/logger.ts`**

```typescript
import "server-only";
import pino from "pino";

export const logger = pino({
  level: process.env.NODE_ENV === "production" ? "info" : "debug",
  ...(process.env.NODE_ENV !== "production"
    ? { transport: { target: "pino-pretty", options: { colorize: true } } }
    : {}),
});
```

- [ ] **Step 5: Add `server-only` package**

```bash
NO_SUDO=1 scripts/dev.sh pnpm add server-only --filter @cmbot/web
```

- [ ] **Step 6: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
```

- [ ] **Step 7: Commit**

```bash
git add apps/web pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "feat(web): db client, operator helper, IPC notify, logger"
```

---

## Task 8: Web Dockerfile + compose service

**Files:**
- Replace: `docker/web.Dockerfile`
- Modify: `docker-compose.base.yml`
- Modify: `docker-compose.dev.yml`

- [ ] **Step 1: Replace `docker/web.Dockerfile`** with the multi-stage build

```dockerfile
FROM node:22-alpine AS base
RUN npm install -g pnpm@9.12.0
WORKDIR /app

FROM base AS deps
COPY package.json pnpm-workspace.yaml pnpm-lock.yaml ./
COPY apps/web/package.json apps/web/
COPY packages/db/package.json packages/db/
COPY packages/shared/package.json packages/shared/
RUN pnpm install --frozen-lockfile

FROM base AS build
COPY --from=deps /app/node_modules /app/node_modules
COPY --from=deps /app/apps/web/node_modules /app/apps/web/node_modules
COPY --from=deps /app/packages/db/node_modules /app/packages/db/node_modules
COPY --from=deps /app/packages/shared/node_modules /app/packages/shared/node_modules
COPY tsconfig.base.json turbo.json ./
COPY apps/web apps/web
COPY packages/db packages/db
COPY packages/shared packages/shared
RUN pnpm --filter @cmbot/shared build && \
    pnpm --filter @cmbot/db build && \
    pnpm --filter @cmbot/web build

FROM base AS runtime
ENV NODE_ENV=production
ENV PORT=3000
ENV HOSTNAME=0.0.0.0
COPY --from=build /app/apps/web/.next/standalone ./
COPY --from=build /app/apps/web/.next/static ./apps/web/.next/static
COPY --from=build /app/apps/web/public ./apps/web/public
EXPOSE 3000
CMD ["node", "apps/web/server.js"]
```

- [ ] **Step 2: Add `web` service to `docker-compose.base.yml`** (insert before `networks:` block)

```yaml
  web:
    build:
      context: .
      dockerfile: docker/web.Dockerfile
    image: cm-whatsapp-web:local
    container_name: cmbot-web
    restart: unless-stopped
    environment:
      DATABASE_URL: ${DATABASE_URL}
      DATA_DIR: ${DATA_DIR}
      MEDIA_DIR: ${MEDIA_DIR}
      WEB_PORT: ${WEB_PORT}
    networks:
      - cmbot
```

- [ ] **Step 3: Add web override to `docker-compose.dev.yml`**

```yaml
  web:
    build:
      context: .
      dockerfile: docker/web.Dockerfile
      target: build
    image: cm-whatsapp-web:dev
    container_name: cmbot-web
    user: "${HOST_UID:-1000}:${HOST_GID:-1000}"
    working_dir: /app
    command: ["pnpm", "--filter", "@cmbot/web", "dev"]
    restart: unless-stopped
    volumes:
      - .:/app
      - ./dev-data:/data
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      NODE_ENV: development
      DATABASE_URL: ${DATABASE_URL}
      DATA_DIR: ${DATA_DIR}
      MEDIA_DIR: ${MEDIA_DIR}
      WEB_PORT: ${WEB_PORT}
    depends_on:
      - tools
```

- [ ] **Step 4: Commit**

```bash
git add docker/web.Dockerfile docker-compose.base.yml docker-compose.dev.yml
git -c commit.gpgsign=false commit -m "chore: add web Dockerfile and dev compose service"
```

---

## Task 9: VERIFY web container serves the placeholder page

This task has no source changes — just brings up the new `web` service and confirms it works.

- [ ] **Step 1: Bring up the stack**

```bash
NO_SUDO=1 scripts/dev.sh up
```

Expected: tools, bot, and web all start. First-time web build pulls Next.js + React (1-2 min).

- [ ] **Step 2: Tail web logs**

```bash
docker compose --env-file .env.development -f docker-compose.base.yml -f docker-compose.dev.yml logs --tail=30 web
```

Expected: Next.js dev server logs, ending with `Ready in <ms>` and `Local:        http://localhost:3000`.

- [ ] **Step 3: curl the placeholder page**

```bash
curl -s http://localhost:3000 | grep -o "cm WhatsApp Bot"
```

Expected: `cm WhatsApp Bot` (one match — the H1).

(No commit — verification only.)

---

# Phase C — Foundation: layout, SSE, middleware

## Task 10: App shell layout (responsive nav)

**Files:**
- Create: `apps/web/src/components/app-shell.tsx`
- Create: `apps/web/src/components/theme-provider.tsx`
- Modify: `apps/web/src/app/layout.tsx`

This task uses the **frontend-design:frontend-design** skill — when you reach this task, dispatch frontend-design with the brief: "Build a responsive app shell for a self-hosted reminder dashboard. Mobile (<640px): top app bar with title + back button + bottom nav with 4 tabs (Dashboard 🏠, Accounts 📒, Reminders 📅, Settings ⚙). Desktop (≥640px): collapsible left sidebar with same nav. Use shadcn Sheet for mobile drawer if needed. Light + dark theme via CSS variables. Tabs: Dashboard `/`, Accounts `/accounts`, Reminders `/reminders`, Settings `/settings`."

- [ ] **Step 1: Use frontend-design to build `apps/web/src/components/app-shell.tsx` and `theme-provider.tsx`**

After the skill produces files, ensure they meet the requirements above. The shell should accept `children` as the main content area and render the active route name in the app bar.

- [ ] **Step 2: Wire shell into `apps/web/src/app/layout.tsx`**

```typescript
import type { Metadata, Viewport } from "next";
import { GeistSans } from "geist/font/sans";
import { ThemeProvider } from "@/components/theme-provider";
import { AppShell } from "@/components/app-shell";
import { Toaster } from "@/components/ui/sonner";
import "./globals.css";

export const metadata: Metadata = {
  title: "cm WhatsApp Bot",
  description: "Self-hosted WhatsApp reminder bot",
  applicationName: "cm WhatsApp Bot",
  appleWebApp: { capable: true, title: "cm WA Bot", statusBarStyle: "default" },
};

export const viewport: Viewport = {
  themeColor: [
    { media: "(prefers-color-scheme: light)", color: "#ffffff" },
    { media: "(prefers-color-scheme: dark)", color: "#0a0a0a" },
  ],
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning className={GeistSans.className}>
      <body>
        <ThemeProvider>
          <AppShell>{children}</AppShell>
          <Toaster richColors position="top-right" />
        </ThemeProvider>
      </body>
    </html>
  );
}
```

- [ ] **Step 3: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
```

- [ ] **Step 4: Commit**

```bash
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): app shell with responsive nav + theme provider"
```

---

## Task 11: SSE endpoint + useEvents hook

**Files:**
- Create: `apps/web/src/app/api/events/route.ts`
- Create: `apps/web/src/hooks/use-events.ts`

- [ ] **Step 1: Create `apps/web/src/app/api/events/route.ts`**

```typescript
import { NextRequest } from "next/server";
import { Client } from "pg";
import { env } from "@/env";
import { logger } from "@/lib/logger";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";

export async function GET(_req: NextRequest) {
  const stream = new ReadableStream({
    async start(controller) {
      const encoder = new TextEncoder();
      const client = new Client({ connectionString: env.DATABASE_URL });
      let closed = false;

      const send = (event: string, data: unknown) => {
        if (closed) return;
        try {
          controller.enqueue(
            encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`),
          );
        } catch (err) {
          logger.warn({ err }, "sse: enqueue failed");
        }
      };

      try {
        await client.connect();
        await client.query('LISTEN "web.event"');
      } catch (err) {
        logger.error({ err }, "sse: failed to start listener");
        controller.close();
        return;
      }

      client.on("notification", (msg) => {
        if (msg.channel !== "web.event" || !msg.payload) return;
        try {
          const parsed = JSON.parse(msg.payload) as { type: string };
          send(parsed.type, parsed);
        } catch (err) {
          logger.warn({ err, payload: msg.payload }, "sse: bad payload");
        }
      });

      client.on("error", (err) => {
        logger.error({ err }, "sse: pg client error");
      });

      // Keep-alive ping every 25 seconds
      const ping = setInterval(() => send("ping", { ts: Date.now() }), 25_000);

      // Initial hello
      send("hello", { ts: Date.now() });

      // Cleanup on client disconnect — wired via the abort signal below
      const cleanup = async () => {
        if (closed) return;
        closed = true;
        clearInterval(ping);
        try {
          await client.query('UNLISTEN "web.event"');
        } catch {
          // ignore
        }
        await client.end().catch(() => undefined);
        try {
          controller.close();
        } catch {
          // ignore
        }
      };

      // Tie cleanup to the request being aborted
      _req.signal.addEventListener("abort", () => void cleanup());
    },
  });

  return new Response(stream, {
    headers: {
      "Content-Type": "text/event-stream",
      "Cache-Control": "no-cache, no-transform",
      Connection: "keep-alive",
      "X-Accel-Buffering": "no",
    },
  });
}
```

- [ ] **Step 2: Create `apps/web/src/hooks/use-events.ts`**

```typescript
"use client";

import { useEffect } from "react";

export type WebEventMap = {
  hello: { ts: number };
  ping: { ts: number };
  "session.qr": { accountId: string; qrPng: string };
  "session.connected": { accountId: string; phoneNumber: string | null };
  "session.disconnected": { accountId: string };
  "session.timeout": { accountId: string };
  "groups.synced": { accountId: string; count: number };
  "reminder.fired": { reminderId: string; runId: string; status: string };
  "reminder.failed": { reminderId: string; error: string };
};

type Handlers = { [K in keyof WebEventMap]?: (data: WebEventMap[K]) => void };

export function useEvents(handlers: Handlers): void {
  useEffect(() => {
    const es = new EventSource("/api/events");
    const wired: { type: string; fn: (e: MessageEvent) => void }[] = [];
    for (const type of Object.keys(handlers) as (keyof WebEventMap)[]) {
      const h = handlers[type];
      if (!h) continue;
      const fn = (e: MessageEvent) => {
        try {
          (h as (data: unknown) => void)(JSON.parse(e.data));
        } catch {
          // ignore malformed
        }
      };
      es.addEventListener(type, fn);
      wired.push({ type, fn });
    }
    return () => {
      for (const { type, fn } of wired) {
        es.removeEventListener(type, fn);
      }
      es.close();
    };
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, []);
}
```

- [ ] **Step 3: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
```

- [ ] **Step 4: Verify the SSE endpoint streams hello + ping**

```bash
curl -N http://localhost:3000/api/events 2>&1 | head -8
```

Expected output (Ctrl-C to stop after a few lines):
```
event: hello
data: {"ts":1778...}

event: ping
data: {"ts":1778...}
```

- [ ] **Step 5: Commit**

```bash
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): SSE endpoint + useEvents hook"
```

---

## Task 12: Rate-limit middleware + /api/* deny rule

**Files:**
- Create: `apps/web/src/middleware.ts`

- [ ] **Step 1: Create `apps/web/src/middleware.ts`**

```typescript
import { NextRequest, NextResponse } from "next/server";

const WINDOW_MS = 10_000;
const MAX_REQUESTS = 30;

const buckets = new Map<string, { count: number; windowStart: number }>();

function isRateLimited(ip: string): boolean {
  const now = Date.now();
  const bucket = buckets.get(ip);
  if (!bucket || now - bucket.windowStart > WINDOW_MS) {
    buckets.set(ip, { count: 1, windowStart: now });
    return false;
  }
  bucket.count += 1;
  return bucket.count > MAX_REQUESTS;
}

export function middleware(req: NextRequest) {
  const path = req.nextUrl.pathname;

  // Block all /api/* except /api/events and /api/health
  if (path.startsWith("/api/") && path !== "/api/events" && path !== "/api/health") {
    return new NextResponse("Not Found", { status: 404 });
  }

  // Rate limit by source IP. SSE endpoints are exempt (long-lived connection).
  if (path === "/api/events") return NextResponse.next();
  const ip =
    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ??
    req.headers.get("x-real-ip") ??
    "unknown";
  if (isRateLimited(ip)) {
    return new NextResponse("Too Many Requests", { status: 429 });
  }

  return NextResponse.next();
}

export const config = {
  matcher: ["/((?!_next/static|_next/image|favicon.ico|icon-).*)"],
};
```

- [ ] **Step 2: Commit**

```bash
git add apps/web/src/middleware.ts
git -c commit.gpgsign=false commit -m "feat(web): rate-limit middleware + /api deny rule"
```

---

# Phase D — Read-only pages

## Task 13: Dashboard + accounts list + account detail (frontend-design)

**Files:**
- Modify: `apps/web/src/app/page.tsx` (dashboard)
- Create: `apps/web/src/app/accounts/page.tsx`
- Create: `apps/web/src/app/accounts/[id]/page.tsx`
- Create: `apps/web/src/components/account-status-badge.tsx`

This task uses the **frontend-design:frontend-design** skill.

- [ ] **Step 1: Define data fetchers** — create `apps/web/src/lib/queries.ts`

```typescript
import "server-only";
import { sql } from "drizzle-orm";
import { db } from "./db";

export async function getDashboardStats(operatorId: string) {
  const accounts = await db.query.whatsappAccounts.findMany({
    where: (a, { eq }) => eq(a.operatorId, operatorId),
  });
  const reminders = await db.query.reminders.findMany({
    where: (_, { sql: s }) => s`status = 'active'`,
  });
  const recentRuns = await db.execute(sql`
    SELECT rr.id, rr.status, rr.fired_at, r.name
    FROM reminder_runs rr
    JOIN reminders r ON r.id = rr.reminder_id
    JOIN whatsapp_accounts wa ON wa.id = r.account_id
    WHERE wa.operator_id = ${operatorId}
    ORDER BY rr.fired_at DESC
    LIMIT 10
  `);
  return {
    connectedAccounts: accounts.filter((a) => a.status === "connected").length,
    totalAccounts: accounts.length,
    activeReminders: reminders.length,
    recentRuns: recentRuns.rows as never[],
  };
}

export async function listAccounts(operatorId: string) {
  return db.query.whatsappAccounts.findMany({
    where: (a, { eq }) => eq(a.operatorId, operatorId),
    orderBy: (a, { asc }) => [asc(a.label)],
  });
}

export async function getAccount(operatorId: string, accountId: string) {
  return db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.id, accountId), eq(a.operatorId, operatorId)),
  });
}
```

- [ ] **Step 2: Use frontend-design to build the three pages**

Brief for the skill:
> Build three Server-Component pages for a self-hosted reminder dashboard:
>
> 1. **`/` (Dashboard)** — calls `getDashboardStats`. Render 3 stat cards (Accounts connected / Active reminders / Recent runs) and a Recent Activity table (last 10 reminder runs with status pills).
> 2. **`/accounts` (Accounts list)** — calls `listAccounts`. Header with "Pair New Account" button (links to `/accounts/new`). Each account is a Card with label + phone + status badge + "Open" link to detail.
> 3. **`/accounts/[id]` (Account detail)** — calls `getAccount`. Show label, phone, status, paired-at date, and three action links: "View Groups" (`/accounts/[id]/groups`), "Sync Groups Now" (server action to be added in Task 17), "Unpair" (server action — destructive button with confirm Dialog).
>
> Status badge component (`<AccountStatusBadge status={...} />`) is shared: colors green / amber / red / neutral.
>
> Use shadcn Card, Button, Dialog. Mobile-first, but use grid layouts on `sm:` breakpoint.

- [ ] **Step 3: Typecheck**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
```

- [ ] **Step 4: Browse manually**

Visit `http://localhost:3000/`, `http://localhost:3000/accounts`, `http://localhost:3000/accounts/<existing-id>`. Should render without errors and show your existing test account from the bot.

- [ ] **Step 5: Commit**

```bash
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): dashboard + accounts list + account detail"
```

---

## Task 14: Groups list + group detail pages (frontend-design)

**Files:**
- Create: `apps/web/src/app/accounts/[id]/groups/page.tsx`
- Create: `apps/web/src/app/groups/[id]/page.tsx`
- Add to: `apps/web/src/lib/queries.ts`

- [ ] **Step 1: Add queries** to `lib/queries.ts`

```typescript
export async function listGroupsForAccount(operatorId: string, accountId: string) {
  const account = await getAccount(operatorId, accountId);
  if (!account) return null;
  const groups = await db.query.whatsappGroups.findMany({
    where: (g, { eq }) => eq(g.accountId, accountId),
    orderBy: (g, { asc }) => [asc(g.name)],
  });
  return { account, groups };
}

export async function getGroup(operatorId: string, groupId: string) {
  const group = await db.query.whatsappGroups.findFirst({
    where: (g, { eq }) => eq(g.id, groupId),
  });
  if (!group) return null;
  const account = await getAccount(operatorId, group.accountId);
  if (!account) return null;
  return { group, account };
}
```

- [ ] **Step 2: Use frontend-design to build the two pages**

Brief:
> Two pages:
>
> 1. **`/accounts/[id]/groups`** — uses `listGroupsForAccount`. Search box at top filters group list client-side. Each group is a row with name + member count + chevron link to `/groups/[groupId]`. "Refresh" button next to header (server action stub for Task 17).
> 2. **`/groups/[id]`** — uses `getGroup`. Hero showing group name, member count, account label. Send-Test text area + "Send Test" button (server action in Task 18). Below: "Use this group in a reminder" link to `/reminders/new?groupId=...`.

- [ ] **Step 3: Typecheck + browse**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
```

- [ ] **Step 4: Commit**

```bash
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): groups list + group detail pages"
```

---

## Task 15: Reminders list + reminder detail (frontend-design)

**Files:**
- Create: `apps/web/src/app/reminders/page.tsx`
- Create: `apps/web/src/app/reminders/[id]/page.tsx`
- Add to: `apps/web/src/lib/queries.ts`

- [ ] **Step 1: Add queries** (re-export the existing crud helpers from bot's `reminders/crud.ts`? No — duplicate the bare query in the web's `queries.ts` instead, since the bot's helper imports `bot/db`):

Add to `apps/web/src/lib/queries.ts`:

```typescript
export async function listReminders(operatorId: string) {
  const rows = await db.execute(sql`
    SELECT r.*, wa.label as account_label,
      (SELECT count(*) FROM reminder_targets rt WHERE rt.reminder_id = r.id) as group_count
    FROM reminders r
    JOIN whatsapp_accounts wa ON wa.id = r.account_id
    WHERE wa.operator_id = ${operatorId}
    ORDER BY r.scheduled_at DESC NULLS LAST, r.created_at DESC
    LIMIT 100
  `);
  return rows.rows as never[];
}

export async function getReminderWithRuns(reminderId: string) {
  const reminder = await db.query.reminders.findFirst({
    where: (r, { eq }) => eq(r.id, reminderId),
  });
  if (!reminder) return null;
  const targets = await db.query.reminderTargets.findMany({
    where: (t, { eq }) => eq(t.reminderId, reminderId),
  });
  const messages = await db.query.reminderMessages.findMany({
    where: (m, { eq }) => eq(m.reminderId, reminderId),
    orderBy: (m, { asc }) => [asc(m.position)],
  });
  const runs = await db.query.reminderRuns.findMany({
    where: (rr, { eq }) => eq(rr.reminderId, reminderId),
    orderBy: (rr, { desc }) => [desc(rr.firedAt)],
    limit: 20,
  });
  return { reminder, targets, messages, runs };
}
```

- [ ] **Step 2: Use frontend-design to build the two pages**

Brief:
> Two pages for a reminder dashboard:
>
> 1. **`/reminders`** — uses `listReminders`. "New Reminder" button at top right links to `/reminders/new`. Table-style list (or cards on mobile) with columns: Name, Account, When (formatted in operator's timezone), Status (pill), Group count. Click row → detail.
> 2. **`/reminders/[id]`** — uses `getReminderWithRuns`. Hero with name + when + status. Body section showing message text or "(media)" placeholder. Targets list (group names). Run history table: fired_at, status, latency. "Delete" button (destructive, server action in Task 19).

- [ ] **Step 3: Typecheck + commit**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): reminders list + detail pages"
```

---

## Task 16: Settings page (frontend-design)

**Files:**
- Create: `apps/web/src/app/settings/page.tsx`

- [ ] **Step 1: Use frontend-design to build the page**

Brief:
> Settings page for a single-operator self-hosted dashboard:
> - Read-only display of operator: display name, telegram_user_id (legacy field, label "Operator ID" for clarity), default_timezone.
> - Theme toggle (light / dark / system) — wires to the existing ThemeProvider.
> - Build/version line at the bottom.
>
> No server action yet (editing comes later). Plain Server Component reading from `getSeededOperator()`.

- [ ] **Step 2: Typecheck + commit**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): settings page"
```

---

# Phase E — Mutations

## Task 17: Pair / unpair / sync-groups server actions

**Files:**
- Create: `apps/web/src/actions/accounts.ts`

- [ ] **Step 1: Create `apps/web/src/actions/accounts.ts`**

```typescript
"use server";

import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { z } from "zod";
import { eq } from "drizzle-orm";
import { whatsappAccounts } from "@cmbot/db";
import { db } from "@/lib/db";
import { getSeededOperator } from "@/lib/operator";
import { pgNotifyBot } from "@/lib/notify";

const pairSchema = z.object({
  label: z.string().min(1).max(60),
});

export async function pairAccountAction(_prev: unknown, formData: FormData) {
  const parsed = pairSchema.safeParse({ label: formData.get("label") });
  if (!parsed.success) {
    return { ok: false as const, error: parsed.error.issues[0]?.message ?? "Invalid label" };
  }
  const op = await getSeededOperator();

  // Reject if a connected account already has this label
  const existing = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.operatorId, op.id), eq(a.label, parsed.data.label)),
  });
  if (existing && existing.status === "connected") {
    return { ok: false as const, error: `"${parsed.data.label}" is already connected. Unpair first.` };
  }

  let accountId = existing?.id;
  if (!accountId) {
    const [created] = await db
      .insert(whatsappAccounts)
      .values({ operatorId: op.id, label: parsed.data.label, status: "pending" })
      .returning({ id: whatsappAccounts.id });
    accountId = created!.id;
  }

  await pgNotifyBot({ type: "account.start_pairing", accountId });
  revalidatePath("/accounts");
  redirect(`/accounts/${accountId}/pairing`);
}

export async function unpairAccountAction(accountId: string) {
  const op = await getSeededOperator();
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.id, accountId), eq(a.operatorId, op.id)),
  });
  if (!account) return { ok: false as const, error: "Not found" };
  await pgNotifyBot({ type: "account.unpair", accountId });
  // Optimistic UI update — actual state flip happens via SSE when bot finishes
  await db
    .update(whatsappAccounts)
    .set({ status: "logged_out", phoneNumber: null })
    .where(eq(whatsappAccounts.id, accountId));
  revalidatePath("/accounts");
  revalidatePath(`/accounts/${accountId}`);
  return { ok: true as const };
}

export async function syncGroupsAction(accountId: string) {
  const op = await getSeededOperator();
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.id, accountId), eq(a.operatorId, op.id)),
  });
  if (!account) return { ok: false as const, error: "Not found" };
  await pgNotifyBot({ type: "account.sync_groups", accountId });
  return { ok: true as const };
}
```

- [ ] **Step 2: Wire `pairAccountAction` into `/accounts/new` page** — create `apps/web/src/app/accounts/new/page.tsx`

Brief for **frontend-design**:
> Build the "Pair New Account" form. Single text field (Label, max 60 chars), submit button "Start Pairing", cancel link to `/accounts`. On submit, the form posts to `pairAccountAction`. On error, show field error. On success, the action redirects to `/accounts/[id]/pairing`. Use shadcn Form + react-hook-form + zod with the same `pairSchema`.

- [ ] **Step 3: Wire `unpairAccountAction` and `syncGroupsAction` into the account detail page**

Update `/accounts/[id]/page.tsx` — add an Unpair Dialog (with confirm) that posts to `unpairAccountAction`, and a Sync button that posts to `syncGroupsAction` and shows a toast.

- [ ] **Step 4: Build the live QR pairing page** — `apps/web/src/app/accounts/[id]/pairing/page.tsx`

Brief for **frontend-design**:
> Build the "Pair Account — Waiting for QR" page. Server Component reads the account row by id; renders a client island that:
> 1. Shows a QR placeholder shimmer.
> 2. Subscribes via `useEvents` to `session.qr` (replace shimmer with `<img src="data:image/png;base64,..." />`), `session.connected` (show success state + redirect to `/accounts/[id]` after 3s), `session.timeout` (show "Timed out" with "Try Again" button linking to `/accounts/new`).
> 3. Includes a 30-second countdown ring that resets on each new QR.
>
> Use shadcn Skeleton, Button, Card.

- [ ] **Step 5: Typecheck + commit**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): pair / unpair / sync-groups actions + live QR page"
```

---

## Task 18: Send-test action

**Files:**
- Create: `apps/web/src/actions/groups.ts`

- [ ] **Step 1: Create `apps/web/src/actions/groups.ts`**

```typescript
"use server";

import { z } from "zod";
import { eq, and } from "drizzle-orm";
import { whatsappAccounts } from "@cmbot/db";
import { db } from "@/lib/db";
import { getSeededOperator } from "@/lib/operator";
import { pgNotifyBot } from "@/lib/notify";

const sendTestSchema = z.object({
  groupId: z.string().uuid(),
  text: z.string().min(1).max(4000),
});

export async function sendTestAction(_prev: unknown, formData: FormData) {
  const parsed = sendTestSchema.safeParse({
    groupId: formData.get("groupId"),
    text: formData.get("text"),
  });
  if (!parsed.success) {
    return { ok: false as const, error: parsed.error.issues[0]?.message ?? "Invalid input" };
  }
  const op = await getSeededOperator();
  const group = await db.query.whatsappGroups.findFirst({
    where: (g, { eq }) => eq(g.id, parsed.data.groupId),
  });
  if (!group) return { ok: false as const, error: "Group not found" };
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.id, group.accountId), eq(a.operatorId, op.id)),
  });
  if (!account) return { ok: false as const, error: "Group not yours" };
  if (account.status !== "connected") {
    return { ok: false as const, error: "Account not connected" };
  }

  await pgNotifyBot({ type: "group.send_test", groupId: parsed.data.groupId, text: parsed.data.text });
  return { ok: true as const, message: `Sending to ${group.name}…` };
}
```

- [ ] **Step 2: Wire into `/groups/[id]/page.tsx`**

Already-built page (from Task 14) gains a form bound to `sendTestAction`. On success, show a toast "Sending to <group>…". On error, show a toast with the message.

- [ ] **Step 3: Typecheck + commit**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): send-test server action wired into group detail"
```

---

## Task 19: Reminder delete action

**Files:**
- Create: `apps/web/src/actions/reminders.ts` (just the delete piece for this task — create + edit come in Phase F)

- [ ] **Step 1: Create `apps/web/src/actions/reminders.ts`**

```typescript
"use server";

import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { eq } from "drizzle-orm";
import { reminders } from "@cmbot/db";
import { db } from "@/lib/db";
import { getSeededOperator } from "@/lib/operator";
import { writeAuditLog } from "@cmbot/shared/audit"; // see note below

export async function deleteReminderAction(reminderId: string) {
  const op = await getSeededOperator();
  const reminder = await db.query.reminders.findFirst({
    where: (r, { eq }) => eq(r.id, reminderId),
  });
  if (!reminder) return { ok: false as const, error: "Not found" };
  // Verify operator owns the reminder via the account's operator_id
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.id, reminder.accountId), eq(a.operatorId, op.id)),
  });
  if (!account) return { ok: false as const, error: "Not yours" };

  await db.delete(reminders).where(eq(reminders.id, reminderId));
  revalidatePath("/reminders");
  redirect("/reminders");
}
```

NOTE: `@cmbot/shared/audit` doesn't exist — `writeAuditLog` lives in `apps/bot/src/audit.ts` and we don't want to share it (web → bot module). Drop the import; the audit_log row is written by the bot's IPC handler when it processes commands. For pure-DB deletes (like this one) skip audit logging in v1 — easy to add later by porting `writeAuditLog` to `packages/shared` if needed.

Replace the import line and the (now unused) reference in the action with: just delete the reminder. The pg-boss job for that reminder will fire and find the row gone (soft cancel from plan 2).

- [ ] **Step 2: Final action body**

```typescript
"use server";

import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { eq } from "drizzle-orm";
import { reminders } from "@cmbot/db";
import { db } from "@/lib/db";
import { getSeededOperator } from "@/lib/operator";

export async function deleteReminderAction(reminderId: string) {
  const op = await getSeededOperator();
  const reminder = await db.query.reminders.findFirst({
    where: (r, { eq }) => eq(r.id, reminderId),
  });
  if (!reminder) return { ok: false as const, error: "Not found" };
  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.id, reminder.accountId), eq(a.operatorId, op.id)),
  });
  if (!account) return { ok: false as const, error: "Not yours" };

  await db.delete(reminders).where(eq(reminders.id, reminderId));
  revalidatePath("/reminders");
  redirect("/reminders");
}
```

- [ ] **Step 3: Wire into `/reminders/[id]/page.tsx`** — Delete button → confirm Dialog → server action.

- [ ] **Step 4: Typecheck + commit**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): delete reminder action + UI"
```

---

# Phase F — Reminder wizard

## Task 20: Reminder create action + media upload action

**Files:**
- Modify: `apps/web/src/actions/reminders.ts` (add createReminderAction)
- Create: `apps/web/src/actions/media.ts`

- [ ] **Step 1: Add `createReminderAction` to `apps/web/src/actions/reminders.ts`**

```typescript
import { reminderTargets, reminderMessages } from "@cmbot/db";
import { z } from "zod";
import { DateTime } from "luxon";
import PgBoss from "pg-boss";
import { env } from "@/env";
import { DEFAULT_TIMEZONE } from "@cmbot/shared";

const createReminderSchema = z.object({
  accountId: z.string().uuid(),
  groupIds: z.array(z.string().uuid()).min(1),
  text: z.string().nullable().optional(),
  mediaId: z.string().uuid().nullable().optional(),
  caption: z.string().nullable().optional(),
  scheduledAtIso: z.string().datetime(),
  timezone: z.string().default(DEFAULT_TIMEZONE),
});

export async function createReminderAction(input: z.infer<typeof createReminderSchema>) {
  const op = await getSeededOperator();
  const parsed = createReminderSchema.safeParse(input);
  if (!parsed.success) {
    return { ok: false as const, error: parsed.error.issues[0]?.message ?? "Invalid input" };
  }
  const { accountId, groupIds, text, mediaId, caption, scheduledAtIso, timezone } = parsed.data;

  const account = await db.query.whatsappAccounts.findFirst({
    where: (a, { eq, and }) => and(eq(a.id, accountId), eq(a.operatorId, op.id)),
  });
  if (!account) return { ok: false as const, error: "Account not yours" };

  const scheduledAt = DateTime.fromISO(scheduledAtIso, { zone: timezone }).toJSDate();
  if (scheduledAt.getTime() <= Date.now()) {
    return { ok: false as const, error: "Time is in the past" };
  }

  const reminderId = await db.transaction(async (tx) => {
    const [rem] = await tx
      .insert(reminders)
      .values({
        accountId,
        name: (text ?? caption ?? "Reminder").slice(0, 50),
        scheduleKind: "one_off",
        scheduledAt,
        timezone,
        status: "active",
        createdBy: op.id,
      })
      .returning({ id: reminders.id });

    await tx.insert(reminderTargets).values(
      groupIds.map((groupId, position) => ({ reminderId: rem!.id, groupId, position })),
    );

    if (text && !mediaId) {
      await tx.insert(reminderMessages).values({
        reminderId: rem!.id,
        position: 0,
        kind: "text",
        textContent: text,
        mediaId: null,
      });
    } else if (mediaId) {
      await tx.insert(reminderMessages).values({
        reminderId: rem!.id,
        position: 0,
        kind: "media",
        textContent: caption ?? text ?? null,
        mediaId,
      });
    }
    return rem!.id;
  });

  // Schedule via pg-boss directly from web. We don't go through the bot
  // because pg-boss reads its own queue table; the bot's worker picks up.
  const boss = new PgBoss({ connectionString: env.DATABASE_URL, schema: "pgboss" });
  await boss.start();
  await boss.send(
    "reminder.fire",
    { reminderId },
    {
      startAfter: scheduledAt,
      retryLimit: 3,
      retryDelay: 30,
      retryBackoff: true,
      singletonKey: `reminder:${reminderId}`,
    },
  );
  await boss.stop({ graceful: false });

  revalidatePath("/reminders");
  return { ok: true as const, reminderId };
}
```

NOTE: Using `pg-boss` from web means an extra connection per create. Alternative: send a `bot.command` like `reminder.schedule` and let the bot do the pg-boss send. That's cleaner — let me change to that approach.

- [ ] **Step 2: Switch to IPC-based scheduling**

Replace the pg-boss block in `createReminderAction` with:

```typescript
import { pgNotifyBot } from "@/lib/notify";

// (instead of pg-boss start + send + stop)
await pgNotifyBot({ type: "reminder.schedule", reminderId, scheduledAtIso });
```

And add `reminder.schedule` to the `BotCommand` union in **both** `apps/web/src/lib/notify.ts` and `apps/bot/src/ipc/command-consumer.ts`.

- [ ] **Step 3: Add a bot handler for `reminder.schedule`**

Create `apps/bot/src/ipc/schedule-reminder-handler.ts`:

```typescript
import { getBoss } from "../scheduler/pgboss-client.js";
import { scheduleReminderFire } from "../scheduler/reminder-jobs.js";

export async function handleScheduleReminder(reminderId: string, scheduledAtIso: string): Promise<void> {
  await scheduleReminderFire(getBoss(), reminderId, new Date(scheduledAtIso));
}
```

Register in `apps/bot/src/ipc/command-consumer.ts` `registerDefaultHandlers()`:

```typescript
registerHandler("reminder.schedule", async (cmd) => {
  await handleScheduleReminder(cmd.reminderId, cmd.scheduledAtIso);
});
```

- [ ] **Step 4: Create `apps/web/src/actions/media.ts`**

```typescript
"use server";

import { mkdir, writeFile } from "node:fs/promises";
import { dirname } from "node:path";
import { createHash } from "node:crypto";
import { mediaFiles } from "@cmbot/db";
import { newMediaPath, absoluteMediaPath } from "@cmbot/shared";
import { db } from "@/lib/db";
import { env } from "@/env";
import { getSeededOperator } from "@/lib/operator";

const MAX_BYTES = 50 * 1024 * 1024;

export async function uploadMediaAction(formData: FormData) {
  const file = formData.get("file");
  if (!(file instanceof File)) return { ok: false as const, error: "No file" };
  if (file.size > MAX_BYTES) return { ok: false as const, error: "File too large (>50MB)" };
  const op = await getSeededOperator();

  const buffer = Buffer.from(await file.arrayBuffer());
  const sha256 = createHash("sha256").update(buffer).digest("hex");
  const storagePath = newMediaPath(file.name);
  const absolute = absoluteMediaPath(storagePath, env.MEDIA_DIR);
  await mkdir(dirname(absolute), { recursive: true });
  await writeFile(absolute, buffer);

  const [row] = await db
    .insert(mediaFiles)
    .values({
      operatorId: op.id,
      filenameOriginal: file.name,
      mimeType: file.type || "application/octet-stream",
      sizeBytes: buffer.byteLength,
      sha256,
      storagePath,
    })
    .returning({ id: mediaFiles.id });

  return { ok: true as const, mediaId: row!.id, filename: file.name, mimeType: file.type };
}
```

- [ ] **Step 5: Typecheck + commit**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/bot typecheck
git add apps/web/src apps/bot/src
git -c commit.gpgsign=false commit -m "feat(web,bot): create-reminder + media-upload + reminder.schedule IPC"
```

---

## Task 21: Reminder wizard UI (5 steps with URL state)

**Files:**
- Create: `apps/web/src/app/reminders/new/page.tsx` (URL-state dispatcher)
- Create: `apps/web/src/components/reminder-wizard/` (step components)

This task uses **frontend-design:frontend-design**.

- [ ] **Step 1: Use frontend-design with this brief**

> Build a 5-step reminder wizard at `/reminders/new`. URL state via `?step=1..5&accountId=...&groupIds=a,b&text=...&mediaId=...&scheduledAt=...`. Each step is a Server Component that:
>
> - **Step 1 — Account.** List paired accounts as cards (radio-style). On select, navigate to `/reminders/new?step=2&accountId=...`.
> - **Step 2 — Groups.** Fetch groups for the chosen account. Multi-select with search. "Continue" button → step 3 with `&groupIds=` comma-joined.
> - **Step 3 — Compose.** Textarea for body, drag-drop file upload (calls `uploadMediaAction`), thumbnail preview with remove button. "Continue" → step 4 (preserve text + mediaId in URL).
> - **Step 4 — When.** `<input type="datetime-local">` defaulting to "now + 1 hour". Quick-pick chips: Now, Tomorrow 9 AM, Next Mon 9 AM. "Continue" → step 5 with `&scheduledAt=...`.
> - **Step 5 — Review.** Summary card with all chosen values + "Edit account / groups / body / time" links back to those steps. "Schedule" button posts to `createReminderAction` and redirects to `/reminders/[id]`.
>
> Visual: stepper progress at the top showing "1 — Account · 2 — Groups · 3 — Compose · 4 — When · 5 — Review" with the current step highlighted. Use shadcn Form, Card, Button, Input, Textarea, Badge.

- [ ] **Step 2: Typecheck + commit**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web typecheck
git add apps/web/src
git -c commit.gpgsign=false commit -m "feat(web): reminder wizard (5 steps with URL state)"
```

---

# Phase G — PWA

## Task 22: @serwist/next setup + manifest + icons

**Files:**
- Create: `apps/web/src/app/manifest.webmanifest/route.ts`
- Create: `apps/web/src/pwa/sw.ts`
- Modify: `apps/web/next.config.ts`
- Add icon files: `apps/web/public/icon-192.png`, `apps/web/public/icon-512.png`, `apps/web/public/apple-touch-icon.png`

- [ ] **Step 1: Install serwist**

```bash
NO_SUDO=1 scripts/dev.sh pnpm add @serwist/next serwist --filter @cmbot/web
```

- [ ] **Step 2: Create `apps/web/src/app/manifest.webmanifest/route.ts`**

```typescript
import { NextResponse } from "next/server";

export function GET() {
  return NextResponse.json({
    name: "cm WhatsApp Bot",
    short_name: "cm WA Bot",
    description: "Self-hosted WhatsApp reminder bot",
    start_url: "/",
    display: "standalone",
    background_color: "#0a0a0a",
    theme_color: "#0a0a0a",
    icons: [
      { src: "/icon-192.png", sizes: "192x192", type: "image/png", purpose: "any maskable" },
      { src: "/icon-512.png", sizes: "512x512", type: "image/png", purpose: "any maskable" },
    ],
  });
}
```

- [ ] **Step 3: Create `apps/web/src/pwa/sw.ts`**

```typescript
import { defaultCache } from "@serwist/next/worker";
import { Serwist } from "serwist";

declare const self: ServiceWorkerGlobalScope & {
  __SW_MANIFEST: (string | { url: string; revision: string | null })[];
};

const serwist = new Serwist({
  precacheEntries: self.__SW_MANIFEST,
  skipWaiting: true,
  clientsClaim: true,
  navigationPreload: true,
  runtimeCaching: defaultCache,
});

serwist.addEventListeners();
```

- [ ] **Step 4: Wire serwist into `apps/web/next.config.ts`**

Replace contents:

```typescript
import type { NextConfig } from "next";
import withSerwistInit from "@serwist/next";

const withSerwist = withSerwistInit({
  swSrc: "src/pwa/sw.ts",
  swDest: "public/sw.js",
  cacheOnNavigation: true,
  reloadOnOnline: true,
  disable: process.env.NODE_ENV !== "production",
});

const nextConfig: NextConfig = {
  reactStrictMode: true,
  output: "standalone",
  transpilePackages: ["@cmbot/db", "@cmbot/shared"],
  experimental: { typedRoutes: true },
};

export default withSerwist(nextConfig);
```

- [ ] **Step 5: Generate icons** (you may use any PNG generator or design tool — for now, generate simple placeholder PNGs using imagemagick inside the tools container)

```bash
NO_SUDO=1 scripts/dev.sh exec sh -c "
apk add --no-cache imagemagick >/dev/null 2>&1 || true
# Tools container is alpine — imagemagick may not be available. Skip if it errors.
convert -size 512x512 xc:'#0a0a0a' -fill white -gravity center -pointsize 280 -annotate 0 'cm' /workspace/apps/web/public/icon-512.png 2>/dev/null && echo 'icon-512 generated' || echo 'imagemagick unavailable; create icons manually'
convert /workspace/apps/web/public/icon-512.png -resize 192x192 /workspace/apps/web/public/icon-192.png 2>/dev/null
convert /workspace/apps/web/public/icon-512.png -resize 180x180 /workspace/apps/web/public/apple-touch-icon.png 2>/dev/null
"
```

Fallback if imagemagick isn't there: drop in any 512×512 and 192×192 PNG you have. Branding can come later.

- [ ] **Step 6: Build the production bundle to verify serwist hooks correctly**

```bash
NO_SUDO=1 scripts/dev.sh pnpm --filter @cmbot/web build
```

Expected: `[Serwist] Service worker generated at .../public/sw.js`. No errors.

- [ ] **Step 7: Commit**

```bash
git add apps/web pnpm-lock.yaml
git -c commit.gpgsign=false commit -m "feat(web): PWA via @serwist/next + manifest + icons"
```

---

# Phase H — Verify + push

## Task 23: Manual end-to-end runbook + execution

**Files:**
- Create: `docs/superpowers/specs/manual-test-web.md`

- [ ] **Step 1: Create `docs/superpowers/specs/manual-test-web.md`**

```markdown
# Manual test: Web app end-to-end

Run after every major web change.

## Prerequisites
- `scripts/dev.sh up` is running.
- Browser open on `http://localhost:3000`.

## Smoke
1. Visit `/` — see dashboard with stat cards. No errors in browser console.
2. Visit `/accounts` — see existing paired accounts.
3. Tap "Pair New Account" → form → enter "Web Test 1" → "Start Pairing".
4. Should redirect to `/accounts/<id>/pairing`. Within ~5s see a QR.
5. Scan with WhatsApp on a test phone.
6. See "✅ Connected as +60xxx" + auto-redirect to account detail.
7. Visit `/accounts/<id>/groups` — see groups.
8. Tap a group → see detail, send a test message → toast "Sending…".
9. WhatsApp should receive the message in ~5s.

## Reminder
1. `/reminders` → "New Reminder".
2. Step 1 — pick account, Step 2 — pick a group, Step 3 — type "Test", Step 4 — Now, Step 5 — Schedule.
3. Within ~30s, message arrives in WhatsApp group.
4. `/reminders/<id>` shows status `ended` and one run row in history.

## PWA install
1. Phone Chrome → menu → Install App.
2. Open from home screen — fullscreen, no browser chrome.

## Sign-off
- [ ] All steps passed
- [ ] No console errors
- [ ] Tester / date
```

- [ ] **Step 2: Run the runbook** end-to-end against your dev environment.

- [ ] **Step 3: Commit**

```bash
git add docs/superpowers/specs/manual-test-web.md
git -c commit.gpgsign=false commit -m "docs: manual web app end-to-end test runbook"
```

---

## Task 24: README update + push

**Files:**
- Modify: `README.md`

- [ ] **Step 1: Update `README.md`** — replace status section to reflect web-first.

Find the "Status" section and replace with:

```markdown
## Status

**Plans 1, 2, and 3 complete.** Web app at `wabot.04080616.xyz` is the primary control surface. Telegram bot has been fully removed.

What's working today:

- Self-hosted Next.js 16 PWA (installable on phone home screen).
- Pair WhatsApp accounts with live QR shown directly in the browser.
- Browse paired accounts and their groups; send test messages.
- Schedule one-off reminders via 5-step wizard with multi-group targets and media attachments.
- Auto-reconnect on transient drops; restart-survival via Baileys session persistence.
- All actions audited; reminder run history queryable from the UI.
```

- [ ] **Step 2: Push to Gitea**

```bash
git add README.md
git -c commit.gpgsign=false commit -m "docs: update README for web-first pivot"
git push origin master
```

Expected: push succeeds.

---

## Plan 3 done — what's working

- Telegram code fully removed; bot codebase shrunk by ~700 lines.
- Web app running at `wabot.04080616.xyz` with all daily-ops flows.
- Pair / groups / reminders / settings pages.
- Live QR pairing in-browser via SSE.
- Reminder wizard with media attachment.
- Server Actions for all mutations; no public REST API for state changes.
- PWA installable on phone.

## Deferred

- **Recurring reminders (RRULE)** — schema is ready; UI presets needed.
- **Standalone media library** browser.
- **Edit reminder** (only delete + recreate for now).
- **E2E browser tests** (Playwright).
- **Auth** (passkeys / email-password) — bring back if URL exposure becomes a concern.