From f86ae205a9a05ff4377e9c8b0814039e08f16342 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 00:26:54 +0800
Subject: [PATCH 01/16] feat: add image generation metadata re-stamp script

---
 package.json                                 |   1 +
 scripts/reindex-image-generation-metadata.ts | 247 +++++++++++++++++++
 2 files changed, 248 insertions(+)
 create mode 100644 scripts/reindex-image-generation-metadata.ts

diff --git a/package.json b/package.json
index 987bcba5a..e44f6bc8a 100644
--- a/package.json
+++ b/package.json
@@ -71,6 +71,7 @@
     "reindex": "tsx scripts/reindex.ts",
     "reindex:health": "tsx scripts/reindex-health.ts",
     "reindex:cleanup-staged": "tsx scripts/cleanup-abandoned-reindex-generations.ts",
+    "images:re-stamp-generation": "tsx scripts/reindex-image-generation-metadata.ts",
     "supabase:recovery-status": "tsx scripts/supabase-recovery-status.ts",
     "promote:query-misses": "tsx scripts/promote-query-misses.ts",
     "promote:public-documents": "tsx scripts/promote-public-documents.ts",
diff --git a/scripts/reindex-image-generation-metadata.ts b/scripts/reindex-image-generation-metadata.ts
new file mode 100644
index 000000000..a537f1487
--- /dev/null
+++ b/scripts/reindex-image-generation-metadata.ts
@@ -0,0 +1,247 @@
+import { loadEnvConfig } from "@next/env";
+import { confirm } from "./cli-utils";
+import { committedIndexGeneration, metadataRecord } from "@/lib/reindex-pipeline";
+import { assertSupabaseHealthy, probeSupabaseHealth } from "@/lib/supabase/health";
+import { checkSupabaseProjectConfig, formatSupabaseProjectCheck } from "@/lib/supabase/project";
+import { createAdminClient } from "@/lib/supabase/admin";
+import { requireServerEnv } from "@/lib/env";
+
+loadEnvConfig(process.cwd());
+
+type Args = {
+  documentId: string | null;
+  ownerId: string | null;
+  allOwners: boolean;
+  limit: number;
+  write: boolean;
+  confirm: boolean;
+};
+
+type DocumentRow = {
+  id: string;
+  title: string | null;
+  file_name: string | null;
+  metadata: unknown;
+};
+
+type ImageRow = {
+  id: string;
+  index_generation_id: string | null;
+  metadata: unknown;
+};
+
+type ImagePatch = {
+  imageId: string;
+  indexGenerationId: string;
+  metadata: Record<string, unknown>;
+};
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    documentId: null,
+    ownerId: process.env.RAG_EVAL_OWNER_ID ?? process.env.LOCAL_NO_AUTH_OWNER_ID ?? null,
+    allOwners: false,
+    limit: 25,
+    write: false,
+    confirm: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--all-owners") {
+      args.allOwners = true;
+      args.ownerId = null;
+      continue;
+    }
+    if (token === "--write") {
+      args.write = true;
+      continue;
+    }
+    if (token === "--confirm") {
+      args.confirm = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) {
+      if (token === "--document-id" || token === "--owner-id" || token === "--limit") {
+        throw new Error(`Missing value for ${token}`);
+      }
+      continue;
+    }
+    if (token === "--document-id") args.documentId = value;
+    if (token === "--owner-id") args.ownerId = value;
+    if (token === "--limit") args.limit = Number.parseInt(value, 10);
+    if (token === "--document-id" || token === "--owner-id" || token === "--limit") {
+      index += 1;
+    }
+  }
+
+  if (!Number.isFinite(args.limit) || args.limit <= 0) {
+    throw new Error("--limit must be a positive integer.");
+  }
+  if (!args.documentId && !args.ownerId && !args.allOwners) {
+    throw new Error("Provide --document-id, --owner-id, or --all-owners.");
+  }
+  return args;
+}
+
+function rowNeedsRefresh(row: ImageRow, committedGeneration: string) {
+  const rowMetadataGeneration = committedIndexGeneration(row.metadata);
+  if (row.index_generation_id !== null && row.index_generation_id !== committedGeneration) return true;
+  return row.index_generation_id === null
+    ? rowMetadataGeneration !== committedGeneration
+    : rowMetadataGeneration !== committedGeneration;
+}
+
+async function loadDocuments(args: {
+  supabase: ReturnType<typeof createAdminClient>;
+  ownerId: string | null;
+  documentId: string | null;
+  allOwners: boolean;
+  limit: number;
+}) {
+  let query = args.supabase.from("documents").select("id,title,file_name,metadata").eq("status", "indexed").order("created_at", {
+    ascending: false,
+  });
+
+  if (args.documentId) query = query.eq("id", args.documentId);
+  if (args.ownerId) query = query.eq("owner_id", args.ownerId);
+  if (!args.allOwners && !args.ownerId && !args.documentId) return [];
+
+  const { data, error } = await query.limit(args.limit);
+  if (error) throw new Error(error.message);
+  return (data ?? []) as DocumentRow[];
+}
+
+async function loadImages(args: {
+  supabase: ReturnType<typeof createAdminClient>;
+  documentId: string;
+}) {
+  const rows: ImageRow[] = [];
+  for (let offset = 0; ; offset += 1000) {
+    const { data, error } = await args.supabase
+      .from("document_images")
+      .select("id,index_generation_id,metadata")
+      .eq("document_id", args.documentId)
+      .range(offset, offset + 999);
+    if (error) throw new Error(error.message);
+    const page = (data ?? []) as ImageRow[];
+    rows.push(...page);
+    if (page.length < 1000) break;
+  }
+  return rows;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  requireServerEnv();
+
+  const projectCheck = checkSupabaseProjectConfig(
+    {
+      NEXT_PUBLIC_SUPABASE_URL: process.env.NEXT_PUBLIC_SUPABASE_URL,
+      SUPABASE_PROJECT_REF: process.env.SUPABASE_PROJECT_REF,
+      SUPABASE_PROJECT_NAME: process.env.SUPABASE_PROJECT_NAME,
+    },
+    { requireMetadata: true },
+  );
+  if (projectCheck.status === "mismatch") {
+    throw new Error(`Supabase project mismatch: ${formatSupabaseProjectCheck(projectCheck)}`);
+  }
+  if (projectCheck.warnings.length > 0) {
+    console.log(`Supabase project warning: ${projectCheck.warnings.join(" ; ")}`);
+  }
+
+  const supabase = createAdminClient();
+  console.log(`Target project: ${projectCheck.expected.name} (${projectCheck.expected.ref})`);
+  assertSupabaseHealthy(await probeSupabaseHealth(supabase), "Re-stamp document image generation");
+
+  const documents = await loadDocuments({
+    supabase,
+    ownerId: args.ownerId,
+    documentId: args.documentId,
+    allOwners: args.allOwners,
+    limit: args.limit,
+  });
+
+  if (documents.length === 0) {
+    console.log("No indexed documents matched the target filter.");
+    return;
+  }
+
+  const label = args.allOwners ? "all owners" : args.documentId ? `document ${args.documentId}` : `owner ${args.ownerId}`;
+  console.log(`Loaded ${documents.length} indexed document(s) for ${label} inspection.`);
+
+  const patches: ImagePatch[] = [];
+  let inspectedImageCount = 0;
+  let documentsWithCandidates = 0;
+
+  for (const document of documents) {
+    const committedGeneration = committedIndexGeneration(document.metadata);
+    if (!committedGeneration) {
+      console.log(`SKIP ${document.title ?? document.file_name ?? document.id}: missing index_generation_id in documents.metadata`);
+      continue;
+    }
+
+    const images = await loadImages({ supabase, documentId: document.id });
+    const staleRows = images.filter((image) => rowNeedsRefresh(image, committedGeneration));
+    inspectedImageCount += images.length;
+
+    if (staleRows.length === 0) {
+      console.log(`OK   ${document.title ?? document.file_name ?? document.id}: ${images.length} image rows aligned`);
+      continue;
+    }
+
+    documentsWithCandidates += 1;
+    console.log(
+      `MISMATCH ${document.title ?? document.file_name ?? document.id}: ${staleRows.length}/${images.length} image rows need re-stamp`,
+    );
+    for (const row of staleRows) {
+      patches.push({
+        imageId: row.id,
+        indexGenerationId: committedGeneration,
+        metadata: { ...metadataRecord(row.metadata), index_generation_id: committedGeneration },
+      });
+    }
+  }
+
+  if (patches.length === 0) {
+    console.log(`\nNo stale image generation metadata found. Images inspected: ${inspectedImageCount}.`);
+    return;
+  }
+
+  console.log(`\nStale rows found: ${patches.length} image rows across ${documentsWithCandidates} documents.`);
+  if (!args.write) {
+    console.log("Dry run complete. Run with --write --confirm to apply changes.");
+    return;
+  }
+
+  const approved = args.confirm || (await confirm(`Apply re-stamp to ${patches.length} image rows?`));
+  if (!approved) {
+    console.log("Operation cancelled. No rows updated.");
+    return;
+  }
+
+  for (let start = 0; start < patches.length; start += 8) {
+    const batch = patches.slice(start, start + 8);
+    await Promise.all(
+      batch.map(async (patch) => {
+        const { error } = await supabase
+          .from("document_images")
+          .update({
+            index_generation_id: patch.indexGenerationId,
+            metadata: patch.metadata,
+          })
+          .eq("id", patch.imageId);
+        if (error) throw new Error(`Failed to re-stamp image row ${patch.imageId}: ${error.message}`);
+      }),
+    );
+  }
+
+  console.log(`Completed re-stamp. Updated ${patches.length} image rows across ${documentsWithCandidates} documents.`);
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

From bac17526dd674d4e5451949d92000b51e768b4d0 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 14:31:00 +0800
Subject: [PATCH 02/16] chore: reconcile ingestion RPC execute privileges,
 schema.sql and drift manifest

---
 .cursor/skills/accessibility-review/SKILL.md  |  18 ++
 .../skills/ai-architecture-review/SKILL.md    |  23 ++
 .cursor/skills/api-review/SKILL.md            |  28 ++
 .cursor/skills/code-quality-review/SKILL.md   |  19 ++
 .cursor/skills/design-review/SKILL.md         |  18 ++
 .../frontend-architecture-review/SKILL.md     |  18 ++
 .cursor/skills/performance-review/SKILL.md    |  18 ++
 .../skills/release-readiness-review/SKILL.md  |  20 ++
 .cursor/skills/repo-auditor/SKILL.md          |  15 +
 .cursor/skills/security-review/SKILL.md       |  20 ++
 .../CHANGELOG.md                              |  29 ++
 .../supabase-postgres-best-practices/SKILL.md |  22 +-
 .../references/_contributing.md               |  28 +-
 .../references/_sections.md                   |   8 -
 .../references/security-rls-performance.md    |  12 +-
 .cursor/skills/supabase/CHANGELOG.md          |  35 +++
 .cursor/skills/supabase/SKILL.md              |  45 ++-
 .cursor/skills/testing-review/SKILL.md        |  19 ++
 .cursor/skills/ux-review/SKILL.md             |  18 ++
 package.json                                  |   3 +
 scripts/compare-retrieval-eval.ts             |  87 ++++++
 scripts/embed-registry-records.ts             | 162 ++++++++++
 scripts/eval-retrieval.ts                     |  30 +-
 scripts/reindex-image-generation-metadata.ts  |  51 +++-
 scripts/seed-differential-records.ts          |  12 +
 scripts/seed-medication-records.ts            |  12 +
 scripts/seed-registry-records.ts              |  14 +
 src/lib/differential-seed.ts                  |  11 +-
 src/lib/differentials.ts                      |   4 +-
 src/lib/document-index-units.ts               |  78 ++++-
 src/lib/env.ts                                |   4 +
 src/lib/forms.ts                              |   2 +-
 src/lib/medication-seed.ts                    |  11 +-
 src/lib/rag.ts                                |  96 ++++--
 src/lib/registry-corpus.ts                    | 277 ++++++++++++++++++
 src/lib/registry-seed.ts                      |  11 +-
 src/lib/source-governance.ts                  |  17 +-
 src/lib/source-metadata.ts                    |   2 +
 src/lib/types.ts                              |   4 +-
 supabase/drift-allowlist.json                 |  23 +-
 supabase/drift-manifest.json                  |  14 +-
 ...000_reconcile_ingestion_rpc_privileges.sql |  12 +
 supabase/schema.sql                           |  21 ++
 tests/document-index-units.test.ts            |  35 +++
 tests/registry-corpus.test.ts                 |  70 +++++
 tests/source-governance.test.ts               |  38 +++
 46 files changed, 1391 insertions(+), 123 deletions(-)
 create mode 100644 .cursor/skills/accessibility-review/SKILL.md
 create mode 100644 .cursor/skills/ai-architecture-review/SKILL.md
 create mode 100644 .cursor/skills/api-review/SKILL.md
 create mode 100644 .cursor/skills/code-quality-review/SKILL.md
 create mode 100644 .cursor/skills/design-review/SKILL.md
 create mode 100644 .cursor/skills/frontend-architecture-review/SKILL.md
 create mode 100644 .cursor/skills/performance-review/SKILL.md
 create mode 100644 .cursor/skills/release-readiness-review/SKILL.md
 create mode 100644 .cursor/skills/repo-auditor/SKILL.md
 create mode 100644 .cursor/skills/security-review/SKILL.md
 create mode 100644 .cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
 create mode 100644 .cursor/skills/supabase/CHANGELOG.md
 create mode 100644 .cursor/skills/testing-review/SKILL.md
 create mode 100644 .cursor/skills/ux-review/SKILL.md
 create mode 100644 scripts/compare-retrieval-eval.ts
 create mode 100644 scripts/embed-registry-records.ts
 create mode 100644 src/lib/registry-corpus.ts
 create mode 100644 supabase/migrations/20260709150000_reconcile_ingestion_rpc_privileges.sql
 create mode 100644 tests/registry-corpus.test.ts

diff --git a/.cursor/skills/accessibility-review/SKILL.md b/.cursor/skills/accessibility-review/SKILL.md
new file mode 100644
index 000000000..209a598a9
--- /dev/null
+++ b/.cursor/skills/accessibility-review/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: accessibility-review
+description: Reviews keyboard navigation support, semantic HTML tags, drawer/dialog behaviors, focus management, and screen-reader standards. Use during UI audits.
+---
+
+# Accessibility Review Skill
+
+Use this skill when reviewing user interfaces to ensure compliance with a11y standards.
+
+## Review Checklist
+
+### 1. Keyboard & Focus Control
+- **Interactive Elements:** Verify all button-like and link-like components use semantic HTML elements (`<button>`, `<a>`) rather than `div` tags with onClick handlers.
+- **Focus Trapping:** Ensure modal dialogs, side drawers, and search overlays trap keyboard focus properly and support `Esc` key cancellation.
+
+### 2. ARIA & Reader Markup
+- **Labels:** Verify that icon-only buttons, custom inputs, and dynamic charts include appropriate `aria-label` or screen-reader descriptions.
+- **Table Structure:** Ensure data tables (like document table facts) use correct semantic tags (`<thead>`, `<tbody>`, `<th>`) for readable text-to-speech rendering.
diff --git a/.cursor/skills/ai-architecture-review/SKILL.md b/.cursor/skills/ai-architecture-review/SKILL.md
new file mode 100644
index 000000000..2a8f5c44b
--- /dev/null
+++ b/.cursor/skills/ai-architecture-review/SKILL.md
@@ -0,0 +1,23 @@
+---
+name: ai-architecture-review
+description: Reviews RAG flows, context assembly, model routing, structured outputs, safety filters, provenance, fallbacks, evals, cost, and latency. Use during retrieval or answer generation changes.
+---
+
+# AI Architecture Review Skill
+
+Use this skill when reviewing or modifying the RAG (Retrieval-Augmented Generation) pipeline, document retrieval, and LLM integrations.
+
+## Review Checklist
+
+### 1. Retrieval Quality & Provenance
+- **Hybrid Search:** Confirm queries use proper hybrid search patterns (pgvector + semantic/trigram matching) and respect user/organization boundaries.
+- **Provenance / Citations:** Ensure generated answers are strongly tied to source documents and include clean, traceable citation references.
+- **Fail-Closed Policy:** If no relevant documents are retrieved or verification fails, the system must degrade gracefully or return a clear "No evidence found" response rather than hallucinating.
+
+### 2. Model Routing & Timeout Logic
+- **Routing Rules:** Check that routing between fast and strong models follows defined rules (e.g. `RAG_PROVIDER_MODE`).
+- **Timeouts:** Ensure LLM calls are bounded by client and server-side timeouts (e.g., `OPENAI_ANSWER_TIMEOUT_MS`).
+
+### 3. Structured Output & Safety
+- **Schema Conformity:** Validate that LLM responses use strict schema structures (e.g., OpenAI structured JSON output) to prevent parsing errors.
+- **Safety Filters:** Check that toxicity, safety filters, and prompt injection mitigations are active on user inputs and LLM outputs.
diff --git a/.cursor/skills/api-review/SKILL.md b/.cursor/skills/api-review/SKILL.md
new file mode 100644
index 000000000..c491ac380
--- /dev/null
+++ b/.cursor/skills/api-review/SKILL.md
@@ -0,0 +1,28 @@
+---
+name: api-review
+description: Reviews API routes for routing contracts, input schema validation (Zod), JSON error taxonomies, request/response models, pagination, authentication, recoverability, and HTTP status codes. Use during API code changes or integrations.
+---
+
+# API Review Skill
+
+Use this skill when reviewing or modifying API routes, endpoints, or network boundaries within this repository (primarily under `src/app/api/`).
+
+## Review Checklist
+
+### 1. Request Validation
+- **Zod Schemas:** Ensure all incoming requests (`req.json()`, query parameters, route segments) are validated using strict Zod schemas.
+- **Fail Early:** Requests failing schema validation must return `400 Bad Request` immediately before running downstream DB or AI logic.
+- **Safety check:** Validate input boundaries (e.g., maximum string length, non-empty collections, limit boundaries on pagination).
+
+### 2. Error Handling & Taxonomy
+- **Closed Errors:** Avoid throwing raw database, library, or system errors to the client. Wrap exceptions in consistent JSON error envelopes.
+- **HTTP Semantics:** Use correct HTTP status codes (e.g., `401 Unauthorized` vs `403 Forbidden`, `404 Not Found` for missing resources, `429 Too Many Requests` for rate limits).
+- **Consistency:** Ensure error payloads follow a unified schema, containing a clear error code (e.g., `VALIDATION_FAILED`, `INTERNAL_ERROR`) and user-safe descriptions.
+
+### 3. Response Contracts
+- **Serialization:** Explicitly define the serialized JSON shape of the response. Avoid passing DB model instances directly to the frontend.
+- **Pagination:** For resource listing APIs, verify pagination params (`limit`, `offset` / `cursor`) are implemented, validated, and bounded.
+
+### 4. Authentication & Authorization
+- **Server-Side Enforcement:** Do not rely on client assertions. Re-authenticate user credentials (JWT / session cookies) server-side.
+- **Tenant Isolation:** Ensure fetched resources are filtered by the active user's identity (`user_id`).
diff --git a/.cursor/skills/code-quality-review/SKILL.md b/.cursor/skills/code-quality-review/SKILL.md
new file mode 100644
index 000000000..40567d068
--- /dev/null
+++ b/.cursor/skills/code-quality-review/SKILL.md
@@ -0,0 +1,19 @@
+---
+name: code-quality-review
+description: Reviews code quality, naming structures, control flow patterns, abstraction complexity, duplication, and maintainability. Use during general refactoring.
+---
+
+# Code Quality Review Skill
+
+Use this skill when auditing source files for maintainability, readability, and structural patterns.
+
+## Review Checklist
+
+### 1. Maintainability & Naming
+- **Clean Naming:** Ensure functions, variables, and database keys carry logical, self-describing names.
+- **Decomposition:** Look for bloated files/functions that should be decomposed. Keep modules focused on a single responsibility.
+- **Duplication (DRY):** Consolidate duplicate helper logic, styles, and configurations.
+
+### 2. Logic & Complexity
+- **Control Flow:** Simplify nested conditionals, deeply nested loops, or fragile edge-case handling.
+- **Dead Code:** Remove unused functions, comments, or commented-out code blocks left behind.
diff --git a/.cursor/skills/design-review/SKILL.md b/.cursor/skills/design-review/SKILL.md
new file mode 100644
index 000000000..ee1e4636b
--- /dev/null
+++ b/.cursor/skills/design-review/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: design-review
+description: Reviews layout density, theme adherence, typography, spacing, and visual consistency. Use during visual layout or CSS adjustments.
+---
+
+# Design Review Skill
+
+Use this skill when auditing UI styling, colors, layout structures, and spacing rules.
+
+## Review Checklist
+
+### 1. Style & Spacing Consistency
+- **Design System Tokens:** Ensure custom components utilize predefined design variables (colors, borders, shadows, font sizes) rather than ad-hoc inline styles.
+- **Layout Spacing:** Check for consistent paddings, margins, grid gaps, and alignment.
+
+### 2. Clinical Theme Adherence
+- **Layout Density:** Review components to confirm the visual target is dense, clean, calm, and fast to scan rather than overly flashy or visually expressive.
+- **Browser QA / Screenshot Verification:** For major UI changes, run a local dev server with `npm run ensure` and capture screenshots to verify cross-device visual fidelity.
diff --git a/.cursor/skills/frontend-architecture-review/SKILL.md b/.cursor/skills/frontend-architecture-review/SKILL.md
new file mode 100644
index 000000000..295b74593
--- /dev/null
+++ b/.cursor/skills/frontend-architecture-review/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: frontend-architecture-review
+description: Reviews Next/React boundaries, state ownership, duplicated client state, rendering contracts, and component boundaries. Use during frontend architecture refactoring.
+---
+
+# Frontend Architecture Review Skill
+
+Use this skill when reviewing Next.js App Router structures, component boundaries, state management, and React performance.
+
+## Review Checklist
+
+### 1. Next.js App Router Boundaries
+- **RSC vs. Client Components:** Ensure components are Server Components by default. Keep client-side logic (`use state`, `use effect`, browser APIs) isolated to leaf components marked with `"use client"`.
+- **Data Fetching:** Fetch data in Server Components or Server Actions where possible. Avoid calling internal `/api/...` endpoints directly from RSCs.
+
+### 2. State & Rendering
+- **State Duplication:** Avoid replicating URL/router state in local React state. Prefer URLSearchParams and next/navigation controls for search/filters.
+- **Rendering Waste:** Check for unnecessary context re-renders, un-memoized expensive calculations, or excessive component mount/unmount cycles.
diff --git a/.cursor/skills/performance-review/SKILL.md b/.cursor/skills/performance-review/SKILL.md
new file mode 100644
index 000000000..c8ae00f46
--- /dev/null
+++ b/.cursor/skills/performance-review/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: performance-review
+description: Reviews model latency/cost, cache policies, duplicate query coalescing, and heavy asset load performance. Use during optimization or profiling.
+---
+
+# Performance Review Skill
+
+Use this skill when reviewing query bottlenecks, database RPC latencies, client bundle sizes, or API cost overhead.
+
+## Review Checklist
+
+### 1. Database & API Latency
+- **Query Caching:** Verify that repetitive/expensive database fetches and RAG queries leverage caching layers (e.g. `rag_response_cache`).
+- **Index Optimization:** Ensure queries leverage appropriate indices (e.g., trigram/lexical text indexes, vector HNSW).
+
+### 2. LLM & Asset Loading
+- **Token Overhead:** Check that prompt sizes and context window limits are optimized to keep API costs down.
+- **Resource Streaming:** Ensure heavy document rendering, search lists, and PDF asset previews load incrementally or use lazy-loading controls.
diff --git a/.cursor/skills/release-readiness-review/SKILL.md b/.cursor/skills/release-readiness-review/SKILL.md
new file mode 100644
index 000000000..0760f9fa0
--- /dev/null
+++ b/.cursor/skills/release-readiness-review/SKILL.md
@@ -0,0 +1,20 @@
+---
+name: release-readiness-review
+description: Reviews build validation, linting/type-checking, target database checks, clinical governance preflight approvals, and environment variables. Use before staging or production releases.
+---
+
+# Release Readiness Review Skill
+
+Use this skill when preparing a branch for merging, pull request submission, or production deployment.
+
+## Review Checklist
+
+### 1. Build & Automation Checks
+- **Static Analysis:** Confirm `npm run lint` and `npm run typecheck` run clean.
+- **Verification Gates:** Ensure the appropriate verification scripts run successfully (`npm run verify:cheap` at minimum; `npm run verify:release` for full handoffs).
+- **Target database checks:** Run `npm run check:supabase-project` to confirm env targets match `Clinical KB Database` ref `sjrfecxgysukkwxsowpy`.
+
+### 2. Clinical Governance Compliance
+- **Preflight Verification:** Complete all checklist items in `.github/pull_request_template.md`.
+- **Secret Scan:** Confirm no private configuration files (`.env.local`), local debug logs, or keys are present in the git stage.
+- **Production Readiness Check:** Run `npm run check:production-readiness` for privacy, ingestion, or clinical behavior changes.
diff --git a/.cursor/skills/repo-auditor/SKILL.md b/.cursor/skills/repo-auditor/SKILL.md
new file mode 100644
index 000000000..577a06798
--- /dev/null
+++ b/.cursor/skills/repo-auditor/SKILL.md
@@ -0,0 +1,15 @@
+---
+name: repo-auditor
+description: Reviews module dependencies, broken imports, unused files, and structural cleanup. Use during repo-wide audits or refactoring.
+---
+
+# Repo Auditor Skill
+
+Use this skill when auditing the workspace layout, folder structures, imports, and dependencies.
+
+## Review Checklist
+
+### 1. Structural Audits
+- **Broken Imports:** Scan modified files for broken relative imports, incorrect library names, or obsolete modules.
+- **Unused Files:** Identify and safely remove files that are truly dead and not part of route mappings, active scripts, migrations, or test resources.
+- **Consolidation:** Check for identical or redundant configuration keys, environment variables, or scripts that can be safely merged.
diff --git a/.cursor/skills/security-review/SKILL.md b/.cursor/skills/security-review/SKILL.md
new file mode 100644
index 000000000..d58ce01e6
--- /dev/null
+++ b/.cursor/skills/security-review/SKILL.md
@@ -0,0 +1,20 @@
+---
+name: security-review
+description: Reviews credentials, token handling, JWT claims, service-role confinement, public error envelopes, Row-Level Security (RLS) policies, and private bucket access. Use during database, authentication, or network boundary edits.
+---
+
+# Security Review Skill
+
+Use this skill when reviewing code that touches authentication, database schemas, environment variables, storage, or external API gateways.
+
+## Review Checklist
+
+### 1. Key Confinement & Environment Safety
+- **Service Role Key:** Ensure the Supabase `service_role` key is never exposed to public clients. Never prefix variables containing secret keys with `NEXT_PUBLIC_`.
+- **Credential Storage:** Verify that credentials are not committed or hardcoded. Look for placeholder usage in `.env.example`.
+
+### 2. Database & Storage Safety
+- **Row-Level Security (RLS):** Ensure RLS is active on all public/exposed tables. Avoid deprecated checkers like `auth.role()` and prefer strict role predicates (`TO authenticated`).
+- **Owner Scope Verification:** Verify that API endpoints filter queries by the authenticated user's ID (`user_id`) to prevent unauthorized cross-tenant data access.
+- **Storage Buckets:** Verify that files uploaded to private buckets (`clinical-documents`, `clinical-images`) require validated user signatures for retrieval.
+- **Views:** Ensure Postgres views are created with security invokers (`WITH (security_invoker = true)`) so they respect RLS.
diff --git a/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
new file mode 100644
index 000000000..94aee4878
--- /dev/null
+++ b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
@@ -0,0 +1,29 @@
+# Changelog
+
+## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+
+## [1.2.0](https://github.com/supabase/agent-skills/compare/v1.1.1...v1.2.0) (2026-06-02)
+
+
+### Features
+
+* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
diff --git a/.cursor/skills/supabase-postgres-best-practices/SKILL.md b/.cursor/skills/supabase-postgres-best-practices/SKILL.md
index 07aa1b3a6..d9ef1949f 100644
--- a/.cursor/skills/supabase-postgres-best-practices/SKILL.md
+++ b/.cursor/skills/supabase-postgres-best-practices/SKILL.md
@@ -17,7 +17,6 @@ Comprehensive performance optimization guide for Postgres, maintained by Supabas
 ## When to Apply
 
 Reference these guidelines when:
-
 - Writing SQL queries or designing schemas
 - Implementing indexes or query optimization
 - Reviewing database performance issues
@@ -27,16 +26,16 @@ Reference these guidelines when:
 
 ## Rule Categories by Priority
 
-| Priority | Category                 | Impact      | Prefix      |
-| -------- | ------------------------ | ----------- | ----------- |
-| 1        | Query Performance        | CRITICAL    | `query-`    |
-| 2        | Connection Management    | CRITICAL    | `conn-`     |
-| 3        | Security & RLS           | CRITICAL    | `security-` |
-| 4        | Schema Design            | HIGH        | `schema-`   |
-| 5        | Concurrency & Locking    | MEDIUM-HIGH | `lock-`     |
-| 6        | Data Access Patterns     | MEDIUM      | `data-`     |
-| 7        | Monitoring & Diagnostics | LOW-MEDIUM  | `monitor-`  |
-| 8        | Advanced Features        | LOW         | `advanced-` |
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Query Performance | CRITICAL | `query-` |
+| 2 | Connection Management | CRITICAL | `conn-` |
+| 3 | Security & RLS | CRITICAL | `security-` |
+| 4 | Schema Design | HIGH | `schema-` |
+| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
+| 6 | Data Access Patterns | MEDIUM | `data-` |
+| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
+| 8 | Advanced Features | LOW | `advanced-` |
 
 ## How to Use
 
@@ -49,7 +48,6 @@ references/_sections.md
 ```
 
 Each rule file contains:
-
 - Brief explanation of why it matters
 - Incorrect SQL example with explanation
 - Correct SQL example with explanation
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
index ba1a4e892..1c055aff9 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
@@ -27,7 +27,7 @@ to recognize anti-patterns.
 
 Include specific metrics. Helps agents prioritize fixes.
 
-**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
+**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1" 
 **Bad:** "Faster", "Better", "More efficient"
 
 ### 4. Self-Contained Examples
@@ -105,7 +105,9 @@ Most references should focus on pure SQL patterns. This keeps examples portable.
 
 ```typescript
 for (const user of users) {
-  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [user.id]);
+  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
+    user.id,
+  ]);
 }
 ```
 ````
@@ -113,21 +115,23 @@ for (const user of users) {
 **Correct (batch query):**
 
 ```typescript
-const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [userIds]);
+const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
+  userIds,
+]);
 ```
 
 ---
 
 ## Impact Level Guidelines
 
-| Level           | Improvement | Use When                                                                 |
-| --------------- | ----------- | ------------------------------------------------------------------------ |
-| **CRITICAL**    | 10-100x     | Missing indexes, connection exhaustion, sequential scans on large tables |
-| **HIGH**        | 5-20x       | Wrong index types, poor partitioning, missing covering indexes           |
-| **MEDIUM-HIGH** | 2-5x        | N+1 queries, inefficient pagination, RLS optimization                    |
-| **MEDIUM**      | 1.5-3x      | Redundant indexes, query plan instability                                |
-| **LOW-MEDIUM**  | 1.2-2x      | VACUUM tuning, configuration tweaks                                      |
-| **LOW**         | Incremental | Advanced patterns, edge cases                                            |
+| Level | Improvement | Use When |
+|-------|-------------|----------|
+| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
+| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
+| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
+| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
+| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
+| **LOW** | Incremental | Advanced patterns, edge cases |
 
 ---
 
@@ -163,4 +167,4 @@ Before submitting a reference:
 - [ ] Comments explain _why_, not _what_
 - [ ] Trade-offs mentioned if applicable
 - [ ] Reference links included
-- [ ] `mise run test` passes
+- [ ] `pnpm test` passes
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/_sections.md b/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
index 42c16e707..8ba57c23e 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
@@ -7,41 +7,33 @@ Take the examples below as pure demonstrative. Replace each section with the act
 ---
 
 ## 1. Query Performance (query)
-
 **Impact:** CRITICAL
 **Description:** Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.
 
 ## 2. Connection Management (conn)
-
 **Impact:** CRITICAL
 **Description:** Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.
 
 ## 3. Security & RLS (security)
-
 **Impact:** CRITICAL
 **Description:** Row-Level Security policies, privilege management, and authentication patterns.
 
 ## 4. Schema Design (schema)
-
 **Impact:** HIGH
 **Description:** Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.
 
 ## 5. Concurrency & Locking (lock)
-
 **Impact:** MEDIUM-HIGH
 **Description:** Transaction management, isolation levels, deadlock prevention, and lock contention patterns.
 
 ## 6. Data Access Patterns (data)
-
 **Impact:** MEDIUM
 **Description:** N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.
 
 ## 7. Monitoring & Diagnostics (monitor)
-
 **Impact:** LOW-MEDIUM
 **Description:** Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.
 
 ## 8. Advanced Features (advanced)
-
 **Impact:** LOW
 **Description:** Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md b/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
index b32d92f7e..c3c7c416d 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
@@ -29,9 +29,11 @@ create policy orders_policy on orders
 
 Use security definer functions for complex checks:
 
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+
 ```sql
--- Create helper function (runs as definer, bypasses RLS)
-create or replace function is_team_member(team_id bigint)
+-- Create helper function in a private schema
+create or replace function private.is_team_member(team_id bigint)
 returns boolean
 language sql
 security definer
@@ -39,13 +41,17 @@ set search_path = ''
 as $$
   select exists (
     select 1 from public.team_members
+    -- always check the calling user's identity inside the function
     where team_id = $1 and user_id = (select auth.uid())
   );
 $$;
 
+-- Revoke direct execution from public roles
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+
 -- Use in policy (indexed lookup, not per-row check)
 create policy team_orders_policy on orders
-  using ((select is_team_member(team_id)));
+  using ((select private.is_team_member(team_id)));
 ```
 
 Always add indexes on columns used in RLS policies:
diff --git a/.cursor/skills/supabase/CHANGELOG.md b/.cursor/skills/supabase/CHANGELOG.md
new file mode 100644
index 000000000..a62015d35
--- /dev/null
+++ b/.cursor/skills/supabase/CHANGELOG.md
@@ -0,0 +1,35 @@
+# Changelog
+
+## [0.1.4](https://github.com/supabase/agent-skills/compare/v0.1.3...v0.1.4) (2026-06-05)
+
+
+### Features
+
+* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+
+## [0.1.3](https://github.com/supabase/agent-skills/compare/v0.1.2...v0.1.3) (2026-06-02)
+
+
+### Features
+
+* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+
+
+### Bug Fixes
+
+* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
diff --git a/.cursor/skills/supabase/SKILL.md b/.cursor/skills/supabase/SKILL.md
index b64f55c2a..198c98550 100644
--- a/.cursor/skills/supabase/SKILL.md
+++ b/.cursor/skills/supabase/SKILL.md
@@ -3,15 +3,17 @@ name: supabase
 description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector)."
 metadata:
   author: supabase
-  version: "0.1.0"
+  version: "0.1.2"
 ---
 
 # Supabase
 
 ## Core Principles
 
-**1. Supabase changes frequently — verify against current docs before implementing.**
-Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions. Before implementing, look up the relevant topic using the documentation access methods below.
+**1. Supabase changes frequently — verify against changelog and current docs before implementing.**
+Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions.
+
+First, fetch `https://supabase.com/changelog.md` (a lightweight summary index — not a heavy pull), scan for `breaking-change` tags relevant to your task, and follow the linked page for any that apply. Then look up the relevant topic using the documentation access methods below.
 
 **2. Verify your work.**
 After implementing any fix, run a test query to confirm the change works. A fix without verification is incomplete.
@@ -19,10 +21,16 @@ After implementing any fix, run a test query to confirm the change works. A fix
 **3. Recover from errors, don't loop.**
 If an approach fails after 2-3 attempts, stop and reconsider. Try a different method, check documentation, inspect the error more carefully, and review relevant logs when available. Supabase issues are not always solved by retrying the same command, and the answer is not always in the logs, but logs are often worth checking before proceeding.
 
-**4. RLS by default in exposed schemas.**
-Enable RLS on every table in any exposed schema, especially `public`. This is critical in Supabase because tables in exposed schemas can be reachable through the Data API. For private schemas, prefer RLS as defense in depth. After enabling RLS, create policies that match the actual access model rather than defaulting every table to the same `auth.uid()` pattern.
+**4. Exposing tables to the Data API:** Depending on the user's [Data API settings](https://supabase.com/dashboard/project/<ref>/integrations/data_api/settings), newly created tables may not be automatically exposed via the Data (REST) API. If this is the case, `anon` and `authenticated` roles will need to be explicitly granted access.
+
+> Note that this is separate from RLS, which controls which _rows_ are visible once a table is accessible, not whether the table is accessible at all.
+
+When a user reports a SQL-created table is unexpectedly inaccessible, check their Data API settings and whether the roles have been granted access via explicit `GRANT` SQL. When granting public (`anon`/`authenticated`) access, always enable RLS too. See [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md) for the full setup workflow.
 
-**5. Security checklist.**
+**5. RLS in exposed schemas.**
+Enable RLS on every table in any exposed schema, which includes `public` by default. This is critical in Supabase because tables in exposed schemas can be reachable through the Data API when the `anon`/`authenticated` roles have access (see [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md)). For private schemas, prefer RLS as defense in depth. After enabling RLS, create policies that match the actual access model rather than defaulting every table to the same `auth.uid()` pattern.
+
+**6. Security checklist.**
 When working on any Supabase task that touches auth, RLS, views, storage, or user data, run through this checklist. These are Supabase-specific security traps that silently create vulnerabilities:
 
 - **Auth and session security**
@@ -36,11 +44,34 @@ When working on any Supabase task that touches auth, RLS, views, storage, or use
 - **RLS, views, and privileged database code**
   - **Views bypass RLS by default.** In Postgres 15 and above, use `CREATE VIEW ... WITH (security_invoker = true)`. In older versions of Postgres, protect your views by revoking access from the `anon` and `authenticated` roles, or by putting them in an unexposed schema.
   - **UPDATE requires a SELECT policy.** In Postgres RLS, an UPDATE needs to first SELECT the row. Without a SELECT policy, updates silently return 0 rows — no error, just no change.
