release: v1.0.0-alpha.20

.env.example

@@ -11,6 +11,11 @@ SUPABASE_URL=https://your-project.supabase.co
 SUPABASE_ANON_KEY=your-anon-key-from-supabase-dashboard
 SUPABASE_SERVICE_KEY=your-service-role-key-from-supabase-dashboard
 
+# ADMIN_EMAIL — primary admin email for the v1.1 admin dashboards.
+# Referenced by nuxt.config.ts:81 (adminEmail) and server/utils/auth.ts admin gate.
+# MISSING → no admin can authenticate to /admin/* routes (dashboards inaccessible).
+ADMIN_EMAIL=admin@example.com
+
 # ============================================
 # OpenAI (AI Analysis)
 # ============================================
@@ -23,6 +28,15 @@ STRIPE_SECRET_KEY=sk_live_your-stripe-secret-key
 STRIPE_PUBLISHABLE_KEY=pk_live_your-stripe-publishable-key
 STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret
 
+# Stripe production price IDs — server/utils/stripe-client.ts:20-39
+# Each STRIPE_PRICE_ID_*_CREDITS maps a credit pack to its live Stripe price.
+# MISSING → silent fallback to hard-coded test price ID for the 5-credit pack → wrong-product billing in prod.
+STRIPE_PRICE_ID_5_CREDITS=price_test_REPLACE_ME_5_CREDITS
+# MISSING → silent fallback to hard-coded test price ID for the 10-credit pack → wrong-product billing in prod.
+STRIPE_PRICE_ID_10_CREDITS=price_test_REPLACE_ME_10_CREDITS
+# MISSING → silent fallback to hard-coded test price ID for the 25-credit pack → wrong-product billing in prod.
+STRIPE_PRICE_ID_25_CREDITS=price_test_REPLACE_ME_25_CREDITS
+
 # ============================================
 # Redis (BullMQ Queue Backend)
 # Use Upstash for production (TLS required) or local Redis
@@ -36,7 +50,20 @@ REDIS_TOKEN=your-redis-auth-token
 # ============================================
 BASE_URL=https://clarify.yourdomain.com
 
+# NODE_ENV — controls multiple runtime branches (dev logging, error verbosity, secure cookies).
+# MISSING → defaults to "development"; production deploys MUST set "production".
+NODE_ENV=production
+
+# ALLOWED_REDIRECT_ORIGINS — comma-separated safe origins for auth redirect callbacks.
+# MISSING → redirect validation falls back to BASE_URL only (may break multi-domain setups).
+ALLOWED_REDIRECT_ORIGINS=https://clarify.yourdomain.com
+
 # ============================================
 # Worker Configuration
 # ============================================
 BULLMQ_CONCURRENCY=2
+
+# DISABLE_WORKER — set to "true" to disable the in-process BullMQ worker.
+# Used when running a dedicated worker container (HTTP-only app pods).
+# MISSING → worker runs inside the Nuxt server (default, fine for single-container deploys; unset/empty is treated as "false").
+DISABLE_WORKER=false

.github/workflows/ci-cd.yml

@@ -15,17 +15,17 @@ jobs:
           ref: ${{ github.event.release.tag_name }}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: Extract metadata
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@v6
         with:
           images: ${{ secrets.DOCKER_USERNAME }}/clarify
           tags: |
@@ -34,7 +34,7 @@ jobs:
             type=sha
 
       - name: Build and push Docker image
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@v7
         with:
           context: .
           file: ./Dockerfile
@@ -97,3 +97,4 @@ jobs:
 
             echo "=== Deployment Logs ==="
             docker compose -f docker-compose.prod.yml logs --tail=50
+

.planning/MILESTONES.md

@@ -41,33 +41,36 @@ _For detailed milestone archive, see `.planning/milestones/v1.0-mvp-ROADMAP.md`_
 
 ---
 
-## v1.1 Admin & Deploy — 2026-03-25
+## v1.1 Admin & Deploy — 2026-03-25 (fully closed 2026-05-07)
 
-**Phases:** 6-7 | **Plans:** 4 | **Status:** ✅ SHIPPED
+**Phases:** 6, 7, 10 | **Plans:** 8 | **Status:** ✅ SHIPPED + AUDIT GAPS CLOSED
 
 ### Key Accomplishments
 
 1. **Admin Revenue Dashboard** — Daily/weekly/monthly/quarterly revenue charts with gross/net comparison and package breakdown
 2. **Conversion Funnel Tracking** — 4-stage funnel (Signups → Email Verified → First Analysis → First Purchase) with conversion rates
 3. **Cost Analysis by Tier** — Profit margin tracking for Basic/Premium/Forensic with AI cost calculations
