172 proper docs site

.clauderc

@@ -33,27 +33,38 @@ Do not worry about migrations either client side or backend unless specifically
 
 ## Libraries
 
-Use Zod for schema and input validation.
+Use Zod for schema and input validation (backend).
 Use Drizzle ORM for database interactions and migrations.
 Use Better-Auth for authentication and user management.
-Use Zag.js for UI components and design system.
+Use Ark UI components from `@corates/ui` package (built with Ark UI and some remaining Zag.js components).
 
 ## Documentation Tool
 
-PLEASE USE THE CORATES MCP tools to explore local documentation sources. Use this MCP for all Better-Auth, Drizzle, Icons, and Zag documentation.
+PLEASE USE THE CORATES MCP tools to explore local documentation sources. Use this MCP for all Better-Auth, Drizzle, Icons, and Ark UI documentation. For comprehensive development guides, see the docs site (`packages/docs/`) - run `pnpm docs` to view.
 
-## Zag.js
+## UI Components
 
-Zag component exist in `packages/web/src/components/zag/*` and should be reused, see the README.md in that folder for a list of existing components. BE SURE TO CHECK THAT LIST AND REFERENCE EXISTING COMPONENTS AS WELL AS THE DOCS MCP BEFORE ADDING NEW COMPONENTS AND WHEN DEBUGGING.
+UI components are in `@corates/ui` package, built with Ark UI (and some remaining Zag.js components). NOT in local components.
+
+```js
+// CORRECT - Import from @corates/ui
+import { Dialog, Select, Toast, showToast, Avatar } from '@corates/ui';
+
+// WRONG - Don't import from local components
+import { Dialog } from '@/components/zag/Dialog.jsx';
+```
+
+See `packages/ui/src/components/index.ts` for all available components. Most components have been migrated to Ark UI. Common ones include Dialog, Select, Toast, Avatar, Tabs, Checkbox, Switch, RadioGroup, Tooltip, Popover, Menu, FileUpload, PasswordInput, and more.
 
 ## Additional References
 
-- The style-guide.md file contains additional style and formatting guidelines.
+- The [Style Guide](/guides/style-guide) in the docs site contains additional style and formatting guidelines.
 - See vite.config.js or jsconfig.json for path aliases and build configurations.
-- See TESTING.md for testing guidelines and best practices, do NOT add tests unless asked.
+- See the [Testing Guide](/guides/testing) in the docs site for testing guidelines and best practices, do NOT add tests unless asked.
 - Cloudflare Pages is not used in this project; only Cloudflare Workers is used for backend services and frontend deployments.
 - This project is split into multiple packages under the `packages/` directory. Each package may have its own dependencies and configurations. The landing/marketing site, the main app, and the backend services.
 - Use the Corates MCP for documentation.
+- For comprehensive documentation, see the docs site (`packages/docs/`) - run `pnpm docs` to view guides.
 
 ## Database Migrations
 

.cursor/rules/api-routes.mdc

