From f5896aa575b0aac71917052d12038974f5e950a3 Mon Sep 17 00:00:00 2001
From: NeilClack <cnclack@pm.me>
Date: Thu, 16 Jul 2026 20:23:59 -0500
Subject: [PATCH] Update AGENTS.md

---
 AGENTS.md                   | 612 +++++++++++++++++++-----------------
 AGENTS.md.bak               | 363 +++++++++++++++++++++
 docs/ai/api.md              | 235 ++++++++++++++
 docs/ai/svelte-patterns.md  | 184 +++++++++++
 docs/ai/testing-patterns.md | 241 ++++++++++++++
 5 files changed, 1351 insertions(+), 284 deletions(-)
 create mode 100644 AGENTS.md.bak
 create mode 100644 docs/ai/api.md
 create mode 100644 docs/ai/svelte-patterns.md
 create mode 100644 docs/ai/testing-patterns.md

diff --git a/AGENTS.md b/AGENTS.md
index 4006341..45a22ca 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,363 +1,407 @@
-# portal.Rhemawavetech.com
+You're right — I gave you the optimized root content earlier, but I did not provide it cleanly as a single copy/paste artifact. Here it is.
 
-SvelteKit 2 + Svelte 5 (runes) + Tailwind CSS v4 + Prisma 7 + PostgreSQL + Better-Auth.
+Save this as:
 
-## Quick start
+```text
+AGENTS.md
+```
+
+at your project root:
+
+````text
+# Rhemawave Portal AI Guide
+
+## Mission
+
+You are working on portal.Rhemawavetech.com.
+
+Act as a senior engineer making complete, production-ready changes.
+
+Do not stop after analysis.
+Do not provide a plan and wait.
+Do not describe what should be done instead of doing it.
+
+When asked to make a change:
+
+1. Inspect the relevant code.
+2. Understand the existing implementation.
+3. Make the change.
+4. Validate the result.
+5. Fix any problems introduced.
+6. Report what changed and what was verified.
+
+A task is incomplete until the implementation is finished and verified.
+
+---
+
+# Working Style
+
+## Focused Context
+
+Do not load the entire repository into context.
+
+Use a focused approach:
+
+1. Identify relevant files.
+2. Read only necessary code.
+3. Find existing patterns.
+4. Make the smallest correct change.
+
+Avoid:
+- broad rewrites
+- unrelated cleanup
+- speculative refactors
+- introducing unnecessary dependencies
+
+Prefer:
+- small diffs
+- existing conventions
+- explicit implementations
+
+---
+
+# Development Loop
+
+Always follow this workflow:
+
+## 1. Understand
+
+Before editing:
+
+- Locate relevant files.
+- Inspect current behavior.
+- Find similar working examples.
+- Identify constraints.
+
+## 2. Implement
+
+Make the smallest correct change.
+
+Follow existing architecture.
+
+Do not replace working patterns with new abstractions unless required.
+
+## 3. Verify
+
+Run appropriate checks:
 
 ```sh
-npm install          # engine-strict=true in .npmrc
-npm run prepare      # svelte-kit sync (generate types)
-npm run dev          # vite dev on :5173
-```
+npm run check
+npm run lint
+npm run test
+````
 
-Requires `.env` with at least `DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`.
+Use narrower commands when appropriate.
 
-## Commands
+## 4. Complete
 
-| npm run ...                | What it does                                     |
-| -------------------------- | ------------------------------------------------ |
-| `check`                    | `svelte-kit sync && svelte-check` (typecheck)    |
-| `lint`                     | `prettier --check . && eslint .` (order matters) |
-| `format`                   | `prettier --write .`                             |
-| `test`                     | `vitest --run` (single run)                      |
-| `test:unit`                | `vitest` (watch mode)                            |
-| `migrate -- --name <name>` | Create a Prisma migration                        |
-| `deploy`                   | Apply pending migrations                         |
-| `build`                    | Production build (adapter-node)                  |
+If validation fails:
 
-## Testing quirks
+* Diagnose the failure.
+* Fix the issue.
+* Run validation again.
 
-- **Two Vitest projects**: `client` (Playwright/Chromium headless, `src/**/*.svelte.{test,spec}.{js,ts}`) and `server` (node env, everything else — `src/**/*.{test,spec}.{js,ts}` excluding `.svelte.*`). Tests co-located beside source files.
-- **`expect: { requireAssertions: true }`** — every test must assert something. No assertions = test fails.
-- **All route tests mock `$lib/db`** (Prisma client) and `$lib/auth-client`/`$lib/auth` via `vi.mock()`. Stub factories in `src/lib/test-utils.ts`.
-- **No `.env.test`** — mocking `$lib/db` makes real DB unnecessary.
-- **Mock `$app/forms`** for any component using `use:enhance` — provide `enhance: () => () => {}` (action → destroy fn).
-- **Mock TipTap** for client tests rendering ProclamationForm — the Svelte 5 component mock pattern is a function `($anchor: Element) => { …; $anchor.replaceWith(div); }`.
-
-## Architecture notes
-
-- **Route groups**: `(protected)/` requires auth + profile; `(user)/` is user-facing; `admin/` requires roleId <= 3 (STAFF+).
-- **Admin forms**: Each route has its own form component (e.g. `ProclamationForm.svelte`, `CategoryForm.svelte`). The generic `AdminForm.svelte` / `AdminPage.svelte` were **deleted**. Registry config (`registry.ts`) still provides metadata, list fields, search fields, relation options, etc., but forms are hand-written per route.
-- **Prisma client** generated to `src/lib/generated/prisma/` (not `node_modules/.prisma/client`). Lazy singleton via Proxy in `src/lib/db.ts`.
-- **Better-Auth** server instance in `src/lib/auth.ts`, browser client in `src/lib/auth-client.ts`. Session fetched in `src/hooks.server.ts`.
-- **Roles**: integer hierarchy (SUPER=1, ADMIN=2, STAFF=3, USER=4). `canAccessAdmin` checks roleId <= 3.
-- **Payments are stubbed** (`src/lib/payments.ts` — setTimeout + console.log).
-- **API keys**: SHA-256 hashed before storage (`ApiKey` model); only prefix (11 chars) stored for identification. `/api/v1/*` requires `Authorization: Bearer <key>`, except `/api/v1/automations/` (GHL webhook, no API key needed). Rotation: normal (48h grace via `expiresAt`) or emergency (immediate via `revokedAt`). Super-only admin page at `/admin/api-keys`.
-
-## Formatting conventions
-
-- Tabs, single quotes, no trailing commas, 100 print width (enforced by Prettier).
-- Svelte 5 runes only (`$state`, `$derived`, `$effect`, `$props`). No legacy stores (`writable`, `derived`, etc.).
+Never finish with known failures.
 
 ---
 
