AI Product

# my-app

Generated by [Agentic Boilerplate](https://github.com/agentic-studio/agentic-boilerplate) from [Agentic Studio](https://theagentic.studio). Same `agentic.config.json`, same repo: regenerate and diff any time.

- **Stack:** Next.js on Vercel (`nextjs-vercel`)
- **Batteries:** Drizzle ORM (`drizzle`), Neon (`neon`), Better Auth (`better-auth`), Polar (`polar`), Resend (`resend`), Sentry (`sentry`), PostHog (`posthog`), AI bundle (`ai-bundle`), Admin panel (`admin-panel`)
- **Design:** Midnight (`midnight`). See [DESIGN.md](DESIGN.md).
- **Package manager:** bun
- **Mode:** solo
- **Agent targets:** claude

## Read this first

On a fresh clone, read [docs/onboard.md](docs/onboard.md) before running or
editing anything. It lists every environment variable, where to get it, and
the order to set the services up.

```sh
bun install
cp .env.example .env.local
bun run verify
bun run dev
```

## How this repo is set up for agents

- `.claude/rules/`: 30 rules. 4 load every session, 26 load when you read a file they cover.
- `.claude/agents/`: 7 subagents, listed below.
- `.claude/skills/`: 28 skills, listed below.
- `.claude/hooks/`: 7 guard hooks, wired in `.claude/settings.json` for Claude Code.
- `.mcp.json`: 5 MCP servers (`better-auth`, `neon`, `polar`, `posthog`, `sentry`). Setup is in [docs/onboard.md](docs/onboard.md).
- `docs/solutions/`: 75 solved problems. Read the relevant one before re-solving anything.
- `docs/plans/`: one plan per unit of work.

Run `bun run verify:hooks` to prove the guards still block what they claim to block.
Do not edit `.claude/settings.json` by hand: the `system-manager` agent owns it.

## Workflow

The Compound Engineering plugin adds the loop: `/ce-brainstorm`, `/ce-plan`, `/ce-work`, `/ce-code-review`, `/ce-compound`.
`.claude/settings.json` enables it once you trust this folder. If the commands are missing, run `/plugin install compound-engineering@compound-engineering-plugin`.

## Rules

Loaded every session:

- [Code style and file conventions](.claude/rules/code-style.md)
- [Git and change hygiene](.claude/rules/git.md)
- [Security rules](.claude/rules/security.md)
- [No personal data in breadcrumbs, tags or extra](.claude/rules/sentry-no-pii.md)

Loaded when you read a file they cover:

| Rule | Applies to |
|---|---|
| [Admin pages check the role themselves and read data on the server](.claude/rules/admin-access.md) | `src/app/(admin)/**`, `src/components/admin/**`, `src/lib/admin/actions.ts`, `src/app/api/admin/**` |
| [Admin writes go through the provider port, and every one is audited](.claude/rules/admin-mutations.md) | `src/lib/admin/**`, `src/components/admin/**`, `scripts/admin/**` |
| [Never interpolate untrusted text into a system prompt](.claude/rules/ai-prompt-safety.md) | `src/lib/ai/**`, `src/app/api/**` |
| [Model calls stay on the server, and they stream](.claude/rules/ai-server-boundary.md) | `src/lib/ai/**`, `src/app/api/chat/**`, `src/app/api/agent/**`, `src/components/ai/**`, `vercel.json` |
| [Every structured call carries a Zod schema](.claude/rules/ai-structured-output.md) | `src/lib/ai/**`, `src/app/api/**` |
| [Every tool validates its own input](.claude/rules/ai-tools.md) | `src/lib/ai/tools/**`, `src/lib/ai/agent.ts`, `src/app/api/agent/**` |
| [Pages in the signed-in app](.claude/rules/app-shell.md) | `src/app/(app)/**`, `src/components/app/**`, `src/components/ui/sidebar.tsx`, `src/lib/app-shell.ts`, `src/lib/nav.ts` |
| [The auth server boundary and sign-in methods](.claude/rules/auth-server-boundary.md) | `src/lib/auth/**`, `src/app/api/auth/**`, `src/app/(better-auth)/**`, `src/components/auth/**` |
| [Billing is one shared layer with one provider adapter](.claude/rules/billing-core.md) | `src/lib/pricing.ts`, `src/lib/billing/**`, `src/app/pricing/**`, `src/app/(app)/billing/**`, `src/components/billing/**` |
| [Deployment rules](.claude/rules/deployment.md) | `next.config.ts`, `vercel.json`, `package.json`, `src/proxy.ts`, `src/app/**/route.ts`, `.env.example` |
| [Every schema change ships with its generated migration](.claude/rules/drizzle-migrations.md) | `src/db/**`, `drizzle/**`, `drizzle.config.ts` |
| [Schema and query conventions for Drizzle](.claude/rules/drizzle-schema.md) | `src/db/**` |
| [Every email goes through sendEmail, from a verified domain, with a reply-to](.claude/rules/email-sending-discipline.md) | `src/lib/email/**`, `src/app/api/webhooks/resend/**`, `src/lib/auth/**`, `src/lib/billing/**` |
| [Events are declared in the catalogue, named object_verb, past tense](.claude/rules/event-naming.md) | `src/lib/analytics/**`, `src/app/**`, `src/components/**` |
| [Identify before the first event that matters, reset on sign-out](.claude/rules/identify-timing.md) | `src/lib/analytics/**`, `src/app/**`, `src/components/**` |
| [Landing page, legal pages and llms.txt](.claude/rules/landing-and-legal.md) | `src/lib/site.ts`, `src/lib/llms.ts`, `src/app/page.tsx`, `src/app/(legal)/**`, `src/app/llms.txt/**`, `src/components/marketing/**`, `src/components/site/**` |
| [One connection surface, and the right driver for the job](.claude/rules/neon-connections.md) | `src/db/**`, `src/app/api/**` |
| [Schema changes go through ORM migration files on the direct URL](.claude/rules/neon-migrations.md) | `src/db/**` |
| [Polar translates, the shared billing core writes the store](.claude/rules/polar-billing-adapter.md) | `src/lib/pricing.ts`, `src/lib/billing/**`, `scripts/billing/**` |
| [Verify every Polar webhook, keep every handler idempotent](.claude/rules/polar-webhook-integrity.md) | `src/app/api/webhooks/polar/**`, `src/lib/billing/provider.ts`, `src/lib/billing/polar-webhooks.ts`, `src/lib/billing/webhook.ts` |
| [Roles are decided on the server, every time](.claude/rules/roles-are-server-side.md) | `src/app/**`, `src/components/**`, `src/lib/auth/**` |
| [Every captured exception carries a stable fingerprint hint](.claude/rules/sentry-capture.md) | `src/**`, `sentry.server.config.ts`, `sentry.edge.config.ts` |
| [Server events for anything a client can lie about, and never PII in properties](.claude/rules/server-truth-and-pii.md) | `src/lib/analytics/**`, `src/app/**`, `src/components/**` |
| [Testing rules](.claude/rules/testing.md) | `tests/**`, `src/**/*.test.ts`, `src/**/*.test.tsx` |
| [Midnight: tokens only, and both modes every time](.claude/rules/tokens-only.md) | `src/components/**`, `src/app/**` |
| [Build UI from the component kit](.claude/rules/ui-kit.md) | `src/components/**`, `src/app/**` |

## Skills

| Skill | Use it for |
|---|---|
| `/add-admin-action` | Add an admin action (verify an email, reset a plan, delete an account) as a checked, validated, audited server action with a confirm dialog. |
| `/add-admin-page` | Add a page to /admin with the role check, a sidebar entry, loading and empty states, and data read through the admin ports. |
| `/add-app-page` | Add a page to the signed-in app (sidebar entry, session check, loading state), or a new tab under /settings. |
| `/add-email-template` | Add a React Email template, preview it, wire it into a send, and check it renders and lands in a real inbox. |
| `/add-event` | Add a product event end to end: catalogue entry, the question it answers, the capture call on the correct side of the network, and a check that it arrives. |
| `/add-oauth-provider` | Turn on Google, GitHub or Microsoft sign-in (env keys only), or add another OAuth provider to the list in src/lib/auth/providers.ts. |
| `/add-product` | Add or change a plan or price on Polar (monthly, yearly or one-time lifetime). Edit src/lib/pricing.ts, create the Polar product, wire its env var, and prove checkout and the webhook end to end. |
| `/add-table` | Add a table to the Drizzle schema, generate and apply its migration, and wire the typed queries for it. |
| `/add-tool` | Add a tool the model can call (schema, execute, registry entry, surface and a test) without widening what a stranger's sentence can reach. |
| `/ask-product` | Answer a question about user behaviour from this repo's event catalogue and the PostHog project, with the caveats that make the number usable. |
| `/db-branch` | Create, use, reset and delete Neon database branches, for a feature branch, a preview deploy, a migration rehearsal or a point-in-time investigation. |
| `/deploy-to-vercel` | Ship my-app to Vercel: local gates, environment variables per scope, preview verification, promotion and rollback. |
| `/edit-pricing` | Add, change or remove a plan or a price (monthly, yearly or one-time lifetime) and wire it to the payment provider. |
| `/eval-prompt` | Change a prompt, a model or a schema safely. Build the eval suite first, measure the baseline, change one thing, and compare pass rates. |
| `/help` | Explain the agentic system in this repo (rules, skills, agents, hooks, solution docs and the CE loop) and where to go for help beyond it. |
| `/landing-copy` | Rewrite the landing page, the metadata and the legal details for the real product from a short brief, by editing src/lib/site.ts only. |
| `/migrate` | Generate, review and apply Drizzle migrations safely, including backfills, destructive changes and the deploy step. |
| `/migrate-on-neon` | Run a schema migration against Neon safely, on the direct URL, rehearsed on a branch first, with a recovery path when it fails halfway. |
| `/new-component` | Add a component to the Midnight kit. Prefer pasting from shadcn/ui, fix the two bridge classes, keep it token-only and verify it in both light and dark. |
| `/preview-and-test-email` | Diagnose an email problem (not sending, landing in spam, rendering wrong) in the order that finds the cause fastest. |
| `/protect-route` | Put an authentication or role check on a page, a route handler, a server action or a whole route group, at the right layer, without a redirect loop. |
| `/qa-feature` | Exercise a feature end to end (happy path, unhappy paths, auth boundaries, refresh and mobile) before anyone calls it done. |
| `/scrub-pii` | Audit what this app actually sends to Sentry, extend the scrubbing layer for a new field or shape, and respond when something sensitive has already been sent. |
| `/security-audit` | Run the standing security pass through the security-auditor agent (secrets, auth boundaries, injection, dependencies and deploy config) and turn findings into fixes. |
| `/test-webhook` | Exercise the Polar webhook endpoint locally. Forward real sandbox events with the Polar CLI, or sign a one-time order yourself; buy both kinds of price, refund one, prove replays are no-ops, and debug signature failures. |
| `/triage-errors` | Work the Sentry issue list: rank by users affected, separate regressions from background noise, find the deploy that caused it, and fix or suppress with a reason. |
| `/verify` | Prove the repo is actually configured: every required env var present, every configured service reachable, and the guard hooks still blocking what they claim to block. |
| `/write-spec` | Turn a loose request into a written spec (problem, scope, behaviour, acceptance criteria) that /ce-plan can consume without guessing. |

## Subagents

| Agent | Use it for |
|---|---|
| `db-inspector` | Read-only Neon Postgres inspector. Explains schema, data shape and query plans. Runs SELECT and EXPLAIN only, and refuses every statement that writes or changes schema. |
| `designer` | Owns the Midnight design system and its shadcn bridge. The only agent allowed to introduce a new visual pattern or a new token. Refuses to ship a raw colour or a single-mode change. |
| `documentarian` | Keeps README, CLAUDE.md, DESIGN.md, docs/onboard.md and docs/solutions/ true to the code. Writes solution docs from work that just landed. |
| `pr-reviewer` | Reviews a diff against this repo's rules before it becomes a PR. Convention-aware, blocking on correctness and security, advisory on taste. |
| `product-analyst` | Read-only product analyst. Answers questions about user behaviour from the event catalogue and the PostHog project, and says plainly when the instrumentation cannot answer them. |
| `security-auditor` | Audits the repo or a diff for leaked secrets, broken auth boundaries, injection, unsafe dependencies and unsafe deploy configuration. |
| `system-manager` | Maintains the .claude agentic layer itself: rules, skills, agents, hooks, settings. Adds a rule when a correction repeats. |

## Credit

Generated by [Agentic Boilerplate](https://github.com/agentic-studio/agentic-boilerplate) from [Agentic Studio](https://theagentic.studio).

- [AI Mechanic](https://theagentic.studio/ai-mechanic): Fix a vibe-coded repo, then install this system into it.
- [Claude Engineering System](https://theagentic.studio/claude-engineering-system): The same agentic layer, installed into your existing codebase.
- [AI Product Sprint](https://theagentic.studio/ai-product-sprint): We build the MVP on top of a repo like this one.

---
paths:
  - src/app/(admin)/**
  - src/components/admin/**
  - src/lib/admin/actions.ts
  - src/app/api/admin/**
---

# Admin pages check the role themselves and read data on the server

## Three checks, each for a different question

| Where | Call | What it stops |
|---|---|---|
| `src/app/(admin)/layout.tsx` | `requireRole("admin", returnTo)` | A non-admin ever seeing the shell |
| Every `page.tsx` | `requireRole("admin", "/admin/<path>")` | A stale layout: layouts do not re-render on client navigation |
| Every server action | `authorise()` in `src/lib/admin/actions.ts` | Anyone with curl: an action is a public POST endpoint |

```tsx
export default async function AdminReportsPage() {
  await requireRole("admin", "/admin/reports");
  // load data, render
}
```

The page's call is free: each auth battery wraps its session read in React
`cache`. Pass the page's own path so sign-in brings the admin back to it.

Every export of `src/lib/admin/actions.ts` starts with `authorise()`, before it
reads a form field. It runs `requireRole("admin")`, then re-reads the admin
from the provider, because a role removed a minute ago can still sit in a
cached cookie (Better Auth, 5 minutes) or an unexpired token (Clerk, Supabase).
The one exception is `stopImpersonationAction`: the impersonated session is not
an admin session, so it checks `adminProvider.getImpersonation()` instead.

A route handler under `src/app/api/admin/**` uses `requireApiRole("admin")`
(401 or 403, never a redirect) and catches with `authErrorResponse`.

Never:

- rely on the proxy: `/admin/:path*` is in its matcher so signed-out visitors
  bounce early, but it has no role check worth trusting;
- compare strings (`user.role === "admin"` misses Clerk's `owner`): use
  `requireRole`, or `navItemsFor` for what the UI shows;
- move a page out of `src/app/(admin)/admin/`: it loses the shell and the
  layout's check, and nothing warns you;
- render the shell for a refused user: `requireRole` answers with a 404 or the
  auth battery's no-access page, and the chrome would tell an outsider the
  page exists.

## Pages load, components render

A page is a Server Component. It calls the read helpers (`listUsers`,
`getUser`, `getUserStats` from `@/lib/admin/users`, `listAuditEntries` from
`@/lib/admin/audit`) and passes results down. Load independent data with
`Promise.all`. A slow section goes in its own async component inside
`<Suspense>` with a skeleton, as `/admin` does for its counts.

Components under `src/components/admin/**` take props. Two kinds load their
own data because a slot cannot pass them any: `ImpersonationBanner` (the
`app-banner` fill) and the billing summary (`AdminBillingStats`,
`AdminBillingCard`). Do not add a third without the same reason.

## Keep data on the server

- Modules in `src/lib/admin/` that reach a provider open with
  `import "server-only"`: `users.ts`, `audit.ts`, `user-store.ts`,
  `provider.ts`, `audit-store.ts`. Client components import only the pure
  ones (`types.ts`, `policy.ts`, `format.ts`, `query.ts`, `cursor.ts`) and the
  `"use server"` actions.
- Pick fields for client components: `UserActions` gets
  `{ id, name, email, role, banned }`, never a database row.
- Never send a session token to the browser. The page sends a session id;
  `findSessionToken` turns it into a token on the server.
- Filters and cursors live in the URL, parsed by `parseUserQuery` and
  `parseAuditQuery`. A value that does not parse means "no filter", never an
  error page.

## Look like the rest of the app

Use the kit (`@/components/ui/*`), `PageHeader` and `EmptyState` from
`@/components/app/*`, and token classes (`bg-surface-card`, `text-muted`,
`border-hairline`). No palette classes, no hex, no `dark:` for colour: the
panel must read well in every design, light and dark.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/auto-lint.ts"
          },
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/enforce-doc-meta.ts"
          }
        ]
      },
      {
        "matcher": "Edit|Write|MultiEdit|Bash|Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/env-leak-detector-write.ts"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-destructive.ts"
          },
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/enforce-typecheck.ts"
          },
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/guard-neon-sql.ts"
          }
        ]
      },
      {
        "matcher": "Bash|Read|Grep",
        "hooks": [
          {
            "type": "command",
            "command": "bun \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/env-leak-detector.ts"
          }
        ]
      }
    ]
  },
  "extraKnownMarketplaces": {
    "compound-engineering-plugin": {
      "source": {
        "source": "github",
        "repo": "EveryInc/compound-engineering-plugin",
        "ref": "compound-engineering-v3.28.2"
      }
    }
  },
  "enabledPlugins": {
    "compound-engineering@compound-engineering-plugin": true
  }
}