From ef0d2a47e38db904a774bd3a93d2191bc9097385 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 3 Aug 2026 16:38:02 +0000
Subject: [PATCH 1/3] Update README and docs: fix stale SQLite/NextAuth
 references, sync structure
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The database has been Postgres (via @prisma/adapter-neon) since the
B-04 audit fix, but README.md, AGENTS.md, and several docs/ files
still described SQLite as current — including a literal
`provider = "sqlite"` schema snippet and `file:./dev.db` env examples
that would produce a broken setup if followed today. Fixed all
current-state references (left docs/AUDIT-FOLLOWUPS.md's historical
finding and docs/HANDOFF.md's dated 2026-07-20 snapshot alone, since
both are accurate records of a specific point in time, not claims
about the app today).

Also fixed the env var names to match .env.example / src/lib/auth.ts
(AUTH_SECRET, not NEXTAUTH_SECRET/NEXTAUTH_URL — this repo runs
NextAuth v5's Auth.js env var convention and doesn't need a URL var
at all).

Other fixes:
- README's project structure tree still showed core/ as a flat
  3-file module and CreateCampaignWizard.tsx as a top-level file;
  updated to match the real core/engine + core/slices split and the
  wizard/ subdirectory with per-ad-type steps.
- README's Tech Stack table was missing Astryx (153 components,
  actively used across ~40 files) entirely.
- README's pre-built-campaign table listed campaign #3's targeting
  mode as "Video creative" — that's the ad format, not targetingMode
  (which is actually 'Keyword'); corrected.
- README claimed "8 slices" for the Zustand store; it's 8 core slices
  + 7 feature slices (15 total), per CLAUDE.md.
