Content Site

# 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`), Supabase (`supabase`), Clerk (`clerk`), Resend (`resend`), PostHog (`posthog`), Sanity blog (`blog-sanity`)
- **Design:** Paper (`paper`). 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/`: 22 rules. 3 load every session, 19 load when you read a file they cover.
- `.claude/agents/`: 6 subagents, listed below.
- `.claude/skills/`: 21 skills, listed below.
- `.claude/hooks/`: 6 guard hooks, wired in `.claude/settings.json` for Claude Code.
- `.mcp.json`: 2 MCP servers (`posthog`, `supabase`). Setup is in [docs/onboard.md](docs/onboard.md).
- `docs/solutions/`: 47 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)

Loaded when you read a file they cover:

| Rule | Applies to |
|---|---|
| [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` |
| [Authorise from the session, never from the client user object](.claude/rules/authorise-on-the-server.md) | `src/app/**`, `src/components/**`, `src/lib/auth/**` |
| [Clerk's components wear the design's tokens and only render inside the provider](.claude/rules/clerk-ui-follows-the-design.md) | `src/components/auth/**`, `src/lib/auth/appearance.ts`, `src/app/(auth)/**`, `src/components/site/header.tsx` |
| [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/**` |
| [Read tokens stay on the server, Portable Text uses design tokens](.claude/rules/sanity-runtime.md) | `src/app/(sanity)/**`, `src/app/studio/**`, `src/app/api/draft-mode/**`, `src/app/api/sanity/**`, `src/components/sanity/**`, `sanity/lib/**` |
| [The schema is code, and every GROQ query lives in one file](.claude/rules/sanity-schema.md) | `sanity/**`, `sanity.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/**` |
| [Row level security is on by default and the service role is a last resort](.claude/rules/supabase-db-access.md) | `src/db/**` |
| [Schema changes go through supabase/migrations, never the dashboard](.claude/rules/supabase-migrations.md) | `supabase/**` |
| [Testing rules](.claude/rules/testing.md) | `tests/**`, `src/**/*.test.ts`, `src/**/*.test.tsx` |
| [Paper: 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/**` |
| [The Clerk webhook verifies its signature before anything else](.claude/rules/verify-the-webhook-first.md) | `src/app/api/webhooks/clerk/**`, `src/lib/auth/user-sync.ts`, `src/lib/auth/user-store.ts`, `src/lib/auth/webhook-idempotency.ts` |

## Skills

| Skill | Use it for |
|---|---|
| `/add-app-page` | Add a page to the signed-in app (sidebar entry, session check, loading state), or a new tab under /settings. |
| `/add-clerk-role` | Add a role to the Clerk-backed role vocabulary, wire it into the session claim, gate a route with it, and assign it safely. |
| `/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-rls-policy` | Add or fix row level security policies on a Supabase table, with a migration, a policy test and regenerated types. |
| `/add-sanity-type` | Add or extend a Sanity document type end to end (schema, GROQ projection, result type, renderer and cache tags) so nothing renders blank. |
| `/add-table` | Add a table to the Drizzle schema, generate and apply its migration, and wire the typed queries for it. |
| `/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. |
| `/deploy-to-vercel` | Ship my-app to Vercel: local gates, environment variables per scope, preview verification, promotion and rollback. |
| `/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. |
| `/local-supabase` | Boot, reset, inspect and troubleshoot the local Supabase stack, and pull schema down from a hosted project. |
| `/migrate` | Generate, review and apply Drizzle migrations safely, including backfills, destructive changes and the deploy step. |
| `/new-component` | Add a component to the Paper 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. |
| `/preview-draft` | Set up or debug Sanity draft previews: the enable route, the secret, the banner, and why an editor is still seeing published content. |
| `/qa-feature` | Exercise a feature end to end (happy path, unhappy paths, auth boundaries, refresh and mobile) before anyone calls it done. |
| `/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. |
| `/sync-clerk-user` | Extend, backfill or re-verify the Clerk user mirror: the users table and ClerkSyncStore that this battery already ships. |
| `/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 |
|---|---|
| `designer` | Owns the Paper 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/**
  - src/components/**
  - src/lib/auth/**
---

# Authorise from the session, never from the client user object

## The client user object is display data

`useUser()`, `useAuth()`, `useOrganization()` and the `<Show>` component
(`<Show when="signed-in">`, `<Show when={{ role: "admin" }}>`; Clerk Core 3
replaced `<SignedIn>`, `<SignedOut>` and `<Protect>` with it) exist to render the
right UI. They read state the browser
holds, which the browser can edit. They decide what is *shown*. They never
decide what is *allowed*.

```tsx
// no — this is a visual hint being used as a control
const { user } = useUser();
if (user?.publicMetadata.role === "admin") {
  await fetch("/api/refunds", { method: "POST", body });
}
```

The route handler behind that call is what an attacker invokes, with curl,
without ever loading your page. It authorises itself:

```ts
const user = await requireApiRole("admin");   // from @/lib/auth/session
```

Hiding the button remains worth doing. It is the second step, not the only one.

## `unsafeMetadata` is never an input to a decision

Clerk gives you three metadata buckets:

| Bucket | Written by | Trust |
|---|---|---|
| `publicMetadata` | your backend only | authorisation input |
| `privateMetadata` | your backend only, never sent to the browser | authorisation input |
| `unsafeMetadata` | **the signed-in user, from the browser** | never |

`unsafeMetadata` is named that way for a reason: it is a scratchpad for user
preferences. Reading a role, an entitlement, a plan or a feature flag from it is
a self-service privilege escalation.

## Read the role through one helper

Every role check in this repo goes through `src/lib/auth/session.ts`, which
reads the `metadata` session claim first and falls back to the Backend API only
when it is absent. Do not re-implement it:

- No `auth().sessionClaims?.metadata?.role === "admin"` inline in a page.
- No `clerkClient().users.getUser(id)` in a component to look up a role.
- No role strings outside `src/lib/auth/roles.ts`.

One helper means one place to fix when the claim shape changes, and one place a
security review has to read.

There are two ways in, and the difference is a network call:

| Helper | Answers | Cost |
|---|---|---|
| `getSessionClaims()` / `requireApiClaims()` | `id`, `role`, `orgId`, `impersonatedBy` | the token only |
| `getSessionUser()` / `requireUser()` / `requireRole()` | the whole `SessionUser`, including `email` and `name` | one Backend API call, cached per request |

Clerk's token does not carry the email address, so a helper that promises one
has to fetch it. Guards that only decide yes-or-no should take the cheap path;
anything that renders or emails the person takes the other. Both resolve the
role identically, so neither is more or less trustworthy than the other.

## Never take identity from the request

The user id comes from the session, never from the body, the query string or a
header:

```ts
// no
const { userId } = await request.json();
await deleteAccount(userId);

// yes
const { id } = await requireApiUser();
await deleteAccount(id);
```

When an action legitimately targets *another* user (an admin banning someone)
the target id may come from the request, but only after the actor has been
authorised for that action.

## `auth()` needs the proxy

`auth()` throws if `clerkMiddleware` did not run for the request. That is why
`clerkProxy` from `src/lib/auth/proxy.ts` is a step in `src/proxy.ts`, and why
the matcher there must cover every route that reads a session. A route that
"randomly" throws an auth error is almost always a route the matcher does not
reach.

The proxy is not the authorisation boundary either. It redirects signed-out
visitors early; the page, handler or action still checks the role. A page
under `src/app/(app)/` calls `requireUser(path)` itself: a layout does not
re-run on client navigation.

Before the Clerk keys are set, `clerkIsConfigured()` is false, the proxy skips
Clerk, and every helper answers "signed out". Keep that path working: never
call `auth()` or a Clerk hook without going through those helpers or
`clerkProviderMounted()`.

## Impersonated sessions change nothing on the account

An administrator can sign in as someone from the Clerk dashboard. The token's
`act` claim then names the administrator, and `SessionUser.impersonatedBy`
carries its `sub` (null otherwise, and null for an AI agent actor). While it is
set, the settings pages are read-only summaries. Any new action that changes a
password, an email, a sign-in method or a payment method checks
`impersonatedBy` on the server and refuses, and anything it does write names
both ids in the log.

Never render `<UserProfile />`, `<UserButton />` or `<OrganizationProfile />`
for an actor session: Clerk does not document hiding their forms for one. And never tell an
operator Clerk itself makes the session read-only. Clerk documents no such
lock, and the browser can call Clerk's Frontend API directly, so the app's
lock stops mistakes, not an admin who goes around it (see
`docs/solutions/clerk/clerk-impersonation-and-the-act-claim.md`).

## Server-only imports

`CLERK_SECRET_KEY` and everything that reads it stay on the server.
`src/lib/auth/session.ts` starts with `import "server-only"` so an accidental
import from a client component is a build error rather than a leaked key.

{
  "$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"
          }
        ]
      },
      {
        "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
  }
}