> ## Documentation Index
> Fetch the complete documentation index at: https://fit4lifecare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Admin Runbooks

> Operational procedures for maintainers: seeding the database, seeding bot golden exemplars safely, isolated testing on the mirror, and how the bot actually improves.

Procedures a maintainer runs by hand. Each one has a sharp edge, read the warnings.

## Seed / migrate the database

```
POST /api/admin/db-setup
```

Gated, idempotent. Applies the additive schema and upserts customers/orders from `real-data.ts` (with the Oren-phone override).

<Warning>
  The full `db-setup` does `ON CONFLICT DO UPDATE` on customers/orders, running it on prod **reverts manual OS edits**. Never run it on prod just to seed something. `real-data.ts` remains the seed source, so a full reseed is the only "official" repopulate, with this caveat.
</Warning>

## Seed only the bot golden exemplars

```
POST /api/admin/db-setup?examplesOnly=1
```

Seeds **only** the `bot_conversations` golden rows (retires obsolete exemplar ids, then upserts the current set), it does not touch customers/orders.

<Warning>
  This route has proven **unreliable for actually persisting** the menu exemplars to prod (it has reported a count without writing the rows). The dependable path is a **direct write to prod `neondb` via the Neon MCP `run_sql`**, replicating `seedBotExamples`' row shape (`phone_key='seed'`, `golden=true`, `topics text[]`, `transcript` via `jsonb_build_*`, idempotent `ON CONFLICT (id) DO UPDATE`). Note: `run_sql` rejects multiple statements per call. After seeding, verify `SELECT count(*) ... WHERE golden`.
</Warning>

## Isolated testing: the mirror

Never test write-paths against prod. Use **`neondb_mirror`**: a separate Neon database (not a branch) holding a copy of live data.

<Steps>
  <Step title="Build/refresh the mirror">
    `node scripts/setup-mirror.mjs` (full detail in `scripts/MIRROR-README.md`).
  </Step>

  <Step title="Point the review server at it">
    Set `DATABASE_URL` / `POSTGRES_URL` to the mirror URL (`.env.local`'s `DATABASE_URL_UNPOOLED` with `/neondb` → `/neondb_mirror`) and `npm run dev` (port 3100).
  </Step>
</Steps>

<Warning>
  **The mirror diverges from prod in two known ways.** (1) It uses the **in-memory** conversation/threads store, so bugs that only appear with Upstash Redis (e.g. numeric thread keys auto-deserialized by the REST client) are **structurally impossible** to reproduce there, verify any inbox/SMS-store behavior against a Redis backend. (2) `next dev` diverges from the production build for client-side `useSearchParams` / `router.replace` effects under `force-dynamic`, verify suspected client-nav bugs against the deployed prod before treating them as real.
</Warning>

## How the bot "improves"

The model weights never change. The only quality lever is **curated golden exemplars**: golden rows are always surfaced first in recall; non-golden rows surface only on a keyword/FTS match and are not quality-filtered. To improve the bot, promote a well-handled real thread to golden (mechanism: the `golden` flag on `bot_conversations`). The documented upgrade path is semantic recall via pgvector + an embeddings model so the bot recalls by **meaning**, not just keywords.

## Verifying changes

The project convention is the `/verify-loop` skill: define success criteria + rubric, run realistic + adversarial + regression scenarios under isolated conditions, score with independent judge subagents to consensus, fix the root cause, rerun until unanimous. Run write-path verification on the mirror; keep prod untouched.