chore: database schema reconciliation and pipeline review updates

.cursor/skills/accessibility-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+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.

.cursor/skills/ai-architecture-review/SKILL.md

@@ -0,0 +1,26 @@
+---
+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.

.cursor/skills/api-review/SKILL.md

@@ -0,0 +1,32 @@
+---
+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`).

.cursor/skills/code-quality-review/SKILL.md

@@ -0,0 +1,21 @@
+---
+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.

.cursor/skills/design-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+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.

.cursor/skills/frontend-architecture-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+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.

.cursor/skills/performance-review/SKILL.md

@@ -0,0 +1,20 @@
+---
+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.

.cursor/skills/release-readiness-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+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.

.cursor/skills/repo-auditor/SKILL.md

@@ -0,0 +1,16 @@
+---
+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.

.cursor/skills/security-review/SKILL.md

@@ -0,0 +1,22 @@
+---
+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.

.cursor/skills/supabase-postgres-best-practices/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [1.3.0](https://github.com/supabase/agent-skills/compare/v1.2.0...v1.3.0) (2026-06-05)
+
+### Documentation
+
+- 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)
+
+### 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))

.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
-- [ ] `mise run test` passes
+- [ ] `npm run test` passes

.cursor/skills/supabase-postgres-best-practices/references/security-rls-performance.md

@@ -29,23 +29,29 @@ 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` 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 (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
 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/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
-  using ((select is_team_member(team_id)));
+  using ((select private.is_team_member(team_id)));
 ```
 
 Always add indexes on columns used in RLS policies:

.cursor/skills/supabase/CHANGELOG.md

@@ -0,0 +1,31 @@
+# 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))