docs: add REFERENCE docs, M4 workspace, Caddyfile

release/migrate_add_cut_id.sql

@@ -0,0 +1,15 @@
+-- Migration: Add cut_id column for per-cut trace scoping
+-- Date: 2026-05-16
+-- Usage: psql -U accusys -d momentry -f migrate_add_cut_id.sql
+-- Note: runs with current search_path
+
+ALTER TABLE face_detections ADD COLUMN IF NOT EXISTS cut_id INTEGER;
+
+-- Back-fill existing data where cuts exist
+UPDATE face_detections fd
+SET cut_id = c.id
+FROM chunk c
+WHERE c.file_uuid = fd.file_uuid
+  AND c.chunk_type = 'cut'
+  AND fd.frame_number BETWEEN c.start_frame AND c.end_frame
+  AND fd.cut_id IS NULL;

release/migrate_add_stranger_id.sql

@@ -0,0 +1,13 @@
+-- Migration: Add stranger_id column for unmatched face traces
+-- Unmatched traces get stranger_id = trace_id (per-file sequential integer)
+-- Unique constraint: (file_uuid, stranger_id) WHERE stranger_id IS NOT NULL
+-- Date: 2026-05-16
+-- Usage: psql -U accusys -d momentry -f migrate_add_stranger_id.sql
+
+ALTER TABLE face_detections ADD COLUMN IF NOT EXISTS stranger_id INTEGER;
+CREATE UNIQUE INDEX IF NOT EXISTS idx_face_detections_stranger
+    ON face_detections (file_uuid, stranger_id) WHERE stranger_id IS NOT NULL;
+
+-- Assign stranger_id = trace_id for existing unmatched traces
+UPDATE face_detections SET stranger_id = trace_id
+WHERE trace_id IS NOT NULL AND identity_id IS NULL AND stranger_id IS NULL;

release/migrate_create_cuts_table.sql

@@ -0,0 +1,38 @@
+-- Migration: Create independent cuts table
+-- Cut = 同鏡頭連續拍攝的一組 frame
+-- Date: 2026-05-16
+-- Usage: psql -U accusys -d momentry -f migrate_create_cuts_table.sql
+
+CREATE TABLE IF NOT EXISTS cuts (
+    id SERIAL PRIMARY KEY,
+    file_uuid VARCHAR(32) NOT NULL,
+    cut_number INTEGER NOT NULL,
+    start_frame BIGINT NOT NULL,
+    end_frame BIGINT NOT NULL,
+    start_time DOUBLE PRECISION,
+    end_time DOUBLE PRECISION,
+    fps DOUBLE PRECISION,
+    metadata JSONB DEFAULT '{}',
+    created_at TIMESTAMPTZ DEFAULT NOW(),
+    UNIQUE(file_uuid, cut_number)
+);
+
+-- Migrate from chunk (chunk_type='cut')
+INSERT INTO cuts (file_uuid, cut_number, start_frame, end_frame, start_time, end_time, fps, metadata)
+SELECT c.file_uuid, 
+       (c.content->>'scene_number')::int as cut_number,
+       c.start_frame, c.end_frame,
+       c.start_time, c.end_time,
+       c.fps,
+       c.metadata
+FROM chunk c
+WHERE c.chunk_type = 'cut'
+ON CONFLICT (file_uuid, cut_number) DO NOTHING;
+
+-- Update face_detections.cut_id to reference cuts.id
+UPDATE face_detections fd
+SET cut_id = cs.id
+FROM cuts cs
+WHERE cs.file_uuid = fd.file_uuid
+  AND fd.frame_number BETWEEN cs.start_frame AND cs.end_frame
+  AND (fd.cut_id IS NULL OR fd.cut_id != cs.id);