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

​
Seed / migrate the database

Gated, idempotent. Applies the additive schema and upserts customers/orders from real-data.ts (with the Oren-phone override).
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.

​
Seed only the bot golden exemplars

Seeds only the bot_conversations golden rows (retires obsolete exemplar ids, then upserts the current set), it does not touch customers/orders.
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.

​
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.
1

Build/refresh the mirror

node scripts/setup-mirror.mjs (full detail in scripts/MIRROR-README.md).
2

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).
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.

​
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.