-  - **Do not put `security definer` functions in an exposed schema.** Keep them in a private or otherwise unexposed schema.
+  - **`auth.role()` is deprecated — use the `TO` clause instead.** Supabase has deprecated `auth.role()` in favour of specifying the target role directly on the policy with `TO authenticated` or `TO anon`. Beyond deprecation, `auth.role() = 'authenticated'` breaks silently when anonymous sign-ins are enabled, because anonymous users carry the `authenticated` Postgres role and pass the check regardless of whether the user is genuinely signed in.
+    ```sql
+    -- Deprecated (do not use)
+    create policy "example" on table_name for select
+    using ( auth.role() = 'authenticated' );
+    ```
+  - **`TO authenticated` alone is authentication without authorization (BOLA / IDOR).** Using `TO authenticated` only checks the role — it does not restrict which rows a user can access. The correct pattern combines `TO authenticated` with an ownership predicate in `USING`:
+    ```sql
+    create policy "example" on table_name for select
+    to authenticated
+    using ( (select auth.uid()) = user_id );
+    ```
+  - **UPDATE policies require both `USING` and `WITH CHECK`.** Without `WITH CHECK`, a user can reassign a row's `user_id` to another user:
+    ```sql
+    create policy "example" on table_name for update
+    to authenticated
+    using ( (select auth.uid()) = user_id )
+    with check ( (select auth.uid()) = user_id );
+    ```
+  - **`SECURITY DEFINER` functions bypass RLS.** A `SECURITY DEFINER` function runs with its creator's privileges — typically a role with `bypassrls` (e.g., `postgres`). Never add `SECURITY DEFINER` to resolve a permission error; it silently removes access control without fixing the underlying cause. Prefer `SECURITY INVOKER`.
+  - **`SECURITY DEFINER` functions in `public` are callable by all roles.** Postgres grants `EXECUTE` to `PUBLIC` by default for every new function, so any `SECURITY DEFINER` function in `public` is a public API endpoint callable by `anon` and `authenticated` (which inherit from `PUBLIC`) without any additional grant. When `SECURITY DEFINER` is genuinely needed (e.g., bypassing RLS on an internal lookup table), keep the function in a non-exposed schema, always include an `auth.uid()` check in the function body, and run `supabase db advisors` after making changes.
 
 - **Storage access control**
   - **Storage upsert requires INSERT + SELECT + UPDATE.** Granting only INSERT allows new uploads but file replacement (upsert) silently fails. You need all three.
 