-## Svelte 5 Runes Gotchas & Patterns
+# Project Overview
 
-### `$state` initialization vs `$effect` sync
+Application:
 
-State variables declared with `$state('')` are set once on component mount. To keep them in sync with a changing `$props()` value, use a **separate `$effect`**:
+portal.Rhemawavetech.com
 
-```svelte
-<script lang="ts">
-	let { record = {} as Record<string, unknown> } = $props();
+Stack:
 
-	let name = $state('');
-	let freq = $state('');
+* SvelteKit 2
+* Svelte 5
+* TypeScript
+* Tailwind CSS v4
+* Prisma 7
+* PostgreSQL
+* Better Auth
+* Vitest
+* Playwright
 
-	// Sync local state when prop changes
-	$effect(() => {
-		name = String(record.name ?? '');
-		freq = String(record.solfeggioFrequencyId ?? '');
-	});
-</script>
+Package manager:
+
+npm
+
+---
+
+# Quick Start
+
+Install:
+
+```sh
+npm install
 ```
 
-This is the **only correct pattern** for form fields that edit an existing record. Do NOT initialize `$state` directly from the prop — that only captures the initial value and won't re-sync when the parent changes the record (e.g. switching from one row to another in a modal).
+Generate types:
 
-### `$effect` ordering matters
-
-Effects run in declaration order. If you have multiple effects, the first one's writes are applied before the second one runs. This matters for the `dirty` flag:
-
-```svelte
-let dirty = $state(false);
-
-// Runs first — resets dirty on mount / record change
-$effect(() => {
-	dirty = false;
-});
-
-// Runs second — syncs field values
-$effect(() => {
-	name = String(record.name ?? '');
-	// …
-});
+```sh
+npm run prepare
 ```
 
-Both effects run synchronously during mount, so by the time the browser paints, all state is consistent.
+Run development:
 
-### `bind:value` on `<select>` is broken with `$effect`-driven state
-
-**DO NOT USE** `bind:value={stateVar}` on `<select>` elements when the state is set from a `$effect`. Svelte 5's select binding does not respond to `$state` changes triggered inside `$effect`. Instead:
-
-**Use `selected` on `<option>` + `onchange` on `<select>`:**
-
-```svelte
-<select name="solfeggioFrequencyId" onchange={(e) => freq = (e.target as HTMLSelectElement).value}>
-	<option value="">-- Select --</option>
-	{#each options as opt (opt.value)}
-		<option value={opt.value} selected={String(opt.value) === freq}>{opt.label}</option>
-	{/each}
-</select>
+```sh
+npm run dev
 ```
 
-This pattern applies to ALL `<select>` elements in form components. The `value={stateVar}` prop directive also does not work reliably — always use `selected` on options.
+Required environment:
 
-### `bind:value` on `<input>` works fine
-
-Unlike `<select>`, `bind:value` on `<input type="text">` works correctly with `$effect`-driven state. Feel free to use it for text inputs.
-
-### `$props()` destructuring
-
-Always destructure `$props()` with defaults:
-
-```svelte
-let {
-	record = {} as Record<string, unknown>,
-	fieldErrors = {} as Record<string, string>,
-	isSuper = false,
-}: { record?: Record<string, unknown>; … } = $props();
-```
-
-The type annotation on the destructuring object is REQUIRED for Svelte 5 to infer prop types. Default values are used when the parent doesn't pass that prop.
-
-### Component mocking for client tests
-
-When mocking a Svelte 5 component in `vi.mock`, use a function that takes `($anchor, props)`:
-
-```ts
-vi.mock('$lib/components/tiptap/TipTap.svelte', () => ({
-	default: ($anchor: Element, _props: Record<string, unknown>) => {
-		const div = document.createElement('div');
-		div.setAttribute('data-testid', 'tiptap-mock');
-		$anchor.replaceWith(div);
-	}
-}));
+```text
+DATABASE_URL
+BETTER_AUTH_SECRET
+BETTER_AUTH_URL
 ```
 
 ---
 
-## Testing Patterns & Gotchas
+# Architecture Map
 
-### What tests to write
+## Routes
 
-For every admin route, write BOTH:
+Protected routes:
 
-1. **Server test** (`page.server.spec.ts`): Test the `load` function and all `actions` (upsert, delete). Cover role-based access control (Super vs non-Super content stripping, rejection of unauthorized mutations). Mock `$lib/db` and `$lib/svelte-admin/crud`.
-
-2. **Client test** (`Component.svelte.spec.ts`): Test the form component rendering in Playwright/Chromium. Cover:
-   - All fields render
-   - Pre-fill on edit (name input, select values)
-   - Conditional field visibility (e.g. content hidden for non-Super)
-   - Submit button disabled/enabled by dirty state
-   - No visual regression testing — only functional assertions.
-
-### Available Playwright/Vitest Browser Locator API
-
-These methods are available on `page` from `vitest/browser`:
-
-| Method              | Works? | Example                                       |
-| ------------------- | ------ | --------------------------------------------- |
-| `getByRole`         | ✅     | `page.getByRole('textbox', { name: 'Name' })` |
-| `getByText`         | ✅     | `page.getByText('Content')`                   |
-| `getByPlaceholder`  | ✅     | `page.getByPlaceholder('Email Address')`      |
-| `getByAltText`      | ✅     | `page.getByAltText('Sign In with Google')`    |
-| `getByTestId`       | ✅     | `page.getByTestId('tiptap-mock')`             |
-| `getByLabel`        | ❌     | Not available in this version                 |
-| `getByDisplayValue` | ❌     | Not available in this version                 |
-
-For label-identified elements, use `getByRole` with `name` option:
-
-- Text inputs → `getByRole('textbox', { name: /^Name$/ })`
-- Selects → `getByRole('combobox', { name: /^Frequency$/ })`
-- Buttons → `getByRole('button', { name: 'Save' })`
-
-**Always use regex `{ name: /^Exact$/ }`** for role queries to avoid strict-mode violations from substring matches (e.g. `'Category'` matching both `'Category'` and `'Sub-Category'`).
-
-### Querying select values in client tests
-
-Since `bind:value` on selects doesn't work with `$effect`-driven state, and we use `selected` on `<option>` instead, you can check the select's value directly:
-
-```ts
-const el = (await page
-	.getByRole('combobox', { name: /^Frequency$/ })
-	.element()) as HTMLSelectElement;
-expect(el.value).toBe('2');
+```text
+(protected)/
 ```
 
-The `.element()` call returns the underlying DOM element. This works synchronously because `selected` is set during render.
+Require authentication and profile.
 
-### Server test patterns
+User routes:
 
-**Always call `vi.clearAllMocks()` in `beforeEach`.**
-
-Mock `$lib/db` with the exact Prisma model methods the code under test uses:
-
-```ts
-vi.mock('$lib/db', () => ({
-	prisma: {
-		proclamation: {
-			findMany: vi.fn(),
-			findUnique: vi.fn(),
-			create: vi.fn(),
-			update: vi.fn(),
-			delete: vi.fn()
-		},
-		proclamationCategory: { findMany: vi.fn() }
-	}
-}));
+```text
+(user)/
 ```
 