-4. **User Management** — Credit adjustments and account suspension with audit trail logging
+4. **User Management** — Credit adjustments and account suspension with audit trail logging (16/16 UAT passed)
 5. **Production Infrastructure** — `.env.example` template, configurable worker concurrency, Redis health check
+6. **Suspension Enforcement** (Phase 10) — Upload and BullMQ worker gates reject suspended users (ADMIN-04 BLOCKER closed)
+7. **Funnel Stage 2 RPC** (Phase 10) — PostgreSQL SECURITY DEFINER function for email-verified counts (ADMIN-01 closed)
+8. **Complete `.env.example`** (Phase 10) — 6 missing critical vars documented with consequence-if-missing (DEPLOY-01 closed)
+9. **Revenue Package Join** (Phase 10) — credits_purchased join replaces brittle price-band inference (ADMIN-02 closed)
 
 ### Stats
 
-- **Timeline:** 2026-03-16 → 2026-03-25 (9 days)
-- **Files Modified:** 15+
-- **Test Coverage:** 43 admin tests (14 costs, 16 user-management, 6 revenue, 7 funnel)
-- **Requirements:** 4/5 complete (80%)
+- **Timeline:** 2026-03-16 → 2026-05-07 (52 days including Phase 10)
+- **Phase 6-7 Files:** 15+ | **Phase 10 Files:** 42, +3324/-282 LOC
+- **Test Coverage:** 43 admin tests + 23 Phase 10 tests (suspension, funnel RPC, revenue breakdown)
+- **Requirements:** 5/5 complete (100%) — all v1.1 audit gaps closed
 
-### Known Gaps
-
-- **DEPLOY-01** — Deployment artifacts complete, live verification pending (HTTPS, health endpoint, worker processing, Traefik routing)
+### Deferred Items
 
-### Tech Debt
+- DEPLOY-01 live verification (HTTPS, health, worker, Traefik) — deferred to v2.0 launch (requires live server)
+- Phase 07 production UAT (5 tests) — deferred to v2.0 launch
+- Phase 01 Test 4 (Forensic UI sections) — deferred to v2.0 (known Phase 2 gap)
 
-- Phase 06 missing VERIFICATION.md file
-- Database migrations for user suspension require manual Supabase execution
+### Known Deferred items at close: 3 (see STATE.md Deferred Items)
 
 ---
 

.planning/PROJECT.md

@@ -2,11 +2,21 @@
 
 ## Current State
 
-**v1.1 Admin & Deploy: SHIPPED** ✅ (2026-03-25)
+**v1.1 Admin & Deploy: SHIPPED** ✅ (2026-03-25, fully closed 2026-05-07)
+**v2.0 Analysis Experience: IN PROGRESS** 🔄 (planning started 2026-05-07)
 
 Clarify is a shipped AI-powered contract analysis platform with 3-tier pricing, Stripe payments, free credits onboarding, interactive demo, and admin analytics dashboard.
 
-**Next Milestone: v2.0** — TBD (planning required)
+**Phase 10 complete (2026-05-07):** All 4 v1.1 audit gaps closed — suspension enforcement (ADMIN-04 BLOCKER), funnel Stage 2 RPC (ADMIN-01), .env.example completeness (DEPLOY-01 BLOCKER), revenue package mapping (ADMIN-02). 21/21 DB migrations applied. 23/23 tests pass.
+
+## Current Milestone: v2.0 Analysis Experience
+
+**Goal:** Transform the flat analysis report into a structured, navigable reading experience with confidence signals that help non-lawyers know what to trust and what to scrutinize.
+
+**Target features:**
+- Clause navigation — sidebar jump links + expandable clause cards + AI-quoted source clause text (all tiers)
+- Confidence signals — risk score (0–10) with category breakdown + per-clause certainty badges (high/medium/low) + coverage percentage
+- Prompt improvements — updated prompts to emit structured clause-level data powering the new UI
 
 ---
 
@@ -97,4 +107,4 @@ Individual consumers who need to understand contracts — renters, freelancers,
 | Suspension requires mandatory reason field | Compliance and accountability | ✓ Validated v1.1 |
 
 ---
