From 3270e3f8fec1c354159e0da6e60c5c36edc51911 Mon Sep 17 00:00:00 2001
From: Sean O'Connor <sean@soconnor.dev>
Date: Sun, 22 Mar 2026 18:11:42 -0400
Subject: [PATCH] docs: update documentation for forms system and role-based
 access

- Add forms system to README key features
- Update router/table counts to reflect new forms router
- Add forms section to quick-reference with types, templates, routes
- Clarify study-level user roles (owner/researcher/wizard/observer)
---
 docs/README.md          |  7 +++++--
 docs/quick-reference.md | 31 ++++++++++++++++++++++++-------
 2 files changed, 29 insertions(+), 9 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index 043a9cc..e976cde 100755
--- a/docs/README.md
+++ b/docs/README.md
@@ -76,18 +76,21 @@ docker compose up -d
 - **WebSocket Real-time**: Trial updates with auto-reconnect
 - **Plugin System**: Robot-agnostic via identifier lookup
 - **Docker NAO6**: Three-service ROS2 integration
+- **Forms System**: Consent forms, surveys, questionnaires with templates
+- **Role-based Access**: Owner, Researcher, Wizard, Observer permissions
 
 ## System Components
 
 ### Backend (src/server/)
-- `api/routers/` - 12 tRPC routers
-- `db/schema.ts` - Drizzle schema (31 tables)
+- `api/routers/` - 13 tRPC routers (studies, experiments, trials, participants, forms, etc.)
+- `db/schema.ts` - Drizzle schema (33 tables)
 - `services/trial-execution.ts` - Trial execution engine
 - `services/websocket-manager.ts` - Real-time connections
 
 ### Frontend (src/)
 - `app/` - Next.js App Router pages
 - `components/trials/wizard/` - Wizard interface
+- `components/trials/forms/` - Form builder and viewer
 - `hooks/useWebSocket.ts` - Real-time trial updates
 - `lib/ros/wizard-ros-service.ts` - Robot control
 
diff --git a/docs/quick-reference.md b/docs/quick-reference.md
index 82e1481..76d2ef1 100755
--- a/docs/quick-reference.md
+++ b/docs/quick-reference.md
@@ -29,11 +29,11 @@ bun dev
 Study → Experiment → Trial → Step → Action
 ```
 
-### User Roles
-- **Administrator**: Full system access
-- **Researcher**: Create studies, design experiments
-- **Wizard**: Execute trials, control robots
-- **Observer**: Read-only monitoring
+### User Roles (Study-level)
+- **Owner**: Full study control, manage members
+- **Researcher**: Design experiments, manage participants
+- **Wizard**: Execute trials, control robot during sessions
+- **Observer**: Read-only access to study data
 
 ### Plugin Identifier System
 - `identifier`: Machine-readable key (e.g., `nao6-ros2`)
@@ -50,8 +50,25 @@ Study → Experiment → Trial → Step → Action
 | `bun build` | Production build |
 | `bun typecheck` | TypeScript validation |
 | `bun db:push` | Push schema changes |
-| `bun db:seed` | Seed data + sync plugins |
-| `bun run docker:up` | Start PostgreSQL |
+| `bun db:seed` | Seed data + sync plugins + forms |
+| `bun run docker:up` | Start PostgreSQL + MinIO |
+
+## Forms System
+
+### Form Types
+- **Consent**: Legal/IRB consent documents with signature fields
+- **Survey**: Multi-question questionnaires (ratings, multiple choice)
+- **Questionnaire**: Custom data collection forms
+
+### Templates (seeded by default)
+- Informed Consent - Standard consent template
+- Post-Session Survey - Participant feedback form
+- Demographics - Basic demographic collection
+
+### Routes
+- `/studies/[id]/forms` - List forms
+- `/studies/[id]/forms/new` - Create form (from template or scratch)
+- `/studies/[id]/forms/[formId]` - View/edit form, preview, responses
 
 ---