-Mock `$lib/svelte-admin/crud` when the route uses custom upsert/delete logic:
+User-facing functionality.
 
-```ts
-vi.mock('$lib/svelte-admin/crud', () => ({
-	loadRecords: vi.fn(),
-	deleteRecord: vi.fn(),
-	superFormErrorsToFieldErrors: vi.fn(() => ({ error: '', fieldErrors: {} }))
-}));
+Admin routes:
+
+```text
+admin/
 ```
 
-Use `createLocals(mockUser({ roleId: 4 }) as any)` to simulate different user roles.
-Use `createFormRequest({ name: 'test' })` for form submissions.
-Use `.catch((e) => e)` + `isHttpError()` for error assertions.
+Require:
 
-### `createLocals` nuances
-
-- `createLocals()` (no arg) → unauthenticated (session is `undefined`).
-- `createLocals(mockUser() as any)` → authenticated with the mock user object.
-- Cast to `any` when passing to load/action functions: `{ locals: createLocals(mockUser()) } as any`.
-
-### `vi.mock` hoisting
-
-All `vi.mock()` calls must be at the top level of the test file. Values needed inside `vi.mock` factories must use `vi.hoisted()`:
-
-```ts
-const { mockFn } = vi.hoisted(() => ({ mockFn: vi.fn() }));
-vi.mock('$lib/some-module', () => ({ default: mockFn }));
+```text
+roleId <= 3
 ```
 
-Imports of the mocked module must come AFTER `vi.mock()` calls.
+Roles:
+
+```text
+SUPER = 1
+ADMIN = 2
+STAFF = 3
+USER = 4
+```
 
 ---
 
-## Admin Form Architecture
+# Database
 
-### Per-route form components
+Prisma generated client:
 