-*Last updated: 2026-03-25 after v1.1 Admin & Deploy milestone*
+*Last updated: 2026-05-07 after Phase 10 v1.1 audit gap closure*

.planning/REQUIREMENTS.md

@@ -0,0 +1,72 @@
+# Requirements: v2.0 Analysis Experience
+
+## Milestone Goal
+
+Transform the flat analysis report into a structured, navigable reading experience with confidence signals that help non-lawyers know what to trust and what to scrutinize.
+
+---
+
+## v2.0 Requirements
+
+### Analysis Results UI
+
+- [x] **RESULT-01**: User can view analysis results with a sidebar index of clause sections, clickable to jump to each section
+- [x] **RESULT-02**: User can expand/collapse individual clause finding cards to reduce cognitive overload
+- [x] **RESULT-03**: User can see AI-quoted source clause text alongside each finding's explanation
+
+### Confidence Signals
+
+- [x] **CONF-01**: User can see an overall risk score (0–10) with a breakdown by risk category at the top of each analysis
+- [x] **CONF-02**: User can see a per-clause certainty badge (High/Medium/Low) indicating AI confidence in each flag
+- [x] **CONF-03**: User can see a coverage percentage showing what portion of the contract was analyzed
+
+### Prompt Engineering
+
+- [ ] **PROMPT-02**: All tier prompts (Basic, Premium, Forensic) emit structured clause-level data including clause quotes, certainty ratings, and risk category tags
+- [ ] **PROMPT-03**: Forensic tier prompt returns a coverage estimate (percentage of contract clauses analyzed)
+
+### Launch Verification (v1.1 Deferred)
+
+- [ ] **LAUNCH-01**: Production deployment at clarify.cativo.dev is live — HTTPS active, health endpoint responds, BullMQ worker running
+- [ ] **LAUNCH-02**: PDF export renders correctly in production (Supabase Storage bucket configured and verified)
+- [ ] **LAUNCH-03**: PDF caching round-trip verified in production (upload → cache → re-serve)
+- [ ] **LAUNCH-04**: Forensic tier UI sections render correctly in the analysis report (resolves Phase 1 Test 4 UAT gap)
+
+---
+
+## Future Requirements (Deferred)
+
+- Contract comparison mode — upload two versions, see risk delta (deferred to v2.1)
+- Subscription billing — recurring plans (deferred until credit model profitability confirmed)
+- Mobile app — web-first approach maintained
+
+## Out of Scope
+
+- Contract comparison / diff view — not enough user signal on exact use case; deferred to v2.1
+- Real-time collaboration — individual user focus
+- Multi-language support — English only
+- Full CLM (Contract Lifecycle Management) — pre-signature analysis focus only
+- PDF parsing for clause extraction — AI quotes clause text inline; no client/server PDF parsing layer
+
+---
+
+## Traceability
+
+| REQ-ID | Phase | Plan |
+|--------|-------|------|
+| PROMPT-02 | Phase 11 | — |
+| PROMPT-03 | Phase 11 | — |
+| RESULT-01 | Phase 12 | — |
+| RESULT-02 | Phase 12 | — |
+| RESULT-03 | Phase 12 | — |
+| CONF-01 | Phase 12 | 12-03 |
+| CONF-02 | Phase 12 | 12-01 |
+| CONF-03 | Phase 12 | 12-03 |
+| LAUNCH-01 | Phase 13 | — |
+| LAUNCH-02 | Phase 13 | — |
+| LAUNCH-03 | Phase 13 | — |
+| LAUNCH-04 | Phase 13 | — |
+
+---
+
+*Last updated: 2026-05-07 — v2.0 roadmap created, traceability filled (Phases 11-13)*

.planning/RETROSPECTIVE.md

