Bug-fix batch, answer thread polish, and CI fixes

.cursor/skills/cursor-codebase-indexing/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: cursor-codebase-indexing
+description: 'Set up and optimize Cursor codebase indexing for semantic code search
+  and @Codebase queries.
+
+  Triggers on "cursor index", "codebase indexing", "index codebase", "cursor semantic
+  search",
+
+  "@codebase", "cursor embeddings".
+
+  '
+allowed-tools: Read, Write, Edit, Bash(cmd:*)
+version: 1.0.0
+license: MIT
+author: Jeremy Longshore <jeremy@intentsolutions.io>
+tags:
+  - saas
+  - cursor
+  - cursor-codebase
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
+---
+
+# Cursor Codebase Indexing
+
+Set up and optimize Cursor's codebase indexing system. Indexing creates embeddings of your code, enabling `@Codebase` semantic search and improving AI context awareness across Chat, Composer, and Agent mode.
+
+## How Indexing Works
+
+```
+Your Code Files
+      │
+      ▼
+  Syntax Chunking ─── splits files into meaningful code blocks
+      │
+      ▼
+  Embedding Generation ─── converts chunks to vector representations
+      │
+      ▼
+  Vector Storage (Turbopuffer) ─── cloud-hosted nearest-neighbor search
+      │
+      ▼
+  @Codebase Query ─── your question → embedding → similarity search → relevant chunks
+```
+
+### Key Architecture Details
+
+- **Merkle tree** for change detection: only modified files are re-indexed (every 10 minutes)
+- **No plaintext storage**: code is not stored server-side; only embeddings and obfuscated metadata
+- **Privacy Mode compatible**: with Privacy Mode on, embeddings are computed without retaining source code
+- Indexing runs in the background; small projects complete in seconds, large projects (50K+ files) may take hours initially
+
+## Initial Setup
+
+1. Open your project in Cursor
+2. Indexing starts automatically on first open
+3. Check status: look at the bottom status bar for "Indexing..." indicator
+4. View indexed files: `Cursor Settings` > `Features` > `Codebase Indexing` > `View included files`
+
+### Verify Indexing Status
+
+The status bar shows:
+
+- **"Indexing..."** with progress indicator -- initial indexing in progress
+- **"Indexed"** -- indexing complete, `@Codebase` queries are available
+- No indicator -- indexing may be disabled or not started
+
+## Configuration
+
+### .cursorignore
+
+Exclude files from indexing and AI features. Place in project root. Uses `.gitignore` syntax:
+
+```gitignore
+# .cursorignore
+
+# Build artifacts (large, not useful for AI context)
+dist/
+build/
+out/
+.next/
+target/
+
+# Dependencies
+node_modules/
+vendor/
+venv/
+.venv/
+
+# Generated files
+*.min.js
+*.min.css
+*.bundle.js
+*.map
+*.lock
+
+# Large data files
+*.csv
+*.sql
+*.sqlite
+*.parquet
+fixtures/
+seed-data/
+
+# Secrets (defense in depth -- also use .gitignore)
+.env*
+**/secrets/
+**/credentials/
+```
+
+### .cursorindexingignore
+
+Exclude files from indexing only but keep them accessible to AI features when explicitly referenced:
+
+```gitignore
+# .cursorindexingignore
+
+# Large test fixtures -- don't index, but allow @Files reference
+tests/fixtures/
+e2e/recordings/
+
+# Documentation build output
+docs/.vitepress/dist/
+```
+
+**Difference:** `.cursorignore` hides files from both indexing and AI features. `.cursorindexingignore` only excludes from the index; files can still be referenced via `@Files`.
+
+### Default Exclusions
+
+Cursor automatically excludes everything in `.gitignore`. You only need `.cursorignore` for files tracked by git that you want to exclude from AI.
+
+## Using the Index
+
+### @Codebase Queries
+
+Ask semantic questions about your entire codebase:
+
+```
+@Codebase where is user authentication handled?
+
+@Codebase show me all API endpoints that accept file uploads
+
+@Codebase how does the payment processing flow work?
+
+@Codebase find all places where we connect to Redis
+```
+
+`@Codebase` performs a nearest-neighbor search using your question's embedding. It returns the most semantically similar code chunks, even if they do not contain the exact keywords you used.
+
+### @Codebase vs @Files vs Text Search
+
+| Method         | When to Use                             | Context Cost        |
+| -------------- | --------------------------------------- | ------------------- |
+| `@Codebase`    | Discovery -- you don't know which files | High (many chunks)  |
+| `@Files`       | You know exactly which file             | Low (one file)      |
+| `@Folders`     | You know the directory                  | Medium-High         |
+| `Ctrl+Shift+F` | Exact text/regex match                  | N/A (editor search) |
+
+Use `@Codebase` for discovery, then switch to `@Files` once you know where the code lives.
+
+## Optimization for Large Projects
+
+### Monorepo Strategy
+
+For monorepos with many packages, open the specific package directory instead of the root:
+
+```bash
+# Instead of opening the entire monorepo:
+cursor /path/to/monorepo           # Indexes everything -- slow
+
+# Open the specific package:
+cursor /path/to/monorepo/packages/api   # Indexes only this package -- fast
+```
+
+Or use `.cursorignore` at the root to exclude packages you are not actively working on:
+
+```gitignore
+# .cursorignore -- monorepo, focus on api and shared
+packages/web/
+packages/mobile/
+packages/admin/
+# packages/api/    ← not listed, so it IS indexed
+# packages/shared/ ← not listed, so it IS indexed
+```
+
+### Re-Indexing
+
+If search results are stale or indexing appears stuck:
+
+1. `Cmd+Shift+P` > `Cursor: Resync Index`
+2. Wait for status bar to show indexing progress
+3. If that fails, delete the local cache:
+   - macOS: `~/Library/Application Support/Cursor/Cache/`
+   - Linux: `~/.config/Cursor/Cache/`
+   - Windows: `%APPDATA%\Cursor\Cache\`
+4. Restart Cursor and allow full re-index
+
+### File Watcher Limits (Linux)
+
+On Linux, large projects may hit the file watcher limit:
+
+```bash
+# Check current limit
+cat /proc/sys/fs/inotify/max_user_watches
+
+# Increase (temporary)
+sudo sysctl fs.inotify.max_user_watches=524288
+
+# Increase (permanent)
+echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
+sudo sysctl -p
+```
+
+## Enterprise Considerations
+
+- **Data residency**: Embeddings are stored in Turbopuffer (cloud). Obfuscated filenames and no plaintext code, but metadata exists
+- **Privacy Mode**: With Privacy Mode on, embeddings are computed with zero data retention at the provider
+- **Air-gapped environments**: Indexing requires network access to Cursor's embedding API. Not available offline
+- **Indexing scope**: Only files in the currently open workspace are indexed. Closing a project removes its index from active queries
+
+## Troubleshooting
+
+| Symptom                      | Cause                               | Fix                              |
+| ---------------------------- | ----------------------------------- | -------------------------------- |
+| @Codebase returns no results | Index not built                     | Wait for "Indexed" in status bar |
+| Search misses known files    | File in .gitignore or .cursorignore | Check ignore files               |
+| Indexing stuck at N%         | Large project or network issue      | Resync index via Command Palette |
+| Stale results after refactor | Index not yet updated               | Wait 10 min or manual resync     |
+| High CPU during indexing     | Initial embedding computation       | Normal for first run; subsides   |
+
+## Resources
+
+- [Codebase Indexing Docs](https://docs.cursor.com/context/codebase-indexing)
+- [Ignore Files](https://docs.cursor.com/context/ignore-files)
+- [Secure Codebase Indexing](https://cursor.com/blog/secure-codebase-indexing)

.cursorignore

@@ -0,0 +1,42 @@
+# Cursor semantic index exclusions — keep search focused on source, not artifacts.
+# Mirrors .gitignore noise; Cursor still indexes tracked source under src/, worker/, scripts/, supabase/.
+
+node_modules/
+.next/
+out/
+build/
+coverage/
+output/
+test-results/
+playwright-report/
+playwright-cli/
+.playwright-cli/
+playwright/.auth/
+
+# Local env and secrets
+.env*
+
+# Generated / machine-local
+*.tsbuildinfo
+sample-documents/
+tmp/
+.tmp-visual/
+.codex-screenshots/
+artifacts/
+scratch/
+.qa-smoke/
+.impeccable/
+supabase/.temp/
+
+# Logs and PIDs
+*.log
+*.pid
+dev-server*.log
+worker-*.log
+
+# Python caches
+__pycache__/
+.pytest_cache/
+
+# Large binary / review scratch (not application logic)
+docs/mockups/

.cursorindexingignore

@@ -0,0 +1,12 @@
+# Exclude from Cursor semantic index only — still reachable via @Files when needed.
+
+# Golden eval fixtures (large JSON, low day-to-day search value)
+scripts/fixtures/
+
+# Playwright auth state and reports (already in .cursorignore via .gitignore patterns)
+playwright/.auth/
+playwright-report/
+
+# Local temp clones from tooling (if present)
+.tmp-skills-clone/
+.tmp-adeonir-skills/

.env.example

@@ -6,6 +6,8 @@ SUPABASE_PROJECT_REF=sjrfecxgysukkwxsowpy
 SUPABASE_PROJECT_NAME=Clinical KB Database
 NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=your-publishable-or-anon-key
 SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
+# Edge Function only (indexing-v3-agent cron auth). Not read by Next.js env.ts.
+# Set in Supabase Edge Function secrets / deployment env, not in the browser bundle.
 INDEXING_V3_AGENT_SECRET=your-long-random-cron-shared-secret
 
 # Local-only no-auth mode (development only).
@@ -23,6 +25,8 @@ INDEXING_V3_AGENT_SECRET=your-long-random-cron-shared-secret
 # to OpenAI for embeddings, captioning, and grounded answer generation.
 OPENAI_API_KEY=replace-with-openai-api-key
 OPENAI_EMBEDDING_MODEL=text-embedding-3-small
+# Must match vector(N) in supabase/schema.sql. Do not change without a migration.
+EMBEDDING_DIMENSIONS=1536
 OPENAI_ANSWER_MODEL=gpt-5.5
 OPENAI_FAST_ANSWER_MODEL=gpt-5.5
 # Strong tier stays on the standard (non-pro) model; fast vs strong differ by reasoning effort.
@@ -62,6 +66,11 @@ RAG_SEARCH_CACHE_TTL_MS=60000
 RAG_SEARCH_CACHE_SIZE=200
 RAG_AWAIT_QUERY_LOGS=false
 
+# Privacy / production safety
+# Explicit demo opt-in. Blocked by npm run check:production-readiness in production.
+#NEXT_PUBLIC_DEMO_MODE=false
+# Persist raw clinical query text in logs. Default off; blocked in production readiness.
+#RAG_PERSIST_RAW_QUERY_TEXT=false
 # Server-side key for the redacted query-hash placeholder (min 16 chars).
 # When set, stored query hashes are HMAC-SHA256 keyed pseudonyms — not
 # offline-reversible and not correlatable outside this deployment. Strongly
@@ -92,7 +101,7 @@ WORKER_HEALTH_BACKOFF_MS=120000
 WORKER_MAX_CLAIM_FAILURES=3
 WORKER_PROGRESS_UPDATE_MIN_INTERVAL_MS=60000
 WORKER_MAX_CAPTIONED_IMAGES_PER_DOCUMENT=15
-WORKER_MAX_CAPTIONED_IMAGES_PER_PAGE=4
+WORKER_MAX_CAPTIONED_IMAGES_PER_PAGE=2
 WORKER_VISION_CONCURRENCY=4
 WORKER_INLINE_ENRICHMENT=false
 PYTHON_BIN=python

.gitignore

@@ -68,6 +68,7 @@ next-env.d.ts
 
 # agent/QA artifacts
 .codex-screenshots/
+/docs/mockups/
 # design/UX review scratch dumps (favourites-review, tools-page-review, etc.) — never commit
 artifacts/
 # local hook tool cache — machine-local, never commit

AGENTS.md

@@ -253,7 +253,7 @@ After completing `upload`, summarize the current branch and worktree state, whet
 ## Codex productivity defaults
 
 - Treat terse prompts as workflow shortcuts when the intent is clear. If the user says `run`, execute `npm run ensure`, verify the project identity through that helper, and return the printed local URL without a long log dump.
-- For non-trivial changes, start from concrete repo state: branch, `git status`, relevant package scripts, recent failures, and local logs such as `dev-server.log` when runtime behavior is involved.
+- For non-trivial changes, start from concrete repo state: branch, `git status`, relevant package scripts, recent failures, and local logs such as `dev-server.log` when runtime behavior is involved. For architecture and module orientation, read `docs/codebase-index.md` (routes: `docs/site-map.md`).
 - For UI, browser, styling, routing, accessibility, or screenshot work, run `npm run ensure` before opening the app, then use browser QA and the smallest relevant UI proof before broader gates.
 - Prefer the smallest failing check first. For this repo, use focused Vitest or Playwright targets before widening to `npm run verify:cheap`, `npm run verify:ui`, or `npm run verify:release`.
 - When the user says `safely`, preserve unrelated staged, unstaged, and untracked work; stop only clearly repo-owned transient processes; and verify the result instead of doing broad cleanup.

COLOR_REDESIGN_PLAN.md

@@ -1,3 +1,7 @@
+> **SUPERSEDED — historical exploration only.** Do not implement from this file.
+> Active design direction: [`docs/redesign/02-design-direction.md`](docs/redesign/02-design-direction.md)
+> (Clinical White / Aegean Graphite).
+
 # Luxury Black-First Color Redesign Plan (Global UI Polish)
 
 ## 1) Intent