+- **Dependency and supply-chain security**
+  - **Always pin package versions and commit lockfiles** when installing Supabase packages (`supabase-js`, `@supabase/ssr`, `supabase-py`, etc.). See the [npm security guide](https://supabase.com/docs/guides/security/npm-security.md) for the full checklist.
+
 For any security concern not covered above, fetch the Supabase product security index: `https://supabase.com/docs/guides/security/product-security.md`
 
 ## Supabase CLI
diff --git a/.cursor/skills/testing-review/SKILL.md b/.cursor/skills/testing-review/SKILL.md
new file mode 100644
index 000000000..c72c29671
--- /dev/null
+++ b/.cursor/skills/testing-review/SKILL.md
@@ -0,0 +1,19 @@
+---
+name: testing-review
+description: Reviews unit/integration/E2E coverage, checks for fragile/flaky tests, asserts clinical safety checks, and reviews verification sequence. Use during test addition or refactoring.
+---
+
+# Testing Review Skill
+
+Use this skill when reviewing test coverage, testing harnesses, and test execution paths (Vitest + Playwright).
+
+## Review Checklist
+
+### 1. Test Harness Coverage
+- **Unit Tests:** Ensure new or modified utils, helper scripts, and backend libraries have corresponding Vitest unit tests (`*.test.ts`).
+- **E2E/UI Tests:** Verify frontend routes and interactive components are covered by Playwright specs (`ui-*.spec.ts`).
+- **Clinical Safety Assertions:** Check that tests verify critical safety boundaries, such as correct citation indexing, fallback behavior on weak RAG evidence, and tenant data isolation.
+
+### 2. Flakiness & Mocking
+- **Mocking External APIs:** Ensure test flows do not hit live external APIs (like OpenAI) directly. Mock these services with predictable fixtures.
+- **Verification Gates:** Confirm the appropriate check level is used (`verify:cheap` for localized code changes, `verify:ui` for Chromium work, `verify:release` for comprehensive releases).
diff --git a/.cursor/skills/ux-review/SKILL.md b/.cursor/skills/ux-review/SKILL.md
new file mode 100644
index 000000000..dd25ec116
--- /dev/null
+++ b/.cursor/skills/ux-review/SKILL.md
@@ -0,0 +1,18 @@
+---
+name: ux-review
+description: Reviews the question-to-answer flow, source-review friction, evidence navigation, mobile/desktop usability, and global search composer behaviors. Use during UX/UI refactoring.
+---
+
+# UX Review Skill
+
+Use this skill when reviewing user interface flows, search input behaviors, sidebars, modal navigation, and responsiveness.
+
+## Review Checklist
+
+### 1. Search Composer Integration
+- **Composer Placement:** Verify that the shared composer (`master-search-header.tsx`) matches the correct placement rules (inline in heroes on home views, fixed bottom/sticky top on results, and absent on document viewers).
+- **Navigation:** Check that search queries trigger the correct routing paths (`?q=...&run=1`) and preserve active filters.
+
+### 2. User Flows & Responsiveness
+- **Source-Review Friction:** Ensure the document drawer and PDF previewer load with minimal user interaction and maintain focus.
+- **Mobile Usability:** Verify touch boundaries, drawer slide-up interactions, and layout density on mobile/tablet widths.
diff --git a/package.json b/package.json
index e44f6bc8a..f01dd5eff 100644
--- a/package.json
+++ b/package.json
@@ -63,6 +63,7 @@
     "check:type-scale": "node scripts/check-type-scale.mjs",
     "recover:ingestion": "tsx scripts/recover-ingestion-queue.ts",
     "registry:seed": "tsx scripts/seed-registry-records.ts",
+    "registry:embed": "tsx scripts/embed-registry-records.ts",
     "services:import": "tsx scripts/import-services-export.ts",
     "differentials:import": "tsx scripts/import-differentials-export.ts",
     "differentials:seed": "tsx scripts/seed-differential-records.ts",
@@ -82,6 +83,8 @@
     "eval:quality:release": "npm run eval:quality -- --fail-on-threshold --source-metadata-debt docs/release-source-metadata-debt-2026-06-30.json",
     "eval:retrieval": "node scripts/run-eval-safe.mjs scripts/eval-retrieval.ts",
     "eval:retrieval:quality": "node scripts/run-eval-safe.mjs scripts/eval-retrieval.ts --mode quality",
+    "eval:retrieval:index-unit-vector": "node scripts/run-eval-safe.mjs scripts/eval-retrieval.ts --mode quality --force-embedding --json-out artifacts/retrieval/index-unit-vector.json",
+    "eval:retrieval:compare": "tsx scripts/compare-retrieval-eval.ts",
     "eval:retrieval:latency": "node scripts/run-eval-safe.mjs scripts/eval-retrieval.ts --mode latency --case-timeout-ms 25000 --p90-ms 20000",
     "eval:search": "tsx scripts/eval-search.ts",
     "eval:search:api": "tsx scripts/eval-search-api.ts",
diff --git a/scripts/compare-retrieval-eval.ts b/scripts/compare-retrieval-eval.ts
new file mode 100644
index 000000000..c8e724d2b
--- /dev/null
+++ b/scripts/compare-retrieval-eval.ts
@@ -0,0 +1,87 @@
+import { readFileSync } from "node:fs";
+
+type EvalPayload = {
+  summary?: Record<string, unknown>;
+  results?: Array<Record<string, unknown>>;
+};
+
+function readPayload(path: string): EvalPayload {
+  return JSON.parse(readFileSync(path, "utf8")) as EvalPayload;
+}
+
+function numberValue(summary: Record<string, unknown>, key: string) {
+  const value = summary[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function arrayLength(summary: Record<string, unknown>, key: string) {
+  const value = summary[key];
+  return Array.isArray(value) ? value.length : 0;
+}
+
+function layerCount(summary: Record<string, unknown>, layer: string) {
+  const counts = summary.retrieval_layer_counts;
+  if (!counts || typeof counts !== "object") return 0;
+  const value = (counts as Record<string, unknown>)[layer];
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function formatDelta(candidate: number, baseline: number, digits = 4) {
+  const delta = candidate - baseline;
+  const sign = delta > 0 ? "+" : "";
+  return `${candidate.toFixed(digits)} (${sign}${delta.toFixed(digits)})`;
+}
+
+function main() {
+  const [, , baselinePath, candidatePath] = process.argv;
+  if (!baselinePath || !candidatePath) {
+    throw new Error("Usage: tsx scripts/compare-retrieval-eval.ts <baseline.json> <candidate.json>");
+  }
+
+  const baseline = readPayload(baselinePath).summary ?? {};
+  const candidate = readPayload(candidatePath).summary ?? {};
+
+  const metrics: Array<[string, number, number, number?]> = [
+    ["case_count", numberValue(baseline, "case_count"), numberValue(candidate, "case_count"), 0],
+    [
+      "document_recall_at_5",
+      numberValue(baseline, "document_recall_at_5"),
+      numberValue(candidate, "document_recall_at_5"),
+    ],
+    [
+      "content_recall_at_5",
+      numberValue(baseline, "content_recall_at_5"),
+      numberValue(candidate, "content_recall_at_5"),
+    ],
+    ["top_k_hit_rate", numberValue(baseline, "top_k_hit_rate"), numberValue(candidate, "top_k_hit_rate")],
+    ["mrr_at_10", numberValue(baseline, "mrr_at_10"), numberValue(candidate, "mrr_at_10")],
+    ["median_latency_ms", numberValue(baseline, "median_latency_ms"), numberValue(candidate, "median_latency_ms"), 0],
+    ["p90_latency_ms", numberValue(baseline, "p90_latency_ms"), numberValue(candidate, "p90_latency_ms"), 0],
+    [
+      "force_embedding_failure_count",
+      numberValue(baseline, "force_embedding_failure_count"),
+      numberValue(candidate, "force_embedding_failure_count"),
+      0,
+    ],
+    ["failed_cases", arrayLength(baseline, "failed_cases"), arrayLength(candidate, "failed_cases"), 0],
+    [
+      "latency_failed_cases",
+      arrayLength(baseline, "latency_failed_cases"),
+      arrayLength(candidate, "latency_failed_cases"),
+      0,
+    ],
+    ["index_units_layer_count", layerCount(baseline, "index_units"), layerCount(candidate, "index_units"), 0],
+  ];
+
+  console.log("Retrieval eval comparison: candidate (delta from baseline)");
+  for (const [name, baseValue, candidateValue, digits] of metrics) {
+    console.log(`  ${name}: ${formatDelta(candidateValue, baseValue, digits ?? 4)}`);
+  }
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}
diff --git a/scripts/embed-registry-records.ts b/scripts/embed-registry-records.ts
new file mode 100644
index 000000000..cd25aefb4
--- /dev/null
+++ b/scripts/embed-registry-records.ts
@@ -0,0 +1,162 @@
+import { loadEnvConfig } from "@next/env";
+
+import { confirm } from "./cli-utils";
+import type { DifferentialRecordRow } from "@/lib/differential-records";
+import type { MedicationRecordRow } from "@/lib/medication-records";
+import type { RegistryRecordKind, RegistryRecordRow } from "@/lib/registry-records";
+
+loadEnvConfig(process.cwd());
+
+type EmbedKind = RegistryRecordKind | "medication" | "differential" | "all";
+
+type Args = {
+  ownerId?: string;
+  kind: EmbedKind;
+  slug?: string;
+  write: boolean;
+  confirmed: boolean;
+};
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    ownerId: process.env.LOCAL_NO_AUTH_OWNER_ID,
+    kind: "all",
+    write: false,
+    confirmed: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === "--write") {
+      args.write = true;
+      continue;
+    }
+    if (token === "--confirm") {
+      args.confirmed = true;
+      continue;
+    }
+
+    const value = argv[index + 1];
+    if (!value || value.startsWith("--")) throw new Error(`Missing value for ${token}`);
+    if (token === "--owner-id") args.ownerId = value;
+    else if (token === "--slug") args.slug = value;
+    else if (token === "--kind") {
+      if (!["service", "form", "medication", "differential", "all"].includes(value)) {
+        throw new Error("--kind must be service, form, medication, differential, or all.");
+      }
+      args.kind = value as EmbedKind;
+    } else {
+      throw new Error(`Unknown argument: ${token}`);
+    }
+    index += 1;
+  }
+
+  return args;
+}
+
+async function loadAdminClient() {
+  const { createAdminClient } = await import("@/lib/supabase/admin");
+  return createAdminClient();
+}
+
+function registryKinds(kind: EmbedKind): RegistryRecordKind[] {
+  if (kind === "all") return ["service", "form"];
+  if (kind === "service" || kind === "form") return [kind];
+  return [];
+}
+
+async function loadRegistryRows(supabase: Awaited<ReturnType<typeof loadAdminClient>>, args: Args, ownerId: string) {
+  const kinds = registryKinds(args.kind);
+  if (kinds.length === 0) return [] as RegistryRecordRow[];
+  let query = supabase.from("clinical_registry_records").select("*").eq("owner_id", ownerId).in("kind", kinds);
+  if (args.slug) query = query.eq("slug", args.slug);
+  const { data, error } = await query.order("kind").order("title");
+  if (error) throw new Error(`Could not load registry records: ${error.message}`);
+  return (data ?? []) as RegistryRecordRow[];
+}
+
+async function loadMedicationRows(supabase: Awaited<ReturnType<typeof loadAdminClient>>, args: Args, ownerId: string) {
+  if (args.kind !== "all" && args.kind !== "medication") return [] as MedicationRecordRow[];
+  let query = supabase.from("medication_records").select("*").eq("owner_id", ownerId);
+  if (args.slug) query = query.eq("slug", args.slug);
+  const { data, error } = await query.order("name");
+  if (error) throw new Error(`Could not load medication records: ${error.message}`);
+  return (data ?? []) as MedicationRecordRow[];
+}
+
+async function loadDifferentialRows(
+  supabase: Awaited<ReturnType<typeof loadAdminClient>>,
+  args: Args,
+  ownerId: string,
+) {
+  if (args.kind !== "all" && args.kind !== "differential") return [] as DifferentialRecordRow[];
+  let query = supabase.from("differential_records").select("*").eq("owner_id", ownerId);
+  if (args.slug) query = query.eq("slug", args.slug);
+  const { data, error } = await query.order("kind").order("title");
+  if (error) throw new Error(`Could not load differential records: ${error.message}`);
+  return (data ?? []) as DifferentialRecordRow[];
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const ownerId = args.ownerId;
+  if (!ownerId) throw new Error("No owner id. Pass --owner-id <uuid> or set LOCAL_NO_AUTH_OWNER_ID.");
+
+  const {
+    clinicalRegistryRowsToCorpusEntries,
+    differentialRowsToCorpusEntries,
+    embedClinicalRegistryRows,
+    embedDifferentialRows,
+    embedMedicationRows,
+    medicationRowsToCorpusEntries,
+    registryCorpusEmbeddingEnabled,
+  } = await import("@/lib/registry-corpus");
+
+  const supabase = await loadAdminClient();
+  const [registryRows, medicationRows, differentialRows] = await Promise.all([
+    loadRegistryRows(supabase, args, ownerId),
+    loadMedicationRows(supabase, args, ownerId),
+    loadDifferentialRows(supabase, args, ownerId),
+  ]);
+  const registryEntries = clinicalRegistryRowsToCorpusEntries(registryRows);
+  const medicationEntries = medicationRowsToCorpusEntries(medicationRows);
+  const differentialEntries = differentialRowsToCorpusEntries(differentialRows);
+  const total = registryEntries.length + medicationEntries.length + differentialEntries.length;
+
+  console.log(`[registry:embed] owner ${ownerId}`);
+  console.log(
+    `[registry:embed] loaded ${registryEntries.length} service/form, ${medicationEntries.length} medication, ${differentialEntries.length} differential entr${total === 1 ? "y" : "ies"}`,
+  );
+  for (const entry of [...registryEntries, ...medicationEntries, ...differentialEntries].slice(0, 20)) {
+    console.log(`  ${entry.kind.padEnd(12)} ${entry.slug.padEnd(42)} ${entry.title}`);
+  }
+  if (total > 20) console.log(`  ... ${total - 20} more`);
+
+  if (!args.write) {
+    console.log(
+      "[registry:embed] Dry run. Re-run with --write --confirm and RAG_REGISTRY_CORPUS_EMBEDDING=true to write embeddings.",
+    );
+    return;
+  }
+  if (!registryCorpusEmbeddingEnabled()) {
+    throw new Error("Refusing to write registry corpus embeddings unless RAG_REGISTRY_CORPUS_EMBEDDING=true.");
+  }
+  if (!args.confirmed) {
+    const proceed = await confirm(`Embed and upsert ${total} registry corpus entr${total === 1 ? "y" : "ies"}?`);
+    if (!proceed) {
+      console.log("[registry:embed] Aborted.");
+      return;
+    }
+  }
+
+  const registryResult = await embedClinicalRegistryRows(supabase, registryRows);
+  const medicationResult = await embedMedicationRows(supabase, medicationRows);
+  const differentialResult = await embedDifferentialRows(supabase, differentialRows);
+  const chunkCount = registryResult.chunkCount + medicationResult.chunkCount + differentialResult.chunkCount;
+  console.log(`[registry:embed] Done. Upserted ${chunkCount} registry corpus chunk(s).`);
+}
+
+main().catch((error) => {
+  console.error(`[registry:embed] ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 1;
+});
diff --git a/scripts/eval-retrieval.ts b/scripts/eval-retrieval.ts
index 1e3ec67f0..c3a789a0d 100644
--- a/scripts/eval-retrieval.ts
+++ b/scripts/eval-retrieval.ts
@@ -1,5 +1,5 @@
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { loadEnvConfig } from "@next/env";
 import { z } from "zod";
@@ -36,6 +36,7 @@ type EvalArgs = {
   limit?: number;
   query?: string;
   json: boolean;
+  jsonOut?: string;
   failOnThreshold: boolean;
   mode: "combined" | "quality" | "latency";
   caseTimeoutMs: number;
@@ -160,6 +161,10 @@ function parseArgs(argv: string[]): EvalArgs {
     if (token === "--owner-id") args.ownerId = value;
     if (token === "--limit") args.limit = Number.parseInt(value, 10);
     if (token === "--query") args.query = value;
+    if (token === "--json-out") {
+      args.jsonOut = value;
+      args.json = true;
+    }
     if (token === "--mode") {
       if (!["combined", "quality", "latency"].includes(value))
         throw new Error("--mode must be combined, quality, or latency.");
@@ -902,13 +907,20 @@ async function main() {
         ].filter(Boolean)
       : [];
   if (args.json) {
-    console.log(
-      JSON.stringify(
-        { fixture: args.fixture, mode: args.mode, readinessWarnings, latencyThresholdFailures, results, summary },
-        null,
-        2,
-      ),
-    );
+    const payload = {
+      fixture: args.fixture,
+      mode: args.mode,
+      readinessWarnings,
+      latencyThresholdFailures,
+      results,
+      summary,
+    };
+    const json = JSON.stringify(payload, null, 2);
+    if (args.jsonOut) {
+      mkdirSync(dirname(args.jsonOut), { recursive: true });
+      writeFileSync(args.jsonOut, `${json}\n`);
+    }
+    console.log(json);
   } else {
     printHumanSummary(summary);
     if (latencyThresholdFailures.length) {
diff --git a/scripts/reindex-image-generation-metadata.ts b/scripts/reindex-image-generation-metadata.ts
index a537f1487..3d0f4904e 100644
--- a/scripts/reindex-image-generation-metadata.ts
+++ b/scripts/reindex-image-generation-metadata.ts
@@ -36,6 +36,24 @@ type ImagePatch = {
   metadata: Record<string, unknown>;
 };
 
+type UntypedTable = {
+  select(columns: string): {
+    eq(
+      column: string,
+      value: string,
+    ): {
+      range(from: number, to: number): Promise<{ data: unknown; error: { message: string } | null }>;
+    };
+  };
+  update(values: Record<string, unknown>): {
+    eq(column: string, value: string): Promise<{ error: { message: string } | null }>;
+  };
+};
+
+function untypedTable(supabase: ReturnType<typeof createAdminClient>, table: string): UntypedTable {
+  return supabase.from(table as never) as unknown as UntypedTable;
+}
+
 function parseArgs(argv: string[]): Args {
   const args: Args = {
     documentId: null,
@@ -101,9 +119,13 @@ async function loadDocuments(args: {
   allOwners: boolean;
   limit: number;
 }) {
-  let query = args.supabase.from("documents").select("id,title,file_name,metadata").eq("status", "indexed").order("created_at", {
-    ascending: false,
-  });
+  let query = args.supabase
+    .from("documents")
+    .select("id,title,file_name,metadata")
+    .eq("status", "indexed")
+    .order("created_at", {
+      ascending: false,
+    });
 
   if (args.documentId) query = query.eq("id", args.documentId);
   if (args.ownerId) query = query.eq("owner_id", args.ownerId);
@@ -114,19 +136,15 @@ async function loadDocuments(args: {
   return (data ?? []) as DocumentRow[];
 }
 
-async function loadImages(args: {
-  supabase: ReturnType<typeof createAdminClient>;
-  documentId: string;
-}) {
+async function loadImages(args: { supabase: ReturnType<typeof createAdminClient>; documentId: string }) {
   const rows: ImageRow[] = [];
   for (let offset = 0; ; offset += 1000) {
-    const { data, error } = await args.supabase
-      .from("document_images")
+    const { data, error } = await untypedTable(args.supabase, "document_images")
       .select("id,index_generation_id,metadata")
       .eq("document_id", args.documentId)
       .range(offset, offset + 999);
     if (error) throw new Error(error.message);
-    const page = (data ?? []) as ImageRow[];
+    const page = (data ?? []) as unknown as ImageRow[];
     rows.push(...page);
     if (page.length < 1000) break;
   }
@@ -169,7 +187,11 @@ async function main() {
     return;
   }
 
-  const label = args.allOwners ? "all owners" : args.documentId ? `document ${args.documentId}` : `owner ${args.ownerId}`;
+  const label = args.allOwners
+    ? "all owners"
+    : args.documentId
+      ? `document ${args.documentId}`
+      : `owner ${args.ownerId}`;
   console.log(`Loaded ${documents.length} indexed document(s) for ${label} inspection.`);
 
   const patches: ImagePatch[] = [];
@@ -179,7 +201,9 @@ async function main() {
   for (const document of documents) {
     const committedGeneration = committedIndexGeneration(document.metadata);
     if (!committedGeneration) {
-      console.log(`SKIP ${document.title ?? document.file_name ?? document.id}: missing index_generation_id in documents.metadata`);
+      console.log(
+        `SKIP ${document.title ?? document.file_name ?? document.id}: missing index_generation_id in documents.metadata`,
+      );
       continue;
     }
 
@@ -226,8 +250,7 @@ async function main() {
     const batch = patches.slice(start, start + 8);
     await Promise.all(
       batch.map(async (patch) => {
-        const { error } = await supabase
-          .from("document_images")
+        const { error } = await untypedTable(supabase, "document_images")
           .update({
             index_generation_id: patch.indexGenerationId,
             metadata: patch.metadata,
diff --git a/scripts/seed-differential-records.ts b/scripts/seed-differential-records.ts
index 9e573e5f7..0283258c9 100644
--- a/scripts/seed-differential-records.ts
+++ b/scripts/seed-differential-records.ts
@@ -2,6 +2,8 @@ import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
 import { buildDefaultDifferentialRows, loadDifferentialSnapshot } from "@/lib/differential-fixtures";
+import type { DifferentialRecordRow } from "@/lib/differential-records";
+import { embedDifferentialRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 
 loadEnvConfig(process.cwd());
 
@@ -122,6 +124,16 @@ async function main() {
   } else {
     console.log(`[differentials:seed] Done. Owner now has ${count ?? "?"} differential records.`);
   }
+
+  if (registryCorpusEmbeddingEnabled()) {
+    const { data: embeddedRows, error: embedRowsError } = await supabase
+      .from("differential_records")
+      .select("*")
+      .eq("owner_id", args.ownerId);
+    if (embedRowsError) throw new Error(`Could not reload differential rows for embedding: ${embedRowsError.message}`);
+    const embedded = await embedDifferentialRows(supabase, (embeddedRows ?? []) as DifferentialRecordRow[]);
+    console.log(`[differentials:seed] Embedded ${embedded.chunkCount} registry corpus chunk(s).`);
+  }
 }
 
 main().catch((error) => {
diff --git a/scripts/seed-medication-records.ts b/scripts/seed-medication-records.ts
index 092f4736f..09582e05a 100644
--- a/scripts/seed-medication-records.ts
+++ b/scripts/seed-medication-records.ts
@@ -2,6 +2,8 @@ import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
 import { buildMedicationSeedRows } from "@/lib/medication-seed";
+import { embedMedicationRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import type { MedicationRecordRow } from "@/lib/medication-records";
 
 loadEnvConfig(process.cwd());
 
@@ -119,6 +121,16 @@ async function main() {
   } else {
     console.log(`[medications:seed] Done. Owner now has ${count ?? "?"} medication records.`);
   }
+
+  if (registryCorpusEmbeddingEnabled()) {
+    const { data: embeddedRows, error: embedRowsError } = await supabase
+      .from("medication_records")
+      .select("*")
+      .eq("owner_id", args.ownerId);
+    if (embedRowsError) throw new Error(`Could not reload medication rows for embedding: ${embedRowsError.message}`);
+    const embedded = await embedMedicationRows(supabase, (embeddedRows ?? []) as MedicationRecordRow[]);
+    console.log(`[medications:seed] Embedded ${embedded.chunkCount} registry corpus chunk(s).`);
+  }
 }
 
 main().catch((error) => {
diff --git a/scripts/seed-registry-records.ts b/scripts/seed-registry-records.ts
index c0e5c3acc..97bc0482b 100644
--- a/scripts/seed-registry-records.ts
+++ b/scripts/seed-registry-records.ts
@@ -1,6 +1,8 @@
 import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
+import { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import type { RegistryRecordRow } from "@/lib/registry-records";
 import { type RegistryRecordKind } from "@/lib/registry-records";
 import { buildDefaultRegistryRows, defaultRegistryRecords } from "@/lib/registry-seed";
 import type { ServiceRecord } from "@/lib/services";
@@ -144,6 +146,18 @@ async function main() {
   } else {
     console.log(`[registry:seed] Done. Owner now has ${count ?? "?"} registry records.`);
   }
+
+  if (registryCorpusEmbeddingEnabled()) {
+    const kinds: RegistryRecordKind[] = args.kind === "all" ? ["service", "form"] : [args.kind];
+    const { data: embeddedRows, error: embedRowsError } = await supabase
+      .from("clinical_registry_records")
+      .select("*")
+      .eq("owner_id", args.ownerId)
+      .in("kind", kinds);
+    if (embedRowsError) throw new Error(`Could not reload registry rows for embedding: ${embedRowsError.message}`);
+    const embedded = await embedClinicalRegistryRows(supabase, (embeddedRows ?? []) as RegistryRecordRow[]);
+    console.log(`[registry:seed] Embedded ${embedded.chunkCount} registry corpus chunk(s).`);
+  }
 }
 
 main().catch((error) => {
diff --git a/src/lib/differential-seed.ts b/src/lib/differential-seed.ts
index 3db9efadf..c1b17d3f2 100644
--- a/src/lib/differential-seed.ts
+++ b/src/lib/differential-seed.ts
@@ -1,5 +1,6 @@
 import { buildDefaultDifferentialRows } from "@/lib/differential-fixtures";
 import { type DifferentialRecordInsert, type DifferentialRecordRow } from "@/lib/differential-records";
+import { embedDifferentialRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 
 type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
 
@@ -15,7 +16,15 @@ export async function ensureDifferentialsSeeded(
     .upsert(rows, { onConflict: "owner_id,kind,slug" })
     .select("*");
   if (error) throw new Error(`Differential seed failed: ${error.message}`);
-  return (data ?? []) as DifferentialRecordRow[];
+  const seededRows = (data ?? []) as DifferentialRecordRow[];
+  if (registryCorpusEmbeddingEnabled()) {
+    try {
+      await embedDifferentialRows(supabase, seededRows);
+    } catch (embedError) {
+      console.error(`[differentials] corpus embedding failed for owner ${ownerId}`, embedError);
+    }
+  }
+  return seededRows;
 }
 
 export function buildDifferentialSeedRows(ownerId: string): DifferentialRecordInsert[] {
diff --git a/src/lib/differentials.ts b/src/lib/differentials.ts
index 0903f9808..e215965c8 100644
--- a/src/lib/differentials.ts
+++ b/src/lib/differentials.ts
@@ -147,7 +147,7 @@ function diagnosisHingeText(record: DifferentialRecord) {
   );
 }
 
-function diagnosisFullText(record: DifferentialRecord) {
+export function diagnosisFullText(record: DifferentialRecord) {
   return normalizeSearchText(
     [
       record.title,
@@ -213,7 +213,7 @@ function presentationSafetyText(workflow: DifferentialPresentationWorkflow) {
   return normalizeSearchText([workflow.subtitle, ...workflow.safetySnapshot.tags].join(" "));
 }
 
-function presentationFullText(workflow: DifferentialPresentationWorkflow) {
+export function presentationFullText(workflow: DifferentialPresentationWorkflow) {
   return normalizeSearchText(
     [
       workflow.title,
diff --git a/src/lib/document-index-units.ts b/src/lib/document-index-units.ts
index b6c43b9c6..e669dfc19 100644
--- a/src/lib/document-index-units.ts
+++ b/src/lib/document-index-units.ts
@@ -105,6 +105,73 @@ function compact(value: unknown, limit = 900) {
   return compacted.length <= limit ? compacted : `${compacted.slice(0, limit - 3).trim()}...`;
 }
 
+function boundedEditDistance(left: string, right: string, maxDistance: number) {
+  if (Math.abs(left.length - right.length) > maxDistance) return maxDistance + 1;
+  let previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    const current = [leftIndex];
+    let rowMin = current[0]!;
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const substitutionCost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      const value = Math.min(
+        previous[rightIndex]! + 1,
+        current[rightIndex - 1]! + 1,
+        previous[rightIndex - 1]! + substitutionCost,
+      );
+      current[rightIndex] = value;
+      rowMin = Math.min(rowMin, value);
+    }
+    if (rowMin > maxDistance) return maxDistance + 1;
+    previous = current;
+  }
+  return previous[right.length] ?? maxDistance + 1;
+}
+
+function referenceDictionary(reference: string) {
+  return Array.from(new Set(reference.toLowerCase().match(/[a-z]{6,}/g) ?? []));
+}
+
+function bestOcrRepair(fragment: string, dictionary: string[]) {
+  const collapsed = fragment.toLowerCase().replace(/[^a-z]/g, "");
+  if (collapsed.length < 6) return null;
+  let best: { word: string; distance: number } | null = null;
+  for (const word of dictionary) {
+    const maxDistance = word.length >= 10 ? 2 : 1;
+    if (Math.abs(word.length - collapsed.length) > maxDistance) continue;
+    const distance = boundedEditDistance(collapsed, word, maxDistance);
+    if (distance <= maxDistance && (!best || distance < best.distance)) best = { word, distance };
+  }
+  return best?.word ?? null;
+}
+
+export function repairOcrDropoutAgainstReference(text: string, reference: string) {
+  const dictionary = referenceDictionary(reference);
+  if (dictionary.length === 0) return { text, replacements: [] as Array<{ from: string; to: string }> };
+  const tokenMatches = Array.from(text.matchAll(/[A-Za-z]+/g));
+  const replacements: Array<{ from: string; to: string }> = [];
+  let repaired = text;
+
+  for (let windowSize = 5; windowSize >= 2; windowSize -= 1) {
+    for (let index = tokenMatches.length - windowSize; index >= 0; index -= 1) {
+      const window = tokenMatches.slice(index, index + windowSize);
+      if (!window.some((match) => match[0].length === 1)) continue;
+      const start = window[0]!.index ?? 0;
+      const last = window[window.length - 1]!;
+      const end = (last.index ?? 0) + last[0].length;
+      const fragment = text.slice(start, end);
+      if (!/^[A-Za-z]+(?:\s+[A-Za-z]+)+$/.test(fragment)) continue;
+      const repair = bestOcrRepair(fragment, dictionary);
+      if (!repair || repair === fragment.toLowerCase()) continue;
+      const currentFragment = repaired.slice(start, end);
+      if (currentFragment !== fragment) continue;
+      repaired = `${repaired.slice(0, start)}${repair}${repaired.slice(end)}`;
+      replacements.push({ from: fragment, to: repair });
+    }
+  }
+
+  return { text: repaired, replacements };
+}
+
 function indexGenerationFromChunk(chunk?: { metadata?: Record<string, unknown> | null } | null) {
   const generation = chunk?.metadata?.index_generation_id;
   return typeof generation === "string" && generation.trim() ? generation.trim() : null;
@@ -580,7 +647,10 @@ function buildUnit(args: {
   metadata?: Record<string, unknown>;
 }): DocumentIndexUnitInput | null {
   const title = compact(args.title, 160);
-  const content = compact(clinicalVocabularySearchText(args.content), 1400);
+  const ocrRepair = args.sourceChunk?.content
+    ? repairOcrDropoutAgainstReference(args.content, args.sourceChunk.content)
+    : { text: args.content, replacements: [] as Array<{ from: string; to: string }> };
+  const content = compact(clinicalVocabularySearchText(ocrRepair.text), 1400);
   if (!title || !content) return null;
   return {
     owner_id: args.document.owner_id ?? null,
@@ -603,6 +673,12 @@ function buildUnit(args: {
       index_generation_id: indexGenerationFromChunk(args.sourceChunk),
       chunk_index: args.sourceChunk?.chunk_index ?? null,
       section_heading: args.sourceChunk?.section_heading ?? null,
+      ...(ocrRepair.replacements.length
+        ? {
+            ocr_repair_version: "clean-chunk-fragment-v1",
+            ocr_replacements: ocrRepair.replacements.slice(0, 8),
+          }
+        : {}),
       ...args.metadata,
     },
   };
diff --git a/src/lib/env.ts b/src/lib/env.ts
index e1da11dfc..dccf68890 100644
--- a/src/lib/env.ts
+++ b/src/lib/env.ts
@@ -89,6 +89,10 @@ const envSchema = z.object({
     .enum(["true", "false"])
     .default("false")
     .transform((value) => value === "true"),
+  RAG_REGISTRY_CORPUS_EMBEDDING: z
+    .enum(["true", "false"])
+    .default("false")
+    .transform((value) => value === "true"),
   RAG_ANSWER_CACHE_TTL_MS: z.coerce.number().int().nonnegative().default(300000),
   RAG_ANSWER_CACHE_SIZE: z.coerce.number().int().nonnegative().default(100),
   RAG_SEARCH_CACHE_TTL_MS: z.coerce.number().int().nonnegative().default(60000),
diff --git a/src/lib/forms.ts b/src/lib/forms.ts
index f774d1671..1763f6b9e 100644
--- a/src/lib/forms.ts
+++ b/src/lib/forms.ts
@@ -215,7 +215,7 @@ export const formRecords: FormRecord[] = [
   },
 ];
 
-function formRecordSearchText(form: FormRecord) {
+export function formRecordSearchText(form: FormRecord) {
   const values = [
     form.title,
     form.slug,
diff --git a/src/lib/medication-seed.ts b/src/lib/medication-seed.ts
index 6f392443e..78179fb41 100644
--- a/src/lib/medication-seed.ts
+++ b/src/lib/medication-seed.ts
@@ -1,4 +1,5 @@
 import { buildDefaultMedicationRows, defaultMedicationRecords } from "@/lib/medication-fixtures";
+import { embedMedicationRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { type MedicationRecordInsert, type MedicationRecordRow } from "@/lib/medication-records";
 
 type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
@@ -14,7 +15,15 @@ export async function ensureMedicationsSeeded(supabase: AdminClient, ownerId: st
     .upsert(rows, { onConflict: "owner_id,slug" })
     .select("*");
   if (error) throw new Error(`Medication seed failed: ${error.message}`);
-  return (data ?? []) as MedicationRecordRow[];
+  const seededRows = (data ?? []) as MedicationRecordRow[];
+  if (registryCorpusEmbeddingEnabled()) {
+    try {
+      await embedMedicationRows(supabase, seededRows);
+    } catch (embedError) {
+      console.error(`[medications] corpus embedding failed for owner ${ownerId}`, embedError);
+    }
+  }
+  return seededRows;
 }
 
 export { defaultMedicationRecords };
diff --git a/src/lib/rag.ts b/src/lib/rag.ts
index 2bc8e90e8..b33e6fb58 100644
--- a/src/lib/rag.ts
+++ b/src/lib/rag.ts
@@ -2331,29 +2331,54 @@ async function withMemoryBoostedCandidates(args: {
   };
 }
 
+type DocumentRankingMetadataCache = {
+  documentMetadata: Map<
+    string,
+    { labels: SearchResult["document_labels"]; summary: SearchResult["document_summary"] } | null
+  >;
+  indexQuality: Map<string, SearchResult["indexing_quality"] | null>;
+};
+
+function createDocumentRankingMetadataCache(): DocumentRankingMetadataCache {
+  return {
+    documentMetadata: new Map(),
+    indexQuality: new Map(),
+  };
+}
+
 async function attachDocumentRankingMetadata(
   supabase: ReturnType<typeof createAdminClient>,
   results: SearchResult[],
   ownerId?: string,
+  cache = createDocumentRankingMetadataCache(),
 ) {
   const documentIds = Array.from(new Set(results.map((result) => result.document_id)));
   if (documentIds.length === 0) return results;
-  const missingMetadata = results.some(
-    (result) =>
-      (result.document_labels === undefined || result.document_labels.length === 0) &&
-      (result.document_summary === undefined || result.document_summary === null),
+  const missingDocumentIds = documentIds.filter(
+    (documentId) =>
+      !cache.documentMetadata.has(documentId) &&
+      results.some(
+        (result) =>
+          result.document_id === documentId &&
+          (result.document_labels === undefined || result.document_labels.length === 0) &&
+          (result.document_summary === undefined || result.document_summary === null),
+      ),
   );
-  if (!missingMetadata) return attachIndexQualityMetadata(supabase, results, ownerId);
+  if (missingDocumentIds.length === 0) return attachIndexQualityMetadata(supabase, results, ownerId, cache);
 
   try {
     const metadataRows = await fetchRelatedDocumentMetadata({
       supabase,
       ownerId,
-      documentIds,
+      documentIds: missingDocumentIds,
     });
+    for (const documentId of missingDocumentIds) cache.documentMetadata.set(documentId, null);
+    for (const row of metadataRows) {
+      cache.documentMetadata.set(row.document_id, { labels: row.labels, summary: row.summary });
+    }
     const metadataByDocument = new Map(metadataRows.map((row) => [row.document_id, row]));
     const enriched = results.map((result) => {
-      const metadata = metadataByDocument.get(result.document_id);
+      const metadata = metadataByDocument.get(result.document_id) ?? cache.documentMetadata.get(result.document_id);
       if (!metadata) return result;
       return {
         ...result,
@@ -2361,7 +2386,7 @@ async function attachDocumentRankingMetadata(
         document_summary: metadata.summary,
       };
     });
-    return attachIndexQualityMetadata(supabase, enriched, ownerId);
+    return attachIndexQualityMetadata(supabase, enriched, ownerId, cache);
   } catch {
     return results;
   }
@@ -2371,22 +2396,33 @@ async function attachIndexQualityMetadata(
   supabase: ReturnType<typeof createAdminClient>,
   results: SearchResult[],
   ownerId?: string,
+  cache = createDocumentRankingMetadataCache(),
 ): Promise<SearchResult[]> {
   const documentIds = Array.from(new Set(results.map((result) => result.document_id)));
   if (documentIds.length === 0) return results;
+  const missingDocumentIds = documentIds.filter((documentId) => !cache.indexQuality.has(documentId));
+  if (missingDocumentIds.length === 0) {
+    return results.map((result) => ({
+      ...result,
+      indexing_quality: cache.indexQuality.get(result.document_id) ?? result.indexing_quality ?? null,
+    }));
+  }
   try {
     let query = supabase
       .from("document_index_quality")
       .select("document_id,owner_id,quality_score,extraction_quality,metrics,issues,updated_at")
-      .in("document_id", documentIds);
+      .in("document_id", missingDocumentIds);
     if (ownerId) query = query.eq("owner_id", ownerId);
     const { data, error } = await query;
-    if (error || !data?.length) return results;
-    const qualityByDocument = new Map(data.map((row) => [row.document_id, row]));
+    if (error) return results;
+    for (const documentId of missingDocumentIds) cache.indexQuality.set(documentId, null);
+    for (const row of data ?? []) cache.indexQuality.set(row.document_id, row as SearchResult["indexing_quality"]);
+    const qualityByDocument = new Map((data ?? []).map((row) => [row.document_id, row]));
     return results.map((result) => ({
       ...result,
       indexing_quality:
         (qualityByDocument.get(result.document_id) as SearchResult["indexing_quality"]) ??
+        cache.indexQuality.get(result.document_id) ??
         result.indexing_quality ??
         null,
     }));
@@ -2949,9 +2985,15 @@ async function prepareCoverageGateResults(args: {
   maxResultsPerDocument: number;
   queryClass: RagQueryClass;
   telemetry: SearchTelemetry;
+  metadataCache: DocumentRankingMetadataCache;
 }) {
   const startedAt = Date.now();
-  const candidates = await attachDocumentRankingMetadata(args.supabase, args.candidates, args.ownerId);
+  const candidates = await attachDocumentRankingMetadata(
+    args.supabase,
+    args.candidates,
+    args.ownerId,
+    args.metadataCache,
+  );
   let results = await attachPageVisualEvidence(
     args.supabase,
     selectRankedRetrievalResults({
@@ -3009,16 +3051,6 @@ function shouldUseMemoryBeforeFastPath(queryClass: RagQueryClass) {
   return queryClass === "table_threshold" || queryClass === "medication_dose_risk" || queryClass === "comparison";
 }
 
-function shouldPreloadEmbedding(queryAnalysis: ReturnType<typeof analyzeClinicalQuery>) {
-  if (queryAnalysis.documentTitleIntent && queryAnalysis.queryClass === "document_lookup") return false;
-  return (
-    queryAnalysis.queryClass === "comparison" ||
-    queryAnalysis.queryClass === "broad_summary" ||
-    (queryAnalysis.queryClass === "medication_dose_risk" && queryAnalysis.needsSynthesis) ||
-    queryAnalysis.needsClassifierFallback
-  );
-}
-
 function memoryCardAnswerScore(card: DocumentMemoryCard, query: string, queryClass: RagQueryClass) {
   const content = sourceTextForDisplay(card.content);
   if (!content) return -1;
@@ -3087,6 +3119,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
   // A3: shared across every withMemoryBoostedCandidates call in this request so the same
   // owner/query memory cards are fetched at most once per (query, embedding-present, count).
   const memoryCardCache: MemoryCardCache = new Map();
+  const documentRankingMetadataCache = createDocumentRankingMetadataCache();
   const retrievalQuery = queryForClinicalMode(args.query, args.queryMode ?? "auto");
   const modeQueryClass = queryClassForClinicalMode(args.queryMode ?? "auto");
   const documentFilterList = args.documentIds?.length
@@ -3217,7 +3250,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
   const minSimilarity = args.minSimilarity ?? 0.15;
   let embeddingStartedAt = 0;
   const preloadedEmbedding =
-    !sourceOnlyRetrieval && !args.lexicalOnly && shouldPreloadEmbedding(queryAnalysis)
+    !sourceOnlyRetrieval && !args.lexicalOnly
       ? (() => {
           embeddingStartedAt = Date.now();
           return Promise.resolve(embedTextWithTelemetry(expandedQuery)).catch(() => null);
@@ -3246,7 +3279,12 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
 
   if (textData.length) {
     const rerankStartedAt = Date.now();
-    const textCandidates = await attachDocumentRankingMetadata(supabase, textData as SearchResult[], args.ownerId);
+    const textCandidates = await attachDocumentRankingMetadata(
+      supabase,
+      textData as SearchResult[],
+      args.ownerId,
+      documentRankingMetadataCache,
+    );
     if (!preloadedEmbedding) {
       expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, textCandidates);
     }
@@ -3368,6 +3406,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
         supabase,
         mergeSearchResults(documentLookupData, textFastResults),
         args.ownerId,
+        documentRankingMetadataCache,
       );
       if (!preloadedEmbedding) {
         expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, documentLookupCandidates);
@@ -3442,6 +3481,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
       maxResultsPerDocument,
       queryClass: queryClassification.queryClass,
       telemetry,
+      metadataCache: documentRankingMetadataCache,
     });
     const coverageGate = evaluateEvidenceCoverageGate(args.query, coverageGateResults, queryClassification.queryClass);
     applyCoverageGateTelemetry(telemetry, coverageGate, !args.forceEmbedding && coverageGate.accepted);
@@ -3587,7 +3627,12 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
   if (!hybridError) {
     const rerankStartedAt = Date.now();
     const merged = args.forceEmbedding ? vectorCandidates : mergeSearchResults(vectorCandidates, textFastResults);
-    const mergedWithMetadata = await attachDocumentRankingMetadata(supabase, merged, args.ownerId);
+    const mergedWithMetadata = await attachDocumentRankingMetadata(
+      supabase,
+      merged,
+      args.ownerId,
+      documentRankingMetadataCache,
+    );
     const memoryBoost = await withMemoryBoostedCandidates({
       supabase,
       query: retrievalQuery,
@@ -3668,6 +3713,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
     supabase,
     args.forceEmbedding ? fallbackVectorCandidates : mergeSearchResults(fallbackVectorCandidates, textFastResults),
     args.ownerId,
+    documentRankingMetadataCache,
   );
   const memoryBoost = await withMemoryBoostedCandidates({
     supabase,
diff --git a/src/lib/registry-corpus.ts b/src/lib/registry-corpus.ts
new file mode 100644
index 000000000..8a3bcfc1c
--- /dev/null
+++ b/src/lib/registry-corpus.ts
@@ -0,0 +1,277 @@
+import { createHash } from "node:crypto";
+
+import { diagnosisFullText, presentationFullText } from "@/lib/differentials";
+import type { DifferentialPresentationWorkflow, DifferentialRecord } from "@/lib/differential-snapshot";
+import {
+  rowToDifferentialRecord,
+  rowToPresentationWorkflow,
+  type DifferentialRecordRow,
+} from "@/lib/differential-records";
+import { env } from "@/lib/env";
+import { formRecordSearchText } from "@/lib/forms";
+import { rowToMedicationRecord, type MedicationRecordRow } from "@/lib/medication-records";
+import { rowToServiceRecord, type RegistryRecordKind, type RegistryRecordRow } from "@/lib/registry-records";
+import { serviceRecordSearchText } from "@/lib/services";
+import type { Json, TablesInsert, Vector } from "@/lib/supabase/database.types";
+
+export type RegistryCorpusKind = "service" | "form" | "medication" | "differential";
+
+type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
+
+type RegistryCorpusEntry = {
+  kind: RegistryCorpusKind;
+  subkind: string | null;
+  ownerId: string;
+  recordId: string;
+  slug: string;
+  title: string;
+  subtitle: string | null;
+  content: string;
+  searchText: string;
+  sourceStatus: string;
+  validationStatus: string;
+  metadata: Record<string, Json>;
+};
+
+function sha256(value: string) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function deterministicUuid(seed: string) {
+  const hex = sha256(seed).slice(0, 32).split("");
+  hex[12] = "5";
+  hex[16] = ((Number.parseInt(hex[16] ?? "8", 16) & 0x3) | 0x8).toString(16);
+  const value = hex.join("");
+  return `${value.slice(0, 8)}-${value.slice(8, 12)}-${value.slice(12, 16)}-${value.slice(16, 20)}-${value.slice(20)}`;
+}
+
+function compactText(parts: unknown[], limit = 8000) {
+  const text = parts
+    .flatMap((part) => (Array.isArray(part) ? part : [part]))
+    .map((part) =>
+      String(part ?? "")
+        .replace(/\s+/g, " ")
+        .trim(),
+    )
+    .filter(Boolean)
+    .join("\n");
+  return text.length <= limit ? text : `${text.slice(0, limit - 3).trim()}...`;
+}
+
+function stringArray(value: unknown) {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
+    : [];
+}
+
+function registryBaseMetadata(entry: RegistryCorpusEntry): Record<string, Json> {
+  return {
+    source_kind: "registry_record",
+    registry_record_kind: entry.kind,
+    registry_record_subkind: entry.subkind,
+    registry_record_id: entry.recordId,
+    registry_record_slug: entry.slug,
+    source_title: entry.title,
+    document_status: entry.sourceStatus,
+    clinical_validation_status: entry.validationStatus,
+    extraction_quality: "good",
+    publisher: "Clinical KB registry",
+    jurisdiction: "WA/local clinical workspace",
+  };
+}
+
+function registryDocumentRow(entry: RegistryCorpusEntry): TablesInsert<"documents"> {
+  const documentId = deterministicUuid(`registry-document:${entry.kind}:${entry.recordId}`);
+  const metadata = { ...registryBaseMetadata(entry), ...entry.metadata };
+  return {
+    id: documentId,
+    owner_id: entry.ownerId,
+    title: entry.title,
+    description: entry.subtitle,
+    file_name: `${entry.kind}-${entry.slug}.registry.json`,
+    file_type: "application/vnd.clinical-kb.registry+json",
+    file_size: Buffer.byteLength(entry.content, "utf8"),
+    storage_path: `registry://${entry.kind}/${entry.recordId}`,
+    source_path: `registry://${entry.kind}/${entry.slug}`,
+    status: "indexed",
+    page_count: 1,
+    chunk_count: 1,
+    image_count: 0,
+    content_hash: sha256(entry.content),
+    metadata,
+  };
+}
+
+function registryChunkRow(entry: RegistryCorpusEntry, embedding: Vector): TablesInsert<"document_chunks"> {
+  const documentId = deterministicUuid(`registry-document:${entry.kind}:${entry.recordId}`);
+  const metadata = { ...registryBaseMetadata(entry), ...entry.metadata };
+  return {
+    id: deterministicUuid(`registry-chunk:${entry.kind}:${entry.recordId}`),
+    document_id: documentId,
+    chunk_index: 0,
+    page_number: 1,
+    section_heading: "Registry summary",
+    section_path: ["Registry summary"],
+    content: entry.content,
+    retrieval_synopsis: entry.subtitle,
+    token_estimate: Math.ceil(entry.content.length / 4),
+    image_ids: [],
+    content_hash: sha256(entry.content),
+    embedding,
+    metadata,
+  };
+}
+
+export function registryCorpusEmbeddingEnabled() {
+  return env.RAG_REGISTRY_CORPUS_EMBEDDING === true;
+}
+
+export function clinicalRegistryRowsToCorpusEntries(rows: RegistryRecordRow[]): RegistryCorpusEntry[] {
+  return rows.map((row) => {
+    const kind: RegistryRecordKind = row.kind === "form" ? "form" : "service";
+    const record = rowToServiceRecord(row);
+    const searchText = kind === "form" ? formRecordSearchText(record) : serviceRecordSearchText(record);
+    const content = compactText([
+      `${kind === "form" ? "Form" : "Service"}: ${record.title}`,
+      record.subtitle,
+      record.route && `Route: ${record.route}`,
+      record.eligibility && `Eligibility: ${record.eligibility}`,
+      record.referral && `Referral: ${record.referral}`,
+      record.location && `Location: ${record.location}`,
+      record.bestUse && `Best use: ${record.bestUse}`,
+      record.primaryContact && `Primary contact: ${record.primaryContact.value} ${record.primaryContact.detail ?? ""}`,
+      record.tags?.length ? `Tags: ${record.tags.join(", ")}` : null,
+      record.catchments?.length ? `Catchments: ${record.catchments.join(", ")}` : null,
+      searchText,
+    ]);
+    return {
+      kind,
+      subkind: kind,
+      ownerId: row.owner_id,
+      recordId: row.id,
+      slug: row.slug,
+      title: record.title,
+      subtitle: record.subtitle ?? null,
+      content,
+      searchText,
+      sourceStatus: row.source_status,
+      validationStatus: row.validation_status,
+      metadata: {
+        catalogue_label: row.catalogue_label,
+        tags: row.tags,
+        catchments: row.catchments,
+      },
+    };
+  });
+}
+
+export function medicationRowsToCorpusEntries(rows: MedicationRecordRow[]): RegistryCorpusEntry[] {
+  return rows.map((row) => {
+    const record = rowToMedicationRecord(row);
+    const sectionText = Array.isArray(record.sections)
+      ? record.sections
+          .flatMap((section) => [
+            section.title,
+            section.type,
+            ...(section.rows ?? []).flatMap((item) => [item.key, item.val]),
+          ])
+          .join(" ")
+      : "";
+    const quickText = Array.isArray(record.quick)
+      ? record.quick.flatMap((item) => [item.label, item.value]).join(" ")
+      : "";
+    const searchText = compactText(
+      [record.name, record.slug, record.class, record.subclass, record.category, sectionText, quickText],
+      4000,
+    );
+    return {
+      kind: "medication",
+      subkind: record.category || record.class || null,
+      ownerId: row.owner_id,
+      recordId: row.id,
+      slug: row.slug,
+      title: record.name,
+      subtitle: record.class || row.category,
+      content: compactText([
+        `Medication: ${record.name}`,
+        record.class && `Class: ${record.class}`,
+        record.subclass && `Subclass: ${record.subclass}`,
+        record.schedule && `Schedule: ${record.schedule}`,
+        record.tag && `Tag: ${record.tag}`,
+        sectionText,
+        quickText,
+      ]),
+      searchText,
+      sourceStatus: row.source_status,
+      validationStatus: row.validation_status,
+      metadata: {
+        medication_class: row.class,
+        medication_subclass: row.subclass,
+        tags: stringArray(row.tag),
+      },
+    };
+  });
+}
+
+export function differentialRowsToCorpusEntries(rows: DifferentialRecordRow[]): RegistryCorpusEntry[] {
+  return rows.map((row) => {
+    const isPresentation = row.kind === "presentation";
+    const payload = isPresentation ? rowToPresentationWorkflow(row) : rowToDifferentialRecord(row);
+    const searchText = isPresentation
+      ? presentationFullText(payload as DifferentialPresentationWorkflow)
+      : diagnosisFullText(payload as DifferentialRecord);
+    return {
+      kind: "differential",
+      subkind: isPresentation ? "presentation" : "diagnosis",
+      ownerId: row.owner_id,
+      recordId: row.id,
+      slug: row.slug,
+      title: row.title,
+      subtitle: row.subtitle,
+      content: compactText([
+        `${isPresentation ? "Presentation workflow" : "Differential diagnosis"}: ${row.title}`,
+        row.subtitle,
+        row.clinical_hinge && `Clinical hinge: ${row.clinical_hinge}`,
+        row.tags.length ? `Tags: ${row.tags.join(", ")}` : null,
+        searchText,
+      ]),
+      searchText,
+      sourceStatus: row.source_status,
+      validationStatus: row.validation_status,
+      metadata: {
+        differential_kind: row.kind,
+        status: row.status,
+        tags: row.tags,
+      },
+    };
+  });
+}
+
+export async function embedRegistryCorpusEntries(supabase: AdminClient, entries: RegistryCorpusEntry[]) {
+  if (entries.length === 0) return { documentCount: 0, chunkCount: 0 };
+
+  const { embedTexts } = await import("@/lib/openai");
+  const embeddings = await embedTexts(entries.map((entry) => entry.content));
+  const documents = entries.map(registryDocumentRow);
+  const chunks = entries.map((entry, index) => registryChunkRow(entry, embeddings[index] as Vector));
+
+  const { error: documentError } = await supabase.from("documents").upsert(documents, { onConflict: "id" });
+  if (documentError) throw new Error(`Registry corpus document upsert failed: ${documentError.message}`);
+
+  const { error: chunkError } = await supabase.from("document_chunks").upsert(chunks, { onConflict: "id" });
+  if (chunkError) throw new Error(`Registry corpus chunk upsert failed: ${chunkError.message}`);
+
+  return { documentCount: documents.length, chunkCount: chunks.length };
+}
+
+export function embedClinicalRegistryRows(supabase: AdminClient, rows: RegistryRecordRow[]) {
+  return embedRegistryCorpusEntries(supabase, clinicalRegistryRowsToCorpusEntries(rows));
+}
+
+export function embedMedicationRows(supabase: AdminClient, rows: MedicationRecordRow[]) {
+  return embedRegistryCorpusEntries(supabase, medicationRowsToCorpusEntries(rows));
+}
+
+export function embedDifferentialRows(supabase: AdminClient, rows: DifferentialRecordRow[]) {
+  return embedRegistryCorpusEntries(supabase, differentialRowsToCorpusEntries(rows));
+}
diff --git a/src/lib/registry-seed.ts b/src/lib/registry-seed.ts
index 875805a4d..4078b3879 100644
--- a/src/lib/registry-seed.ts
+++ b/src/lib/registry-seed.ts
@@ -1,5 +1,6 @@
 import { formRecords } from "@/lib/forms";
 import { buildDefaultFormRows, buildDefaultServiceRows, defaultServiceRecords } from "@/lib/registry-fixtures";
+import { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { type RegistryRecordInsert, type RegistryRecordKind, type RegistryRecordRow } from "@/lib/registry-records";
 
 // Type-only reference to the admin client so this module carries no runtime
@@ -42,7 +43,15 @@ export async function ensureRegistrySeeded(
     .upsert(rows, { onConflict: "owner_id,kind,slug" })
     .select("*");
   if (error) throw new Error(`Registry seed failed: ${error.message}`);
-  return (data ?? []) as RegistryRecordRow[];
+  const seededRows = (data ?? []) as RegistryRecordRow[];
+  if (registryCorpusEmbeddingEnabled()) {
+    try {
+      await embedClinicalRegistryRows(supabase, seededRows);
+    } catch (embedError) {
+      console.error(`[registry] corpus embedding failed for owner ${ownerId} (${kind})`, embedError);
+    }
+  }
+  return seededRows;
 }
 
 /**
diff --git a/src/lib/source-governance.ts b/src/lib/source-governance.ts
index 90777719f..d701fa569 100644
--- a/src/lib/source-governance.ts
+++ b/src/lib/source-governance.ts
@@ -11,7 +11,8 @@ export type SourceGovernanceWarning = {
     | "partial_extraction"
     | "low_index_quality"
     | "weak_evidence"
-    | "weak_table_extraction";
+    | "weak_table_extraction"
+    | "registry_record_source";
   severity: "info" | "warning" | "danger";
   message: string;
   document_id?: string;
@@ -58,6 +59,7 @@ const frontendVisibleWarningCodes = new Set<SourceGovernanceWarning["code"]>([
   // searchable regardless of clinical_validation_status), "not locally
   // validated" is a clinically material caveat, not routine review metadata.
   "unverified_source",
+  "registry_record_source",
 ]);
 
 function isLocalMetadataText(value: string) {
@@ -92,6 +94,17 @@ export function sourceGovernanceWarnings(args: {
     const title = result.title;
     const document_id = result.document_id;
 
+    if (source.source_kind === "registry_record") {
+      pushUnique(warnings, {
+        code: "registry_record_source",
+        severity: "info",
+        message:
+          "One or more supporting sources are curated registry summaries, not source documents; verify against linked source documents for clinical decisions.",
+        document_id,
+        title,
+      });
+    }
+
     if (source.document_status === "outdated") {
       pushUnique(warnings, {
         code: "outdated_source",
@@ -195,6 +208,8 @@ function groupedMessage(warning: SourceGovernanceWarning, count: number) {
     return `${plural(count, "source")} ${count === 1 ? "has" : "have"} low indexing quality.`;
   if (warning.code === "weak_table_extraction")
     return `${plural(count, "table evidence item")} reviewed as administrative, unrelated, or poor extraction.`;
+  if (warning.code === "registry_record_source")
+    return `${plural(count, "registry summary", "registry summaries")} used as supporting evidence.`;
   return warning.message;
 }
 
diff --git a/src/lib/source-metadata.ts b/src/lib/source-metadata.ts
index 337b246ca..4ede237a6 100644
--- a/src/lib/source-metadata.ts
+++ b/src/lib/source-metadata.ts
@@ -16,6 +16,7 @@ export function normalizeSourceMetadata(input: unknown): ClinicalSourceMetadata
   const value = input && typeof input === "object" ? (input as Record<string, unknown>) : {};
 
   return {
+    source_kind: stringOrNull(value.source_kind),
     source_title: stringOrNull(value.source_title),
     publisher: stringOrNull(value.publisher),
     jurisdiction: stringOrNull(value.jurisdiction),
@@ -44,6 +45,7 @@ export function formatClinicalDate(value: string | null | undefined) {
 }
 
 export function sourceStatusLabel(metadata?: ClinicalSourceMetadata | null) {
+  if (metadata?.source_kind === "registry_record") return "Registry summary";
   const status = metadata?.document_status ?? "unknown";
   if (status === "current") return "Current source";
   if (status === "review_due") return "Review due";
diff --git a/src/lib/types.ts b/src/lib/types.ts
index 41f649ddd..012657f5a 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -94,6 +94,7 @@ export type DocumentOrganizationProfile = {
 };
 
 export type ClinicalSourceMetadata = {
+  source_kind?: "document" | "registry_record" | string | null;
   source_title: string | null;
   publisher: string | null;
   publisher_code?: string | null;
@@ -137,7 +138,8 @@ export type SourceGovernanceWarning = {
     | "partial_extraction"
     | "low_index_quality"
     | "weak_evidence"
-    | "weak_table_extraction";
+    | "weak_table_extraction"
+    | "registry_record_source";
   severity: "info" | "warning" | "danger";
   message: string;
   document_id?: string;
diff --git a/supabase/drift-allowlist.json b/supabase/drift-allowlist.json
index b73d6df55..5c3ea0a09 100644
--- a/supabase/drift-allowlist.json
+++ b/supabase/drift-allowlist.json
@@ -106,13 +106,7 @@
       "reason": "LIVE IS AHEAD of the repo: live carries newer raw-SQL retrieval bodies (e.g. match_document_chunks has an hnsw.ef_search=100 wrapper; chunks_text/table_facts_text carry richer multi-strategy implementations). Migration 20260705210000 (which had OLDER bodies) was NEUTRALIZED 2026-07-08 so a db push can never regress live. DO NOT apply it. Resolution is forward-codification of the live bodies into schema.sql + a migration (drift backlog); until then these are allowlisted. Note: live retrieval RPCs are under active concurrent multi-session edits.",
       "ref": "docs/database-drift-detection.md#reconciliation-backlog"
     },
-    {
-      "category": "functions",
-      "key": "public.retrieval_owner_matches(uuid,uuid)",
-      "kind": "mismatch",
-      "reason": "ACL-only drift: live retains a default PUBLIC execute grant (=X/postgres) that schema.sql (service-role-only) does not. Same posture as search_document_chunks — this is a security-invoker helper, RLS still applies; revoke on live via an approved hardening migration, then remove. The prior search_path half of this drift (live pg_catalog vs schema.sql pg_temp) was reconciled 2026-07-08: schema.sql + drift-manifest def_hash now match live's body (verified read-only via schema_drift_snapshot). This function is a stable boolean owner-scoping helper — NOT one of the raw-SQL retrieval RPCs (match_document_chunks et al.) whose bodies genuinely diverge; do not conflate.",
-      "ref": "docs/database-drift-detection.md#reconciliation-backlog"
-    },
+
     {
       "category": "functions",
       "key": "public.run_all_visual_eval_cases(integer)",
@@ -127,20 +121,7 @@
       "reason": "Live-only function (raw-SQL era) not yet codified into schema.sql/migrations; codification wave follow-up (same pattern as 20260705230000 and 20260707000000).",
       "ref": "docs/database-drift-detection.md#reconciliation-backlog"
     },
-    {
-      "category": "functions",
-      "key": "public.search_document_chunks(uuid,text,integer,uuid)",
-      "kind": "mismatch",
-      "reason": "Live retains default PUBLIC execute (security-invoker fn, RLS still applies); schema.sql declares service-role-only. Revoke on live via an approved hardening migration. Remove after apply.",
-      "ref": "docs/database-drift-detection.md#reconciliation-backlog"
-    },
-    {
-      "category": "functions",
-      "key": "public.search_schema_health()",
-      "kind": "mismatch",
-      "reason": "APPLIED to live 2026-07-08 via migration 20260706010000 (search_schema_health M13 guard); live now matches schema.sql. Entry retained until the drift manifest is regenerated; safe to remove then. (Live may re-drift from concurrent multi-session edits.)",
-      "ref": "docs/database-drift-detection.md#reconciliation-backlog"
-    },
+
     {
       "category": "functions",
       "key": "public.set_document_embedding_field_content_hash()",
diff --git a/supabase/drift-manifest.json b/supabase/drift-manifest.json
index f37e0b762..af1569902 100644
--- a/supabase/drift-manifest.json
+++ b/supabase/drift-manifest.json
@@ -1,9 +1,9 @@
 {
-  "generated_at": "2026-07-08T06:45:01.039Z",
+  "generated_at": "2026-07-09T06:25:31.894Z",
   "generator": "scripts/generate-drift-manifest.ts",
   "postgres_image": "supabase/postgres:17.6.1.127",
-  "schema_sha256": "f7ca50611471d4ced647bfc7731d72f87856bd03890f03eaca8e0ccb8affc6b0",
-  "replay_seconds": 13,
+  "schema_sha256": "6156b7d030de666c5d307769b796431b6ec72ea26659abad75fdd465bce503c8",
+  "replay_seconds": 12,
   "snapshot": {
     "views": [
       {
@@ -5901,6 +5901,14 @@
         "def_hash": "3f7a8939ee41c93b0c0126a6b1b65124",
         "signature": "public.purge_expired_rag_queries(integer)"
       },
+      {
+        "acl": [
+          "postgres=X/postgres",
+          "service_role=X/postgres"
+        ],
+        "def_hash": "8dbddbaae2cceed984bfeb7c0ee61df0",
+        "signature": "public.purge_expired_rag_query_misses(integer)"
+      },
       {
         "acl": [
           "postgres=X/postgres",
diff --git a/supabase/migrations/20260709150000_reconcile_ingestion_rpc_privileges.sql b/supabase/migrations/20260709150000_reconcile_ingestion_rpc_privileges.sql
new file mode 100644
index 000000000..832ea3fc2
--- /dev/null
+++ b/supabase/migrations/20260709150000_reconcile_ingestion_rpc_privileges.sql
@@ -0,0 +1,12 @@
+-- Reconcile ingestion RPC permissions (revoke execute from public)
+-- Recent migration 20260708130000 dropped and recreated complete_ingestion_job and fail_or_retry_ingestion_job.
+-- Since migrations run as supabase_admin on Supabase, the default privileges for role postgres
+-- do not apply. We must explicitly revoke PUBLIC execution on these new signatures.
+
+set search_path = public, pg_catalog, pg_temp;
+
+revoke execute on function public.complete_ingestion_job(uuid, uuid, uuid, text, text) from public, anon, authenticated;
+grant execute on function public.complete_ingestion_job(uuid, uuid, uuid, text, text) to service_role;
+
+revoke execute on function public.fail_or_retry_ingestion_job(uuid, uuid, uuid, boolean, text, text, text, timestamp with time zone, text) from public, anon, authenticated;
+grant execute on function public.fail_or_retry_ingestion_job(uuid, uuid, uuid, boolean, text, text, text, timestamp with time zone, text) to service_role;
diff --git a/supabase/schema.sql b/supabase/schema.sql
index 5c5a5ddea..318f83b64 100644
--- a/supabase/schema.sql
+++ b/supabase/schema.sql
@@ -2807,6 +2807,27 @@ $function$;
 revoke execute on function public.purge_expired_rag_queries(integer) from public, anon, authenticated;
 grant execute on function public.purge_expired_rag_queries(integer) to service_role;
 
+CREATE OR REPLACE FUNCTION public.purge_expired_rag_query_misses(p_retention_days integer DEFAULT 90)
+ RETURNS integer
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'public', 'pg_catalog', 'pg_temp'
+AS $function$
+declare
+  v_deleted integer;
+begin
+  if p_retention_days < 1 then
+    raise exception 'retention days must be positive';
+  end if;
+  delete from public.rag_query_misses where created_at < now() - make_interval(days => p_retention_days);
+  get diagnostics v_deleted = row_count;
+  return v_deleted;
+end;
+$function$;
+
+revoke execute on function public.purge_expired_rag_query_misses(integer) from public, anon, authenticated;
+grant execute on function public.purge_expired_rag_query_misses(integer) to service_role;
+
 CREATE OR REPLACE FUNCTION public.correct_clinical_query_terms(input_query text, min_sim real DEFAULT 0.45)
  RETURNS text
  LANGUAGE plpgsql
diff --git a/tests/document-index-units.test.ts b/tests/document-index-units.test.ts
index 0925e7fd7..facd25a00 100644
--- a/tests/document-index-units.test.ts
+++ b/tests/document-index-units.test.ts
@@ -243,4 +243,39 @@ describe("document index units", () => {
       metadata: expect.objectContaining({ visual_item_type: "sparse_visual_fallback" }),
     });
   });
+
+  it("repairs whitespace-fragmented OCR words against the source chunk", () => {
+    const units = buildDocumentIndexUnitInputs({
+      document,
+      chunks: [
+        {
+          id: "chunk-1",
+          document_id: "doc-1",
+          page_number: 7,
+          chunk_index: 0,
+          section_heading: "Discharge",
+          section_path: ["Discharge"],
+          content: "Psychosocial interventions should be documented before discharge.",
+          metadata: {},
+        },
+      ],
+      images: [
+        {
+          id: "image-ocr",
+          pageNumber: 7,
+          sourceKind: "table_crop",
+          tableTitle: "Discharge table",
+          tableRows: [["p ycho ocial", "Document before discharge"]],
+          tableColumns: ["Intervention", "Action"],
+          metadata: {},
+        },
+      ],
+    });
+
+    const repaired = units.find((unit) => unit.metadata.ocr_repair_version === "clean-chunk-fragment-v1");
+    expect(repaired?.content).toContain("psychosocial");
+    expect(repaired?.metadata.ocr_replacements).toEqual(
+      expect.arrayContaining([expect.objectContaining({ from: "p ycho ocial", to: "psychosocial" })]),
+    );
+  });
 });
diff --git a/tests/registry-corpus.test.ts b/tests/registry-corpus.test.ts
new file mode 100644
index 000000000..c78bf3986
--- /dev/null
+++ b/tests/registry-corpus.test.ts
@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+
+import { clinicalRegistryRowsToCorpusEntries } from "../src/lib/registry-corpus";
+import type { RegistryRecordRow } from "../src/lib/registry-records";
+
+function registryRow(overrides: Partial<RegistryRecordRow> = {}): RegistryRecordRow {
+  return {
+    id: "11111111-1111-4111-8111-111111111111",
+    owner_id: "22222222-2222-4222-8222-222222222222",
+    kind: "service",
+    slug: "crisis-service",
+    title: "Crisis service",
+    subtitle: "Urgent mental health access",
+    route: "Call the crisis line before transfer",
+    eligibility: "Acute mental health crisis",
+    cost: "No cost",
+    referral: "Phone referral required",
+    location: "Perth",
+    best_use: "Use for urgent triage",
+    catalogue_label: "Service",
+    navigator_query: "crisis service urgent triage",
+    tags: ["crisis", "triage"],
+    catchments: ["Perth"],
+    status_chips: [],
+    primary_contact: { label: "Phone", value: "Crisis line", kind: "phone" },
+    contacts: [],
+    summary_cards: [],
+    referral_info: [],
+    criteria: [],
+    verification: { locallyVerified: true, confidence: "High", notes: ["Fixture"] },
+    source: { label: "Local source", status: "Checked", reviewed: "July 2026", notes: [] },
+    source_status: "current",
+    validation_status: "locally_reviewed",
+    last_reviewed_at: null,
+    review_due_at: null,
+    catalog_payload: {},
+    created_at: "2026-07-01T00:00:00.000Z",
+    updated_at: "2026-07-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
+describe("registry corpus", () => {
+  it("converts registry rows into source-governed corpus entries", () => {
+    const [entry] = clinicalRegistryRowsToCorpusEntries([registryRow()]);
+
+    expect(entry).toMatchObject({
+      kind: "service",
+      subkind: "service",
+      ownerId: "22222222-2222-4222-8222-222222222222",
+      recordId: "11111111-1111-4111-8111-111111111111",
+      slug: "crisis-service",
+      title: "Crisis service",
+      sourceStatus: "current",
+      validationStatus: "locally_reviewed",
+    });
+    expect(entry?.content).toContain("Service: Crisis service");
+    expect(entry?.content).toContain("Route: Call the crisis line before transfer");
+    expect(entry?.searchText).toContain("crisis");
+  });
+
+  it("preserves form kind separately from service kind", () => {
+    const [entry] = clinicalRegistryRowsToCorpusEntries([
+      registryRow({ kind: "form", slug: "transport-order", title: "Transport order", catalogue_label: "Form" }),
+    ]);
+
+    expect(entry).toMatchObject({ kind: "form", subkind: "form", slug: "transport-order" });
+    expect(entry?.content).toContain("Form: Transport order");
+  });
+});
diff --git a/tests/source-governance.test.ts b/tests/source-governance.test.ts
index 9cca00d79..a56ebdd0d 100644
--- a/tests/source-governance.test.ts
+++ b/tests/source-governance.test.ts
@@ -250,6 +250,44 @@ describe("source governance warnings", () => {
     expect(visibleCodes).not.toContain("non_local_source");
   });
 
+  it("surfaces registry summaries as visible info warnings", () => {
+    const warnings = sourceGovernanceWarnings({
+      results: [
+        result({
+          source_metadata: {
+            source_kind: "registry_record",
+            source_title: "Crisis service summary",
+            publisher: "Clinical KB registry",
+            jurisdiction: "WA/local clinical workspace",
+            version: null,
+            publication_date: null,
+            review_date: null,
+            uploaded_at: null,
+            indexed_at: null,
+            uploaded_by: null,
+            document_status: "current",
+            clinical_validation_status: "locally_reviewed",
+            extraction_quality: "good",
+          },
+          indexing_quality: {
+            document_id: "doc-1",
+            quality_score: 0.9,
+            extraction_quality: "good",
+            metrics: {},
+            issues: [],
+          },
+          table_facts: [],
+        }),
+      ],
+    });
+
+    expect(warnings).toEqual([expect.objectContaining({ code: "registry_record_source", severity: "info" })]);
+    expect(frontendSourceGovernanceWarnings(warnings).map((warning) => warning.code)).toEqual([
+      "registry_record_source",
+    ]);
+    expect(groupSourceGovernanceWarnings(warnings)[0]?.message).toBe("1 registry summary used as supporting evidence.");
+  });
+
   it("keeps the refusal message free of backend and source-backed wording", () => {
     expect(sourceGovernanceRefusalAnswer).not.toMatch(/source-backed|source-governance|admin|need review/i);
     expect(sourceGovernanceRefusalAnswer).toContain("matched documents are not suitable for clinical use yet");

From 92161875b2375ba4a6fcc9a0fbcf660f2dc4f7ee Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 15:11:25 +0800
Subject: [PATCH 03/16] ci: add db-reset-verify and dependency-review workflows

---
 .github/workflows/ci.yml                | 26 ++++++++++++++++++++++++-
 .github/workflows/dependency-review.yml | 23 ++++++++++++++++++++++
 2 files changed, 48 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/dependency-review.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b54c429b6..76803701c 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -136,9 +136,33 @@ jobs:
             playwright-report/
           if-no-files-found: ignore
 
+  # Database migration replay in parallel with verify and ui-smoke, so we verify
+  # that our schema and migration chain can rebuild cleanly from scratch on
+  # every PR.
+  db-reset-verify:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+
+      - name: Setup Supabase CLI
+        uses: supabase/setup-cli@v1
+        with:
+          version: latest
+
+      - name: Start Supabase Local Emulator
+        run: supabase start
+
+      - name: Verify Migration Replay
+        run: supabase db reset
+
   release-browser-matrix:
     if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')
-    needs: [verify, ui-smoke]
+    needs: [verify, ui-smoke, db-reset-verify]
     runs-on: ubuntu-latest
     timeout-minutes: 70
 
diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
new file mode 100644
index 000000000..4b6956d38
--- /dev/null
+++ b/.github/workflows/dependency-review.yml
@@ -0,0 +1,23 @@
+name: Dependency Review
+
+on:
+  pull_request:
+    branches: [main, "release/**"]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  dependency-review:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Dependency Review
+        uses: actions/dependency-review-action@v4

From 83b437e4416fc4478c9fecedfbc2745f6365db1e Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 15:14:15 +0800
Subject: [PATCH 04/16] ci: remove dependency-review workflow because
 repository is private without GHAS

---
 .github/workflows/dependency-review.yml | 23 -----------------------
 1 file changed, 23 deletions(-)
 delete mode 100644 .github/workflows/dependency-review.yml

diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml
deleted file mode 100644
index 4b6956d38..000000000
--- a/.github/workflows/dependency-review.yml
+++ /dev/null
@@ -1,23 +0,0 @@
-name: Dependency Review
-
-on:
-  pull_request:
-    branches: [main, "release/**"]
-
-concurrency:
-  group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
-
-permissions:
-  contents: read
-
-jobs:
-  dependency-review:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Repository
-        uses: actions/checkout@v7
-        with:
-          persist-credentials: false
-      - name: Dependency Review
-        uses: actions/dependency-review-action@v4

From 6b7e5812f6fb155fe7c9a1aec65c6661ed519d18 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Thu, 9 Jul 2026 15:34:18 +0800
Subject: [PATCH 05/16] =?UTF-8?q?=F0=9F=93=9D=20CodeRabbit=20Chat:=20Simpl?=
 =?UTF-8?q?ify=20code=20implementation=20(#434)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
---
 scripts/reindex-image-generation-metadata.ts | 22 +++------
 scripts/seed-differential-records.ts         | 15 +++----
 scripts/seed-medication-records.ts           | 15 +++----
 scripts/seed-registry-records.ts             | 16 +++----
 src/lib/differential-seed.ts                 | 14 +++---
 src/lib/medication-seed.ts                   | 14 +++---
 src/lib/rag.ts                               | 27 +++++------
 src/lib/registry-corpus.ts                   | 47 ++++++++++++++++----
 src/lib/registry-seed.ts                     | 15 +++----
 9 files changed, 96 insertions(+), 89 deletions(-)

diff --git a/scripts/reindex-image-generation-metadata.ts b/scripts/reindex-image-generation-metadata.ts
index 3d0f4904e..ced585e07 100644
--- a/scripts/reindex-image-generation-metadata.ts
+++ b/scripts/reindex-image-generation-metadata.ts
@@ -80,19 +80,14 @@ function parseArgs(argv: string[]): Args {
       continue;
     }
 
+    if (token !== "--document-id" && token !== "--owner-id" && token !== "--limit") continue;
+
     const value = argv[index + 1];
-    if (!value || value.startsWith("--")) {
-      if (token === "--document-id" || token === "--owner-id" || token === "--limit") {
-        throw new Error(`Missing value for ${token}`);
-      }
-      continue;
-    }
+    if (!value || value.startsWith("--")) throw new Error(`Missing value for ${token}`);
     if (token === "--document-id") args.documentId = value;
-    if (token === "--owner-id") args.ownerId = value;
-    if (token === "--limit") args.limit = Number.parseInt(value, 10);
-    if (token === "--document-id" || token === "--owner-id" || token === "--limit") {
-      index += 1;
-    }
+    else if (token === "--owner-id") args.ownerId = value;
+    else args.limit = Number.parseInt(value, 10);
+    index += 1;
   }
 
   if (!Number.isFinite(args.limit) || args.limit <= 0) {
@@ -105,11 +100,8 @@ function parseArgs(argv: string[]): Args {
 }
 
 function rowNeedsRefresh(row: ImageRow, committedGeneration: string) {
-  const rowMetadataGeneration = committedIndexGeneration(row.metadata);
   if (row.index_generation_id !== null && row.index_generation_id !== committedGeneration) return true;
-  return row.index_generation_id === null
-    ? rowMetadataGeneration !== committedGeneration
-    : rowMetadataGeneration !== committedGeneration;
+  return committedIndexGeneration(row.metadata) !== committedGeneration;
 }
 
 async function loadDocuments(args: {
diff --git a/scripts/seed-differential-records.ts b/scripts/seed-differential-records.ts
index 0283258c9..2120bd5a1 100644
--- a/scripts/seed-differential-records.ts
+++ b/scripts/seed-differential-records.ts
@@ -3,7 +3,7 @@ import { loadEnvConfig } from "@next/env";
 import { confirm } from "./cli-utils";
 import { buildDefaultDifferentialRows, loadDifferentialSnapshot } from "@/lib/differential-fixtures";
 import type { DifferentialRecordRow } from "@/lib/differential-records";
-import { embedDifferentialRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import { embedDifferentialRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 
 loadEnvConfig(process.cwd());
 
@@ -126,13 +126,12 @@ async function main() {
   }
 
   if (registryCorpusEmbeddingEnabled()) {
-    const { data: embeddedRows, error: embedRowsError } = await supabase
-      .from("differential_records")
-      .select("*")
-      .eq("owner_id", args.ownerId);
-    if (embedRowsError) throw new Error(`Could not reload differential rows for embedding: ${embedRowsError.message}`);
-    const embedded = await embedDifferentialRows(supabase, (embeddedRows ?? []) as DifferentialRecordRow[]);
-    console.log(`[differentials:seed] Embedded ${embedded.chunkCount} registry corpus chunk(s).`);
+    const chunkCount = await embedReloadedOwnerRows(
+      supabase.from("differential_records").select("*").eq("owner_id", args.ownerId),
+      (rows) => embedDifferentialRows(supabase, rows as DifferentialRecordRow[]),
+      "differential",
+    );
+    console.log(`[differentials:seed] Embedded ${chunkCount} registry corpus chunk(s).`);
   }
 }
 
diff --git a/scripts/seed-medication-records.ts b/scripts/seed-medication-records.ts
index 09582e05a..0806ac820 100644
--- a/scripts/seed-medication-records.ts
+++ b/scripts/seed-medication-records.ts
@@ -2,7 +2,7 @@ import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
 import { buildMedicationSeedRows } from "@/lib/medication-seed";
-import { embedMedicationRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import { embedMedicationRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import type { MedicationRecordRow } from "@/lib/medication-records";
 
 loadEnvConfig(process.cwd());
@@ -123,13 +123,12 @@ async function main() {
   }
 
   if (registryCorpusEmbeddingEnabled()) {
-    const { data: embeddedRows, error: embedRowsError } = await supabase
-      .from("medication_records")
-      .select("*")
-      .eq("owner_id", args.ownerId);
-    if (embedRowsError) throw new Error(`Could not reload medication rows for embedding: ${embedRowsError.message}`);
-    const embedded = await embedMedicationRows(supabase, (embeddedRows ?? []) as MedicationRecordRow[]);
-    console.log(`[medications:seed] Embedded ${embedded.chunkCount} registry corpus chunk(s).`);
+    const chunkCount = await embedReloadedOwnerRows(
+      supabase.from("medication_records").select("*").eq("owner_id", args.ownerId),
+      (rows) => embedMedicationRows(supabase, rows as MedicationRecordRow[]),
+      "medication",
+    );
+    console.log(`[medications:seed] Embedded ${chunkCount} registry corpus chunk(s).`);
   }
 }
 
diff --git a/scripts/seed-registry-records.ts b/scripts/seed-registry-records.ts
index 97bc0482b..5d548b89c 100644
--- a/scripts/seed-registry-records.ts
+++ b/scripts/seed-registry-records.ts
@@ -1,7 +1,7 @@
 import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
-import { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import { embedClinicalRegistryRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import type { RegistryRecordRow } from "@/lib/registry-records";
 import { type RegistryRecordKind } from "@/lib/registry-records";
 import { buildDefaultRegistryRows, defaultRegistryRecords } from "@/lib/registry-seed";
@@ -149,14 +149,12 @@ async function main() {
 
   if (registryCorpusEmbeddingEnabled()) {
     const kinds: RegistryRecordKind[] = args.kind === "all" ? ["service", "form"] : [args.kind];
-    const { data: embeddedRows, error: embedRowsError } = await supabase
-      .from("clinical_registry_records")
-      .select("*")
-      .eq("owner_id", args.ownerId)
-      .in("kind", kinds);
-    if (embedRowsError) throw new Error(`Could not reload registry rows for embedding: ${embedRowsError.message}`);
-    const embedded = await embedClinicalRegistryRows(supabase, (embeddedRows ?? []) as RegistryRecordRow[]);
-    console.log(`[registry:seed] Embedded ${embedded.chunkCount} registry corpus chunk(s).`);
+    const chunkCount = await embedReloadedOwnerRows(
+      supabase.from("clinical_registry_records").select("*").eq("owner_id", args.ownerId).in("kind", kinds),
+      (rows) => embedClinicalRegistryRows(supabase, rows as RegistryRecordRow[]),
+      "registry",
+    );
+    console.log(`[registry:seed] Embedded ${chunkCount} registry corpus chunk(s).`);
   }
 }
 
diff --git a/src/lib/differential-seed.ts b/src/lib/differential-seed.ts
index c1b17d3f2..4e36421e4 100644
--- a/src/lib/differential-seed.ts
+++ b/src/lib/differential-seed.ts
@@ -1,6 +1,6 @@
 import { buildDefaultDifferentialRows } from "@/lib/differential-fixtures";
 import { type DifferentialRecordInsert, type DifferentialRecordRow } from "@/lib/differential-records";
-import { embedDifferentialRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import { bestEffortEmbedRows, embedDifferentialRows } from "@/lib/registry-corpus";
 
 type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
 
@@ -17,13 +17,11 @@ export async function ensureDifferentialsSeeded(
     .select("*");
   if (error) throw new Error(`Differential seed failed: ${error.message}`);
   const seededRows = (data ?? []) as DifferentialRecordRow[];
-  if (registryCorpusEmbeddingEnabled()) {
-    try {
-      await embedDifferentialRows(supabase, seededRows);
-    } catch (embedError) {
-      console.error(`[differentials] corpus embedding failed for owner ${ownerId}`, embedError);
-    }
-  }
+  await bestEffortEmbedRows({
+    scope: "differentials",
+    ownerId,
+    embed: () => embedDifferentialRows(supabase, seededRows),
+  });
   return seededRows;
 }
 
diff --git a/src/lib/medication-seed.ts b/src/lib/medication-seed.ts
index 78179fb41..e02850e37 100644
--- a/src/lib/medication-seed.ts
+++ b/src/lib/medication-seed.ts
@@ -1,5 +1,5 @@
 import { buildDefaultMedicationRows, defaultMedicationRecords } from "@/lib/medication-fixtures";
-import { embedMedicationRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import { bestEffortEmbedRows, embedMedicationRows } from "@/lib/registry-corpus";
 import { type MedicationRecordInsert, type MedicationRecordRow } from "@/lib/medication-records";
 
 type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
@@ -16,13 +16,11 @@ export async function ensureMedicationsSeeded(supabase: AdminClient, ownerId: st
     .select("*");
   if (error) throw new Error(`Medication seed failed: ${error.message}`);
   const seededRows = (data ?? []) as MedicationRecordRow[];
-  if (registryCorpusEmbeddingEnabled()) {
-    try {
-      await embedMedicationRows(supabase, seededRows);
-    } catch (embedError) {
-      console.error(`[medications] corpus embedding failed for owner ${ownerId}`, embedError);
-    }
-  }
+  await bestEffortEmbedRows({
+    scope: "medications",
+    ownerId,
+    embed: () => embedMedicationRows(supabase, seededRows),
+  });
   return seededRows;
 }
 
diff --git a/src/lib/rag.ts b/src/lib/rag.ts
index b33e6fb58..11c45fe9f 100644
--- a/src/lib/rag.ts
+++ b/src/lib/rag.ts
@@ -2376,9 +2376,8 @@ async function attachDocumentRankingMetadata(
     for (const row of metadataRows) {
       cache.documentMetadata.set(row.document_id, { labels: row.labels, summary: row.summary });
     }
-    const metadataByDocument = new Map(metadataRows.map((row) => [row.document_id, row]));
     const enriched = results.map((result) => {
-      const metadata = metadataByDocument.get(result.document_id) ?? cache.documentMetadata.get(result.document_id);
+      const metadata = cache.documentMetadata.get(result.document_id);
       if (!metadata) return result;
       return {
         ...result,
@@ -2392,6 +2391,13 @@ async function attachDocumentRankingMetadata(
   }
 }
 
+function withCachedIndexQuality(results: SearchResult[], cache: DocumentRankingMetadataCache) {
+  return results.map((result) => ({
+    ...result,
+    indexing_quality: cache.indexQuality.get(result.document_id) ?? result.indexing_quality ?? null,
+  }));
+}
+
 async function attachIndexQualityMetadata(
   supabase: ReturnType<typeof createAdminClient>,
   results: SearchResult[],
@@ -2401,12 +2407,7 @@ async function attachIndexQualityMetadata(
   const documentIds = Array.from(new Set(results.map((result) => result.document_id)));
   if (documentIds.length === 0) return results;
   const missingDocumentIds = documentIds.filter((documentId) => !cache.indexQuality.has(documentId));
-  if (missingDocumentIds.length === 0) {
-    return results.map((result) => ({
-      ...result,
-      indexing_quality: cache.indexQuality.get(result.document_id) ?? result.indexing_quality ?? null,
-    }));
-  }
+  if (missingDocumentIds.length === 0) return withCachedIndexQuality(results, cache);
   try {
     let query = supabase
       .from("document_index_quality")
@@ -2417,15 +2418,7 @@ async function attachIndexQualityMetadata(
     if (error) return results;
     for (const documentId of missingDocumentIds) cache.indexQuality.set(documentId, null);
     for (const row of data ?? []) cache.indexQuality.set(row.document_id, row as SearchResult["indexing_quality"]);
-    const qualityByDocument = new Map((data ?? []).map((row) => [row.document_id, row]));
-    return results.map((result) => ({
-      ...result,
-      indexing_quality:
-        (qualityByDocument.get(result.document_id) as SearchResult["indexing_quality"]) ??
-        cache.indexQuality.get(result.document_id) ??
-        result.indexing_quality ??
-        null,
-    }));
+    return withCachedIndexQuality(results, cache);
   } catch {
     return results;
   }
diff --git a/src/lib/registry-corpus.ts b/src/lib/registry-corpus.ts
index 8a3bcfc1c..854270a1a 100644
--- a/src/lib/registry-corpus.ts
+++ b/src/lib/registry-corpus.ts
@@ -80,11 +80,17 @@ function registryBaseMetadata(entry: RegistryCorpusEntry): Record<string, Json>
   };
 }
 
+function registryDocumentId(entry: RegistryCorpusEntry) {
+  return deterministicUuid(`registry-document:${entry.kind}:${entry.recordId}`);
+}
+
+function registryEntryMetadata(entry: RegistryCorpusEntry): Record<string, Json> {
+  return { ...registryBaseMetadata(entry), ...entry.metadata };
+}
+
 function registryDocumentRow(entry: RegistryCorpusEntry): TablesInsert<"documents"> {
-  const documentId = deterministicUuid(`registry-document:${entry.kind}:${entry.recordId}`);
-  const metadata = { ...registryBaseMetadata(entry), ...entry.metadata };
   return {
-    id: documentId,
+    id: registryDocumentId(entry),
     owner_id: entry.ownerId,
     title: entry.title,
     description: entry.subtitle,
@@ -98,16 +104,14 @@ function registryDocumentRow(entry: RegistryCorpusEntry): TablesInsert<"document
     chunk_count: 1,
     image_count: 0,
     content_hash: sha256(entry.content),
-    metadata,
+    metadata: registryEntryMetadata(entry),
   };
 }
 
 function registryChunkRow(entry: RegistryCorpusEntry, embedding: Vector): TablesInsert<"document_chunks"> {
-  const documentId = deterministicUuid(`registry-document:${entry.kind}:${entry.recordId}`);
-  const metadata = { ...registryBaseMetadata(entry), ...entry.metadata };
   return {
     id: deterministicUuid(`registry-chunk:${entry.kind}:${entry.recordId}`),
-    document_id: documentId,
+    document_id: registryDocumentId(entry),
     chunk_index: 0,
     page_number: 1,
     section_heading: "Registry summary",
@@ -118,7 +122,7 @@ function registryChunkRow(entry: RegistryCorpusEntry, embedding: Vector): Tables
     image_ids: [],
     content_hash: sha256(entry.content),
     embedding,
-    metadata,
+    metadata: registryEntryMetadata(entry),
   };
 }
 
@@ -275,3 +279,30 @@ export function embedMedicationRows(supabase: AdminClient, rows: MedicationRecor
 export function embedDifferentialRows(supabase: AdminClient, rows: DifferentialRecordRow[]) {
   return embedRegistryCorpusEntries(supabase, differentialRowsToCorpusEntries(rows));
 }
+
+/** Best-effort corpus embedding for a seed path: failures are logged, not thrown,
+ *  so a broken embedding call never blocks the seed write it runs after. */
+export async function bestEffortEmbedRows(args: { scope: string; ownerId: string; detail?: string; embed: () => Promise<unknown> }) {
+  if (!registryCorpusEmbeddingEnabled()) return;
+  try {
+    await args.embed();
+  } catch (embedError) {
+    const suffix = args.detail ? ` ${args.detail}` : "";
+    console.error(`[${args.scope}] corpus embedding failed for owner ${args.ownerId}${suffix}`, embedError);
+  }
+}
+
+/** Reload an owner's rows for a table and embed them, returning the chunk count
+ *  written. Shared by the registry/medication/differential seed CLIs, which each
+ *  re-read their own rows (rather than reusing the upsert response) so the
+ *  embedded corpus always reflects what is actually stored. */
+export async function embedReloadedOwnerRows<Row>(
+  reload: PromiseLike<{ data: Row[] | null; error: { message: string } | null }>,
+  embed: (rows: Row[]) => Promise<{ chunkCount: number }>,
+  tableLabel: string,
+) {
+  const { data, error } = await reload;
+  if (error) throw new Error(`Could not reload ${tableLabel} rows for embedding: ${error.message}`);
+  const { chunkCount } = await embed(data ?? []);
+  return chunkCount;
+}
diff --git a/src/lib/registry-seed.ts b/src/lib/registry-seed.ts
index 4078b3879..0b42f24e6 100644
--- a/src/lib/registry-seed.ts
+++ b/src/lib/registry-seed.ts
@@ -1,6 +1,6 @@
 import { formRecords } from "@/lib/forms";
 import { buildDefaultFormRows, buildDefaultServiceRows, defaultServiceRecords } from "@/lib/registry-fixtures";
-import { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import { bestEffortEmbedRows, embedClinicalRegistryRows } from "@/lib/registry-corpus";
 import { type RegistryRecordInsert, type RegistryRecordKind, type RegistryRecordRow } from "@/lib/registry-records";
 
 // Type-only reference to the admin client so this module carries no runtime
@@ -44,13 +44,12 @@ export async function ensureRegistrySeeded(
     .select("*");
   if (error) throw new Error(`Registry seed failed: ${error.message}`);
   const seededRows = (data ?? []) as RegistryRecordRow[];
-  if (registryCorpusEmbeddingEnabled()) {
-    try {
-      await embedClinicalRegistryRows(supabase, seededRows);
-    } catch (embedError) {
-      console.error(`[registry] corpus embedding failed for owner ${ownerId} (${kind})`, embedError);
-    }
-  }
+  await bestEffortEmbedRows({
+    scope: "registry",
+    ownerId,
+    detail: `(${kind})`,
+    embed: () => embedClinicalRegistryRows(supabase, seededRows),
+  });
   return seededRows;
 }
 

From 7efedc2cb3309b1324bc67d8c0b96ac3b3008cb5 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 15:48:48 +0800
Subject: [PATCH 06/16] fix(db): rename duplicate migration version
 20260708160000 to unique 20260708160001

---
 ...sql => 20260708160001_retrieval_owner_matches_fail_closed.sql} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename supabase/migrations/{20260708160000_retrieval_owner_matches_fail_closed.sql => 20260708160001_retrieval_owner_matches_fail_closed.sql} (100%)

diff --git a/supabase/migrations/20260708160000_retrieval_owner_matches_fail_closed.sql b/supabase/migrations/20260708160001_retrieval_owner_matches_fail_closed.sql
similarity index 100%
rename from supabase/migrations/20260708160000_retrieval_owner_matches_fail_closed.sql
rename to supabase/migrations/20260708160001_retrieval_owner_matches_fail_closed.sql

From 24314db5abb9310fb03551d299c29d73d13f6fa4 Mon Sep 17 00:00:00 2001
From: Copilot <198982749+Copilot@users.noreply.github.com>
Date: Thu, 9 Jul 2026 16:13:24 +0800
Subject: [PATCH 07/16] fix: run prettier on 19 files to fix CI format:check
 failure (#436)

---
 .cursor/skills/accessibility-review/SKILL.md  |  2 ++
 .../skills/ai-architecture-review/SKILL.md    |  3 ++
 .cursor/skills/api-review/SKILL.md            |  4 +++
 .cursor/skills/code-quality-review/SKILL.md   |  2 ++
 .cursor/skills/design-review/SKILL.md         |  2 ++
 .../frontend-architecture-review/SKILL.md     |  2 ++
 .cursor/skills/performance-review/SKILL.md    |  2 ++
 .../skills/release-readiness-review/SKILL.md  |  2 ++
 .cursor/skills/repo-auditor/SKILL.md          |  1 +
 .cursor/skills/security-review/SKILL.md       |  2 ++
 .../CHANGELOG.md                              | 20 +++++-------
 .../supabase-postgres-best-practices/SKILL.md | 22 +++++++------
 .../references/_contributing.md               | 26 +++++++--------
 .../references/_sections.md                   |  8 +++++
 .cursor/skills/supabase/CHANGELOG.md          | 32 ++++++++-----------
 .cursor/skills/testing-review/SKILL.md        |  2 ++
 .cursor/skills/ux-review/SKILL.md             |  2 ++
 scripts/seed-registry-records.ts              |  6 +++-
 src/lib/registry-corpus.ts                    |  7 +++-
 19 files changed, 90 insertions(+), 57 deletions(-)

diff --git a/.cursor/skills/accessibility-review/SKILL.md b/.cursor/skills/accessibility-review/SKILL.md
index 209a598a9..20f697292 100644
--- a/.cursor/skills/accessibility-review/SKILL.md
+++ b/.cursor/skills/accessibility-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing user interfaces to ensure compliance with a11y sta
 ## Review Checklist
 
 ### 1. Keyboard & Focus Control
+
 - **Interactive Elements:** Verify all button-like and link-like components use semantic HTML elements (`<button>`, `<a>`) rather than `div` tags with onClick handlers.
 - **Focus Trapping:** Ensure modal dialogs, side drawers, and search overlays trap keyboard focus properly and support `Esc` key cancellation.
 
 ### 2. ARIA & Reader Markup
+
 - **Labels:** Verify that icon-only buttons, custom inputs, and dynamic charts include appropriate `aria-label` or screen-reader descriptions.
 - **Table Structure:** Ensure data tables (like document table facts) use correct semantic tags (`<thead>`, `<tbody>`, `<th>`) for readable text-to-speech rendering.
diff --git a/.cursor/skills/ai-architecture-review/SKILL.md b/.cursor/skills/ai-architecture-review/SKILL.md
index 2a8f5c44b..74df735d9 100644
--- a/.cursor/skills/ai-architecture-review/SKILL.md
+++ b/.cursor/skills/ai-architecture-review/SKILL.md
@@ -10,14 +10,17 @@ Use this skill when reviewing or modifying the RAG (Retrieval-Augmented Generati
 ## Review Checklist
 
 ### 1. Retrieval Quality & Provenance
+
 - **Hybrid Search:** Confirm queries use proper hybrid search patterns (pgvector + semantic/trigram matching) and respect user/organization boundaries.
 - **Provenance / Citations:** Ensure generated answers are strongly tied to source documents and include clean, traceable citation references.
 - **Fail-Closed Policy:** If no relevant documents are retrieved or verification fails, the system must degrade gracefully or return a clear "No evidence found" response rather than hallucinating.
 
 ### 2. Model Routing & Timeout Logic
+
 - **Routing Rules:** Check that routing between fast and strong models follows defined rules (e.g. `RAG_PROVIDER_MODE`).
 - **Timeouts:** Ensure LLM calls are bounded by client and server-side timeouts (e.g., `OPENAI_ANSWER_TIMEOUT_MS`).
 
 ### 3. Structured Output & Safety
+
 - **Schema Conformity:** Validate that LLM responses use strict schema structures (e.g., OpenAI structured JSON output) to prevent parsing errors.
 - **Safety Filters:** Check that toxicity, safety filters, and prompt injection mitigations are active on user inputs and LLM outputs.
diff --git a/.cursor/skills/api-review/SKILL.md b/.cursor/skills/api-review/SKILL.md
index c491ac380..92c96971d 100644
--- a/.cursor/skills/api-review/SKILL.md
+++ b/.cursor/skills/api-review/SKILL.md
@@ -10,19 +10,23 @@ Use this skill when reviewing or modifying API routes, endpoints, or network bou
 ## Review Checklist
 
 ### 1. Request Validation
+
 - **Zod Schemas:** Ensure all incoming requests (`req.json()`, query parameters, route segments) are validated using strict Zod schemas.
 - **Fail Early:** Requests failing schema validation must return `400 Bad Request` immediately before running downstream DB or AI logic.
 - **Safety check:** Validate input boundaries (e.g., maximum string length, non-empty collections, limit boundaries on pagination).
 
 ### 2. Error Handling & Taxonomy
+
 - **Closed Errors:** Avoid throwing raw database, library, or system errors to the client. Wrap exceptions in consistent JSON error envelopes.
 - **HTTP Semantics:** Use correct HTTP status codes (e.g., `401 Unauthorized` vs `403 Forbidden`, `404 Not Found` for missing resources, `429 Too Many Requests` for rate limits).
 - **Consistency:** Ensure error payloads follow a unified schema, containing a clear error code (e.g., `VALIDATION_FAILED`, `INTERNAL_ERROR`) and user-safe descriptions.
 
 ### 3. Response Contracts
+
 - **Serialization:** Explicitly define the serialized JSON shape of the response. Avoid passing DB model instances directly to the frontend.
 - **Pagination:** For resource listing APIs, verify pagination params (`limit`, `offset` / `cursor`) are implemented, validated, and bounded.
 
 ### 4. Authentication & Authorization
+
 - **Server-Side Enforcement:** Do not rely on client assertions. Re-authenticate user credentials (JWT / session cookies) server-side.
 - **Tenant Isolation:** Ensure fetched resources are filtered by the active user's identity (`user_id`).
diff --git a/.cursor/skills/code-quality-review/SKILL.md b/.cursor/skills/code-quality-review/SKILL.md
index 40567d068..add222b68 100644
--- a/.cursor/skills/code-quality-review/SKILL.md
+++ b/.cursor/skills/code-quality-review/SKILL.md
@@ -10,10 +10,12 @@ Use this skill when auditing source files for maintainability, readability, and
 ## Review Checklist
 
 ### 1. Maintainability & Naming
+
 - **Clean Naming:** Ensure functions, variables, and database keys carry logical, self-describing names.
 - **Decomposition:** Look for bloated files/functions that should be decomposed. Keep modules focused on a single responsibility.
 - **Duplication (DRY):** Consolidate duplicate helper logic, styles, and configurations.
 
 ### 2. Logic & Complexity
+
 - **Control Flow:** Simplify nested conditionals, deeply nested loops, or fragile edge-case handling.
 - **Dead Code:** Remove unused functions, comments, or commented-out code blocks left behind.
diff --git a/.cursor/skills/design-review/SKILL.md b/.cursor/skills/design-review/SKILL.md
index ee1e4636b..e52718181 100644
--- a/.cursor/skills/design-review/SKILL.md
+++ b/.cursor/skills/design-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when auditing UI styling, colors, layout structures, and spacing
 ## Review Checklist
 
 ### 1. Style & Spacing Consistency
+
 - **Design System Tokens:** Ensure custom components utilize predefined design variables (colors, borders, shadows, font sizes) rather than ad-hoc inline styles.
 - **Layout Spacing:** Check for consistent paddings, margins, grid gaps, and alignment.
 
 ### 2. Clinical Theme Adherence
+
 - **Layout Density:** Review components to confirm the visual target is dense, clean, calm, and fast to scan rather than overly flashy or visually expressive.
 - **Browser QA / Screenshot Verification:** For major UI changes, run a local dev server with `npm run ensure` and capture screenshots to verify cross-device visual fidelity.
diff --git a/.cursor/skills/frontend-architecture-review/SKILL.md b/.cursor/skills/frontend-architecture-review/SKILL.md
index 295b74593..626c9bef2 100644
--- a/.cursor/skills/frontend-architecture-review/SKILL.md
+++ b/.cursor/skills/frontend-architecture-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing Next.js App Router structures, component boundarie
 ## Review Checklist
 
 ### 1. Next.js App Router Boundaries
+
 - **RSC vs. Client Components:** Ensure components are Server Components by default. Keep client-side logic (`use state`, `use effect`, browser APIs) isolated to leaf components marked with `"use client"`.
 - **Data Fetching:** Fetch data in Server Components or Server Actions where possible. Avoid calling internal `/api/...` endpoints directly from RSCs.
 
 ### 2. State & Rendering
+
 - **State Duplication:** Avoid replicating URL/router state in local React state. Prefer URLSearchParams and next/navigation controls for search/filters.
 - **Rendering Waste:** Check for unnecessary context re-renders, un-memoized expensive calculations, or excessive component mount/unmount cycles.
diff --git a/.cursor/skills/performance-review/SKILL.md b/.cursor/skills/performance-review/SKILL.md
index c8ae00f46..af66b5fad 100644
--- a/.cursor/skills/performance-review/SKILL.md
+++ b/.cursor/skills/performance-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing query bottlenecks, database RPC latencies, client
 ## Review Checklist
 
 ### 1. Database & API Latency
+
 - **Query Caching:** Verify that repetitive/expensive database fetches and RAG queries leverage caching layers (e.g. `rag_response_cache`).
 - **Index Optimization:** Ensure queries leverage appropriate indices (e.g., trigram/lexical text indexes, vector HNSW).
 
 ### 2. LLM & Asset Loading
+
 - **Token Overhead:** Check that prompt sizes and context window limits are optimized to keep API costs down.
 - **Resource Streaming:** Ensure heavy document rendering, search lists, and PDF asset previews load incrementally or use lazy-loading controls.
diff --git a/.cursor/skills/release-readiness-review/SKILL.md b/.cursor/skills/release-readiness-review/SKILL.md
index 0760f9fa0..eac0fb971 100644
--- a/.cursor/skills/release-readiness-review/SKILL.md
+++ b/.cursor/skills/release-readiness-review/SKILL.md
@@ -10,11 +10,13 @@ Use this skill when preparing a branch for merging, pull request submission, or
 ## Review Checklist
 
 ### 1. Build & Automation Checks
+
 - **Static Analysis:** Confirm `npm run lint` and `npm run typecheck` run clean.
 - **Verification Gates:** Ensure the appropriate verification scripts run successfully (`npm run verify:cheap` at minimum; `npm run verify:release` for full handoffs).
 - **Target database checks:** Run `npm run check:supabase-project` to confirm env targets match `Clinical KB Database` ref `sjrfecxgysukkwxsowpy`.
 
 ### 2. Clinical Governance Compliance
+
 - **Preflight Verification:** Complete all checklist items in `.github/pull_request_template.md`.
 - **Secret Scan:** Confirm no private configuration files (`.env.local`), local debug logs, or keys are present in the git stage.
 - **Production Readiness Check:** Run `npm run check:production-readiness` for privacy, ingestion, or clinical behavior changes.
diff --git a/.cursor/skills/repo-auditor/SKILL.md b/.cursor/skills/repo-auditor/SKILL.md
index 577a06798..2b48c5bde 100644
--- a/.cursor/skills/repo-auditor/SKILL.md
+++ b/.cursor/skills/repo-auditor/SKILL.md
@@ -10,6 +10,7 @@ Use this skill when auditing the workspace layout, folder structures, imports, a
 ## Review Checklist
 
 ### 1. Structural Audits
+
 - **Broken Imports:** Scan modified files for broken relative imports, incorrect library names, or obsolete modules.
 - **Unused Files:** Identify and safely remove files that are truly dead and not part of route mappings, active scripts, migrations, or test resources.
 - **Consolidation:** Check for identical or redundant configuration keys, environment variables, or scripts that can be safely merged.
diff --git a/.cursor/skills/security-review/SKILL.md b/.cursor/skills/security-review/SKILL.md
index d58ce01e6..663195611 100644
--- a/.cursor/skills/security-review/SKILL.md
+++ b/.cursor/skills/security-review/SKILL.md
@@ -10,10 +10,12 @@ Use this skill when reviewing code that touches authentication, database schemas
 ## Review Checklist
 
 ### 1. Key Confinement & Environment Safety
+
 - **Service Role Key:** Ensure the Supabase `service_role` key is never exposed to public clients. Never prefix variables containing secret keys with `NEXT_PUBLIC_`.
 - **Credential Storage:** Verify that credentials are not committed or hardcoded. Look for placeholder usage in `.env.example`.
 
 ### 2. Database & Storage Safety
+
 - **Row-Level Security (RLS):** Ensure RLS is active on all public/exposed tables. Avoid deprecated checkers like `auth.role()` and prefer strict role predicates (`TO authenticated`).
 - **Owner Scope Verification:** Verify that API endpoints filter queries by the authenticated user's ID (`user_id`) to prevent unauthorized cross-tenant data access.
 - **Storage Buckets:** Verify that files uploaded to private buckets (`clinical-documents`, `clinical-images`) require validated user signatures for retrieval.
diff --git a/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
index 94aee4878..e4d7c09be 100644
--- a/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
+++ b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
@@ -2,28 +2,24 @@
 
 ## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
 
-
 ### Features
 
-* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
+- add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
 
 ### Bug Fixes
 
-* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
 
 ## [1.2.0](https://github.com/supabase/agent-skills/compare/v1.1.1...v1.2.0) (2026-06-02)
 
-
 ### Features
 
-* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
+- add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
 
 ### Bug Fixes
 
-* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
diff --git a/.cursor/skills/supabase-postgres-best-practices/SKILL.md b/.cursor/skills/supabase-postgres-best-practices/SKILL.md
index d9ef1949f..07aa1b3a6 100644
--- a/.cursor/skills/supabase-postgres-best-practices/SKILL.md
+++ b/.cursor/skills/supabase-postgres-best-practices/SKILL.md
@@ -17,6 +17,7 @@ Comprehensive performance optimization guide for Postgres, maintained by Supabas
 ## When to Apply
 
 Reference these guidelines when:
+
 - Writing SQL queries or designing schemas
 - Implementing indexes or query optimization
 - Reviewing database performance issues
@@ -26,16 +27,16 @@ Reference these guidelines when:
 
 ## Rule Categories by Priority
 
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Query Performance | CRITICAL | `query-` |
-| 2 | Connection Management | CRITICAL | `conn-` |
-| 3 | Security & RLS | CRITICAL | `security-` |
-| 4 | Schema Design | HIGH | `schema-` |
-| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
-| 6 | Data Access Patterns | MEDIUM | `data-` |
-| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
-| 8 | Advanced Features | LOW | `advanced-` |
+| Priority | Category                 | Impact      | Prefix      |
+| -------- | ------------------------ | ----------- | ----------- |
+| 1        | Query Performance        | CRITICAL    | `query-`    |
+| 2        | Connection Management    | CRITICAL    | `conn-`     |
+| 3        | Security & RLS           | CRITICAL    | `security-` |
+| 4        | Schema Design            | HIGH        | `schema-`   |
+| 5        | Concurrency & Locking    | MEDIUM-HIGH | `lock-`     |
+| 6        | Data Access Patterns     | MEDIUM      | `data-`     |
+| 7        | Monitoring & Diagnostics | LOW-MEDIUM  | `monitor-`  |
+| 8        | Advanced Features        | LOW         | `advanced-` |
 
 ## How to Use
 
@@ -48,6 +49,7 @@ references/_sections.md
 ```
 
 Each rule file contains:
+
 - Brief explanation of why it matters
 - Incorrect SQL example with explanation
 - Correct SQL example with explanation
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
index 1c055aff9..4c3efce95 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
@@ -27,7 +27,7 @@ to recognize anti-patterns.
 
 Include specific metrics. Helps agents prioritize fixes.
 
-**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1" 
+**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
 **Bad:** "Faster", "Better", "More efficient"
 
 ### 4. Self-Contained Examples
@@ -105,9 +105,7 @@ Most references should focus on pure SQL patterns. This keeps examples portable.
 
 ```typescript
 for (const user of users) {
-  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
-    user.id,
-  ]);
+  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [user.id]);
 }
 ```
 ````
@@ -115,23 +113,21 @@ for (const user of users) {
 **Correct (batch query):**
 
 ```typescript
-const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
-  userIds,
-]);
+const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [userIds]);
 ```
 
 ---
 
 ## Impact Level Guidelines
 
-| Level | Improvement | Use When |
-|-------|-------------|----------|
-| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
-| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
-| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
-| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
-| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
-| **LOW** | Incremental | Advanced patterns, edge cases |
+| Level           | Improvement | Use When                                                                 |
+| --------------- | ----------- | ------------------------------------------------------------------------ |
+| **CRITICAL**    | 10-100x     | Missing indexes, connection exhaustion, sequential scans on large tables |
+| **HIGH**        | 5-20x       | Wrong index types, poor partitioning, missing covering indexes           |
+| **MEDIUM-HIGH** | 2-5x        | N+1 queries, inefficient pagination, RLS optimization                    |
+| **MEDIUM**      | 1.5-3x      | Redundant indexes, query plan instability                                |
+| **LOW-MEDIUM**  | 1.2-2x      | VACUUM tuning, configuration tweaks                                      |
+| **LOW**         | Incremental | Advanced patterns, edge cases                                            |
 
 ---
 
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/_sections.md b/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
index 8ba57c23e..42c16e707 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
@@ -7,33 +7,41 @@ Take the examples below as pure demonstrative. Replace each section with the act
 ---
 
 ## 1. Query Performance (query)
+
 **Impact:** CRITICAL
 **Description:** Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.
 
 ## 2. Connection Management (conn)
+
 **Impact:** CRITICAL
 **Description:** Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.
 
 ## 3. Security & RLS (security)
+
 **Impact:** CRITICAL
 **Description:** Row-Level Security policies, privilege management, and authentication patterns.
 
 ## 4. Schema Design (schema)
+
 **Impact:** HIGH
 **Description:** Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.
 
 ## 5. Concurrency & Locking (lock)
+
 **Impact:** MEDIUM-HIGH
 **Description:** Transaction management, isolation levels, deadlock prevention, and lock contention patterns.
 
 ## 6. Data Access Patterns (data)
+
 **Impact:** MEDIUM
 **Description:** N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.
 
 ## 7. Monitoring & Diagnostics (monitor)
+
 **Impact:** LOW-MEDIUM
 **Description:** Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.
 
 ## 8. Advanced Features (advanced)
+
 **Impact:** LOW
 **Description:** Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.
diff --git a/.cursor/skills/supabase/CHANGELOG.md b/.cursor/skills/supabase/CHANGELOG.md
index a62015d35..7d4f1ea1f 100644
--- a/.cursor/skills/supabase/CHANGELOG.md
+++ b/.cursor/skills/supabase/CHANGELOG.md
@@ -2,34 +2,30 @@
 
 ## [0.1.4](https://github.com/supabase/agent-skills/compare/v0.1.3...v0.1.4) (2026-06-05)
 
-
 ### Features
 
-* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
-* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
-* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
+- add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+- add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+- instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
 
 ### Bug Fixes
 
-* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
-* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+- bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
 
 ## [0.1.3](https://github.com/supabase/agent-skills/compare/v0.1.2...v0.1.3) (2026-06-02)
 
-
 ### Features
 
-* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
-* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
-* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
+- add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+- add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+- instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
 
 ### Bug Fixes
 
-* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
-* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+- bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
diff --git a/.cursor/skills/testing-review/SKILL.md b/.cursor/skills/testing-review/SKILL.md
index c72c29671..23d9af423 100644
--- a/.cursor/skills/testing-review/SKILL.md
+++ b/.cursor/skills/testing-review/SKILL.md
@@ -10,10 +10,12 @@ Use this skill when reviewing test coverage, testing harnesses, and test executi
 ## Review Checklist
 
 ### 1. Test Harness Coverage
+
 - **Unit Tests:** Ensure new or modified utils, helper scripts, and backend libraries have corresponding Vitest unit tests (`*.test.ts`).
 - **E2E/UI Tests:** Verify frontend routes and interactive components are covered by Playwright specs (`ui-*.spec.ts`).
 - **Clinical Safety Assertions:** Check that tests verify critical safety boundaries, such as correct citation indexing, fallback behavior on weak RAG evidence, and tenant data isolation.
 
 ### 2. Flakiness & Mocking
+
 - **Mocking External APIs:** Ensure test flows do not hit live external APIs (like OpenAI) directly. Mock these services with predictable fixtures.
 - **Verification Gates:** Confirm the appropriate check level is used (`verify:cheap` for localized code changes, `verify:ui` for Chromium work, `verify:release` for comprehensive releases).
diff --git a/.cursor/skills/ux-review/SKILL.md b/.cursor/skills/ux-review/SKILL.md
index dd25ec116..d4de4dae9 100644
--- a/.cursor/skills/ux-review/SKILL.md
+++ b/.cursor/skills/ux-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing user interface flows, search input behaviors, side
 ## Review Checklist
 
 ### 1. Search Composer Integration
+
 - **Composer Placement:** Verify that the shared composer (`master-search-header.tsx`) matches the correct placement rules (inline in heroes on home views, fixed bottom/sticky top on results, and absent on document viewers).
 - **Navigation:** Check that search queries trigger the correct routing paths (`?q=...&run=1`) and preserve active filters.
 
 ### 2. User Flows & Responsiveness
+
 - **Source-Review Friction:** Ensure the document drawer and PDF previewer load with minimal user interaction and maintain focus.
 - **Mobile Usability:** Verify touch boundaries, drawer slide-up interactions, and layout density on mobile/tablet widths.
diff --git a/scripts/seed-registry-records.ts b/scripts/seed-registry-records.ts
index 5d548b89c..cf8215ccc 100644
--- a/scripts/seed-registry-records.ts
+++ b/scripts/seed-registry-records.ts
@@ -1,7 +1,11 @@
 import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
-import { embedClinicalRegistryRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
+import {
+  embedClinicalRegistryRows,
+  embedReloadedOwnerRows,
+  registryCorpusEmbeddingEnabled,
+} from "@/lib/registry-corpus";
 import type { RegistryRecordRow } from "@/lib/registry-records";
 import { type RegistryRecordKind } from "@/lib/registry-records";
 import { buildDefaultRegistryRows, defaultRegistryRecords } from "@/lib/registry-seed";
diff --git a/src/lib/registry-corpus.ts b/src/lib/registry-corpus.ts
index 854270a1a..f1cce0b82 100644
--- a/src/lib/registry-corpus.ts
+++ b/src/lib/registry-corpus.ts
@@ -282,7 +282,12 @@ export function embedDifferentialRows(supabase: AdminClient, rows: DifferentialR
 
 /** Best-effort corpus embedding for a seed path: failures are logged, not thrown,
  *  so a broken embedding call never blocks the seed write it runs after. */
-export async function bestEffortEmbedRows(args: { scope: string; ownerId: string; detail?: string; embed: () => Promise<unknown> }) {
+export async function bestEffortEmbedRows(args: {
+  scope: string;
+  ownerId: string;
+  detail?: string;
+  embed: () => Promise<unknown>;
+}) {
   if (!registryCorpusEmbeddingEnabled()) return;
   try {
     await args.embed();

From def4753f2b5b13f0f480a54c36f50fdd21c63e3a Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 9 Jul 2026 08:30:43 +0000
Subject: [PATCH 08/16] fix: address PR 433 review comments

- Defer embedding until after text/document fast paths and coverage gate
- Rehydrate cached document metadata in attachDocumentRankingMetadata
- Load env-dependent script imports after loadEnvConfig in seed/reindex scripts
- Harden registry corpus: shared identity, medication tags, rollback, detail hrefs
- Route registry citations to detail pages; handle registry rows in signed-url API
- Prioritize safety warnings over registry info; preserve stale registry labels
- Guard OCR repair against dropping isolated single-letter clinical tokens
- Update skill docs, changelog dedup, CI Supabase setup-cli@v3

Co-authored-by: BigSimmo <BigSimmo@users.noreply.github.com>
---
 .../CHANGELOG.md                              | 10 +--
 .../references/_contributing.md               |  2 +-
 .../references/security-rls-performance.md    |  6 +-
 .github/workflows/ci.yml                      |  2 +-
 scripts/reindex-image-generation-metadata.ts  | 32 ++++++---
 scripts/seed-differential-records.ts          |  4 +-
 scripts/seed-medication-records.ts            |  4 +-
 scripts/seed-registry-records.ts              | 10 +--
 .../api/documents/[id]/signed-url/route.ts    | 33 +++++++++-
 .../clinical-dashboard/source-actions.tsx     | 12 ++++
 src/lib/document-index-units.ts               | 18 +++++
 src/lib/rag.ts                                | 65 ++++++++++---------
 src/lib/registry-corpus.ts                    | 64 ++++++++++++++----
 src/lib/source-governance.ts                  | 27 ++++----
 src/lib/source-metadata.ts                    |  6 +-
 src/lib/universal-search.ts                   | 18 ++++-
 tests/document-index-units.test.ts            | 21 ++++++
 tests/registry-corpus.test.ts                 | 28 +++++++-
 tests/source-governance.test.ts               | 36 ++++++++++
 tests/source-metadata.test.ts                 | 11 ++++
 20 files changed, 320 insertions(+), 89 deletions(-)

diff --git a/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
index e4d7c09be..ceb0a1d7f 100644
--- a/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
+++ b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
@@ -2,15 +2,9 @@
 
 ## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
 
-### Features
-
-- add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
-- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
+### Documentation
 
-### Bug Fixes
-
-- correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
-- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- refresh RLS performance guidance for SECURITY DEFINER helper usage ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
 
 ## [1.2.0](https://github.com/supabase/agent-skills/compare/v1.1.1...v1.2.0) (2026-06-02)
 
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
index 4c3efce95..da5f75fab 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
@@ -163,4 +163,4 @@ Before submitting a reference:
 - [ ] Comments explain _why_, not _what_
 - [ ] Trade-offs mentioned if applicable
 - [ ] Reference links included
-- [ ] `pnpm test` passes
+- [ ] `npm run test` passes
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md b/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
index c3c7c416d..bf3d48873 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
@@ -29,7 +29,7 @@ create policy orders_policy on orders
 
 Use security definer functions for complex checks:
 
-`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` only from roles that should never call the helper directly (for example `PUBLIC` and `anon`). Roles that must satisfy an RLS policy referencing the helper still need `EXECUTE`.
 
 ```sql
 -- Create helper function in a private schema