- docs/TECH-SPECS.md's file-statistics table was stale in both
  directory shape and line counts (e.g. citing a single 600-line
  engine.ts that hasn't existed since the engine/ split); refreshed
  with real counts and dated the snapshot so future staleness is at
  least self-documenting.
- Linked the new CHANGELOG.md and existing-but-unlinked
  docs/DEPLOYMENT.md from README's Documentation section.
- CLAUDE.md: documented the new .claude/.agents/.codex ECC bundle
  (PR #56) and flagged that its auto-generated skill file contains at
  least one inaccurate claim (invented camelCase filename examples
  that don't match this repo's real PascalCase-components /
  lowercase-engine-modules convention) — CLAUDE.md remains the
  authoritative source when they disagree.
---
 AGENTS.md            |  4 +--
 CLAUDE.md            |  1 +
 README.md            | 34 +++++++++++++---------
 docs/ARCHITECTURE.md |  7 ++---
 docs/AUTH.md         | 35 +++++++++--------------
 docs/FEATURES.md     |  2 +-
 docs/TECH-SPECS.md   | 68 ++++++++++++++++++++++----------------------
 7 files changed, 76 insertions(+), 75 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1a96f56..0b013cf 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,10 +4,10 @@
 
 - **Framework**: Next.js 16, React 19, TypeScript ~5.8
 - **State**: Zustand 5
-- **Database**: Prisma 7 (SQLite dev)
+- **Database**: Prisma 7 + Postgres (via `@prisma/adapter-neon`)
 - **Auth**: NextAuth 5 (beta)
 - **Testing**: Vitest 4, Playwright 1.61
-- **Styling**: Tailwind CSS
+- **Styling**: `@astryxdesign/core` components + CSS custom-property tokens (no Tailwind compiler wired up despite the name appearing in some older docs)
 
 ## Build & Test
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 04ae677..d8a08d7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -121,6 +121,7 @@ These come from `AGENTS.md`, `LOOP.md`, `loop-constraints.md`, and `gate.yaml` 
 - `docs/` has deeper reference material: `ARCHITECTURE.md`, `API.md` (full engine function signatures), `SCHEMA.md`, `FEATURES.md`, `INTEGRATION.md` (porting guide), `AUTH.md`, `AUDIT-FOLLOWUPS.md`.
 - `CHANGELOG.md` (repo root) tracks notable changes per release starting at 3.6.0; bump `version` in `package.json` (and the unused-but-should-stay-in-sync `coreState.version` in `core/slices/core.ts`) together with a new entry when cutting a release.
 - `skills/`, `patterns/`, `gate.yaml`, `STATE.md`, `loop-*.md` support an autonomous triage/fix loop tool used against this repo — not part of the app runtime.
+- `.claude/`, `.agents/`, `.codex/` (added via the `ecc-tools` bot PR #56) are an auto-generated agent-tooling bundle: a repo skill, Codex config/agent roles, workflow command scaffolds, and "continuous learning instincts" derived from git-history analysis — not part of the app runtime either. Treat `.claude/skills/Amazon-ad-console/SKILL.md` as unverified: it was generated from commit-history heuristics and contains at least one claim that doesn't match this repo (it says filenames use `camelCase` with invented examples like `adEngine.ts`; the real convention is PascalCase for components (`CampaignManager.tsx`) and lowercase-per-domain-concern for engine modules (`core/engine/campaign.ts`), per the Architecture section above). This file (`CLAUDE.md`) is the authoritative guide — prefer it over the generated skill wherever they disagree.
 
 ## Porting the engine
 
diff --git a/README.md b/README.md
index 895e69f..6207bc3 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ Open [http://localhost:3000](http://localhost:3000) — the simulator loads with
 |---|---|---|---|
 | 1 | SP | Auto \| Coffee Filter \| Discovery | Automatic |
 | 2 | SP | Manual \| Coffee Filter \| Exact Winners | Manual keyword |
-| 3 | SB | Video \| Coffee Brand Awareness | Video creative |
+| 3 | SB | Video \| Coffee Brand Awareness | Keyword (Video ad format) |
 | 4 | SD | Views Remarketing \| 30 Day | Audience |
 | 5 | SB | Product Collection \| Coffee Variety | Product targeting |
 | 6 | SD | Contextual \| Coffee Accessories | Contextual |
@@ -75,11 +75,12 @@ Open [http://localhost:3000](http://localhost:3000) — the simulator loads with
 |-------|-----------|
 | Framework | Next.js 16 (App Router) |
 | UI | React 19 |
-| State | Zustand 5 (single store, 8 slices) |
+| State | Zustand 5 (single store, 8 core slices + 7 feature slices) |
 | Language | TypeScript 5.8 (strict mode) |
-| Styling | Global CSS (premium design system with Amazon-faithful tokens) |
+| UI components | `@astryxdesign/core` (153 components, theme via `@astryxdesign/theme-neutral`) |
+| Styling | Global CSS tokens bridging Astryx to the Amazon-faithful visual identity |
 | Engine | Pure TypeScript — zero React/UI dependencies |
-| Database | Prisma + SQLite (local development) |
+| Database | Prisma 7 + Postgres (via `@prisma/adapter-neon`) |
 | Authentication | NextAuth v5 (credentials provider) |
 | Password Hashing | bcryptjs |
 
@@ -131,9 +132,12 @@ Amazon-ad-console/
 │   │   └── ad-console/
 │   │       ├── core/               # Zero-dep engine
 │   │       │   ├── types.ts        # All domain interfaces
-│   │       │   ├── engine.ts       # Pure stateless functions
+│   │       │   ├── engine/         # Pure stateless functions, one module per domain concern
+│   │       │   │   └── (campaign, target, adgroup, negative, budget, portfolio, draft, id, metrics, responsive, search-term-generator).ts
+│   │       │   ├── simulation.ts   # 7-day performance simulator
+│   │       │   ├── slices/         # Zustand StateCreator slices wrapping the engine
 │   │       │   └── scenarios.ts    # Training data & product catalog
-│   │       ├── features/           # 7 SOLID feature modules
+│   │       ├── features/           # 7 self-contained feature modules
 │   │       │   ├── drills/         # Navigation coaching
 │   │       │   ├── profiles/       # Multi-user profiles
 │   │       │   ├── trainer/        # Certification & grading
@@ -142,27 +146,26 @@ Amazon-ad-console/
 │   │       │   ├── missions/       # Scenario challenges
 │   │       │   └── integrity/      # Data quality checks
 │   │       ├── store.ts            # Composed root Zustand store
-│   │       ├── index.ts            # Public API re-exports
-│   │       ├── engine.ts           # Backward-compat re-export
-│   │       └── types.ts            # Backward-compat re-export
+│   │       └── index.ts            # Public API re-exports
 │   ├── components/
 │   │   ├── AdConsole/              # React UI layer
 │   │   │   ├── AdConsole.tsx        # Root view router
 │   │   │   ├── Dashboard.tsx        # Aggregate metrics
 │   │   │   ├── CampaignManager.tsx  # Campaign list + filters
 │   │   │   ├── CampaignDetail.tsx   # Single campaign deep-dive
-│   │   │   ├── CreateCampaignWizard.tsx # Multi-step creation flow
 │   │   │   ├── PortfolioOverview.tsx # Portfolio grouping
+│   │   │   ├── wizard/              # 6-step campaign creation flow (per SP/SB/SD)
+│   │   │   │   └── CreateCampaignWizard.tsx
 │   │   │   ├── layout/
-│   │   │   │   ├── Sidebar.tsx      # Navigation rail
+│   │   │   │   ├── Sidebar.tsx      # Desktop navigation rail
 │   │   │   │   └── Topbar.tsx       # Header with actions + UserMenu
 │   │   │   ├── mobile/
-│   │   │   │   └── MobileNav.tsx    # Mobile drawer navigation
+│   │   │   │   └── MobileNav.tsx    # Mobile/tablet hamburger drawer navigation
 │   │   │   ├── nav/
 │   │   │   │   └── consoleNav.ts    # Amazon console nav model
 │   │   │   ├── metrics/
 │   │   │   │   └── MetricCard.tsx   # Reusable metric display
-│   │   │   ├── details/             # Tab components
+│   │   │   ├── details/             # Tab components + shared EmptyState
 │   │   │   └── features/            # Feature-specific pages
 │   │   │       ├── drills/DrillsPage.tsx
 │   │   │       ├── missions/MissionsPage.tsx
@@ -191,6 +194,9 @@ Amazon-ad-console/
 │   ├── TECH-SPECS.md
 │   ├── MOBILE_REDESIGN_PLAN.md
 │   └── AUTH.md                      # Multi-user authentication guide
+├── CLAUDE.md                        # Architecture + conventions guide for Claude Code
+├── CHANGELOG.md                     # Notable changes per release
+├── .env.example                     # DATABASE_URL / AUTH_SECRET template
 ├── package.json
 ├── tsconfig.json
 ├── next.config.ts
@@ -232,7 +238,9 @@ See [docs/INTEGRATION.md](docs/INTEGRATION.md) for the full porting guide.
 - [Tech Specs](docs/TECH-SPECS.md) — Dependencies, configuration, performance
 - [Mobile Redesign Plan](docs/MOBILE_REDESIGN_PLAN.md) — Mobile-first redesign strategy
 - [Authentication Guide](docs/AUTH.md) — Multi-user access setup and configuration
+- [Deployment](docs/DEPLOYMENT.md) — Vercel project setup and deploy process
 - [Audit Follow-Ups](docs/AUDIT-FOLLOWUPS.md) — Status of each finding from the 2026-07-21 audit, with PR links
+- [Changelog](CHANGELOG.md) — Notable changes per release, starting at 3.6.0
 
 ## License
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 5df5f6c..cdeec41 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -112,7 +112,7 @@ User Action → Component → Store Slice → Engine Function → New State →
 
 ### Server-Side Data Flow
 ```
-Component → API Route → Prisma Client → SQLite Database
+Component → API Route → Prisma Client (Neon adapter) → Postgres Database
      ↓
 Component ← API Response ← Prisma Query Result
 ```
@@ -123,7 +123,7 @@ Component ← API Response ← Prisma Query Result
 - **Provider**: Credentials (email/password)
 - **Session Strategy**: JWT
 - **Password Hashing**: bcryptjs
-- **Database**: SQLite via Prisma
+- **Database**: Postgres via Prisma (`@prisma/adapter-neon`)
 
 ### API Route Protection
 All `/api/*` routes check for valid session:
@@ -246,8 +246,7 @@ model Campaign {
 ### Environment Variables
 ```env
 DATABASE_URL="postgresql://..."
-NEXTAUTH_SECRET="your-secret-here"
-NEXTAUTH_URL="http://localhost:3000"
+AUTH_SECRET="your-secret-here"
 ```
 
 ### Production Considerations
diff --git a/docs/AUTH.md b/docs/AUTH.md
index 6c9c5d1..d394aa2 100644
--- a/docs/AUTH.md
+++ b/docs/AUTH.md
@@ -17,7 +17,7 @@ The application supports multiple users with isolated campaign data. Each user c
 
 1. **NextAuth v5** — Authentication provider
 2. **Prisma** — Database ORM
-3. **SQLite** — Local development database
+3. **Postgres** — Database (via `@prisma/adapter-neon`), used in every environment
 4. **JWT Sessions** — Stateless session management
 
 ### Database Schema
@@ -61,7 +61,7 @@ npm install -D @types/bcryptjs
 ### 2. Initialize Prisma
 
 ```bash
-npx prisma init --datasource-provider sqlite
+npx prisma init --datasource-provider postgresql
 ```
 
 ### 3. Configure Environment Variables
@@ -69,12 +69,11 @@ npx prisma init --datasource-provider sqlite
 Create `.env` file:
 
 ```env
-# Prisma
-DATABASE_URL="file:./dev.db"
+# Prisma (Postgres — e.g. from Vercel Storage → Postgres, or Neon directly)
+DATABASE_URL="postgresql://user:password@host/dbname?sslmode=require"
 
-# NextAuth
-NEXTAUTH_SECRET="your-secret-key-here"
-NEXTAUTH_URL="http://localhost:3000"
+# NextAuth/Auth.js session secret — generate with: openssl rand -base64 32
+AUTH_SECRET="your-secret-key-here"
 ```
 
 ### 4. Run Migrations
@@ -295,25 +294,20 @@ export function SyncButton() {
 ## Production Deployment
 
 ### Database
-Replace SQLite with a production database:
+`prisma/schema.prisma` targets Postgres (via `@prisma/adapter-neon`) in every environment, not just production — see `.env.example`:
 
 ```env
-# PostgreSQL
-DATABASE_URL="postgresql://user:password@localhost:5432/adconsole"
-
-# MySQL
-DATABASE_URL="mysql://user:password@localhost:3306/adconsole"
+DATABASE_URL="postgresql://user:password@host/dbname?sslmode=require"
 ```
 
 ### Environment Variables
 ```env
-DATABASE_URL="your-production-db-url"
-NEXTAUTH_SECRET="strong-random-secret"
-NEXTAUTH_URL="https://your-domain.com"
+DATABASE_URL="your-postgres-connection-string"
+AUTH_SECRET="strong-random-secret"   # generate with: openssl rand -base64 32
 ```
 
 ### Security Checklist
-- [ ] Use strong NEXTAUTH_SECRET (32+ characters)
+- [ ] Use strong AUTH_SECRET (32+ characters)
 - [ ] Enable HTTPS in production
 - [ ] Set secure cookie flags
 - [ ] Add rate limiting to auth endpoints
@@ -333,18 +327,17 @@ NEXTAUTH_URL="https://your-domain.com"
 **"Unauthorized" error**
 - Ensure user is logged in
 - Check JWT token expiration
-- Verify NEXTAUTH_SECRET is set
+- Verify AUTH_SECRET is set
 
 **Database connection errors**
 - Run `npx prisma migrate dev`
-- Check DATABASE_URL in .env
-- Verify SQLite file exists
+- Check DATABASE_URL in .env points at a reachable Postgres instance
 
 ### Debug Mode
 Enable NextAuth debug logging:
 
 ```env
-NEXTAUTH_DEBUG=true
+AUTH_DEBUG=true
 ```
 
 ## Future Enhancements
diff --git a/docs/FEATURES.md b/docs/FEATURES.md
index e9fd5b7..aa596aa 100644
--- a/docs/FEATURES.md
+++ b/docs/FEATURES.md
@@ -435,7 +435,7 @@ When clicking a tab-mapped item:
 ## 15. Multi-User Authentication
 
 **Auth Provider**: NextAuth v5
-**Database**: Prisma + SQLite
+**Database**: Prisma + Postgres (via `@prisma/adapter-neon`)
 **Components**: `SessionProvider.tsx`, `UserMenu.tsx`, `SyncButton.tsx`
 **Pages**: `/auth/login`, `/auth/register`, `/landing`
 
diff --git a/docs/TECH-SPECS.md b/docs/TECH-SPECS.md
index bd81934..fffff58 100644
--- a/docs/TECH-SPECS.md
+++ b/docs/TECH-SPECS.md
@@ -85,23 +85,22 @@ generator client {
 }
 
 datasource db {
-  provider = "sqlite"
+  provider = "postgresql"
 }
 ```
+(The connection itself — `DATABASE_URL` plus the `@prisma/adapter-neon` driver adapter — is wired up in `prisma.config.ts` / `src/lib/prisma.ts`, not the `url` field here; Prisma 7's driver-adapter pattern moved that out of `schema.prisma`.)
 
 ### Environment Variables
 ```env
-# Prisma
-DATABASE_URL="file:./dev.db"
+# Prisma (Postgres — e.g. from Vercel Storage → Postgres, or Neon directly)
+DATABASE_URL="postgresql://user:password@host/dbname?sslmode=require"
 
-# NextAuth
-NEXTAUTH_SECRET="your-secret-key-here"
-NEXTAUTH_URL="http://localhost:3000"
+# NextAuth/Auth.js session secret — generate with: openssl rand -base64 32
+AUTH_SECRET="your-secret-key-here"
 ```
 
 ### Database Commands
 ```bash
-npx prisma init --datasource-provider sqlite
 npx prisma migrate dev --name init
 npx prisma generate
 npx prisma db push
@@ -109,33 +108,35 @@ npx prisma db push
 
 ## File Statistics
 
+*Point-in-time snapshot as of 2026-08-03 (v3.6.0) — expect drift; re-run the `find`/`wc -l` commands below rather than trusting these numbers long-term.*
+
 | Directory | Files | Total Lines |
 |-----------|-------|------------|
-| `src/engine/ad-console/core/` | 3 | ~800 |
-| `src/engine/ad-console/features/` | 21 | ~1,800 |
-| `src/engine/ad-console/` (root) | 4 | ~220 |
-| `src/components/AdConsole/` | 15 | ~1,800 |
-| `src/components/` (root) | 3 | ~200 |
-| `src/app/` | 8 | ~1,200 |
-| `src/lib/` | 4 | ~300 |
-| `prisma/` | 2 | ~100 |
-| **Total src/** | **60+** | **~7,500** |
-
-### Source File Breakdown
-
-| File | Lines | Responsibility |
-|------|-------|---------------|
-| `globals.css` | 1,377 | Design system tokens + responsive styles |
-| `store.ts` | 250 | Zustand root store composition |
-| `engine.ts` | 600 | Core business logic functions |
-| `types.ts` | 200 | Domain interfaces |
-| `scenarios.ts` | 400 | Training data & product catalog |
-| `CampaignManager.tsx` | 300 | Campaign list + filters |
-| `CampaignDetail.tsx` | 550 | Single campaign deep-dive |
-| `CreateCampaignWizard.tsx` | 200 | Multi-step creation flow |
-| `MobileNav.tsx` | 133 | Mobile drawer navigation |
-| `auth.ts` | 80 | NextAuth configuration |
-| `prisma.ts` | 15 | Prisma client singleton |
+| `src/engine/ad-console/core/` (incl. `engine/`, `slices/`) | 25 | ~2,330 |
+| `src/engine/ad-console/features/` | 21 | ~1,180 |
+| `src/engine/ad-console/` (root: `index.ts`, `store.ts`, `scenarios.ts`, `types.ts`) | 4 | ~180 |
+| `src/components/AdConsole/` | 44 | ~3,930 |
+| `src/components/` (root) | 3 | ~160 |
+| `src/app/` (top-level, incl. `globals.css`) | 5 | ~4,530 |
+| `src/lib/` | 7 | ~260 |
+| **Total src/** | — | ~20,700 |
+
+Note: `core/` was originally a 3-file module (`types.ts`, a single `engine.ts`, `scenarios.ts`); it's since been split into `core/engine/` (one file per domain concern — `campaign.ts`, `target.ts`, `adgroup.ts`, `negative.ts`, `budget.ts`, `portfolio.ts`, `draft.ts`, `id.ts`, `metrics.ts`, `responsive.ts`, `search-term-generator.ts`), `core/simulation.ts`, and `core/slices/` (the Zustand-dependent wrappers) — see `CLAUDE.md` for the current breakdown.
+
+### Selected File Sizes
+
+| File | Responsibility |
+|------|---------------|
+| `globals.css` | Design system tokens + responsive styles (largest single file in the repo) |
+| `store.ts` | Zustand root store composition |
+| `core/types.ts` | Domain interfaces |
+| `core/scenarios.ts` | Training data & product catalog |
+| `CampaignManager.tsx` | Campaign list + filters |
+| `CampaignDetail.tsx` | Single campaign deep-dive |
+| `wizard/CreateCampaignWizard.tsx` + `wizard/steps/**` | 6-step, per-ad-type creation flow |
+| `MobileNav.tsx` | Mobile/tablet hamburger drawer navigation |
+| `auth.ts` | NextAuth configuration |
+| `prisma.ts` | Prisma client singleton |
 
 ## Testing Configuration
 
@@ -210,6 +211,5 @@ CMD ["npm", "start"]
 ### Environment Variables for Production
 ```env
 DATABASE_URL="postgresql://user:password@host:5432/db"
-NEXTAUTH_SECRET="strong-random-secret"
-NEXTAUTH_URL="https://your-domain.com"
+AUTH_SECRET="strong-random-secret"
 ```

From 492c51717ec23b27c6f6672195b0db17758f1baf Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 3 Aug 2026 16:42:54 +0000
Subject: [PATCH 2/3] Restore top-level types.ts/scenarios.ts in README's
 structure tree
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Copilot review flagged that these two backward-compat re-export files
(export * from './core/types' / './core/scenarios') were dropped when
the tree was resynced — they still exist and are real navigation
points, unlike the engine.ts single-file that was correctly removed.
---
 README.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 6207bc3..2b32c84 100644
--- a/README.md
+++ b/README.md
@@ -146,7 +146,9 @@ Amazon-ad-console/
 │   │       │   ├── missions/       # Scenario challenges
 │   │       │   └── integrity/      # Data quality checks
 │   │       ├── store.ts            # Composed root Zustand store
-│   │       └── index.ts            # Public API re-exports
+│   │       ├── index.ts            # Public API re-exports
+│   │       ├── types.ts            # Backward-compat re-export of core/types.ts
+│   │       └── scenarios.ts        # Backward-compat re-export of core/scenarios.ts
 │   ├── components/
 │   │   ├── AdConsole/              # React UI layer
 │   │   │   ├── AdConsole.tsx        # Root view router

From edf96f8f102b004f591bbde499de698bceee6d60 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 3 Aug 2026 16:46:35 +0000
Subject: [PATCH 3/3] Address CodeRabbit findings: adapter wiring location,
 deps, migrate deploy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docs/AUTH.md: clarified that prisma/schema.prisma only declares the
  postgresql provider — the DATABASE_URL/adapter-neon runtime wiring
  lives in prisma.config.ts / src/lib/prisma.ts, not the schema.
- docs/AUTH.md + docs/TECH-SPECS.md: added the two Neon packages
  (@prisma/adapter-neon, @neondatabase/serverless) to the install
  command and dependency table; also refreshed the dependency table's
  stale versions (^5.0.0 Prisma, ^11.0.0 motion, etc. — actual
  package.json has 7.8.0/12.42.2) and added the Astryx/phosphor-icons/
  dotenv packages that were missing from it entirely. Dropped the
  "total runtime dependency count" line in favor of pointing at
  package.json, since a hardcoded count is exactly the kind of number
  that goes stale silently.
- docs/AUTH.md + docs/TECH-SPECS.md: distinguished `migrate dev`
  (local development) from `migrate deploy` (production/CI — doesn't
  prompt interactively).
- README.md: added docs/DEPLOYMENT.md and docs/AUDIT-FOLLOWUPS.md to
  the project structure tree, matching the Documentation section's
  links.
---
 README.md          |  4 +++-
 docs/AUTH.md       |  7 ++++---
 docs/TECH-SPECS.md | 23 +++++++++++++++++------
 3 files changed, 24 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 2b32c84..2f88a90 100644
--- a/README.md
+++ b/README.md
@@ -195,7 +195,9 @@ Amazon-ad-console/
 │   ├── INTEGRATION.md
 │   ├── TECH-SPECS.md
 │   ├── MOBILE_REDESIGN_PLAN.md
-│   └── AUTH.md                      # Multi-user authentication guide
+│   ├── AUTH.md                      # Multi-user authentication guide
+│   ├── DEPLOYMENT.md                # Vercel project setup and deploy process
+│   └── AUDIT-FOLLOWUPS.md           # Status of each audit finding, with PR links
 ├── CLAUDE.md                        # Architecture + conventions guide for Claude Code
 ├── CHANGELOG.md                     # Notable changes per release
 ├── .env.example                     # DATABASE_URL / AUTH_SECRET template
diff --git a/docs/AUTH.md b/docs/AUTH.md
index d394aa2..c626440 100644
--- a/docs/AUTH.md
+++ b/docs/AUTH.md
@@ -54,7 +54,7 @@ model Campaign {
 ### 1. Install Dependencies
 
 ```bash
-npm install prisma @prisma/client next-auth bcryptjs
+npm install prisma @prisma/client @prisma/adapter-neon @neondatabase/serverless next-auth bcryptjs
 npm install -D @types/bcryptjs
 ```
 
@@ -294,7 +294,7 @@ export function SyncButton() {
 ## Production Deployment
 
 ### Database
-`prisma/schema.prisma` targets Postgres (via `@prisma/adapter-neon`) in every environment, not just production — see `.env.example`:
+`prisma/schema.prisma` declares the `postgresql` datasource provider, used in every environment, not just production. The runtime connection (`DATABASE_URL` plus the `@prisma/adapter-neon` driver adapter) is wired up separately in `prisma.config.ts` / `src/lib/prisma.ts`, not in the schema itself — see `.env.example`:
 
 ```env
 DATABASE_URL="postgresql://user:password@host/dbname?sslmode=require"
@@ -330,7 +330,8 @@ AUTH_SECRET="strong-random-secret"   # generate with: openssl rand -base64 32
 - Verify AUTH_SECRET is set
 
 **Database connection errors**
-- Run `npx prisma migrate dev`
+- Local development: run `npx prisma migrate dev` to apply pending migrations
+- Production: run `npx prisma migrate deploy` instead (`migrate dev` is dev-only — it can prompt interactively and isn't safe for CI/deploy pipelines)
 - Check DATABASE_URL in .env points at a reachable Postgres instance
 
 ### Debug Mode
diff --git a/docs/TECH-SPECS.md b/docs/TECH-SPECS.md
index fffff58..5af68ad 100644
--- a/docs/TECH-SPECS.md
+++ b/docs/TECH-SPECS.md
@@ -18,21 +18,28 @@
 | `react` | ^19.0.0 | UI library |
 | `react-dom` | ^19.0.0 | React DOM renderer |
 | `zustand` | ^5.0.0 | State management |
-| `@prisma/client` | ^5.0.0 | Database ORM |
+| `@astryxdesign/core` | ^0.1.8 | UI component library (153 components) |
+| `@astryxdesign/theme-neutral` | ^0.1.8 | Astryx theme |
+| `@phosphor-icons/react` | ^2.1.10 | Icon set |
+| `@prisma/client` | ^7.8.0 | Database ORM |
+| `@prisma/adapter-neon` | ^7.8.0 | Postgres driver adapter (Neon) |
+| `@neondatabase/serverless` | ^1.1.0 | Neon serverless Postgres driver |
+| `prisma` | ^7.8.0 | Prisma CLI (also listed as a runtime dep; used by `postinstall`) |
 | `next-auth` | ^5.0.0-beta.31 | Authentication |
-| `bcryptjs` | ^2.4.3 | Password hashing |
-| `motion` | ^11.0.0 | Animation library |
+| `bcryptjs` | ^3.0.3 | Password hashing |
+| `motion` | ^12.42.2 | Animation library |
 
 ### Development
 
 | Package | Version | Purpose |
 |---------|---------|---------|
+| `@astryxdesign/cli` | ^0.1.8 | Astryx component/token discovery CLI |
 | `@types/node` | ^22.0.0 | Node.js type definitions |
 | `@types/react` | ^19.0.0 | React type definitions |
 | `@types/react-dom` | ^19.0.0 | ReactDOM type definitions |
-| `@types/bcryptjs` | ^2.4.0 | bcryptjs type definitions |
+| `@types/bcryptjs` | ^2.4.6 | bcryptjs type definitions |
 | `typescript` | ~5.8.0 | TypeScript compiler |
-| `prisma` | ^5.0.0 | Prisma CLI |
+| `dotenv` | ^17.4.2 | Loads `.env` for `prisma.config.ts` |
 | `vitest` | ^4.1.10 | Test runner |
 | `@vitest/coverage-v8` | ^4.1.10 | Code coverage |
 | `@playwright/test` | ^1.61.1 | E2E testing |
@@ -40,7 +47,7 @@
 | `@testing-library/user-event` | ^14.6.1 | User interaction simulation |
 | `jsdom` | ^29.1.1 | DOM implementation for tests |
 
-**Total runtime dependency count: 8** (next, react, react-dom, zustand, @prisma/client, next-auth, bcryptjs, motion)
+See `package.json` for the authoritative, exact version list — this table is a point-in-time summary and will drift as dependencies are bumped.
 
 ## TypeScript Configuration
 
@@ -101,9 +108,13 @@ AUTH_SECRET="your-secret-key-here"
 
 ### Database Commands
 ```bash
+# Local development
 npx prisma migrate dev --name init
 npx prisma generate
 npx prisma db push
+
+# Production deployment (CI/deploy pipelines — non-interactive, no schema drift prompts)
+npx prisma migrate deploy
 ```
 
 ## File Statistics