# Admin Operations Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add complete moderation, logs, analytics, DevOps, and online-user administration verticals.

**Architecture:** Port each reference vertical independently, adapt its data access to EpicNext's Prisma/schema conventions, and enforce ACL at both route and mutation boundaries. Reuse shared admin components and semantic admin theme tokens.

**Tech Stack:** Next.js 16, React 19, TypeScript, Prisma/MariaDB, Vitest, RCON.

## Global Constraints

- Work directly on `main`; no worktree or subagents.
- Preserve and never stage the local `package.json` change.
- Do not copy generated Prisma code.
- Every page/action/API must use its documented ACL permission.
- Missing optional emulator tables render unavailable states instead of crashing the admin shell.

---

### Task 1: Define route, ACL, and theme contracts

**Files:**
- Create: `src/lib/admin-operations-contract.test.ts`

- [ ] Assert all moderation, log, analytics, DevOps, and online routes exist.
- [ ] Assert mutations and APIs contain the matching `PERMS` guard.
- [ ] Assert new sources contain no forbidden public structural theme tokens.
- [ ] Run the contract and confirm it fails because routes are absent.
- [ ] Commit with `test: define admin operations contracts`.

### Task 2: Moderation and calls for help

**Files:**
- Create: `src/actions/moderation.ts`
- Create: `src/app/admin/moderation/**`
- Modify: `src/app/admin/layout.tsx`

- [ ] Port moderation validation tests and confirm failure.
- [ ] Add dashboard, actions, CFH list/detail, and team pages.
- [ ] Adapt user/ban/CFH queries and protect reads/edits with moderation ACL.
- [ ] Log actions and separate RCON failures from database results.
- [ ] Run contract, moderation tests, and typecheck; commit `feat: add admin moderation operations`.

### Task 3: Detailed administration logs

**Files:**
- Create: `src/app/admin/logs/{audit,chat,commands,trades}/**`
- Modify: `src/app/admin/logs/page.tsx`

- [ ] Add failing route/filter contract coverage.
- [ ] Port paginated read-only tables using EpicNext log models or compatible raw queries.
- [ ] Protect every route with `admin.logs.view` and use semantic admin status colors.
- [ ] Run log tests and typecheck; commit `feat: add detailed admin logs`.

### Task 4: Analytics and export

**Files:**
- Create: `src/app/admin/analytics/**`
- Create: `src/app/api/admin/analytics/export/route.ts`

- [ ] Add failing ACL/export contract checks.
- [ ] Port overview, activity, and economy aggregates.
- [ ] Guard reads with `admin.analytics.view` and export with `admin.analytics.export`.
- [ ] Ensure export excludes secrets and fields absent from the visible tables.
- [ ] Run analytics contracts and typecheck; commit `feat: add admin analytics`.

### Task 5: DevOps health and online users

**Files:**
- Create: `src/app/admin/devops/**`
- Create: `src/app/api/admin/devops/health/route.ts`
- Create: `src/app/admin/online/**`

- [ ] Add failing route, redaction, and ACL checks.
- [ ] Port health/errors/online pages and adapt queries to EpicNext models.
- [ ] Redact credentials, connection strings, environment variables, and stack details from API responses.
- [ ] Guard DevOps with `admin.devops.view/edit` and online users with `admin.users.view`.
- [ ] Run contracts and typecheck; commit `feat: add devops and online operations`.

### Task 6: Verify and publish

- [ ] Run `git diff --check origin/main...HEAD`.
- [ ] Run `pnpm test`, `pnpm typecheck`, and `pnpm build`.
- [ ] Confirm only `package.json` remains modified.
- [ ] Fetch `origin/main`, verify it is an ancestor of `HEAD`, and push `main` without force.