@@ -46,8 +46,8 @@ as $$
   );
 $$;
 
--- Revoke direct execution from public roles
-revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+-- Revoke direct execution from public/anonymous roles only
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon;
 
 -- Use in policy (indexed lookup, not per-row check)
 create policy team_orders_policy on orders
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 51b3fa4d4..8bddc0fb8 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -151,7 +151,7 @@ jobs:
           persist-credentials: false
 
       - name: Setup Supabase CLI
-        uses: supabase/setup-cli@v1
+        uses: supabase/setup-cli@v3
         with:
           version: latest
 
diff --git a/scripts/reindex-image-generation-metadata.ts b/scripts/reindex-image-generation-metadata.ts
index ced585e07..9ebc8c86c 100644
--- a/scripts/reindex-image-generation-metadata.ts
+++ b/scripts/reindex-image-generation-metadata.ts
@@ -1,10 +1,6 @@
 import { loadEnvConfig } from "@next/env";
 import { confirm } from "./cli-utils";
 import { committedIndexGeneration, metadataRecord } from "@/lib/reindex-pipeline";
-import { assertSupabaseHealthy, probeSupabaseHealth } from "@/lib/supabase/health";
-import { checkSupabaseProjectConfig, formatSupabaseProjectCheck } from "@/lib/supabase/project";
-import { createAdminClient } from "@/lib/supabase/admin";
-import { requireServerEnv } from "@/lib/env";
 
 loadEnvConfig(process.cwd());
 