@@ -0,0 +1,94 @@
+# Retrospective: Clarify
+
+Living retrospective — updated at each milestone close.
+
+---
+
+## Milestone: v1.0 MVP
+
+**Shipped:** 2026-03-15
+**Phases:** 5 | **Plans:** 22
+
+### What Was Built
+
+- 3-tier AI contract analysis (Basic/Premium/Forensic) with gpt-4o-mini, gpt-5-mini, gpt-5
+- Secure upload with magic byte validation and BullMQ async processing
+- PDF export with branded reports, Supabase Storage caching, history filters
+- Stripe monetization (3 credit packages) with atomic webhook fulfillment
+- Free credits onboarding (10 credits on signup) + 1 free Basic/month
+- Homepage demo with rate limiting for trial-without-signup UX
+
+### What Worked
+
+- Tier-based credit system landed cleanly — 1/3/10 credits is intuitive
+- BullMQ + Upstash Redis: async processing with no UI blocking, zero timeouts
+- PDF generation (pdfkit) with bufferPages for consistent footers across pages
+- Atomic PostgreSQL RPC for credit fulfillment — no double-credit bugs
+
+### What Was Inefficient
+
+- Forensic UI sections (analisis_cruzado, omisiones_critic, mapa_estructural) were built in backend but not surfaced in UI — discovered at UAT
+- Phase 1-2 required a 2-pass approach (implement then fix UI)
+
+### Key Lessons
+
+- Plan UI display of new data structures at the same time as backend prompts, not after
+- Magic byte validation is easy to implement but error message extraction needs explicit handling
+
+---
+
+## Milestone: v1.1 Admin & Deploy
+
+**Shipped:** 2026-03-25 (Phases 6-7) | **Audit gaps closed:** 2026-05-07 (Phase 10)
+**Phases:** 3 (6, 7, 10) | **Plans:** 8
+
+### What Was Built
+
+- Admin analytics dashboard: revenue charts, conversion funnel, cost analysis, user management
+- Production deployment: `.env.example`, worker config, Redis health check
+- Suspension enforcement: upload + BullMQ job gates check `users.is_suspended` (ADMIN-04)
+- Funnel Stage 2: PostgreSQL SECURITY DEFINER RPC for email-verified counts (ADMIN-01)
+- `.env.example` completeness: 6 missing vars documented with consequence-if-missing (DEPLOY-01)
+- Revenue package breakdown via `credits_purchased` join, decoupled from Stripe prices (ADMIN-02)
+
+### What Worked
+
+- Post-ship audit caught 4 real blockers before v2.0 planning started — worth the extra phase
+- Phase 10 audit gap closure was clean: 4 plans, 4 atomic commits, 23 tests, all passing
+- Browser-based UAT via Claude's chrome automation tool was effective for admin UI testing
+- Admin user management (credit adjustment + suspend/unsuspend) all worked on first attempt
+
+### What Was Inefficient
+
+- Initial v1.1 close (2026-03-25) was done without sufficient cross-phase integration checks — suspension flag was written but never read, RPC was called but never migrated
+- Phase 10 was needed to fix what should have been caught before initial v1.1 tag
+- `require()` vs `import` bug in ESM modules (funnel, revenue API files) slipped through testing
+
+### Patterns Established
+
+- Post-ship audit (`gsd-audit-milestone`) is mandatory before milestone close — catches integration gaps that code review misses
+- SECURITY DEFINER SQL functions with explicit REVOKE/GRANT for cross-schema RPCs
+- Env var documentation: per-key "consequence if missing" comments in `.env.example`
+- `type='adjustment', amount=0` pattern for credit adjustments (monetary-neutral audit trail)
+- Suspension enforcement at two layers (HTTP upload + queue job pickup) for defense in depth
+
+### Key Lessons
+
+- The initial v1.1 ship had 4 features that appeared complete but were cosmetic (suspension) or fallback-only (funnel, revenue, .env). Cross-phase integration checks must go deeper than "does the code exist?"
+- Phase 10 pattern: targeted 1-blocker-per-plan + test-first approach is highly efficient for gap closure
+- Browser automation for UAT is powerful but requires domain permission setup in advance
+
+---
+
+## Cross-Milestone Trends
+
+| Metric | v1.0 | v1.1 |
+|--------|------|------|
+| Phases | 5 | 3 (6,7,10) |
+| Plans | 22 | 8 |
+| Tests | 95+ | 43+23=66 |
+| UAT Gaps Found at Close | 1 (minor UI) | 4 (2 blockers) |
+| Post-ship fixes needed | 0 | 1 phase (Phase 10) |
+| Requirements hit rate | 85% (17/20) | 100% (5/5 after Phase 10) |
+
+**Trend:** Test coverage is growing but integration testing gaps persist. The post-ship audit workflow is becoming a reliable backstop. Consider adding cross-phase integration tests to the plan checklist for v2.0.