@@ -6,6 +6,9 @@ globs: packages/workers/**
 
 # API Route Patterns
 
+> **For comprehensive API development patterns**, see the [API Development Guide](/guides/api-development) in the docs site.
+> This file provides quick reference patterns for AI agents.
+
 ## Request Validation
 
 **ALWAYS use `validateRequest` middleware** for request body validation:
@@ -212,3 +215,9 @@ See these files for reference:
 - `packages/workers/src/routes/members.js` - Validation, error handling
 - `packages/workers/src/routes/account-merge.js` - Complex batch operations
 - `packages/workers/src/config/validation.js` - Schema definitions
+
+## Related Documentation
+
+- [API Development Guide](/guides/api-development) - Comprehensive API development patterns
+- [Database Guide](/guides/database) - Drizzle ORM patterns and batch operations
+- [Error Handling Guide](/guides/error-handling) - Error handling patterns

.cursor/rules/checklist-operations.mdc

@@ -0,0 +1,275 @@
+---
+alwaysApply: false
+description: "Checklist-specific patterns for AMSTAR2, ROBINS-I, and checklist operations"
+globs: packages/web/src/components/checklist-ui/**, packages/web/src/AMSTAR2/**, packages/web/src/ROBINS-I/**, packages/web/src/lib/checklist-domain.js
+---
+
+# Checklist Operations Patterns
+
+> This file provides quick reference patterns for AI agents working with checklist operations.
+
+## Checklist Types
+
+### Supported Checklists
+
+- **AMSTAR2**: 16-question quality assessment
+- **ROBINS-I**: Risk of bias assessment
+- **Generic**: Framework for custom checklists
+
+### Checklist Registry
+
+Checklists are registered in `checklist-registry`:
+
+```js
+import { getChecklistType, getChecklistComponent } from '@/checklist-registry';
+
+const type = getChecklistType(checklistId);
+const Component = getChecklistComponent(type);
+```
+
+## Checklist Structure
+
+### Checklist Data Model
+
+```js
+{
+  id: 'uuid',
+  type: 'AMSTAR2' | 'ROBINS-I' | 'Generic',
+  title: 'Checklist Title',
+  assignedTo: userId,
+  status: 'in_progress' | 'completed' | 'reconciled',
+  createdAt: timestamp,
+  updatedAt: timestamp,
+  answers: {
+    // Question key => answer data
+    q1: { answers: [[...]], critical: boolean },
+    q2: { answers: [[...]], critical: boolean },
+    // ...
+  }
+}
+```
+
+### Answer Structure
+
+Answers vary by checklist type:
+
+```js
+// AMSTAR2 answer structure
+{
+  answers: [
+    [true, false, false], // Column 1 options
+    [false, true, false], // Column 2 options
+    // ...
+  ],
+  critical: boolean // Whether question is critical
+}
+
+// ROBINS-I answer structure
+{
+  answer: 'Y' | 'PY' | 'PN' | 'N' | 'NI' | 'NA',
+  comment: string // Optional comment
+}
+```
+
+## Checklist Operations
+
+### Creating Checklists
+
+Use `createChecklist` operation:
+
+```js
+const { createChecklist } = useProject(projectId);
+
+const checklist = await createChecklist(studyId, {
+  type: 'AMSTAR2',
+  title: 'Reviewer 1 Assessment',
+  assignedTo: userId,
+});
+```
+
+### Updating Checklist Answers
+
+Use `updateChecklistAnswer` operation:
+
+```js
+const { updateChecklistAnswer } = useProject(projectId);
+
+await updateChecklistAnswer(studyId, checklistId, 'q1', {
+  answers: [[true, false], [false, true]],
+  critical: false,
+});
+```
+
+### Getting Checklist Data
+
+Use `getChecklistData` operation:
+
+```js
+const { getChecklistData } = useProject(projectId);
+
+const checklist = getChecklistData(studyId, checklistId);
+// Returns full checklist with answers
+```
+
+## AMSTAR2 Specific
+
+### Question Structure
+
+AMSTAR2 has 16 questions, some with parts:
+
+- q1-q8: Single-part questions
+- q9: Multi-part (q9a, q9b)
+- q10: Single-part
+- q11: Multi-part (q11a, q11b)
+- q12-q16: Single-part questions
+
+### Answer Matrix
+
+AMSTAR2 uses answer matrices:
+
+```js
+// Each question has columns (e.g., "Yes", "Partial Yes", "No", "No Meta-analysis")
+// Each column has options (checkboxes)
+answers: [
+  [true, false, false],  // Column 1: Yes selected
+  [false, true, false],  // Column 2: Partial Yes selected
+  [false, false, true],  // Column 3: No selected
+]
+```
+
+### Scoring
+
+Use `scoreChecklist` utility:
+
+```js
+import { scoreChecklist } from '@/AMSTAR2/checklist.js';
+
+const score = scoreChecklist(checklist.answers);
+// Returns: 'High' | 'Moderate' | 'Low' | 'Critically Low'
+```
+
+## ROBINS-I Specific
+
+### Section Structure
+
+ROBINS-I has sections:
+
+- **Section B**: Pre-assessment (decide whether to proceed)
+- **Domains**: D1-D7 (risk of bias domains)
+
+### Section B
+
+Section B determines if assessment should stop:
+
+```js
+import { shouldStopAssessment } from '@/ROBINS-I/checklist.js';
+
+const stop = shouldStopAssessment(sectionBState);
+// If true, assessment should stop (critical risk of bias)
+```
+
+### Domain Judgements
+
+Each domain has a judgement:
+
+```js
+// Domain judgement options
+'Low' | 'Moderate' | 'Serious' | 'Critical' | 'No Information'
+
+// Get domain judgement
+const judgement = domain.judgement;
+```
+
+### Scoring
+
+Use `scoreChecklist` utility:
+
+```js
+import { scoreChecklist } from '@/ROBINS-I/checklist.js';
+
+const score = scoreChecklist(checklistState);
+// Returns: 'Low' | 'Moderate' | 'Serious' | 'Critical'
+```
+
+## Checklist Status
+
+### Status Values
+
+```js
+const CHECKLIST_STATUS = {
+  IN_PROGRESS: 'in_progress',
+  COMPLETED: 'completed',
+  RECONCILED: 'reconciled',
+};
+```
+
+### Status Transitions
+
+- `in_progress` → `completed`: When all questions answered
+- `completed` → `reconciled`: When reconciliation is complete
+
+### Checking Status
+
+Use `getChecklistStatus` utility:
+
+```js
+import { getChecklistStatus } from '@/lib/checklist-domain.js';
+
+const status = getChecklistStatus(checklist);
+```
+
+## Checklist Notes
+
+### Question Notes
+
+Each question can have notes (Y.Text for collaborative editing):
+
+```js
+const { getQuestionNote } = useProject(projectId);
+
+const note = getQuestionNote(studyId, checklistId, questionKey);
+// Returns: Y.Text object
+```
+
+### Note Editor Component
+
+Use `NoteEditor` component:
+
+```jsx
+import NoteEditor from '@/components/checklist-ui/common/NoteEditor.jsx';
+
+<NoteEditor
+  yText={note}
+  readOnly={false}
+  collapsed={false}
+  maxLength={2000}
+/>
+```
+
+## Best Practices
+
+### DO
+
+- Use checklist operations from useProject
+- Handle multi-part questions correctly (q9, q11)
+- Use scoring utilities for AMSTAR2/ROBINS-I
+- Check checklist status before operations
+- Use NoteEditor for question notes
+- Store answers in correct format for checklist type
+
+### DON'T
+
+- Don't manually update checklist structure
+- Don't mix answer formats between checklist types
+- Don't forget to handle multi-part questions
+- Don't bypass checklist operations
+- Don't store notes outside of Y.Text
+
+## Examples from Codebase
+
+- `packages/web/src/components/checklist-ui/AMSTAR2Checklist.jsx` - AMSTAR2 checklist component
+- `packages/web/src/components/checklist-ui/ROBINSIChecklist/ROBINSIChecklist.jsx` - ROBINS-I checklist component
+- `packages/web/src/lib/checklist-domain.js` - Checklist utilities
+- `packages/web/src/AMSTAR2/checklist.js` - AMSTAR2 scoring logic
+- `packages/web/src/ROBINS-I/checklist.js` - ROBINS-I scoring logic
+- `packages/web/src/primitives/useProject/checklists.js` - Checklist operations

.cursor/rules/corates.mdc

@@ -18,6 +18,7 @@ The project is split into multiple packages under the `packages/` directory:
 - `/ui`: Shared UI component library built with Ark UI
 - `/shared`: Shared TypeScript utilities and error definitions
 - `/mcp`: MCP server for development tools and documentation
+- `/docs`: Vitepress docs site containing internal documentation
 
 The web package is copied into the landing package during build and deployed as a single site on one worker.
 
@@ -112,10 +113,20 @@ See `solidjs.mdc` for detailed reactivity patterns and examples.
 
 ## Documentation
 
+- **Primary source**: Comprehensive guides are in the docs site (`packages/docs/`) - run `pnpm docs` to view
 - **ALWAYS use Corates MCP tools or other MCP** for Better-Auth, Drizzle, Icons, linting, and Ark UI documentation
-- Reference `style-guide.md` for UI styling guidelines
-- Reference `docs/error-handling-guide.md` for error handling patterns
-- See `TESTING.md` for testing guidelines (do NOT add tests unless asked)
+- **For comprehensive documentation**, see the docs site guides:
+  - [Testing Guide](/guides/testing) - Frontend and backend testing patterns, setup, and best practices
+  - [Authentication Guide](/guides/authentication) - Setup, configuration, API endpoints, and usage patterns
+  - [Database Guide](/guides/database) - Schema management, Drizzle ORM patterns, migrations, and test helpers
+  - [State Management](/guides/state-management) - SolidJS store patterns
+  - [Primitives](/guides/primitives) - Reusable hooks and primitives
+  - [Components](/guides/components) - Component development patterns
+  - [API Development](/guides/api-development) - Backend API route patterns
+  - [Error Handling](/guides/error-handling) - Error handling patterns
+  - [Style Guide](/guides/style-guide) - UI styling guidelines
+  - [Configuration](/guides/configuration) - Configuration files and environment variables
+  - [Development Workflow](/guides/development-workflow) - Getting started and common tasks
 
 ## Specialized Rule Files
 
@@ -126,6 +137,16 @@ For detailed patterns, see:
 - `ui-components.mdc` - UI component imports and usage
 - `workers.mdc` - Workers package specific patterns
 
+### Complex Area Rules
+
+For specific complex areas, see:
+- `yjs-sync.mdc` - Yjs synchronization, connection management, sync operations
+- `reconciliation.mdc` - Checklist reconciliation, multi-part questions, comparison logic
+- `pdf-handling.mdc` - PDF upload, caching, Google Drive integration
+- `form-state.mdc` - Form state persistence across OAuth redirects
+- `durable-objects.mdc` - Durable Objects patterns for Yjs and WebSocket handling
+- `checklist-operations.mdc` - Checklist-specific patterns (AMSTAR2, ROBINS-I)
+
 ## Additional Notes
 
 - Cloudflare Pages is NOT used; only Cloudflare Workers