@@ -42,7 +38,12 @@ type UntypedTable = {
       column: string,
       value: string,
     ): {
-      range(from: number, to: number): Promise<{ data: unknown; error: { message: string } | null }>;
+      order(
+        column: string,
+        options: { ascending: boolean },
+      ): {
+        range(from: number, to: number): Promise<{ data: unknown; error: { message: string } | null }>;
+      };
     };
   };
   update(values: Record<string, unknown>): {
@@ -50,7 +51,12 @@ type UntypedTable = {
   };
 };
 
-function untypedTable(supabase: ReturnType<typeof createAdminClient>, table: string): UntypedTable {
+async function loadAdminClient() {
+  const { createAdminClient } = await import("@/lib/supabase/admin");
+  return createAdminClient();
+}
+
+function untypedTable(supabase: Awaited<ReturnType<typeof loadAdminClient>>, table: string): UntypedTable {
   return supabase.from(table as never) as unknown as UntypedTable;
 }
 
@@ -80,7 +86,9 @@ function parseArgs(argv: string[]): Args {
       continue;
     }
 
-    if (token !== "--document-id" && token !== "--owner-id" && token !== "--limit") continue;
+    if (token !== "--document-id" && token !== "--owner-id" && token !== "--limit") {
+      throw new Error(`Unknown argument: ${token}`);
+    }
 
     const value = argv[index + 1];
     if (!value || value.startsWith("--")) throw new Error(`Missing value for ${token}`);
@@ -105,7 +113,7 @@ function rowNeedsRefresh(row: ImageRow, committedGeneration: string) {
 }
 
 async function loadDocuments(args: {
-  supabase: ReturnType<typeof createAdminClient>;
+  supabase: Awaited<ReturnType<typeof loadAdminClient>>;
   ownerId: string | null;
   documentId: string | null;
   allOwners: boolean;
@@ -128,12 +136,13 @@ async function loadDocuments(args: {
   return (data ?? []) as DocumentRow[];
 }
 
-async function loadImages(args: { supabase: ReturnType<typeof createAdminClient>; documentId: string }) {
+async function loadImages(args: { supabase: Awaited<ReturnType<typeof loadAdminClient>>; documentId: string }) {
   const rows: ImageRow[] = [];
   for (let offset = 0; ; offset += 1000) {
     const { data, error } = await untypedTable(args.supabase, "document_images")
       .select("id,index_generation_id,metadata")
       .eq("document_id", args.documentId)
+      .order("id", { ascending: true })
       .range(offset, offset + 999);
     if (error) throw new Error(error.message);
     const page = (data ?? []) as unknown as ImageRow[];
@@ -144,6 +153,9 @@ async function loadImages(args: { supabase: ReturnType<typeof createAdminClient>
 }
 
 async function main() {
+  const { requireServerEnv } = await import("@/lib/env");
+  const { assertSupabaseHealthy, probeSupabaseHealth } = await import("@/lib/supabase/health");
+  const { checkSupabaseProjectConfig, formatSupabaseProjectCheck } = await import("@/lib/supabase/project");
   const args = parseArgs(process.argv.slice(2));
   requireServerEnv();
 
@@ -162,7 +174,7 @@ async function main() {
     console.log(`Supabase project warning: ${projectCheck.warnings.join(" ; ")}`);
   }
 
-  const supabase = createAdminClient();
+  const supabase = await loadAdminClient();
   console.log(`Target project: ${projectCheck.expected.name} (${projectCheck.expected.ref})`);
   assertSupabaseHealthy(await probeSupabaseHealth(supabase), "Re-stamp document image generation");
 
diff --git a/scripts/seed-differential-records.ts b/scripts/seed-differential-records.ts
index 2120bd5a1..b77e78297 100644
--- a/scripts/seed-differential-records.ts
+++ b/scripts/seed-differential-records.ts
@@ -3,7 +3,6 @@ import { loadEnvConfig } from "@next/env";
 import { confirm } from "./cli-utils";
 import { buildDefaultDifferentialRows, loadDifferentialSnapshot } from "@/lib/differential-fixtures";
 import type { DifferentialRecordRow } from "@/lib/differential-records";
-import { embedDifferentialRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 
 loadEnvConfig(process.cwd());
 
@@ -47,6 +46,9 @@ function parseArgs(argv: string[]): SeedArgs {
 }
 
 async function main() {
+  const { embedDifferentialRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } = await import(
+    "@/lib/registry-corpus"
+  );
   const args = parseArgs(process.argv.slice(2));
   if (!args.ownerId) {
     throw new Error("No owner id. Pass --owner-id <uuid> or set LOCAL_NO_AUTH_OWNER_ID.");
diff --git a/scripts/seed-medication-records.ts b/scripts/seed-medication-records.ts
index 0806ac820..cec0c1339 100644
--- a/scripts/seed-medication-records.ts
+++ b/scripts/seed-medication-records.ts
@@ -2,7 +2,6 @@ import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
 import { buildMedicationSeedRows } from "@/lib/medication-seed";
-import { embedMedicationRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import type { MedicationRecordRow } from "@/lib/medication-records";
 
 loadEnvConfig(process.cwd());
@@ -47,6 +46,9 @@ function parseArgs(argv: string[]): SeedArgs {
 }
 
 async function main() {
+  const { embedMedicationRows, embedReloadedOwnerRows, registryCorpusEmbeddingEnabled } = await import(
+    "@/lib/registry-corpus"
+  );
   const args = parseArgs(process.argv.slice(2));
   if (!args.ownerId) {
     throw new Error("No owner id. Pass --owner-id <uuid> or set LOCAL_NO_AUTH_OWNER_ID.");
diff --git a/scripts/seed-registry-records.ts b/scripts/seed-registry-records.ts
index cf8215ccc..fa0734659 100644
--- a/scripts/seed-registry-records.ts
+++ b/scripts/seed-registry-records.ts
@@ -1,11 +1,6 @@
 import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
-import {
-  embedClinicalRegistryRows,
-  embedReloadedOwnerRows,
-  registryCorpusEmbeddingEnabled,
-} from "@/lib/registry-corpus";
 import type { RegistryRecordRow } from "@/lib/registry-records";
 import { type RegistryRecordKind } from "@/lib/registry-records";
 import { buildDefaultRegistryRows, defaultRegistryRecords } from "@/lib/registry-seed";
@@ -69,6 +64,11 @@ function seedSets(kind: SeedArgs["kind"]): Array<{ kind: RegistryRecordKind; rec
 }
 
 async function main() {
+  const {
+    embedClinicalRegistryRows,
+    embedReloadedOwnerRows,
+    registryCorpusEmbeddingEnabled,
+  } = await import("@/lib/registry-corpus");
   const args = parseArgs(process.argv.slice(2));
   if (!args.ownerId) {
     throw new Error("No owner id. Pass --owner-id <uuid> or set LOCAL_NO_AUTH_OWNER_ID.");
diff --git a/src/app/api/documents/[id]/signed-url/route.ts b/src/app/api/documents/[id]/signed-url/route.ts
index 7ecb96f47..89ff33243 100644
--- a/src/app/api/documents/[id]/signed-url/route.ts
+++ b/src/app/api/documents/[id]/signed-url/route.ts
@@ -5,6 +5,8 @@ import { getDemoDocument } from "@/lib/demo-data";
 import { env } from "@/lib/env";
 import { isDemoMode } from "@/lib/env";
 import { jsonError, PublicApiError } from "@/lib/http";
+import { registryCorpusDetailHref } from "@/lib/registry-corpus";
+import { normalizeSourceMetadata } from "@/lib/source-metadata";
 import { createAdminClient } from "@/lib/supabase/admin";
 import { AuthenticationError, unauthorizedResponse } from "@/lib/supabase/auth";
 import { enforceDocumentReadRateLimit, withOwnerReadScope } from "@/lib/public-api-access";
@@ -38,13 +40,42 @@ export async function GET(_request: Request, { params }: { params: Promise<{ id:
       return rateLimitJsonResponse("Document requests are rate limited. Try again shortly.", rateLimit);
     }
     const { data: document, error } = await withOwnerReadScope(
-      supabase.from("documents").select("storage_path,file_type").eq("id", id),
+      supabase.from("documents").select("storage_path,file_type,metadata").eq("id", id),
       access.ownerId,
     ).maybeSingle();
 
     if (error) throw new Error(error.message);
     if (!document) return NextResponse.json({ error: "Document not found." }, { status: 404 });
 
+    const metadata =
+      document.metadata && typeof document.metadata === "object"
+        ? (document.metadata as Record<string, unknown>)
+        : {};
+    const source = normalizeSourceMetadata(metadata);
+    const registryHref =
+      (typeof metadata.registry_detail_href === "string" && metadata.registry_detail_href) ||
+      registryCorpusDetailHref({
+        kind: metadata.registry_record_kind,
+        slug: metadata.registry_record_slug,
+        subkind: metadata.registry_record_subkind,
+        recordId: metadata.registry_record_id,
+      });
+    if (source.source_kind === "registry_record" && registryHref) {
+      return NextResponse.json({
+        url: registryHref,
+        fileType: document.file_type,
+        registrySource: true,
+        expiresAt: null,
+      });
+    }
+
+    if (document.storage_path.startsWith("registry://")) {
+      return NextResponse.json(
+        { error: "Registry summaries open on their registry detail page, not as stored documents." },
+        { status: 409 },
+      );
+    }
+
     const storage = supabase.storage.from(env.SUPABASE_DOCUMENT_BUCKET);
     const signed = shouldDownload
       ? await storage.createSignedUrl(document.storage_path, signedUrlTtlSeconds, { download: true })
diff --git a/src/components/clinical-dashboard/source-actions.tsx b/src/components/clinical-dashboard/source-actions.tsx
index ef374e88d..9b3a79059 100644
--- a/src/components/clinical-dashboard/source-actions.tsx
+++ b/src/components/clinical-dashboard/source-actions.tsx
@@ -3,6 +3,7 @@
 import Link from "next/link";
 import { ExternalLink, FileText, Filter, Search } from "lucide-react";
 import { cn, floatingControl, metadataPill, primaryControl } from "@/components/ui-primitives";
+import { registryCorpusDetailHref } from "@/lib/registry-corpus";
 import type { CrossModeLink } from "@/lib/cross-mode-links";
 import type { SearchResult } from "@/lib/types";
 
@@ -61,6 +62,17 @@ export function SourceActionRow({
 }
 
 export function sourceResultHref(source: SearchResult) {
+  const metadata =
+    source.source_metadata && typeof source.source_metadata === "object"
+      ? (source.source_metadata as Record<string, unknown>)
+      : {};
+  const registryHref = registryCorpusDetailHref({
+    kind: metadata.registry_record_kind,
+    slug: metadata.registry_record_slug,
+    subkind: metadata.registry_record_subkind,
+    recordId: metadata.registry_record_id,
+  });
+  if (registryHref) return registryHref;
   return `/documents/${source.document_id}?page=${source.page_number ?? 1}&chunk=${source.id}`;
 }
 
diff --git a/src/lib/document-index-units.ts b/src/lib/document-index-units.ts
index e669dfc19..f44a2c166 100644
--- a/src/lib/document-index-units.ts
+++ b/src/lib/document-index-units.ts
@@ -144,6 +144,23 @@ function bestOcrRepair(fragment: string, dictionary: string[]) {
   return best?.word ?? null;
 }
 
+function dropsIsolatedSingleLetterToken(fragment: string, repair: string) {
+  const tokens = fragment.match(/\b[A-Za-z]+\b/g) ?? [];
+  const repairLower = repair.toLowerCase();
+  for (const token of tokens) {
+    if (token.length !== 1) continue;
+    const letterPattern = new RegExp(`\\b${token}\\b`, "i");
+    if (!letterPattern.test(fragment) || letterPattern.test(repairLower)) continue;
+    const remainingTokens = fragment
+      .replace(letterPattern, "")
+      .match(/\b[A-Za-z]+\b/g)
+      ?.filter((remaining) => remaining.length > 0);
+    if (!remainingTokens?.length) continue;
+    if (remainingTokens.every((remaining) => new RegExp(`\\b${remaining}\\b`, "i").test(repairLower))) return true;
+  }
+  return false;
+}
+
 export function repairOcrDropoutAgainstReference(text: string, reference: string) {
   const dictionary = referenceDictionary(reference);
   if (dictionary.length === 0) return { text, replacements: [] as Array<{ from: string; to: string }> };
@@ -162,6 +179,7 @@ export function repairOcrDropoutAgainstReference(text: string, reference: string
       if (!/^[A-Za-z]+(?:\s+[A-Za-z]+)+$/.test(fragment)) continue;
       const repair = bestOcrRepair(fragment, dictionary);
       if (!repair || repair === fragment.toLowerCase()) continue;
+      if (dropsIsolatedSingleLetterToken(fragment, repair)) continue;
       const currentFragment = repaired.slice(start, end);
       if (currentFragment !== fragment) continue;
       repaired = `${repaired.slice(0, start)}${repair}${repaired.slice(end)}`;
diff --git a/src/lib/rag.ts b/src/lib/rag.ts
index 11c45fe9f..e01bfd5f2 100644
--- a/src/lib/rag.ts
+++ b/src/lib/rag.ts
@@ -2364,7 +2364,24 @@ async function attachDocumentRankingMetadata(
           (result.document_summary === undefined || result.document_summary === null),
       ),
   );
-  if (missingDocumentIds.length === 0) return attachIndexQualityMetadata(supabase, results, ownerId, cache);
+  if (missingDocumentIds.length === 0) {
+    const enriched = results.map((result) => {
+      const metadata = cache.documentMetadata.get(result.document_id);
+      if (!metadata) return result;
+      if (
+        (result.document_labels !== undefined && result.document_labels.length > 0) ||
+        (result.document_summary !== undefined && result.document_summary !== null)
+      ) {
+        return result;
+      }
+      return {
+        ...result,
+        document_labels: metadata.labels,
+        document_summary: metadata.summary,
+      };
+    });
+    return attachIndexQualityMetadata(supabase, enriched, ownerId, cache);
+  }
 
   try {
     const metadataRows = await fetchRelatedDocumentMetadata({
@@ -3242,13 +3259,6 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
   const maxResultsPerDocument = queryClassification.queryClass === "comparison" ? 2 : 4;
   const minSimilarity = args.minSimilarity ?? 0.15;
   let embeddingStartedAt = 0;
-  const preloadedEmbedding =
-    !sourceOnlyRetrieval && !args.lexicalOnly
-      ? (() => {
-          embeddingStartedAt = Date.now();
-          return Promise.resolve(embedTextWithTelemetry(expandedQuery)).catch(() => null);
-        })()
-      : null;
 
   let textFastResults: SearchResult[] = [];
   const textRpcStartedAt = Date.now();
@@ -3278,9 +3288,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
       args.ownerId,
       documentRankingMetadataCache,
     );
-    if (!preloadedEmbedding) {
-      expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, textCandidates);
-    }
+    expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, textCandidates);
     const baseTextResults = selectRankedRetrievalResults({
       query: retrievalQuery,
       queryClass: queryClassification.queryClass,
@@ -3401,9 +3409,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
         args.ownerId,
         documentRankingMetadataCache,
       );
-      if (!preloadedEmbedding) {
-        expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, documentLookupCandidates);
-      }
+      expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, documentLookupCandidates);
       const memoryBoost = await withMemoryBoostedCandidates({
         supabase,
         query: args.query,
@@ -3499,23 +3505,20 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
   }
 
   throwIfAborted(args.signal);
-  if (!embeddingStartedAt) embeddingStartedAt = Date.now();
-  let embeddingResult = await preloadedEmbedding;
-  if (!embeddingResult) {
-    embeddingStartedAt = Date.now();
-    try {
-      embeddingResult = await embedTextWithTelemetry(expandedQuery);
-    } catch (error) {
-      // In auto mode a failed embedding call (e.g. quota exhausted) degrades to the lexical
-      // results already gathered rather than failing the whole search. "openai" mode rethrows.
-      if (args.forceEmbedding || !allowsAutoDegrade()) throw error;
-      telemetry.embedding_skipped = true;
-      telemetry.embedding_skip_reason = sourceOnlyReason(error);
-      telemetry.vector_skipped_reason = classifyProviderFailure(error);
-      telemetry.retrieval_strategy = telemetry.retrieval_strategy ?? "text_fast_path";
-      recordSearchScoreTelemetry(telemetry, textFastResults);
-      return { results: textFastResults, telemetry };
-    }
+  embeddingStartedAt = Date.now();
+  let embeddingResult: Awaited<ReturnType<typeof embedTextWithTelemetry>> | null = null;
+  try {
+    embeddingResult = await embedTextWithTelemetry(expandedQuery);
+  } catch (error) {
+    // In auto mode a failed embedding call (e.g. quota exhausted) degrades to the lexical
+    // results already gathered rather than failing the whole search. "openai" mode rethrows.
+    if (args.forceEmbedding || !allowsAutoDegrade()) throw error;
+    telemetry.embedding_skipped = true;
+    telemetry.embedding_skip_reason = sourceOnlyReason(error);
+    telemetry.vector_skipped_reason = classifyProviderFailure(error);
+    telemetry.retrieval_strategy = telemetry.retrieval_strategy ?? "text_fast_path";
+    recordSearchScoreTelemetry(telemetry, textFastResults);
+    return { results: textFastResults, telemetry };
   }
   const { embedding, cacheHit } = embeddingResult;
   telemetry.embedding_latency_ms = Date.now() - embeddingStartedAt;
diff --git a/src/lib/registry-corpus.ts b/src/lib/registry-corpus.ts
index f1cce0b82..23898bf27 100644
--- a/src/lib/registry-corpus.ts
+++ b/src/lib/registry-corpus.ts
@@ -58,12 +58,6 @@ function compactText(parts: unknown[], limit = 8000) {
   return text.length <= limit ? text : `${text.slice(0, limit - 3).trim()}...`;
 }
 
-function stringArray(value: unknown) {
-  return Array.isArray(value)
-    ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
-    : [];
-}
-
 function registryBaseMetadata(entry: RegistryCorpusEntry): Record<string, Json> {
   return {
     source_kind: "registry_record",
@@ -88,9 +82,45 @@ function registryEntryMetadata(entry: RegistryCorpusEntry): Record<string, Json>
   return { ...registryBaseMetadata(entry), ...entry.metadata };
 }
 
+function registryCorpusIdentity(entry: RegistryCorpusEntry) {
+  return {
+    documentId: registryDocumentId(entry),
+    metadata: registryEntryMetadata(entry),
+  };
+}
+
+export function registryCorpusDetailHref(args: {
+  kind: unknown;
+  slug: unknown;
+  subkind?: unknown;
+  recordId?: unknown;
+}) {
+  const kind = typeof args.kind === "string" ? args.kind : null;
+  const slug = typeof args.slug === "string" ? args.slug : null;
+  const subkind = typeof args.subkind === "string" ? args.subkind : null;
+  const recordId = typeof args.recordId === "string" ? args.recordId : null;
+  if (!kind || !slug) return null;
+  if (kind === "service") return `/services/${slug}`;
+  if (kind === "form") return `/forms/${slug}`;
+  if (kind === "medication") return `/medications/${slug}`;
+  if (kind === "differential") {
+    return subkind === "presentation" && recordId
+      ? `/differentials/presentations/${recordId}`
+      : `/differentials/diagnoses/${slug}`;
+  }
+  return null;
+}
+
 function registryDocumentRow(entry: RegistryCorpusEntry): TablesInsert<"documents"> {
+  const { documentId, metadata } = registryCorpusIdentity(entry);
+  const detailHref = registryCorpusDetailHref({
+    kind: entry.kind,
+    slug: entry.slug,
+    subkind: entry.subkind,
+    recordId: entry.recordId,
+  });
   return {
-    id: registryDocumentId(entry),
+    id: documentId,
     owner_id: entry.ownerId,
     title: entry.title,
     description: entry.subtitle,
@@ -104,14 +134,18 @@ function registryDocumentRow(entry: RegistryCorpusEntry): TablesInsert<"document
     chunk_count: 1,
     image_count: 0,
     content_hash: sha256(entry.content),
-    metadata: registryEntryMetadata(entry),
+    metadata: {
+      ...metadata,
+      registry_detail_href: detailHref,
+    },
   };
 }
 
 function registryChunkRow(entry: RegistryCorpusEntry, embedding: Vector): TablesInsert<"document_chunks"> {
+  const { documentId, metadata } = registryCorpusIdentity(entry);
   return {
     id: deterministicUuid(`registry-chunk:${entry.kind}:${entry.recordId}`),
-    document_id: registryDocumentId(entry),
+    document_id: documentId,
     chunk_index: 0,
     page_number: 1,
     section_heading: "Registry summary",
@@ -122,7 +156,7 @@ function registryChunkRow(entry: RegistryCorpusEntry, embedding: Vector): Tables
     image_ids: [],
     content_hash: sha256(entry.content),
     embedding,
-    metadata: registryEntryMetadata(entry),
+    metadata,
   };
 }
 
@@ -211,7 +245,7 @@ export function medicationRowsToCorpusEntries(rows: MedicationRecordRow[]): Regi
       metadata: {
         medication_class: row.class,
         medication_subclass: row.subclass,
-        tags: stringArray(row.tag),
+        tags: row.tag ? [row.tag] : [],
       },
     };
   });
@@ -258,12 +292,18 @@ export async function embedRegistryCorpusEntries(supabase: AdminClient, entries:
   const embeddings = await embedTexts(entries.map((entry) => entry.content));
   const documents = entries.map(registryDocumentRow);
   const chunks = entries.map((entry, index) => registryChunkRow(entry, embeddings[index] as Vector));
+  const documentIds = documents.map((document) => document.id).filter((id): id is string => Boolean(id));
 
   const { error: documentError } = await supabase.from("documents").upsert(documents, { onConflict: "id" });
   if (documentError) throw new Error(`Registry corpus document upsert failed: ${documentError.message}`);
 
   const { error: chunkError } = await supabase.from("document_chunks").upsert(chunks, { onConflict: "id" });
-  if (chunkError) throw new Error(`Registry corpus chunk upsert failed: ${chunkError.message}`);
+  if (chunkError) {
+    if (documentIds.length > 0) {
+      await supabase.from("documents").delete().in("id", documentIds);
+    }
+    throw new Error(`Registry corpus chunk upsert failed: ${chunkError.message}`);
+  }
 
   return { documentCount: documents.length, chunkCount: chunks.length };
 }
diff --git a/src/lib/source-governance.ts b/src/lib/source-governance.ts
index d701fa569..d55156240 100644
--- a/src/lib/source-governance.ts
+++ b/src/lib/source-governance.ts
@@ -94,17 +94,6 @@ export function sourceGovernanceWarnings(args: {
     const title = result.title;
     const document_id = result.document_id;
 
-    if (source.source_kind === "registry_record") {
-      pushUnique(warnings, {
-        code: "registry_record_source",
-        severity: "info",
-        message:
-          "One or more supporting sources are curated registry summaries, not source documents; verify against linked source documents for clinical decisions.",
-        document_id,
-        title,
-      });
-    }
-
     if (source.document_status === "outdated") {
       pushUnique(warnings, {
         code: "outdated_source",
@@ -185,9 +174,23 @@ export function sourceGovernanceWarnings(args: {
         title,
       });
     }
+
+    if (source.source_kind === "registry_record") {
+      pushUnique(warnings, {
+        code: "registry_record_source",
+        severity: "info",
+        message:
+          "One or more supporting sources are curated registry summaries, not source documents; verify against linked source documents for clinical decisions.",
+        document_id,
+        title,
+      });
+    }
   }
 
-  return warnings.slice(0, args.limit ?? 8);
+  const severityRank = { danger: 0, warning: 1, info: 2 } satisfies Record<SourceGovernanceWarning["severity"], number>;
+  return warnings
+    .sort((left, right) => severityRank[left.severity] - severityRank[right.severity])
+    .slice(0, args.limit ?? 8);
 }
 
 function plural(count: number, singular: string, pluralValue = `${singular}s`) {
diff --git a/src/lib/source-metadata.ts b/src/lib/source-metadata.ts
index 4ede237a6..6ddcc1265 100644
--- a/src/lib/source-metadata.ts
+++ b/src/lib/source-metadata.ts
@@ -45,8 +45,12 @@ export function formatClinicalDate(value: string | null | undefined) {
 }
 
 export function sourceStatusLabel(metadata?: ClinicalSourceMetadata | null) {
-  if (metadata?.source_kind === "registry_record") return "Registry summary";
   const status = metadata?.document_status ?? "unknown";
+  if (metadata?.source_kind === "registry_record") {
+    if (status === "review_due") return "Registry summary · Review due";
+    if (status === "outdated") return "Registry summary · Outdated source";
+    return "Registry summary";
+  }
   if (status === "current") return "Current source";
   if (status === "review_due") return "Review due";
   if (status === "outdated") return "Outdated source";
diff --git a/src/lib/universal-search.ts b/src/lib/universal-search.ts
index 4512e4e57..a87cd050c 100644
--- a/src/lib/universal-search.ts
+++ b/src/lib/universal-search.ts
@@ -9,6 +9,7 @@ import { rowToMedicationRecord } from "@/lib/medication-records";
 import { defaultMedicationRecords, fetchOwnerMedicationRowsWithSeed } from "@/lib/medication-seed";
 import { medicationIndication, rankMedicationRecords, type MedicationRecord } from "@/lib/medications";
 import { searchChunksWithTelemetry } from "@/lib/rag";
+import { registryCorpusDetailHref } from "@/lib/registry-corpus";
 import { rowToServiceRecord } from "@/lib/registry-records";
 import { fetchOwnerRegistryRowsWithSeed } from "@/lib/registry-seed";
 import { rankServiceRecords, serviceRecords, type ServiceRecord } from "@/lib/services";
@@ -226,6 +227,21 @@ async function searchToolsDomain(args: ResolvedSearchArgs): Promise<UniversalSea
   }));
 }
 
+function searchResultDocumentHref(result: SearchResult) {
+  const metadata =
+    result.source_metadata && typeof result.source_metadata === "object"
+      ? (result.source_metadata as Record<string, unknown>)
+      : {};
+  const registryHref = registryCorpusDetailHref({
+    kind: metadata.registry_record_kind,
+    slug: metadata.registry_record_slug,
+    subkind: metadata.registry_record_subkind,
+    recordId: metadata.registry_record_id,
+  });
+  if (registryHref) return registryHref;
+  return `/documents/${result.document_id}`;
+}
+
 function documentItemsFromChunks(results: SearchResult[], limit: number): UniversalSearchItem[] {
   const byDocument = new Map<string, UniversalSearchItem>();
   for (const result of results) {
@@ -240,7 +256,7 @@ function documentItemsFromChunks(results: SearchResult[], limit: number): Univer
       kind: "documents",
       title: result.title,
       subtitle: result.section_heading ?? undefined,
-      href: `/documents/${result.document_id}`,
+      href: searchResultDocumentHref(result),
       score,
       meta: result.file_name,
     });
diff --git a/tests/document-index-units.test.ts b/tests/document-index-units.test.ts
index facd25a00..83ca666c3 100644
--- a/tests/document-index-units.test.ts
+++ b/tests/document-index-units.test.ts
@@ -3,6 +3,7 @@ import {
   buildDocumentIndexUnitInputs,
   countDocumentIndexUnitsByType,
   documentIntelligenceVersion,
+  repairOcrDropoutAgainstReference,
 } from "../src/lib/document-index-units";
 
 const document = {
@@ -278,4 +279,24 @@ describe("document index units", () => {
       expect.arrayContaining([expect.objectContaining({ from: "p ycho ocial", to: "psychosocial" })]),
     );
   });
+
+  it("does not drop isolated single-letter clinical tokens during OCR repair", () => {
+    const { text, replacements } = repairOcrDropoutAgainstReference(
+      "vitamin D deficiency may require supplementation",
+      "vitamin D deficiency monitoring protocol",
+    );
+
+    expect(text).toContain("vitamin D");
+    expect(replacements).toEqual([]);
+  });
+
+  it("still repairs whitespace-fragmented OCR words against the source chunk", () => {
+    const { text, replacements } = repairOcrDropoutAgainstReference(
+      "p ycho ocial",
+      "Psychosocial interventions should be documented before discharge.",
+    );
+
+    expect(text).toContain("psychosocial");
+    expect(replacements).toEqual([expect.objectContaining({ from: "p ycho ocial", to: "psychosocial" })]);
+  });
 });
diff --git a/tests/registry-corpus.test.ts b/tests/registry-corpus.test.ts
index c78bf3986..2491a4956 100644
--- a/tests/registry-corpus.test.ts
+++ b/tests/registry-corpus.test.ts
@@ -1,6 +1,8 @@
 import { describe, expect, it } from "vitest";
 
-import { clinicalRegistryRowsToCorpusEntries } from "../src/lib/registry-corpus";
+import { buildDefaultMedicationRows } from "../src/lib/medication-fixtures";
+import { clinicalRegistryRowsToCorpusEntries, medicationRowsToCorpusEntries, registryCorpusDetailHref } from "../src/lib/registry-corpus";
+import type { MedicationRecordRow } from "../src/lib/medication-records";
 import type { RegistryRecordRow } from "../src/lib/registry-records";
 
 function registryRow(overrides: Partial<RegistryRecordRow> = {}): RegistryRecordRow {
@@ -67,4 +69,28 @@ describe("registry corpus", () => {
     expect(entry).toMatchObject({ kind: "form", subkind: "form", slug: "transport-order" });
     expect(entry?.content).toContain("Form: Transport order");
   });
+
+  it("maps scalar medication tags into metadata.tags", () => {
+    const rows = buildDefaultMedicationRows("22222222-2222-4222-8222-222222222222") as MedicationRecordRow[];
+    const [entry] = medicationRowsToCorpusEntries(rows.map((row) => ({ ...row, tag: "alcohol" })));
+
+    expect(entry?.metadata.tags).toEqual(["alcohol"]);
+  });
+
+  it("builds registry detail hrefs for embedded corpus rows", () => {
+    expect(
+      registryCorpusDetailHref({
+        kind: "service",
+        slug: "crisis-service",
+      }),
+    ).toBe("/services/crisis-service");
+    expect(
+      registryCorpusDetailHref({
+        kind: "differential",
+        slug: "psychosis",
+        subkind: "presentation",
+        recordId: "44444444-4444-4444-8444-444444444444",
+      }),
+    ).toBe("/differentials/presentations/44444444-4444-4444-8444-444444444444");
+  });
 });
diff --git a/tests/source-governance.test.ts b/tests/source-governance.test.ts
index a56ebdd0d..e49c74d9f 100644
--- a/tests/source-governance.test.ts
+++ b/tests/source-governance.test.ts
@@ -288,6 +288,42 @@ describe("source governance warnings", () => {
     expect(groupSourceGovernanceWarnings(warnings)[0]?.message).toBe("1 registry summary used as supporting evidence.");
   });
 
+  it("prioritizes safety warnings over registry info when truncating", () => {
+    const warnings = sourceGovernanceWarnings({
+      limit: 1,
+      results: [
+        result({
+          source_metadata: {
+            source_kind: "registry_record",
+            source_title: "Registry summary",
+            publisher: "Clinical KB registry",
+            jurisdiction: "WA/local clinical workspace",
+            version: null,
+            publication_date: null,
+            review_date: null,
+            uploaded_at: null,
+            indexed_at: null,
+            uploaded_by: null,
+            document_status: "current",
+            clinical_validation_status: "locally_reviewed",
+            extraction_quality: "good",
+          },
+          indexing_quality: {
+            document_id: "doc-1",
+            quality_score: 0.9,
+            extraction_quality: "good",
+            metrics: {},
+            issues: [],
+          },
+          table_facts: [],
+        }),
+        result(),
+      ],
+    });
+
+    expect(warnings).toEqual([expect.objectContaining({ code: "outdated_source", severity: "danger" })]);
+  });
+
   it("keeps the refusal message free of backend and source-backed wording", () => {
     expect(sourceGovernanceRefusalAnswer).not.toMatch(/source-backed|source-governance|admin|need review/i);
     expect(sourceGovernanceRefusalAnswer).toContain("matched documents are not suitable for clinical use yet");
diff --git a/tests/source-metadata.test.ts b/tests/source-metadata.test.ts
index 06eef7a5e..b935c54ec 100644
--- a/tests/source-metadata.test.ts
+++ b/tests/source-metadata.test.ts
@@ -23,6 +23,17 @@ describe("source metadata helpers", () => {
     expect(formatClinicalDate("2026-05-18T10:00:00.000+08:00")).toBe("18/05/2026");
   });
 
+  it("preserves stale status labels for registry summaries", () => {
+    expect(
+      sourceStatusLabel(
+        normalizeSourceMetadata({
+          source_kind: "registry_record",
+          document_status: "outdated",
+        }),
+      ),
+    ).toBe("Registry summary · Outdated source");
+  });
+
   it("includes source status in copied provenance lines", () => {
     const line = clipboardProvenanceLine(
       normalizeSourceMetadata({

From 255ca676868b5cfa4a6aef54f462ce7ae5ab9bbb Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 9 Jul 2026 08:32:40 +0000
Subject: [PATCH 09/16] fix: address follow-up PR 433 review comments

- Backfill NULL document_images.index_generation_id during re-stamp
- Count globally forced embedding eval cases in retrieval summaries

Co-authored-by: BigSimmo <BigSimmo@users.noreply.github.com>
---
 scripts/eval-retrieval.ts                    |  7 +++--
 scripts/reindex-image-generation-metadata.ts |  3 ++-
 tests/eval-retrieval.test.ts                 | 28 ++++++++++++++++++++
 3 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/scripts/eval-retrieval.ts b/scripts/eval-retrieval.ts
index c3a789a0d..a73ec94d5 100644
--- a/scripts/eval-retrieval.ts
+++ b/scripts/eval-retrieval.ts
@@ -504,7 +504,9 @@ export function evaluateGoldenRetrievalCase(args: {
   latencyMs: number;
   timedOut?: boolean;
   latencyFailures?: string[];
+  globalForceEmbedding?: boolean;
 }): GoldenRetrievalResult {
+  const forceEmbedding = Boolean(args.testCase.forceEmbedding || args.globalForceEmbedding);
   const documentHits = expectedDocumentHits(args.testCase.expectedDocumentSubstrings, args.results, 5);
   const contentHits = expectedContentHits(args.testCase.expectedContentTerms, args.results, 5);
   const topK = args.testCase.topK;
@@ -544,7 +546,7 @@ export function evaluateGoldenRetrievalCase(args: {
   if (args.testCase.expectTableEvidence && !tableEvidenceFound) {
     failures.push("expected table evidence in top 5");
   }
-  if (args.testCase.forceEmbedding) {
+  if (forceEmbedding) {
     if (args.telemetry.embedding_skipped) failures.push("forceEmbedding expected embedding to run");
     if (args.telemetry.retrieval_strategy === "search_cache") failures.push("forceEmbedding served search cache");
     if (
@@ -560,7 +562,7 @@ export function evaluateGoldenRetrievalCase(args: {
   return {
     id: args.testCase.id,
     query: args.testCase.query,
-    forceEmbedding: args.testCase.forceEmbedding ?? false,
+    forceEmbedding,
     expectedQueryClass: args.testCase.expectedQueryClass,
     actualQueryClass,
     expectedDocumentSubstrings: args.testCase.expectedDocumentSubstrings,
@@ -876,6 +878,7 @@ async function main() {
       latencyMs,
       timedOut: searchOutcome.timedOut,
       latencyFailures,
+      globalForceEmbedding: args.forceEmbedding,
     });
     results.push(result);
 
diff --git a/scripts/reindex-image-generation-metadata.ts b/scripts/reindex-image-generation-metadata.ts
index 9ebc8c86c..c3d8a3dd1 100644
--- a/scripts/reindex-image-generation-metadata.ts
+++ b/scripts/reindex-image-generation-metadata.ts
@@ -108,7 +108,8 @@ function parseArgs(argv: string[]): Args {
 }
 
 function rowNeedsRefresh(row: ImageRow, committedGeneration: string) {
-  if (row.index_generation_id !== null && row.index_generation_id !== committedGeneration) return true;
+  if (row.index_generation_id === null) return true;
+  if (row.index_generation_id !== committedGeneration) return true;
   return committedIndexGeneration(row.metadata) !== committedGeneration;
 }
 
diff --git a/tests/eval-retrieval.test.ts b/tests/eval-retrieval.test.ts
index 9cb6f73d8..efdc312e1 100644
--- a/tests/eval-retrieval.test.ts
+++ b/tests/eval-retrieval.test.ts
@@ -286,6 +286,34 @@ describe("golden retrieval eval helpers", () => {
     ).toBe("table_threshold");
   });
 
+  it("marks globally forced embedding cases for vector-layer failure checks", () => {
+    const evaluated = evaluateGoldenRetrievalCase({
+      testCase: {
+        id: "case-1",
+        query: "What ANC threshold should withhold clozapine?",
+        expectedQueryClass: "table_threshold",
+        expectedDocumentSubstrings: ["ClozapinePresAdminMonitor"],
+        expectedContentTerms: ["anc"],
+        topK: 8,
+        expectTableEvidence: false,
+      },
+      results: [result({ content: "ANC below 1.5 requires withholding clozapine." })],
+      telemetry: {
+        query_class: "table_threshold",
+        retrieval_strategy: "text_fast_path",
+        embedding_skipped: true,
+        retrieval_layer_counts: {},
+      },
+      latencyMs: 50,
+      globalForceEmbedding: true,
+    });
+
+    expect(evaluated.forceEmbedding).toBe(true);
+    expect(evaluated.failures).toEqual(
+      expect.arrayContaining(["forceEmbedding expected embedding to run", "forceEmbedding found no vector-layer candidates"]),
+    );
+  });
+
   it("converts captured RAG eval cases into golden retrieval cases", () => {
     expect(
       capturedRagCaseToGoldenCase({

From e811cc12e16ad3bf814a7a3ac573a7a308e64aee Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 16:33:40 +0800
Subject: [PATCH 10/16] fix: address PR 433 review blockers

---
 .cursor/skills/accessibility-review/SKILL.md  |  2 +
 .../skills/ai-architecture-review/SKILL.md    |  3 +
 .cursor/skills/api-review/SKILL.md            |  4 +
 .cursor/skills/code-quality-review/SKILL.md   |  2 +
 .cursor/skills/design-review/SKILL.md         |  2 +
 .../frontend-architecture-review/SKILL.md     |  2 +
 .cursor/skills/performance-review/SKILL.md    |  2 +
 .../skills/release-readiness-review/SKILL.md  |  2 +
 .cursor/skills/repo-auditor/SKILL.md          |  1 +
 .cursor/skills/security-review/SKILL.md       |  2 +
 .../CHANGELOG.md                              | 22 ++----
 .../supabase-postgres-best-practices/SKILL.md | 22 +++---
 .../references/_contributing.md               | 28 +++----
 .../references/_sections.md                   |  8 ++
 .../references/security-rls-performance.md    |  8 +-
 .cursor/skills/supabase/CHANGELOG.md          | 32 ++++----
 .cursor/skills/testing-review/SKILL.md        |  2 +
 .cursor/skills/ux-review/SKILL.md             |  2 +
 .github/workflows/ci.yml                      | 25 ++++++-
 deno.lock                                     | 14 ++--
 scripts/reindex-image-generation-metadata.ts  | 57 +++++++++++----
 scripts/seed-differential-records.ts          |  6 +-
 scripts/seed-medication-records.ts            |  6 +-
 scripts/seed-registry-records.ts              |  6 +-
 src/app/api/differentials/[slug]/route.ts     |  2 +
 .../presentations/[slug]/route.ts             |  2 +
 src/app/api/differentials/route.ts            |  2 +
 src/app/api/medications/[slug]/route.ts       |  2 +
 src/app/api/registry/records/[slug]/route.ts  |  2 +
 src/lib/citations.ts                          | 23 ++++++
 src/lib/differential-seed.ts                  |  6 +-
 src/lib/document-index-units.ts               |  9 +++
 src/lib/medication-seed.ts                    |  7 +-
 src/lib/rag.ts                                | 73 ++++++++-----------
 src/lib/registry-corpus.ts                    | 30 ++++++--
 src/lib/registry-seed.ts                      |  7 +-
 src/lib/source-governance.ts                  | 32 +++++---
 src/lib/source-metadata.ts                    | 14 ++--
 src/lib/types.ts                              |  4 +
 ...0_retrieval_owner_matches_fail_closed.sql} |  0
 tests/citations.test.ts                       | 51 +++++++++++++
 tests/document-index-units.test.ts            | 44 +++++++++++
 tests/registry-corpus.test.ts                 | 34 ++++++++-
 tests/source-governance.test.ts               | 61 ++++++++++++++++
 tests/source-metadata.test.ts                 | 12 +++
 45 files changed, 505 insertions(+), 172 deletions(-)
 rename supabase/migrations/{20260708160000_retrieval_owner_matches_fail_closed.sql => 20260708161000_retrieval_owner_matches_fail_closed.sql} (100%)

diff --git a/.cursor/skills/accessibility-review/SKILL.md b/.cursor/skills/accessibility-review/SKILL.md
index 209a598a9..20f697292 100644
--- a/.cursor/skills/accessibility-review/SKILL.md
+++ b/.cursor/skills/accessibility-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing user interfaces to ensure compliance with a11y sta
 ## Review Checklist
 
 ### 1. Keyboard & Focus Control
+
 - **Interactive Elements:** Verify all button-like and link-like components use semantic HTML elements (`<button>`, `<a>`) rather than `div` tags with onClick handlers.
 - **Focus Trapping:** Ensure modal dialogs, side drawers, and search overlays trap keyboard focus properly and support `Esc` key cancellation.
 
 ### 2. ARIA & Reader Markup
+
 - **Labels:** Verify that icon-only buttons, custom inputs, and dynamic charts include appropriate `aria-label` or screen-reader descriptions.
 - **Table Structure:** Ensure data tables (like document table facts) use correct semantic tags (`<thead>`, `<tbody>`, `<th>`) for readable text-to-speech rendering.
diff --git a/.cursor/skills/ai-architecture-review/SKILL.md b/.cursor/skills/ai-architecture-review/SKILL.md
index 2a8f5c44b..74df735d9 100644
--- a/.cursor/skills/ai-architecture-review/SKILL.md
+++ b/.cursor/skills/ai-architecture-review/SKILL.md
@@ -10,14 +10,17 @@ Use this skill when reviewing or modifying the RAG (Retrieval-Augmented Generati
 ## Review Checklist
 
 ### 1. Retrieval Quality & Provenance
+
 - **Hybrid Search:** Confirm queries use proper hybrid search patterns (pgvector + semantic/trigram matching) and respect user/organization boundaries.
 - **Provenance / Citations:** Ensure generated answers are strongly tied to source documents and include clean, traceable citation references.
 - **Fail-Closed Policy:** If no relevant documents are retrieved or verification fails, the system must degrade gracefully or return a clear "No evidence found" response rather than hallucinating.
 
 ### 2. Model Routing & Timeout Logic
+
 - **Routing Rules:** Check that routing between fast and strong models follows defined rules (e.g. `RAG_PROVIDER_MODE`).
 - **Timeouts:** Ensure LLM calls are bounded by client and server-side timeouts (e.g., `OPENAI_ANSWER_TIMEOUT_MS`).
 
 ### 3. Structured Output & Safety
+
 - **Schema Conformity:** Validate that LLM responses use strict schema structures (e.g., OpenAI structured JSON output) to prevent parsing errors.
 - **Safety Filters:** Check that toxicity, safety filters, and prompt injection mitigations are active on user inputs and LLM outputs.
diff --git a/.cursor/skills/api-review/SKILL.md b/.cursor/skills/api-review/SKILL.md
index c491ac380..92c96971d 100644
--- a/.cursor/skills/api-review/SKILL.md
+++ b/.cursor/skills/api-review/SKILL.md
@@ -10,19 +10,23 @@ Use this skill when reviewing or modifying API routes, endpoints, or network bou
 ## Review Checklist
 
 ### 1. Request Validation
+
 - **Zod Schemas:** Ensure all incoming requests (`req.json()`, query parameters, route segments) are validated using strict Zod schemas.
 - **Fail Early:** Requests failing schema validation must return `400 Bad Request` immediately before running downstream DB or AI logic.
 - **Safety check:** Validate input boundaries (e.g., maximum string length, non-empty collections, limit boundaries on pagination).
 
 ### 2. Error Handling & Taxonomy
+
 - **Closed Errors:** Avoid throwing raw database, library, or system errors to the client. Wrap exceptions in consistent JSON error envelopes.
 - **HTTP Semantics:** Use correct HTTP status codes (e.g., `401 Unauthorized` vs `403 Forbidden`, `404 Not Found` for missing resources, `429 Too Many Requests` for rate limits).
 - **Consistency:** Ensure error payloads follow a unified schema, containing a clear error code (e.g., `VALIDATION_FAILED`, `INTERNAL_ERROR`) and user-safe descriptions.
 
 ### 3. Response Contracts
+
 - **Serialization:** Explicitly define the serialized JSON shape of the response. Avoid passing DB model instances directly to the frontend.
 - **Pagination:** For resource listing APIs, verify pagination params (`limit`, `offset` / `cursor`) are implemented, validated, and bounded.
 
 ### 4. Authentication & Authorization
+
 - **Server-Side Enforcement:** Do not rely on client assertions. Re-authenticate user credentials (JWT / session cookies) server-side.
 - **Tenant Isolation:** Ensure fetched resources are filtered by the active user's identity (`user_id`).
diff --git a/.cursor/skills/code-quality-review/SKILL.md b/.cursor/skills/code-quality-review/SKILL.md
index 40567d068..add222b68 100644
--- a/.cursor/skills/code-quality-review/SKILL.md
+++ b/.cursor/skills/code-quality-review/SKILL.md
@@ -10,10 +10,12 @@ Use this skill when auditing source files for maintainability, readability, and
 ## Review Checklist
 
 ### 1. Maintainability & Naming
+
 - **Clean Naming:** Ensure functions, variables, and database keys carry logical, self-describing names.
 - **Decomposition:** Look for bloated files/functions that should be decomposed. Keep modules focused on a single responsibility.
 - **Duplication (DRY):** Consolidate duplicate helper logic, styles, and configurations.
 
 ### 2. Logic & Complexity
+
 - **Control Flow:** Simplify nested conditionals, deeply nested loops, or fragile edge-case handling.
 - **Dead Code:** Remove unused functions, comments, or commented-out code blocks left behind.
diff --git a/.cursor/skills/design-review/SKILL.md b/.cursor/skills/design-review/SKILL.md
index ee1e4636b..e52718181 100644
--- a/.cursor/skills/design-review/SKILL.md
+++ b/.cursor/skills/design-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when auditing UI styling, colors, layout structures, and spacing
 ## Review Checklist
 
 ### 1. Style & Spacing Consistency
+
 - **Design System Tokens:** Ensure custom components utilize predefined design variables (colors, borders, shadows, font sizes) rather than ad-hoc inline styles.
 - **Layout Spacing:** Check for consistent paddings, margins, grid gaps, and alignment.
 
 ### 2. Clinical Theme Adherence
+
 - **Layout Density:** Review components to confirm the visual target is dense, clean, calm, and fast to scan rather than overly flashy or visually expressive.
 - **Browser QA / Screenshot Verification:** For major UI changes, run a local dev server with `npm run ensure` and capture screenshots to verify cross-device visual fidelity.
diff --git a/.cursor/skills/frontend-architecture-review/SKILL.md b/.cursor/skills/frontend-architecture-review/SKILL.md
index 295b74593..626c9bef2 100644
--- a/.cursor/skills/frontend-architecture-review/SKILL.md
+++ b/.cursor/skills/frontend-architecture-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing Next.js App Router structures, component boundarie
 ## Review Checklist
 
 ### 1. Next.js App Router Boundaries
+
 - **RSC vs. Client Components:** Ensure components are Server Components by default. Keep client-side logic (`use state`, `use effect`, browser APIs) isolated to leaf components marked with `"use client"`.
 - **Data Fetching:** Fetch data in Server Components or Server Actions where possible. Avoid calling internal `/api/...` endpoints directly from RSCs.
 
 ### 2. State & Rendering
+
 - **State Duplication:** Avoid replicating URL/router state in local React state. Prefer URLSearchParams and next/navigation controls for search/filters.
 - **Rendering Waste:** Check for unnecessary context re-renders, un-memoized expensive calculations, or excessive component mount/unmount cycles.
diff --git a/.cursor/skills/performance-review/SKILL.md b/.cursor/skills/performance-review/SKILL.md
index c8ae00f46..af66b5fad 100644
--- a/.cursor/skills/performance-review/SKILL.md
+++ b/.cursor/skills/performance-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing query bottlenecks, database RPC latencies, client
 ## Review Checklist
 
 ### 1. Database & API Latency
+
 - **Query Caching:** Verify that repetitive/expensive database fetches and RAG queries leverage caching layers (e.g. `rag_response_cache`).
 - **Index Optimization:** Ensure queries leverage appropriate indices (e.g., trigram/lexical text indexes, vector HNSW).
 
 ### 2. LLM & Asset Loading
+
 - **Token Overhead:** Check that prompt sizes and context window limits are optimized to keep API costs down.
 - **Resource Streaming:** Ensure heavy document rendering, search lists, and PDF asset previews load incrementally or use lazy-loading controls.
diff --git a/.cursor/skills/release-readiness-review/SKILL.md b/.cursor/skills/release-readiness-review/SKILL.md
index 0760f9fa0..eac0fb971 100644
--- a/.cursor/skills/release-readiness-review/SKILL.md
+++ b/.cursor/skills/release-readiness-review/SKILL.md
@@ -10,11 +10,13 @@ Use this skill when preparing a branch for merging, pull request submission, or
 ## Review Checklist
 
 ### 1. Build & Automation Checks
+
 - **Static Analysis:** Confirm `npm run lint` and `npm run typecheck` run clean.
 - **Verification Gates:** Ensure the appropriate verification scripts run successfully (`npm run verify:cheap` at minimum; `npm run verify:release` for full handoffs).
 - **Target database checks:** Run `npm run check:supabase-project` to confirm env targets match `Clinical KB Database` ref `sjrfecxgysukkwxsowpy`.
 
 ### 2. Clinical Governance Compliance
+
 - **Preflight Verification:** Complete all checklist items in `.github/pull_request_template.md`.
 - **Secret Scan:** Confirm no private configuration files (`.env.local`), local debug logs, or keys are present in the git stage.
 - **Production Readiness Check:** Run `npm run check:production-readiness` for privacy, ingestion, or clinical behavior changes.
diff --git a/.cursor/skills/repo-auditor/SKILL.md b/.cursor/skills/repo-auditor/SKILL.md
index 577a06798..2b48c5bde 100644
--- a/.cursor/skills/repo-auditor/SKILL.md
+++ b/.cursor/skills/repo-auditor/SKILL.md
@@ -10,6 +10,7 @@ Use this skill when auditing the workspace layout, folder structures, imports, a
 ## Review Checklist
 
 ### 1. Structural Audits
+
 - **Broken Imports:** Scan modified files for broken relative imports, incorrect library names, or obsolete modules.
 - **Unused Files:** Identify and safely remove files that are truly dead and not part of route mappings, active scripts, migrations, or test resources.
 - **Consolidation:** Check for identical or redundant configuration keys, environment variables, or scripts that can be safely merged.
diff --git a/.cursor/skills/security-review/SKILL.md b/.cursor/skills/security-review/SKILL.md
index d58ce01e6..663195611 100644
--- a/.cursor/skills/security-review/SKILL.md
+++ b/.cursor/skills/security-review/SKILL.md
@@ -10,10 +10,12 @@ Use this skill when reviewing code that touches authentication, database schemas
 ## Review Checklist
 
 ### 1. Key Confinement & Environment Safety
+
 - **Service Role Key:** Ensure the Supabase `service_role` key is never exposed to public clients. Never prefix variables containing secret keys with `NEXT_PUBLIC_`.
 - **Credential Storage:** Verify that credentials are not committed or hardcoded. Look for placeholder usage in `.env.example`.
 
 ### 2. Database & Storage Safety
+
 - **Row-Level Security (RLS):** Ensure RLS is active on all public/exposed tables. Avoid deprecated checkers like `auth.role()` and prefer strict role predicates (`TO authenticated`).
 - **Owner Scope Verification:** Verify that API endpoints filter queries by the authenticated user's ID (`user_id`) to prevent unauthorized cross-tenant data access.
 - **Storage Buckets:** Verify that files uploaded to private buckets (`clinical-documents`, `clinical-images`) require validated user signatures for retrieval.
diff --git a/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
index 94aee4878..191613e94 100644
--- a/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
+++ b/.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md
@@ -2,28 +2,16 @@
 
 ## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
 
-
-### Features
-
-* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
-
-### Bug Fixes
-
-* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+_This vendored archive does not include release-specific entries beyond the 1.2.0 changes below._
 
 ## [1.2.0](https://github.com/supabase/agent-skills/compare/v1.1.1...v1.2.0) (2026-06-02)
 
-
 ### Features
 
-* add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
+- add schema-constraints reference for safe migration patterns ([#30](https://github.com/supabase/agent-skills/issues/30)) ([9b236f3](https://github.com/supabase/agent-skills/commit/9b236f3ebd65d76a2c570f19931353da9c858d5a))
+- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
 
 ### Bug Fixes
 
-* correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- correct broken reference link in postgres best practices skill ([#58](https://github.com/supabase/agent-skills/issues/58)) ([f4e2277](https://github.com/supabase/agent-skills/commit/f4e22777fd8573537297b568c16e5a45a25927da))
+- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
diff --git a/.cursor/skills/supabase-postgres-best-practices/SKILL.md b/.cursor/skills/supabase-postgres-best-practices/SKILL.md
index d9ef1949f..07aa1b3a6 100644
--- a/.cursor/skills/supabase-postgres-best-practices/SKILL.md
+++ b/.cursor/skills/supabase-postgres-best-practices/SKILL.md
@@ -17,6 +17,7 @@ Comprehensive performance optimization guide for Postgres, maintained by Supabas
 ## When to Apply
 
 Reference these guidelines when:
+
 - Writing SQL queries or designing schemas
 - Implementing indexes or query optimization
 - Reviewing database performance issues
@@ -26,16 +27,16 @@ Reference these guidelines when:
 
 ## Rule Categories by Priority
 
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Query Performance | CRITICAL | `query-` |
-| 2 | Connection Management | CRITICAL | `conn-` |
-| 3 | Security & RLS | CRITICAL | `security-` |
-| 4 | Schema Design | HIGH | `schema-` |
-| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
-| 6 | Data Access Patterns | MEDIUM | `data-` |
-| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
-| 8 | Advanced Features | LOW | `advanced-` |
+| Priority | Category                 | Impact      | Prefix      |
+| -------- | ------------------------ | ----------- | ----------- |
+| 1        | Query Performance        | CRITICAL    | `query-`    |
+| 2        | Connection Management    | CRITICAL    | `conn-`     |
+| 3        | Security & RLS           | CRITICAL    | `security-` |
+| 4        | Schema Design            | HIGH        | `schema-`   |
+| 5        | Concurrency & Locking    | MEDIUM-HIGH | `lock-`     |
+| 6        | Data Access Patterns     | MEDIUM      | `data-`     |
+| 7        | Monitoring & Diagnostics | LOW-MEDIUM  | `monitor-`  |
+| 8        | Advanced Features        | LOW         | `advanced-` |
 
 ## How to Use
 
@@ -48,6 +49,7 @@ references/_sections.md
 ```
 
 Each rule file contains:
+
 - Brief explanation of why it matters
 - Incorrect SQL example with explanation
 - Correct SQL example with explanation
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
index 1c055aff9..da5f75fab 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/_contributing.md
@@ -27,7 +27,7 @@ to recognize anti-patterns.
 
 Include specific metrics. Helps agents prioritize fixes.
 
-**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1" 
+**Good:** "10x faster queries", "50% smaller index", "Eliminates N+1"
 **Bad:** "Faster", "Better", "More efficient"
 
 ### 4. Self-Contained Examples
@@ -105,9 +105,7 @@ Most references should focus on pure SQL patterns. This keeps examples portable.
 
 ```typescript
 for (const user of users) {
-  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [
-    user.id,
-  ]);
+  const posts = await db.query("SELECT * FROM posts WHERE user_id = $1", [user.id]);
 }
 ```
 ````
@@ -115,23 +113,21 @@ for (const user of users) {
 **Correct (batch query):**
 
 ```typescript
-const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [
-  userIds,
-]);
+const posts = await db.query("SELECT * FROM posts WHERE user_id = ANY($1)", [userIds]);
 ```
 
 ---
 
 ## Impact Level Guidelines
 
-| Level | Improvement | Use When |
-|-------|-------------|----------|
-| **CRITICAL** | 10-100x | Missing indexes, connection exhaustion, sequential scans on large tables |
-| **HIGH** | 5-20x | Wrong index types, poor partitioning, missing covering indexes |
-| **MEDIUM-HIGH** | 2-5x | N+1 queries, inefficient pagination, RLS optimization |
-| **MEDIUM** | 1.5-3x | Redundant indexes, query plan instability |
-| **LOW-MEDIUM** | 1.2-2x | VACUUM tuning, configuration tweaks |
-| **LOW** | Incremental | Advanced patterns, edge cases |
+| Level           | Improvement | Use When                                                                 |
+| --------------- | ----------- | ------------------------------------------------------------------------ |
+| **CRITICAL**    | 10-100x     | Missing indexes, connection exhaustion, sequential scans on large tables |
+| **HIGH**        | 5-20x       | Wrong index types, poor partitioning, missing covering indexes           |
+| **MEDIUM-HIGH** | 2-5x        | N+1 queries, inefficient pagination, RLS optimization                    |
+| **MEDIUM**      | 1.5-3x      | Redundant indexes, query plan instability                                |
+| **LOW-MEDIUM**  | 1.2-2x      | VACUUM tuning, configuration tweaks                                      |
+| **LOW**         | Incremental | Advanced patterns, edge cases                                            |
 
 ---
 
@@ -167,4 +163,4 @@ Before submitting a reference:
 - [ ] Comments explain _why_, not _what_
 - [ ] Trade-offs mentioned if applicable
 - [ ] Reference links included
-- [ ] `pnpm test` passes
+- [ ] `npm run test` passes
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/_sections.md b/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
index 8ba57c23e..42c16e707 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/_sections.md
@@ -7,33 +7,41 @@ Take the examples below as pure demonstrative. Replace each section with the act
 ---
 
 ## 1. Query Performance (query)
+
 **Impact:** CRITICAL
 **Description:** Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.
 
 ## 2. Connection Management (conn)
+
 **Impact:** CRITICAL
 **Description:** Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.
 
 ## 3. Security & RLS (security)
+
 **Impact:** CRITICAL
 **Description:** Row-Level Security policies, privilege management, and authentication patterns.
 
 ## 4. Schema Design (schema)
+
 **Impact:** HIGH
 **Description:** Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.
 
 ## 5. Concurrency & Locking (lock)
+
 **Impact:** MEDIUM-HIGH
 **Description:** Transaction management, isolation levels, deadlock prevention, and lock contention patterns.
 
 ## 6. Data Access Patterns (data)
+
 **Impact:** MEDIUM
 **Description:** N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.
 
 ## 7. Monitoring & Diagnostics (monitor)
+
 **Impact:** LOW-MEDIUM
 **Description:** Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.
 
 ## 8. Advanced Features (advanced)
+
 **Impact:** LOW
 **Description:** Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.
diff --git a/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md b/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
index c3c7c416d..72b7db4e6 100644
--- a/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
+++ b/.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md
@@ -29,7 +29,7 @@ create policy orders_policy on orders
 
 Use security definer functions for complex checks:
 
-`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and keep `EXECUTE` available only to roles that need to evaluate policies using the helper.
 
 ```sql
 -- Create helper function in a private schema
@@ -46,8 +46,10 @@ as $$
   );
 $$;
 
--- Revoke direct execution from public roles
-revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+-- Keep EXECUTE for roles that must evaluate team_orders_policy.
+-- Revoke only from roles that will never use that policy path.
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, service_role;
+grant execute on function private.is_team_member(bigint) to authenticated;
 
 -- Use in policy (indexed lookup, not per-row check)
 create policy team_orders_policy on orders
diff --git a/.cursor/skills/supabase/CHANGELOG.md b/.cursor/skills/supabase/CHANGELOG.md
index a62015d35..7d4f1ea1f 100644
--- a/.cursor/skills/supabase/CHANGELOG.md
+++ b/.cursor/skills/supabase/CHANGELOG.md
@@ -2,34 +2,30 @@
 
 ## [0.1.4](https://github.com/supabase/agent-skills/compare/v0.1.3...v0.1.4) (2026-06-05)
 
-
 ### Features
 
-* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
-* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
-* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
+- add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+- add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+- instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
 
 ### Bug Fixes
 
-* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
-* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+- bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
 
 ## [0.1.3](https://github.com/supabase/agent-skills/compare/v0.1.2...v0.1.3) (2026-06-02)
 
-
 ### Features
 
-* add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
-* add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
-* instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
-* using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
-
+- add instructions to check changelog ([#74](https://github.com/supabase/agent-skills/issues/74)) ([4bb13d8](https://github.com/supabase/agent-skills/commit/4bb13d858d19f1f848505a66f46fc9603fdcde95))
+- add npm supply-chain security guidance to supabase skill ([#94](https://github.com/supabase/agent-skills/issues/94)) ([82df90a](https://github.com/supabase/agent-skills/commit/82df90a5de1cd84386d8bc192746e50343b86dc0))
+- instructions on exposing tables to the data api ([#71](https://github.com/supabase/agent-skills/issues/71)) ([f15a5a4](https://github.com/supabase/agent-skills/commit/f15a5a40779072a530c9e53c3f14ec4131118ea6))
+- using Supabase agent skills ([#12](https://github.com/supabase/agent-skills/issues/12)) ([7c2e389](https://github.com/supabase/agent-skills/commit/7c2e3894fddfde8eb6c77d2a8921904543b9be7a))
 
 ### Bug Fixes
 
-* bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
-* cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
-* update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
+- bump supabase skill to v0.1.1 and fix Data API broken link ([#72](https://github.com/supabase/agent-skills/issues/72)) ([5a6542e](https://github.com/supabase/agent-skills/commit/5a6542e08fc026d90c9a6a0f5a67749e9ceb9946))
+- cover SECURITY DEFINER, auth.role() deprecation, and BOLA in security checklist ([#85](https://github.com/supabase/agent-skills/issues/85)) ([133f43e](https://github.com/supabase/agent-skills/commit/133f43e8c2ffc48823ff0630c692cabecea3e3a3))
+- update Data API doc link and bump supabase skill to v0.1.1 ([#73](https://github.com/supabase/agent-skills/issues/73)) ([e5f7a7c](https://github.com/supabase/agent-skills/commit/e5f7a7cfd697765848ffd6a4505f3c02e1ee17ee))
diff --git a/.cursor/skills/testing-review/SKILL.md b/.cursor/skills/testing-review/SKILL.md
index c72c29671..23d9af423 100644
--- a/.cursor/skills/testing-review/SKILL.md
+++ b/.cursor/skills/testing-review/SKILL.md
@@ -10,10 +10,12 @@ Use this skill when reviewing test coverage, testing harnesses, and test executi
 ## Review Checklist
 
 ### 1. Test Harness Coverage
+
 - **Unit Tests:** Ensure new or modified utils, helper scripts, and backend libraries have corresponding Vitest unit tests (`*.test.ts`).
 - **E2E/UI Tests:** Verify frontend routes and interactive components are covered by Playwright specs (`ui-*.spec.ts`).
 - **Clinical Safety Assertions:** Check that tests verify critical safety boundaries, such as correct citation indexing, fallback behavior on weak RAG evidence, and tenant data isolation.
 
 ### 2. Flakiness & Mocking
+
 - **Mocking External APIs:** Ensure test flows do not hit live external APIs (like OpenAI) directly. Mock these services with predictable fixtures.
 - **Verification Gates:** Confirm the appropriate check level is used (`verify:cheap` for localized code changes, `verify:ui` for Chromium work, `verify:release` for comprehensive releases).
diff --git a/.cursor/skills/ux-review/SKILL.md b/.cursor/skills/ux-review/SKILL.md
index dd25ec116..d4de4dae9 100644
--- a/.cursor/skills/ux-review/SKILL.md
+++ b/.cursor/skills/ux-review/SKILL.md
@@ -10,9 +10,11 @@ Use this skill when reviewing user interface flows, search input behaviors, side
 ## Review Checklist
 
 ### 1. Search Composer Integration
+
 - **Composer Placement:** Verify that the shared composer (`master-search-header.tsx`) matches the correct placement rules (inline in heroes on home views, fixed bottom/sticky top on results, and absent on document viewers).
 - **Navigation:** Check that search queries trigger the correct routing paths (`?q=...&run=1`) and preserve active filters.
 
 ### 2. User Flows & Responsiveness
+
 - **Source-Review Friction:** Ensure the document drawer and PDF previewer load with minimal user interaction and maintain focus.
 - **Mobile Usability:** Verify touch boundaries, drawer slide-up interactions, and layout density on mobile/tablet widths.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 51b3fa4d4..44f687a6b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -151,13 +151,36 @@ jobs:
           persist-credentials: false
 
       - name: Setup Supabase CLI
-        uses: supabase/setup-cli@v1
+        uses: supabase/setup-cli@v3
         with:
           version: latest
 
+      - name: Restore Supabase Docker image cache
+        uses: actions/cache@v6
+        with:
+          path: /tmp/supabase-docker-cache
+          key: supabase-docker-${{ runner.os }}-${{ hashFiles('supabase/config.toml') }}
+          restore-keys: |
+            supabase-docker-${{ runner.os }}-
+
+      - name: Load cached Supabase Docker images
+        run: |
+          if [ -f /tmp/supabase-docker-cache/images.tar ]; then
+            docker load -i /tmp/supabase-docker-cache/images.tar
+          fi
+
       - name: Start Supabase Local Emulator
         run: supabase start
 
+      - name: Save Supabase Docker images
+        if: always()
+        run: |
+          mkdir -p /tmp/supabase-docker-cache
+          docker images --format '{{.Repository}}:{{.Tag}}' \
+            | grep -E '^(supabase/|ghcr.io/supabase/)' \
+            | sort -u \
+            | xargs -r docker save -o /tmp/supabase-docker-cache/images.tar
+
       - name: Verify Migration Replay
         run: supabase db reset
 
diff --git a/deno.lock b/deno.lock
index 97ed091da..34b0a980d 100644
--- a/deno.lock
+++ b/deno.lock
@@ -223,34 +223,34 @@
   "workspace": {
     "packageJson": {
       "dependencies": [
-        "npm:@next/env@16.2.9",
+        "npm:@next/env@16.2.10",
+        "npm:@supabase/ssr@0.12",
         "npm:@supabase/supabase-js@^2.108.2",
-        "npm:@tailwindcss/postcss@^4.3.1",
+        "npm:@tailwindcss/postcss@^4.3.2",
         "npm:@types/node@^24.13.2",
         "npm:@types/pdf-parse@^1.1.5",
         "npm:@types/pdfkit@~0.17.6",
         "npm:@types/react-dom@^19.2.3",
         "npm:@types/react@^19.2.17",
         "npm:@vitest/coverage-v8@^4.1.9",
-        "npm:eslint-config-next@16.2.9",
+        "npm:eslint-config-next@16.2.10",
         "npm:eslint@^9.39.4",
         "npm:exceljs@^4.4.0",
+        "npm:fast-check@^4.8.0",
         "npm:jszip@^3.10.1",
         "npm:lucide-react@^1.22.0",
         "npm:mammoth@^1.12.0",
-        "npm:next@16.2.9",
+        "npm:next@16.2.10",
         "npm:openai@^6.45.0",
         "npm:pdf-parse@^2.4.5",
         "npm:pdfjs-dist@^6.1.200",
         "npm:pdfkit@~0.19.1",
         "npm:playwright@^1.61.1",
         "npm:postcss@^8.5.15",
-        "npm:postgres@3.4.9",
-        "npm:prettier@^3.9.1",
+        "npm:prettier@^3.9.4",
         "npm:react-dom@19.2.7",
         "npm:react@19.2.7",
         "npm:tailwindcss@^4.3.1",
-        "npm:tesseract.js@7",
         "npm:tsx@^4.22.4",
         "npm:typescript@^6.0.3",
         "npm:vitest@^4.1.8",
diff --git a/scripts/reindex-image-generation-metadata.ts b/scripts/reindex-image-generation-metadata.ts
index 3d0f4904e..bf3fabf88 100644
--- a/scripts/reindex-image-generation-metadata.ts
+++ b/scripts/reindex-image-generation-metadata.ts
@@ -1,13 +1,11 @@
 import { loadEnvConfig } from "@next/env";
 import { confirm } from "./cli-utils";
 import { committedIndexGeneration, metadataRecord } from "@/lib/reindex-pipeline";
-import { assertSupabaseHealthy, probeSupabaseHealth } from "@/lib/supabase/health";
-import { checkSupabaseProjectConfig, formatSupabaseProjectCheck } from "@/lib/supabase/project";
-import { createAdminClient } from "@/lib/supabase/admin";
-import { requireServerEnv } from "@/lib/env";
 
 loadEnvConfig(process.cwd());
 
+type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
+
 type Args = {
   documentId: string | null;
   ownerId: string | null;
@@ -42,7 +40,12 @@ type UntypedTable = {
       column: string,
       value: string,
     ): {
-      range(from: number, to: number): Promise<{ data: unknown; error: { message: string } | null }>;
+      order(
+        column: string,
+        options: { ascending: boolean },
+      ): {
+        range(from: number, to: number): Promise<{ data: unknown; error: { message: string } | null }>;
+      };
     };
   };
   update(values: Record<string, unknown>): {
@@ -50,10 +53,27 @@ type UntypedTable = {
   };
 };
 
-function untypedTable(supabase: ReturnType<typeof createAdminClient>, table: string): UntypedTable {
+function untypedTable(supabase: AdminClient, table: string): UntypedTable {
   return supabase.from(table as never) as unknown as UntypedTable;
 }
 
+async function loadRuntime() {
+  const [{ createAdminClient }, { requireServerEnv }, health, project] = await Promise.all([
+    import("@/lib/supabase/admin"),
+    import("@/lib/env"),
+    import("@/lib/supabase/health"),
+    import("@/lib/supabase/project"),
+  ]);
+  return {
+    createAdminClient,
+    requireServerEnv,
+    assertSupabaseHealthy: health.assertSupabaseHealthy,
+    probeSupabaseHealth: health.probeSupabaseHealth,
+    checkSupabaseProjectConfig: project.checkSupabaseProjectConfig,
+    formatSupabaseProjectCheck: project.formatSupabaseProjectCheck,
+  };
+}
+
 function parseArgs(argv: string[]): Args {
   const args: Args = {
     documentId: null,
@@ -79,20 +99,18 @@ function parseArgs(argv: string[]): Args {
       args.confirm = true;
       continue;
     }
+    if (token !== "--document-id" && token !== "--owner-id" && token !== "--limit") {
+      throw new Error(`Unknown argument: ${token}`);
+    }
 
     const value = argv[index + 1];
     if (!value || value.startsWith("--")) {
-      if (token === "--document-id" || token === "--owner-id" || token === "--limit") {
-        throw new Error(`Missing value for ${token}`);
-      }
-      continue;
+      throw new Error(`Missing value for ${token}`);
     }
     if (token === "--document-id") args.documentId = value;
     if (token === "--owner-id") args.ownerId = value;
     if (token === "--limit") args.limit = Number.parseInt(value, 10);
-    if (token === "--document-id" || token === "--owner-id" || token === "--limit") {
-      index += 1;
-    }
+    index += 1;
   }
 
   if (!Number.isFinite(args.limit) || args.limit <= 0) {
@@ -113,7 +131,7 @@ function rowNeedsRefresh(row: ImageRow, committedGeneration: string) {
 }
 
 async function loadDocuments(args: {
-  supabase: ReturnType<typeof createAdminClient>;
+  supabase: AdminClient;
   ownerId: string | null;
   documentId: string | null;
   allOwners: boolean;
@@ -136,12 +154,13 @@ async function loadDocuments(args: {
   return (data ?? []) as DocumentRow[];
 }
 
-async function loadImages(args: { supabase: ReturnType<typeof createAdminClient>; documentId: string }) {
+async function loadImages(args: { supabase: AdminClient; documentId: string }) {
   const rows: ImageRow[] = [];
   for (let offset = 0; ; offset += 1000) {
     const { data, error } = await untypedTable(args.supabase, "document_images")
       .select("id,index_generation_id,metadata")
       .eq("document_id", args.documentId)
+      .order("id", { ascending: true })
       .range(offset, offset + 999);
     if (error) throw new Error(error.message);
     const page = (data ?? []) as unknown as ImageRow[];
@@ -153,6 +172,14 @@ async function loadImages(args: { supabase: ReturnType<typeof createAdminClient>
 
 async function main() {
   const args = parseArgs(process.argv.slice(2));
+  const {
+    createAdminClient,
+    requireServerEnv,
+    assertSupabaseHealthy,
+    probeSupabaseHealth,
+    checkSupabaseProjectConfig,
+    formatSupabaseProjectCheck,
+  } = await loadRuntime();
   requireServerEnv();
 
   const projectCheck = checkSupabaseProjectConfig(
diff --git a/scripts/seed-differential-records.ts b/scripts/seed-differential-records.ts
index 0283258c9..e78fdf95f 100644
--- a/scripts/seed-differential-records.ts
+++ b/scripts/seed-differential-records.ts
@@ -3,7 +3,6 @@ import { loadEnvConfig } from "@next/env";
 import { confirm } from "./cli-utils";
 import { buildDefaultDifferentialRows, loadDifferentialSnapshot } from "@/lib/differential-fixtures";
 import type { DifferentialRecordRow } from "@/lib/differential-records";
-import { embedDifferentialRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 
 loadEnvConfig(process.cwd());
 
@@ -18,6 +17,10 @@ async function loadAdminClient() {
   return createAdminClient();
 }
 
+async function loadRegistryCorpus() {
+  return import("@/lib/registry-corpus");
+}
+
 function parseArgs(argv: string[]): SeedArgs {
   const args: SeedArgs = {
     ownerId: process.env.LOCAL_NO_AUTH_OWNER_ID,
@@ -125,6 +128,7 @@ async function main() {
     console.log(`[differentials:seed] Done. Owner now has ${count ?? "?"} differential records.`);
   }
 
+  const { embedDifferentialRows, registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
   if (registryCorpusEmbeddingEnabled()) {
     const { data: embeddedRows, error: embedRowsError } = await supabase
       .from("differential_records")
diff --git a/scripts/seed-medication-records.ts b/scripts/seed-medication-records.ts
index 09582e05a..4e08a416c 100644
--- a/scripts/seed-medication-records.ts
+++ b/scripts/seed-medication-records.ts
@@ -2,7 +2,6 @@ import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
 import { buildMedicationSeedRows } from "@/lib/medication-seed";
-import { embedMedicationRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import type { MedicationRecordRow } from "@/lib/medication-records";
 
 loadEnvConfig(process.cwd());
@@ -18,6 +17,10 @@ async function loadAdminClient() {
   return createAdminClient();
 }
 
+async function loadRegistryCorpus() {
+  return import("@/lib/registry-corpus");
+}
+
 function parseArgs(argv: string[]): SeedArgs {
   const args: SeedArgs = {
     ownerId: process.env.LOCAL_NO_AUTH_OWNER_ID,
@@ -122,6 +125,7 @@ async function main() {
     console.log(`[medications:seed] Done. Owner now has ${count ?? "?"} medication records.`);
   }
 
+  const { embedMedicationRows, registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
   if (registryCorpusEmbeddingEnabled()) {
     const { data: embeddedRows, error: embedRowsError } = await supabase
       .from("medication_records")
diff --git a/scripts/seed-registry-records.ts b/scripts/seed-registry-records.ts
index 97bc0482b..0f7582f5d 100644
--- a/scripts/seed-registry-records.ts
+++ b/scripts/seed-registry-records.ts
@@ -1,7 +1,6 @@
 import { loadEnvConfig } from "@next/env";
 
 import { confirm } from "./cli-utils";
-import { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import type { RegistryRecordRow } from "@/lib/registry-records";
 import { type RegistryRecordKind } from "@/lib/registry-records";
 import { buildDefaultRegistryRows, defaultRegistryRecords } from "@/lib/registry-seed";
@@ -21,6 +20,10 @@ async function loadAdminClient() {
   return createAdminClient();
 }
 
+async function loadRegistryCorpus() {
+  return import("@/lib/registry-corpus");
+}
+
 function parseArgs(argv: string[]): SeedArgs {
   const args: SeedArgs = {
     ownerId: process.env.LOCAL_NO_AUTH_OWNER_ID,
@@ -147,6 +150,7 @@ async function main() {
     console.log(`[registry:seed] Done. Owner now has ${count ?? "?"} registry records.`);
   }
 
+  const { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
   if (registryCorpusEmbeddingEnabled()) {
     const kinds: RegistryRecordKind[] = args.kind === "all" ? ["service", "form"] : [args.kind];
     const { data: embeddedRows, error: embedRowsError } = await supabase
diff --git a/src/app/api/differentials/[slug]/route.ts b/src/app/api/differentials/[slug]/route.ts
index abe35bbb2..6689be3fb 100644
--- a/src/app/api/differentials/[slug]/route.ts
+++ b/src/app/api/differentials/[slug]/route.ts
@@ -19,6 +19,7 @@ import { getDifferentialRecord, getPresentationWorkflow } from "@/lib/differenti
 import { isDemoMode, isLocalNoAuthMode } from "@/lib/env";
 import { jsonError } from "@/lib/http";
 import { publicAccessContext, shouldResolvePublicCatalogAccess } from "@/lib/public-api-access";
+import { registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { createAdminClient } from "@/lib/supabase/admin";
 import { AuthenticationError, unauthorizedResponse } from "@/lib/supabase/auth";
 import { parseRequestQuery } from "@/lib/validation/query";
@@ -146,6 +147,7 @@ export async function GET(request: Request, context: { params: Promise<{ slug: s
           await ensureDifferentialsSeeded(supabase, access.ownerId);
         } catch (seedError) {
           console.error(`[differentials] auto-seed failed for owner ${access.ownerId}`, seedError);
+          if (registryCorpusEmbeddingEnabled()) throw seedError;
         }
         row = await fetchRecord();
       }
diff --git a/src/app/api/differentials/presentations/[slug]/route.ts b/src/app/api/differentials/presentations/[slug]/route.ts
index 85574d8fe..334ae96d7 100644
--- a/src/app/api/differentials/presentations/[slug]/route.ts
+++ b/src/app/api/differentials/presentations/[slug]/route.ts
@@ -18,6 +18,7 @@ import { getDifferentialRecord, getPresentationWorkflow } from "@/lib/differenti
 import { isDemoMode, isLocalNoAuthMode } from "@/lib/env";
 import { jsonError } from "@/lib/http";
 import { publicAccessContext, shouldResolvePublicCatalogAccess } from "@/lib/public-api-access";
+import { registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { createAdminClient } from "@/lib/supabase/admin";
 import { AuthenticationError, unauthorizedResponse } from "@/lib/supabase/auth";
 
@@ -130,6 +131,7 @@ export async function GET(request: Request, context: { params: Promise<{ slug: s
           await ensureDifferentialsSeeded(supabase, access.ownerId);
         } catch (seedError) {
           console.error(`[differentials] auto-seed failed for owner ${access.ownerId}`, seedError);
+          if (registryCorpusEmbeddingEnabled()) throw seedError;
         }
         row = await fetchPresentation();
       }
diff --git a/src/app/api/differentials/route.ts b/src/app/api/differentials/route.ts
index 9322e327c..d44da8707 100644
--- a/src/app/api/differentials/route.ts
+++ b/src/app/api/differentials/route.ts
@@ -25,6 +25,7 @@ import {
 import { isDemoMode, isLocalNoAuthMode } from "@/lib/env";
 import { jsonError } from "@/lib/http";
 import { publicAccessContext, shouldResolvePublicCatalogAccess } from "@/lib/public-api-access";
+import { registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { createAdminClient } from "@/lib/supabase/admin";
 import { AuthenticationError, unauthorizedResponse } from "@/lib/supabase/auth";
 import { parseRequestQuery, queryInteger } from "@/lib/validation/query";
@@ -134,6 +135,7 @@ export async function GET(request: Request) {
         await ensureDifferentialsSeeded(supabase, access.ownerId);
       } catch (seedError) {
         console.error(`[differentials] auto-seed failed for owner ${access.ownerId}`, seedError);
+        if (registryCorpusEmbeddingEnabled()) throw seedError;
       }
       rows = await fetchRecords(kind);
     }
diff --git a/src/app/api/medications/[slug]/route.ts b/src/app/api/medications/[slug]/route.ts
index 83ba38e40..9db651ed1 100644
--- a/src/app/api/medications/[slug]/route.ts
+++ b/src/app/api/medications/[slug]/route.ts
@@ -17,6 +17,7 @@ import {
   type MedicationRecordRow,
 } from "@/lib/medication-records";
 import { publicAccessContext, shouldResolvePublicCatalogAccess } from "@/lib/public-api-access";
+import { registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { createAdminClient } from "@/lib/supabase/admin";
 import { AuthenticationError, unauthorizedResponse } from "@/lib/supabase/auth";
 
@@ -114,6 +115,7 @@ export async function GET(request: Request, context: { params: Promise<{ slug: s
           await ensureMedicationsSeeded(supabase, access.ownerId);
         } catch (seedError) {
           console.error(`[medications] auto-seed failed for owner ${access.ownerId}`, seedError);
+          if (registryCorpusEmbeddingEnabled()) throw seedError;
         }
         row = await fetchRecord();
       }
diff --git a/src/app/api/registry/records/[slug]/route.ts b/src/app/api/registry/records/[slug]/route.ts
index 79eda031e..0797e19c1 100644
--- a/src/app/api/registry/records/[slug]/route.ts
+++ b/src/app/api/registry/records/[slug]/route.ts
@@ -17,6 +17,7 @@ import {
   rowToServiceRecord,
   type RegistryRecordRow,
 } from "@/lib/registry-records";
+import { registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { ensureRegistrySeeded } from "@/lib/registry-seed";
 import { getServiceRecord } from "@/lib/services";
 import { createAdminClient } from "@/lib/supabase/admin";
@@ -128,6 +129,7 @@ export async function GET(request: Request, context: { params: Promise<{ slug: s
           await ensureRegistrySeeded(supabase, access.ownerId, kind);
         } catch (seedError) {
           console.error(`[registry] auto-seed failed for owner ${access.ownerId} (${kind})`, seedError);
+          if (registryCorpusEmbeddingEnabled()) throw seedError;
         }
         row = await fetchRecord();
       }
diff --git a/src/lib/citations.ts b/src/lib/citations.ts
index 2d652f2ca..b6fc748fa 100644
--- a/src/lib/citations.ts
+++ b/src/lib/citations.ts
@@ -76,7 +76,30 @@ export function formatCompactCitationLabel(citation: Pick<Citation, "title" | "f
   return `${shortTitle} ${page}`;
 }
 
+function registryCitationHref(citation: Citation) {
+  const metadata = citation.source_metadata;
+  if (metadata?.source_kind !== "registry_record") return null;
+
+  const slug = metadata.registry_record_slug;
+  if (!slug) return null;
+
+  const encodedSlug = encodeURIComponent(slug);
+  if (metadata.registry_record_kind === "service") return `/services/${encodedSlug}`;
+  if (metadata.registry_record_kind === "form") return `/forms/${encodedSlug}`;
+  if (metadata.registry_record_kind === "medication") return `/medications/${encodedSlug}`;
+  if (metadata.registry_record_kind === "differential") {
+    return metadata.registry_record_subkind === "presentation"
+      ? `/differentials/presentations/${encodedSlug}`
+      : `/differentials/diagnoses/${encodedSlug}`;
+  }
+
+  return null;
+}
+
 export function documentCitationHref(citation: Citation) {
+  const registryHref = registryCitationHref(citation);
+  if (registryHref) return registryHref;
+
   const params = new URLSearchParams();
   if (citation.page_number) params.set("page", String(citation.page_number));
   params.set("chunk", citation.chunk_id);
diff --git a/src/lib/differential-seed.ts b/src/lib/differential-seed.ts
index c1b17d3f2..10d21cbf1 100644
--- a/src/lib/differential-seed.ts
+++ b/src/lib/differential-seed.ts
@@ -18,11 +18,7 @@ export async function ensureDifferentialsSeeded(
   if (error) throw new Error(`Differential seed failed: ${error.message}`);
   const seededRows = (data ?? []) as DifferentialRecordRow[];
   if (registryCorpusEmbeddingEnabled()) {
-    try {
-      await embedDifferentialRows(supabase, seededRows);
-    } catch (embedError) {
-      console.error(`[differentials] corpus embedding failed for owner ${ownerId}`, embedError);
-    }
+    await embedDifferentialRows(supabase, seededRows);
   }
   return seededRows;
 }
diff --git a/src/lib/document-index-units.ts b/src/lib/document-index-units.ts
index e669dfc19..a28dd0193 100644
--- a/src/lib/document-index-units.ts
+++ b/src/lib/document-index-units.ts
@@ -144,6 +144,14 @@ function bestOcrRepair(fragment: string, dictionary: string[]) {
   return best?.word ?? null;
 }
 
+function repairDropsStandaloneClinicalLetter(fragment: string, repair: string) {
+  const tokens = fragment.toLowerCase().match(/[a-z]+/g) ?? [];
+  if (!tokens.some((token) => token.length === 1)) return false;
+  return tokens.some(
+    (token, index) => token.length === 1 && tokens.filter((_, itemIndex) => itemIndex !== index).join("") === repair,
+  );
+}
+
 export function repairOcrDropoutAgainstReference(text: string, reference: string) {
   const dictionary = referenceDictionary(reference);
   if (dictionary.length === 0) return { text, replacements: [] as Array<{ from: string; to: string }> };
@@ -162,6 +170,7 @@ export function repairOcrDropoutAgainstReference(text: string, reference: string
       if (!/^[A-Za-z]+(?:\s+[A-Za-z]+)+$/.test(fragment)) continue;
       const repair = bestOcrRepair(fragment, dictionary);
       if (!repair || repair === fragment.toLowerCase()) continue;
+      if (repairDropsStandaloneClinicalLetter(fragment, repair)) continue;
       const currentFragment = repaired.slice(start, end);
       if (currentFragment !== fragment) continue;
       repaired = `${repaired.slice(0, start)}${repair}${repaired.slice(end)}`;
diff --git a/src/lib/medication-seed.ts b/src/lib/medication-seed.ts
index 78179fb41..97f294a53 100644
--- a/src/lib/medication-seed.ts
+++ b/src/lib/medication-seed.ts
@@ -17,11 +17,7 @@ export async function ensureMedicationsSeeded(supabase: AdminClient, ownerId: st
   if (error) throw new Error(`Medication seed failed: ${error.message}`);
   const seededRows = (data ?? []) as MedicationRecordRow[];
   if (registryCorpusEmbeddingEnabled()) {
-    try {
-      await embedMedicationRows(supabase, seededRows);
-    } catch (embedError) {
-      console.error(`[medications] corpus embedding failed for owner ${ownerId}`, embedError);
-    }
+    await embedMedicationRows(supabase, seededRows);
   }
   return seededRows;
 }
@@ -55,6 +51,7 @@ export async function fetchOwnerMedicationRowsWithSeed(
       await ensureMedicationsSeeded(supabase, ownerId);
     } catch (seedError) {
       console.error(`[medications] auto-seed failed for owner ${ownerId}`, seedError);
+      if (registryCorpusEmbeddingEnabled()) throw seedError;
     }
     rows = await fetchRecords();
   }
diff --git a/src/lib/rag.ts b/src/lib/rag.ts
index b33e6fb58..4f0484640 100644
--- a/src/lib/rag.ts
+++ b/src/lib/rag.ts
@@ -2346,6 +2346,18 @@ function createDocumentRankingMetadataCache(): DocumentRankingMetadataCache {
   };
 }
 
+function attachCachedDocumentMetadata(results: SearchResult[], cache: DocumentRankingMetadataCache) {
+  return results.map((result) => {
+    const metadata = cache.documentMetadata.get(result.document_id);
+    if (!metadata) return result;
+    return {
+      ...result,
+      document_labels: metadata.labels,
+      document_summary: metadata.summary,
+    };
+  });
+}
+
 async function attachDocumentRankingMetadata(
   supabase: ReturnType<typeof createAdminClient>,
   results: SearchResult[],
@@ -2364,7 +2376,9 @@ async function attachDocumentRankingMetadata(
           (result.document_summary === undefined || result.document_summary === null),
       ),
   );
-  if (missingDocumentIds.length === 0) return attachIndexQualityMetadata(supabase, results, ownerId, cache);
+  if (missingDocumentIds.length === 0) {
+    return attachIndexQualityMetadata(supabase, attachCachedDocumentMetadata(results, cache), ownerId, cache);
+  }
 
   try {
     const metadataRows = await fetchRelatedDocumentMetadata({
@@ -2376,16 +2390,7 @@ async function attachDocumentRankingMetadata(
     for (const row of metadataRows) {
       cache.documentMetadata.set(row.document_id, { labels: row.labels, summary: row.summary });
     }
-    const metadataByDocument = new Map(metadataRows.map((row) => [row.document_id, row]));
-    const enriched = results.map((result) => {
-      const metadata = metadataByDocument.get(result.document_id) ?? cache.documentMetadata.get(result.document_id);
-      if (!metadata) return result;
-      return {
-        ...result,
-        document_labels: metadata.labels,
-        document_summary: metadata.summary,
-      };
-    });
+    const enriched = attachCachedDocumentMetadata(results, cache);
     return attachIndexQualityMetadata(supabase, enriched, ownerId, cache);
   } catch {
     return results;
@@ -3249,13 +3254,6 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
   const maxResultsPerDocument = queryClassification.queryClass === "comparison" ? 2 : 4;
   const minSimilarity = args.minSimilarity ?? 0.15;
   let embeddingStartedAt = 0;
-  const preloadedEmbedding =
-    !sourceOnlyRetrieval && !args.lexicalOnly
-      ? (() => {
-          embeddingStartedAt = Date.now();
-          return Promise.resolve(embedTextWithTelemetry(expandedQuery)).catch(() => null);
-        })()
-      : null;
 
   let textFastResults: SearchResult[] = [];
   const textRpcStartedAt = Date.now();
@@ -3285,9 +3283,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
       args.ownerId,
       documentRankingMetadataCache,
     );
-    if (!preloadedEmbedding) {
-      expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, textCandidates);
-    }
+    expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, textCandidates);
     const baseTextResults = selectRankedRetrievalResults({
       query: retrievalQuery,
       queryClass: queryClassification.queryClass,
@@ -3408,9 +3404,7 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
         args.ownerId,
         documentRankingMetadataCache,
       );
-      if (!preloadedEmbedding) {
-        expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, documentLookupCandidates);
-      }
+      expandedQuery = expandClinicalQueryWithCandidateMetadata(args.query, expandedQuery, documentLookupCandidates);
       const memoryBoost = await withMemoryBoostedCandidates({
         supabase,
         query: args.query,
@@ -3506,23 +3500,20 @@ export async function searchChunksWithTelemetry(args: SearchChunksArgs) {
   }
 
   throwIfAborted(args.signal);
-  if (!embeddingStartedAt) embeddingStartedAt = Date.now();
-  let embeddingResult = await preloadedEmbedding;
-  if (!embeddingResult) {
-    embeddingStartedAt = Date.now();
-    try {
-      embeddingResult = await embedTextWithTelemetry(expandedQuery);
-    } catch (error) {
-      // In auto mode a failed embedding call (e.g. quota exhausted) degrades to the lexical
-      // results already gathered rather than failing the whole search. "openai" mode rethrows.
-      if (args.forceEmbedding || !allowsAutoDegrade()) throw error;
-      telemetry.embedding_skipped = true;
-      telemetry.embedding_skip_reason = sourceOnlyReason(error);
-      telemetry.vector_skipped_reason = classifyProviderFailure(error);
-      telemetry.retrieval_strategy = telemetry.retrieval_strategy ?? "text_fast_path";
-      recordSearchScoreTelemetry(telemetry, textFastResults);
-      return { results: textFastResults, telemetry };
-    }
+  embeddingStartedAt = Date.now();
+  let embeddingResult: Awaited<ReturnType<typeof embedTextWithTelemetry>>;
+  try {
+    embeddingResult = await embedTextWithTelemetry(expandedQuery);
+  } catch (error) {
+    // In auto mode a failed embedding call (e.g. quota exhausted) degrades to the lexical
+    // results already gathered rather than failing the whole search. "openai" mode rethrows.
+    if (args.forceEmbedding || !allowsAutoDegrade()) throw error;
+    telemetry.embedding_skipped = true;
+    telemetry.embedding_skip_reason = sourceOnlyReason(error);
+    telemetry.vector_skipped_reason = classifyProviderFailure(error);
+    telemetry.retrieval_strategy = telemetry.retrieval_strategy ?? "text_fast_path";
+    recordSearchScoreTelemetry(telemetry, textFastResults);
+    return { results: textFastResults, telemetry };
   }
   const { embedding, cacheHit } = embeddingResult;
   telemetry.embedding_latency_ms = Date.now() - embeddingStartedAt;
diff --git a/src/lib/registry-corpus.ts b/src/lib/registry-corpus.ts
index 8a3bcfc1c..7cbdd9ac2 100644
--- a/src/lib/registry-corpus.ts
+++ b/src/lib/registry-corpus.ts
@@ -58,12 +58,6 @@ function compactText(parts: unknown[], limit = 8000) {
   return text.length <= limit ? text : `${text.slice(0, limit - 3).trim()}...`;
 }
 
-function stringArray(value: unknown) {
-  return Array.isArray(value)
-    ? value.filter((item): item is string => typeof item === "string" && item.trim().length > 0)
-    : [];
-}
-
 function registryBaseMetadata(entry: RegistryCorpusEntry): Record<string, Json> {
   return {
     source_kind: "registry_record",
@@ -207,7 +201,7 @@ export function medicationRowsToCorpusEntries(rows: MedicationRecordRow[]): Regi
       metadata: {
         medication_class: row.class,
         medication_subclass: row.subclass,
-        tags: stringArray(row.tag),
+        tags: row.tag ? [row.tag] : [],
       },
     };
   });
@@ -254,12 +248,32 @@ export async function embedRegistryCorpusEntries(supabase: AdminClient, entries:
   const embeddings = await embedTexts(entries.map((entry) => entry.content));
   const documents = entries.map(registryDocumentRow);
   const chunks = entries.map((entry, index) => registryChunkRow(entry, embeddings[index] as Vector));
+  const documentIds = documents.map((document) => document.id).filter((id): id is string => typeof id === "string");
+  const { data: existingDocuments, error: existingDocumentError } = await supabase
+    .from("documents")
+    .select("id")
+    .in("id", documentIds);
+  if (existingDocumentError) {
+    throw new Error(`Registry corpus preflight failed: ${existingDocumentError.message}`);
+  }
+  const existingDocumentIds = new Set((existingDocuments ?? []).map((document) => document.id));
 
   const { error: documentError } = await supabase.from("documents").upsert(documents, { onConflict: "id" });
   if (documentError) throw new Error(`Registry corpus document upsert failed: ${documentError.message}`);
 
   const { error: chunkError } = await supabase.from("document_chunks").upsert(chunks, { onConflict: "id" });
-  if (chunkError) throw new Error(`Registry corpus chunk upsert failed: ${chunkError.message}`);
+  if (chunkError) {
+    const insertedDocumentIds = documentIds.filter((id) => !existingDocumentIds.has(id));
+    if (insertedDocumentIds.length > 0) {
+      const { error: rollbackError } = await supabase.from("documents").delete().in("id", insertedDocumentIds);
+      if (rollbackError) {
+        throw new Error(
+          `Registry corpus chunk upsert failed: ${chunkError.message}; rollback failed: ${rollbackError.message}`,
+        );
+      }
+    }
+    throw new Error(`Registry corpus chunk upsert failed: ${chunkError.message}`);
+  }
 
   return { documentCount: documents.length, chunkCount: chunks.length };
 }
diff --git a/src/lib/registry-seed.ts b/src/lib/registry-seed.ts
index 4078b3879..5aec60940 100644
--- a/src/lib/registry-seed.ts
+++ b/src/lib/registry-seed.ts
@@ -45,11 +45,7 @@ export async function ensureRegistrySeeded(
   if (error) throw new Error(`Registry seed failed: ${error.message}`);
   const seededRows = (data ?? []) as RegistryRecordRow[];
   if (registryCorpusEmbeddingEnabled()) {
-    try {
-      await embedClinicalRegistryRows(supabase, seededRows);
-    } catch (embedError) {
-      console.error(`[registry] corpus embedding failed for owner ${ownerId} (${kind})`, embedError);
-    }
+    await embedClinicalRegistryRows(supabase, seededRows);
   }
   return seededRows;
 }
@@ -85,6 +81,7 @@ export async function fetchOwnerRegistryRowsWithSeed(
       await ensureRegistrySeeded(supabase, ownerId, kind);
     } catch (seedError) {
       console.error(`[registry] auto-seed failed for owner ${ownerId} (${kind})`, seedError);
+      if (registryCorpusEmbeddingEnabled()) throw seedError;
     }
     rows = await fetchRecords();
   }
diff --git a/src/lib/source-governance.ts b/src/lib/source-governance.ts
index d701fa569..e9249a958 100644
--- a/src/lib/source-governance.ts
+++ b/src/lib/source-governance.ts
@@ -74,6 +74,14 @@ function pushUnique(warnings: SourceGovernanceWarning[], warning: SourceGovernan
   warnings.push(warning);
 }
 
+function prioritizeSourceWarnings(warnings: SourceGovernanceWarning[]) {
+  const severityRank = { danger: 0, warning: 1, info: 2 } satisfies Record<SourceGovernanceWarning["severity"], number>;
+  return warnings
+    .map((warning, index) => ({ warning, index }))
+    .sort((a, b) => severityRank[a.warning.severity] - severityRank[b.warning.severity] || a.index - b.index)
+    .map((item) => item.warning);
+}
+
 export function sourceGovernanceWarnings(args: {
   results: SearchResult[];
   relevance?: EvidenceRelevance | null;
@@ -94,17 +102,6 @@ export function sourceGovernanceWarnings(args: {
     const title = result.title;
     const document_id = result.document_id;
 
-    if (source.source_kind === "registry_record") {
-      pushUnique(warnings, {
-        code: "registry_record_source",
-        severity: "info",
-        message:
-          "One or more supporting sources are curated registry summaries, not source documents; verify against linked source documents for clinical decisions.",
-        document_id,
-        title,
-      });
-    }
-
     if (source.document_status === "outdated") {
       pushUnique(warnings, {
         code: "outdated_source",
@@ -185,9 +182,20 @@ export function sourceGovernanceWarnings(args: {
         title,
       });
     }
+
+    if (source.source_kind === "registry_record") {
+      pushUnique(warnings, {
+        code: "registry_record_source",
+        severity: "info",
+        message:
+          "One or more supporting sources are curated registry summaries, not source documents; verify against linked source documents for clinical decisions.",
+        document_id,
+        title,
+      });
+    }
   }
 
-  return warnings.slice(0, args.limit ?? 8);
+  return prioritizeSourceWarnings(warnings).slice(0, args.limit ?? 8);
 }
 
 function plural(count: number, singular: string, pluralValue = `${singular}s`) {
diff --git a/src/lib/source-metadata.ts b/src/lib/source-metadata.ts
index 4ede237a6..1871b59d8 100644
--- a/src/lib/source-metadata.ts
+++ b/src/lib/source-metadata.ts
@@ -17,6 +17,10 @@ export function normalizeSourceMetadata(input: unknown): ClinicalSourceMetadata
 
   return {
     source_kind: stringOrNull(value.source_kind),
+    registry_record_kind: stringOrNull(value.registry_record_kind),
+    registry_record_subkind: stringOrNull(value.registry_record_subkind),
+    registry_record_id: stringOrNull(value.registry_record_id),
+    registry_record_slug: stringOrNull(value.registry_record_slug),
     source_title: stringOrNull(value.source_title),
     publisher: stringOrNull(value.publisher),
     jurisdiction: stringOrNull(value.jurisdiction),
@@ -45,12 +49,12 @@ export function formatClinicalDate(value: string | null | undefined) {
 }
 
 export function sourceStatusLabel(metadata?: ClinicalSourceMetadata | null) {
-  if (metadata?.source_kind === "registry_record") return "Registry summary";
+  const registryPrefix = metadata?.source_kind === "registry_record" ? "Registry summary" : null;
   const status = metadata?.document_status ?? "unknown";
-  if (status === "current") return "Current source";
-  if (status === "review_due") return "Review due";
-  if (status === "outdated") return "Outdated source";
-  return "Review status unknown";
+  if (status === "current") return registryPrefix ?? "Current source";
+  if (status === "review_due") return registryPrefix ? `${registryPrefix} - review due` : "Review due";
+  if (status === "outdated") return registryPrefix ? `${registryPrefix} - outdated` : "Outdated source";
+  return registryPrefix ? `${registryPrefix} - review status unknown` : "Review status unknown";
 }
 
 export function validationStatusLabel(metadata?: ClinicalSourceMetadata | null) {
diff --git a/src/lib/types.ts b/src/lib/types.ts
index 012657f5a..2c8e353ad 100644
--- a/src/lib/types.ts
+++ b/src/lib/types.ts
@@ -95,6 +95,10 @@ export type DocumentOrganizationProfile = {
 
 export type ClinicalSourceMetadata = {
   source_kind?: "document" | "registry_record" | string | null;
+  registry_record_kind?: "service" | "form" | "medication" | "differential" | string | null;
+  registry_record_subkind?: string | null;
+  registry_record_id?: string | null;
+  registry_record_slug?: string | null;
   source_title: string | null;
   publisher: string | null;
   publisher_code?: string | null;
diff --git a/supabase/migrations/20260708160000_retrieval_owner_matches_fail_closed.sql b/supabase/migrations/20260708161000_retrieval_owner_matches_fail_closed.sql
similarity index 100%
rename from supabase/migrations/20260708160000_retrieval_owner_matches_fail_closed.sql
rename to supabase/migrations/20260708161000_retrieval_owner_matches_fail_closed.sql
diff --git a/tests/citations.test.ts b/tests/citations.test.ts
index ef3a755f7..4896d115e 100644
--- a/tests/citations.test.ts
+++ b/tests/citations.test.ts
@@ -106,6 +106,57 @@ describe("citations", () => {
     expect(documentCitationHref(citationFromResult(result))).toBe("/documents/doc-1?page=12&chunk=chunk-1");
   });
 
+  it("links registry citations to their native detail route instead of the storage-backed document viewer", () => {
+    expect(
+      documentCitationHref(
+        citation({
+          source_metadata: {
+            source_kind: "registry_record",
+            registry_record_kind: "service",
+            registry_record_slug: "crisis-service",
+            source_title: "Crisis service",
+            publisher: "Clinical KB registry",
+            jurisdiction: "WA/local clinical workspace",
+            version: null,
+            publication_date: null,
+            review_date: null,
+            uploaded_at: null,
+            indexed_at: null,
+            uploaded_by: null,
+            document_status: "current",
+            clinical_validation_status: "locally_reviewed",
+            extraction_quality: "good",
+          },
+        }),
+      ),
+    ).toBe("/services/crisis-service");
+
+    expect(
+      documentCitationHref(
+        citation({
+          source_metadata: {
+            source_kind: "registry_record",
+            registry_record_kind: "differential",
+            registry_record_subkind: "presentation",
+            registry_record_slug: "first-episode-psychosis",
+            source_title: "First episode psychosis",
+            publisher: "Clinical KB registry",
+            jurisdiction: "WA/local clinical workspace",
+            version: null,
+            publication_date: null,
+            review_date: null,
+            uploaded_at: null,
+            indexed_at: null,
+            uploaded_by: null,
+            document_status: "current",
+            clinical_validation_status: "locally_reviewed",
+            extraction_quality: "good",
+          },
+        }),
+      ),
+    ).toBe("/differentials/presentations/first-episode-psychosis");
+  });
+
   it("deduplicates visible citations by document page and chunk", () => {
     const citations = uniqueCitations([
       citation(),
diff --git a/tests/document-index-units.test.ts b/tests/document-index-units.test.ts
index facd25a00..55ec250f0 100644
--- a/tests/document-index-units.test.ts
+++ b/tests/document-index-units.test.ts
@@ -278,4 +278,48 @@ describe("document index units", () => {
       expect.arrayContaining([expect.objectContaining({ from: "p ycho ocial", to: "psychosocial" })]),
     );
   });
+
+  it("does not repair by deleting standalone clinical letter tokens", () => {
+    const units = buildDocumentIndexUnitInputs({
+      document,
+      chunks: [
+        {
+          id: "chunk-1",
+          document_id: "doc-1",
+          page_number: 8,
+          chunk_index: 0,
+          section_heading: "Supplements",
+          section_path: ["Supplements"],
+          content: "Vitamin deficiency and class antiarrhythmics are separate concepts.",
+          metadata: {},
+        },
+      ],
+      images: [
+        {
+          id: "image-letters",
+          pageNumber: 8,
+          sourceKind: "table_crop",
+          tableTitle: "Medication considerations",
+          tableRows: [
+            ["vitamin D deficiency", "check baseline status"],
+            ["Class I antiarrhythmics", "avoid in selected cardiac risk"],
+          ],
+          tableColumns: ["Risk", "Action"],
+          metadata: {},
+        },
+      ],
+    });
+
+    const repairedFragments = units.flatMap((unit) =>
+      Array.isArray(unit.metadata.ocr_replacements) ? unit.metadata.ocr_replacements : [],
+    );
+    expect(repairedFragments).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ from: "vitamin D deficiency" }),
+        expect.objectContaining({ from: "Class I antiarrhythmics" }),
+      ]),
+    );
+    expect(units.map((unit) => unit.content).join("\n")).toContain("vitamin D deficiency");
+    expect(units.map((unit) => unit.content).join("\n")).toContain("Class I antiarrhythmics");
+  });
 });
diff --git a/tests/registry-corpus.test.ts b/tests/registry-corpus.test.ts
index c78bf3986..8a49ca74c 100644
--- a/tests/registry-corpus.test.ts
+++ b/tests/registry-corpus.test.ts
@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
-import { clinicalRegistryRowsToCorpusEntries } from "../src/lib/registry-corpus";
+import { clinicalRegistryRowsToCorpusEntries, medicationRowsToCorpusEntries } from "../src/lib/registry-corpus";
+import type { MedicationRecordRow } from "../src/lib/medication-records";
 import type { RegistryRecordRow } from "../src/lib/registry-records";
 
 function registryRow(overrides: Partial<RegistryRecordRow> = {}): RegistryRecordRow {
@@ -40,6 +41,31 @@ function registryRow(overrides: Partial<RegistryRecordRow> = {}): RegistryRecord
   };
 }
 
+function medicationRow(overrides: Partial<MedicationRecordRow> = {}): MedicationRecordRow {
+  return {
+    id: "33333333-3333-4333-8333-333333333333",
+    owner_id: "22222222-2222-4222-8222-222222222222",
+    slug: "lithium",
+    name: "Lithium",
+    accent: null,
+    class: "Mood stabiliser",
+    subclass: "Mineral",
+    category: "mood-stabiliser",
+    schedule: "S4",
+    tag: "monitoring",
+    quick: [],
+    sections: [],
+    stats: {},
+    source_status: "current",
+    validation_status: "locally_reviewed",
+    last_reviewed_at: null,
+    review_due_at: null,
+    created_at: "2026-07-01T00:00:00.000Z",
+    updated_at: "2026-07-01T00:00:00.000Z",
+    ...overrides,
+  };
+}
+
 describe("registry corpus", () => {
   it("converts registry rows into source-governed corpus entries", () => {
     const [entry] = clinicalRegistryRowsToCorpusEntries([registryRow()]);
@@ -67,4 +93,10 @@ describe("registry corpus", () => {
     expect(entry).toMatchObject({ kind: "form", subkind: "form", slug: "transport-order" });
     expect(entry?.content).toContain("Form: Transport order");
   });
+
+  it("maps scalar medication tags into registry corpus metadata", () => {
+    const [entry] = medicationRowsToCorpusEntries([medicationRow()]);
+
+    expect(entry?.metadata.tags).toEqual(["monitoring"]);
+  });
 });
diff --git a/tests/source-governance.test.ts b/tests/source-governance.test.ts
index a56ebdd0d..53d6914a8 100644
--- a/tests/source-governance.test.ts
+++ b/tests/source-governance.test.ts
@@ -288,6 +288,67 @@ describe("source governance warnings", () => {
     expect(groupSourceGovernanceWarnings(warnings)[0]?.message).toBe("1 registry summary used as supporting evidence.");
   });
 
+  it("keeps danger and warning source issues ahead of registry info when limiting warnings", () => {
+    const warnings = sourceGovernanceWarnings({
+      limit: 2,
+      results: [
+        result({
+          document_id: "registry-doc",
+          source_metadata: {
+            source_kind: "registry_record",
+            source_title: "Registry summary",
+            publisher: "Clinical KB registry",
+            jurisdiction: "WA/local clinical workspace",
+            version: null,
+            publication_date: null,
+            review_date: null,
+            uploaded_at: null,
+            indexed_at: null,
+            uploaded_by: null,
+            document_status: "current",
+            clinical_validation_status: "locally_reviewed",
+            extraction_quality: "good",
+          },
+          indexing_quality: {
+            document_id: "registry-doc",
+            quality_score: 0.9,
+            extraction_quality: "good",
+            metrics: {},
+            issues: [],
+          },
+          table_facts: [],
+        }),
+        result({
+          document_id: "outdated-doc",
+          source_metadata: {
+            source_title: "Outdated guideline",
+            publisher: "WA Health",
+            jurisdiction: "Australia/WA",
+            version: null,
+            publication_date: null,
+            review_date: null,
+            uploaded_at: null,
+            indexed_at: null,
+            uploaded_by: null,
+            document_status: "outdated",
+            clinical_validation_status: "unverified",
+            extraction_quality: "good",
+          },
+          indexing_quality: {
+            document_id: "outdated-doc",
+            quality_score: 0.9,
+            extraction_quality: "good",
+            metrics: {},
+            issues: [],
+          },
+          table_facts: [],
+        }),
+      ],
+    });
+
+    expect(warnings.map((warning) => warning.code)).toEqual(["outdated_source", "unverified_source"]);
+  });
+
   it("keeps the refusal message free of backend and source-backed wording", () => {
     expect(sourceGovernanceRefusalAnswer).not.toMatch(/source-backed|source-governance|admin|need review/i);
     expect(sourceGovernanceRefusalAnswer).toContain("matched documents are not suitable for clinical use yet");
diff --git a/tests/source-metadata.test.ts b/tests/source-metadata.test.ts
index 06eef7a5e..581ebb999 100644
--- a/tests/source-metadata.test.ts
+++ b/tests/source-metadata.test.ts
@@ -39,6 +39,18 @@ describe("source metadata helpers", () => {
     expect(line).toContain("Jurisdiction: Australia/WA");
   });
 
+  it("preserves stale status labels for registry summaries", () => {
+    const metadata = normalizeSourceMetadata({
+      source_kind: "registry_record",
+      document_status: "outdated",
+      clinical_validation_status: "locally_reviewed",
+    });
+
+    expect(sourceStatusLabel(metadata)).toBe("Registry summary - outdated");
+    expect(sourceProvenanceSummary(metadata)).toContain("Registry summary - outdated");
+    expect(clipboardProvenanceLine(metadata)).toContain("Review status: Registry summary - outdated");
+  });
+
   it("drops unknown filler segments but keeps governance warnings", () => {
     const emptySummary = sourceProvenanceSummary(normalizeSourceMetadata(null));
 

From 553eac9aa35424449baa33d4df0ebd1919f47ab0 Mon Sep 17 00:00:00 2001
From: Cursor Agent <cursoragent@cursor.com>
Date: Thu, 9 Jul 2026 08:34:39 +0000
Subject: [PATCH 11/16] fix: address PR 433 review comments on image re-stamp
 and eval forcing

Treat NULL document_images.index_generation_id as stale even when JSON
metadata already matches the committed generation, and propagate global
--force-embedding into eval reporting/validation so index-unit-vector runs
count forced cases correctly.

Co-authored-by: BigSimmo <BigSimmo@users.noreply.github.com>
---
 scripts/eval-quality.ts                      |  1 +
 scripts/reindex-image-generation-metadata.ts | 10 ++++----
 src/lib/reindex-pipeline.ts                  |  9 +++++++
 tests/reindex-pipeline.test.ts               | 25 ++++++++++++++++++++
 4 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/scripts/eval-quality.ts b/scripts/eval-quality.ts
index 23eb97877..fdeddd5fb 100644
--- a/scripts/eval-quality.ts
+++ b/scripts/eval-quality.ts
@@ -780,6 +780,7 @@ async function runRetrievalQualityCases(args: {
     results.push(
       evaluateGoldenRetrievalCase({
         testCase,
+        globalForceEmbedding: args.forceEmbedding,
         results: search.results,
         telemetry: search.telemetry,
         latencyMs,
diff --git a/scripts/reindex-image-generation-metadata.ts b/scripts/reindex-image-generation-metadata.ts
index c3d8a3dd1..fd391134a 100644
--- a/scripts/reindex-image-generation-metadata.ts
+++ b/scripts/reindex-image-generation-metadata.ts
@@ -1,6 +1,6 @@
 import { loadEnvConfig } from "@next/env";
 import { confirm } from "./cli-utils";
-import { committedIndexGeneration, metadataRecord } from "@/lib/reindex-pipeline";
+import { committedIndexGeneration, imageRowNeedsGenerationRestamp, metadataRecord } from "@/lib/reindex-pipeline";
 
 loadEnvConfig(process.cwd());
 
@@ -108,9 +108,11 @@ function parseArgs(argv: string[]): Args {
 }
 
 function rowNeedsRefresh(row: ImageRow, committedGeneration: string) {
-  if (row.index_generation_id === null) return true;
-  if (row.index_generation_id !== committedGeneration) return true;
-  return committedIndexGeneration(row.metadata) !== committedGeneration;
+  return imageRowNeedsGenerationRestamp({
+    indexGenerationId: row.index_generation_id,
+    metadata: row.metadata,
+    committedGeneration,
+  });
 }
 
 async function loadDocuments(args: {
diff --git a/src/lib/reindex-pipeline.ts b/src/lib/reindex-pipeline.ts
index 2fda55bfe..d5c69388b 100644
--- a/src/lib/reindex-pipeline.ts
+++ b/src/lib/reindex-pipeline.ts
@@ -54,6 +54,15 @@ export function isCommittedGenerationMetadata(args: { rowMetadata?: unknown; com
   return rowGeneration === args.committedGeneration;
 }
 
+export function imageRowNeedsGenerationRestamp(args: {
+  indexGenerationId: string | null;
+  metadata: unknown;
+  committedGeneration: string;
+}) {
+  if (args.indexGenerationId !== args.committedGeneration) return true;
+  return committedIndexGeneration(args.metadata) !== args.committedGeneration;
+}
+
 export function isAbandonedStagedGeneration(args: {
   rowMetadata?: unknown;
   rowGenerationId?: string | null;
diff --git a/tests/reindex-pipeline.test.ts b/tests/reindex-pipeline.test.ts
index 2d025b3cc..1bb76c686 100644
--- a/tests/reindex-pipeline.test.ts
+++ b/tests/reindex-pipeline.test.ts
@@ -3,6 +3,7 @@ import {
   abandonedReindexGenerationTotal,
   committedIndexGeneration,
   hasAbandonedReindexGenerations,
+  imageRowNeedsGenerationRestamp,
   isAbandonedStagedGeneration,
   hasIncompleteDocumentsWithoutOpenJobs,
   isAtomicReindexCandidate,
@@ -84,6 +85,30 @@ describe("reindex pipeline queue state", () => {
     ).toBe(true);
   });
 
+  it("identifies image rows that still need typed generation columns populated", () => {
+    expect(
+      imageRowNeedsGenerationRestamp({
+        indexGenerationId: null,
+        metadata: { index_generation_id: "generation-a" },
+        committedGeneration: "generation-a",
+      }),
+    ).toBe(true);
+    expect(
+      imageRowNeedsGenerationRestamp({
+        indexGenerationId: "generation-a",
+        metadata: { index_generation_id: "generation-a" },
+        committedGeneration: "generation-a",
+      }),
+    ).toBe(false);
+    expect(
+      imageRowNeedsGenerationRestamp({
+        indexGenerationId: "generation-b",
+        metadata: { index_generation_id: "generation-b" },
+        committedGeneration: "generation-a",
+      }),
+    ).toBe(true);
+  });
+
   it("identifies abandoned staged generation rows without flagging legacy generationless rows", () => {
     expect(
       isAbandonedStagedGeneration({

From 6a905164ebaaa968305b8ec7b8282d8aafd13b83 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 17:18:04 +0800
Subject: [PATCH 12/16] fix: restore neutralized 160000 migration for Supabase
 Preview parity

PR #433 preview branch recorded 20260708160000 before the file was removed, causing remote migration versions not found in local migrations directory. Keep a no-op stub for history sync; transactional index DDL stays on 170000.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 ...000_ingestion_jobs_one_open_per_document.sql | 11 +++++++++++
 ...000_ingestion_jobs_one_open_per_document.sql |  6 +++---
 tests/supabase-schema.test.ts                   | 17 +++++++++++++++++
 3 files changed, 31 insertions(+), 3 deletions(-)
 create mode 100644 supabase/migrations/20260708160000_ingestion_jobs_one_open_per_document.sql

diff --git a/supabase/migrations/20260708160000_ingestion_jobs_one_open_per_document.sql b/supabase/migrations/20260708160000_ingestion_jobs_one_open_per_document.sql
new file mode 100644
index 000000000..c12dbbca0
--- /dev/null
+++ b/supabase/migrations/20260708160000_ingestion_jobs_one_open_per_document.sql
@@ -0,0 +1,11 @@
+-- NEUTRALIZED 2026-07-09 — DO NOT DELETE THIS FILE.
+--
+-- Supabase Preview branch mouqbgieqejpamctasbu (PR #433) recorded this stem
+-- after the original CONCURRENTLY definition shipped. Removing the file breaks
+-- preview sync with "Remote migration versions not found in local migrations
+-- directory." The transactional index creation lives in
+-- 20260708170000_ingestion_jobs_one_open_per_document.sql; on live, prefer the
+-- lock-free CONCURRENTLY path in docs/operator-apply-july8-batch.md when the
+-- queue is idle, then repair history to match effect.
+
+select 1 where false;
diff --git a/supabase/migrations/20260708170000_ingestion_jobs_one_open_per_document.sql b/supabase/migrations/20260708170000_ingestion_jobs_one_open_per_document.sql
index 62c04a6f3..3ad593350 100644
--- a/supabase/migrations/20260708170000_ingestion_jobs_one_open_per_document.sql
+++ b/supabase/migrations/20260708170000_ingestion_jobs_one_open_per_document.sql
@@ -5,9 +5,9 @@
 -- which is a check-then-act race. This index makes the invariant structural.
 --
 -- Uses a transactional CREATE UNIQUE INDEX (not CONCURRENTLY) so `supabase db
--- push` can apply it with the rest of the July 8 batch. This version is
--- intentionally separate from 20260708160000_retrieval_owner_matches_fail_closed
--- so migration history/repair cannot collide on the same timestamp.
+-- push` and Supabase Preview replay can apply it inside a transaction. Stem
+-- 20260708160000 is a neutralized no-op retained for preview history parity;
+-- this migration carries the actual index DDL.
 --
 -- Before applying on live, confirm `npm run reindex:health` reports
 -- jobs_pending = 0 and jobs_processing = 0 (live had 0/0 as of 2026-07-08).
diff --git a/tests/supabase-schema.test.ts b/tests/supabase-schema.test.ts
index fe9c25716..a9d11ee86 100644
--- a/tests/supabase-schema.test.ts
+++ b/tests/supabase-schema.test.ts
@@ -46,6 +46,14 @@ const retrievalOwnerFilterSentinelMigration = readFileSync(
   new URL("../supabase/migrations/20260705210000_retrieval_owner_filter_sentinel.sql", import.meta.url),
   "utf8",
 ).replace(/\s+/g, " ");
+const ingestionJobsOneOpenNeutralizedMigration = readFileSync(
+  new URL("../supabase/migrations/20260708160000_ingestion_jobs_one_open_per_document.sql", import.meta.url),
+  "utf8",
+).replace(/\s+/g, " ");
+const ingestionJobsOneOpenMigration = readFileSync(
+  new URL("../supabase/migrations/20260708170000_ingestion_jobs_one_open_per_document.sql", import.meta.url),
+  "utf8",
+).replace(/\s+/g, " ");
 const atomicReindexMigration = readFileSync(
   new URL("../supabase/migrations/20260628000000_atomic_reindex_generation_commit.sql", import.meta.url),
   "utf8",
@@ -461,6 +469,7 @@ describe("Supabase schema Data API grants", () => {
       ["audit_logs", 2],
       ["audit_logs_service_role_policy", 2],
       ["indexing_reliability_recovery", 2],
+      ["ingestion_jobs_one_open_per_document", 2],
       ["rag_queries_retention", 2],
     ]);
     const stemCounts = new Map<string, number>();
@@ -889,4 +898,12 @@ describe("Supabase Preview replay guards", () => {
     }
     expect(ragQueriesRetentionDuplicateMigration).toMatch(/select 1;/);
   });
+
+  it("keeps ingestion_jobs_one_open stem neutralized for preview history parity", () => {
+    expect(ingestionJobsOneOpenNeutralizedMigration).toContain("NEUTRALIZED 2026-07-09");
+    expect(ingestionJobsOneOpenNeutralizedMigration).toContain("select 1 where false;");
+    expect(ingestionJobsOneOpenNeutralizedMigration).not.toContain("concurrently");
+    expect(ingestionJobsOneOpenMigration).toContain("ingestion_jobs_one_open_per_document_uidx");
+    expect(ingestionJobsOneOpenMigration).not.toContain("concurrently");
+  });
 });

From e1b5407e17157259a03720ea5c88cb3b4f15713b Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 17:19:11 +0800
Subject: [PATCH 13/16] ci: keep supabase cache save non-blocking

---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 44f687a6b..57d70370b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -174,6 +174,7 @@ jobs:
 
       - name: Save Supabase Docker images
         if: always()
+        continue-on-error: true
         run: |
           mkdir -p /tmp/supabase-docker-cache
           docker images --format '{{.Repository}}:{{.Tag}}' \

From 93c70e314b0f4c853c179c3572f8d7c66a54cfb7 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 9 Jul 2026 09:22:20 +0000
Subject: [PATCH 14/16] ci: run migration verification before docker image
 cache save

---
 .github/workflows/ci.yml | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 57d70370b..c5b46b981 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -172,6 +172,9 @@ jobs:
       - name: Start Supabase Local Emulator
         run: supabase start
 
+      - name: Verify Migration Replay
+        run: supabase db reset
+
       - name: Save Supabase Docker images
         if: always()
         continue-on-error: true
@@ -182,9 +185,6 @@ jobs:
             | sort -u \
             | xargs -r docker save -o /tmp/supabase-docker-cache/images.tar
 
-      - name: Verify Migration Replay
-        run: supabase db reset
-
   release-browser-matrix:
     if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule' || github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/heads/release/')
     needs: [verify, ui-smoke, db-reset-verify]

From c42484507f0e78330d2a95218fbb90bafea37e72 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 17:29:57 +0800
Subject: [PATCH 15/16] fix: address registry corpus review comments

---
 src/lib/differential-seed.ts     |  6 +++-
 src/lib/medication-seed.ts       |  7 +++-
 src/lib/registry-corpus-links.ts |  5 +--
 src/lib/registry-seed.ts         |  7 +++-
 src/lib/universal-search.ts      | 13 ++++++-
 tests/registry-corpus.test.ts    |  4 +--
 tests/universal-search.test.ts   | 60 ++++++++++++++++++++++++++++++++
 7 files changed, 92 insertions(+), 10 deletions(-)

diff --git a/src/lib/differential-seed.ts b/src/lib/differential-seed.ts
index 10d21cbf1..521778143 100644
--- a/src/lib/differential-seed.ts
+++ b/src/lib/differential-seed.ts
@@ -1,9 +1,12 @@
 import { buildDefaultDifferentialRows } from "@/lib/differential-fixtures";
 import { type DifferentialRecordInsert, type DifferentialRecordRow } from "@/lib/differential-records";
-import { embedDifferentialRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 
 type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
 
+function loadRegistryCorpus() {
+  return import("@/lib/registry-corpus");
+}
+
 export { loadDifferentialSnapshot } from "@/lib/differential-fixtures";
 
 export async function ensureDifferentialsSeeded(
@@ -17,6 +20,7 @@ export async function ensureDifferentialsSeeded(
     .select("*");
   if (error) throw new Error(`Differential seed failed: ${error.message}`);
   const seededRows = (data ?? []) as DifferentialRecordRow[];
+  const { embedDifferentialRows, registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
   if (registryCorpusEmbeddingEnabled()) {
     await embedDifferentialRows(supabase, seededRows);
   }
diff --git a/src/lib/medication-seed.ts b/src/lib/medication-seed.ts
index 97f294a53..d040e91a0 100644
--- a/src/lib/medication-seed.ts
+++ b/src/lib/medication-seed.ts
@@ -1,9 +1,12 @@
 import { buildDefaultMedicationRows, defaultMedicationRecords } from "@/lib/medication-fixtures";
-import { embedMedicationRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { type MedicationRecordInsert, type MedicationRecordRow } from "@/lib/medication-records";
 
 type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
 
+function loadRegistryCorpus() {
+  return import("@/lib/registry-corpus");
+}
+
 export function buildMedicationSeedRows(ownerId: string): MedicationRecordInsert[] {
   return buildDefaultMedicationRows(ownerId);
 }
@@ -16,6 +19,7 @@ export async function ensureMedicationsSeeded(supabase: AdminClient, ownerId: st
     .select("*");
   if (error) throw new Error(`Medication seed failed: ${error.message}`);
   const seededRows = (data ?? []) as MedicationRecordRow[];
+  const { embedMedicationRows, registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
   if (registryCorpusEmbeddingEnabled()) {
     await embedMedicationRows(supabase, seededRows);
   }
@@ -51,6 +55,7 @@ export async function fetchOwnerMedicationRowsWithSeed(
       await ensureMedicationsSeeded(supabase, ownerId);
     } catch (seedError) {
       console.error(`[medications] auto-seed failed for owner ${ownerId}`, seedError);
+      const { registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
       if (registryCorpusEmbeddingEnabled()) throw seedError;
     }
     rows = await fetchRecords();
diff --git a/src/lib/registry-corpus-links.ts b/src/lib/registry-corpus-links.ts
index 3fa5da396..57bc47d17 100644
--- a/src/lib/registry-corpus-links.ts
+++ b/src/lib/registry-corpus-links.ts
@@ -7,15 +7,12 @@ export function registryCorpusDetailHref(args: {
   const kind = typeof args.kind === "string" ? args.kind : null;
   const slug = typeof args.slug === "string" ? args.slug : null;
   const subkind = typeof args.subkind === "string" ? args.subkind : null;
-  const recordId = typeof args.recordId === "string" ? args.recordId : null;
   if (!kind || !slug) return null;
   if (kind === "service") return `/services/${slug}`;
   if (kind === "form") return `/forms/${slug}`;
   if (kind === "medication") return `/medications/${slug}`;
   if (kind === "differential") {
-    return subkind === "presentation" && recordId
-      ? `/differentials/presentations/${recordId}`
-      : `/differentials/diagnoses/${slug}`;
+    return subkind === "presentation" ? `/differentials/presentations/${slug}` : `/differentials/diagnoses/${slug}`;
   }
   return null;
 }
diff --git a/src/lib/registry-seed.ts b/src/lib/registry-seed.ts
index 5aec60940..1649ed81e 100644
--- a/src/lib/registry-seed.ts
+++ b/src/lib/registry-seed.ts
@@ -1,6 +1,5 @@
 import { formRecords } from "@/lib/forms";
 import { buildDefaultFormRows, buildDefaultServiceRows, defaultServiceRecords } from "@/lib/registry-fixtures";
-import { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } from "@/lib/registry-corpus";
 import { type RegistryRecordInsert, type RegistryRecordKind, type RegistryRecordRow } from "@/lib/registry-records";
 
 // Type-only reference to the admin client so this module carries no runtime
@@ -9,6 +8,10 @@ import { type RegistryRecordInsert, type RegistryRecordKind, type RegistryRecord
 // client into `ensureRegistrySeeded`.
 type AdminClient = ReturnType<typeof import("@/lib/supabase/admin").createAdminClient>;
 
+function loadRegistryCorpus() {
+  return import("@/lib/registry-corpus");
+}
+
 /** The curated default registry fixtures for a kind — the same set the CLI
  *  seeds and the API falls back to when an owner has no records yet. */
 export function defaultRegistryRecords(kind: RegistryRecordKind) {
@@ -44,6 +47,7 @@ export async function ensureRegistrySeeded(
     .select("*");
   if (error) throw new Error(`Registry seed failed: ${error.message}`);
   const seededRows = (data ?? []) as RegistryRecordRow[];
+  const { embedClinicalRegistryRows, registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
   if (registryCorpusEmbeddingEnabled()) {
     await embedClinicalRegistryRows(supabase, seededRows);
   }
@@ -81,6 +85,7 @@ export async function fetchOwnerRegistryRowsWithSeed(
       await ensureRegistrySeeded(supabase, ownerId, kind);
     } catch (seedError) {
       console.error(`[registry] auto-seed failed for owner ${ownerId} (${kind})`, seedError);
+      const { registryCorpusEmbeddingEnabled } = await loadRegistryCorpus();
       if (registryCorpusEmbeddingEnabled()) throw seedError;
     }
     rows = await fetchRecords();
diff --git a/src/lib/universal-search.ts b/src/lib/universal-search.ts
index 1e774709a..2a598efc6 100644
--- a/src/lib/universal-search.ts
+++ b/src/lib/universal-search.ts
@@ -266,6 +266,16 @@ function documentItemsFromChunks(results: SearchResult[], limit: number): Univer
     .slice(0, limit);
 }
 
+function documentHrefMapFromChunks(results: SearchResult[]) {
+  const hrefByDocument = new Map<string, string>();
+  for (const result of results) {
+    if (!hrefByDocument.has(result.document_id)) {
+      hrefByDocument.set(result.document_id, searchResultDocumentHref(result));
+    }
+  }
+  return hrefByDocument;
+}
+
 async function searchDocumentsDomain(args: ResolvedSearchArgs): Promise<UniversalSearchItem[]> {
   // Original query on purpose: the live retrieval path runs its own analyzeClinicalQuery.
   if (args.demo || !args.supabase) {
@@ -284,6 +294,7 @@ async function searchDocumentsDomain(args: ResolvedSearchArgs): Promise<Universa
     // still embed. Owner scoping and public-corpus behavior are unchanged (handled downstream).
     lexicalOnly: true,
   });
+  const hrefByDocument = documentHrefMapFromChunks(results);
   const related = await fetchRelatedDocuments({
     supabase: args.supabase,
     ownerId: args.ownerId,
@@ -297,7 +308,7 @@ async function searchDocumentsDomain(args: ResolvedSearchArgs): Promise<Universa
       kind: "documents" as const,
       title: document.title,
       subtitle: document.summary ?? undefined,
-      href: `/documents/${document.document_id}`,
+      href: hrefByDocument.get(document.document_id) ?? `/documents/${document.document_id}`,
       score: document.score,
       meta: document.match_reason,
     }));
diff --git a/tests/registry-corpus.test.ts b/tests/registry-corpus.test.ts
index 86442d696..71250ca36 100644
--- a/tests/registry-corpus.test.ts
+++ b/tests/registry-corpus.test.ts
@@ -88,10 +88,10 @@ describe("registry corpus", () => {
     expect(
       registryCorpusDetailHref({
         kind: "differential",
-        slug: "psychosis",
+        slug: "first-episode-psychosis",
         subkind: "presentation",
         recordId: "44444444-4444-4444-8444-444444444444",
       }),
-    ).toBe("/differentials/presentations/44444444-4444-4444-8444-444444444444");
+    ).toBe("/differentials/presentations/first-episode-psychosis");
   });
 });
diff --git a/tests/universal-search.test.ts b/tests/universal-search.test.ts
index d7bfab3ba..26aaec340 100644
--- a/tests/universal-search.test.ts
+++ b/tests/universal-search.test.ts
@@ -85,6 +85,66 @@ describe("runUniversalSearch (demo/fixtures path)", () => {
     expect(documents?.items.length ?? 0).toBeGreaterThan(0);
     expect(documents?.items[0]?.href).toContain("/documents/");
   });
+
+  it("keeps registry hrefs when document search uses related-document mapping", async () => {
+    vi.doMock("@/lib/rag", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("../src/lib/rag")>();
+      return {
+        ...actual,
+        searchChunksWithTelemetry: vi.fn(async () => ({
+          results: [
+            {
+              id: "registry-chunk",
+              document_id: "registry-doc",
+              title: "Crisis service",
+              file_name: "service-crisis-service.registry.json",
+              page_number: 1,
+              hybrid_score: 0.92,
+              similarity: 0.9,
+              images: [],
+              source_metadata: {
+                source_kind: "registry_record",
+                registry_record_kind: "service",
+                registry_record_slug: "crisis-service",
+              },
+            },
+          ],
+        })),
+      };
+    });
+    vi.doMock("@/lib/document-enrichment", async (importOriginal) => {
+      const actual = await importOriginal<typeof import("../src/lib/document-enrichment")>();
+      return {
+        ...actual,
+        fetchRelatedDocuments: vi.fn(async () => [
+          {
+            document_id: "registry-doc",
+            title: "Crisis service",
+            file_name: "service-crisis-service.registry.json",
+            labels: [],
+            summary: null,
+            best_pages: [1],
+            best_chunk_ids: ["registry-chunk"],
+            image_count: 0,
+            table_count: 0,
+            match_reason: "Matched 1 indexed passage",
+            score: 0.92,
+          },
+        ]),
+      };
+    });
+
+    const { runUniversalSearch } = await loadUniversalSearch();
+    const response = await runUniversalSearch({
+      query: "crisis service",
+      limitPerDomain: 5,
+      domains: ["documents"],
+      demo: false,
+      supabase: {} as Parameters<typeof runUniversalSearch>[0]["supabase"],
+    });
+
+    expect(response.groups[0]?.items[0]?.href).toBe("/services/crisis-service");
+  });
 });
 
 describe("GET /api/search/universal (demo mode)", () => {

From 72b5b17964907c5cee1583d30b3d6b0cea875559 Mon Sep 17 00:00:00 2001
From: BigSimmo <87357024+BigSimmo@users.noreply.github.com>
Date: Thu, 9 Jul 2026 17:42:57 +0800
Subject: [PATCH 16/16] docs: clarify required PR check setup

---
 .github/workflows/ci.yml  | 10 ++++++----
 README.md                 |  9 +++++++--
 docs/process-hardening.md | 10 +++++-----
 3 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index c5b46b981..40f2dc678 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -23,7 +23,8 @@ env:
 
 jobs:
   # Fast deterministic merge gate: static checks, unit tests, and build.
-  # Intended as a required status check on main together with ui-smoke.
+  # Intended as a required status check on main together with ui-smoke,
+  # Gitleaks, and one migration replay gate.
   verify:
     runs-on: ubuntu-latest
     timeout-minutes: 25
@@ -137,9 +138,10 @@ jobs:
             playwright-report/
           if-no-files-found: ignore
 
-  # Database migration replay in parallel with verify and ui-smoke, so we verify
-  # that our schema and migration chain can rebuild cleanly from scratch on
-  # every PR.
+  # Database migration replay in parallel with verify and ui-smoke. This is the
+  # repo-owned replay gate; if the external Supabase Preview check is already
+  # required and reliable, keep this advisory or path-filtered rather than
+  # requiring both replay gates on every PR.
   db-reset-verify:
     runs-on: ubuntu-latest
     timeout-minutes: 15
diff --git a/README.md b/README.md
index a1da1c115..924157799 100644
--- a/README.md
+++ b/README.md
@@ -183,8 +183,13 @@ npm run verify:release # check:runtime + lint + typecheck + test + build + test:
 ```
 
 CI runs `format:check` in the `verify` job alongside lint, typecheck,
-test:coverage, build, and edge-function typecheck. PRs also run the Chromium
-`ui-smoke` job in parallel.
+test:coverage, build, dependency audit, production-readiness CI mode, and
+edge-function typecheck. PRs also run Chromium `ui-smoke` and the repo-owned
+Supabase `db-reset-verify` job in parallel. The external `Supabase Preview`
+check, when enabled, is the branch-database migration replay gate. Docker image
+builds, full browser matrix, live drift, and live eval canary checks are
+path-filtered, scheduled, or manual rather than normal required checks for every
+source-only PR.
 
 ```bash
 npm run dev       # Next.js UI/API on this project's stable localhost port
diff --git a/docs/process-hardening.md b/docs/process-hardening.md
index 67c8b5f9d..1043f28e3 100644
--- a/docs/process-hardening.md
+++ b/docs/process-hardening.md
@@ -7,7 +7,7 @@ This document turns the current process review into phased, durable repo practic
 - `npm run verify:cheap` is the default broad local gate for source/config/test changes: `check:runtime`, `sitemap:check`, lint, typecheck, and unit tests.
 - `npm run verify:ui` is the default UI gate: `check:runtime` plus Chromium Playwright smoke, stress, and accessibility media checks (`test:e2e:chromium`).
 - `npm run verify:release` is the release-confidence gate: `check:runtime`, lint, typecheck, unit tests, build, full Playwright browser matrix, `check:production-readiness`, `governance:release`, and `eval:quality:release` (the last step needs live Supabase and OpenAI keys).
-- CI runs two parallel PR jobs: `verify` (runtime alignment, edge-function typecheck, CI-safe production readiness, `format:check`, lint, typecheck, unit tests with coverage, build) and `ui-smoke` (Chromium Playwright against its own dev server). A gated `release-browser-matrix` job runs the full Playwright browser set on `main`, `release/*`, manual dispatch, and the weekly schedule.
+- CI runs three parallel PR jobs in the `CI` workflow: `verify` (runtime alignment, dependency vulnerability audit, edge-function typecheck, CI-safe production readiness, `format:check`, lint, typecheck, unit tests with coverage, build), `ui-smoke` (Chromium Playwright against its own dev server), and `db-reset-verify` (Supabase local start plus `supabase db reset` migration replay). The external `Supabase Preview` check also replays the migration chain on branch databases when enabled. A gated `release-browser-matrix` job runs the full Playwright browser set on `main`, `release/*`, manual dispatch, and the weekly schedule.
 - `tests/ui-accessibility.spec.ts` covers reduced-motion and forced-colors dashboard usability so those modes are no longer only reviewed by inspection.
 - `tests/ui-tools.spec.ts` covers the Applications dashboard mode at mobile and desktop sizes, including the `/applications` compatibility redirect.
 - `AGENTS.md` now points future agents to these gates and to this document.
@@ -130,10 +130,10 @@ passes `p_worker_id`. Ordered apply steps, R17 manual `CONCURRENTLY` index, and
 
 ## PR merge gate: tiered CI + required checks (2026-07-02)
 
-- CI is now two parallel PR jobs instead of one serial 6-7 minute job: `verify` (runtime alignment, edge typecheck, CI-safe production readiness, lint, typecheck, unit tests with coverage gate, build — ~3 min) and `ui-smoke` (Chromium Playwright smoke against its own dev server — ~4.5 min). Wall-clock PR feedback drops to the slower of the two, and a flaky smoke rerun no longer repeats lint/typecheck/tests/build.
-- The deployment boot smoke and full browser matrix remain gated to `main`, `release/*`, manual dispatch, and the weekly schedule — they are deliberately not PR gates.
-- **Required-check debt: RESOLVED 2026-07-02.** Branch protection is now applied on `main` requiring `verify`, `ui-smoke`, and `Gitleaks`, with "require branches up to date" left OFF (strict up-to-dateness would force constant rebases across the many concurrent agent branches), `enforce_admins` OFF (admin bypass retained as an emergency hatch), and no required PR-review count (a solo+agents flow has no second human approver). This closes the gap that let #131/#133 merge red. Consequence now in effect: **direct pushes to `main` are blocked for non-bypass users; normal work must land via PR.** Repository admins can still use the retained bypass only as an emergency hatch. To adjust, edit the rule under repo Settings → Branches or via `gh api -X PUT repos/BigSimmo/Database/branches/main/protection`.
-- If `ui-smoke` proves flaky as a required check, demote it to advisory (remove from required contexts) rather than tolerating red merges — the deterministic `verify` gate stays required regardless.
+- CI is now three parallel PR jobs instead of one serial 6-7 minute job: `verify` (runtime alignment, production dependency audit, edge typecheck, CI-safe production readiness, format, lint, typecheck, unit tests with coverage gate, build), `ui-smoke` (Chromium Playwright smoke against its own dev server), and `db-reset-verify` (local Supabase migration replay). Wall-clock PR feedback drops to the slowest independent gate, and a flaky smoke rerun no longer repeats lint/typecheck/tests/build.
+- The deployment boot smoke, full browser matrix, live drift check, live eval canary, and Docker image builds remain gated, scheduled, manual, or path-filtered — they are deliberately not normal required checks for every source-only PR.
+- **Required-check debt: RESOLVED 2026-07-02; updated 2026-07-09.** Branch protection for `main` should require the exact active check contexts for `CI / verify`, `CI / ui-smoke`, `Secret Scan / Gitleaks`, and one migration replay gate. Prefer the external `Supabase Preview` check when it is enabled and reliable; otherwise require `CI / db-reset-verify`. Requiring both replay gates is conservative but usually redundant. Keep `SAST / Semgrep` required only if the repository owner accepts its external-rule/network dependency as part of the normal merge gate. Do not require path-filtered or scheduled/manual contexts such as `Docker image build / app-image`, `Docker image build / worker-image`, `CI / release-browser-matrix`, `Eval Canary`, or `Live drift check`; they can be absent on ordinary PRs and would leave branches stuck at "Expected - Waiting for status to be reported." Keep "require branches up to date" OFF unless the branch flow changes, keep `enforce_admins` OFF only as an emergency bypass decision, and avoid requiring duplicate legacy contexts named only `verify` or `ui-smoke` when GitHub already reports the active `CI / ...` contexts.
+- If `ui-smoke` proves flaky as a required check, demote it to advisory (remove from required contexts) rather than tolerating red merges — the deterministic `verify` gate stays required regardless. If `db-reset-verify` becomes the bottleneck, path-filter it to Supabase migrations/schema/config and database-access code before demoting it entirely.
 
 ## CSS cascade layering (2026-07-02)