-Each admin route under `admin/[model]/` has its own form component (e.g. `ProclamationForm.svelte`). These components:
-
-- Receive `record`, `fieldErrors`, `formError`, `relationOptionsData`, and model-specific extras (e.g. `categories`, `isSuper`) as props.
-- Use `$state` + `$effect` for field values (see "Svelte 5 Runes Gotchas" above).
-- Use `selected` on `<option>` for selects.
-- Use `oninput` on the `<form>` to track dirty state: `<form oninput={markDirty}>`.
-- Submit via `action="?/upsert"` with SvelteKit's `use:enhance`.
-
-### Server actions
-
-Routes with custom requirements (like proclamation's Super-only restriction) override the generic `upsertRecord`/`deleteRecord` with their own actions. The generic functions in `crud.ts` are still available and used by simpler routes.
-
-### Super-only proclamation restriction
-
-- **Load**: content field is stripped from records for non-Super users before returning.
-- **Upsert**: returns `{ success: false, error: 'Only Super admins can edit proclamations' }` for non-Super.
-- **Delete**: same early return for non-Super; delegates to `deleteRecord` for Super.
-- **Content field in form**: wrapped in `{#if isSuper}` block — hidden from non-Super users.
-- **Row click / New button**: disabled for non-Super in `+page.svelte`.
-
-### Dirty-state submit pattern
-
-When editing an existing record (`record.id` is truthy), the submit button is disabled until the user modifies at least one field. The form tracks dirtiness with `let dirty = $state(false)` and a `markDirty()` handler:
-
-```svelte
-<form oninput={markDirty}>
-	<button disabled={!!record?.id && !dirty}>Save</button>
-</form>
+```text
+src/lib/generated/prisma/
 ```
 
-The `$effect` resets `dirty = false` on mount (when the record prop changes).
+Do not import Prisma from:
+
+```text
+node_modules/.prisma/client
+```
+
+Database singleton:
+
+```text
+src/lib/db.ts
+```
 
 ---
 
-## Generated / build artifacts
+# Authentication
 
-- `.svelte-kit/` — SvelteKit generated types (gitignored)
-- `src/lib/generated/prisma/` — Prisma client output (not gitignored; regenerate with `npx prisma generate`)
+Server:
+
+```text
+src/lib/auth.ts
+```
+
+Browser:
+
+```text
+src/lib/auth-client.ts
+```
+
+Session handling:
+
+```text
+src/hooks.server.ts
+```
 
 ---
 
-## API v1 Endpoints
+# Admin Architecture
 
-| Route                                | Method | Auth     | Description                                      |
-| ------------------------------------ | ------ | -------- | ------------------------------------------------ |
-| `/api/v1/categories`                | GET    | API key  | List all proclamation categories                 |
-| `/api/v1/frequencies`               | GET    | API key  | List all solfeggio frequencies                   |
-| `/api/v1/proclamations`             | GET    | API key  | List proclamations (with optional `?key` + `?email` filter) |
-| `/api/v1/license`                   | POST   | API key  | Validate key: `{ license_key, email_address }`     |
-| `/api/v1/automations/create/account` | POST  | None     | GHL webhook: create user + license key + emails   |
+Admin forms are route-specific.
 
-## GHL Webhook — Auto Account Creation
+Example:
 
-`POST /api/v1/automations/create/account` — excluded from API key auth in `hooks.server.ts`.
-
-**Payload:**
-
-```json
-{ "email": "...", "name": "...", "subscription_level": "Basic" }
+```text
+admin/[model]/
+  ModelForm.svelte
 ```
 
-`subscription_level` must match a `SubscriptionLevel.name` in the database.
+Do not recreate deleted generic components:
 
-**Flow:**
-1. If user email doesn't exist → `auth.api.signUpEmail()` with random temp password
-2. Query `Verification` table for the auto-generated verification token → construct verify URL
-3. Send `automated-user-registration` Resend template (variables: `firstName`, `tempPassword`, `verifyUrl`, `loginUrl`)
-4. Create `LicenseKey` record (`active: true`, `level: subscription_level`)
-5. Send `license-key-delivery` Resend template (variables: `firstName`, `license_key`)
-6. If user already exists → skip signup, just create key + send delivery email
+```text
+AdminForm.svelte
+AdminPage.svelte
+```
 
-**Better Auth email callbacks** (`sendVerificationEmail`, `sendResetPassword`) use `void` + `.catch()` — template send failures are logged, never crash the server.
+Registry metadata exists for:
 
-## Resend Email Templates
+* columns
+* searches
+* relations
 
-| Template ID                    | Variables                                                       | Subject (API-level)            |
-| ------------------------------ | --------------------------------------------------------------- | ------------------------------ |
-| `automated-user-registration`  | `firstName`, `tempPassword`, `verifyUrl`, `loginUrl`            | "Your account is ready"        |
-| `license-key-delivery`         | `firstName`, `license_key`                                      | "Your Rhemawave License Key"   |
-| `email-verification-email`     | `target_email_address`, `verification_link`                     | "Verify your email address"    |
+Forms are manually implemented per route.
 
-Variables must be declared in the Resend template editor's Variables section. Undeclared variables render as literal `{{{varName}}}` text.
+---
 
-Controlled by `src/lib/server/resend.ts` (`sendMail`) and `src/lib/server/email-verification.ts`.
+# Svelte Rules
 
-## AdminTable Drag-and-Drop
+This project uses Svelte 5 runes.
 
-AdminTable supports full-`<tr>` drag-and-drop reorder via props:
+Use:
 
-- `draggable: boolean` — enables drag handles on rows
-- `onReorder: (ids: string[]) => Promise<void>` — called after drop with new row ID order
-- `copyableFields: string[]` — field keys to show a copy-to-clipboard icon
+```text
+$state()
+$derived()
+$effect()
+$props()
+```
 
-**Pattern:** `$derived` + `dragOverride` — no `$effect` sync. `handleDragOver` always calls `preventDefault()` for reliable drop targets. `handleDrop` awaits `onReorder` then calls `invalidateAll()`.
+Do not use:
 
-See `src/lib/components/admin/AdminTable.svelte` and `src/routes/(protected)/admin/proclamation-categories/+page.svelte` for example usage.
+```text
+writable()
+derived()
+legacy stores
+```
 
-## License Key Admin
+For Svelte-specific patterns, read:
 
-- **Create**: `/admin/license-keys` form → `?/createKey` action. Requires email + subscription level. Generates key, persists to DB, emails the key via Resend template.
-- **Replace**: Table row action → `?/replace` action. Deletes old key, creates new one with same user + level. No email sent.
-- **Subscription level** stored as `SubscriptionLevel.name` string (not a FK).
+```text
+docs/ai/svelte-patterns.md
+```
+
+Only load that file when modifying Svelte components or Svelte logic.
+
+---
+
+# Testing Rules
+
+Testing uses:
+
+* Vitest
+* Playwright browser testing
+
+For testing patterns, read:
+
+```text
+docs/ai/testing-patterns.md
+```
+
+Only load that file when modifying tests.
+
+---
+
+# API Rules
+
+For API routes, authentication, keys, or integrations, read:
+
+```text
+docs/ai/api.md
+```
+
+Only load that file when working on API functionality.
+
+---
+
+# Formatting
+
+Prettier rules:
+
+* tabs
+* single quotes
+* no trailing commas
+* 80 character print width
+
+Follow existing formatting.
+
+---
+
+# Important Commands
+
+Check:
+
+```sh
+npm run check
+```
+
+Lint:
+
+```sh
+npm run lint
+```
+
+Format:
+
+```sh
+npm run format
+```
+
+Tests:
+
+```sh
+npm run test
+```
+
+Build:
+
+```sh
+npm run build
+```
+
+---
+
+# Completion Standard
+
+Before claiming a task is complete:
+
+Confirm:
+
+1. Code changes are implemented.
+2. Relevant tests/checks were run.
+3. Failures were fixed.
+4. The final response explains:
+
+   * what changed
+   * files modified
+   * verification performed
+
+Do not stop at:
+
+* "I found the issue"
+* "Here is a plan"
+* "The next step would be"
+
+Finish the work.
 
-## Key Generation
 
-- **License keys**: 16 uppercase hex chars in `XXXX-XXXX-XXXX-XXXX` format. `crypto.randomUUID()` → strip dashes → uppercase → 4x4 chunks. Level stored as `SubscriptionLevel.name` string (not FK).
-- **API keys**: `sk_` + 64 random hex chars. SHA-256 hashed for storage; first 11 chars stored as `keyPrefix` for identification.
diff --git a/AGENTS.md.bak b/AGENTS.md.bak
new file mode 100644
index 0000000..4006341
--- /dev/null
+++ b/AGENTS.md.bak
@@ -0,0 +1,363 @@
+# portal.Rhemawavetech.com
+
+SvelteKit 2 + Svelte 5 (runes) + Tailwind CSS v4 + Prisma 7 + PostgreSQL + Better-Auth.
+
+## Quick start
+
+```sh
+npm install          # engine-strict=true in .npmrc
+npm run prepare      # svelte-kit sync (generate types)
+npm run dev          # vite dev on :5173
+```
+
+Requires `.env` with at least `DATABASE_URL`, `BETTER_AUTH_SECRET`, `BETTER_AUTH_URL`.
+
+## Commands
+
+| npm run ...                | What it does                                     |
+| -------------------------- | ------------------------------------------------ |
+| `check`                    | `svelte-kit sync && svelte-check` (typecheck)    |
+| `lint`                     | `prettier --check . && eslint .` (order matters) |
+| `format`                   | `prettier --write .`                             |
+| `test`                     | `vitest --run` (single run)                      |
+| `test:unit`                | `vitest` (watch mode)                            |
+| `migrate -- --name <name>` | Create a Prisma migration                        |
+| `deploy`                   | Apply pending migrations                         |
+| `build`                    | Production build (adapter-node)                  |
+
+## Testing quirks
+
+- **Two Vitest projects**: `client` (Playwright/Chromium headless, `src/**/*.svelte.{test,spec}.{js,ts}`) and `server` (node env, everything else — `src/**/*.{test,spec}.{js,ts}` excluding `.svelte.*`). Tests co-located beside source files.
+- **`expect: { requireAssertions: true }`** — every test must assert something. No assertions = test fails.
+- **All route tests mock `$lib/db`** (Prisma client) and `$lib/auth-client`/`$lib/auth` via `vi.mock()`. Stub factories in `src/lib/test-utils.ts`.
+- **No `.env.test`** — mocking `$lib/db` makes real DB unnecessary.
+- **Mock `$app/forms`** for any component using `use:enhance` — provide `enhance: () => () => {}` (action → destroy fn).
+- **Mock TipTap** for client tests rendering ProclamationForm — the Svelte 5 component mock pattern is a function `($anchor: Element) => { …; $anchor.replaceWith(div); }`.
+
+## Architecture notes
+
+- **Route groups**: `(protected)/` requires auth + profile; `(user)/` is user-facing; `admin/` requires roleId <= 3 (STAFF+).
+- **Admin forms**: Each route has its own form component (e.g. `ProclamationForm.svelte`, `CategoryForm.svelte`). The generic `AdminForm.svelte` / `AdminPage.svelte` were **deleted**. Registry config (`registry.ts`) still provides metadata, list fields, search fields, relation options, etc., but forms are hand-written per route.
+- **Prisma client** generated to `src/lib/generated/prisma/` (not `node_modules/.prisma/client`). Lazy singleton via Proxy in `src/lib/db.ts`.
+- **Better-Auth** server instance in `src/lib/auth.ts`, browser client in `src/lib/auth-client.ts`. Session fetched in `src/hooks.server.ts`.
+- **Roles**: integer hierarchy (SUPER=1, ADMIN=2, STAFF=3, USER=4). `canAccessAdmin` checks roleId <= 3.
+- **Payments are stubbed** (`src/lib/payments.ts` — setTimeout + console.log).
+- **API keys**: SHA-256 hashed before storage (`ApiKey` model); only prefix (11 chars) stored for identification. `/api/v1/*` requires `Authorization: Bearer <key>`, except `/api/v1/automations/` (GHL webhook, no API key needed). Rotation: normal (48h grace via `expiresAt`) or emergency (immediate via `revokedAt`). Super-only admin page at `/admin/api-keys`.
+
+## Formatting conventions
+
+- Tabs, single quotes, no trailing commas, 100 print width (enforced by Prettier).
+- Svelte 5 runes only (`$state`, `$derived`, `$effect`, `$props`). No legacy stores (`writable`, `derived`, etc.).
+
+---
+
+## Svelte 5 Runes Gotchas & Patterns
+
+### `$state` initialization vs `$effect` sync
+
+State variables declared with `$state('')` are set once on component mount. To keep them in sync with a changing `$props()` value, use a **separate `$effect`**:
+
+```svelte
+<script lang="ts">
+	let { record = {} as Record<string, unknown> } = $props();
+
+	let name = $state('');
+	let freq = $state('');
+
+	// Sync local state when prop changes
+	$effect(() => {
+		name = String(record.name ?? '');
+		freq = String(record.solfeggioFrequencyId ?? '');
+	});
+</script>
+```
+
+This is the **only correct pattern** for form fields that edit an existing record. Do NOT initialize `$state` directly from the prop — that only captures the initial value and won't re-sync when the parent changes the record (e.g. switching from one row to another in a modal).
+
+### `$effect` ordering matters
+
+Effects run in declaration order. If you have multiple effects, the first one's writes are applied before the second one runs. This matters for the `dirty` flag:
+
+```svelte
+let dirty = $state(false);
+
+// Runs first — resets dirty on mount / record change
+$effect(() => {
+	dirty = false;
+});
+
+// Runs second — syncs field values
+$effect(() => {
+	name = String(record.name ?? '');
+	// …
+});
+```
+
+Both effects run synchronously during mount, so by the time the browser paints, all state is consistent.
+
+### `bind:value` on `<select>` is broken with `$effect`-driven state
+
+**DO NOT USE** `bind:value={stateVar}` on `<select>` elements when the state is set from a `$effect`. Svelte 5's select binding does not respond to `$state` changes triggered inside `$effect`. Instead:
+
+**Use `selected` on `<option>` + `onchange` on `<select>`:**
+
+```svelte
+<select name="solfeggioFrequencyId" onchange={(e) => freq = (e.target as HTMLSelectElement).value}>
+	<option value="">-- Select --</option>
+	{#each options as opt (opt.value)}
+		<option value={opt.value} selected={String(opt.value) === freq}>{opt.label}</option>
+	{/each}
+</select>
+```
+
+This pattern applies to ALL `<select>` elements in form components. The `value={stateVar}` prop directive also does not work reliably — always use `selected` on options.
+
+### `bind:value` on `<input>` works fine
+
+Unlike `<select>`, `bind:value` on `<input type="text">` works correctly with `$effect`-driven state. Feel free to use it for text inputs.
+
+### `$props()` destructuring
+
+Always destructure `$props()` with defaults:
+
+```svelte
+let {
+	record = {} as Record<string, unknown>,
+	fieldErrors = {} as Record<string, string>,
+	isSuper = false,
+}: { record?: Record<string, unknown>; … } = $props();
+```
+
+The type annotation on the destructuring object is REQUIRED for Svelte 5 to infer prop types. Default values are used when the parent doesn't pass that prop.
+
+### Component mocking for client tests
+
+When mocking a Svelte 5 component in `vi.mock`, use a function that takes `($anchor, props)`:
+
+```ts
+vi.mock('$lib/components/tiptap/TipTap.svelte', () => ({
+	default: ($anchor: Element, _props: Record<string, unknown>) => {
+		const div = document.createElement('div');
+		div.setAttribute('data-testid', 'tiptap-mock');
+		$anchor.replaceWith(div);
+	}
+}));
+```
+
+---
+
+## Testing Patterns & Gotchas
+
+### What tests to write
+
+For every admin route, write BOTH:
+
+1. **Server test** (`page.server.spec.ts`): Test the `load` function and all `actions` (upsert, delete). Cover role-based access control (Super vs non-Super content stripping, rejection of unauthorized mutations). Mock `$lib/db` and `$lib/svelte-admin/crud`.
+
+2. **Client test** (`Component.svelte.spec.ts`): Test the form component rendering in Playwright/Chromium. Cover:
+   - All fields render
+   - Pre-fill on edit (name input, select values)
+   - Conditional field visibility (e.g. content hidden for non-Super)
+   - Submit button disabled/enabled by dirty state
+   - No visual regression testing — only functional assertions.
+
+### Available Playwright/Vitest Browser Locator API
+
+These methods are available on `page` from `vitest/browser`:
+
+| Method              | Works? | Example                                       |
+| ------------------- | ------ | --------------------------------------------- |
+| `getByRole`         | ✅     | `page.getByRole('textbox', { name: 'Name' })` |
+| `getByText`         | ✅     | `page.getByText('Content')`                   |
+| `getByPlaceholder`  | ✅     | `page.getByPlaceholder('Email Address')`      |
+| `getByAltText`      | ✅     | `page.getByAltText('Sign In with Google')`    |
+| `getByTestId`       | ✅     | `page.getByTestId('tiptap-mock')`             |
+| `getByLabel`        | ❌     | Not available in this version                 |
+| `getByDisplayValue` | ❌     | Not available in this version                 |
+
+For label-identified elements, use `getByRole` with `name` option:
+
+- Text inputs → `getByRole('textbox', { name: /^Name$/ })`
+- Selects → `getByRole('combobox', { name: /^Frequency$/ })`
+- Buttons → `getByRole('button', { name: 'Save' })`
+
+**Always use regex `{ name: /^Exact$/ }`** for role queries to avoid strict-mode violations from substring matches (e.g. `'Category'` matching both `'Category'` and `'Sub-Category'`).
+
+### Querying select values in client tests
+
+Since `bind:value` on selects doesn't work with `$effect`-driven state, and we use `selected` on `<option>` instead, you can check the select's value directly:
+
+```ts
+const el = (await page
+	.getByRole('combobox', { name: /^Frequency$/ })
+	.element()) as HTMLSelectElement;
+expect(el.value).toBe('2');
+```
+
+The `.element()` call returns the underlying DOM element. This works synchronously because `selected` is set during render.
+
+### Server test patterns
+
+**Always call `vi.clearAllMocks()` in `beforeEach`.**
+
+Mock `$lib/db` with the exact Prisma model methods the code under test uses:
+
+```ts
+vi.mock('$lib/db', () => ({
+	prisma: {
+		proclamation: {
+			findMany: vi.fn(),
+			findUnique: vi.fn(),
+			create: vi.fn(),
+			update: vi.fn(),
+			delete: vi.fn()
+		},
+		proclamationCategory: { findMany: vi.fn() }
+	}
+}));
+```
+
+Mock `$lib/svelte-admin/crud` when the route uses custom upsert/delete logic:
+
+```ts
+vi.mock('$lib/svelte-admin/crud', () => ({
+	loadRecords: vi.fn(),
+	deleteRecord: vi.fn(),
+	superFormErrorsToFieldErrors: vi.fn(() => ({ error: '', fieldErrors: {} }))
+}));
+```
+
+Use `createLocals(mockUser({ roleId: 4 }) as any)` to simulate different user roles.
+Use `createFormRequest({ name: 'test' })` for form submissions.
+Use `.catch((e) => e)` + `isHttpError()` for error assertions.
+
+### `createLocals` nuances
+
+- `createLocals()` (no arg) → unauthenticated (session is `undefined`).
+- `createLocals(mockUser() as any)` → authenticated with the mock user object.
+- Cast to `any` when passing to load/action functions: `{ locals: createLocals(mockUser()) } as any`.
+
+### `vi.mock` hoisting
+
+All `vi.mock()` calls must be at the top level of the test file. Values needed inside `vi.mock` factories must use `vi.hoisted()`:
+
+```ts
+const { mockFn } = vi.hoisted(() => ({ mockFn: vi.fn() }));
+vi.mock('$lib/some-module', () => ({ default: mockFn }));
+```
+
+Imports of the mocked module must come AFTER `vi.mock()` calls.
+
+---
+
+## Admin Form Architecture
+
+### Per-route form components
+
+Each admin route under `admin/[model]/` has its own form component (e.g. `ProclamationForm.svelte`). These components:
+
+- Receive `record`, `fieldErrors`, `formError`, `relationOptionsData`, and model-specific extras (e.g. `categories`, `isSuper`) as props.
+- Use `$state` + `$effect` for field values (see "Svelte 5 Runes Gotchas" above).
+- Use `selected` on `<option>` for selects.
+- Use `oninput` on the `<form>` to track dirty state: `<form oninput={markDirty}>`.
+- Submit via `action="?/upsert"` with SvelteKit's `use:enhance`.
+
+### Server actions
+
+Routes with custom requirements (like proclamation's Super-only restriction) override the generic `upsertRecord`/`deleteRecord` with their own actions. The generic functions in `crud.ts` are still available and used by simpler routes.
+
+### Super-only proclamation restriction
+
+- **Load**: content field is stripped from records for non-Super users before returning.
+- **Upsert**: returns `{ success: false, error: 'Only Super admins can edit proclamations' }` for non-Super.
+- **Delete**: same early return for non-Super; delegates to `deleteRecord` for Super.
+- **Content field in form**: wrapped in `{#if isSuper}` block — hidden from non-Super users.
+- **Row click / New button**: disabled for non-Super in `+page.svelte`.
+
+### Dirty-state submit pattern
+
+When editing an existing record (`record.id` is truthy), the submit button is disabled until the user modifies at least one field. The form tracks dirtiness with `let dirty = $state(false)` and a `markDirty()` handler:
+
+```svelte
+<form oninput={markDirty}>
+	<button disabled={!!record?.id && !dirty}>Save</button>
+</form>
+```
+
+The `$effect` resets `dirty = false` on mount (when the record prop changes).
+
+---
+
+## Generated / build artifacts
+
+- `.svelte-kit/` — SvelteKit generated types (gitignored)
+- `src/lib/generated/prisma/` — Prisma client output (not gitignored; regenerate with `npx prisma generate`)
+
+---
+
+## API v1 Endpoints
+
+| Route                                | Method | Auth     | Description                                      |
+| ------------------------------------ | ------ | -------- | ------------------------------------------------ |
+| `/api/v1/categories`                | GET    | API key  | List all proclamation categories                 |
+| `/api/v1/frequencies`               | GET    | API key  | List all solfeggio frequencies                   |
+| `/api/v1/proclamations`             | GET    | API key  | List proclamations (with optional `?key` + `?email` filter) |
+| `/api/v1/license`                   | POST   | API key  | Validate key: `{ license_key, email_address }`     |
+| `/api/v1/automations/create/account` | POST  | None     | GHL webhook: create user + license key + emails   |
+
+## GHL Webhook — Auto Account Creation
+
+`POST /api/v1/automations/create/account` — excluded from API key auth in `hooks.server.ts`.
+
+**Payload:**
+
+```json
+{ "email": "...", "name": "...", "subscription_level": "Basic" }
+```
+
+`subscription_level` must match a `SubscriptionLevel.name` in the database.
+
+**Flow:**
+1. If user email doesn't exist → `auth.api.signUpEmail()` with random temp password
+2. Query `Verification` table for the auto-generated verification token → construct verify URL
+3. Send `automated-user-registration` Resend template (variables: `firstName`, `tempPassword`, `verifyUrl`, `loginUrl`)
+4. Create `LicenseKey` record (`active: true`, `level: subscription_level`)
+5. Send `license-key-delivery` Resend template (variables: `firstName`, `license_key`)
+6. If user already exists → skip signup, just create key + send delivery email
+
+**Better Auth email callbacks** (`sendVerificationEmail`, `sendResetPassword`) use `void` + `.catch()` — template send failures are logged, never crash the server.
+
+## Resend Email Templates
+
+| Template ID                    | Variables                                                       | Subject (API-level)            |
+| ------------------------------ | --------------------------------------------------------------- | ------------------------------ |
+| `automated-user-registration`  | `firstName`, `tempPassword`, `verifyUrl`, `loginUrl`            | "Your account is ready"        |
+| `license-key-delivery`         | `firstName`, `license_key`                                      | "Your Rhemawave License Key"   |
+| `email-verification-email`     | `target_email_address`, `verification_link`                     | "Verify your email address"    |
+
+Variables must be declared in the Resend template editor's Variables section. Undeclared variables render as literal `{{{varName}}}` text.
+
+Controlled by `src/lib/server/resend.ts` (`sendMail`) and `src/lib/server/email-verification.ts`.
+
+## AdminTable Drag-and-Drop
+
+AdminTable supports full-`<tr>` drag-and-drop reorder via props:
+
+- `draggable: boolean` — enables drag handles on rows
+- `onReorder: (ids: string[]) => Promise<void>` — called after drop with new row ID order
+- `copyableFields: string[]` — field keys to show a copy-to-clipboard icon
+
+**Pattern:** `$derived` + `dragOverride` — no `$effect` sync. `handleDragOver` always calls `preventDefault()` for reliable drop targets. `handleDrop` awaits `onReorder` then calls `invalidateAll()`.
+
+See `src/lib/components/admin/AdminTable.svelte` and `src/routes/(protected)/admin/proclamation-categories/+page.svelte` for example usage.
+
+## License Key Admin
+
+- **Create**: `/admin/license-keys` form → `?/createKey` action. Requires email + subscription level. Generates key, persists to DB, emails the key via Resend template.
+- **Replace**: Table row action → `?/replace` action. Deletes old key, creates new one with same user + level. No email sent.
+- **Subscription level** stored as `SubscriptionLevel.name` string (not a FK).
+
+## Key Generation
+
+- **License keys**: 16 uppercase hex chars in `XXXX-XXXX-XXXX-XXXX` format. `crypto.randomUUID()` → strip dashes → uppercase → 4x4 chunks. Level stored as `SubscriptionLevel.name` string (not FK).
+- **API keys**: `sk_` + 64 random hex chars. SHA-256 hashed for storage; first 11 chars stored as `keyPrefix` for identification.
diff --git a/docs/ai/api.md b/docs/ai/api.md
new file mode 100644
index 0000000..65ffc45
--- /dev/null
+++ b/docs/ai/api.md
@@ -0,0 +1,235 @@
+# API Documentation
+
+Only read this file when modifying API routes, authentication, keys, or integrations.
+
+---
+
+# API Location
+
+API routes:
+
+src/routes/api/v1/
+
+---
+
+# Authentication
+
+Most API endpoints require:
+
+Authorization: Bearer <API key>
+
+API keys are:
+
+- generated randomly
+- hashed with SHA-256 before storage
+- displayed using stored prefix only
+
+Never store plaintext API keys.
+
+---
+
+# API Key Lifecycle
+
+Normal rotation:
+
+- New key generated.
+- Old key remains valid for 48 hours.
+- Old key expires using expiresAt.
+
+Emergency rotation:
+
+- Old key immediately invalidated.
+- revokedAt is set.
+
+---
+
+# API Routes
+
+## Categories
+
+GET:
+
+/api/v1/categories
+
+Requires API key.
+
+---
+
+## Frequencies
+
+GET:
+
+/api/v1/frequencies
+
+Requires API key.
+
+---
+
+## Proclamations
+
+GET:
+
+/api/v1/proclamations
+
+Supports:
+
+- optional key filtering
+- optional email filtering
+
+Requires API key.
+
+---
+
+## License Validation
+
+POST:
+
+/api/v1/license
+
+Payload:
+
+{
+	"license_key": "...",
+	"email_address": "..."
+}
+
+Requires API key.
+
+---
+
+# GHL Account Creation Webhook
+
+Endpoint:
+
+POST /api/v1/automations/create/account
+
+This endpoint does NOT require an API key.
+
+It is used by GoHighLevel automation.
+
+---
+
+# Account Creation Flow
+
+When a request arrives:
+
+1. Check whether the email already exists.
+
+If user does not exist:
+
+2. Create user through Better Auth.
+3. Generate temporary password.
+4. Retrieve verification token.
+5. Build verification URL.
+6. Send registration email.
+
+Then:
+
+7. Create LicenseKey.
+8. Send license key delivery email.
+
+If user already exists:
+
+1. Skip signup.
+2. Create license key.
+3. Send delivery email.
+
+---
+
+# Email Templates
+
+Controlled by:
+
+src/lib/server/resend.ts
+
+Templates:
+
+automated-user-registration
+
+Variables:
+
+- firstName
+- tempPassword
+- verifyUrl
+- loginUrl
+
+
+license-key-delivery
+
+Variables:
+
+- firstName
+- license_key
+
+
+email-verification-email
+
+Variables:
+
+- target_email_address
+- verification_link
+
+---
+
+# Better Auth
+
+Server:
+
+src/lib/auth.ts
+
+Client:
+
+src/lib/auth-client.ts
+
+Email callbacks:
+
+- sendVerificationEmail
+- sendResetPassword
+
+Failures should:
+
+- log errors
+- not crash requests
+
+Use:
+
+void promise.catch()
+
+pattern.
+
+---
+
+# Security Rules
+
+Never:
+
+- expose plaintext API keys
+- bypass authorization checks
+- trust client role information
+- skip validation
+
+Always:
+
+- validate input
+- check permissions
+- preserve existing security patterns
+
+---
+
+# API Change Workflow
+
+Before modifying an endpoint:
+
+1. Read the route.
+2. Read related auth middleware.
+3. Read database models involved.
+4. Check existing tests.
+
+After modifying:
+
+Run:
+
+npm run check
+npm run test
+
+Fix failures before completing.
diff --git a/docs/ai/svelte-patterns.md b/docs/ai/svelte-patterns.md
new file mode 100644
index 0000000..8d8a5fc
--- /dev/null
+++ b/docs/ai/svelte-patterns.md
@@ -0,0 +1,184 @@
+# Svelte 5 Patterns and Rules
+
+This document contains Svelte-specific implementation rules.
+
+Only read this file when modifying Svelte components, routes, or Svelte-specific logic.
+
+---
+
+# Svelte Version
+
+This project uses:
+
+- SvelteKit 2
+- Svelte 5
+- runes mode
+
+Always use:
+
+- $state()
+- $derived()
+- $effect()
+- $props()
+
+Do not use legacy stores:
+
+- writable()
+- readable()
+- derived()
+
+---
+
+# Component Props
+
+Always destructure $props() with defaults.
+
+Preferred pattern:
+
+let {
+	record = {} as Record<string, unknown>,
+	fieldErrors = {} as Record<string, string>,
+	isSuper = false
+}: {
+	record?: Record<string, unknown>;
+	fieldErrors?: Record<string, string>;
+	isSuper?: boolean;
+} = $props();
+
+Do not assume props exist.
+
+---
+
+# State Synchronization
+
+IMPORTANT:
+
+Do not initialize $state from props when the prop can change.
+
+Incorrect:
+
+let name = $state(record.name);
+
+This only captures the initial value.
+
+Correct:
+
+let name = $state('');
+
+$effect(() => {
+	name = String(record.name ?? '');
+});
+
+Use $effect whenever component state needs to follow changing props.
+
+---
+
+# Effect Ordering
+
+$effect blocks execute in declaration order.
+
+When multiple effects modify related state:
+
+1. Reset state first.
+2. Populate state second.
+3. Perform dependent calculations afterward.
+
+Example:
+
+let dirty = $state(false);
+
+$effect(() => {
+	dirty = false;
+});
+
+$effect(() => {
+	name = String(record.name ?? '');
+});
+
+This ensures a new record starts clean.
+
+---
+
+# Select Inputs
+
+IMPORTANT:
+
+Do not use bind:value on select elements whose values are synchronized through $effect.
+
+Incorrect:
+
+<select bind:value={frequency}>
+	<option value="1">One</option>
+</select>
+
+This can fail to update correctly.
+
+Use:
+
+<select onchange={(e) => frequency = e.currentTarget.value}>
+	<option value="1" selected={frequency === '1'}>
+		One
+	</option>
+</select>
+
+Use selected on options.
+
+---
+
+# Input Elements
+
+Text inputs are different.
+
+This is acceptable:
+
+<input bind:value={name} />
+
+bind:value works correctly with normal input elements.
+
+---
+
+# Forms
+
+Admin forms use:
+
+- $state for field values
+- $effect for prop synchronization
+- oninput for dirty tracking
+- use:enhance for submission
+
+Example:
+
+<form oninput={markDirty}>
+	<button disabled={!!record?.id && !dirty}>
+		Save
+	</button>
+</form>
+
+---
+
+# Avoid Unnecessary State
+
+Prefer:
+
+$derived()
+
+for values computed from other state.
+
+Use:
+
+$state()
+
+only for values that change independently.
+
+---
+
+# Component Changes
+
+Before modifying a component:
+
+1. Read the entire component.
+2. Find similar components.
+3. Follow existing patterns.
+4. Avoid introducing new abstractions unless necessary.
+
+Small, consistent changes are preferred.
diff --git a/docs/ai/testing-patterns.md b/docs/ai/testing-patterns.md
new file mode 100644
index 0000000..42146b1
--- /dev/null
+++ b/docs/ai/testing-patterns.md
@@ -0,0 +1,241 @@
+# Testing Patterns
+
+Only read this file when creating or modifying tests.
+
+This project uses:
+
+- Vitest
+- Playwright browser testing
+- Svelte Testing Library patterns through vitest/browser
+
+---
+
+# Test Philosophy
+
+Tests should prove behavior.
+
+Do not write tests that only confirm implementation details.
+
+Every test must contain meaningful assertions.
+
+A test without assertions fails because:
+
+expect.requireAssertions is enabled.
+
+---
+
+# Test Locations
+
+Tests are colocated with source files.
+
+Client tests:
+
+*.svelte.test.ts
+*.svelte.spec.ts
+
+Server tests:
+
+*.test.ts
+*.spec.ts
+
+---
+
+# Vitest Projects
+
+There are two test environments.
+
+## Client
+
+Used for Svelte components.
+
+Environment:
+
+Playwright Chromium browser.
+
+Used for:
+
+- rendering
+- user interaction
+- form behavior
+
+---
+
+## Server
+
+Used for:
+
+- load functions
+- actions
+- server utilities
+
+Environment:
+
+Node.
+
+---
+
+# Before Each Test
+
+Always reset mocks:
+
+beforeEach(() => {
+	vi.clearAllMocks();
+});
+
+---
+
+# Server Tests
+
+Server route tests should cover:
+
+- authenticated behavior
+- unauthenticated behavior
+- authorization rules
+- successful operations
+- failed operations
+
+Mock:
+
+- $lib/db
+- authentication helpers
+- external services
+
+---
+
+# Prisma Mocking
+
+Mock only the methods used.
+
+Example:
+
+vi.mock('$lib/db', () => ({
+	prisma: {
+		proclamation: {
+			findMany: vi.fn(),
+			findUnique: vi.fn(),
+			create: vi.fn(),
+			update: vi.fn(),
+			delete: vi.fn()
+		}
+	}
+}));
+
+Do not create massive unused mocks.
+
+---
+
+# Authentication Testing
+
+Use:
+
+createLocals()
+
+Examples:
+
+Unauthenticated:
+
+createLocals()
+
+Authenticated:
+
+createLocals(mockUser() as any)
+
+Specific roles:
+
+createLocals(
+	mockUser({ roleId: 4 }) as any
+)
+
+---
+
+# Client Test Locators
+
+Available:
+
+getByRole
+getByText
+getByPlaceholder
+getByAltText
+getByTestId
+
+Unavailable:
+
+getByLabel
+getByDisplayValue
+
+---
+
+# Role Queries
+
+Always use exact regex names.
+
+Preferred:
+
+page.getByRole(
+	'textbox',
+	{ name: /^Name$/ }
+)
+
+Avoid:
+
+page.getByRole(
+	'textbox',
+	{ name: 'Name' }
+)
+
+because substring matching can create strict-mode failures.
+
+---
+
+# Select Testing
+
+Because selects use selected options instead of bind:value:
+
+const element =
+	await page
+		.getByRole(
+			'combobox',
+			{ name: /^Frequency$/ }
+		)
+		.element();
+
+expect(
+	(element as HTMLSelectElement).value
+).toBe('2');
+
+---
+
+# Svelte Component Mocking
+
+When mocking Svelte 5 components:
+
+Use:
+
+vi.mock('$lib/components/example.svelte', () => ({
+	default: ($anchor: Element) => {
+		const div = document.createElement('div');
+		$anchor.replaceWith(div);
+	}
+}));
+
+Imports using mocked modules must come after vi.mock().
+
+If variables are needed inside mocks:
+
+Use vi.hoisted().
+
+---
+
+# Test Completion Rule
+
+After writing tests:
+
+Run:
+
+npm run test
+
+If failures occur:
+
+Fix them.
+
+Do not report "tests added" without verifying they pass.