diff --git a/.agents/skills/deploy-railway/SKILL.md b/.agents/skills/deploy-railway/SKILL.md
new file mode 100644
index 0000000..588c828
--- /dev/null
+++ b/.agents/skills/deploy-railway/SKILL.md
@@ -0,0 +1,143 @@
+---
+name: deploy-railway
+description: Deploy the Hyperindex frontend and backend to Railway. Use this skill when the user asks to deploy, redeploy, or update the production services on Railway.
+---
+
+# Deploy Hyperindex to Railway
+
+## Project Layout
+
+Hyperindex is a monorepo with two Railway services:
+
+| Service | Source | Dockerfile | Railway Name |
+|---------|--------|------------|-------------|
+| **Backend** (Go) | repo root `/` | `Dockerfile` | `backend` |
+| **Frontend** (Next.js) | `client/` | `client/Dockerfile` | `frontend` |
+
+## Custom Domains
+
+| Service | Domain |
+|---------|--------|
+| Backend | `https://api.hi.gainforest.app` |
+| Frontend | `https://hi.gainforest.app` |
+
+Legacy domains (still active): `backend-production-95a22.up.railway.app`, `frontend-production-dcce.up.railway.app`
+
+## Prerequisites
+
+- Railway CLI v4+ installed and logged in (`railway whoami`)
+- Linked to project: `railway status` should show project `hyperindex`
+- On the correct git branch (typically `tap-feature`)
+
+## Deploy Backend
+
+The backend deploys from the repo root using the root `Dockerfile`:
+
+```bash
+railway up -s backend -d
+```
+
+This uploads the entire repo, builds the Go binary in Docker, and deploys it. Takes ~3-5 minutes.
+
+### Verify backend:
+```bash
+curl -s https://api.hi.gainforest.app/
+# Should return: {"name":"Hyperindex","version":"0.1.0-dev",...}
+```
+
+## Deploy Frontend
+
+**CRITICAL:** The frontend MUST use `--path-as-root` to avoid Railway picking up the root Go Dockerfile:
+
+```bash
+railway up --path-as-root client/ -s frontend -d
+```
+
+This makes `client/` the archive root so Railway only sees `client/Dockerfile` (the Next.js build). Takes ~3-5 minutes.
+
+### Why `--path-as-root`?
+
+Without it, `railway up` uploads the entire monorepo and Railway finds the root `Dockerfile` (Go backend) instead of `client/Dockerfile` (Next.js frontend). This causes the frontend service to run the Go binary instead of the Next.js app.
+
+### Verify frontend:
+```bash
+curl -s -o /dev/null -w "%{http_code}" https://hi.gainforest.app/
+# Should return: 200
+
+# Verify it's actually Next.js (not the Go server):
+curl -s https://hi.gainforest.app/ | grep -o '<title>[^<]*</title>'
+# Should return: <title>Hyperindex</title>
+```
+
+## Deploy Both Services
+
+```bash
+# Backend (from repo root)
+railway up -s backend -d
+
+# Frontend (with path-as-root)
+railway up --path-as-root client/ -s frontend -d
+```
+
+## Environment Variables
+
+### Backend (`backend` service)
+| Variable | Value |
+|----------|-------|
+| `HOST` | `0.0.0.0` |
+| `PORT` | `8080` |
+| `DATABASE_URL` | `sqlite:/app/data/hypergoat.db` |
+| `EXTERNAL_BASE_URL` | `https://api.hi.gainforest.app` |
+| `TRUST_PROXY_HEADERS` | `true` |
+| `ADMIN_DIDS` | `did:plc:qc42fmqqlsmdq7jiypiiigww` (daviddao.org) |
+| `OAUTH_LOOPBACK_MODE` | `true` |
+| `SECRET_KEY_BASE` | *(set on Railway, do not change)* |
+
+### Frontend (`frontend` service)
+| Variable | Value |
+|----------|-------|
+| `PORT` | `3000` |
+| `PUBLIC_URL` | `https://hi.gainforest.app` |
+| `NEXT_PUBLIC_API_URL` | `https://api.hi.gainforest.app` |
+| `HYPERINDEX_URL` | `https://api.hi.gainforest.app` |
+| `COOKIE_SECRET` | *(set on Railway, do not change)* |
+| `ATPROTO_JWK_PRIVATE` | *(ES256 JWK, set on Railway, do not change)* |
+
+**Note:** `NEXT_PUBLIC_API_URL` is a build-time variable (inlined by Next.js during `npm run build`). The `client/Dockerfile` declares `ARG NEXT_PUBLIC_API_URL` so Railway passes it during Docker build.
+
+## Troubleshooting
+
+### Frontend shows Go JSON response instead of HTML
+You forgot `--path-as-root client/`. Redeploy with:
+```bash
+railway up --path-as-root client/ -s frontend -d
+```
+
+### "Application not found" on custom domain
+SSL certificate is still provisioning. Wait 5-15 minutes after adding DNS records.
+
+### GraphiQL returns 500 through frontend
+GraphiQL is served directly by the backend. The frontend has a `/graphiql` server-side redirect route that redirects to `https://api.hi.gainforest.app/graphiql`.
+
+### OAuth login fails
+Check that `ATPROTO_JWK_PRIVATE` and `PUBLIC_URL` are set on the frontend service. Generate a new JWK with:
+```bash
+node scripts/generate-jwk.js  # (in hyperscan repo, or client/scripts/ if copied)
+```
+
+### "admin privileges required" after login
+Ensure `TRUST_PROXY_HEADERS=true` is set on the backend. Without it, the backend ignores the `X-User-DID` header from the Next.js proxy.
+
+## Setting Environment Variables
+
+```bash
+# Set a variable on a service
+railway variables set 'KEY=value' -s backend
+railway variables set 'KEY=value' -s frontend
+
+# View all variables for a service
+railway variables -s backend
+railway variables -s frontend
+```
+
+After changing env vars, redeploy the affected service.
diff --git a/.beads/.gitignore b/.beads/.gitignore
new file mode 100644
index 0000000..0acd8c6
--- /dev/null
+++ b/.beads/.gitignore
@@ -0,0 +1,46 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+sync-state.json
+last-touched
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+.jsonl.lock
+sync_base.jsonl
+export-state/
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.
diff --git a/.beads/.jsonl.lock b/.beads/.jsonl.lock
new file mode 100644
index 0000000..e69de29
diff --git a/.beads/.local_version b/.beads/.local_version
new file mode 100644
index 0000000..76d0ef9
--- /dev/null
+++ b/.beads/.local_version
@@ -0,0 +1 @@
+0.49.6
diff --git a/.beads/README.md b/.beads/README.md
new file mode 100644
index 0000000..50f281f
--- /dev/null
+++ b/.beads/README.md
@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡
diff --git a/.beads/beads.db b/.beads/beads.db
new file mode 100644
index 0000000..48bf4d3
Binary files /dev/null and b/.beads/beads.db differ
diff --git a/.beads/beads.db-shm b/.beads/beads.db-shm
new file mode 100644
index 0000000..c6bf417
Binary files /dev/null and b/.beads/beads.db-shm differ
diff --git a/.beads/beads.db-wal b/.beads/beads.db-wal
new file mode 100644
index 0000000..1c3f32f
Binary files /dev/null and b/.beads/beads.db-wal differ
diff --git a/.beads/config.yaml b/.beads/config.yaml
new file mode 100644
index 0000000..ff8bc92
--- /dev/null
+++ b/.beads/config.yaml
@@ -0,0 +1,67 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo
diff --git a/.beads/daemon.lock b/.beads/daemon.lock
new file mode 100644
index 0000000..321c431
--- /dev/null
+++ b/.beads/daemon.lock
@@ -0,0 +1,7 @@
+{
+  "pid": 46504,
+  "parent_pid": 46496,
+  "database": "/Users/david/Projects/gainforest/hyperindex/.beads/beads.db",
+  "version": "0.49.6",
+  "started_at": "2026-02-18T08:44:00.42754Z"
+}
diff --git a/.beads/daemon.log b/.beads/daemon.log
new file mode 100644
index 0000000..41e5eea
--- /dev/null
+++ b/.beads/daemon.log
@@ -0,0 +1,777 @@
+time=2026-02-18T16:44:00.440+08:00 level=INFO msg="Daemon started" interval=5s auto_commit=false auto_push=false
+time=2026-02-18T16:44:00.440+08:00 level=INFO msg="using database" path=/Users/david/Projects/gainforest/hyperindex/.beads/beads.db
+time=2026-02-18T16:44:00.467+08:00 level=INFO msg="database opened" path=/Users/david/Projects/gainforest/hyperindex/.beads/beads.db backend=sqlite freshness_checking=true
+time=2026-02-18T16:44:00.467+08:00 level=INFO msg="upgrading .beads/.gitignore"
+time=2026-02-18T16:44:00.467+08:00 level=WARN msg="failed to upgrade .gitignore" error="open .beads/.gitignore: no such file or directory"
+time=2026-02-18T16:44:00.473+08:00 level=INFO msg="Repository fingerprint validated" repo_id=f8ba04d3
+time=2026-02-18T16:44:00.473+08:00 level=INFO msg="starting RPC server" socket=/Users/david/Projects/gainforest/hyperindex/.beads/bd.sock
+time=2026-02-18T16:44:00.473+08:00 level=INFO msg="RPC server ready (socket listening)"
+time=2026-02-18T16:44:00.479+08:00 level=INFO msg="registered in global registry"
+time=2026-02-18T16:44:00.480+08:00 level=WARN msg="initial import failed (continuing anyway)" error="failed to open JSONL: open /Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl: no such file or directory"
+time=2026-02-18T16:44:00.480+08:00 level=INFO msg="Starting sync cycle" mode="sync cycle"
+time=2026-02-18T16:44:00.486+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:44:01.276+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:44:01.304+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:44:01.324+08:00 level=INFO msg="Sync cycle complete"
+time=2026-02-18T16:44:01.324+08:00 level=INFO msg="monitoring parent process" pid=0
+time=2026-02-18T16:44:01.324+08:00 level=INFO msg="using event-driven mode"
+time=2026-02-18T16:44:01.325+08:00 level=INFO msg="Auto-pull disabled: use 'git pull' manually to sync remote changes"
+time=2026-02-18T16:44:02.333+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:03.335+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:44:03.337+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:44:04.111+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:44:04.111+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:44:04.112+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:44:05.637+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-md3.10
+time=2026-02-18T16:44:06.138+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:44:06.138+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:44:06.150+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:44:06.152+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:44:06.152+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:44:06.201+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:44:06.201+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:07.203+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:44:07.204+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:44:07.215+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:07.215+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:44:07.215+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:44:07.990+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:44:07.990+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:44:07.990+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:44:07.998+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:44:07.999+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:44:09.223+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:44:09.274+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:44:09.274+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:10.275+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:44:10.276+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:44:10.287+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:10.299+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:10.299+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:44:10.299+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:44:11.050+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:44:11.050+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:44:11.051+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:44:11.289+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:44:11.289+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:44:11.297+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:11.297+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:44:11.297+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:44:12.015+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:44:12.015+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:44:12.015+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:44:54.719+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:44:54.770+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:44:54.770+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:55.772+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:44:55.774+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:44:55.786+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:44:56.526+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:44:56.526+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:44:56.526+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:44:56.788+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:44:56.789+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:44:57.616+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:44:57.616+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:44:57.616+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:45:00.597+08:00 level=INFO msg="Mutation detected" type=status issue_id=hyperindex-md3.10
+time=2026-02-18T16:45:01.098+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:45:01.100+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:45:01.117+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:45:01.119+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:45:01.120+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:45:01.168+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:45:01.168+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:02.170+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:02.171+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:02.186+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:02.186+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:45:02.186+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:45:02.918+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:02.918+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:02.918+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:45:02.926+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:45:02.927+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:45:02.960+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:45:03.011+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:45:03.011+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:04.012+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:04.013+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:04.026+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:04.026+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:45:04.026+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:45:04.768+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:04.769+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:04.769+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:45:46.287+08:00 level=INFO msg="Mutation detected" type=status issue_id=hyperindex-md3.10
+time=2026-02-18T16:45:46.788+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:45:46.788+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:45:46.796+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:45:46.797+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:45:46.797+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:45:46.847+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:45:46.847+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:47.849+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:47.850+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:47.861+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:47.863+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:47.863+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:45:47.863+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:45:48.691+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:48.691+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:48.692+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:45:48.699+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:45:48.699+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:45:48.862+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:48.863+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:48.872+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:48.874+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:48.874+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:45:48.874+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:45:49.684+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:49.684+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:49.684+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:45:49.692+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:45:49.693+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:45:49.875+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:49.875+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:49.884+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:49.887+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:49.887+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:45:49.887+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:45:50.135+08:00 level=INFO msg="Mutation detected" type=status issue_id=hyperindex-md3
+time=2026-02-18T16:45:50.615+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:50.615+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:50.616+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:45:50.622+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:45:50.622+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:45:50.635+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:45:50.635+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:45:50.635+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T16:45:50.642+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T16:45:50.647+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:45:50.649+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:45:50.649+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:45:50.699+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:45:50.699+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:51.134+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:51.135+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:51.143+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:51.143+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:45:51.143+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:45:51.700+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:51.701+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:51.710+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:51.710+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:45:51.710+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:45:51.871+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:51.871+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:51.872+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:45:51.879+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:45:51.880+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:45:52.407+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:52.407+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:52.407+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:45:52.415+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:45:52.416+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:45:53.534+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:45:53.585+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:45:53.585+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:53.603+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:53.721+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:45:53.772+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:45:53.772+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:54.774+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:54.774+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:54.782+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:45:55.539+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:55.540+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:55.540+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:45:55.784+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:45:55.784+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:45:56.515+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:45:56.515+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:45:56.515+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:48:34.554+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-6bl
+time=2026-02-18T16:48:35.056+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:48:35.056+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:48:35.069+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:48:35.071+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:48:35.071+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:48:35.120+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:48:35.121+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:36.123+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:48:36.124+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:48:36.142+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:36.142+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:48:36.142+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:48:36.904+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:48:36.904+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:48:36.904+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:48:36.912+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:48:36.914+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:48:40.475+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-73q
+time=2026-02-18T16:48:40.976+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:48:40.977+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:48:40.978+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T16:48:40.991+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T16:48:41.002+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:48:41.005+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:48:41.005+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:48:41.053+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:48:41.053+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:42.055+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:48:42.056+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:48:42.070+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:42.070+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:48:42.070+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:48:42.825+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:48:42.825+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:48:42.827+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:48:42.835+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:48:42.836+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:48:45.610+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-m1t
+time=2026-02-18T16:48:46.111+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:48:46.112+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:48:46.113+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T16:48:46.127+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T16:48:46.138+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:48:46.141+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:48:46.141+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:48:46.190+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:48:46.190+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:47.192+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:48:47.193+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:48:47.208+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:47.208+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:48:47.208+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:48:48.004+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:48:48.004+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:48:48.004+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:48:48.012+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:48:48.013+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:48:53.283+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-6bl
+time=2026-02-18T16:48:53.381+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-73q
+time=2026-02-18T16:48:53.471+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-m1t
+time=2026-02-18T16:48:53.972+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:48:53.973+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:48:53.973+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T16:48:53.988+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T16:48:54.000+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:48:54.003+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:48:54.003+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:48:54.051+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:48:54.051+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:55.054+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:48:55.055+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:48:55.068+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:55.068+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:48:55.068+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:48:55.812+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:48:55.812+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:48:55.813+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:48:55.821+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:48:55.823+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:48:56.263+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:48:56.314+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:48:56.314+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:57.316+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:48:57.317+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:48:57.329+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:57.348+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:57.348+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:48:57.348+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:48:58.063+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:48:58.063+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:48:58.064+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:48:58.331+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:48:58.332+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:48:58.345+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:48:58.345+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:48:58.345+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:48:59.078+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:48:59.078+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:48:59.079+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:49:26.577+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:49:26.628+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:49:26.628+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:27.630+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:27.631+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:27.647+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:27.651+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:27.651+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:27.651+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:28.425+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:28.425+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:28.427+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:49:28.649+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:28.650+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:28.664+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:28.664+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:28.664+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:29.393+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:29.393+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:29.393+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:49:37.492+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-uau
+time=2026-02-18T16:49:37.993+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:49:37.994+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:49:38.008+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:49:38.011+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:49:38.011+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:49:38.059+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:49:38.059+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:39.061+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:39.062+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:39.075+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:39.075+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:39.075+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:39.797+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:39.797+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:39.798+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:49:39.807+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:49:39.809+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:49:41.018+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-uau
+time=2026-02-18T16:49:41.520+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:49:41.520+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:49:41.521+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T16:49:41.533+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T16:49:41.554+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:49:41.573+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:49:41.573+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:49:41.605+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:49:41.605+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:42.607+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:42.617+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:42.633+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:42.633+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:42.633+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:43.404+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:43.404+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:43.405+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:49:43.414+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:49:43.415+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:49:47.688+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-3jy
+time=2026-02-18T16:49:48.189+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:49:48.190+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:49:48.192+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T16:49:48.208+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T16:49:48.217+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:49:48.220+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:49:48.220+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:49:48.268+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:49:48.268+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:49.271+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:49.272+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:49.284+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:49.284+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:49.284+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:49.970+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-3jy
+time=2026-02-18T16:49:49.997+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:49.997+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:49.998+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:49:50.004+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:49:50.005+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:49:50.471+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T16:49:50.471+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T16:49:50.472+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T16:49:50.486+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T16:49:50.497+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:49:50.500+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T16:49:50.500+08:00 level=INFO msg="Export complete"
+time=2026-02-18T16:49:50.549+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:49:50.549+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:51.551+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:51.552+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:51.562+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:51.562+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:51.562+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:52.285+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:52.285+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:52.286+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T16:49:52.294+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T16:49:52.296+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T16:49:53.259+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T16:49:53.310+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T16:49:53.310+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:54.312+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:54.314+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:54.329+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:54.349+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:54.349+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:54.349+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:55.085+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:55.085+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:55.086+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T16:49:55.330+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T16:49:55.331+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T16:49:55.344+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T16:49:55.344+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T16:49:55.344+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T16:49:56.078+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T16:49:56.078+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T16:49:56.079+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:10:15.982+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-xuq
+time=2026-02-18T17:10:16.484+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:10:16.484+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:10:16.493+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:10:16.495+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:10:16.495+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:10:16.544+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:10:16.544+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:10:17.546+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:10:17.547+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:10:17.563+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:10:17.563+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:10:17.563+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:10:18.320+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:10:18.320+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:10:18.321+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:10:18.328+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:10:18.328+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:10:35.044+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-xuq.1
+time=2026-02-18T17:10:35.545+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:10:35.546+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:10:35.546+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T17:10:35.553+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T17:10:35.560+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:10:35.562+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:10:35.562+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:10:35.611+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:10:35.611+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:10:36.613+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:10:36.614+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:10:36.625+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:10:36.625+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:10:36.625+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:10:37.335+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:10:37.335+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:10:37.335+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:10:37.341+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:10:37.342+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:10:46.160+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-xuq.2
+time=2026-02-18T17:10:46.661+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:10:46.661+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:10:46.662+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T17:10:46.676+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T17:10:46.686+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:10:46.688+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:10:46.688+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:10:46.737+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:10:46.737+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:10:47.740+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:10:47.740+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:10:47.754+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:10:47.754+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:10:47.754+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:10:48.539+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:10:48.539+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:10:48.540+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:10:48.548+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:10:48.549+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:11:04.452+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-xuq.3
+time=2026-02-18T17:11:04.953+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:11:04.953+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:11:04.954+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T17:11:04.964+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T17:11:04.973+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:11:04.977+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:11:04.977+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:11:05.024+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:11:05.024+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:06.026+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:11:06.030+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:11:06.039+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:06.039+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:11:06.039+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:11:06.787+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:11:06.788+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:11:06.788+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:11:06.797+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:11:06.798+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:11:20.029+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-xuq.4
+time=2026-02-18T17:11:20.530+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:11:20.530+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:11:20.530+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T17:11:20.541+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T17:11:20.551+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:11:20.554+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:11:20.554+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:11:20.603+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:11:20.603+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:21.605+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:11:21.605+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:11:21.619+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:21.619+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:11:21.619+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:11:22.323+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:11:22.324+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:11:22.324+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:11:22.332+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:11:22.333+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:11:29.668+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-xuq.5
+time=2026-02-18T17:11:30.169+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:11:30.170+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:11:30.170+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T17:11:30.181+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T17:11:30.190+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:11:30.192+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:11:30.192+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:11:30.241+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:11:30.241+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:31.243+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:11:31.244+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:11:31.257+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:31.257+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:11:31.257+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:11:32.027+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:11:32.027+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:11:32.027+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:11:32.037+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:11:32.037+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:11:43.522+08:00 level=INFO msg="Mutation detected" type=create issue_id=hyperindex-xuq.6
+time=2026-02-18T17:11:44.024+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:11:44.024+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:11:44.024+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T17:11:44.032+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T17:11:44.039+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:11:44.041+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:11:44.041+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:11:44.090+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:11:44.090+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:45.092+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:11:45.093+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:11:45.110+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:45.110+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:11:45.110+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:11:45.873+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:11:45.873+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:11:45.874+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:11:45.880+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:11:45.881+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:11:48.534+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-xuq.4
+time=2026-02-18T17:11:49.035+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:11:49.036+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:11:49.036+08:00 level=INFO msg="JSONL changed externally, importing before export"
+time=2026-02-18T17:11:49.046+08:00 level=INFO msg="Auto-import complete, proceeding with export"
+time=2026-02-18T17:11:49.055+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:11:49.057+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:11:49.058+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:11:49.106+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:11:49.106+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:50.109+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:11:50.109+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:11:50.119+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:50.119+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:11:50.119+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:11:50.836+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:11:50.836+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:11:50.837+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:11:50.845+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:11:50.846+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:11:54.000+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:11:54.051+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:11:54.051+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:54.162+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:11:54.213+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:11:54.213+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:55.216+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:11:55.216+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:11:55.221+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:11:56.097+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:11:56.097+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:11:56.097+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:11:56.224+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:11:56.224+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:11:56.941+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:11:56.941+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:11:56.942+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:11.280+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:11.332+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:11.332+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:11.716+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:11.767+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:11.767+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:12.201+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:12.252+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:12.252+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:12.468+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:12.519+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:12.519+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:12.739+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:12.790+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:12.790+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:12.869+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:13.871+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:13.872+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:13.882+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:14.616+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:14.616+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:14.616+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:14.884+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:14.885+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:15.674+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:15.674+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:15.674+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:16.347+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-xuq.3
+time=2026-02-18T17:12:16.551+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-xuq.6
+time=2026-02-18T17:12:17.010+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-xuq.2
+time=2026-02-18T17:12:17.512+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:12:17.512+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:12:17.521+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:17.523+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:12:17.523+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:12:17.572+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:17.572+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:17.908+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-xuq.1
+time=2026-02-18T17:12:18.384+08:00 level=INFO msg="Mutation detected" type=update issue_id=hyperindex-xuq.5
+time=2026-02-18T17:12:18.536+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:18.573+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:18.574+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:18.579+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:18.579+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:18.579+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:18.586+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:18.586+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:18.586+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:18.773+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:18.824+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:18.824+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:18.885+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:12:18.885+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:12:18.892+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:18.893+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:12:18.893+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:12:18.943+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:18.943+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:19.260+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:19.260+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:19.260+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:19.696+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:19.747+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:19.747+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:19.945+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:19.946+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:19.955+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:19.970+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:19.970+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:19.970+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:20.327+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:20.378+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:20.378+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:20.685+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:20.685+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:20.686+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:20.689+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:20.741+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:20.741+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:21.742+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:21.743+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:21.752+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:21.766+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:21.767+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:21.767+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:22.450+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:22.450+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:22.450+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:22.754+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:22.755+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:22.765+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:22.765+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:22.765+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:23.449+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:23.449+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:23.450+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:33.665+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:33.716+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:33.716+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:34.719+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:34.726+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:34.738+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:35.570+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:35.570+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:35.570+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:35.740+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:35.741+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:36.302+08:00 level=INFO msg="Mutation detected" type=status issue_id=hyperindex-xuq.2
+time=2026-02-18T17:12:36.474+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:36.474+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:36.475+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:36.803+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:12:36.804+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:12:36.821+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:36.825+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:12:36.825+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:12:36.873+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:36.873+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:37.875+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:37.875+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:37.886+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:37.886+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:37.886+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:38.068+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:38.120+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:38.120+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:38.710+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:38.710+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:38.711+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:39.122+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:39.123+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:39.133+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:39.133+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:39.133+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:39.831+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:39.831+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:39.831+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:43.524+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:43.575+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:43.575+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:44.577+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:44.578+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:44.585+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:45.348+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:45.349+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:45.349+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:45.587+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:45.588+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:46.302+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:46.302+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:46.302+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:46.604+08:00 level=INFO msg="Mutation detected" type=status issue_id=hyperindex-xuq.5
+time=2026-02-18T17:12:47.105+08:00 level=INFO msg="Export triggered by mutation events"
+time=2026-02-18T17:12:47.105+08:00 level=INFO msg=Starting mode=export
+time=2026-02-18T17:12:47.113+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:47.115+08:00 level=INFO msg="Exported to JSONL"
+time=2026-02-18T17:12:47.115+08:00 level=INFO msg="Export complete"
+time=2026-02-18T17:12:47.164+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:47.164+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:48.166+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:48.167+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:48.176+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:48.176+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:48.176+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:48.917+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:48.918+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:48.918+08:00 level=INFO msg="JSONL content changed, proceeding with operation..." mode=auto-import
+time=2026-02-18T17:12:48.925+08:00 level=INFO msg="Imported from JSONL"
+time=2026-02-18T17:12:48.926+08:00 level=INFO msg="Auto-import complete"
+time=2026-02-18T17:12:50.125+08:00 level=INFO msg="JSONL removed/renamed, re-establishing watch"
+time=2026-02-18T17:12:50.176+08:00 level=INFO msg="Successfully re-established JSONL watch" delay=50ms
+time=2026-02-18T17:12:50.176+08:00 level=INFO msg="JSONL file created" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:50.178+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:51.180+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:51.181+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:51.186+08:00 level=INFO msg="File change detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:51.197+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:51.197+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:51.197+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:51.931+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:51.931+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:51.931+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
+time=2026-02-18T17:12:52.187+08:00 level=INFO msg="Import triggered by file change"
+time=2026-02-18T17:12:52.188+08:00 level=INFO msg="Starting auto-import" mode=auto-import
+time=2026-02-18T17:12:52.199+08:00 level=INFO msg="WARNING: Uncommitted local changes detected" path=/Users/david/Projects/gainforest/hyperindex/.beads/issues.jsonl
+time=2026-02-18T17:12:52.199+08:00 level=INFO msg="   Pulling from remote may overwrite local unpushed changes."
+time=2026-02-18T17:12:52.199+08:00 level=INFO msg="   Consider running 'bd sync' to commit and push your changes first."
+time=2026-02-18T17:12:52.951+08:00 level=INFO msg="Pulled from remote"
+time=2026-02-18T17:12:52.951+08:00 level=INFO msg="🔍 Checking JSONL content hash AFTER pull (fix: auto-pull-not-pulling)"
+time=2026-02-18T17:12:52.953+08:00 level=INFO msg="Skipping: JSONL content unchanged" mode=auto-import
diff --git a/.beads/daemon.pid b/.beads/daemon.pid
new file mode 100644
index 0000000..68d11c4
--- /dev/null
+++ b/.beads/daemon.pid
@@ -0,0 +1 @@
+46504
diff --git a/.beads/interactions.jsonl b/.beads/interactions.jsonl
new file mode 100644
index 0000000..e69de29
diff --git a/.beads/issues.jsonl b/.beads/issues.jsonl
new file mode 100644
index 0000000..2451d01
--- /dev/null
+++ b/.beads/issues.jsonl
@@ -0,0 +1,82 @@
+{"id":"hyperindex-0nk","title":"Epic: Frontend Design Overhaul — Adopt Hypercerts Design Language","description":"## Goals\n- Adopt the hypercerts-scaffold-atproto design language for the hyperindex Next.js client\n- Replace the goat emoji / logo.png with the hypercerts_logo.png from hyperscan\n- Add light mode / dark mode toggle (like hyperscan uses)\n- Rename all user-visible branding from 'hi' and 'Hypergoat' to 'Hyperindex'\n- Update API documentation pages to reflect new branding\n\n## Design Source\nThe design language comes from `../hypercerts-scaffold-atproto` which uses:\n- **Fonts**: Syne (display/headings) + Outfit (body text)\n- **Colors**: OKLCH color space with blue-gray hue angle 260, near-monochromatic palette\n- **Surfaces**: Glass-panel (frosted glass with backdrop-blur)\n- **Background**: noise-bg texture + gradient-mesh radial gradients\n- **Dark mode**: Full OKLCH dark theme with CSS custom properties\n- **Border radius**: 0.625rem (10px) base\n- **Animations**: fade-in-up, stagger-children, scale-in\n\n## Theme Toggle Source\nThe dark/light toggle comes from `../hyperscan` which uses:\n- `next-themes` library with `attribute='class'`, `defaultTheme='light'`, `enableSystem={false}`\n- Sun/Moon icon toggle button\n- `@custom-variant dark (\u0026:where(.dark, .dark *))` for Tailwind v4\n\n## Scope\n- All files in `client/` (Next.js frontend)\n- A few strings in `cmd/hypergoat/main.go` and `internal/server/graphiql.go` (rename branding)\n- Config files (`.env.example`, `client/src/lib/env.ts`, etc.)\n\n## Constraints\n- Do NOT change the Go module path (`github.com/GainForest/hypergoat`) — too many import references\n- Do NOT change the binary name or Dockerfile entrypoint\n- Do NOT change any Go tests except `handlers_test.go` title assertions\n- Preserve all existing functionality — this is purely visual + branding","status":"open","priority":1,"issue_type":"epic","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","created_at":"2026-02-18T17:32:33.630839+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:55:59.06656+08:00","labels":["needs-integration-review","scope:medium"]}
+{"id":"hyperindex-0nk.1","title":"Setup: Install next-themes, add Syne + Outfit fonts to layout","description":"## Files\n- client/package.json (modify)\n- client/src/app/layout.tsx (modify)\n\n## What to do\n\n### 1. Add next-themes dependency\nIn `client/package.json`, add to `dependencies`:\n```\n\"next-themes\": \"^0.4.6\"\n```\nThen run `npm install` in the `client/` directory.\n\n### 2. Replace fonts in layout.tsx\nReplace the current font imports:\n```tsx\n// REMOVE these:\nimport { Inter, EB_Garamond } from \"next/font/google\";\nconst inter = Inter({ variable: \"--font-inter\", subsets: [\"latin\"] });\nconst garamond = EB_Garamond({ variable: \"--font-garamond\", subsets: [\"latin\"], weight: [\"400\", \"500\", \"600\", \"700\"] });\n\n// ADD these:\nimport { Syne, Outfit } from \"next/font/google\";\n\nconst syne = Syne({\n  variable: \"--font-syne\",\n  subsets: [\"latin\"],\n  weight: [\"400\", \"500\", \"600\", \"700\", \"800\"],\n});\n\nconst outfit = Outfit({\n  variable: \"--font-outfit\",\n  subsets: [\"latin\"],\n  weight: [\"300\", \"400\", \"500\", \"600\", \"700\"],\n});\n```\n\n### 3. Update body className\nChange the body tag className from:\n```tsx\nclassName={`${inter.variable} ${garamond.variable} antialiased bg-white text-zinc-800`}\n```\nto:\n```tsx\nclassName={`${syne.variable} ${outfit.variable} antialiased`}\n```\n(Background/text colors will be handled by globals.css in a separate task)\n\n## Don't\n- Do NOT change any other files\n- Do NOT modify Providers, Header, or footer yet (those are separate tasks)\n- Do NOT remove the existing CSS variable references in globals.css yet","acceptance_criteria":"1. `npm ls next-themes` in client/ shows next-themes installed\n2. layout.tsx imports Syne and Outfit from next/font/google (not Inter or EB_Garamond)\n3. layout.tsx defines CSS variables --font-syne and --font-outfit\n4. body className includes both font variables and antialiased\n5. `npm run build` in client/ succeeds without errors","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-18T17:32:48.187066+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:47:52.643169+08:00","closed_at":"2026-02-18T17:47:52.643169+08:00","close_reason":"d39a509 Setup: Install next-themes, add Syne + Outfit fonts to layout","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-0nk.1","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:32:48.187828+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.10","title":"Pages: Update Lexicons + Backfill pages for dark mode","description":"## Files\n- client/src/app/lexicons/page.tsx (modify)\n- client/src/app/backfill/page.tsx (modify)\n\n## What to do\nUpdate both pages to use CSS custom properties instead of hardcoded color classes. Apply the same consistent pattern used in Dashboard and Docs pages.\n\n### Common pattern for both pages:\n\n**Text replacements (use style prop):**\n- `text-zinc-900` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-800` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-700` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-600` → `style={{ color: \"var(--secondary-foreground)\" }}`\n- `text-zinc-500` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-400` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-300` → `style={{ color: \"var(--border)\" }}`\n- `text-emerald-*` → `style={{ color: \"var(--primary)\" }}` (or keep semantic OKLCH for status indicators)\n- `text-red-500`, `text-red-*` → keep as is (error state, works in both themes)\n\n**Background replacements:**\n- `bg-white` → `style={{ backgroundColor: \"var(--card)\" }}`\n- `bg-zinc-50` → `style={{ backgroundColor: \"var(--muted)\" }}`\n- `bg-zinc-100` → `style={{ backgroundColor: \"var(--muted)\" }}`\n- `bg-emerald-50` → `style={{ backgroundColor: \"var(--accent)\" }}`\n- `hover:bg-zinc-50` → `hover:opacity-90` or keep and override inline\n\n**Border replacements:**\n- `border-zinc-200/60` → `style={{ borderColor: \"var(--border)\" }}`\n- `border-zinc-200` → `style={{ borderColor: \"var(--border)\" }}`\n- `border-zinc-100` → `style={{ borderColor: \"var(--border)\" }}`\n- `divide-zinc-*` → use CSS variable for divider color\n\n**Font replacements:**\n- `font-[family-name:var(--font-garamond)]` → `font-[family-name:var(--font-syne)]`\n\n**Skeleton/loading states:**\n- `bg-zinc-100 animate-pulse` → `animate-pulse` with `style={{ backgroundColor: \"var(--muted)\" }}`\n\n### Lexicons-specific notes:\n- The tree view uses indentation and expand/collapse icons — keep the structural logic\n- NSID text in monospace — keep `font-mono`\n- Delete buttons / destructive actions — keep red colors\n\n### Backfill-specific notes:\n- Status indicators (running/idle) — keep green/gray semantic colors but use OKLCH:\n  - Running: `style={{ color: \"oklch(0.65 0.15 155)\" }}` with a pulsing dot\n  - Idle: `style={{ color: \"var(--muted-foreground)\" }}`\n- DID input field uses the Input component (already updated in task 6)\n\n## Don't\n- Do NOT change any data fetching, mutation, or state logic\n- Do NOT change component structure or imports\n- Do NOT change form validation or error handling behavior","acceptance_criteria":"1. No hardcoded zinc-*/emerald-* Tailwind color classes remain in either file (except text-red-* for errors)\n2. All font-garamond references replaced with font-syne\n3. All card-like containers use var(--card) background\n4. All borders use var(--border)\n5. All text uses appropriate CSS variables\n6. `npm run build` in client/ succeeds","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T17:36:20.172865+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:54:00.049557+08:00","closed_at":"2026-02-18T17:54:00.049557+08:00","close_reason":"4b86216 feat: update lexicons and backfill pages for dark mode","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.10","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:36:20.173778+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.10","depends_on_id":"hyperindex-0nk.4","type":"blocks","created_at":"2026-02-18T17:36:20.17514+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.10","depends_on_id":"hyperindex-0nk.6","type":"blocks","created_at":"2026-02-18T17:36:20.176306+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.11","title":"Pages: Update Settings + Onboarding pages for dark mode","description":"## Files\n- client/src/app/settings/page.tsx (modify)\n- client/src/app/onboarding/page.tsx (modify)\n\n## What to do\nUpdate both pages to use CSS custom properties instead of hardcoded color classes. Apply the same consistent pattern.\n\n### Common pattern for both pages:\n\n**Text replacements (use style prop):**\n- `text-zinc-900` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-800` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-700` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-600` → `style={{ color: \"var(--secondary-foreground)\" }}`\n- `text-zinc-500` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-400` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-300` → `style={{ color: \"var(--border)\" }}`\n- `text-emerald-*` → `style={{ color: \"var(--primary)\" }}`\n\n**Background replacements:**\n- `bg-white` → `style={{ backgroundColor: \"var(--card)\" }}`\n- `bg-zinc-50` → `style={{ backgroundColor: \"var(--muted)\" }}`\n- `bg-zinc-100` → `style={{ backgroundColor: \"var(--muted)\" }}`\n\n**Border replacements:**\n- `border-zinc-200/60` → `style={{ borderColor: \"var(--border)\" }}`\n- `border-zinc-200` → `style={{ borderColor: \"var(--border)\" }}`\n- `border-zinc-100` → `style={{ borderColor: \"var(--border)\" }}`\n\n**Font replacements:**\n- `font-[family-name:var(--font-garamond)]` → `font-[family-name:var(--font-syne)]`\n\n### Settings-specific notes:\n- The settings page uses Card components (already updated in task 6)\n- Keep the danger zone section with red styling (text-red-*, border-red-*) — these semantic colors work in both themes\n- OAuth client cards — update background and border colors\n- Admin DID list — update colors\n\n### Onboarding-specific notes:\n- The step indicator/stepper — update active/inactive colors:\n  - Active step: `style={{ backgroundColor: \"var(--primary)\", color: \"var(--primary-foreground)\" }}`\n  - Completed step: same as active\n  - Upcoming step: `style={{ backgroundColor: \"var(--muted)\", color: \"var(--muted-foreground)\" }}`\n- Welcome screen text and decorative elements\n- Success/complete screen at the end\n\n## Don't\n- Do NOT change form logic, state management, or mutations\n- Do NOT change the step flow in onboarding\n- Do NOT change card layout or section structure\n- Do NOT change danger zone logic (reset all, etc.)","acceptance_criteria":"1. No hardcoded zinc-*/emerald-* Tailwind color classes remain in either file (except red for danger zone)\n2. All font-garamond references replaced with font-syne\n3. All card backgrounds use var(--card) or Card component\n4. All borders use var(--border)\n5. Onboarding stepper uses CSS variables for active/inactive states\n6. `npm run build` in client/ succeeds","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T17:36:33.968542+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:54:17.9742+08:00","closed_at":"2026-02-18T17:54:17.9742+08:00","close_reason":"6033c8f feat: update settings and onboarding pages for dark mode","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.11","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:36:33.969326+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.11","depends_on_id":"hyperindex-0nk.4","type":"blocks","created_at":"2026-02-18T17:36:33.970574+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.11","depends_on_id":"hyperindex-0nk.6","type":"blocks","created_at":"2026-02-18T17:36:33.971536+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.12","title":"Docs: Update agent docs route — rename branding to Hyperindex","description":"## Files\n- client/src/app/docs/agents/route.ts (modify)\n\n## What to do\nUpdate the agent documentation markdown content to use consistent \"Hyperindex\" branding.\n\n### 1. Update title (line ~4)\nChange: `# Hyperindex (hi) API - Complete Integration Guide for AI Agents`\nTo: `# Hyperindex API - Complete Integration Guide for AI Agents`\n\n### 2. Update \"What is Hyperindex?\" section (lines ~6-15)\nChange:\n```\n**Hyperindex** (short: **hi**, formerly known as Hypergoat) is GainForest's AT Protocol AppView server...\nThe name \"hi\" stands for **H**yper**i**ndex -- it indexes...\n```\nTo:\n```\n**Hyperindex** is GainForest's AT Protocol AppView server for the Hypersphere ecosystem. It indexes Lexicon-defined records from the AT Protocol network and exposes them via a dynamically-generated GraphQL API.\n```\n\n### 3. Remove \"History\" line\nDelete: `- **History**: Formerly known as Hypergoat (Hypersphere Go ATProto AppView)`\n\n### 4. Update all remaining instances\nSearch for any remaining \"Hypergoat\" or \"hi\" alias references in the file and replace:\n- \"Hypergoat\" → \"Hyperindex\" (in text descriptions)\n- Remove any \"(hi)\" or \"short: hi\" references\n- Keep the string \"Hyperindex\" as-is where it already appears\n\n### 5. Keep URLs as-is\nDo NOT change the API_ENDPOINT or WS_ENDPOINT constants — these are deployment URLs.\n\n## Don't\n- Do NOT change the API_ENDPOINT or WS_ENDPOINT URL constants\n- Do NOT change the GraphQL query examples\n- Do NOT change the code examples\n- Do NOT change the response format for the GET handler\n- Do NOT change the Content-Type or Cache-Control headers","acceptance_criteria":"1. Title reads \"# Hyperindex API - Complete Integration Guide for AI Agents\" (no \"hi\" in parens)\n2. No \"Hypergoat\" string appears anywhere in the file\n3. No \"(hi)\" or \"short: hi\" references remain\n4. No \"formerly known as\" text remains\n5. API_ENDPOINT and WS_ENDPOINT URLs are unchanged\n6. `npm run build` in client/ succeeds","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T17:36:51.204447+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:44:04.094028+08:00","closed_at":"2026-02-18T17:44:04.094028+08:00","close_reason":"3e6b656 docs: rename branding to Hyperindex in agents route","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-0nk.12","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:36:51.205271+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.13","title":"Backend: Rename Hypergoat → Hyperindex in Go user-visible strings + client config","description":"## Files\n- cmd/hypergoat/main.go (modify)\n- internal/server/graphiql.go (modify — package doc comment only)\n- internal/server/handlers_test.go (modify)\n- client/src/lib/env.ts (modify)\n- client/src/lib/graphql/client.ts (modify)\n- client/src/app/api/admin/graphql/route.ts (modify)\n- client/.env.example (modify)\n\n## What to do\n\n### Go files\n\n#### cmd/hypergoat/main.go\n1. Line ~109: Change `\"Starting Hypergoat - AT Protocol AppView Server\"` → `\"Starting Hyperindex - AT Protocol AppView Server\"`\n2. Line ~354: Change `\"name\": \"Hypergoat\"` → `\"name\": \"Hyperindex\"` in the root endpoint JSON response\n3. Line ~408: Change `ClientName: \"Hypergoat\"` → `ClientName: \"Hyperindex\"` in OAuth metadata\n4. Line ~487: Change `Title: \"Hypergoat GraphQL\"` → `Title: \"Hyperindex GraphQL\"` \n5. Line ~488: Change `# Hypergoat GraphQL API` → `# Hyperindex GraphQL API`\n6. Line ~506: Change `Title: \"Hypergoat Admin\"` → `Title: \"Hyperindex Admin\"`\n7. Line ~507: Change `# Hypergoat Admin API` → `# Hyperindex Admin API`\n\n#### internal/server/graphiql.go\n1. Line 1: Change package doc comment from `// Package server contains HTTP handlers for the hypergoat server.` → `// Package server contains HTTP handlers for the Hyperindex server.`\n\n#### internal/server/handlers_test.go\nSearch for test assertions containing \"Hypergoat\" and update them:\n1. Any test title like `\"Hypergoat GraphiQL\"` → `\"Hyperindex GraphiQL\"` (or whatever the test expects)\n\n### Client config files\n\n#### client/src/lib/env.ts\n1. Line ~28: Change comment from `// Hypergoat backend URL` → `// Hyperindex backend URL`\n2. Line ~29: Change `HYPERGOAT_URL: getEnv(\"HYPERGOAT_URL\", ...)` → `HYPERINDEX_URL: getEnv(\"HYPERINDEX_URL\", \"http://127.0.0.1:8080\")`\n   Also support fallback: `getEnv(\"HYPERINDEX_URL\", getEnv(\"HYPERGOAT_URL\", \"http://127.0.0.1:8080\"))` for backward compatibility\n\n#### client/src/lib/graphql/client.ts\n1. Line ~13: Rename function `getHypergoatUrl` → `getHyperindexUrl`\n2. Line ~15: Change `HYPERGOAT_URL` → `HYPERINDEX_URL` in process.env reference\n3. Update comment on line ~13: `// Get Hyperindex URL for direct backend access`\n\n#### client/src/app/api/admin/graphql/route.ts\n1. Update all comments from \"Hypergoat\" → \"Hyperindex\":\n   - Line ~9: `Checks session authentication and passes user DID to Hyperindex.`\n   - Line ~16: `// Build headers for Hyperindex`\n2. Line ~30: Change `env.HYPERGOAT_URL` → `env.HYPERINDEX_URL`\n3. Line ~38: Change `// Log errors from Hypergoat` → `// Log errors from Hyperindex`\n\n#### client/.env.example\n1. Line ~2: Change `# Hypergoat Client Configuration` → `# Hyperindex Client Configuration`\n2. Line ~11: Change `HYPERGOAT_URL=http://127.0.0.1:8080` → `HYPERINDEX_URL=http://127.0.0.1:8080`\n\n## Don't\n- Do NOT change the Go module path (github.com/GainForest/hypergoat) — changing that would break all import paths\n- Do NOT rename the binary name (hypergoat) in Makefile/Dockerfile\n- Do NOT change any package-level doc comments EXCEPT the graphiql.go one specified above\n- Do NOT change any non-user-visible internal variable names in Go code\n- Do NOT change the CI workflow or Docker configuration","acceptance_criteria":"1. `go build ./...` succeeds\n2. `go test ./...` passes (especially handlers_test.go)\n3. grep -r \"Hypergoat\" cmd/hypergoat/main.go returns NO matches for user-visible strings (startup log, JSON, GraphiQL titles)\n4. client/src/lib/env.ts exports HYPERINDEX_URL (not HYPERGOAT_URL)\n5. client/src/app/api/admin/graphql/route.ts references env.HYPERINDEX_URL\n6. client/.env.example uses HYPERINDEX_URL\n7. `npm run build` in client/ succeeds","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T17:37:14.846706+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:47:45.915489+08:00","closed_at":"2026-02-18T17:47:45.915489+08:00","close_reason":"d39a509 rename Hypergoat → Hyperindex in user-visible strings and client config","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.13","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:37:14.847467+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.2","title":"Foundation: Rewrite globals.css with OKLCH design tokens + dark mode","description":"## Files\n- client/src/app/globals.css (modify)\n\n## What to do\nReplace the entire contents of globals.css with the new design system CSS. The file must contain:\n\n### 1. Tailwind import + dark mode variant\n```css\n@import \"tailwindcss\";\n\n@custom-variant dark (\u0026:where(.dark, .dark *));\n```\n\n### 2. Root CSS custom properties (light mode)\n```css\n:root {\n  --font-sans: system-ui, sans-serif;\n  --font-display: var(--font-syne);\n  --font-body: var(--font-outfit);\n  --radius: 0.625rem;\n\n  --background: oklch(0.985 0.002 260);\n  --foreground: oklch(0.16 0.005 260);\n  --card: oklch(0.995 0.001 260);\n  --card-foreground: oklch(0.16 0.005 260);\n  --primary: oklch(0.20 0.005 260);\n  --primary-foreground: oklch(0.98 0.005 260);\n  --secondary: oklch(0.96 0.005 260);\n  --secondary-foreground: oklch(0.20 0.005 260);\n  --muted: oklch(0.96 0.005 260);\n  --muted-foreground: oklch(0.50 0.01 260);\n  --accent: oklch(0.94 0.005 260);\n  --accent-foreground: oklch(0.20 0.005 260);\n  --destructive: oklch(0.577 0.245 27.325);\n  --border: oklch(0.91 0.005 260);\n  --input: oklch(0.91 0.005 260);\n  --ring: oklch(0.35 0.01 260);\n}\n```\n\n### 3. Dark mode custom properties\n```css\n.dark {\n  --background: oklch(0.13 0.005 260);\n  --foreground: oklch(0.95 0.005 260);\n  --card: oklch(0.17 0.005 260);\n  --card-foreground: oklch(0.95 0.005 260);\n  --primary: oklch(0.82 0.01 260);\n  --primary-foreground: oklch(0.13 0.005 260);\n  --secondary: oklch(0.22 0.01 260);\n  --secondary-foreground: oklch(0.95 0.005 260);\n  --muted: oklch(0.22 0.008 260);\n  --muted-foreground: oklch(0.65 0.01 260);\n  --accent: oklch(0.25 0.008 260);\n  --accent-foreground: oklch(0.95 0.005 260);\n  --destructive: oklch(0.577 0.245 27.325);\n  --border: oklch(0.95 0 0 / 10%);\n  --input: oklch(0.95 0 0 / 15%);\n  --ring: oklch(0.55 0.01 260);\n}\n```\n\n### 4. Base body/heading styles\n```css\nbody {\n  font-family: var(--font-body), var(--font-sans);\n  background-color: var(--background);\n  color: var(--foreground);\n}\n\nh1, h2, h3, h4, h5, h6 {\n  font-family: var(--font-display), var(--font-sans);\n}\n```\n\n### 5. Glass panel utility class\n```css\n.glass-panel {\n  background: oklch(1 0 0 / 0.7);\n  backdrop-filter: blur(20px) saturate(1.4);\n  border: 1px solid oklch(0.92 0.005 260 / 0.6);\n}\n\n.dark .glass-panel {\n  background: oklch(0.18 0.005 260 / 0.7);\n  border: 1px solid oklch(0.95 0 0 / 0.08);\n}\n```\n\n### 6. Noise background class\n```css\n.noise-bg {\n  position: relative;\n}\n\n.noise-bg::before {\n  content: \"\";\n  position: absolute;\n  inset: 0;\n  opacity: 0.03;\n  background-image: url(\"data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E\");\n  background-size: 256px 256px;\n  pointer-events: none;\n  z-index: 0;\n}\n\n.dark .noise-bg::before {\n  opacity: 0.06;\n}\n```\n\n### 7. Gradient mesh class\n```css\n.gradient-mesh {\n  background:\n    radial-gradient(ellipse at 20% 50%, oklch(0.40 0.01 260 / 0.08), transparent 50%),\n    radial-gradient(ellipse at 80% 20%, oklch(0.50 0.01 250 / 0.06), transparent 50%),\n    radial-gradient(ellipse at 50% 80%, oklch(0.55 0.008 240 / 0.05), transparent 50%);\n}\n```\n\n### 8. Animation keyframes\n```css\n@keyframes fadeInUp {\n  from { opacity: 0; transform: translateY(12px); }\n  to { opacity: 1; transform: translateY(0); }\n}\n\n@keyframes fadeIn {\n  from { opacity: 0; }\n  to { opacity: 1; }\n}\n\n.animate-fade-in-up {\n  animation: fadeInUp 0.5s ease-out both;\n}\n\n.animate-fade-in {\n  animation: fadeIn 0.4s ease-out both;\n}\n\n.stagger-children \u003e *:nth-child(1) { animation-delay: 0ms; }\n.stagger-children \u003e *:nth-child(2) { animation-delay: 60ms; }\n.stagger-children \u003e *:nth-child(3) { animation-delay: 120ms; }\n.stagger-children \u003e *:nth-child(4) { animation-delay: 180ms; }\n.stagger-children \u003e *:nth-child(5) { animation-delay: 240ms; }\n.stagger-children \u003e *:nth-child(6) { animation-delay: 300ms; }\n```\n\n### 9. Keep existing scrollbar styles but add dark mode\nKeep the scrollbar styles from the original file but add dark mode variants:\n```css\n.overflow-y-auto { scrollbar-width: thin; scrollbar-color: #e4e4e7 transparent; }\n.dark .overflow-y-auto { scrollbar-color: #3f3f46 transparent; }\n/* ... same webkit scrollbar styles + dark variants */\n```\n\n### 10. Keep focus and scrollbar-none utilities\nKeep the existing `scrollbar-none` and focus utilities from the original file.\n\n## Don't\n- Do NOT add any @import for fonts (fonts are loaded via next/font in layout.tsx)\n- Do NOT add Tailwind @theme directive — we use CSS custom properties directly\n- Do NOT remove the existing keyframe animation for float (may still be used temporarily)","acceptance_criteria":"1. globals.css contains `@custom-variant dark` directive\n2. globals.css defines all OKLCH CSS custom properties for both :root and .dark\n3. globals.css defines .glass-panel with backdrop-filter blur\n4. globals.css defines .noise-bg with SVG fractalNoise background\n5. globals.css defines .gradient-mesh with 3 radial gradients\n6. globals.css defines .animate-fade-in-up and .animate-fade-in keyframe animations\n7. body uses var(--background) and var(--foreground) for base colors\n8. Headings use var(--font-display) font-family\n9. `npm run build` in client/ succeeds","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T17:33:18.327031+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:45:13.574186+08:00","closed_at":"2026-02-18T17:45:13.574186+08:00","close_reason":"dbacf8f feat: rewrite globals.css with OKLCH design tokens + dark mode","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.2","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:33:18.327888+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.3","title":"Theme: Create ThemeProvider and ThemeToggle components","description":"## Files\n- client/src/components/ThemeProvider.tsx (create)\n- client/src/components/ThemeToggle.tsx (create)\n\n## What to do\n\n### 1. Create ThemeProvider.tsx\nCreate `client/src/components/ThemeProvider.tsx` with this exact content:\n```tsx\n\"use client\"\n\nimport { ThemeProvider as NextThemesProvider } from \"next-themes\"\n\nexport function ThemeProvider({ children }: { children: React.ReactNode }) {\n  return (\n    \u003cNextThemesProvider attribute=\"class\" defaultTheme=\"light\" enableSystem={false}\u003e\n      {children}\n    \u003c/NextThemesProvider\u003e\n  )\n}\n```\n\n### 2. Create ThemeToggle.tsx\nCreate `client/src/components/ThemeToggle.tsx`:\n```tsx\n\"use client\"\n\nimport { useEffect, useState } from \"react\"\nimport { useTheme } from \"next-themes\"\n\nexport function ThemeToggle() {\n  const { theme, setTheme } = useTheme()\n  const [mounted, setMounted] = useState(false)\n\n  useEffect(() =\u003e setMounted(true), [])\n\n  if (!mounted) {\n    return \u003cdiv className=\"w-9 h-9\" /\u003e\n  }\n\n  const isDark = theme === \"dark\"\n\n  return (\n    \u003cbutton\n      onClick={() =\u003e setTheme(isDark ? \"light\" : \"dark\")}\n      className=\"p-2 rounded-full transition-colors cursor-pointer\"\n      style={{ color: \"var(--muted-foreground)\" }}\n      aria-label={isDark ? \"Switch to light mode\" : \"Switch to dark mode\"}\n      title={isDark ? \"Switch to light mode\" : \"Switch to dark mode\"}\n    \u003e\n      {isDark ? (\n        \u003csvg className=\"w-5 h-5\" fill=\"none\" stroke=\"currentColor\" viewBox=\"0 0 24 24\"\u003e\n          \u003cpath strokeLinecap=\"round\" strokeLinejoin=\"round\" strokeWidth={1.5} d=\"M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z\" /\u003e\n        \u003c/svg\u003e\n      ) : (\n        \u003csvg className=\"w-5 h-5\" fill=\"none\" stroke=\"currentColor\" viewBox=\"0 0 24 24\"\u003e\n          \u003cpath strokeLinecap=\"round\" strokeLinejoin=\"round\" strokeWidth={1.5} d=\"M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z\" /\u003e\n        \u003c/svg\u003e\n      )}\n    \u003c/button\u003e\n  )\n}\n```\n\nKey implementation details:\n- Uses `mounted` state to prevent SSR hydration mismatch\n- Renders a 9x9 placeholder div on server to prevent layout shift\n- Sun icon shows in dark mode (click → light), Moon icon shows in light mode (click → dark)\n- Uses inline style for color via CSS custom property (theme-aware)\n- Has aria-label and title for accessibility\n\n## Don't\n- Do NOT wire these into the layout yet (that is a separate task)\n- Do NOT add any other theme-related files\n- Do NOT use Tailwind dark: classes for the toggle button styling — use CSS custom properties via inline style since the component needs to work before Tailwind processes the dark variant","acceptance_criteria":"1. client/src/components/ThemeProvider.tsx exists and exports ThemeProvider\n2. client/src/components/ThemeToggle.tsx exists and exports ThemeToggle\n3. ThemeProvider wraps children with NextThemesProvider with attribute=\"class\", defaultTheme=\"light\"\n4. ThemeToggle uses useTheme() from next-themes\n5. ThemeToggle renders sun icon in dark mode, moon icon in light mode\n6. ThemeToggle has mounted guard to prevent hydration mismatch\n7. `npm run build` in client/ succeeds","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T17:33:38.319238+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:49:45.533058+08:00","closed_at":"2026-02-18T17:49:45.533058+08:00","close_reason":"812315d feat: add ThemeProvider and ThemeToggle components","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-0nk.3","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:33:38.319974+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.3","depends_on_id":"hyperindex-0nk.1","type":"blocks","created_at":"2026-02-18T17:33:38.321003+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.4","title":"Layout: Wire ThemeProvider, update body/html, replace logo, update footer","description":"## Files\n- client/src/app/layout.tsx (modify)\n\n## What to do\n\n### 1. Import ThemeProvider\nAdd import at top:\n```tsx\nimport { ThemeProvider } from \"@/components/ThemeProvider\";\n```\n\n### 2. Add suppressHydrationWarning to html tag\nChange `\u003chtml lang=\"en\"\u003e` to `\u003chtml lang=\"en\" suppressHydrationWarning\u003e`.\nThis prevents React warnings when next-themes injects the dark class before hydration.\n\n### 3. Wrap content with ThemeProvider\nInside the body tag, wrap everything with ThemeProvider (inside Providers):\n```tsx\n\u003cProviders\u003e\n  \u003cThemeProvider\u003e\n    \u003cdiv className=\"relative min-h-screen overflow-hidden flex flex-col noise-bg\"\u003e\n      \u003cdiv className=\"gradient-mesh fixed inset-0 -z-10 pointer-events-none\" /\u003e\n      \u003cGeometricBackground /\u003e\n      \u003cHeader /\u003e\n      \u003cmain className=\"relative flex-1 max-w-3xl w-full mx-auto px-4 sm:px-6 pb-8 z-10\"\u003e\n        {children}\n      \u003c/main\u003e\n      {/* Footer */}\n      \u003cfooter className=\"relative py-6 mt-auto z-10\"\u003e\n        \u003cdiv className=\"max-w-3xl mx-auto px-4 sm:px-6\"\u003e\n          \u003ca href=\"https://gainforest.earth\" target=\"_blank\" rel=\"noopener noreferrer\"\n             className=\"flex items-center justify-center gap-1.5 hover:opacity-80 transition-opacity\"\u003e\n            \u003cspan className=\"text-[11px] tracking-wide\" style={{ color: \"var(--muted-foreground)\" }}\u003eMade by\u003c/span\u003e\n            \u003cImage src=\"/gainforest-logo.png\" alt=\"GainForest\" width={14} height={14} className=\"inline-block\" /\u003e\n            \u003cspan className=\"text-[11px] font-medium tracking-wide\" style={{ color: \"var(--muted-foreground)\" }}\u003eGainForest\u003c/span\u003e\n          \u003c/a\u003e\n        \u003c/div\u003e\n      \u003c/footer\u003e\n    \u003c/div\u003e\n  \u003c/ThemeProvider\u003e\n\u003c/Providers\u003e\n```\n\n### 4. Update metadata\nChange the icon references:\n```tsx\nexport const metadata: Metadata = {\n  title: \"Hyperindex\",\n  description: \"AT Protocol AppView Server\",\n  icons: {\n    icon: \"/hypercerts_logo.png\",\n    apple: \"/hypercerts_logo.png\",\n  },\n};\n```\n\n### 5. Add noise-bg and gradient-mesh classes\nThe outermost div inside body should have `noise-bg` class and a sibling gradient-mesh div (see layout structure above). These CSS classes are defined in globals.css (task 2).\n\n## Don't\n- Do NOT modify the Header component (separate task)\n- Do NOT modify GeometricBackground (separate task)\n- Do NOT remove the GeometricBackground import (will be updated separately)\n- Do NOT change the Providers component","acceptance_criteria":"1. html tag has suppressHydrationWarning attribute\n2. ThemeProvider wraps the content inside Providers\n3. The outermost content div has noise-bg class\n4. A gradient-mesh div exists as a fixed background layer\n5. Footer text color uses var(--muted-foreground) instead of hardcoded zinc colors\n6. Metadata icons point to /hypercerts_logo.png\n7. `npm run build` in client/ succeeds","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T17:33:56.040485+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:51:27.059161+08:00","closed_at":"2026-02-18T17:51:27.059161+08:00","close_reason":"a6db65d Layout: Wire ThemeProvider, update body/html, replace logo, update footer","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-0nk.4","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:33:56.041328+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.4","depends_on_id":"hyperindex-0nk.1","type":"blocks","created_at":"2026-02-18T17:33:56.042407+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.4","depends_on_id":"hyperindex-0nk.2","type":"blocks","created_at":"2026-02-18T17:33:56.043242+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.4","depends_on_id":"hyperindex-0nk.3","type":"blocks","created_at":"2026-02-18T17:33:56.044356+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.5","title":"Header: Redesign with glass-panel, hypercerts logo, Hyperindex branding, theme toggle","description":"## Files\n- client/src/components/layout/Header.tsx (modify)\n\n## What to do\nRedesign the Header component to match the hypercerts-scaffold design language.\n\n### 1. Add imports\n```tsx\nimport { ThemeToggle } from \"@/components/ThemeToggle\"\n```\n\n### 2. Replace the nav wrapper\nChange from:\n```tsx\n\u003cnav className=\"relative z-10 py-6\"\u003e\n  \u003cdiv className=\"max-w-3xl mx-auto px-4 sm:px-6\"\u003e\n```\nto a sticky glass-panel navbar:\n```tsx\n\u003cnav className=\"sticky top-0 z-50 glass-panel border-b\" style={{ borderColor: \"var(--border)\" }}\u003e\n  \u003cdiv className=\"h-16 max-w-3xl mx-auto px-4 sm:px-6 flex items-center\"\u003e\n```\n\n### 3. Replace Logo\nChange from:\n```tsx\n\u003cImage src=\"/logo.png\" alt=\"Hyperindex\" width={20} height={20} className=\"opacity-80\" /\u003e\n\u003cspan className=\"text-lg font-medium text-zinc-800 tracking-tight\"\u003ehi\u003c/span\u003e\n```\nto:\n```tsx\n\u003cImage src=\"/hypercerts_logo.png\" alt=\"Hyperindex\" width={22} height={22} /\u003e\n\u003cspan className=\"text-lg font-[family-name:var(--font-syne)] font-bold tracking-tight\" style={{ color: \"var(--foreground)\" }}\u003e\n  Hyperindex\n\u003c/span\u003e\n```\n\n### 4. Update nav link styles\nReplace hardcoded zinc colors with CSS variable-based styles:\n- Active: `style={{ color: \"var(--foreground)\" }}` with `font-medium`\n- Inactive: `style={{ color: \"var(--muted-foreground)\" }}`\n- Use `font-[family-name:var(--font-outfit)]` for nav link text\n\n### 5. Add ThemeToggle to the right side\nAdd `\u003cThemeToggle /\u003e` between the nav links and the user menu area:\n```tsx\n{/* Right side */}\n\u003cdiv className=\"flex items-center gap-2 ml-auto\"\u003e\n  \u003cThemeToggle /\u003e\n  {/* existing user menu button/dropdown */}\n\u003c/div\u003e\n```\n\n### 6. Update dropdown styles for dark mode\nThe dropdown menu currently uses hardcoded `bg-white`, `border-zinc-200/60`, `text-zinc-*` classes. Replace with CSS variable-based styles:\n- Dropdown container: `className=\"glass-panel rounded-xl shadow-lg py-2 z-50\"` with `style={{ borderColor: \"var(--border)\" }}`\n- Text colors: Use `style={{ color: \"var(--foreground)\" }}` and `style={{ color: \"var(--muted-foreground)\" }}`\n- Hover backgrounds: Use `hover:bg-[var(--accent)]` or inline style\n- Active link indicator: Use `style={{ color: \"var(--primary)\" }}` instead of emerald\n\n### 7. Update login modal for dark mode\nReplace hardcoded colors in the login modal:\n- Modal backdrop: keep `bg-black/20 backdrop-blur-sm`\n- Modal card: `className=\"glass-panel rounded-xl shadow-lg p-6\"`\n- Input: Use CSS variables for border/focus colors\n- Heading: Use `font-[family-name:var(--font-syne)]`\n- Primary button: `style={{ backgroundColor: \"var(--primary)\", color: \"var(--primary-foreground)\" }}`\n- Secondary button: `style={{ backgroundColor: \"var(--secondary)\", color: \"var(--secondary-foreground)\" }}`\n\n### 8. Update user avatar fallback\nChange from `bg-emerald-100 text-emerald-700` to:\n```tsx\nstyle={{ backgroundColor: \"var(--accent)\", color: \"var(--accent-foreground)\" }}\nclassName=\"font-[family-name:var(--font-syne)] font-semibold\"\n```\n\n## Don't\n- Do NOT change the navigation links array (Dashboard, Lexicons, Backfill, API Docs)\n- Do NOT change the auth logic (login, logout, session handling)\n- Do NOT change the dropdown behavior (click outside to close, etc.)\n- Do NOT use Tailwind dark: prefix — use CSS custom properties via style prop or the glass-panel class","acceptance_criteria":"1. Nav is sticky top-0 z-50 with glass-panel class\n2. Logo shows hypercerts_logo.png (not logo.png) at 22x22\n3. Logo text reads \"Hyperindex\" (not \"hi\") in Syne bold font\n4. ThemeToggle component is rendered in the header\n5. No hardcoded zinc/emerald color classes remain (all replaced with CSS variables)\n6. Login modal uses glass-panel and CSS variables for colors\n7. Dropdown menu uses glass-panel and CSS variables\n8. `npm run build` in client/ succeeds","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T17:34:20.456786+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:52:50.122481+08:00","closed_at":"2026-02-18T17:52:50.122481+08:00","close_reason":"78649fb redesign Header with glass-panel, hypercerts logo, Hyperindex branding, theme toggle","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.5","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:34:20.457778+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.5","depends_on_id":"hyperindex-0nk.3","type":"blocks","created_at":"2026-02-18T17:34:20.459026+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.5","depends_on_id":"hyperindex-0nk.4","type":"blocks","created_at":"2026-02-18T17:34:20.459904+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.6","title":"Components: Update Card, Button, Input, Alert for dark mode + new tokens","description":"## Files\n- client/src/components/ui/Card.tsx (modify)\n- client/src/components/ui/Button.tsx (modify)\n- client/src/components/ui/Input.tsx (modify)\n- client/src/components/ui/Alert.tsx (modify)\n\n## What to do\nUpdate all four UI primitive components to use CSS custom properties instead of hardcoded zinc/emerald Tailwind classes. This makes them theme-aware for dark mode.\n\n### Card.tsx\nReplace hardcoded color classes with CSS variable equivalents:\n\n```tsx\n// Card container — replace:\n\"rounded-xl border border-zinc-200/60 bg-white shadow-sm\"\n// with:\n\"rounded-xl border shadow-sm\"\n// and add style prop: style={{ backgroundColor: \"var(--card)\", borderColor: \"var(--border)\", color: \"var(--card-foreground)\" }}\n\n// CardTitle — replace:\n\"font-[family-name:var(--font-garamond)] text-xl text-zinc-900 leading-none tracking-tight\"\n// with:\n\"font-[family-name:var(--font-syne)] text-xl leading-none tracking-tight\"\n// and add: style={{ color: \"var(--card-foreground)\" }}\n\n// CardDescription — replace:\n\"text-sm text-zinc-400\"\n// with:\n\"text-sm\"\n// and add: style={{ color: \"var(--muted-foreground)\" }}\n```\n\n### Button.tsx\nReplace the button variant colors:\n```tsx\nconst buttonVariants = {\n  default: \"\", // will use style prop\n  primary: \"\", // will use style prop\n  outline: \"border bg-transparent\", // will use style prop for border/text\n  ghost: \"bg-transparent\", // will use style prop\n  destructive: \"\", // will use style prop\n};\n```\n\nFor each variant, apply colors via a `variantStyles` object that returns inline styles:\n```tsx\nconst variantStyles: Record\u003cstring, React.CSSProperties\u003e = {\n  default: { backgroundColor: \"var(--primary)\", color: \"var(--primary-foreground)\" },\n  primary: { backgroundColor: \"var(--primary)\", color: \"var(--primary-foreground)\" },\n  outline: { borderColor: \"var(--border)\", color: \"var(--foreground)\" },\n  ghost: { color: \"var(--foreground)\" },\n  destructive: { backgroundColor: \"var(--destructive)\", color: \"#fff\" },\n};\n```\n\nApply the inline style from variantStyles in the component render. Keep hover via opacity: `hover:opacity-90`.\n\nReplace the focus ring from `focus-visible:ring-emerald-500/30 focus-visible:border-emerald-400` to `focus-visible:ring-2` with `style` using `var(--ring)`.\n\nUpdate font: replace implicit font with `font-[family-name:var(--font-outfit)]`.\n\n### Input.tsx\nReplace hardcoded colors:\n```tsx\n// Replace:\n\"bg-white/50 border border-zinc-200/60\"\n\"text-zinc-800 placeholder:text-zinc-300\"\n\"focus:ring-emerald-500/30 focus:border-emerald-400\"\n\"focus:bg-white/70\"\n\n// With CSS variable equivalents via style prop:\nstyle={{\n  backgroundColor: \"var(--card)\",\n  borderColor: error ? \"var(--destructive)\" : \"var(--input)\",\n  color: \"var(--foreground)\",\n}}\n// Keep: \"w-full px-3 py-2 text-sm border rounded-lg focus:outline-none focus:ring-2 transition-all disabled:opacity-50 disabled:cursor-not-allowed\"\n```\n\nUpdate label: `style={{ color: \"var(--foreground)\" }}` instead of `text-zinc-600`\nUpdate hint: `style={{ color: \"var(--muted-foreground)\" }}` instead of `text-zinc-300`\n\n### Alert.tsx\nReplace hardcoded variant colors. Keep the semantic colors (blue, emerald/green, amber, red) but add dark mode support via opacity patterns:\n```tsx\nconst variants = {\n  info: \"border\",\n  success: \"border\",\n  warning: \"border\",\n  error: \"border\",\n};\n\nconst variantStyles: Record\u003cstring, React.CSSProperties\u003e = {\n  info: { backgroundColor: \"oklch(0.60 0.15 250 / 0.08)\", color: \"oklch(0.45 0.15 250)\", borderColor: \"oklch(0.60 0.15 250 / 0.2)\" },\n  success: { backgroundColor: \"oklch(0.65 0.15 155 / 0.08)\", color: \"oklch(0.45 0.15 155)\", borderColor: \"oklch(0.65 0.15 155 / 0.2)\" },\n  warning: { backgroundColor: \"oklch(0.75 0.15 75 / 0.08)\", color: \"oklch(0.55 0.15 75)\", borderColor: \"oklch(0.75 0.15 75 / 0.2)\" },\n  error: { backgroundColor: \"oklch(0.60 0.20 25 / 0.08)\", color: \"oklch(0.50 0.20 25)\", borderColor: \"oklch(0.60 0.20 25 / 0.2)\" },\n};\n```\nThese OKLCH colors with alpha channel work in both light and dark mode since they are semi-transparent overlays.\n\n## Don't\n- Do NOT change component APIs (props, exported names, displayName)\n- Do NOT remove the cn() utility usage — keep it for className merging\n- Do NOT change the Alert icons or Button loading spinner logic\n- Do NOT add new dependencies","acceptance_criteria":"1. Card, Button, Input, Alert all compile without errors\n2. No hardcoded zinc-* or emerald-* color classes remain in any of the four files\n3. All components use CSS custom properties (via style prop) for colors\n4. CardTitle uses font-syne (not font-garamond)\n5. Button variants use var(--primary), var(--destructive) etc.\n6. Input uses var(--input) for border, var(--foreground) for text\n7. Alert variants use OKLCH colors with alpha for cross-theme support\n8. `npm run build` in client/ succeeds","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":40,"created_at":"2026-02-18T17:34:48.882113+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:50:21.329807+08:00","closed_at":"2026-02-18T17:50:21.329807+08:00","close_reason":"e0029c7 feat: update Card, Button, Input, Alert for dark mode + CSS tokens","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.6","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:34:48.882955+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.6","depends_on_id":"hyperindex-0nk.2","type":"blocks","created_at":"2026-02-18T17:34:48.884128+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.7","title":"Background: Replace GeometricBackground with simplified noise-bg version","description":"## Files\n- client/src/components/layout/GeometricBackground.tsx (modify)\n\n## What to do\nSimplify the GeometricBackground component. The current version has emerald-colored flowing geometric shapes. Replace it with a much simpler component that complements the noise-bg and gradient-mesh already applied in layout.tsx.\n\nReplace the entire file content with:\n\n```tsx\n\"use client\"\n\nimport { useState, useEffect } from \"react\"\n\nexport function GeometricBackground() {\n  const [showLogo, setShowLogo] = useState(false)\n\n  useEffect(() =\u003e {\n    const interval = setInterval(() =\u003e {\n      setShowLogo(true)\n      setTimeout(() =\u003e setShowLogo(false), 8000)\n    }, 30000)\n\n    const initialTimeout = setTimeout(() =\u003e {\n      setShowLogo(true)\n      setTimeout(() =\u003e setShowLogo(false), 8000)\n    }, 2000)\n\n    return () =\u003e {\n      clearInterval(interval)\n      clearTimeout(initialTimeout)\n    }\n  }, [])\n\n  return (\n    \u003cdiv\n      className=\"fixed inset-0 pointer-events-none select-none overflow-hidden z-0\"\n      aria-hidden=\"true\"\n    \u003e\n      {/* Subtle flowing lines using theme-aware colors */}\n      \u003cdiv className=\"absolute right-[220px] top-0\"\u003e\n        \u003cdiv className=\"w-0.5 h-20 rounded-full animate-[flowDown_9s_linear_infinite] [animation-fill-mode:backwards]\"\n             style={{ background: \"linear-gradient(to bottom, transparent, var(--border), transparent)\" }} /\u003e\n      \u003c/div\u003e\n      \u003cdiv className=\"absolute right-[150px] top-0\"\u003e\n        \u003cdiv className=\"w-0.5 h-16 rounded-full animate-[flowDown_7s_linear_infinite_2s] [animation-fill-mode:backwards]\"\n             style={{ background: \"linear-gradient(to bottom, transparent, var(--border), transparent)\" }} /\u003e\n      \u003c/div\u003e\n      \u003cdiv className=\"absolute right-[80px] top-0\"\u003e\n        \u003cdiv className=\"w-0.5 h-[70px] rounded-full animate-[flowDown_11s_linear_infinite_4s] [animation-fill-mode:backwards]\"\n             style={{ background: \"linear-gradient(to bottom, transparent, var(--border), transparent)\" }} /\u003e\n      \u003c/div\u003e\n\n      {/* Hypercerts logo flow - appears every 30s */}\n      {showLogo \u0026\u0026 (\n        \u003cdiv className=\"absolute right-[140px] top-0 animate-[flowDownLogo_8s_ease-in-out_forwards] opacity-20\"\u003e\n          {/* eslint-disable-next-line @next/next/no-img-element */}\n          \u003cimg src=\"/hypercerts_logo.png\" alt=\"\" width={40} height={40} className=\"opacity-40\" /\u003e\n        \u003c/div\u003e\n      )}\n\n      \u003cstyle jsx\u003e{`\n        @keyframes flowDown {\n          0% { transform: translateY(-100px); }\n          100% { transform: translateY(100vh); }\n        }\n        @keyframes flowDownLogo {\n          0% { transform: translateY(-60px); opacity: 0; }\n          10% { opacity: 1; }\n          90% { opacity: 1; }\n          100% { transform: translateY(100vh); opacity: 0; }\n        }\n      `}\u003c/style\u003e\n    \u003c/div\u003e\n  )\n}\n```\n\nKey changes from current version:\n1. Replace all `emerald-400` colors with `var(--border)` CSS variable (theme-aware)\n2. Remove the geometric shapes (squares, triangles) — just keep subtle flowing lines\n3. Replace the inline GainForest SVG logo with the hypercerts_logo.png image\n4. Keep the same timing/animation behavior\n5. Add z-0 to ensure it stays behind content\n\n## Don't\n- Do NOT change the export name (still `GeometricBackground`)\n- Do NOT change the animation timing (30s interval, 8s display)\n- Do NOT remove the component entirely (layout.tsx imports it)","acceptance_criteria":"1. GeometricBackground no longer contains any emerald/green color references\n2. Flowing lines use var(--border) for theme-aware colors\n3. Logo animation uses hypercerts_logo.png instead of inline SVG\n4. Component still exports as GeometricBackground\n5. `npm run build` in client/ succeeds","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T17:35:09.329559+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:49:42.486326+08:00","closed_at":"2026-02-18T17:49:42.486326+08:00","close_reason":"4143af6 simplify GeometricBackground with theme-aware colors and hypercerts logo","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-0nk.7","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:35:09.330405+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.7","depends_on_id":"hyperindex-0nk.2","type":"blocks","created_at":"2026-02-18T17:35:09.331693+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.8","title":"Pages: Update Dashboard page + sub-components for dark mode","description":"## Files\n- client/src/app/page.tsx (modify)\n- client/src/components/dashboard/StatsCards.tsx (modify)\n- client/src/components/dashboard/ActivityChart.tsx (modify)\n- client/src/components/dashboard/RecentActivity.tsx (modify)\n\n## What to do\nUpdate the Dashboard page and its three sub-components to use CSS custom properties instead of hardcoded zinc/emerald Tailwind classes.\n\n### page.tsx (Dashboard)\nReplace all hardcoded color classes:\n- `text-zinc-900` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-500` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-800` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-400` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-emerald-600`, `text-emerald-700` → `style={{ color: \"var(--primary)\" }}`\n- `group-hover:text-emerald-600`, `group-hover:text-emerald-700` → keep hover but use CSS variable\n- `hover:bg-zinc-50` → `hover:opacity-80` or similar\n- `bg-emerald-50` references → `style={{ backgroundColor: \"var(--accent)\" }}`\n- `font-[family-name:var(--font-garamond)]` → `font-[family-name:var(--font-syne)]`\n\nThe heading \"Dashboard\" should use `font-[family-name:var(--font-syne)]` instead of `font-garamond`.\n\n### StatsCards.tsx\nReplace:\n- `text-emerald-600` → `style={{ color: \"oklch(0.65 0.15 155)\" }}` (keep green for Records semantic)\n- `text-blue-600` → keep as is (blue for Actors is fine)\n- `text-purple-600` → keep as is (purple for Lexicons is fine)\n- `text-zinc-400` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-200` → `style={{ color: \"var(--border)\" }}`\n- `bg-zinc-100` → `style={{ backgroundColor: \"var(--muted)\" }}`\n\n### ActivityChart.tsx\nReplace:\n- `font-[family-name:var(--font-garamond)]` → `font-[family-name:var(--font-syne)]`\n- `text-zinc-900` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-400` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `bg-emerald-50 text-emerald-600` → `style={{ backgroundColor: \"var(--accent)\", color: \"var(--primary)\" }}`\n- `border-zinc-200/60 bg-white` → `style={{ backgroundColor: \"var(--card)\", borderColor: \"var(--border)\" }}`\n- `bg-zinc-50` (skeleton) → `style={{ backgroundColor: \"var(--muted)\" }}`\n- Update Recharts Tooltip `contentStyle` to use CSS variables:\n  ```tsx\n  contentStyle={{\n    backgroundColor: \"var(--card)\",\n    border: \"1px solid var(--border)\",\n    borderRadius: \"0.75rem\",\n    fontSize: \"12px\",\n    color: \"var(--foreground)\",\n  }}\n  ```\n- Update CartesianGrid stroke: `stroke=\"var(--border)\"`\n- Update XAxis/YAxis stroke: `stroke=\"var(--muted-foreground)\"`\n\n### RecentActivity.tsx\nReplace:\n- `font-[family-name:var(--font-garamond)]` → `font-[family-name:var(--font-syne)]`\n- `text-zinc-900` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-400` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-800` → `style={{ color: \"var(--foreground)\" }}`\n- `border-zinc-200/60 bg-white` → `style={{ backgroundColor: \"var(--card)\", borderColor: \"var(--border)\" }}`\n- `divide-zinc-100` → style with `var(--border)` for divider color\n- `bg-zinc-50` → style with `var(--muted)` \n- `hover:bg-zinc-50` → `hover:opacity-90`\n- Operation badges: Keep the semantic colors (emerald=create, blue=update, amber=delete) but use OKLCH with alpha for cross-theme:\n  - create: `style={{ backgroundColor: \"oklch(0.65 0.15 155 / 0.1)\", color: \"oklch(0.55 0.15 155)\" }}`\n  - update: `style={{ backgroundColor: \"oklch(0.60 0.15 250 / 0.1)\", color: \"oklch(0.50 0.15 250)\" }}`\n  - delete: `style={{ backgroundColor: \"oklch(0.75 0.15 75 / 0.1)\", color: \"oklch(0.60 0.15 75)\" }}`\n\n## Don't\n- Do NOT change component props or APIs\n- Do NOT change the data fetching logic\n- Do NOT change the Recharts Area colors (keep green/blue/amber for creates/updates/deletes)\n- Do NOT change functionality — only visual styling","acceptance_criteria":"1. No hardcoded zinc-* or emerald-* Tailwind color classes remain in any of the four files\n2. All text uses CSS variables for color (var(--foreground), var(--muted-foreground))\n3. All backgrounds use CSS variables (var(--card), var(--muted), var(--accent))\n4. font-garamond references replaced with font-syne\n5. Recharts Tooltip and grid use CSS variables\n6. `npm run build` in client/ succeeds","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T17:35:33.327352+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:53:58.353165+08:00","closed_at":"2026-02-18T17:53:58.353165+08:00","close_reason":"4b86216 update Dashboard page and sub-components for dark mode","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.8","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:35:33.328235+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.8","depends_on_id":"hyperindex-0nk.4","type":"blocks","created_at":"2026-02-18T17:35:33.329516+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.8","depends_on_id":"hyperindex-0nk.6","type":"blocks","created_at":"2026-02-18T17:35:33.330641+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-0nk.9","title":"Pages: Update Docs page — rename branding + dark mode styles","description":"## Files\n- client/src/app/docs/page.tsx (modify)\n\n## What to do\nUpdate the API docs page for new branding and dark mode support.\n\n### 1. Update API_ENDPOINT constant\nThe constant `API_ENDPOINT` is currently hardcoded to `https://hypergoat-app-production.up.railway.app`. Leave it as is for now — this is a deployment URL that should be configured via env vars, but that is out of scope. Just note: do NOT rename this URL.\n\n### 2. Update branding text\nOn line 631 (approximately), change:\n```tsx\n\u003cstrong className=\"text-zinc-700\"\u003eHyperindex\u003c/strong\u003e (\u003cem\u003ehi\u003c/em\u003e, formerly Hypergoat) is{\" \"}\n```\nto:\n```tsx\n\u003cstrong style={{ color: \"var(--foreground)\" }}\u003eHyperindex\u003c/strong\u003e is{\" \"}\n```\nRemove the \"(hi, formerly Hypergoat)\" parenthetical entirely.\n\n### 3. Replace all font-garamond references\nReplace every instance of `font-[family-name:var(--font-garamond)]` with `font-[family-name:var(--font-syne)]`.\nThis appears in all `\u003ch2\u003e` and `\u003ch3\u003e` headings throughout the page.\n\n### 4. Replace all hardcoded color classes\nApply the same pattern as other pages — replace Tailwind color classes with CSS custom properties:\n\n**Text colors:**\n- `text-zinc-900` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-800` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-700` → `style={{ color: \"var(--foreground)\" }}`\n- `text-zinc-600` → `style={{ color: \"var(--secondary-foreground)\" }}`\n- `text-zinc-500` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-400` → `style={{ color: \"var(--muted-foreground)\" }}`\n- `text-zinc-300` → `style={{ color: \"var(--border)\" }}`\n- `text-emerald-600` → `style={{ color: \"var(--primary)\" }}`\n\n**Backgrounds:**\n- `bg-white` → `style={{ backgroundColor: \"var(--card)\" }}`\n- `bg-zinc-50` → `style={{ backgroundColor: \"var(--muted)\" }}`\n- `bg-zinc-100` → `style={{ backgroundColor: \"var(--muted)\" }}`\n- `bg-emerald-50` → `style={{ backgroundColor: \"var(--accent)\" }}`\n- `bg-emerald-100` → `style={{ backgroundColor: \"var(--accent)\" }}`\n\n**Borders:**\n- `border-zinc-200/60` → `style={{ borderColor: \"var(--border)\" }}`\n- `border-zinc-200` → `style={{ borderColor: \"var(--border)\" }}`\n- `border-zinc-100` → `style={{ borderColor: \"var(--border)\" }}`\n- `border-emerald-200/60` → `style={{ borderColor: \"var(--border)\" }}`\n\n**Code blocks (CodeBlock component):**\n- `bg-zinc-800` (header bar) → keep dark for code blocks — they look good dark in both themes\n- `bg-zinc-900` (code content) → keep dark\n- `bg-zinc-700/50` (copy button) → keep dark\n- `text-zinc-100` (code text) → keep light text for dark code blocks\n- These code blocks should stay dark-themed regardless of page theme (like most code editors)\n\n**LanguageTabs component:**\n- `bg-zinc-100` → `style={{ backgroundColor: \"var(--muted)\" }}`\n- `bg-white text-zinc-900` (active) → `style={{ backgroundColor: \"var(--card)\", color: \"var(--foreground)\" }}`\n- `text-zinc-500` → `style={{ color: \"var(--muted-foreground)\" }}`\n\n**Protocol Details cards:**\n- `bg-emerald-100` → `style={{ backgroundColor: \"oklch(0.65 0.15 155 / 0.15)\" }}`\n- `text-emerald-600` → `style={{ color: \"oklch(0.55 0.15 155)\" }}`\n- `bg-blue-100` → `style={{ backgroundColor: \"oklch(0.60 0.15 250 / 0.15)\" }}`\n- `text-blue-600` → `style={{ color: \"oklch(0.50 0.15 250)\" }}`\n\n**Inline code elements:**\n- `bg-zinc-100 text-zinc-700` → `style={{ backgroundColor: \"var(--muted)\", color: \"var(--foreground)\" }}`\n- `bg-emerald-100` → `style={{ backgroundColor: \"var(--accent)\" }}`\n\n**Tips section gradient:**\n- `border-emerald-200/60 bg-gradient-to-br from-emerald-50/50 to-white` → `style={{ borderColor: \"var(--border)\", backgroundColor: \"var(--card)\" }}`\n\n**Tab buttons:**\n- Active: `style={{ backgroundColor: \"var(--card)\", color: \"var(--foreground)\" }}`\n- Inactive: `style={{ color: \"var(--muted-foreground)\" }}`\n\n### 5. Endpoint code blocks\nThe endpoint display code blocks (`bg-zinc-900 text-emerald-400`, `text-blue-400`, `text-purple-400`) should stay as dark-themed blocks. These look good in both light and dark mode since they are code snippets. Leave the colors of the endpoint URL text as-is.\n\n## Don't\n- Do NOT change the API_ENDPOINT URL value\n- Do NOT change the code examples content (only their wrapping component styles)\n- Do NOT change the CodeBlock highlighting logic (highlightJS, highlightPython, highlightShell)\n- Do NOT change the syntax highlighting token colors inside code blocks (those are fine as-is on dark backgrounds)\n- Do NOT change the component structure or data flow","acceptance_criteria":"1. No \"(hi, formerly Hypergoat)\" text remains\n2. All headings use font-syne instead of font-garamond\n3. No hardcoded zinc-*/emerald-* classes remain except inside CodeBlock dark backgrounds\n4. LanguageTabs use CSS variables for colors\n5. Protocol detail cards use OKLCH colors\n6. Code blocks remain dark-themed in both light and dark mode\n7. `npm run build` in client/ succeeds","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T17:36:02.714257+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:55:17.39867+08:00","closed_at":"2026-02-18T17:55:17.39867+08:00","close_reason":"0198d61 docs page: update branding, font-syne, dark mode CSS vars","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-0nk.9","depends_on_id":"hyperindex-0nk","type":"parent-child","created_at":"2026-02-18T17:36:02.715349+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.9","depends_on_id":"hyperindex-0nk.4","type":"blocks","created_at":"2026-02-18T17:36:02.716722+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-0nk.9","depends_on_id":"hyperindex-0nk.6","type":"blocks","created_at":"2026-02-18T17:36:02.717721+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm","title":"Epic: Replace Jetstream+Backfill with Tap sidecar","description":"## Why\nHyperindex currently has ~2,500 lines of complex data ingestion infrastructure across two subsystems:\n- **Jetstream consumer** (810 lines) — WebSocket client to Bluesky's Jetstream service\n- **Backfill worker** (1,329 lines) — 3-phase pipeline with DID resolution, CAR/CBOR parsing, 3 levels of concurrency semaphores\n\nCritical gaps in current implementation:\n1. **No cryptographic verification** — we accept unverified data from Jetstream\n2. **No ordering guarantees** — backfill and live events race (backfill may arrive after live events)\n3. **No at-least-once delivery** — events lost on crash between receive and DB write\n4. **Identity events ignored** — handle changes, account status not tracked\n\nBluesky's official **Tap** utility (https://github.com/bluesky-social/indigo/tree/main/cmd/tap) handles all of this as a sidecar process. It verifies repo structure + MST integrity + identity signatures, manages backfill automatically, provides strict per-repo ordering, and outputs simple JSON over WebSocket with acks.\n\n## What Success Looks Like\n- Tap runs as a sidecar (Docker or binary) alongside Hyperindex\n- Hyperindex connects to Tap's WebSocket at ws://localhost:2480/channel\n- All record events (create/update/delete) stored in RecordsRepository\n- Identity events update ActorsRepository (handle, status)\n- GraphQL subscriptions receive events from Tap\n- Admin backfill callbacks use Tap's /repos/add API instead of custom backfill code\n- internal/jetstream/ and internal/backfill/ packages deleted\n- Heavy deps removed: bluesky-social/indigo, fxamacker/cbor, ipfs/go-cid, hashicorp/go-retryablehttp\n- All existing tests still pass\n- ~2,100 lines deleted, ~500 lines added\n\n## Key Constraints\n- All changes on the tap-feature branch (branched from filter-feature)\n- Tap event format: {id, type: \"record\"|\"identity\", record: {live, rev, did, collection, rkey, action, cid, record}, identity: {did, handle, isActive, status}}\n- Must support ack-based delivery (send ack after DB write succeeds)\n- Must handle Tap reconnection gracefully\n- Admin single-actor backfill → POST /repos/add to Tap\n- Admin full-network backfill → configure TAP_SIGNAL_COLLECTION or TAP_FULL_NETWORK on Tap side\n- Config env vars: TAP_URL (default ws://localhost:2480), TAP_ADMIN_PASSWORD, TAP_DISABLE_ACKS\n- Keep gorilla/websocket dep (already used) or use nhooyr/websocket (already used for subscriptions)","status":"closed","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-18T16:11:26.42114+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:22:46.227411+08:00","closed_at":"2026-02-18T16:22:46.227411+08:00","close_reason":"5dfe636 All 8 tasks complete — Tap sidecar integration with TAP_ENABLED feature flag","labels":["scope:medium"]}
+{"id":"hyperindex-2hm.1","title":"Add Tap config env vars to config package","description":"## Files\n- internal/config/config.go (modify)\n- internal/config/config_test.go (modify)\n\n## What to do\nAdd Tap-related configuration fields to the Config struct and Load function. These replace the Jetstream and Backfill env vars (but do NOT remove the old ones yet — that happens in a later task).\n\n1. Add fields to Config struct (after the Backfill section, around line 57):\n\\`\\`\\`go\n// Tap (replaces Jetstream + Backfill)\nTapURL           string // Tap WebSocket URL (default: ws://localhost:2480)\nTapAdminPassword string // Tap admin API password for Basic auth\nTapDisableAcks   bool   // Fire-and-forget mode (default: false)\nTapEnabled       bool   // Use Tap instead of Jetstream+Backfill (default: false)\n\\`\\`\\`\n\n2. Add env var loading in Load() (after the Backfill section):\n\\`\\`\\`go\n// Tap\nTapURL:           getEnv(\"TAP_URL\", \"ws://localhost:2480\"),\nTapAdminPassword: getEnv(\"TAP_ADMIN_PASSWORD\", \"\"),\nTapDisableAcks:   getEnvBool(\"TAP_DISABLE_ACKS\", false),\nTapEnabled:       getEnvBool(\"TAP_ENABLED\", false),\n\\`\\`\\`\n\n3. Add Tap fields to LogConfig() (redact TapAdminPassword):\n\\`\\`\\`go\n\"tap_enabled\", c.TapEnabled,\n\"tap_url\", c.TapURL,\n\"tap_admin_password_set\", c.TapAdminPassword != \"\",\n\"tap_disable_acks\", c.TapDisableAcks,\n\\`\\`\\`\n\n## Dont\n- Do NOT remove existing Jetstream/Backfill config fields yet\n- Do NOT modify main.go\n- Do NOT add validation that prevents running without Tap","acceptance_criteria":"1. Config struct has TapURL, TapAdminPassword, TapDisableAcks, TapEnabled fields\n2. TAP_URL env var defaults to \\\"ws://localhost:2480\\\"\n3. TAP_ENABLED defaults to false\n4. LogConfig logs tap_enabled, tap_url, tap_admin_password_set (not the password itself), tap_disable_acks\n5. Existing Jetstream/Backfill config fields still present and working\n6. go test ./internal/config/... passes\n7. go test ./... passes","status":"closed","priority":1,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T16:11:42.034827+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:15:41.766867+08:00","closed_at":"2026-02-18T16:15:41.766867+08:00","close_reason":"68efb07 Add Tap config env vars to config package","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-2hm.1","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:11:42.036029+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm.2","title":"Define Tap event types and JSON parser","description":"## Files\n- internal/tap/event.go (create)\n- internal/tap/event_test.go (create)\n\n## What to do\nCreate the internal/tap/ package with event type definitions matching Tap's JSON output format. These are the Go structs that the Tap client will parse incoming WebSocket messages into.\n\n1. Create internal/tap/event.go:\n\\`\\`\\`go\n// Package tap provides a client for Bluesky's Tap sync utility.\npackage tap\n\nimport (\n    \"encoding/json\"\n    \"fmt\"\n)\n\n// EventType is the top-level event type from Tap.\ntype EventType string\n\nconst (\n    EventTypeRecord   EventType = \"record\"\n    EventTypeIdentity EventType = \"identity\"\n)\n\n// ActionType is the record action type.\ntype ActionType string\n\nconst (\n    ActionCreate ActionType = \"create\"\n    ActionUpdate ActionType = \"update\"\n    ActionDelete ActionType = \"delete\"\n)\n\n// Event is the top-level Tap event envelope.\ntype Event struct {\n    ID       int64          \\`json:\\\"id\\\"\\`\n    Type     EventType      \\`json:\\\"type\\\"\\`\n    Record   *RecordEvent   \\`json:\\\"record,omitempty\\\"\\`\n    Identity *IdentityEvent \\`json:\\\"identity,omitempty\\\"\\`\n}\n\n// RecordEvent is a record change event from Tap.\ntype RecordEvent struct {\n    Live       bool            \\`json:\\\"live\\\"\\`\n    Rev        string          \\`json:\\\"rev\\\"\\`\n    DID        string          \\`json:\\\"did\\\"\\`\n    Collection string          \\`json:\\\"collection\\\"\\`\n    RKey       string          \\`json:\\\"rkey\\\"\\`\n    Action     ActionType      \\`json:\\\"action\\\"\\`\n    CID        string          \\`json:\\\"cid,omitempty\\\"\\`\n    Record     json.RawMessage \\`json:\\\"record,omitempty\\\"\\`  // Only for create/update\n}\n\n// URI returns the AT-URI for this record event.\nfunc (r *RecordEvent) URI() string {\n    return fmt.Sprintf(\"at://%s/%s/%s\", r.DID, r.Collection, r.RKey)\n}\n\n// IdentityEvent is an identity change event from Tap.\ntype IdentityEvent struct {\n    DID      string \\`json:\\\"did\\\"\\`\n    Handle   string \\`json:\\\"handle\\\"\\`\n    IsActive bool   \\`json:\\\"isActive\\\"\\`\n    Status   string \\`json:\\\"status\\\"\\`  // active, takendown, suspended, deactivated, deleted\n}\n\n// ParseEvent parses a Tap event from JSON bytes.\nfunc ParseEvent(data []byte) (*Event, error) {\n    var event Event\n    if err := json.Unmarshal(data, \u0026event); err != nil {\n        return nil, fmt.Errorf(\"failed to parse tap event: %w\", err)\n    }\n    if event.Type == \"\" {\n        return nil, fmt.Errorf(\"tap event missing type field\")\n    }\n    return \u0026event, nil\n}\n\n// IsRecord returns true if this is a record event.\nfunc (e *Event) IsRecord() bool {\n    return e.Type == EventTypeRecord \u0026\u0026 e.Record != nil\n}\n\n// IsIdentity returns true if this is an identity event.\nfunc (e *Event) IsIdentity() bool {\n    return e.Type == EventTypeIdentity \u0026\u0026 e.Identity != nil\n}\n\\`\\`\\`\n\n2. Create event_test.go with table-driven tests:\n- Parse valid record create event (with record body)\n- Parse valid record delete event (no record body, no cid)\n- Parse valid identity event\n- Parse event with missing type field → error\n- Parse invalid JSON → error\n- RecordEvent.URI() returns correct AT-URI\n- IsRecord/IsIdentity helpers\n\n## Dont\n- Do NOT create the WebSocket client yet — that is a separate task\n- Do NOT import any external packages — only stdlib\n- Do NOT duplicate jetstream event types — this is a clean replacement","acceptance_criteria":"1. internal/tap/event.go exists with Event, RecordEvent, IdentityEvent types\n2. ParseEvent correctly parses Tap JSON format: {id: 12345, type: \"record\", record: {live: true, rev: \"...\", did: \"did:plc:abc\", collection: \"app.bsky.feed.post\", rkey: \"abc\", action: \"create\", cid: \"bafyrei...\", record: {\"text\": \"hello\"}}}\n3. ParseEvent correctly parses identity events: {id: 12346, type: \"identity\", identity: {did: \"did:plc:abc\", handle: \"alice.bsky.social\", isActive: true, status: \"active\"}}\n4. ParseEvent returns error for missing type field\n5. RecordEvent.URI() returns \"at://did:plc:abc/app.bsky.feed.post/abc\"\n6. go test -v ./internal/tap/... passes with all test cases\n7. go test ./... passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T16:12:02.155562+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:15:55.244406+08:00","closed_at":"2026-02-18T16:15:55.244406+08:00","close_reason":"7e1d850 feat: add internal/tap package with event types and JSON parser","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-2hm.2","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:12:02.156673+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm.3","title":"Implement Tap HTTP admin client for /repos/add and /repos/remove","description":"## Files\n- internal/tap/admin.go (create)\n- internal/tap/admin_test.go (create)\n\n## What to do\nCreate an HTTP client for Tap's admin API endpoints. This is used by the admin backfill callbacks to add/remove repos from Tap's tracking list.\n\n1. Create internal/tap/admin.go:\n\\`\\`\\`go\n// AdminClient communicates with Tap's HTTP API for repo management.\ntype AdminClient struct {\n    baseURL  string // e.g., \"http://localhost:2480\"\n    password string // Basic auth password (empty = no auth)\n    client   *http.Client\n}\n\n// NewAdminClient creates a new Tap admin HTTP client.\nfunc NewAdminClient(baseURL, password string) *AdminClient\n\n// AddRepos adds DIDs to Tap's tracking list, triggering backfill.\n// POST /repos/add with body {\"dids\": [\"did:plc:abc\", ...]}\nfunc (c *AdminClient) AddRepos(ctx context.Context, dids []string) error\n\n// RemoveRepos removes DIDs from Tap's tracking list.\n// POST /repos/remove with body {\"dids\": [\"did:plc:abc\", ...]}\nfunc (c *AdminClient) RemoveRepos(ctx context.Context, dids []string) error\n\n// Health checks if Tap is healthy.\n// GET /health — expects {\"status\":\"ok\"}\nfunc (c *AdminClient) Health(ctx context.Context) error\n\n// RepoInfo gets info about a tracked repo.\n// GET /info/:did\nfunc (c *AdminClient) RepoInfo(ctx context.Context, did string) (*RepoInfoResponse, error)\n\\`\\`\\`\n\n2. Basic auth: if password is set, add header `Authorization: Basic base64(\"admin:\" + password)` to all requests.\n\n3. Error handling: return wrapped errors with HTTP status code context.\n\n4. HTTP client: use stdlib http.Client with 30s timeout.\n\n## Dont\n- Do NOT add WebSocket logic here — that is the separate client task\n- Do NOT import any external HTTP packages — use stdlib net/http\n- Do NOT add retry logic — keep it simple, Tap handles its own retries","acceptance_criteria":"1. AdminClient.AddRepos sends POST to /repos/add with JSON body {\"dids\": [...]}\n2. AdminClient.RemoveRepos sends POST to /repos/remove with JSON body {\"dids\": [...]}\n3. AdminClient.Health sends GET to /health and verifies response\n4. Basic auth header is included when password is configured\n5. No auth header when password is empty\n6. HTTP errors return wrapped error with status code\n7. Table-driven tests using httptest.NewServer for all methods\n8. go test -v ./internal/tap/... passes\n9. go test ./... passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T16:12:17.345313+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:16:10.59648+08:00","closed_at":"2026-02-18T16:16:10.59648+08:00","close_reason":"85ed81f implement Tap HTTP admin client","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-2hm.3","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:12:17.346524+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm.4","title":"Implement Tap WebSocket consumer with ack support","description":"## Files\n- internal/tap/consumer.go (create)\n- internal/tap/consumer_test.go (create)\n\n## What to do\nCreate the core Tap WebSocket consumer that connects to Tap's /channel endpoint, receives events, dispatches them, and sends acks. This replaces internal/jetstream/client.go + consumer.go.\n\n1. Create internal/tap/consumer.go:\n\\`\\`\\`go\n// ConsumerConfig configures the Tap consumer.\ntype ConsumerConfig struct {\n    TapURL      string // WebSocket URL (e.g., \"ws://localhost:2480\")\n    DisableAcks bool   // Fire-and-forget mode\n}\n\n// EventHandler processes Tap events. Return nil to ack, error to nack.\ntype EventHandler interface {\n    HandleRecord(ctx context.Context, event *RecordEvent) error\n    HandleIdentity(ctx context.Context, event *IdentityEvent) error\n}\n\n// Consumer connects to Tap's WebSocket and dispatches events.\ntype Consumer struct {\n    config  ConsumerConfig\n    handler EventHandler\n    // ... internal state\n}\n\nfunc NewConsumer(config ConsumerConfig, handler EventHandler) *Consumer\n\n// Start connects to Tap and begins processing events.\n// Blocks until context is cancelled or fatal error.\n// Automatically reconnects on connection loss with exponential backoff.\nfunc (c *Consumer) Start(ctx context.Context) error\n\n// Stop gracefully shuts down the consumer.\nfunc (c *Consumer) Stop()\n\\`\\`\\`\n\n2. WebSocket connection:\n   - Connect to {TapURL}/channel\n   - Use gorilla/websocket (already in go.mod)\n   - Read text messages (JSON events)\n   - Parse with tap.ParseEvent()\n   - Dispatch to EventHandler.HandleRecord or HandleIdentity\n   - After successful handling, send ack: write text message with the event ID as string (e.g., \"12345\")\n   - If DisableAcks is true, skip ack sending\n\n3. Reconnection:\n   - On connection loss, exponential backoff: 1s → 2s → 4s → ... → 2min cap\n   - Reset backoff on successful connection\n   - Log reconnection attempts\n\n4. Stats tracking (same pattern as current jetstream consumer):\n\\`\\`\\`go\ntype Stats struct {\n    EventsReceived int64\n    RecordsCreated int64\n    RecordsUpdated int64\n    RecordsDeleted int64\n    IdentityEvents int64\n    Errors         int64\n}\nfunc (c *Consumer) Stats() Stats\n\\`\\`\\`\n\n## Dont\n- Do NOT implement EventHandler here — that is the next task\n- Do NOT handle cursor management — Tap manages cursors via acks\n- Do NOT use nhooyr/websocket — use gorilla/websocket for consistency with existing code\n- Do NOT import any repository packages","acceptance_criteria":"1. Consumer connects to {TapURL}/channel via WebSocket\n2. Consumer parses incoming JSON messages as Tap events\n3. Record events dispatched to handler.HandleRecord, identity events to handler.HandleIdentity\n4. After successful handler return, consumer sends event ID as text message (ack)\n5. When DisableAcks=true, no ack is sent\n6. On connection loss, consumer reconnects with exponential backoff (1s to 2min)\n7. Consumer.Stop() gracefully closes the WebSocket connection\n8. Stats() returns event counts\n9. Tests use a mock WebSocket server (httptest) to verify connect, receive, ack, reconnect\n10. go test -v ./internal/tap/... passes\n11. go test ./... passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T16:12:35.965149+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:18:53.850762+08:00","closed_at":"2026-02-18T16:18:53.850762+08:00","close_reason":"8469c62 implement Tap WebSocket consumer with ack support","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-2hm.4","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:12:35.966442+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.4","depends_on_id":"hyperindex-2hm.2","type":"blocks","created_at":"2026-02-18T16:12:35.967988+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm.5","title":"Implement Tap EventHandler that stores records and publishes to PubSub","description":"## Files\n- internal/tap/handler.go (create)\n- internal/tap/handler_test.go (create)\n\n## What to do\nImplement the EventHandler interface from the consumer task. This is the bridge between Tap events and the existing repository/subscription layer. It mirrors what internal/jetstream/consumer.go's handleCommit() does today.\n\n1. Create internal/tap/handler.go:\n\\`\\`\\`go\n// IndexHandler implements EventHandler and stores events in the database.\ntype IndexHandler struct {\n    records  *repositories.RecordsRepository\n    actors   *repositories.ActorsRepository\n    activity *repositories.JetstreamActivityRepository // reuse existing activity repo\n    pubsub   *subscription.PubSub\n}\n\nfunc NewIndexHandler(\n    records *repositories.RecordsRepository,\n    actors *repositories.ActorsRepository,\n    activity *repositories.JetstreamActivityRepository,\n    pubsub *subscription.PubSub,\n) *IndexHandler\n\\`\\`\\`\n\n2. HandleRecord implementation:\n\\`\\`\\`go\nfunc (h *IndexHandler) HandleRecord(ctx context.Context, event *RecordEvent) error {\n    uri := event.URI()\n\n    switch event.Action {\n    case ActionCreate, ActionUpdate:\n        // Ensure actor exists\n        h.actors.Upsert(ctx, event.DID, \"\") // empty handle, identity events update it\n        \n        // Store record\n        _, err := h.records.Insert(ctx, uri, event.CID, event.DID, event.Collection, string(event.Record))\n        if err != nil {\n            return fmt.Errorf(\"failed to insert record: %w\", err)\n        }\n        \n        // Log activity (if activity repo available)\n        if h.activity != nil {\n            h.activity.LogActivity(ctx, time.Now(), string(event.Action), event.Collection, event.DID, event.RKey, string(event.Record))\n        }\n        \n        // Publish to GraphQL subscriptions\n        eventType := subscription.EventCreate\n        if event.Action == ActionUpdate {\n            eventType = subscription.EventUpdate\n        }\n        h.pubsub.PublishRecord(eventType, uri, event.CID, event.DID, event.Collection, event.Record)\n        \n    case ActionDelete:\n        h.records.Delete(ctx, uri)\n        h.pubsub.PublishRecord(subscription.EventDelete, uri, \"\", event.DID, event.Collection, nil)\n        if h.activity != nil {\n            h.activity.LogActivity(ctx, time.Now(), \"delete\", event.Collection, event.DID, event.RKey, \"\")\n        }\n    }\n    return nil\n}\n\\`\\`\\`\n\n3. HandleIdentity implementation:\n\\`\\`\\`go\nfunc (h *IndexHandler) HandleIdentity(ctx context.Context, event *IdentityEvent) error {\n    // Update actor with handle from identity event\n    return h.actors.Upsert(ctx, event.DID, event.Handle)\n}\n\\`\\`\\`\n\nThis is a key improvement over the current system: we now process identity events and store handles.\n\n## Dont\n- Do NOT modify the existing repositories — use their existing Insert/Delete/Upsert methods\n- Do NOT add new database tables or migrations\n- Do NOT modify the PubSub interface\n- Do NOT log every event at Info level in production — use Debug for individual records, Info for batches","acceptance_criteria":"1. HandleRecord with ActionCreate calls records.Insert and pubsub.PublishRecord(EventCreate, ...)\n2. HandleRecord with ActionUpdate calls records.Insert and pubsub.PublishRecord(EventUpdate, ...)\n3. HandleRecord with ActionDelete calls records.Delete and pubsub.PublishRecord(EventDelete, ...)\n4. HandleRecord ensures actor exists via actors.Upsert for create/update\n5. HandleIdentity calls actors.Upsert with DID and handle from the event\n6. Activity is logged when activity repo is non-nil\n7. Tests use mock repositories (or real SQLite) to verify correct calls\n8. go test -v ./internal/tap/... passes\n9. go test ./... passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":40,"created_at":"2026-02-18T16:12:55.65983+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:18:36.125908+08:00","closed_at":"2026-02-18T16:18:36.125908+08:00","close_reason":"5ac3f2e Implement Tap IndexHandler that stores records and publishes to PubSub","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-2hm.5","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:12:55.662054+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.5","depends_on_id":"hyperindex-2hm.2","type":"blocks","created_at":"2026-02-18T16:12:55.663845+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm.6","title":"Wire Tap consumer into main.go with TAP_ENABLED feature flag","description":"## Files\n- cmd/hypergoat/main.go (modify)\n\n## What to do\nAdd a conditional branch in main.go that uses the Tap consumer instead of Jetstream+Backfill when TAP_ENABLED=true. The old code paths remain for backward compatibility.\n\n1. Add import for internal/tap package.\n\n2. Modify the run() function flow. After setupGraphQL returns collections:\n\\`\\`\\`go\nif cfg.TapEnabled {\n    startTap(cfg, svc, pubsub, adminHandler, bg)\n} else {\n    // Existing code\n    startJetstream(cfg, svc, pubsub, collections, adminHandler, bg)\n    startBackfill(cfg, svc)\n}\n\\`\\`\\`\n\n3. Create startTap function:\n\\`\\`\\`go\nfunc startTap(cfg *config.Config, svc *services, pubsub *subscription.PubSub, adminHandler *admin.Handler, bg *backgroundServices) {\n    tapURL := cfg.TapURL\n    \n    // Create handler that stores records and publishes to subscriptions\n    handler := tap.NewIndexHandler(svc.records, svc.actors, svc.activity, pubsub)\n    \n    // Create and start consumer\n    consumer := tap.NewConsumer(tap.ConsumerConfig{\n        TapURL:      tapURL,\n        DisableAcks: cfg.TapDisableAcks,\n    }, handler)\n    \n    // Store consumer reference for clean shutdown\n    // Add tapConsumer field to backgroundServices struct\n    bg.tapConsumer = consumer\n    \n    tapCtx, tapCancel := context.WithCancel(context.Background())\n    bg.tapCancel = tapCancel\n    \n    go func() {\n        slog.Info(\"Starting Tap consumer\", \"url\", tapURL, \"disable_acks\", cfg.TapDisableAcks)\n        if err := consumer.Start(tapCtx); err != nil {\n            slog.Error(\"Tap consumer error\", \"error\", err)\n        }\n    }()\n    \n    // Wire admin backfill callbacks to use Tap's /repos/add API\n    if adminHandler != nil {\n        tapHTTPURL := strings.Replace(strings.Replace(tapURL, \"ws://\", \"http://\", 1), \"wss://\", \"https://\", 1)\n        adminClient := tap.NewAdminClient(tapHTTPURL, cfg.TapAdminPassword)\n        \n        adminHandler.Resolver().SetBackfillCallback(func(ctx context.Context, did string) error {\n            return adminClient.AddRepos(ctx, []string{did})\n        })\n        \n        adminHandler.Resolver().SetFullBackfillCallback(func(ctx context.Context) error {\n            return fmt.Errorf(\"full network backfill not supported via Tap admin API — configure TAP_SIGNAL_COLLECTION or TAP_FULL_NETWORK on the Tap sidecar instead\")\n        })\n    }\n    \n    slog.Info(\"Tap consumer started (replaces Jetstream + Backfill)\")\n}\n\\`\\`\\`\n\n4. Add tapConsumer and tapCancel to backgroundServices struct:\n\\`\\`\\`go\ntype backgroundServices struct {\n    // ... existing fields ...\n    tapConsumer *tap.Consumer\n    tapCancel   context.CancelFunc\n}\n\\`\\`\\`\n\n5. Update backgroundServices.Stop() to stop Tap consumer:\n\\`\\`\\`go\nif bg.tapConsumer != nil {\n    bg.tapConsumer.Stop()\n}\nif bg.tapCancel != nil {\n    bg.tapCancel()\n}\n\\`\\`\\`\n\n## Dont\n- Do NOT remove the existing startJetstream or startBackfill functions\n- Do NOT remove the Jetstream/Backfill imports\n- Do NOT change behavior when TAP_ENABLED=false (default)\n- Do NOT remove the lexicon change callback for dynamic collection updates (that stays with Jetstream path only — Tap uses collection filters configured on the Tap side)","acceptance_criteria":"1. When TAP_ENABLED=false (default), existing Jetstream+Backfill behavior is unchanged\n2. When TAP_ENABLED=true, startTap is called instead of startJetstream+startBackfill\n3. Tap consumer is started in a goroutine with proper context and cancellation\n4. backgroundServices.Stop() cleanly shuts down the Tap consumer\n5. Admin single-actor backfill calls Tap's /repos/add API\n6. Admin full-network backfill returns informative error directing user to configure Tap\n7. go build ./... succeeds\n8. go test ./... passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T16:13:18.554294+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:20:25.020387+08:00","closed_at":"2026-02-18T16:20:25.020387+08:00","close_reason":"f781a70 Wire Tap consumer into main.go with TAP_ENABLED feature flag","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-2hm.6","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:13:18.555453+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.6","depends_on_id":"hyperindex-2hm.1","type":"blocks","created_at":"2026-02-18T16:13:18.55691+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.6","depends_on_id":"hyperindex-2hm.3","type":"blocks","created_at":"2026-02-18T16:13:18.557962+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.6","depends_on_id":"hyperindex-2hm.4","type":"blocks","created_at":"2026-02-18T16:13:18.558989+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.6","depends_on_id":"hyperindex-2hm.5","type":"blocks","created_at":"2026-02-18T16:13:18.560021+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm.7","title":"Add Tap deployment docs and docker-compose sidecar config","description":"## Files\n- README.md (modify)\n- docker-compose.tap.yml (create)\n- .env.example (modify)\n\n## What to do\nAdd documentation and docker-compose configuration for running Tap as a sidecar.\n\n1. Update README.md — add a new section \"Using Tap (Recommended)\" under the existing data ingestion docs:\n   - Explain what Tap is and why it's recommended (crypto verification, ordering guarantees, simplified architecture)\n   - Show how to run Tap alongside Hyperindex\n   - Document TAP_ENABLED, TAP_URL, TAP_ADMIN_PASSWORD, TAP_DISABLE_ACKS env vars\n   - Show example: docker-compose up with Tap sidecar\n   - Show example: adding repos to track via Tap admin API\n   - Mention TAP_SIGNAL_COLLECTION for auto-discovery\n   - Keep the existing Jetstream+Backfill docs but mark them as \"Legacy Mode\"\n\n2. Create docker-compose.tap.yml:\n\\`\\`\\`yaml\nversion: \"3.8\"\nservices:\n  tap:\n    image: ghcr.io/bluesky-social/indigo/tap:latest\n    ports:\n      - \"2480:2480\"\n    volumes:\n      - tap-data:/data\n    environment:\n      TAP_DATABASE_URL: \"sqlite:///data/tap.db\"\n      TAP_COLLECTION_FILTERS: \"${JETSTREAM_COLLECTIONS}\"\n      TAP_SIGNAL_COLLECTION: \"${TAP_SIGNAL_COLLECTION:-}\"\n      TAP_DISABLE_ACKS: \"false\"\n      TAP_ADMIN_PASSWORD: \"${TAP_ADMIN_PASSWORD:-}\"\n    restart: unless-stopped\n\n  hyperindex:\n    build: .\n    ports:\n      - \"8080:8080\"\n    depends_on:\n      - tap\n    environment:\n      TAP_ENABLED: \"true\"\n      TAP_URL: \"ws://tap:2480\"\n      TAP_ADMIN_PASSWORD: \"${TAP_ADMIN_PASSWORD:-}\"\n      DATABASE_URL: \"${DATABASE_URL:-sqlite:data/hypergoat.db}\"\n      # ... other env vars\n    restart: unless-stopped\n\nvolumes:\n  tap-data:\n\\`\\`\\`\n\n3. Update .env.example with Tap env vars.\n\n## Dont\n- Do NOT remove existing docker-compose.yml or Dockerfile\n- Do NOT change the Dockerfile\n- Do NOT make Tap the only option — keep backward compatibility with Jetstream mode","acceptance_criteria":"1. README.md has a \"Using Tap (Recommended)\" section explaining the setup\n2. README.md marks Jetstream+Backfill as \"Legacy Mode\"\n3. docker-compose.tap.yml is valid YAML and runnable\n4. .env.example includes TAP_ENABLED, TAP_URL, TAP_ADMIN_PASSWORD, TAP_DISABLE_ACKS\n5. Documentation explains TAP_SIGNAL_COLLECTION for auto-discovery\n6. go test ./... passes (no code changes, just docs)","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T16:13:37.056187+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:21:47.007541+08:00","closed_at":"2026-02-18T16:21:47.007541+08:00","close_reason":"6b6f4c0 Add Tap deployment docs and docker-compose sidecar config","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-2hm.7","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:13:37.057297+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.7","depends_on_id":"hyperindex-2hm.6","type":"blocks","created_at":"2026-02-18T16:13:37.058872+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2hm.8","title":"Add /health proxy endpoint to check Tap sidecar status","description":"## Files\n- cmd/hypergoat/main.go (modify) — setupRouter or startTap function\n- internal/tap/admin.go (uses existing Health method)\n\n## What to do\nWhen TAP_ENABLED=true, enhance the existing /health endpoint to also check Tap's health. If Tap is unreachable, the health check should indicate degraded status.\n\n1. In the existing /health handler (or a new /health/tap endpoint), add a Tap health check:\n\\`\\`\\`go\n// If Tap is enabled, also check Tap's health\nif cfg.TapEnabled {\n    tapHTTPURL := strings.Replace(strings.Replace(cfg.TapURL, \"ws://\", \"http://\", 1), \"wss://\", \"https://\", 1)\n    adminClient := tap.NewAdminClient(tapHTTPURL, cfg.TapAdminPassword)\n    if err := adminClient.Health(r.Context()); err != nil {\n        // Return 200 but with degraded status\n        json.NewEncoder(w).Encode(map[string]interface{}{\n            \"status\": \"degraded\",\n            \"tap\": \"unreachable\",\n            \"error\": err.Error(),\n        })\n        return\n    }\n}\n\\`\\`\\`\n\n2. Add a /stats enhancement: when Tap is enabled, include Tap consumer stats (events received, records created, etc.) in the /stats response.\n\n## Dont\n- Do NOT make the main /health fail when Tap is temporarily down — use \"degraded\" status\n- Do NOT create a separate admin client for each health check — store it on backgroundServices or similar\n- Do NOT add this when TAP_ENABLED=false","acceptance_criteria":"1. When TAP_ENABLED=true, /health includes Tap status in the response\n2. When Tap is reachable, health shows \"ok\" with \"tap\": \"ok\"\n3. When Tap is unreachable, health shows \"degraded\" with \"tap\": \"unreachable\"\n4. /stats includes Tap consumer stats when TAP_ENABLED=true\n5. When TAP_ENABLED=false, /health behaves exactly as before\n6. go build ./... succeeds\n7. go test ./... passes","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T16:13:50.18969+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:22:11.051009+08:00","closed_at":"2026-02-18T16:22:11.051009+08:00","close_reason":"5dfe636 feat: add Tap health check to /health and /stats endpoints","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-2hm.8","depends_on_id":"hyperindex-2hm","type":"parent-child","created_at":"2026-02-18T16:13:50.190924+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-2hm.8","depends_on_id":"hyperindex-2hm.6","type":"blocks","created_at":"2026-02-18T16:13:50.19256+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-2rz","title":"Support batch lexicon registration via comma/newline-separated NSIDs","description":"## Files\n- client/src/app/lexicons/page.tsx (modify)\n\n## What to do\nUpdate the lexicon registration form to accept multiple NSIDs at once, separated by commas, spaces, or newlines.\n\n### Changes to `handleRegister`:\n1. Split `nsidInput` by commas, newlines, or whitespace: `nsidInput.split(/[,\\n\\s]+/).map(s =\u003e s.trim()).filter(Boolean)`\n2. Validate each NSID with the existing `isValidNsid()` function. If any are invalid, show an error listing the invalid ones and don't submit.\n3. Call `registerMutation.mutate()` sequentially for each valid NSID. Use a loop with `mutateAsync` so they run one at a time.\n4. Show progress: update the success message as each one completes, e.g. \"Registered 3/5 lexicons...\" and then \"Registered 5 lexicons\" when done.\n5. Clear the input only after all succeed.\n\n### Changes to the input element:\n1. Replace the single-line `\u003cinput\u003e` with a `\u003ctextarea\u003e` so users can paste multi-line lists.\n2. Keep the same styling (font-mono, rounded-lg, border, etc). Set `rows={1}` as default but allow it to grow.\n3. Update placeholder to: `\"Enter NSIDs (comma or newline separated)...\"`\n\n### Edge cases:\n- Empty entries after splitting should be filtered out\n- Duplicate NSIDs in the input should be deduplicated before submitting\n- If one NSID fails mid-batch, show the error but keep already-registered ones (don't roll back)\n- The Register button should show loading state during the batch and be disabled\n\n## Don't\n- Change the GraphQL mutation (backend stays as-is, one NSID per call)\n- Modify the tree view, search, or delete functionality\n- Change any other file","acceptance_criteria":"1. `npm run build` succeeds in client/ directory\n2. Pasting `app.gainforest.dwc.occurrence, app.gainforest.dwc.taxon, app.gainforest.dwc.event` into the input and clicking Register calls registerLexicon 3 times\n3. Pasting a newline-separated list works the same way\n4. Invalid NSIDs in a batch are caught and shown in the error message before any mutations fire\n5. Duplicate NSIDs in the input are deduplicated (only one mutation per unique NSID)\n6. The input field is a textarea that accepts multi-line paste\n7. Progress feedback is shown during batch registration","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-19T12:09:36.692704+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T12:10:48.788943+08:00","closed_at":"2026-02-19T12:10:48.788943+08:00","close_reason":"6275449 feat: support batch lexicon registration via comma/newline-separated NSIDs","labels":["scope:small"]}
+{"id":"hyperindex-3gm","title":"Test gap: coerceRequiredFields not tested via single-record (ByUri) resolver path (from hyperindex-vz7.3)","description":"## Files\n- internal/graphql/schema/builder_test.go (modify)\n\n## What to do\nAdd a test `TestCoerceRequiredFields_SingleRecordResolver` that verifies the `ByUri` (single record) resolver path also coerces missing required fields.\n\nUse the existing `setupCoercionTestDB` and `buildActivitySchema` helpers already in the file. The test should:\n\n1. Set up a DB with a record missing `title` and `shortDescription`: `{\"createdAt\":\"2025-01-01T00:00:00Z\"}`\n2. Build the activity schema\n3. Execute a GraphQL query using the single-record query field:\n   ```graphql\n   {\n     orgHypercertsClaimActivityByUri(uri: \"at://did:plc:test/org.hypercerts.claim.activity/rkey1\") {\n       title\n       shortDescription\n     }\n   }\n   ```\n4. Assert: no GraphQL errors, `title` is `\"\"`, `shortDescription` is `\"\"`\n\nFollow the exact same assertion pattern used in `TestCoerceRequiredFields_MissingFields` but adapted for the single-record response shape (no edges/nodes, just direct fields).\n\n## Dont\n- Do not modify production code\n- Do not duplicate the collection resolver tests — only test the ByUri path\n- Do not use external test frameworks","acceptance_criteria":"1. go test -v -run TestCoerceRequiredFields_SingleRecordResolver ./internal/graphql/schema/... passes\n2. The test queries via orgHypercertsClaimActivityByUri (not the collection query)\n3. The test asserts that missing required string fields are coerced to empty string\n4. go test ./... passes (no regressions)","status":"closed","priority":3,"issue_type":"bug","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-19T20:20:38.520059+08:00","created_by":"einstein.climateai.org","updated_at":"2026-03-05T15:27:57.55139+08:00","closed_at":"2026-02-19T20:23:58.003339+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-3gm","depends_on_id":"hyperindex-vz7","type":"discovered-from","created_at":"2026-02-19T20:20:41.357178+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-3jy","title":"Fix: spurious 'closed unexpectedly' warn logged on clean shutdown (from hyperindex-md3.10)","description":"Review of hyperindex-md3.10 (commit b28087c) found: the ctx.Err() guard was only added to the err != nil branch. The else branch (when runOnce returns nil, i.e. server sent a clean close frame) still logs slog.Warn('Tap connection closed unexpectedly, will reconnect') without checking ctx.Err(). If the server sends a clean close frame at the same moment the context is cancelled, this warning fires during intentional shutdown. Fix: add ctx.Err() check to the else branch too: } else { if ctx.Err() != nil { return ctx.Err() } slog.Warn(...) }. Also: TestConsumer_ShutdownNoSpuriousLog only checks for Error-level messages; it would not catch this spurious Warn. Evidence: consumer.go lines 133-137.","status":"open","priority":3,"issue_type":"bug","owner":"einstein.climateai.org","created_at":"2026-02-18T16:49:47.686073+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:49:47.686073+08:00","dependencies":[{"issue_id":"hyperindex-3jy","depends_on_id":"hyperindex-md3.10","type":"discovered-from","created_at":"2026-02-18T16:49:49.968822+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s","title":"Epic: GraphQL Filtering, Sorting \u0026 Query Completeness","description":"## Why\nThe public GraphQL API currently lacks essential query capabilities that developers need to efficiently consume the API. There are no WHERE filters, no sorting control, no DID/author filtering, no backward pagination, no totalCount, no max page size, and no search. The only way to find specific records is by exact URI lookup or paginating through entire collections newest-first. This makes the API unusable for any non-trivial frontend or data integration.\n\n## What Success Looks Like\n- Developers can filter collection queries by any scalar field (eq, neq, gt, lt, gte, lte, in, contains, startsWith, isNull)\n- Developers can filter by DID (author) on any collection query\n- Developers can sort by any scalar field ASC or DESC\n- Connections return totalCount when requested (opt-in)\n- Pagination has a max page size (100) to prevent abuse\n- Backward pagination (last/before) works per Relay spec\n- A basic LIKE-based search query exists for cross-collection text search\n- Typed records expose did and rkey metadata fields\n\n## Key Constraints\n- All changes must work on both SQLite and PostgreSQL (use Executor interface)\n- JSON field filtering uses existing JSONExtract/JSONExtractPath helpers\n- Field name validation via existing validJSONFieldName regex (SQL injection prevention)\n- No breaking changes to existing queries (additive only)\n- All existing tests must continue to pass (go test ./...)\n- Performance: totalCount must be opt-in (only computed when selected)","status":"open","priority":1,"issue_type":"epic","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","created_at":"2026-02-18T14:22:55.632055+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:22:43.275042+08:00","labels":["scope:medium"]}
+{"id":"hyperindex-49s.1","title":"Scaffold shared filter input types (StringFilter, IntFilter, etc.)","description":"## Files\n- internal/graphql/types/filters.go (create)\n- internal/graphql/types/filters_test.go (create)\n\n## What to do\nCreate a new file `internal/graphql/types/filters.go` that defines shared GraphQL InputObject types for field-level filtering. These are reused across all collections.\n\nDefine these 5 input types using `graphql.NewInputObject()`:\n\n1. **StringFilterInput** — fields: `eq: String`, `neq: String`, `in: [String!]`, `contains: String`, `startsWith: String`, `isNull: Boolean`\n2. **IntFilterInput** — fields: `eq: Int`, `neq: Int`, `gt: Int`, `lt: Int`, `gte: Int`, `lte: Int`, `in: [Int!]`, `isNull: Boolean`\n3. **FloatFilterInput** — fields: `eq: Float`, `neq: Float`, `gt: Float`, `lt: Float`, `gte: Float`, `lte: Float`, `isNull: Boolean`\n4. **BooleanFilterInput** — fields: `eq: Boolean`, `isNull: Boolean`\n5. **DateTimeFilterInput** — fields: `eq: DateTime`, `neq: DateTime`, `gt: DateTime`, `lt: DateTime`, `gte: DateTime`, `lte: DateTime`, `isNull: Boolean` (use the existing `DateTimeScalar` from mapper.go)\n\nExport each as a package-level `var` (e.g., `var StringFilterInput = graphql.NewInputObject(...)`).\n\nAlso export a function `FilterInputForLexiconType(lexiconType, format string) *graphql.InputObject` that maps lexicon property types to the correct filter input:\n- `\"string\"` + `\"datetime\"` format → `DateTimeFilterInput`\n- `\"string\"` (no format or other format) → `StringFilterInput`\n- `\"integer\"` → `IntFilterInput`\n- `\"number\"` → `FloatFilterInput`\n- `\"boolean\"` → `BooleanFilterInput`\n- All other types → return `nil` (not filterable)\n\nWrite table-driven tests in `filters_test.go` that verify:\n- Each input type has the correct fields with correct GraphQL types\n- `FilterInputForLexiconType` returns the right input for each lexicon type/format combo\n- Non-filterable types return nil\n\n## Dont\n- Do not import or modify any existing files\n- Do not define per-collection types here (that is a separate task)\n- Do not add resolver logic or SQL generation","acceptance_criteria":"1. `go build ./...` passes\n2. `go test -v ./internal/graphql/types/...` passes with all new tests green\n3. Each of the 5 InputObject types has exactly the fields listed above\n4. `FilterInputForLexiconType` returns correct type for string, string+datetime, integer, number, boolean\n5. `FilterInputForLexiconType` returns nil for blob, bytes, unknown, ref, union, array, object, record\n6. Package doc comment exists on filters.go","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T14:23:13.541776+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T14:55:10.627075+08:00","closed_at":"2026-02-18T14:55:10.627075+08:00","close_reason":"f3de82e feat: scaffold shared filter input types","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.1","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:23:13.543048+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.10","title":"Wire sorting into resolvers and generalize cursor encoding","description":"## Files\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nConnect the `sortBy` and `sortDirection` arguments from typed collection queries through the resolver to the sorted repository method. Generalize cursor encoding to support sort-key-aware cursors.\n\n### 1. Generalize cursor encoding/decoding\n\nThe current `encodeCursor(indexedAt, uri)` and `decodeCursor(cursor)` functions (builder.go lines ~636-652) encode `base64(timestamp|uri)`. Generalize to encode N values:\n\n```go\n// encodeCursorValues encodes multiple cursor component values.\nfunc encodeCursorValues(values ...string) string {\n    return base64.URLEncoding.EncodeToString([]byte(strings.Join(values, \"|\")))\n}\n\n// decodeCursorValues decodes a cursor into its component values.\nfunc decodeCursorValues(cursor string) ([]string, error) {\n    data, err := base64.URLEncoding.DecodeString(cursor)\n    if err != nil { return nil, fmt.Errorf(\"invalid cursor\") }\n    return strings.Split(string(data), \"|\"), nil\n}\n```\n\nKeep the old `encodeCursor`/`decodeCursor` functions as wrappers for backward compatibility, calling the new generalized functions.\n\n### 2. Modify `resolveRecordConnection` to extract sort args\n\nAfter extracting `first`, `after`, and `where` args, also extract sort:\n\n```go\nvar sortOpt *repositories.SortOption\nif sortByArg, ok := p.Args[\"sortBy\"].(string); ok \u0026\u0026 sortByArg != \"\" {\n    direction := \"DESC\" // default\n    if dirArg, ok := p.Args[\"sortDirection\"].(string); ok {\n        direction = dirArg\n    }\n    sortOpt = \u0026repositories.SortOption{Field: sortByArg, Direction: direction}\n}\n```\n\n### 3. Switch to the sorted repository method\n\nReplace the call to `GetByCollectionFilteredWithKeysetCursor` (from task 4) with `GetByCollectionSortedWithKeysetCursor`, passing the sort option and cursor values.\n\n### 4. Build sort-aware cursors for each edge\n\nWhen building edge cursors in the results loop:\n- If sorting by default (indexed_at), cursor = `encodeCursorValues(rec.IndexedAt.Format(...), rec.URI)` (same as before)\n- If sorting by a JSON field, extract the sort field value from the parsed JSON data map and use it: `encodeCursorValues(sortFieldValue, rec.URI)`\n- If sorting by a column (did, collection, etc.), extract from the Record struct\n\n### 5. Decode sort-aware cursors\n\nWhen an `after` cursor is provided:\n- Decode with `decodeCursorValues(after)` → get `[sortFieldValue, uri]`\n- Pass these as `afterCursorValues` to the repository method\n\n## Dont\n- Do not modify the repository layer (done in task 9)\n- Do not modify sort enum generation (done in task 8)\n- Do not add sorting to the generic `records` query\n- Do not break existing cursor format — old 2-value cursors still decode correctly with the generalized decoder","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. A query with `sortBy: \"indexed_at\", sortDirection: \"ASC\"` returns records oldest-first\n4. A query with sortBy set to a JSON field correctly sorts by that field\n5. Pagination cursors work correctly with custom sort fields\n6. A query WITHOUT sortBy/sortDirection returns records in default order (indexed_at DESC) — backward compatible\n7. Old-format cursors (from before this change) still decode correctly\n8. The generic `records` query still works without sort arguments","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T14:25:58.388179+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:08:11.608991+08:00","closed_at":"2026-02-18T15:08:11.608991+08:00","close_reason":"7d5f062 Wire sorting into resolvers and generalize cursor encoding","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.10","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:25:58.389195+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.10","depends_on_id":"hyperindex-49s.8","type":"blocks","created_at":"2026-02-18T14:25:58.390942+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.10","depends_on_id":"hyperindex-49s.9","type":"blocks","created_at":"2026-02-18T14:25:58.392103+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.10","depends_on_id":"hyperindex-49s.4","type":"blocks","created_at":"2026-02-18T14:25:58.393164+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.11","title":"Populate totalCount on public connections (opt-in)","description":"## Files\n- internal/database/repositories/records.go (modify)\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nThe `totalCount` field exists on typed connection types but always returns null. Populate it when the client requests it, using field selection introspection.\n\n### 1. Add GetCollectionCount to repository (records.go)\n\n```go\n// GetCollectionCount returns the total record count for a collection.\nfunc (r *RecordsRepository) GetCollectionCount(ctx context.Context, collection string) (int64, error) {\n    sqlStr := fmt.Sprintf(\"SELECT COUNT(*) FROM record WHERE collection = %s\", r.db.Placeholder(1))\n    // ... execute and scan\n}\n```\n\nAlso add a filtered version:\n```go\n// GetCollectionCountFiltered returns the count with optional DID and field filters applied.\nfunc (r *RecordsRepository) GetCollectionCountFiltered(\n    ctx context.Context, collection string, filters []FieldFilter, did string,\n) (int64, error)\n```\n\n### 2. Add field selection check in builder.go\n\n```go\nfunc isTotalCountRequested(p graphql.ResolveParams) bool {\n    for _, field := range p.Info.FieldASTs {\n        if field.SelectionSet == nil { continue }\n        for _, sel := range field.SelectionSet.Selections {\n            if f, ok := sel.(*ast.Field); ok \u0026\u0026 f.Name.Value == \"totalCount\" {\n                return true\n            }\n        }\n    }\n    return false\n}\n```\n\nImport `\"github.com/graphql-go/graphql/language/ast\"` for the Field type.\n\n### 3. Populate totalCount in resolveRecordConnection\n\nAt the end of `resolveRecordConnection` (around line 462), add:\n\n```go\nresult := map[string]interface{}{\n    \"edges\":    edges,\n    \"pageInfo\": pageInfo,\n}\nif isTotalCountRequested(p) {\n    count, err := repos.Records.GetCollectionCountFiltered(ctx, collection, filters, didFilter)\n    if err == nil {\n        result[\"totalCount\"] = int(count)\n    }\n}\nreturn result, nil\n```\n\n### 4. Fix emptyConnection inconsistency\n\nThe `emptyConnection()` helper currently sets `totalCount: 0`. Keep this (it is correct for empty results).\n\n### 5. Add totalCount to GenericRecordConnection too\n\nThe `genericRecordConnectionType` (builder.go line ~300) is missing the `totalCount` field entirely. Add it:\n```go\n\"totalCount\": \u0026graphql.Field{\n    Type:        graphql.Int,\n    Description: \"Total number of items (if known)\",\n},\n```\n\n## Dont\n- Do not make totalCount NonNull (keep it nullable Int)\n- Do not always compute totalCount — only when the field is selected in the query\n- Do not modify admin API totalCount (it already works correctly)","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. A query that selects `totalCount` returns the correct integer count\n4. A query that does NOT select `totalCount` does not execute the COUNT SQL\n5. `GetCollectionCount` returns accurate count for a collection\n6. `GetCollectionCountFiltered` respects DID and field filters\n7. `emptyConnection()` still returns `totalCount: 0`\n8. `GenericRecordConnection` now has a `totalCount` field in its schema\n9. Admin API totalCount behavior is unchanged","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":40,"created_at":"2026-02-18T14:26:16.300672+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:04:00.384628+08:00","closed_at":"2026-02-18T15:04:00.384628+08:00","close_reason":"140f601 feat: populate totalCount on public connections opt-in","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.11","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:26:16.301865+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.11","depends_on_id":"hyperindex-49s.2","type":"blocks","created_at":"2026-02-18T14:26:16.303383+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.12","title":"Add backward pagination support (last/before)","description":"## Files\n- internal/graphql/query/connection.go (modify)\n- internal/graphql/schema/builder.go (modify)\n- internal/database/repositories/records.go (modify)\n- internal/database/repositories/records_test.go (modify)\n\n## What to do\nImplement backward pagination (`last`/`before`) per the Relay Connection Spec.\n\n### 1. Add `last` and `before` arguments to ConnectionArgs() (connection.go)\n\n```go\n\"last\": \u0026graphql.ArgumentConfig{\n    Type:        graphql.Int,\n    Description: \"Number of items to return from the end\",\n},\n\"before\": \u0026graphql.ArgumentConfig{\n    Type:        graphql.String,\n    Description: \"Cursor to paginate before (backward pagination)\",\n},\n```\n\n### 2. Add reverse-order query to repository (records.go)\n\nAdd a new method or extend the sorted method to handle backward pagination:\n\n```go\nfunc (r *RecordsRepository) GetByCollectionReversedWithKeysetCursor(\n    ctx context.Context,\n    collection string,\n    filters []FieldFilter,\n    did string,\n    sort *SortOption,\n    limit int,\n    beforeCursorValues []string,\n) ([]*Record, error)\n```\n\nThis method:\n- Reverses the sort direction (DESC→ASC, ASC→DESC) in the ORDER BY\n- Reverses the cursor comparison operator (\u003c becomes \u003e, \u003e becomes \u003c)\n- After fetching, reverses the result slice in-memory so edges are in the correct order\n- Fetches `limit+1` to detect `hasPreviousPage`\n\n### 3. Update resolveRecordConnection in builder.go\n\n- Extract `last` and `before` from `p.Args`\n- Validate: if both `first`/`after` AND `last`/`before` are provided, return an error: \"cannot use both first/after and last/before\"\n- If `last`/`before` are used, call the reverse query method\n- Apply `ClampPageSize` to `last` as well\n- Set `hasPreviousPage` correctly: for backward pagination, use the N+1 technique (same as hasNextPage for forward)\n- Set `hasNextPage` correctly: for backward pagination, `before != \"\"` indicates there are next pages\n\n### 4. Update generic records query args (builder.go inline args)\n\nAdd `last` and `before` arguments to the inline args for the `records` query too.\n\n## Dont\n- Do not support using first/after AND last/before simultaneously (return error)\n- Do not modify the admin API pagination\n- Do not change cursor encoding format","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. A query with `last: 5` returns the last 5 records (oldest 5 in default DESC order)\n4. A query with `last: 5, before: cursor` returns 5 records before the cursor\n5. `hasPreviousPage` is correctly computed using N+1 technique for backward pagination\n6. `hasNextPage` works correctly for backward pagination\n7. Using `first` and `last` together returns a GraphQL error\n8. `last` is clamped to MaxPageSize (100)\n9. Forward pagination (first/after) still works identically to before\n10. The generic `records` query also supports last/before","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":60,"created_at":"2026-02-18T14:26:34.962048+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:17:06.03473+08:00","closed_at":"2026-02-18T15:17:06.03473+08:00","close_reason":"a4a38bc feat: add backward pagination support (last/before)","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.12","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:26:34.96307+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.12","depends_on_id":"hyperindex-49s.6","type":"blocks","created_at":"2026-02-18T14:26:34.964567+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.12","depends_on_id":"hyperindex-49s.9","type":"blocks","created_at":"2026-02-18T14:26:34.965704+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.13","title":"Add LIKE-based cross-collection search query","description":"## Files\n- internal/database/repositories/records.go (modify)\n- internal/database/repositories/records_test.go (modify)\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nAdd a basic text search capability using LIKE/ILIKE on the JSON column. This is Phase 1 of search — simple but functional. FTS can be added later.\n\n### 1. Add Search method to RecordsRepository (records.go)\n\n```go\n// Search performs a LIKE-based text search on record JSON content.\n// On PostgreSQL, uses case-insensitive ILIKE. On SQLite, LIKE is already case-insensitive for ASCII.\nfunc (r *RecordsRepository) Search(\n    ctx context.Context,\n    query string,\n    collection string,  // optional, empty = cross-collection\n    limit int,\n    afterTimestamp string,\n    afterURI string,\n) ([]*Record, error)\n```\n\nSQL construction:\n- Base: `SELECT ... FROM record WHERE json LIKE %s` (SQLite) or `WHERE json::text ILIKE %s` (PostgreSQL)  \n- Value: wrap query in `%`: `\"%\"+query+\"%\"`\n- If collection non-empty, add `AND collection = ?`\n- Keyset cursor: same `AND (indexed_at \u003c ? OR (indexed_at = ? AND uri \u003c ?))` pattern\n- ORDER BY: `indexed_at DESC, uri DESC`\n- LIMIT: `limit + 1`\n\nFor PostgreSQL, cast json to text: `json::text ILIKE ?`. Check if the Executor has a helper for this or just use dialect branching.\n\n### 2. Add `search` field to GraphQL query type (builder.go)\n\nIn `buildQueryType()`, add a new field:\n\n```go\nfields[\"search\"] = \u0026graphql.Field{\n    Type:        genericRecordConnectionType,\n    Description: \"Search records by text content\",\n    Args: graphql.FieldConfigArgument{\n        \"query\": \u0026graphql.ArgumentConfig{\n            Type:        graphql.NewNonNull(graphql.String),\n            Description: \"Search text (matched against record JSON content)\",\n        },\n        \"collection\": \u0026graphql.ArgumentConfig{\n            Type:        graphql.String,\n            Description: \"Optional collection NSID to restrict search\",\n        },\n        \"first\": \u0026graphql.ArgumentConfig{\n            Type:         graphql.Int,\n            DefaultValue: 20,\n        },\n        \"after\": \u0026graphql.ArgumentConfig{\n            Type: graphql.String,\n        },\n    },\n    Resolve: b.createSearchResolver(),\n}\n```\n\n### 3. Add search resolver (builder.go)\n\n```go\nfunc (b *Builder) createSearchResolver() graphql.FieldResolveFn\n```\n\n- Extract `query`, `collection`, `first`, `after` from args\n- Apply `ClampPageSize` to first\n- Validate: `query` must be non-empty, minimum 2 characters\n- Call `repos.Records.Search(ctx, query, collection, first+1, afterTimestamp, afterURI)`\n- Build generic record connection (same pattern as the generic records resolver)\n\n### 4. Tests\n\n- Test Search returns records containing the search term\n- Test Search with collection filter narrows results\n- Test Search with pagination\n- Test empty query returns error\n- Test very short query (1 char) returns error\n\n## Dont\n- Do not add FTS5 or tsvector (that is a future phase)\n- Do not add search to typed collection queries (this is a standalone query)\n- Do not allow empty or single-character queries (minimum 2 chars)\n- Do not add new database indexes (LIKE search is inherently O(n) — fine for Phase 1)","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. `search(query: \"hello\")` returns records whose JSON contains \"hello\"\n4. `search(query: \"hello\", collection: \"app.bsky.feed.post\")` only searches that collection\n5. Pagination works on search results (first/after)\n6. Search query shorter than 2 characters returns a GraphQL error\n7. Empty query string returns a GraphQL error\n8. Search is case-insensitive on both SQLite and PostgreSQL\n9. The search field returns `GenericRecordConnection` type (not typed records)\n10. LIKE value properly escapes % and _ in the user query to prevent wildcard injection","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T14:26:57.899071+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T14:59:18.423051+08:00","closed_at":"2026-02-18T14:59:18.423051+08:00","close_reason":"264d333 Add LIKE-based cross-collection search query","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.13","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:26:57.899953+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.13","depends_on_id":"hyperindex-49s.6","type":"blocks","created_at":"2026-02-18T14:26:57.901396+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.14","title":"Add integration tests for filter/sort/search end-to-end","description":"## Files\n- internal/integration/graphql_filter_test.go (create)\n\n## What to do\nWrite end-to-end integration tests that exercise the full filter/sort/search stack by sending GraphQL queries through the HTTP handler and verifying responses. These tests validate that the schema builder, resolvers, and repository work together correctly.\n\n### Test setup\nUse the existing integration test patterns from `internal/integration/` (if any exist) or from `internal/graphql/handler_test.go`. Set up:\n- An in-memory SQLite database\n- A registry with at least one test lexicon (create a minimal lexicon JSON fixture with string, integer, datetime, and boolean fields)\n- Insert several test records with known JSON content\n- Build the schema and create the GraphQL handler\n\n### Test cases\n\n1. **Filter by string eq**: Query with `where: {title: {eq: \"Test\"}}`, verify only matching records returned\n2. **Filter by string contains**: Query with `where: {title: {contains: \"est\"}}`, verify substring matching\n3. **Filter by integer gt/lt**: Query with `where: {score: {gt: 5, lt: 10}}`, verify range filtering\n4. **Filter by DID**: Query with `where: {did: {eq: \"did:plc:test123\"}}`, verify DID filtering\n5. **Filter by isNull**: Query with `where: {optionalField: {isNull: true}}`, verify null filtering\n6. **Sort by field ASC**: Query with `sortBy: \"title\", sortDirection: \"ASC\"`, verify ascending order\n7. **Sort by field DESC**: Query with `sortBy: \"indexed_at\", sortDirection: \"DESC\"`, verify descending order\n8. **Sort + pagination**: Sort by field, paginate with cursor, verify correct continuation\n9. **totalCount opt-in**: Query selecting totalCount, verify it returns correct integer\n10. **totalCount omitted**: Query NOT selecting totalCount (verify via test that no COUNT query runs — can check by verifying null/omitted)\n11. **Max page size**: Query with `first: 500`, verify at most 100 records returned\n12. **Search**: Query `search(query: \"searchterm\")`, verify matching records found\n13. **Search with collection filter**: Query `search(query: \"term\", collection: \"test.collection\")`, verify filtered\n14. **Backward compatibility**: Query without any where/sort args, verify same behavior as before\n\n## Dont\n- Do not test admin API\n- Do not test subscriptions\n- Do not test OAuth\n- Do not start a real HTTP server — use httptest if needed, or call graphql.Do directly","acceptance_criteria":"1. `go build ./...` passes\n2. `go test -v ./internal/integration/...` passes with all 14 test cases green\n3. Tests use table-driven test pattern\n4. Test setup creates a minimal but complete test environment (DB + lexicon + records + schema)\n5. Each test case is independent and does not depend on ordering\n6. Tests verify both the happy path and edge cases (empty results, invalid input)","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":60,"created_at":"2026-02-18T14:27:17.258793+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:21:53.440089+08:00","closed_at":"2026-02-18T15:21:53.440089+08:00","close_reason":"c179d86 Add integration tests for filter/sort/search end-to-end","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.14","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:27:17.259809+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.14","depends_on_id":"hyperindex-49s.4","type":"blocks","created_at":"2026-02-18T14:27:17.261276+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.14","depends_on_id":"hyperindex-49s.10","type":"blocks","created_at":"2026-02-18T14:27:17.262372+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.14","depends_on_id":"hyperindex-49s.11","type":"blocks","created_at":"2026-02-18T14:27:17.263445+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.14","depends_on_id":"hyperindex-49s.13","type":"blocks","created_at":"2026-02-18T14:27:17.264489+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.2","title":"Add FieldFilter struct and filtered query to RecordsRepository","description":"## Files\n- internal/database/repositories/records.go (modify)\n- internal/database/repositories/records_test.go (modify)\n\n## What to do\nAdd a `FieldFilter` struct and a new repository method that supports field-level filtering using JSON extraction.\n\n### 1. Define the FieldFilter struct (add near top of records.go, after Record struct)\n\n```go\n// FieldFilter represents a single filter condition on a JSON field.\ntype FieldFilter struct {\n    Field     string      // JSON field name (e.g., \"title\", \"createdAt\"). Must be a valid field name.\n    Operator  string      // One of: \"eq\", \"neq\", \"gt\", \"lt\", \"gte\", \"lte\", \"in\", \"contains\", \"startsWith\", \"isNull\"\n    Value     interface{} // The comparison value. For \"in\", must be []interface{}. For \"isNull\", must be bool.\n    FieldType string      // Lexicon type: \"string\", \"integer\", \"number\", \"boolean\", \"datetime\"\n}\n```\n\n### 2. Add a method to build WHERE clause fragments from filters\n\n```go\nfunc (r *RecordsRepository) buildFilterClause(filters []FieldFilter, startPlaceholder int) (string, []database.Value)\n```\n\nFor each filter:\n- Extract the JSON field: `r.db.JSONExtract(\"json\", filter.Field)` \n- Map operator to SQL: eq→`=`, neq→`!=`, gt→`\u003e`, lt→`\u003c`, gte→`\u003e=`, lte→`\u003c=`, contains→`LIKE` (wrap value in `%`), startsWith→`LIKE` (append `%`), isNull→`IS NULL`/`IS NOT NULL` (based on bool Value), in→`IN (...)`\n- For numeric types (integer, number), wrap the JSONExtract in CAST: SQLite `CAST(... AS REAL)`, PostgreSQL `(...)::numeric`\n- Use `r.db.Placeholder(n)` for parameterized values, incrementing from startPlaceholder\n- Join all conditions with ` AND `\n\n### 3. Add a new query method\n\n```go\nfunc (r *RecordsRepository) GetByCollectionFilteredWithKeysetCursor(\n    ctx context.Context,\n    collection string,\n    filters []FieldFilter,\n    did string,           // optional, empty string means no DID filter\n    limit int,\n    afterTimestamp string, // empty means first page\n    afterURI string,\n) ([]*Record, error)\n```\n\nThis builds on the existing `GetByCollectionWithKeysetCursor` pattern but:\n- Appends filter conditions from `buildFilterClause` to the WHERE clause\n- Adds `AND did = ?` if did is non-empty\n- Keeps the same `ORDER BY indexed_at DESC, uri DESC` and keyset cursor logic\n\n### 4. Tests\nAdd table-driven tests for `buildFilterClause` covering:\n- Each operator type (eq, neq, gt, lt, gte, lte, in, contains, startsWith, isNull true, isNull false)\n- Numeric type casting\n- Multiple filters combined with AND\n- Empty filter list returns empty string\n\nAdd integration-style tests for `GetByCollectionFilteredWithKeysetCursor`:\n- Filter by string eq\n- Filter by isNull\n- Filter with DID\n- Pagination with filters\n\n## Dont\n- Do not modify existing methods (GetByCollectionWithKeysetCursor etc.)\n- Do not change the Record struct\n- Do not add GraphQL code — this is DB layer only\n- Do not use raw string concatenation for field names — always go through JSONExtract which validates","acceptance_criteria":"1. `go build ./...` passes\n2. `go test -v ./internal/database/repositories/...` passes with all tests green\n3. `buildFilterClause` correctly generates SQL for all 10 operators\n4. Numeric fields (integer, number) are CAST appropriately per dialect\n5. `contains` wraps value in `%value%`, `startsWith` appends `value%`\n6. `isNull: true` generates `IS NULL`, `isNull: false` generates `IS NOT NULL`\n7. `in` operator generates `IN ($1, $2, ...)` with correct placeholder count\n8. Empty filters list returns empty clause string and nil params\n9. `GetByCollectionFilteredWithKeysetCursor` returns correct results when filtering by string field eq\n10. DID filter adds `AND did = ?` when non-empty, omits when empty","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":60,"created_at":"2026-02-18T14:23:37.993809+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:00:41.89451+08:00","closed_at":"2026-02-18T15:00:41.89451+08:00","close_reason":"8d786ca Add FieldFilter struct and filtered query to RecordsRepository","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.2","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:23:37.994792+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.2","depends_on_id":"hyperindex-49s.1","type":"blocks","created_at":"2026-02-18T14:23:37.996171+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.3","title":"Generate per-collection WhereInput types in schema builder","description":"## Files\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nDuring schema build, generate a per-collection `WhereInput` GraphQL InputObject type for each registered lexicon, and add a `where` argument to each typed collection query field.\n\n### 1. Add a new build phase method: `buildWhereInputTypes()`\n\nCall this after Phase 2 (record types) but before Phase 4 (query type). For each collection lexicon:\n\n- Get the lexicon main definition properties (same iteration as in `buildRecordTypes`)\n- For each property, call `types.FilterInputForLexiconType(prop.Type, prop.Format)` from the new filters.go (task 1)\n- If the filter input is non-nil, add the property name as a field on the WhereInput with that filter type\n- Always add a `did` field with `types.StringFilterInput` (DID is a standard filterable metadata field)\n- Store the resulting InputObject in a new map: `b.whereInputTypes map[string]*graphql.InputObject`\n\nType naming: `{TypeName}WhereInput` (e.g., `AppBskyFeedPostWhereInput`)\n\n### 2. Modify `buildQueryType()` — add `where` argument to collection fields\n\nAt builder.go line ~366, where `query.ConnectionArgs()` is used, replace with custom args that include the where input:\n\n```go\nargs := query.ConnectionArgs()\nif whereInput, ok := b.whereInputTypes[lexiconID]; ok {\n    args[\"where\"] = \u0026graphql.ArgumentConfig{\n        Type:        whereInput,\n        Description: \"Filter conditions\",\n    }\n}\n```\n\n### 3. Store whereInputTypes on the Builder struct\n\nAdd field: `whereInputTypes map[string]*graphql.InputObject`\nInitialize in `NewBuilder()`.\n\n## Dont\n- Do not add resolver logic to process the where argument (separate task)\n- Do not modify the generic `records` query\n- Do not add sort arguments (separate task)\n- Do not create new files — all changes go in builder.go","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes (all existing tests still green)\n3. For a lexicon with string/integer/datetime properties, the generated WhereInput has a field per filterable property\n4. Non-filterable properties (array, ref, union, blob, unknown) are NOT included in the WhereInput\n5. Every WhereInput includes a `did` field of type StringFilterInput\n6. The `where` argument appears on typed collection query fields in schema introspection\n7. The `where` argument does NOT appear on the generic `records` query or `*ByUri` queries\n8. The Builder struct has the new `whereInputTypes` map field initialized in NewBuilder","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T14:23:57.317521+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T14:58:26.465963+08:00","closed_at":"2026-02-18T14:58:26.465963+08:00","close_reason":"6050b63 Generate per-collection WhereInput types in schema builder","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.3","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:23:57.318642+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.3","depends_on_id":"hyperindex-49s.1","type":"blocks","created_at":"2026-02-18T14:23:57.320142+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.4","title":"Wire WHERE filters from GraphQL args into resolvers and repository","description":"## Files\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nConnect the `where` argument from typed collection queries through the resolver to the new filtered repository method.\n\n### 1. Add a helper function to extract filters from the `where` argument\n\n```go\nfunc extractFilters(whereArg interface{}, lexiconID string, registry *lexicon.Registry) ([]repositories.FieldFilter, string)\n```\n\nThis function:\n- Type-asserts `whereArg` to `map[string]interface{}`\n- For each key-value pair in the map:\n  - If key is `\"did\"`, extract the filter and return the DID value separately (or convert to a FieldFilter — but DID is a column, not a JSON field)\n  - Otherwise, look up the property type in the lexicon registry to determine `FieldType`\n  - The value will be a `map[string]interface{}` representing the filter input (e.g., `{\"eq\": \"hello\", \"contains\": \"world\"}`)\n  - For each operator-value pair in the filter input, create a `repositories.FieldFilter{Field: key, Operator: op, Value: val, FieldType: lexiconType}`\n- Return the slice of FieldFilters and the DID string (empty if not filtered)\n\n### 2. Modify `resolveRecordConnection`\n\nCurrently at builder.go lines 396-471. The function signature stays the same but behavior changes:\n\n- After extracting `first` and `after` (lines 407-411), also extract the `where` argument:\n  ```go\n  var filters []repositories.FieldFilter\n  var didFilter string\n  if whereArg, ok := p.Args[\"where\"]; ok \u0026\u0026 whereArg != nil {\n      filters, didFilter = extractFilters(whereArg, collection, b.registry)\n  }\n  ```\n- Replace the call to `repos.Records.GetByCollectionWithKeysetCursor(...)` (line ~424) with `repos.Records.GetByCollectionFilteredWithKeysetCursor(ctx, collection, filters, didFilter, first+1, afterTimestamp, afterURI)`\n- When filters is empty and didFilter is empty, the new method behaves identically to the old one\n\n### 3. Ensure backward compatibility\n\nThe `resolveRecordConnection` is also called by the generic `records` resolver (line 481) which does NOT have a `where` argument. Since `p.Args[\"where\"]` will be nil in that case, the filter extraction is skipped and the unfiltered path is taken. No changes needed to the generic records resolver.\n\n## Dont\n- Do not add sort logic (separate task)\n- Do not modify the repository layer (already done in task 2)\n- Do not modify the WhereInput type generation (already done in task 3)\n- Do not add new test files — add tests inline in existing builder test if one exists, or verify via integration test","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. A GraphQL query like `appBskyFeedPost(where: {text: {contains: \"hello\"}}) { edges { node { uri } } }` correctly filters results\n4. A query with `where: {did: {eq: \"did:plc:abc\"}}` correctly filters by DID\n5. Multiple filter fields are ANDed together\n6. Multiple operators on the same field are ANDed together (e.g., `{score: {gt: 5, lt: 10}}`)\n7. A query WITHOUT `where` argument returns the same results as before (backward compatible)\n8. The generic `records` query still works without where support\n9. No SQL injection possible — field names go through JSONExtract validation","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T14:24:19.056272+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:02:35.44457+08:00","closed_at":"2026-02-18T15:02:35.44457+08:00","close_reason":"110e36d Wire WHERE filters from GraphQL args into resolvers and repository","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.4","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:24:19.057295+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.4","depends_on_id":"hyperindex-49s.2","type":"blocks","created_at":"2026-02-18T14:24:19.059043+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.4","depends_on_id":"hyperindex-49s.3","type":"blocks","created_at":"2026-02-18T14:24:19.060135+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.5","title":"Add did and rkey fields to typed record GraphQL types","description":"## Files\n- internal/graphql/types/object.go (modify)\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nCurrently typed record types only expose `uri` and `cid` as standard metadata fields. The `did` (author DID) and `rkey` (record key) are available in the Record struct but never injected. GenericRecord already has these fields. Fix this inconsistency.\n\n### 1. Modify `buildRecordFields()` in object.go (around line 92-103)\n\nAdd two new standard fields alongside the existing `uri` and `cid`:\n\n```go\n\"did\": \u0026graphql.Field{\n    Type:        graphql.NewNonNull(graphql.String),\n    Description: \"DID of the record author\",\n},\n\"rkey\": \u0026graphql.Field{\n    Type:        graphql.NewNonNull(graphql.String),\n    Description: \"Record key (last segment of AT-URI)\",\n},\n```\n\n### 2. Modify `createCollectionResolver` in builder.go (around line 498-506)\n\nIn the loop that builds data maps from records, add:\n```go\ndata[\"did\"] = rec.DID\ndata[\"rkey\"] = rec.RKey\n```\nalongside the existing `data[\"uri\"] = rec.URI` and `data[\"cid\"] = rec.CID`.\n\n### 3. Modify `createSingleRecordResolver` in builder.go (around line 535-541)\n\nSame injection — add `data[\"did\"]` and `data[\"rkey\"]` to the single-record resolver output.\n\n## Dont\n- Do not modify GenericRecord (it already has these fields)\n- Do not modify subscription types (RecordEvent already has did)\n- Do not add actor resolution (separate future task)\n- Do not add any new files","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. Typed record types now have `did: String!` and `rkey: String!` fields visible in schema introspection\n4. A typed collection query returns `did` and `rkey` values in the response\n5. A single record ByUri query returns `did` and `rkey` values\n6. Existing `uri` and `cid` fields are unchanged\n7. Subscription event types are unchanged","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-18T14:24:33.139969+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T14:54:46.611508+08:00","closed_at":"2026-02-18T14:54:46.611508+08:00","close_reason":"c18791b Add did and rkey fields to typed record GraphQL types","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-49s.5","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:24:33.141069+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.6","title":"Add max page size limit and validate first argument","description":"## Files\n- internal/graphql/schema/builder.go (modify)\n- internal/graphql/query/connection.go (modify)\n\n## What to do\nThere is currently no upper bound on the `first` pagination argument. A client can request `first: 999999` causing the server to fetch a million records. Add a max page size.\n\n### 1. Define constants in connection.go\n\n```go\nconst (\n    DefaultPageSize = 20\n    MaxPageSize     = 100\n)\n```\n\n### 2. Add a helper function in connection.go\n\n```go\n// ClampPageSize returns a valid page size within [1, MaxPageSize], defaulting to DefaultPageSize.\nfunc ClampPageSize(first int) int {\n    if first \u003c= 0 {\n        return DefaultPageSize\n    }\n    if first \u003e MaxPageSize {\n        return MaxPageSize\n    }\n    return first\n}\n```\n\n### 3. Apply in builder.go `resolveRecordConnection` (around line 407-410)\n\nReplace:\n```go\nfirst, _ := p.Args[\"first\"].(int)\nif first == 0 {\n    first = 20\n}\n```\n\nWith:\n```go\nfirstArg, _ := p.Args[\"first\"].(int)\nfirst := query.ClampPageSize(firstArg)\n```\n\n### 4. Apply to the generic `records` resolver too\n\nThe generic records query resolver (around line 473-493) likely has similar default logic. Apply the same clamping there.\n\n## Dont\n- Do not change the default page size (keep 20)\n- Do not return an error for first \u003e 100 — silently clamp to 100\n- Do not modify admin API pagination (labels/reports)","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. `query.ClampPageSize(0)` returns 20\n4. `query.ClampPageSize(-5)` returns 20\n5. `query.ClampPageSize(50)` returns 50\n6. `query.ClampPageSize(200)` returns 100\n7. `query.ClampPageSize(100)` returns 100\n8. A GraphQL query with `first: 500` returns at most 100 records\n9. A GraphQL query with no `first` argument returns 20 records (default unchanged)\n10. Constants `DefaultPageSize` and `MaxPageSize` are exported","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T14:24:45.871588+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T14:55:02.306475+08:00","closed_at":"2026-02-18T14:55:02.306475+08:00","close_reason":"bbfdf23 Add max page size limit and ClampPageSize helper","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-49s.6","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:24:45.872519+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.7","title":"Add composite DB index for keyset pagination performance","description":"## Files\n- internal/database/migrations/sqlite/006_add_composite_index.up.sql (create)\n- internal/database/migrations/sqlite/006_add_composite_index.down.sql (create)\n- internal/database/migrations/postgres/006_add_composite_index.up.sql (create)\n- internal/database/migrations/postgres/006_add_composite_index.down.sql (create)\n\n## What to do\nThe current keyset pagination query uses `WHERE collection = ? AND (indexed_at \u003c ? OR (indexed_at = ? AND uri \u003c ?)) ORDER BY indexed_at DESC, uri DESC`. There is no composite index covering this query pattern. The existing `idx_record_indexed_at` is single-column and `idx_record_collection` is single-column. Add a composite covering index.\n\n### Migration 006 up (both dialects — SQL is identical):\n\n```sql\n-- Composite index for keyset pagination: covers WHERE collection = ? ORDER BY indexed_at DESC, uri DESC\nCREATE INDEX IF NOT EXISTS idx_record_collection_keyset ON record(collection, indexed_at DESC, uri DESC);\n```\n\n### Migration 006 down (both dialects):\n\n```sql\nDROP INDEX IF EXISTS idx_record_collection_keyset;\n```\n\n### Important notes\n- Check existing migration numbers first. The latest migration files should be numbered 005. If 006 already exists, use the next available number.\n- The migration filenames must follow the existing pattern exactly: `NNN_description.up.sql` and `NNN_description.down.sql`\n- Use `IF NOT EXISTS` / `IF EXISTS` for idempotency\n\n## Dont\n- Do not modify any Go code\n- Do not drop existing indexes\n- Do not add FTS indexes (separate future task)\n- Do not add GIN or expression indexes for JSON fields yet","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes (migrations run successfully)\n3. SQLite up migration creates the composite index\n4. PostgreSQL up migration creates the composite index\n5. Down migrations drop the index cleanly\n6. Migration file numbering is correct (no gaps, no conflicts with existing migrations)\n7. Running the server applies the migration without errors","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-18T14:24:58.875985+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T14:54:39.728725+08:00","closed_at":"2026-02-18T14:54:39.728725+08:00","close_reason":"6b2c6ad feat: add composite DB index for keyset pagination performance","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-49s.7","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:24:58.876847+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.8","title":"Add per-collection sort enum and sortBy/sortDirection arguments","description":"## Files\n- internal/graphql/query/connection.go (modify)\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nAdd sorting arguments to typed collection queries. Each collection gets a generated enum of sortable fields. A shared SortDirection enum provides ASC/DESC.\n\n### 1. Define SortDirection enum in connection.go\n\n```go\nvar SortDirectionEnum = graphql.NewEnum(graphql.EnumConfig{\n    Name:        \"SortDirection\",\n    Description: \"Sort direction\",\n    Values: graphql.EnumValueConfigMap{\n        \"ASC\":  \u0026graphql.EnumValueConfig{Value: \"ASC\", Description: \"Ascending order\"},\n        \"DESC\": \u0026graphql.EnumValueConfig{Value: \"DESC\", Description: \"Descending order (default)\"},\n    },\n})\n```\n\n### 2. Add BuildSortFieldEnum function in connection.go (or a new sort.go in the query package)\n\n```go\n// BuildSortFieldEnum creates a per-collection enum of fields that can be used for sorting.\n// Only scalar types are sortable (string, integer, number, boolean, datetime).\n// Always includes \"indexed_at\" as a sortable meta-field.\nfunc BuildSortFieldEnum(typeName string, properties map[string]lexicon.Property) *graphql.Enum\n```\n\nFor each property, check if the type is sortable:\n- string (any format) → sortable\n- integer → sortable\n- number → sortable\n- boolean → sortable\n- datetime (string+datetime) → sortable\n- All others (array, ref, union, blob, bytes, unknown, object) → not sortable\n\nEnum value names should match the property names exactly.\n\n### 3. Store sort enums and add to query args in builder.go\n\n- Add a new map `b.sortFieldEnums map[string]*graphql.Enum` to the Builder struct, initialized in NewBuilder\n- In a new build phase (or alongside whereInputTypes), build sort enums for each collection\n- When building collection query fields in `buildQueryType()`, add `sortBy` and `sortDirection` arguments:\n\n```go\nargs[\"sortBy\"] = \u0026graphql.ArgumentConfig{\n    Type:        sortEnum,\n    Description: \"Field to sort by (default: indexed_at)\",\n}\nargs[\"sortDirection\"] = \u0026graphql.ArgumentConfig{\n    Type:         SortDirectionEnum,\n    Description:  \"Sort direction (default: DESC)\",\n}\n```\n\n## Dont\n- Do not implement the resolver logic to actually use the sort args (separate task)\n- Do not modify cursor encoding (separate task)\n- Do not import lexicon package into connection.go — pass the needed data as params\n- Do not add sorting to the generic `records` query or admin queries","acceptance_criteria":"1. `go build ./...` passes\n2. `go test ./...` passes\n3. `SortDirectionEnum` has exactly two values: ASC and DESC\n4. `BuildSortFieldEnum` generates an enum with `indexed_at` plus one entry per sortable property\n5. Non-sortable properties (array, ref, union, blob, unknown) are excluded from the sort enum\n6. The `sortBy` argument appears on typed collection query fields in schema introspection\n7. The `sortDirection` argument appears on typed collection query fields\n8. Neither sort argument appears on the generic `records` query or `*ByUri` queries","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T14:25:17.754005+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T14:56:31.312978+08:00","closed_at":"2026-02-18T14:56:31.312978+08:00","close_reason":"2140d47 Add per-collection sort enum and sortBy/sortDirection arguments","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.8","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:25:17.754937+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-49s.9","title":"Add sorted query method to RecordsRepository","description":"## Files\n- internal/database/repositories/records.go (modify)\n- internal/database/repositories/records_test.go (modify)\n\n## What to do\nAdd a repository method that supports dynamic ORDER BY on a single field (either a DB column or a JSON-extracted field), with configurable sort direction.\n\n### 1. Define a SortOption struct\n\n```go\n// SortOption specifies a sort field and direction for record queries.\ntype SortOption struct {\n    Field     string // Field name. If \"indexed_at\", \"uri\", \"did\", \"collection\" — use column directly. Otherwise, use JSONExtract.\n    Direction string // \"ASC\" or \"DESC\"\n}\n```\n\n### 2. Add helper to build ORDER BY expression\n\n```go\nfunc (r *RecordsRepository) buildSortExpr(sort *SortOption) string\n```\n\n- If `sort` is nil, return `\"indexed_at DESC, uri DESC\"` (default)\n- If `sort.Field` is one of `\"indexed_at\", \"uri\", \"did\", \"collection\", \"cid\", \"rkey\"`, use it as a direct column reference\n- Otherwise, use `r.db.JSONExtract(\"json\", sort.Field)` to build the sort expression\n- Always append `, uri DESC` as the tiebreaker (unless the field IS uri)\n- The direction comes from `sort.Direction`\n\n### 3. Add new query method\n\n```go\nfunc (r *RecordsRepository) GetByCollectionSortedWithKeysetCursor(\n    ctx context.Context,\n    collection string,\n    filters []FieldFilter,\n    did string,\n    sort *SortOption,     // nil means default sort\n    limit int,\n    afterCursorValues []string, // [sortFieldValue, uri] for keyset. Empty = first page.\n) ([]*Record, error)\n```\n\nThis method:\n- Builds the ORDER BY clause from sort option\n- Builds the keyset WHERE clause using the sort field and uri as the composite cursor key\n- The comparison operator flips based on direction: DESC uses `\u003c`, ASC uses `\u003e`\n- Applies field filters from `buildFilterClause` (from task 2)\n- Applies optional DID filter\n\n### 4. Tests\n\n- Test default sort (nil SortOption) returns records in indexed_at DESC order\n- Test sort by indexed_at ASC returns records in ascending order\n- Test sort by a JSON field (e.g., createdAt) DESC\n- Test keyset cursor works correctly with custom sort field\n- Test sort + filters combined\n\n## Dont\n- Do not support multi-field sorting (only one sort field + uri tiebreaker)\n- Do not modify existing methods\n- Do not add GraphQL code","acceptance_criteria":"1. `go build ./...` passes\n2. `go test -v ./internal/database/repositories/...` passes\n3. Nil SortOption produces `ORDER BY indexed_at DESC, uri DESC`\n4. SortOption{Field: \"indexed_at\", Direction: \"ASC\"} produces `ORDER BY indexed_at ASC, uri ASC`\n5. SortOption for a JSON field uses JSONExtract in the ORDER BY\n6. Keyset cursor with ASC direction uses `\u003e` comparator\n7. Keyset cursor with DESC direction uses `\u003c` comparator\n8. Combined sort + filters produces correct results\n9. The uri tiebreaker direction matches the primary sort direction","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T14:25:38.205489+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:06:00.990256+08:00","closed_at":"2026-02-18T15:06:00.990256+08:00","close_reason":"8986495 Add sorted query method to RecordsRepository","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-49s.9","depends_on_id":"hyperindex-49s","type":"parent-child","created_at":"2026-02-18T14:25:38.206562+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-49s.9","depends_on_id":"hyperindex-49s.2","type":"blocks","created_at":"2026-02-18T14:25:38.208305+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-5ar","title":"Fix: subscription per-collection resolver returns raw record map without null coercion (from hyperindex-vz7)","description":"## Files\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nIn `buildSubscriptionType()`, find the per-collection subscription resolver that returns `event.Record` directly (around line 335). Add a call to `b.coerceRequiredFields()` before returning, matching the pattern used in `createCollectionResolver` and `createSingleRecordResolver`.\n\nThe current code looks like:\n```go\nreturn event.Record, nil\n```\n\nIt should become:\n```go\nif data, ok := event.Record.(map[string]interface{}); ok {\n    b.coerceRequiredFields(data, lexiconID)\n}\nreturn event.Record, nil\n```\n\nMake sure to use the correct `lexiconID` variable that is in scope for that subscription field (the collection NSID like `org.hypercerts.claim.activity`). Check the loop variable name — it may be `id`, `lexiconID`, or `nsid` depending on how `buildSubscriptionType` iterates.\n\n## Dont\n- Do not change the subscription infrastructure or WebSocket handling\n- Do not modify `coerceRequiredFields` itself\n- Do not add new dependencies\n- Do not change any other resolver paths","acceptance_criteria":"1. go build ./... succeeds\n2. go test ./... succeeds (no regressions)\n3. The subscription resolver for typed collections calls b.coerceRequiredFields() on the record data before returning it\n4. The coercion uses the correct collection NSID (lexicon ID) for the subscription field being resolved","status":"open","priority":1,"issue_type":"bug","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-19T20:20:15.974813+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T20:22:26.90495+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-5ar","depends_on_id":"hyperindex-vz7","type":"discovered-from","created_at":"2026-02-19T20:20:19.381083+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-6bl","title":"Fix: README Tap curl uses wrong Basic auth username (from hyperindex-md3.9)","description":"Review of hyperindex-md3.9 found: the README curl example was changed to `-u \":${TAP_ADMIN_PASSWORD}\"` (empty username), but admin.go line 157 sends `\"admin:\" + c.password` as the credential. These produce different Authorization headers: `Basic base64(:pass)` vs `Basic base64(admin:pass)`. The correct fix is `-u \"admin:${TAP_ADMIN_PASSWORD}\"`. Evidence: admin.go:157 `creds := base64.StdEncoding.EncodeToString([]byte(\"admin:\" + c.password))`; TestAdminClient_BasicAuth line 280 confirms username is 'admin'. The spec description incorrectly stated the code used SetBasicAuth(\"\", password) — the worker faithfully implemented the wrong spec.","status":"open","priority":1,"issue_type":"bug","owner":"einstein.climateai.org","created_at":"2026-02-18T16:48:34.553314+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:48:34.553314+08:00","dependencies":[{"issue_id":"hyperindex-6bl","depends_on_id":"hyperindex-md3.9","type":"discovered-from","created_at":"2026-02-18T16:48:53.282601+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-73q","title":"Fix: docker-compose.yml and docker-compose.postgres.yml still have static SECRET_KEY_BASE default (from hyperindex-md3.8)","description":"Review of hyperindex-md3.8 found: the security fix was correctly applied to docker-compose.tap.yml but docker-compose.yml (line 12) and docker-compose.postgres.yml (line 12) still use the static default `development-secret-key-change-in-production-64chars`. Anyone deploying with these files without setting SECRET_KEY_BASE gets a known, forgeable session key. The B8 spec explicitly excluded these files, so the worker was correct to skip them — but the vulnerability remains. Both files need the same `:?` treatment: `${SECRET_KEY_BASE:?SECRET_KEY_BASE must be set - generate with: openssl rand -hex 32}`.","status":"open","priority":2,"issue_type":"bug","owner":"einstein.climateai.org","created_at":"2026-02-18T16:48:40.474421+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:48:40.474421+08:00","dependencies":[{"issue_id":"hyperindex-73q","depends_on_id":"hyperindex-md3.8","type":"discovered-from","created_at":"2026-02-18T16:48:53.380917+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-a10","title":"Make dashboard stats, activity chart, and recent activity public (no auth required)","description":"## Files\n- internal/graphql/admin/schema.go (modify)\n\n## What to do\nRemove the `requireAdmin(p.Context)` guard from three query field resolvers in `buildQueryType()`:\n\n1. **`statistics`** (around line 62-65): Remove the `if err := requireAdmin(...)` block. Update Description from `\"Get system statistics (admin only)\"` to `\"Get system statistics (public)\"`.\n\n2. **`activityBuckets`** (around line 118-121): Remove the `if err := requireAdmin(...)` block. Update Description from `\"Get aggregated activity data for a time range (admin only)\"` to `\"Get aggregated activity data for a time range (public)\"`.\n\n3. **`recentActivity`** (around line 136-139): Remove the `if err := requireAdmin(...)` block. Update Description from `\"Get recent activity entries (admin only)\"` to `\"Get recent activity entries (public)\"`.\n\nKeep the rest of each resolver body intact (args parsing, hour clamping, etc). Do NOT touch any other fields — `settings`, `lexicons`, `oauthClients`, `isBackfilling`, `labelDefinitions`, `labels` must stay admin-only.\n\n## Don't\n- Remove requireAdmin from any other field besides statistics, activityBuckets, recentActivity\n- Change resolver logic, argument handling, or return types\n- Modify any other file","acceptance_criteria":"1. `go build ./...` succeeds\n2. `go test ./...` passes\n3. `curl -s -X POST -H 'Content-Type: application/json' -d '{\"query\":\"{ statistics { recordCount } }\"}' http://localhost:8080/admin/graphql` returns data (no X-User-DID header, no auth) without 'admin privileges required' error\n4. `curl -s -X POST -H 'Content-Type: application/json' -d '{\"query\":\"{ activityBuckets(range: ONE_DAY) { timestamp } }\"}' http://localhost:8080/admin/graphql` returns data without auth\n5. `curl -s -X POST -H 'Content-Type: application/json' -d '{\"query\":\"{ recentActivity(hours: 1) { id } }\"}' http://localhost:8080/admin/graphql` returns data without auth\n6. `curl -s -X POST -H 'Content-Type: application/json' -d '{\"query\":\"{ settings { domainAuthority } }\"}' http://localhost:8080/admin/graphql` still returns 'admin privileges required' (settings remains protected)","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-19T10:09:54.01132+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T10:10:59.004248+08:00","closed_at":"2026-02-19T10:10:59.004248+08:00","close_reason":"9e8acfc Make statistics, activityBuckets, recentActivity public","labels":["scope:small"]}
+{"id":"hyperindex-bn7","title":"Fix: ZeroValueForType format parameter is accepted but never used (from hyperindex-vz7.1)","description":"## Files\n- internal/lexicon/types.go (modify)\n- internal/lexicon/types_test.go (modify)\n\n## What to do\nRemove the unused `format` parameter from `ZeroValueForType`. It currently accepts `format string` but never reads it.\n\n1. Change the signature from `ZeroValueForType(propType, format string) interface{}` to `ZeroValueForType(propType string) interface{}`\n2. Update all callers. There is one caller in `internal/graphql/schema/builder.go` inside `coerceRequiredFields()`:\n   ```go\n   // Before:\n   zero := lexicon.ZeroValueForType(entry.Property.Type, entry.Property.Format)\n   // After:\n   zero := lexicon.ZeroValueForType(entry.Property.Type)\n   ```\n3. Update tests in `internal/lexicon/types_test.go` — remove the `format` field from the test table and update the call sites\n\n## Dont\n- Do not change the behavior of the function\n- Do not add format-dependent logic — just remove the dead parameter","acceptance_criteria":"1. go build ./... succeeds\n2. go test ./... succeeds\n3. ZeroValueForType signature is ZeroValueForType(propType string) interface{}\n4. No callers pass a format parameter\n5. All existing tests still pass with updated signatures","status":"open","priority":3,"issue_type":"bug","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-19T20:20:27.870624+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T20:22:35.280806+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-bn7","depends_on_id":"hyperindex-vz7","type":"discovered-from","created_at":"2026-02-19T20:20:30.798429+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-m1t","title":"Fix: README TAP_ADMIN_PASSWORD table entry still says default is empty after B8 made it required (from hyperindex-md3.8)","description":"Review of hyperindex-md3.8 found: README.md line 91 environment variable table lists TAP_ADMIN_PASSWORD default as '*(empty)*'. After hyperindex-md3.8, docker-compose.tap.yml uses ${TAP_ADMIN_PASSWORD:?...} which makes it required with no default. The table entry is now misleading — it should say '*(required)*' or '*(no default — must be set)*' to match the compose file behavior.","status":"open","priority":3,"issue_type":"bug","owner":"einstein.climateai.org","created_at":"2026-02-18T16:48:45.609562+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:48:45.609562+08:00","dependencies":[{"issue_id":"hyperindex-m1t","depends_on_id":"hyperindex-md3.8","type":"discovered-from","created_at":"2026-02-18T16:48:53.471005+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3","title":"Epic: Fix Tap integration bugs found by code review","description":"Ten bugs (B1-B10) were identified by specialized reviewers of the Tap sidecar integration (epic hyperindex-2hm). These range from HIGH severity (data race, static secret) to LOW (log noise, docs). All bugs are in internal/tap/ package files, docker-compose.tap.yml, and README.md. Success = all 10 bugs fixed, all existing tests still pass (go test ./...), new tests added for each fix, and go test -race ./internal/tap/... passes clean.","status":"closed","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-18T16:30:49.657865+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:45:50.134402+08:00","closed_at":"2026-02-18T16:45:50.134402+08:00","close_reason":"b28087c all 10 Tap review bugs fixed, all tests green","labels":["scope:medium"]}
+{"id":"hyperindex-md3.1","title":"Fix data race: Stop() writes close frame concurrently with dispatch() acks","description":"## Files\n- internal/tap/consumer.go (modify)\n- internal/tap/consumer_test.go (modify)\n\n## What to do\nIn `Stop()` (line 280-297), the call to `conn.WriteMessage(CloseMessage, ...)` at line 290 races with `writeText()` calls from `dispatch()` because gorilla/websocket does not allow concurrent writers. The `connMu` mutex only protects the `c.conn` pointer swap, NOT the write.\n\nFix: Remove the `WriteMessage(CloseMessage, ...)` call from `Stop()`. Keep only `conn.Close()`. The gorilla library sends a close frame internally on `Close()` when the connection is not already closed.\n\nThe fixed `Stop()` should look like:\n```go\nfunc (c *Consumer) Stop() {\n    c.stopOnce.Do(func() {\n        close(c.done)\n        c.connMu.Lock()\n        conn := c.conn\n        c.conn = nil\n        c.connMu.Unlock()\n        if conn != nil {\n            _ = conn.Close()\n        }\n    })\n}\n```\n\nAdd a test `TestConsumer_StopDuringDispatch` that:\n1. Sends many events rapidly from the mock server\n2. Calls `Stop()` concurrently while events are being dispatched\n3. Passes with `go test -race`\n\n## Dont\n- Do NOT add a write mutex — the simpler fix of removing the close-frame write is sufficient\n- Do NOT change the `connMu` usage for the pointer swap (that is correct)\n- Do NOT change `writeText()` signature","acceptance_criteria":"1. `go test -race ./internal/tap/...` passes with no race detected\n2. `TestConsumer_StopDuringDispatch` exists and passes\n3. `Stop()` no longer calls `conn.WriteMessage(CloseMessage, ...)`\n4. All existing consumer tests still pass","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T16:31:04.408366+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:40:26.969429+08:00","closed_at":"2026-02-18T16:40:26.969429+08:00","close_reason":"788e1cf fix: remove concurrent WriteMessage in Stop() to eliminate data race","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-md3.1","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:31:04.40981+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.10","title":"Suppress spurious context.Canceled error log on graceful shutdown","description":"## Files\n- internal/tap/consumer.go (modify)\n- internal/tap/consumer_test.go (modify)\n\n## What to do\nIn `Start()` at lines 116-125, when the context is cancelled during shutdown, `runOnce()` returns `context.Canceled`. The code then logs it as:\n```\nslog.Error(\"Tap connection lost, will reconnect\", \"error\", err, \"backoff\", backoff)\n```\n\nThis is misleading — a context cancellation during shutdown is expected, not an error. The log message says \"will reconnect\" but the very next iteration of the for loop will hit the `\u003c-ctx.Done()` check and return.\n\nFix: Check for context cancellation before logging. Insert the ctx check BEFORE the error logging block:\n\n```go\nerr := c.runOnce(ctx)\n\n// Reset backoff after successful connection.\nbackoff = minBackoff\n\n// Check if we should stop after connection ended.\nselect {\ncase \u003c-ctx.Done():\n    return ctx.Err()\ncase \u003c-c.done:\n    return nil\ndefault:\n}\n\n// Only log reconnection messages for genuine errors (not shutdown).\nif err != nil {\n    slog.Error(\"Tap connection lost, will reconnect\",\n        \"error\", err,\n        \"backoff\", backoff,\n    )\n} else {\n    slog.Warn(\"Tap connection closed unexpectedly, will reconnect\",\n        \"backoff\", backoff,\n    )\n}\n```\n\nThis is actually already the structure — the ctx/done checks at lines 108-114 run BEFORE the log. But the issue is that `runOnce()` can return with `ctx.Err()` when `ReadMessage` fails due to context cancellation, but the outer `select` on `ctx.Done()` might not trigger because the done channel fires first (race between done and ctx). \n\nThe real fix: After the stop/ctx checks at lines 108-114, add an explicit check for `context.Canceled` or `context.DeadlineExceeded`:\n\n```go\nif err != nil {\n    if ctx.Err() != nil {\n        return ctx.Err()\n    }\n    slog.Error(\"Tap connection lost, will reconnect\",\n        \"error\", err,\n        \"backoff\", backoff,\n    )\n} else {\n    slog.Warn(\"Tap connection closed unexpectedly, will reconnect\",\n        \"backoff\", backoff,\n    )\n}\n```\n\nAlso change the log level from `slog.Error` to `slog.Warn` — a lost connection that triggers reconnection is a warning, not an error. Errors should be reserved for unrecoverable situations.\n\nAdd a test `TestConsumer_ShutdownNoSpuriousLog` that:\n1. Uses a `slog.Handler` that captures log records\n2. Starts the consumer, then cancels the context\n3. Verifies no Error-level log messages are emitted during shutdown\n\n## Dont\n- Do NOT change the reconnection logic\n- Do NOT suppress ALL error logs — only context cancellation during shutdown\n- Do NOT change the Stop() method (B1 handles that)","acceptance_criteria":"1. When context is cancelled, `Start()` does NOT log an Error-level message about connection lost\n2. Genuine connection errors still log at Warn level (changed from Error)\n3. `TestConsumer_ShutdownNoSpuriousLog` exists and passes\n4. All existing consumer tests still pass\n5. `go test -race ./internal/tap/...` passes","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T16:33:17.579359+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:45:46.285687+08:00","closed_at":"2026-02-18T16:45:46.285687+08:00","close_reason":"b28087c suppress spurious context.Canceled error log on graceful shutdown","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-md3.10","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:33:17.580701+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-md3.10","depends_on_id":"hyperindex-md3.3","type":"blocks","created_at":"2026-02-18T16:33:32.999393+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.2","title":"Fix backoff never resetting after successful reconnection","description":"## Files\n- internal/tap/consumer.go (modify)\n- internal/tap/consumer_test.go (modify)\n\n## What to do\nIn `Start()` (lines 92-143), `backoff` is initialized to `minBackoff` at line 93, then doubled on each iteration at lines 136-140, but it is never reset after a successful `runOnce()` call. This means after one disconnection-reconnection cycle, the backoff stays escalated forever (e.g., after reaching 2 minutes, every subsequent reconnection waits 2 minutes even if the connection was healthy for hours).\n\nFix: Add `backoff = minBackoff` right after the `runOnce(ctx)` call returns successfully (i.e., before the error/stop checks). Insert at line ~106:\n\n```go\nerr := c.runOnce(ctx)\n\n// Reset backoff after a successful connection that processed events.\nbackoff = minBackoff\n```\n\nThe comment at line 170 (\"Reset backoff is implicit — caller resets on next successful connection\") is now wrong. Remove that comment.\n\nAdd a test `TestConsumer_BackoffResetsAfterSuccess` that:\n1. First connection: server closes immediately → triggers backoff\n2. Second connection: server stays open, sends one event, then closes cleanly\n3. Third connection: verify it reconnects within ~1.5s (not 2s+), confirming backoff was reset\n\n## Dont\n- Do NOT change the backoff doubling logic (lines 136-140)\n- Do NOT change minBackoff or maxBackoff constants\n- Do NOT add configurable backoff — keep it simple","acceptance_criteria":"1. After a successful connection, backoff resets to minBackoff (1s)\n2. The stale comment at line 170 is removed\n3. `TestConsumer_BackoffResetsAfterSuccess` exists and passes\n4. All existing consumer tests still pass\n5. `go test -race ./internal/tap/...` passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T16:31:17.44932+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:42:11.42544+08:00","closed_at":"2026-02-18T16:42:11.42544+08:00","close_reason":"692e95b fix: reset backoff to minBackoff after successful reconnection","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-md3.2","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:31:17.450448+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-md3.2","depends_on_id":"hyperindex-md3.1","type":"blocks","created_at":"2026-02-18T16:33:32.785261+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.3","title":"Add WebSocket SetReadLimit to prevent OOM from oversized messages","description":"## Files\n- internal/tap/consumer.go (modify)\n- internal/tap/consumer_test.go (modify)\n\n## What to do\nIn `runOnce()` at line 152, after `websocket.DefaultDialer.DialContext()` succeeds, there is no call to `conn.SetReadLimit()`. The gorilla/websocket default read limit is 0 (unlimited). A malicious or buggy Tap server could send a multi-GB message causing OOM.\n\nFix: Add a constant and a `SetReadLimit` call immediately after the successful dial:\n\n```go\nconst maxMessageSize = 4 * 1024 * 1024 // 4 MB\n```\n\nAdd this as a package-level constant in the `const` block at lines 14-29.\n\nThen in `runOnce()`, right after the successful dial and before the `connMu.Lock()`:\n\n```go\nconn, _, err := websocket.DefaultDialer.DialContext(ctx, channelURL, nil)\nif err != nil {\n    return fmt.Errorf(\"failed to connect to Tap: %w\", err)\n}\nconn.SetReadLimit(maxMessageSize)\n```\n\nAdd a test `TestConsumer_LargeMessageRejected` that:\n1. Mock server sends a text message larger than 4MB\n2. Verify the consumer gets a read error (the connection closes with CloseMessageTooBig)\n3. The consumer reconnects (does not crash or OOM)\n\n## Dont\n- Do NOT set the limit lower than 4MB — AT Protocol records can be up to 1MB\n- Do NOT make the limit configurable — 4MB is a reasonable fixed cap","acceptance_criteria":"1. `maxMessageSize` constant (4*1024*1024) exists in consumer.go\n2. `conn.SetReadLimit(maxMessageSize)` is called after every successful dial\n3. `TestConsumer_LargeMessageRejected` exists and passes\n4. All existing consumer tests still pass\n5. `go test -race ./internal/tap/...` passes","status":"in_progress","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T16:31:29.214553+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:42:25.997348+08:00","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-md3.3","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:31:29.215597+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-md3.3","depends_on_id":"hyperindex-md3.2","type":"blocks","created_at":"2026-02-18T16:33:32.892499+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.4","title":"Add nil guard for PubSub in IndexHandler to prevent nil-pointer panic","description":"## Files\n- internal/tap/handler.go (modify)\n- internal/tap/handler_test.go (modify)\n\n## What to do\nIn `HandleRecord()`, the `h.activity` field is nil-checked at lines 55 and 73 before calling methods on it, but `h.pubsub` is NOT nil-checked at lines 66 and 72. If `NewIndexHandler()` is called with `pubsub: nil`, line 66 panics with a nil-pointer dereference.\n\nFix: Add nil guards before both `h.pubsub.PublishRecord(...)` calls:\n\nLine 66 (create/update case):\n```go\nif h.pubsub != nil {\n    h.pubsub.PublishRecord(eventType, uri, event.CID, event.DID, event.Collection, event.Record)\n}\n```\n\nLine 72 (delete case):\n```go\nif h.pubsub != nil {\n    h.pubsub.PublishRecord(subscription.EventDelete, uri, \"\", event.DID, event.Collection, nil)\n}\n```\n\nAdd a test `TestIndexHandler_HandleRecord_NilPubSub` that:\n1. Creates an IndexHandler with `pubsub: nil` (similar to existing `TestIndexHandler_HandleRecord_NilActivity`)\n2. Calls HandleRecord with a create event\n3. Verifies it does NOT panic and the record is still stored correctly\n4. Also test with a delete event\n\n## Dont\n- Do NOT make pubsub a required parameter or add validation in NewIndexHandler\n- Do NOT change the PubSub interface\n- Keep the same pattern as the existing nil-check for activity","acceptance_criteria":"1. `h.pubsub.PublishRecord(...)` calls at both lines 66 and 72 are wrapped in `if h.pubsub != nil`\n2. `TestIndexHandler_HandleRecord_NilPubSub` exists and passes (create + delete with nil pubsub)\n3. No panic when pubsub is nil\n4. All existing handler tests still pass\n5. `go test ./internal/tap/...` passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-18T16:31:41.815405+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:40:27.061154+08:00","closed_at":"2026-02-18T16:40:27.061154+08:00","close_reason":"ee9d022 Add nil guard for PubSub in IndexHandler to prevent nil-pointer panic","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-md3.4","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:31:41.820488+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.5","title":"Validate required fields in ParseEvent to prevent garbage URIs","description":"## Files\n- internal/tap/event.go (modify)\n- internal/tap/event_test.go (modify)\n\n## What to do\n`ParseEvent()` (lines 60-68) only validates that `event.Type` is non-empty. It does NOT validate that record events have non-empty DID, Collection, and RKey fields. Empty fields produce garbage URIs like `at:///` from `RecordEvent.URI()`.\n\nFix: Add field validation in `ParseEvent()` after unmarshaling, for record events:\n\n```go\nfunc ParseEvent(data []byte) (*Event, error) {\n    var event Event\n    if err := json.Unmarshal(data, \u0026event); err != nil {\n        return nil, fmt.Errorf(\"failed to parse tap event: %w\", err)\n    }\n    if event.Type == \"\" {\n        return nil, fmt.Errorf(\"tap event missing type field\")\n    }\n    // Validate required fields for record events.\n    if event.Type == EventTypeRecord \u0026\u0026 event.Record != nil {\n        if event.Record.DID == \"\" {\n            return nil, fmt.Errorf(\"tap record event missing did field\")\n        }\n        if event.Record.Collection == \"\" {\n            return nil, fmt.Errorf(\"tap record event missing collection field\")\n        }\n        if event.Record.RKey == \"\" {\n            return nil, fmt.Errorf(\"tap record event missing rkey field\")\n        }\n        if event.Record.Action == \"\" {\n            return nil, fmt.Errorf(\"tap record event missing action field\")\n        }\n    }\n    // Validate required fields for identity events.\n    if event.Type == EventTypeIdentity \u0026\u0026 event.Identity != nil {\n        if event.Identity.DID == \"\" {\n            return nil, fmt.Errorf(\"tap identity event missing did field\")\n        }\n    }\n    return \u0026event, nil\n}\n```\n\nAdd table-driven tests in event_test.go for these new validation cases:\n- Record with empty DID → error\n- Record with empty Collection → error\n- Record with empty RKey → error\n- Record with empty Action → error\n- Identity with empty DID → error\n- Valid record → no error (already exists, verify still passes)\n- Valid identity → no error (already exists, verify still passes)\n\n## Dont\n- Do NOT validate DID format (e.g., did:plc: prefix) — just check non-empty\n- Do NOT validate in handler.go — keep validation at the parse layer\n- Do NOT change the Event/RecordEvent/IdentityEvent struct definitions","acceptance_criteria":"1. `ParseEvent` returns error for record events with empty DID, Collection, RKey, or Action\n2. `ParseEvent` returns error for identity events with empty DID\n3. At least 5 new test cases in event_test.go covering all validation paths\n4. All existing event tests still pass\n5. `go test ./internal/tap/...` passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T16:31:55.130608+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:40:27.151654+08:00","closed_at":"2026-02-18T16:40:27.151654+08:00","close_reason":"c763c4f validate required fields in ParseEvent to prevent garbage URIs","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-md3.5","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:31:55.131661+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.6","title":"Return error from records.Delete failure instead of silently swallowing","description":"## Files\n- internal/tap/handler.go (modify)\n- internal/tap/handler_test.go (modify)\n\n## What to do\nIn `HandleRecord()` at lines 69-71, when `records.Delete()` fails, the error is logged at Debug level and execution continues to send an ack (via the nil return at line 81). This means a failed delete is acked to Tap and the event is lost forever.\n\nCurrent code (lines 68-71):\n```go\ncase ActionDelete:\n    if err := h.records.Delete(ctx, uri); err != nil {\n        slog.Debug(\"Failed to delete record\", \"uri\", uri, \"error\", err)\n    }\n```\n\nFix: Return the error so the consumer does NOT ack:\n\n```go\ncase ActionDelete:\n    if err := h.records.Delete(ctx, uri); err != nil {\n        return fmt.Errorf(\"failed to delete record: %w\", err)\n    }\n```\n\nKeep the PubSub publish and activity logging AFTER the successful delete (they should only run if delete succeeded). The fixed block should be:\n\n```go\ncase ActionDelete:\n    if err := h.records.Delete(ctx, uri); err != nil {\n        return fmt.Errorf(\"failed to delete record: %w\", err)\n    }\n    if h.pubsub != nil {\n        h.pubsub.PublishRecord(subscription.EventDelete, uri, \"\", event.DID, event.Collection, nil)\n    }\n    if h.activity != nil {\n        if _, err := h.activity.LogActivity(ctx, time.Now(), \"delete\", event.Collection, event.DID, event.RKey, \"\"); err != nil {\n            slog.Debug(\"Failed to log delete activity\", \"error\", err)\n        }\n    }\n```\n\nNOTE: If B4 (pubsub nil guard) lands first, the pubsub nil check will already be there. If not, add it here.\n\nAdd a test `TestIndexHandler_HandleRecord_DeleteError` that:\n1. Creates a handler with a real SQLite DB\n2. Attempts to delete a non-existent URI\n3. Verifies... actually `DELETE FROM record WHERE uri = X` succeeds even if nothing matches (SQL DELETE of 0 rows is not an error). So to test this, we need to cause an actual DB error. Instead, verify the behavioral change: the test should verify that the function properly wraps and returns errors from the delete path by checking the error message format.\n\nA simpler approach: Just verify the code path by confirming that for a valid delete (record exists), it returns nil and publishes correctly. The existing `TestIndexHandler_HandleRecord_Delete` already covers this.\n\nFocus the new test on verifying the error propagation by checking the `fmt.Errorf` wrapping is present in the code structure. Or add a test that verifies delete of a non-existent record does NOT return an error (since SQL DELETE of 0 rows is fine).\n\n## Dont\n- Do NOT change the records.Delete() repository method signature\n- Do NOT add a \"not found\" check for 0 affected rows — SQL DELETE of 0 rows is fine\n- Do NOT change the create/update error handling pattern (those already return errors correctly)","acceptance_criteria":"1. `HandleRecord` with ActionDelete returns `fmt.Errorf(\"failed to delete record: %w\", err)` when `records.Delete()` fails\n2. PubSub publish and activity logging only occur AFTER successful delete\n3. Existing `TestIndexHandler_HandleRecord_Delete` still passes\n4. All existing handler tests still pass\n5. `go test ./internal/tap/...` passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-18T16:32:14.758776+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:42:11.520776+08:00","closed_at":"2026-02-18T16:42:11.520776+08:00","close_reason":"9525b34 return error from records.Delete failure instead of silently swallowing","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-md3.6","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:32:14.760746+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-md3.6","depends_on_id":"hyperindex-md3.4","type":"blocks","created_at":"2026-02-18T16:33:33.695173+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.7","title":"Update activity status to completed/failed after record processing","description":"## Files\n- internal/tap/handler.go (modify)\n- internal/tap/handler_test.go (modify)\n\n## What to do\nIn `HandleRecord()`, `LogActivity()` is called at lines 56 and 74 which returns `(int64, error)` — the int64 is the activity row ID. Currently the ID is discarded (assigned to `_`). The activity entry is logged with status \"pending\" (the default in `LogActivity`) but never updated to \"completed\" or \"failed\". Entries stay stuck as \"pending\" forever.\n\nFix: For create/update (lines 54-59), capture the activity ID and update status:\n\n```go\n// Log activity (if activity repo available)\nif h.activity != nil {\n    activityID, err := h.activity.LogActivity(ctx, time.Now(), string(event.Action), event.Collection, event.DID, event.RKey, string(event.Record))\n    if err != nil {\n        slog.Debug(\"Failed to log activity\", \"error\", err)\n    } else {\n        if err := h.activity.UpdateStatus(ctx, activityID, \"completed\", nil); err != nil {\n            slog.Debug(\"Failed to update activity status\", \"error\", err)\n        }\n    }\n}\n```\n\nFor delete (lines 73-77), same pattern:\n\n```go\nif h.activity != nil {\n    activityID, err := h.activity.LogActivity(ctx, time.Now(), \"delete\", event.Collection, event.DID, event.RKey, \"\")\n    if err != nil {\n        slog.Debug(\"Failed to log delete activity\", \"error\", err)\n    } else {\n        if err := h.activity.UpdateStatus(ctx, activityID, \"completed\", nil); err != nil {\n            slog.Debug(\"Failed to update activity status\", \"error\", err)\n        }\n    }\n}\n```\n\nThe `UpdateStatus` method signature is: `func (r *JetstreamActivityRepository) UpdateStatus(ctx context.Context, id int64, status string, errorMessage *string) error`\n\nAdd/update the test `TestIndexHandler_HandleRecord_ActivityLogged` to also verify:\n1. The activity entry status is \"completed\" (not \"pending\")\n2. Query the activity entry by ID and check its status field\n\nThe `JetstreamActivityRepository` does not have a `GetByID` method. Instead, use `GetRecentActivity(ctx, 1)` and check the first entry status. Alternatively, the test can query the DB directly via testutil.\n\n## Dont\n- Do NOT change the LogActivity or UpdateStatus signatures\n- Do NOT make activity logging blocking for the main flow — keep errors as Debug-level log-and-continue\n- Do NOT add a LogActivityWithStatus(\"completed\") shortcut — use the existing two-step LogActivity+UpdateStatus pattern for consistency with the rest of the codebase","acceptance_criteria":"1. Activity ID from `LogActivity` is captured (not discarded) in both create/update and delete paths\n2. `UpdateStatus(ctx, activityID, \"completed\", nil)` is called after successful LogActivity\n3. Test verifies activity entries have status \"completed\" not \"pending\"\n4. Activity update errors are logged at Debug level (not returned)\n5. All existing handler tests still pass\n6. `go test ./internal/tap/...` passes","status":"in_progress","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T16:32:31.735235+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:42:27.741892+08:00","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-md3.7","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:32:31.73632+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-md3.7","depends_on_id":"hyperindex-md3.6","type":"blocks","created_at":"2026-02-18T16:33:33.799152+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.8","title":"Remove static SECRET_KEY_BASE default from docker-compose.tap.yml","description":"## Files\n- docker-compose.tap.yml (modify)\n\n## What to do\nAt line 31 in docker-compose.tap.yml:\n```yaml\nSECRET_KEY_BASE: \"${SECRET_KEY_BASE:-development-secret-key-change-in-production-64chars}\"\n```\n\nThe static default `development-secret-key-change-in-production-64chars` is a security risk — anyone who deploys with the default compose file without setting the env var gets a known secret key. Session tokens signed with this key would be forgeable.\n\nFix: Change to require the variable be set:\n```yaml\nSECRET_KEY_BASE: \"${SECRET_KEY_BASE:?SECRET_KEY_BASE must be set - generate with: openssl rand -hex 32}\"\n```\n\nThe `:?` syntax makes docker compose fail with an error message if the variable is not set.\n\nAlso fix the `TAP_ADMIN_PASSWORD` default on line 15 — it has `:-` (empty default) which means Tap admin API runs without auth:\n```yaml\nTAP_ADMIN_PASSWORD: \"${TAP_ADMIN_PASSWORD:?TAP_ADMIN_PASSWORD must be set}\"\n```\n\nAnd on line 29 (hyperindex service):\n```yaml\nTAP_ADMIN_PASSWORD: \"${TAP_ADMIN_PASSWORD:?TAP_ADMIN_PASSWORD must be set}\"\n```\n\nAlso while here, fix C4 — bind the Tap port to localhost only (line 7):\n```yaml\nports:\n  - \"127.0.0.1:2480:2480\"\n```\n\n## Dont\n- Do NOT change any other environment variables\n- Do NOT change the Dockerfile or docker-compose.yml (only docker-compose.tap.yml)\n- Do NOT remove the ADMIN_DIDS default (empty is fine — it just means no admin access)","acceptance_criteria":"1. SECRET_KEY_BASE uses `${SECRET_KEY_BASE:?...}` syntax (no default value)\n2. TAP_ADMIN_PASSWORD uses `${TAP_ADMIN_PASSWORD:?...}` syntax on BOTH services (lines 15 and 29)\n3. Tap port is bound to localhost: `127.0.0.1:2480:2480`\n4. `docker compose -f docker-compose.tap.yml config` fails with clear error if SECRET_KEY_BASE or TAP_ADMIN_PASSWORD are unset\n5. File is valid YAML","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T16:32:46.578786+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:40:27.244735+08:00","closed_at":"2026-02-18T16:40:27.244735+08:00","close_reason":"7b362ca security: require SECRET_KEY_BASE and TAP_ADMIN_PASSWORD, bind tap to localhost","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-md3.8","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:32:46.580309+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-md3.9","title":"Fix README Tap curl example: Bearer should be Basic auth","description":"## Files\n- README.md (modify)\n\n## What to do\nAt line 72 in README.md, the Tap admin API curl example uses `Bearer` auth:\n```bash\ncurl -X POST http://localhost:2480/repos/add \\\n  -H \"Authorization: Bearer ${TAP_ADMIN_PASSWORD}\" \\\n```\n\nBut the Tap admin client in `internal/tap/admin.go` sends Basic auth (password-only, no username). Looking at the Tap source code, it actually accepts either format depending on version, but the code in admin.go uses:\n```go\nreq.SetBasicAuth(\"\", c.password)\n```\n\nFix: Update the README curl example to match what the code sends:\n```bash\ncurl -X POST http://localhost:2480/repos/add \\\n  -u \":${TAP_ADMIN_PASSWORD}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"dids\": [\"did:plc:your-did-here\"]}'\n```\n\nThe `-u \":password\"` syntax sends Basic auth with empty username, which is equivalent to what `req.SetBasicAuth(\"\", password)` does.\n\n## Dont\n- Do NOT change the admin.go code — the README should match the code\n- Do NOT change any other README sections\n- Do NOT add additional curl examples","acceptance_criteria":"1. README curl example for Tap admin uses `-u \":${TAP_ADMIN_PASSWORD}\"` (Basic auth) instead of `-H \"Authorization: Bearer ...\"`\n2. The curl command is syntactically correct and would work with a running Tap instance\n3. No other README sections are changed","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-18T16:32:57.530897+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:40:27.336004+08:00","closed_at":"2026-02-18T16:40:27.336004+08:00","close_reason":"db029dc fix: use Basic auth in README Tap curl example","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-md3.9","depends_on_id":"hyperindex-md3","type":"parent-child","created_at":"2026-02-18T16:32:57.532476+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00","title":"Epic: Fix bugs identified by code review of filter-feature","description":"## Why\nThe filter-feature branch (epic hyperindex-49s) has 14 completed tasks implementing GraphQL filtering, sorting, search, and pagination. Eight specialized code reviewers identified 10 bugs ranging from data corruption (cursor encoding) to security issues (LIKE wildcard injection) to DoS vectors (unbounded IN clauses, no query timeout). These must be fixed before merging to main.\n\n## What Success Looks Like\n- All 4 HIGH priority bugs fixed: cursor encoding, backward pagination, IN clause limit, query timeout\n- All 6 MEDIUM priority bugs fixed: LIKE escape, DID filter, field name collisions, JSON error logging, search min length, filter cap\n- Missing unit tests added for helper functions\n- All existing tests still pass (go test ./...)\n- No breaking changes to the GraphQL API\n\n## Key Constraints\n- All changes on the filter-feature branch\n- Must work on both SQLite and PostgreSQL\n- Each fix must include a regression test\n- No breaking changes to existing queries","status":"closed","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-18T15:32:53.927543+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:59:22.255246+08:00","closed_at":"2026-02-18T15:59:22.255246+08:00","close_reason":"56a3c6f All 11 bug fixes from code review complete, all tests passing","labels":["scope:medium"]}
+{"id":"hyperindex-q00.1","title":"Fix cursor pipe delimiter collision in encodeCursorValues/decodeCursorValues","description":"## Files\n- internal/graphql/schema/builder.go (modify) — lines 1086-1098\n\n## What to do\nReplace the `|`-delimited cursor encoding with JSON array encoding to prevent corruption when sort field values contain `|`.\n\n**Current code (broken):**\n```go\nfunc encodeCursorValues(values ...string) string {\n    return base64.URLEncoding.EncodeToString([]byte(strings.Join(values, \"|\")))\n}\nfunc decodeCursorValues(cursor string) ([]string, error) {\n    data, err := base64.URLEncoding.DecodeString(cursor)\n    if err != nil { return nil, fmt.Errorf(\"invalid cursor\") }\n    return strings.Split(string(data), \"|\"), nil\n}\n```\n\n**New implementation:**\n```go\nfunc encodeCursorValues(values ...string) string {\n    jsonBytes, _ := json.Marshal(values)\n    return base64.URLEncoding.EncodeToString(jsonBytes)\n}\nfunc decodeCursorValues(cursor string) ([]string, error) {\n    data, err := base64.URLEncoding.DecodeString(cursor)\n    if err != nil { return nil, fmt.Errorf(\"invalid cursor\") }\n    var parts []string\n    if err := json.Unmarshal(data, \u0026parts); err != nil {\n        // Backward compatibility: try legacy pipe-delimited format\n        parts = strings.Split(string(data), \"|\")\n        if len(parts) \u003c 2 {\n            return nil, fmt.Errorf(\"invalid cursor format\")\n        }\n    }\n    return parts, nil\n}\n```\n\nThe backward-compatibility fallback ensures existing cursors from clients still work during the transition. The `encodeCursor` and `decodeCursor` wrapper functions remain unchanged — they delegate to these.\n\n## Dont\n- Do NOT change the `encodeCursor`/`decodeCursor` wrapper functions (lines 1100-1117) — they delegate to these and should keep working\n- Do NOT change the base64 encoding scheme (URLEncoding)\n- Do NOT remove the `strings` import — it is still used elsewhere in the file","acceptance_criteria":"1. `encodeCursorValues(\"hello|world\", \"at://did:plc:abc/col/rkey\")` produces a cursor that `decodeCursorValues` correctly decodes back to `[\"hello|world\", \"at://did:plc:abc/col/rkey\"]`\n2. Legacy cursors (pipe-delimited, no pipes in values) still decode correctly via the fallback path\n3. `decodeCursorValues(\"!!!invalid!!!\")` returns an error\n4. `go test -v -run TestEncodeDecode ./internal/graphql/schema/...` passes — add a table-driven test with cases: normal values, values containing pipes, empty strings, single value, legacy format\n5. All existing tests pass: `go test ./...`","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T15:33:11.786051+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:44:03.485106+08:00","closed_at":"2026-02-18T15:44:03.485106+08:00","close_reason":"6c2350d Fix cursor pipe delimiter collision with JSON encoding","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-q00.1","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:33:11.787209+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.10","title":"Add MaxFilterConditions cap to prevent abuse","description":"## Files\n- internal/graphql/schema/builder.go (modify) — extractFilters function, around line 540\n- internal/database/repositories/records.go (modify) — add constant\n\n## What to do\nUsers can pass an unlimited number of filter conditions in a single query, which could generate extremely complex SQL. Add a cap.\n\n1. Add constant in `records.go` near the other constants:\n```go\n// MaxFilterConditions is the maximum number of individual filter conditions allowed per query.\nconst MaxFilterConditions = 20\n```\n\n2. In `extractFilters` in `builder.go`, after building the filters slice, validate:\n```go\nfunc extractFilters(whereArg interface{}, collection string, registry *lexicon.Registry) ([]repositories.FieldFilter, string) {\n```\n\nThe function currently returns `([]repositories.FieldFilter, string)`. Change it to return an error:\n```go\nfunc extractFilters(whereArg interface{}, collection string, registry *lexicon.Registry) ([]repositories.FieldFilter, string, error) {\n```\n\nAfter the loop that builds filters, add:\n```go\nif len(filters) \u003e repositories.MaxFilterConditions {\n    return nil, \"\", fmt.Errorf(\"too many filter conditions: %d (maximum %d)\", len(filters), repositories.MaxFilterConditions)\n}\n```\n\n3. Update the caller in `resolveRecordConnection` (line 673) to handle the error:\n```go\nif whereArg, ok := p.Args[\"where\"]; ok \u0026\u0026 whereArg != nil {\n    var err error\n    filters, didFilter, err = extractFilters(whereArg, collection, b.registry)\n    if err != nil {\n        return nil, err\n    }\n}\n```\n\n## Dont\n- Do NOT count the DID filter toward the cap (it is a single column condition)\n- Do NOT change the filter operators themselves\n- Do NOT set the cap lower than 20 (some legitimate queries may have many fields)","acceptance_criteria":"1. A query with 21 filter conditions returns an error containing \"too many filter conditions\"\n2. A query with 20 filter conditions succeeds\n3. A query with 0 filter conditions succeeds\n4. The DID filter does not count toward the cap\n5. `MaxFilterConditions` constant is exported and set to 20\n6. `extractFilters` now returns `([]FieldFilter, string, error)` and the caller handles the error\n7. All existing tests pass: `go test ./...`","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T15:35:25.881969+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:55:54.683671+08:00","closed_at":"2026-02-18T15:55:54.683671+08:00","close_reason":"fff01bd Add MaxFilterConditions cap to prevent filter abuse","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-q00.10","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:35:25.883409+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.11","title":"Add missing unit tests for helper functions","description":"## Files\n- internal/graphql/schema/builder_test.go (create) — new test file\n- internal/graphql/query/connection_test.go (create) — new test file\n\n## What to do\nAdd table-driven unit tests for the following helper functions that currently have zero test coverage:\n\n### 1. ClampPageSize (internal/graphql/query/connection.go)\nCreate `internal/graphql/query/connection_test.go`:\n```go\nfunc TestClampPageSize(t *testing.T) {\n    // Cases: 0 → 20 (default), -1 → 20, 50 → 50, 100 → 100, 101 → 100 (max), 200 → 100\n}\n```\n\n### 2. isTotalCountRequested (internal/graphql/schema/builder.go)\nThis is harder to test in isolation because it requires a `graphql.ResolveParams` with AST. If too complex to mock, skip and note in a comment.\n\n### 3. sortFieldValueForRecord (internal/graphql/schema/builder.go)\nCreate `internal/graphql/schema/builder_test.go`:\n```go\nfunc TestSortFieldValueForRecord(t *testing.T) {\n    // Cases: nil sortOpt → indexed_at, direct column fields (uri, did, cid, rkey, collection, indexed_at),\n    // JSON field present, JSON field missing → \"\"\n}\n```\n\n### 4. extractFilters (internal/graphql/schema/builder.go)\n```go\nfunc TestExtractFilters(t *testing.T) {\n    // Cases: nil whereArg, empty map, single eq filter, multiple operators,\n    // did filter extraction, unknown field type → defaults to string\n}\n```\nNote: extractFilters requires a lexicon.Registry. Create a minimal one in the test or pass nil and test the default behavior.\n\n### 5. emptyConnection (internal/graphql/schema/builder.go)\n```go\nfunc TestEmptyConnection(t *testing.T) {\n    // Verify structure: edges is empty slice, pageInfo has all false/nil, totalCount is 0\n}\n```\n\n## Dont\n- Do NOT test private functions that are already covered by integration tests\n- Do NOT add tests that require a running database (those are integration tests)\n- Do NOT modify any production code in this task — only add test files\n- If a function is unexported and hard to test from the _test package, use the same package (not _test suffix)","acceptance_criteria":"1. `go test -v -run TestClampPageSize ./internal/graphql/query/...` passes with at least 5 test cases\n2. `go test -v -run TestSortFieldValueForRecord ./internal/graphql/schema/...` passes with at least 6 test cases\n3. `go test -v -run TestExtractFilters ./internal/graphql/schema/...` passes with at least 4 test cases\n4. `go test -v -run TestEmptyConnection ./internal/graphql/schema/...` passes\n5. All tests are table-driven with descriptive case names\n6. All existing tests pass: `go test ./...`","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T15:35:43.714828+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:58:31.003592+08:00","closed_at":"2026-02-18T15:58:31.003592+08:00","close_reason":"56a3c6f test: add unit tests for ClampPageSize, sortFieldValueForRecord, emptyConnection","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:35:43.715871+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.1","type":"blocks","created_at":"2026-02-18T15:35:53.411072+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.2","type":"blocks","created_at":"2026-02-18T15:35:53.523573+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.3","type":"blocks","created_at":"2026-02-18T15:35:53.636488+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.4","type":"blocks","created_at":"2026-02-18T15:35:53.747742+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.5","type":"blocks","created_at":"2026-02-18T15:35:53.865242+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.6","type":"blocks","created_at":"2026-02-18T15:35:53.978956+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.7","type":"blocks","created_at":"2026-02-18T15:35:54.092679+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.8","type":"blocks","created_at":"2026-02-18T15:35:54.208203+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.9","type":"blocks","created_at":"2026-02-18T15:35:54.331806+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.11","depends_on_id":"hyperindex-q00.10","type":"blocks","created_at":"2026-02-18T15:35:54.44539+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.2","title":"Fix records query backward pagination broken by DefaultValue on first arg","description":"## Files\n- internal/graphql/schema/builder.go (modify) — lines 400-404\n\n## What to do\nRemove `DefaultValue: 20` from the `first` argument of the generic `records` query. The problem: `DefaultValue: 20` means `p.Args[\"first\"].(int)` always succeeds (returns 20), so `hasFirst` at line 659 is always true. When a user sends `records(last: 5, collection: \"...\")`, the validation at line 665 fires \"cannot use both first/after and last/before\" because `hasFirst` is true.\n\n**Current code (broken):**\n```go\n\"first\": \u0026graphql.ArgumentConfig{\n    Type:         graphql.Int,\n    DefaultValue: 20,\n    Description:  \"Number of records to return\",\n},\n```\n\n**Fix:**\n```go\n\"first\": \u0026graphql.ArgumentConfig{\n    Type:        graphql.Int,\n    Description: \"Number of records to return (default 20, max 100)\",\n},\n```\n\nThis is safe because `resolveRecordConnection` at line 775 already calls `query.ClampPageSize(firstArg)` which returns 20 when firstArg is 0 (the zero value when the type assertion fails).\n\n## Dont\n- Do NOT change `ClampPageSize` behavior\n- Do NOT add DefaultValue to the `last` argument\n- Do NOT modify any other query definitions (typed collection queries do not have this bug — verify they also lack DefaultValue)","acceptance_criteria":"1. GraphQL query `{ records(collection: \"test.collection\", last: 5) { edges { node { uri } } } }` does NOT return error \"cannot use both first/after and last/before\"\n2. GraphQL query `{ records(collection: \"test.collection\") { edges { node { uri } } } }` still returns up to 20 records (ClampPageSize default)\n3. GraphQL query `{ records(collection: \"test.collection\", first: 50) { edges { node { uri } } } }` returns up to 50 records\n4. All existing tests pass: `go test ./...`","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T15:33:23.861269+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:38:44.479379+08:00","closed_at":"2026-02-18T15:38:44.479379+08:00","close_reason":"09fd2a3 fix: remove DefaultValue from records query first arg to fix backward pagination","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-q00.2","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:33:23.862324+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.3","title":"Add MaxINListSize limit to prevent SQLite parameter overflow","description":"## Files\n- internal/database/repositories/records.go (modify) — lines 413-426, and near line 16\n\n## What to do\nAdd a `MaxINListSize` constant and validate the `in` operator list length in `buildFilterClause` before building the query.\n\n1. Add constant near the existing batch size constants (line 16-26):\n```go\n// MaxINListSize is the maximum number of values allowed in an IN filter clause.\n// SQLite has a hard 999 parameter limit (SQLITE_MAX_VARIABLE_NUMBER).\n// We cap well below that to leave room for other query parameters.\nconst MaxINListSize = 100\n```\n\n2. In `buildFilterClause`, in the `case \"in\":` block (line 413), add validation:\n```go\ncase \"in\":\n    inVals, _ := f.Value.([]interface{})\n    if len(inVals) == 0 {\n        conditions = append(conditions, \"1 = 0\")\n        continue\n    }\n    if len(inVals) \u003e MaxINListSize {\n        return \"\", nil, fmt.Errorf(\"IN filter on field %q exceeds maximum of %d values\", f.Field, MaxINListSize)\n    }\n    // ... rest unchanged\n```\n\n3. Update `buildFilterClause` signature to return an error:\n```go\nfunc (r *RecordsRepository) buildFilterClause(filters []FieldFilter, startPlaceholder int) (string, []database.Value, error)\n```\n\n4. Update ALL callers of `buildFilterClause` to handle the new error return. Search for `buildFilterClause(` — there should be callers in `GetByCollectionFilteredWithKeysetCursor`, `GetByCollectionSortedWithKeysetCursor`, `GetByCollectionReversedWithKeysetCursor`, and `GetCollectionCountFiltered`.\n\n## Dont\n- Do NOT change the existing `SQLParamBatchSize` constant\n- Do NOT change the behavior for empty IN lists (keep returning \"1 = 0\")\n- Do NOT silently truncate — return an error so the GraphQL layer can report it to the user","acceptance_criteria":"1. `buildFilterClause` with an IN list of 101 values returns a non-nil error containing \"exceeds maximum\"\n2. `buildFilterClause` with an IN list of 100 values succeeds\n3. `buildFilterClause` with an empty IN list still returns \"1 = 0\" condition\n4. Add a table-driven test `TestBuildFilterClause_INLimit` in `records_filter_test.go` covering: 0 values, 1 value, 100 values (boundary), 101 values (error)\n5. All callers of `buildFilterClause` propagate the error correctly\n6. All existing tests pass: `go test ./...`","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-18T15:33:40.428928+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:46:10.57729+08:00","closed_at":"2026-02-18T15:46:10.57729+08:00","close_reason":"ff5e7f5 Add MaxINListSize limit to prevent SQLite parameter overflow","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-q00.3","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:33:40.429954+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.4","title":"Add search query timeout and concurrency control","description":"## Files\n- internal/database/repositories/records.go (modify) — Search method (~line 1095)\n- internal/database/repositories/records.go (modify) — add constants near line 16\n\n## What to do\nThe LIKE-based `Search` method does full table scans with no per-query timeout. SQLite uses `SetMaxOpenConns(1)`, so one expensive query blocks everything. Add a search-specific context timeout.\n\n1. Add constant:\n```go\n// SearchTimeout is the maximum duration for a search query.\nconst SearchTimeout = 10 * time.Second\n```\n\n2. At the top of the `Search` method, wrap the context with a timeout:\n```go\nfunc (r *RecordsRepository) Search(ctx context.Context, ...) ([]*Record, error) {\n    ctx, cancel := context.WithTimeout(ctx, SearchTimeout)\n    defer cancel()\n    // ... rest of method unchanged\n}\n```\n\nThis is the minimal, safe fix. The `context.WithTimeout` will cause the SQL query to be cancelled if it exceeds 10 seconds, and the database/sql package will return a context deadline exceeded error.\n\n## Dont\n- Do NOT add a semaphore or concurrency limiter — that is a larger architectural change for a separate task\n- Do NOT change the Search method signature\n- Do NOT add timeout to other repository methods (only Search does full table scans)\n- Do NOT import any new packages beyond what is already imported (time and context are already imported)","acceptance_criteria":"1. The `Search` method creates a derived context with `context.WithTimeout(ctx, SearchTimeout)` and defers cancel\n2. `SearchTimeout` constant is exported and set to 10 seconds\n3. A unit test `TestSearchTimeout` verifies that the timeout is applied (can check that the context passed to the DB has a deadline set, or test with a very short timeout)\n4. All existing tests pass: `go test ./...`","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-18T15:33:52.911528+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:59:18.948483+08:00","closed_at":"2026-02-18T15:59:18.948483+08:00","close_reason":"0af843c Add search query timeout and concurrency control","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-q00.4","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:33:52.912629+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.5","title":"Fix LIKE wildcard injection in contains/startsWith filter operators","description":"## Files\n- internal/database/repositories/records.go (modify) — lines 396-405\n\n## What to do\nThe `contains` and `startsWith` operators in `buildFilterClause` do NOT call `escapeLIKE()` on user input. The `escapeLIKE` function already exists at line 1084 and is used by the `Search` method, but the filter operators skip it. Values containing `%` or `_` act as SQL wildcards.\n\n**Current code (broken):**\n```go\ncase \"contains\":\n    conditions = append(conditions, fmt.Sprintf(\"%s LIKE %s\", extract, r.db.Placeholder(placeholderIdx)))\n    val := fmt.Sprintf(\"%%%v%%\", f.Value)\n    params = append(params, database.Text(val))\ncase \"startsWith\":\n    conditions = append(conditions, fmt.Sprintf(\"%s LIKE %s\", extract, r.db.Placeholder(placeholderIdx)))\n    val := fmt.Sprintf(\"%v%%\", f.Value)\n    params = append(params, database.Text(val))\n```\n\n**Fix — apply escapeLIKE and add ESCAPE clause:**\n```go\ncase \"contains\":\n    conditions = append(conditions, fmt.Sprintf(\"%s LIKE %s ESCAPE \\\", extract, r.db.Placeholder(placeholderIdx)))\n    val := fmt.Sprintf(\"%%%s%%\", escapeLIKE(fmt.Sprintf(\"%v\", f.Value)))\n    params = append(params, database.Text(val))\ncase \"startsWith\":\n    conditions = append(conditions, fmt.Sprintf(\"%s LIKE %s ESCAPE \\\", extract, r.db.Placeholder(placeholderIdx)))\n    val := fmt.Sprintf(\"%s%%\", escapeLIKE(fmt.Sprintf(\"%v\", f.Value)))\n    params = append(params, database.Text(val))\n```\n\nAlso handle PostgreSQL dialect: if `r.db.Dialect() == database.PostgreSQL`, use `ILIKE` instead of `LIKE` for case-insensitive matching (matching the Search method behavior). Actually, check the existing Search method — if it uses ILIKE for Postgres, do the same here. If not, keep LIKE for both.\n\n## Dont\n- Do NOT modify the `escapeLIKE` function itself\n- Do NOT change the Search method\n- Do NOT add ESCAPE clause to operators other than contains/startsWith (eq, neq, etc. use = not LIKE)","acceptance_criteria":"1. A filter `{title: {contains: \"100%\"}}` matches only records where title literally contains \"100%\", not records where title contains \"100\" followed by anything\n2. A filter `{title: {startsWith: \"test_\"}}` matches only records where title starts with literal \"test_\", not \"test\" + any single char\n3. The LIKE clause includes `ESCAPE \\` \n4. Add test cases in `records_filter_test.go`: `TestBuildFilterClause_LIKEEscape` with values containing %, _, and \\\n5. All existing tests pass: `go test ./...`","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T15:34:09.353004+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:48:21.269548+08:00","closed_at":"2026-02-18T15:48:21.269548+08:00","close_reason":"c9d2dc3 fix: escape LIKE wildcards in contains/startsWith filter operators","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-q00.5","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:34:09.354258+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-q00.5","depends_on_id":"hyperindex-q00.3","type":"blocks","created_at":"2026-02-18T15:35:59.089925+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.6","title":"Expand DID filter to support all StringFilter operators, not just eq","description":"## Files\n- internal/graphql/schema/builder.go (modify) — extractFilters function, lines 550-557\n- internal/database/repositories/records.go (modify) — query methods that accept didFilter string\n\n## What to do\nThe WhereInput exposes full `StringFilterInput` for `did` (eq, neq, in, contains, startsWith, etc.) but `extractFilters` only handles `eq`. Other operators are silently ignored.\n\n**Option A (recommended — simpler):** Restrict the GraphQL type to only accept `eq` and `in` for DID. Replace `types.StringFilterInput` with a new `DIDFilterInput` that only has `eq` and `in` fields. This is the safer approach since DID is a column, not a JSON field, and operators like `contains` on DIDs are not meaningful.\n\n**Option B:** Expand `extractFilters` to convert DID filter operators into SQL WHERE conditions on the `did` column. This requires changing the `didFilter string` parameter to something richer (e.g., `[]FieldFilter` with a special marker for column filters vs JSON filters).\n\n**Go with Option A.** Create a restricted input type:\n\n1. In `internal/graphql/types/filters.go`, add:\n```go\n// DIDFilterInput is a restricted filter for DID fields (column-level, not JSON).\n// Only supports eq and in operators.\nvar DIDFilterInput = graphql.NewInputObject(graphql.InputObjectConfig{\n    Name: \"DIDFilterInput\",\n    Fields: graphql.InputObjectConfigFieldMap{\n        \"eq\": \u0026graphql.InputObjectFieldConfig{Type: graphql.String, Description: \"Equals\"},\n        \"in\": \u0026graphql.InputObjectFieldConfig{Type: graphql.NewList(graphql.String), Description: \"In list\"},\n    },\n})\n```\n\n2. In `builder.go` line 166-168, change `types.StringFilterInput` to `types.DIDFilterInput` for the `did` field in WhereInput generation.\n\n3. In `extractFilters` (line 550-557), expand to handle `in`:\n```go\nif fieldName == \"did\" {\n    if eqVal, ok := filterMap[\"eq\"].(string); ok \u0026\u0026 eqVal != \"\" {\n        didFilter = eqVal\n    }\n    // Handle \"in\" for DID — convert to comma-separated or a slice\n    // Actually, the simplest approach: convert DID \"in\" to multiple FieldFilters on the did column\n    // But didFilter is a string... so for now, just support eq.\n    continue\n}\n```\n\nActually, the cleanest approach: change `didFilter` from `string` to `[]FieldFilter` where the Field is \"did\" (a column name). Then in the repository, handle \"did\" filters as column conditions instead of JSON extract conditions. But this is a bigger refactor.\n\n**Simplest safe fix:** Keep `didFilter string` for `eq` only, but add `in` support by changing `didFilter` to a new type:\n```go\ntype DIDFilter struct {\n    EQ string\n    IN []string\n}\n```\n\nThen update `extractFilters` to populate both fields, and update repository methods to build the appropriate WHERE clause.\n\n## Dont\n- Do NOT add contains/startsWith/gt/lt operators for DID — they are not meaningful\n- Do NOT break existing DID eq filtering\n- Do NOT change the FieldFilter struct — DID filtering is column-level, not JSON-level","acceptance_criteria":"1. WhereInput for any collection shows `did: DIDFilterInput` (not StringFilterInput) in the schema\n2. `DIDFilterInput` only has `eq` and `in` fields\n3. `{where: {did: {eq: \"did:plc:abc\"}}}` still works as before\n4. `{where: {did: {in: [\"did:plc:abc\", \"did:plc:def\"]}}}` returns records from both DIDs\n5. Passing unsupported operators like `{where: {did: {contains: \"abc\"}}}` is rejected by GraphQL schema validation (not silently ignored)\n6. All existing tests pass: `go test ./...`","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":45,"created_at":"2026-02-18T15:34:32.797385+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:53:38.437521+08:00","closed_at":"2026-02-18T15:53:38.437521+08:00","close_reason":"b149838 fix: expand DID filter to support eq and in operators","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-q00.6","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:34:32.798459+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.7","title":"Skip lexicon properties that collide with reserved field names","description":"## Files\n- internal/graphql/types/object.go (modify) — buildRecordFields, lines 121-126\n- internal/graphql/schema/builder.go (modify) — WhereInput generation, lines 171-181\n\n## What to do\nLexicon properties named `did`, `rkey`, `uri`, or `cid` silently overwrite the standard metadata fields that are injected into typed record types and WhereInputs. This causes data corruption — the metadata field disappears and is replaced by the JSON property.\n\n1. In `internal/graphql/types/object.go`, in `buildRecordFields` (line 121), add a skip for reserved names:\n```go\n// reservedRecordFields are field names injected as metadata and must not be overwritten by lexicon properties.\nvar reservedRecordFields = map[string]bool{\n    \"uri\":  true,\n    \"cid\":  true,\n    \"did\":  true,\n    \"rkey\": true,\n}\n```\n\nThen in the loop at line 121:\n```go\nfor _, entry := range def.Properties {\n    if reservedRecordFields[entry.Name] {\n        slog.Warn(\"Skipping lexicon property that collides with reserved field name\",\n            \"lexicon\", lexiconID, \"property\", entry.Name)\n        continue\n    }\n    field := b.buildField(lexiconID, entry.Name, \u0026entry.Property, requiredSet[entry.Name])\n    if field != nil {\n        fields[entry.Name] = field\n    }\n}\n```\n\n2. In `builder.go`, in the WhereInput generation loop (line 172), add the same skip:\n```go\nfor _, entry := range lex.Defs.Main.Properties {\n    if entry.Name == \"did\" {\n        continue // did is handled separately as a metadata filter\n    }\n    if reservedRecordFields[entry.Name] {\n        continue // Skip properties that collide with reserved metadata fields\n    }\n    // ... rest unchanged\n}\n```\n\nNote: `did` is already handled separately in WhereInput (line 166), so the skip there is just for `uri`, `cid`, `rkey`.\n\n3. Add `\"log/slog\"` import to object.go if not already present.\n\n## Dont\n- Do NOT rename the conflicting properties (e.g., prefixing with underscore) — just skip them\n- Do NOT change the reserved field definitions themselves (uri, cid, did, rkey)\n- Do NOT skip properties in the generic record type (only typed record types)","acceptance_criteria":"1. A lexicon with a property named \"uri\" does not overwrite the metadata uri field on the typed GraphQL type\n2. A lexicon with a property named \"did\" does not overwrite the metadata did field\n3. A warning is logged (slog.Warn) when a property is skipped due to collision\n4. The WhereInput for a lexicon with a \"uri\" property does not include a duplicate \"uri\" filter field\n5. Normal lexicon properties (non-colliding) still appear on the typed record type\n6. All existing tests pass: `go test ./...`","status":"closed","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T15:34:49.855258+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:46:26.196831+08:00","closed_at":"2026-02-18T15:46:26.196831+08:00","close_reason":"d60d85d Skip lexicon properties that collide with reserved field names","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-q00.7","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:34:49.857079+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.8","title":"Log json.Unmarshal errors instead of silently skipping records","description":"## Files\n- internal/graphql/schema/builder.go (modify) — lines 722, 798, 883\n\n## What to do\nThree places in `resolveRecordConnection` and `createSearchResolver` silently skip records when `json.Unmarshal` fails on the record JSON. This hides data corruption. Add `slog.Warn` logging.\n\nFind all three locations where this pattern appears:\n```go\nif err := json.Unmarshal([]byte(rec.JSON), \u0026value); err != nil {\n    continue // Skip records with invalid JSON\n}\n```\n\nReplace each with:\n```go\nif err := json.Unmarshal([]byte(rec.JSON), \u0026value); err != nil {\n    slog.Warn(\"Skipping record with invalid JSON\", \"uri\", rec.URI, \"error\", err)\n    continue\n}\n```\n\nThe three locations are:\n1. Line ~722 — backward pagination path in `resolveRecordConnection`\n2. Line ~798 — forward pagination path in `resolveRecordConnection`\n3. Line ~883 — search resolver in `createSearchResolver`\n\nMake sure `\"log/slog\"` is in the imports (it likely already is — check).\n\n## Dont\n- Do NOT return an error — just log and continue (dropping one bad record should not fail the whole query)\n- Do NOT change the control flow (still continue after logging)\n- Do NOT add logging to any other error paths in this task","acceptance_criteria":"1. All three json.Unmarshal error paths in builder.go now log with slog.Warn including the record URI and error\n2. The log message includes \"uri\" and \"error\" structured fields\n3. Records with valid JSON are still returned normally\n4. All existing tests pass: `go test ./...`","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T15:35:01.67118+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:39:06.204066+08:00","closed_at":"2026-02-18T15:39:06.204066+08:00","close_reason":"09fd2a3 Log json.Unmarshal errors with slog.Warn in all three locations","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-q00.8","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:35:01.672253+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-q00.9","title":"Fix search minimum length to use rune count and increase to 3","description":"## Files\n- internal/graphql/schema/builder.go (modify) — createSearchResolver, line 844\n\n## What to do\nThe search minimum length check uses `len()` which counts bytes, not characters. A 2-byte UTF-8 character (e.g., \"é\") would pass the check with just 1 character. Also, 2 characters is too short for a meaningful LIKE search — increase to 3.\n\n**Current code:**\n```go\nif len(searchQuery) \u003c 2 {\n    return nil, fmt.Errorf(\"search query must be at least 2 characters\")\n}\n```\n\n**Fix:**\n```go\nif utf8.RuneCountInString(searchQuery) \u003c 3 {\n    return nil, fmt.Errorf(\"search query must be at least 3 characters\")\n}\n```\n\nAdd `\"unicode/utf8\"` to the imports.\n\n## Dont\n- Do NOT change the minimum for any other validation (only the search query)\n- Do NOT add maximum length validation in this task (that is a separate concern)","acceptance_criteria":"1. Search query \"ab\" returns error \"search query must be at least 3 characters\"\n2. Search query \"abc\" succeeds (3 chars)\n3. Search query \"éé\" (2 multi-byte chars, 4 bytes) returns error (only 2 runes)\n4. Search query \"éée\" (3 multi-byte chars) succeeds\n5. `unicode/utf8` is imported\n6. All existing tests pass: `go test ./...` — update any existing tests that use 2-char search queries to use 3+ chars","status":"closed","priority":2,"issue_type":"task","owner":"einstein.climateai.org","estimated_minutes":15,"created_at":"2026-02-18T15:35:12.361536+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T15:44:47.927275+08:00","closed_at":"2026-02-18T15:44:47.927275+08:00","close_reason":"99b68c3 Fix search minimum length to use rune count and increase to 3","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-q00.9","depends_on_id":"hyperindex-q00","type":"parent-child","created_at":"2026-02-18T15:35:12.362657+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-uau","title":"Fix: backoff resets unconditionally on failed dials (from hyperindex-md3.2)","description":"Review of hyperindex-md3.2 (commit 692e95b) found: backoff = minBackoff is placed unconditionally after every runOnce() call, including immediate dial failures. The comment says 'after a successful connection' but the code does not check for success. If the server is persistently unreachable, the effective maximum backoff is 2s (reset to 1s → wait 1s → double to 2s → reset to 1s...) instead of the intended 2 minutes. This defeats the purpose of exponential backoff for persistent outages. Fix: move the reset inside a success condition: if err == nil { backoff = minBackoff }. Evidence: consumer.go line 113 — backoff = minBackoff is outside any err check, runs unconditionally after runOnce() returns regardless of whether the dial succeeded.","status":"open","priority":1,"issue_type":"bug","owner":"einstein.climateai.org","created_at":"2026-02-18T16:49:37.491393+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T16:49:37.491393+08:00","dependencies":[{"issue_id":"hyperindex-uau","depends_on_id":"hyperindex-md3.2","type":"discovered-from","created_at":"2026-02-18T16:49:41.017962+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-vz7","title":"Epic: Fix NonNull GraphQL violations for required fields with missing data","description":"## Problem\nGraphQL warnings: 'Cannot return null for non-nullable field OrgHypercertsClaimActivity.title' (and shortDescription). The lexicon marks these fields as required, causing the schema to declare them as NonNull (String!). However, old records in the DB were written when these fields were optional, so their JSON lacks these keys. The resolver returns raw maps without coercion, causing NonNull violations.\n\n## Goal\nAdd a null-coercion layer in the resolver that, for each required field in the lexicon, ensures a type-appropriate zero value is present in the data map before returning it to GraphQL. This preserves schema strictness while handling historical data gracefully.\n\n## Scope\n- internal/graphql/schema/builder.go (resolver layer)\n- internal/graphql/types/object.go (optional: export zero-value helper)\n- internal/lexicon/types.go (optional: add helper to get zero value per type)\n- Tests for the coercion logic\n\n## Key Constraints\n- Do NOT make required fields nullable in the schema — that would be a schema regression\n- Do NOT validate/reject records at ingestion — we must tolerate historical data\n- Zero values: string → \"\", integer → 0, boolean → false, array → [], ref/union/blob → nil (keep nullable)\n- The coercion must happen in both createCollectionResolver and createSingleRecordResolver paths","status":"closed","priority":1,"issue_type":"epic","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","created_at":"2026-02-19T20:09:45.606789+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T20:17:45.88078+08:00","closed_at":"2026-02-19T20:17:45.880785+08:00","labels":["needs-integration-review","scope:medium"]}
+{"id":"hyperindex-vz7.1","title":"Add ZeroValue helper to lexicon package for type-appropriate defaults","description":"## Files\n- internal/lexicon/types.go (modify)\n- internal/lexicon/types_test.go (create)\n\n## What to do\nAdd a function `ZeroValueForType(propType string, format string) interface{}` to `internal/lexicon/types.go` that returns the appropriate Go zero value for a given lexicon property type:\n\n```go\nfunc ZeroValueForType(propType, format string) interface{} {\n    switch propType {\n    case TypeString:\n        return \"\"\n    case TypeInteger:\n        return 0\n    case TypeBoolean:\n        return false\n    case TypeArray:\n        return []interface{}{}\n    default:\n        // ref, union, blob, bytes, cid-link, unknown, object — return nil\n        // These are complex types that cannot have a meaningful zero value\n        return nil\n    }\n}\n```\n\nAlso add a method on `RecordDef` to get all required properties with their types:\n\n```go\n// RequiredProperties returns all properties that are marked as required.\nfunc (r *RecordDef) RequiredProperties() []PropertyEntry {\n    var result []PropertyEntry\n    for _, entry := range r.Properties {\n        if entry.Property.Required {\n            result = append(result, entry)\n        }\n    }\n    return result\n}\n```\n\n## Don't\n- Do not modify any existing methods or types\n- Do not change the Property struct\n- Do not add dependencies on graphql packages","acceptance_criteria":"1. `ZeroValueForType(\"string\", \"\")` returns `\"\"` (empty string)\n2. `ZeroValueForType(\"string\", \"datetime\")` returns `\"\"` (empty string)\n3. `ZeroValueForType(\"integer\", \"\")` returns `0` (int)\n4. `ZeroValueForType(\"boolean\", \"\")` returns `false`\n5. `ZeroValueForType(\"array\", \"\")` returns `[]interface{}{}`\n6. `ZeroValueForType(\"ref\", \"\")` returns `nil`\n7. `ZeroValueForType(\"union\", \"\")` returns `nil`\n8. `ZeroValueForType(\"blob\", \"\")` returns `nil`\n9. `RecordDef.RequiredProperties()` returns only entries where `Property.Required == true`\n10. `go test ./internal/lexicon/...` passes with new tests","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-19T20:10:02.055823+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T20:12:45.490745+08:00","closed_at":"2026-02-19T20:12:45.490745+08:00","close_reason":"7fc19ad Add ZeroValueForType and RequiredProperties to lexicon package","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-vz7.1","depends_on_id":"hyperindex-vz7","type":"parent-child","created_at":"2026-02-19T20:10:02.056679+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-vz7.2","title":"Add coerceRequiredFields to schema builder and wire into resolvers","description":"## Files\n- internal/graphql/schema/builder.go (modify)\n\n## What to do\nAdd a method `coerceRequiredFields(data map[string]interface{}, collection string)` to the `Builder` struct that:\n\n1. Looks up the `RecordDef` from `b.registry.GetRecordDef(collection)`\n2. Iterates over `RecordDef.RequiredProperties()` (from task vz7.1)\n3. For each required property, checks if `data[prop.Name]` is nil or absent\n4. If so, sets `data[prop.Name] = lexicon.ZeroValueForType(prop.Type, prop.Format)`\n5. Skips properties where `ZeroValueForType` returns nil (complex types like ref/union)\n6. Logs a `slog.Debug` message when coercing a field (for observability)\n\nThen wire this into the two resolver paths:\n\n### Path 1: `createCollectionResolver` (line ~974)\nIn the `buildNode` callback, after `data[\"rkey\"] = rec.RKey`, add:\n```go\nb.coerceRequiredFields(data, lexiconID)\n```\n\n### Path 2: `createSingleRecordResolver` (line ~1018)\nAfter `data[\"rkey\"] = rec.RKey`, add:\n```go\nb.coerceRequiredFields(data, lexiconID)\n```\n\n### Path 3: `resolveRecordConnection` backward pagination path (line ~753)\nThe `buildNode` callback is already called, so this is covered by Path 1.\n\n### Path 4: Generic `createRecordsResolver` (line ~937 area)\nCheck if there is a generic records resolver that also returns record data maps. If it uses a `buildNode` callback, it's already covered. If not, add coercion there too.\n\nThe signature:\n```go\n// coerceRequiredFields fills in zero values for required fields that are missing or null.\n// This prevents NonNull violations when historical records lack fields that became required.\nfunc (b *Builder) coerceRequiredFields(data map[string]interface{}, collection string) {\n```\n\n## Don't\n- Do not change the GraphQL schema (no nullability changes)\n- Do not modify how records are stored or ingested\n- Do not add any new dependencies\n- Do not change the function signatures of existing resolvers\n- Do not coerce fields that already have a non-nil value","acceptance_criteria":"1. `go build ./...` succeeds\n2. `go test ./...` succeeds (no regressions)\n3. A record with JSON `{\"createdAt\":\"2025-01-01T00:00:00Z\"}` (missing title and shortDescription) for collection `org.hypercerts.claim.activity` gets coerced to have `title: \"\"` and `shortDescription: \"\"` when resolved via the collection query\n4. A record with JSON `{\"title\":\"Hello\",\"shortDescription\":\"World\",\"createdAt\":\"2025-01-01T00:00:00Z\"}` is NOT modified (all required fields present)\n5. Coercion happens in both createCollectionResolver and createSingleRecordResolver paths\n6. No NonNull GraphQL warnings for missing required string/integer/boolean fields\n7. The coercion does not apply to complex types (ref, union, blob) — those remain nil if missing","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":30,"created_at":"2026-02-19T20:10:20.768829+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T20:14:20.063401+08:00","closed_at":"2026-02-19T20:14:20.063401+08:00","close_reason":"fb5c723 Add coerceRequiredFields to schema builder and wire into resolvers","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-vz7.2","depends_on_id":"hyperindex-vz7","type":"parent-child","created_at":"2026-02-19T20:10:20.769797+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-vz7.2","depends_on_id":"hyperindex-vz7.1","type":"blocks","created_at":"2026-02-19T20:10:20.771107+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-vz7.3","title":"Add integration test for null coercion of required fields","description":"## Files\n- internal/graphql/schema/builder_test.go (modify or create)\n\n## What to do\nAdd a test (or tests) that verifies the null coercion behavior end-to-end through the schema builder.\n\n### Test: TestCoerceRequiredFields_MissingFields\n1. Create a `lexicon.Registry` and register the `org.hypercerts.claim.activity` lexicon (load from `testdata/lexicons/org/hypercerts/claim/activity.json`)\n2. Build a schema using `schema.NewBuilder(registry).Build()`\n3. Create a mock record in the DB with JSON that is MISSING the `title` and `shortDescription` fields: `{\"createdAt\":\"2025-01-01T00:00:00Z\"}`\n4. Execute a GraphQL query for that record\n5. Assert: the result contains `title: \"\"` and `shortDescription: \"\"` (coerced zero values) with NO errors/warnings\n\n### Test: TestCoerceRequiredFields_PresentFields\n1. Same setup but with a complete record: `{\"title\":\"My Title\",\"shortDescription\":\"My Desc\",\"createdAt\":\"2025-01-01T00:00:00Z\"}`\n2. Execute a GraphQL query\n3. Assert: the result contains `title: \"My Title\"` and `shortDescription: \"My Desc\"` (original values preserved)\n\n### Test: TestCoerceRequiredFields_NullFields\n1. Same setup but with explicit null values: `{\"title\":null,\"shortDescription\":null,\"createdAt\":\"2025-01-01T00:00:00Z\"}`\n2. Execute a GraphQL query\n3. Assert: the result contains `title: \"\"` and `shortDescription: \"\"` (coerced from null)\n\nLook at existing tests in `internal/graphql/schema/` and `internal/integration/` for patterns on how to set up the schema builder with a registry and execute queries. Follow the same patterns.\n\nIf there is no existing test infrastructure for executing GraphQL queries against the schema builder, create a minimal helper:\n- Build schema from registry\n- Use `graphql.Do()` to execute a query\n- Assert on the result\n\n## Don't\n- Do not modify production code\n- Do not use external test frameworks (use standard `testing` package)\n- Do not duplicate tests that already exist","acceptance_criteria":"1. `go test -v -run TestCoerceRequiredFields ./internal/graphql/schema/...` passes (or wherever tests are placed)\n2. TestCoerceRequiredFields_MissingFields proves that missing required string fields get coerced to \"\"\n3. TestCoerceRequiredFields_PresentFields proves that present fields are not modified\n4. TestCoerceRequiredFields_NullFields proves that explicit null required string fields get coerced to \"\"\n5. `go test ./...` passes (no regressions)","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":40,"created_at":"2026-02-19T20:10:37.526215+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-19T20:17:11.982287+08:00","closed_at":"2026-02-19T20:17:11.982287+08:00","close_reason":"ae64fae test: add integration tests for null coercion of required fields","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-vz7.3","depends_on_id":"hyperindex-vz7","type":"parent-child","created_at":"2026-02-19T20:10:37.527301+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-vz7.3","depends_on_id":"hyperindex-vz7.2","type":"blocks","created_at":"2026-02-19T20:10:37.528557+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-xuq","title":"Epic: Fix bugs found by reviewers of hyperindex-md3 bug fixes","description":"7 issues found by 4 specialized reviewers of the hyperindex-md3 bug-fix epic. Includes 2 P1 bugs (backoff logic broken, README auth wrong), 2 P2 concerns (shutdown log else branch, compose files insecure), and 3 P3 quality items (stale docs, test coverage, event validation gap). All existing tests must continue to pass.","status":"closed","priority":1,"issue_type":"epic","owner":"einstein.climateai.org","created_at":"2026-02-18T17:10:15.981231+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:19:15.515469+08:00","closed_at":"2026-02-18T17:19:15.515469+08:00","close_reason":"5d24874 all 6 reviewer follow-up fixes complete, all tests green","labels":["scope:small"]}
+{"id":"hyperindex-xuq.1","title":"Fix backoff reset to only fire after successful connection, not failed dials","description":"## Files\n- internal/tap/consumer.go (modify)\n- internal/tap/consumer_test.go (modify)\n\n## What to do\nThe B2 fix (commit 692e95b) added `backoff = minBackoff` unconditionally at line 113 after every `runOnce()` return. This is wrong — it also resets after FAILED dials (e.g., server unreachable), which caps effective backoff at 2s for persistent outages instead of the intended 2 minutes.\n\nCurrent code (lines 110-113):\n```go\nerr := c.runOnce(ctx)\n\n// Reset backoff after a successful connection that processed events.\nbackoff = minBackoff\n```\n\nFix: Make the reset conditional on `err == nil`:\n```go\nerr := c.runOnce(ctx)\n\n// Reset backoff only after a successful connection (not failed dials).\nif err == nil {\n    backoff = minBackoff\n}\n```\n\nThis means:\n- Connection succeeds, processes events, server closes cleanly → backoff resets ✓\n- Dial fails immediately → backoff escalates ✓\n- Connection succeeds but drops with read error → backoff resets (debatable, but better than never resetting) ✓\n\nUpdate the existing `TestConsumer_BackoffResetsAfterSuccess` to ensure it still passes (the second connection closes with CloseNormalClosure which makes runOnce return nil, so the test should still work).\n\nAdd a new test `TestConsumer_BackoffEscalatesOnPersistentFailure` that:\n1. Uses an unreachable URL (e.g., ws://127.0.0.1:1 — port 1 will refuse connections)\n2. Starts the consumer with a context timeout of ~4s\n3. Counts how many connection attempts happen in that window\n4. Verifies that fewer than 4 attempts occur (proving backoff is escalating, not resetting to 1s every time)\n\n## Dont\n- Do NOT change the backoff doubling logic\n- Do NOT change minBackoff or maxBackoff constants\n- Do NOT make backoff configurable","acceptance_criteria":"1. `backoff = minBackoff` is inside `if err == nil { ... }` (conditional on success)\n2. `TestConsumer_BackoffResetsAfterSuccess` still passes\n3. `TestConsumer_BackoffEscalatesOnPersistentFailure` exists and passes\n4. All existing consumer tests still pass\n5. `go test -race ./internal/tap/...` passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T17:10:35.042751+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:17:31.998125+08:00","closed_at":"2026-02-18T17:17:31.998125+08:00","close_reason":"a8ea6bb fix: reset backoff only on successful connection","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-xuq.1","depends_on_id":"hyperindex-xuq","type":"parent-child","created_at":"2026-02-18T17:10:35.043622+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-xuq.2","title":"Fix README curl example: use admin username for Basic auth","description":"## Files\n- README.md (modify)\n\n## What to do\nThe B9 fix (commit db029dc) changed the README curl from Bearer to Basic auth, but used `-u \":${TAP_ADMIN_PASSWORD}\"` (empty username). The actual Go code in `internal/tap/admin.go` line 157 uses `\"admin:\" + c.password`:\n\n```go\ncreds := base64.StdEncoding.EncodeToString([]byte(\"admin:\" + c.password))\nreq.Header.Set(\"Authorization\", \"Basic \"+creds)\n```\n\nSo the username is `\"admin\"`, not empty.\n\nFix line 72 of README.md:\n```bash\n# Before (wrong):\ncurl -X POST http://localhost:2480/repos/add \\\n  -u \":${TAP_ADMIN_PASSWORD}\" \\\n\n# After (correct):\ncurl -X POST http://localhost:2480/repos/add \\\n  -u \"admin:${TAP_ADMIN_PASSWORD}\" \\\n```\n\nAlso fix the env var table at line 91. Change:\n```\n| `TAP_ADMIN_PASSWORD` | Password for Tap's admin HTTP API | *(empty)* |\n```\nto:\n```\n| `TAP_ADMIN_PASSWORD` | Password for Tap's admin HTTP API | *(required for docker-compose.tap.yml)* |\n```\n\n## Dont\n- Do NOT change admin.go\n- Do NOT change any other README sections beyond lines 72 and 91","acceptance_criteria":"1. README curl example uses `-u \"admin:${TAP_ADMIN_PASSWORD}\"` (username is \"admin\")\n2. README env var table shows TAP_ADMIN_PASSWORD as required for docker-compose.tap.yml\n3. No other README sections changed\n4. The curl command matches what admin.go actually sends","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-18T17:10:46.158443+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:17:32.090462+08:00","closed_at":"2026-02-18T17:17:32.090462+08:00","close_reason":"c72322b fix: use admin username in README curl Basic auth example","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-xuq.2","depends_on_id":"hyperindex-xuq","type":"parent-child","created_at":"2026-02-18T17:10:46.159255+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-xuq.3","title":"Reject record/identity events with nil payload in ParseEvent","description":"## Files\n- internal/tap/event.go (modify)\n- internal/tap/event_test.go (modify)\n\n## What to do\nIn ParseEvent(), the validation guards are:\n```go\nif event.Type == EventTypeRecord \u0026\u0026 event.Record != nil { ... }\nif event.Type == EventTypeIdentity \u0026\u0026 event.Identity != nil { ... }\n```\n\nThis means `type=record` with `Record: nil` (e.g., JSON `{\"id\":1,\"type\":\"record\"}`) silently passes validation and returns a valid `*Event`. In the consumer, `IsRecord()` returns false (because Record is nil), so the event falls through to the \"Unknown event type\" default case — logged as a warning and silently dropped without incrementing the errors counter properly.\n\nFix: Change the guards to reject nil payloads:\n\n```go\n// Validate record events.\nif event.Type == EventTypeRecord {\n    if event.Record == nil {\n        return nil, fmt.Errorf(\"tap record event missing record payload\")\n    }\n    if event.Record.DID == \"\" {\n        return nil, fmt.Errorf(\"tap record event missing did field\")\n    }\n    // ... rest of field checks unchanged ...\n}\n\n// Validate identity events.\nif event.Type == EventTypeIdentity {\n    if event.Identity == nil {\n        return nil, fmt.Errorf(\"tap identity event missing identity payload\")\n    }\n    if event.Identity.DID == \"\" {\n        return nil, fmt.Errorf(\"tap identity event missing did field\")\n    }\n}\n```\n\nAlso add validation that create/update actions have a non-empty record body:\n```go\nif event.Record.Action == ActionCreate || event.Record.Action == ActionUpdate {\n    if len(event.Record.Record) == 0 {\n        return nil, fmt.Errorf(\"tap record event action %q missing record body\", event.Record.Action)\n    }\n}\n```\n\nAdd table-driven tests:\n- `type=record` with nil Record payload → error\n- `type=identity` with nil Identity payload → error\n- `type=record`, action=create, with empty Record body → error\n- `type=record`, action=update, with empty Record body → error\n- `type=record`, action=delete, with empty Record body → NO error (deletes have no body)\n\n## Dont\n- Do NOT validate unknown action values (out of scope — would need Tap protocol spec confirmation)\n- Do NOT change IsRecord() or IsIdentity() methods\n- Do NOT change struct definitions","acceptance_criteria":"1. ParseEvent rejects `type=record` with nil Record payload (returns error)\n2. ParseEvent rejects `type=identity` with nil Identity payload (returns error)\n3. ParseEvent rejects create/update with empty record body (returns error)\n4. ParseEvent allows delete with empty record body (no error)\n5. At least 5 new test cases covering nil-payload and empty-body scenarios\n6. All existing event tests still pass\n7. `go test ./internal/tap/...` passes","status":"closed","priority":1,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T17:11:04.450231+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:17:32.180675+08:00","closed_at":"2026-02-18T17:17:32.180675+08:00","close_reason":"6c73f1a fix: reject nil-payload and empty-body events in ParseEvent","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-xuq.3","depends_on_id":"hyperindex-xuq","type":"parent-child","created_at":"2026-02-18T17:11:04.45108+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-xuq.4","title":"Add ctx.Err() guard to else branch in Start() reconnect logging","description":"## Files\n- internal/tap/consumer.go (modify)\n- internal/tap/consumer_test.go (modify)\n\n## What to do\nThe B10 fix (commit b28087c) added a `ctx.Err()` check in the `err != nil` branch of Start() (line 126), but missed the `else` branch (line 133-136). When the server closes the connection cleanly (NormalClosure) simultaneously with context cancellation, `runOnce()` returns nil, the ctx/done select at lines 116-122 might not catch it (race between channels), and the else branch logs:\n\n```go\nslog.Warn(\"Tap connection closed unexpectedly, will reconnect\", \"backoff\", backoff)\n```\n\nThis is misleading during shutdown — the connection closed because we are shutting down, not \"unexpectedly\".\n\nFix: Add the same `ctx.Err()` check to the else branch:\n\n```go\nif err != nil {\n    if ctx.Err() != nil {\n        return ctx.Err()\n    }\n    slog.Warn(\"Tap connection lost, will reconnect\",\n        \"error\", err,\n        \"backoff\", backoff,\n    )\n} else {\n    if ctx.Err() != nil {\n        return ctx.Err()\n    }\n    slog.Warn(\"Tap connection closed unexpectedly, will reconnect\",\n        \"backoff\", backoff,\n    )\n}\n```\n\nOr refactor to check ctx.Err() once before the if/else:\n\n```go\n// If context was cancelled, this is a graceful shutdown — do not log.\nif ctx.Err() != nil {\n    return ctx.Err()\n}\n\nif err != nil {\n    slog.Warn(\"Tap connection lost, will reconnect\",\n        \"error\", err,\n        \"backoff\", backoff,\n    )\n} else {\n    slog.Warn(\"Tap connection closed unexpectedly, will reconnect\",\n        \"backoff\", backoff,\n    )\n}\n```\n\nThe second form is cleaner — prefer it.\n\nUpdate `TestConsumer_ShutdownNoSpuriousLog` to also check for Warn-level messages containing \"unexpectedly\" to verify neither branch logs spuriously during shutdown.\n\n## Dont\n- Do NOT change the reconnection logic\n- Do NOT remove the existing err != nil / else structure\n- Do NOT change Stop()","acceptance_criteria":"1. `ctx.Err()` is checked before BOTH the error and no-error log branches\n2. No Warn-level \"closed unexpectedly\" message during graceful shutdown\n3. `TestConsumer_ShutdownNoSpuriousLog` updated to verify no spurious Warn messages\n4. All existing consumer tests still pass\n5. `go test -race ./internal/tap/...` passes","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":20,"created_at":"2026-02-18T17:11:20.027274+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:19:15.425593+08:00","closed_at":"2026-02-18T17:19:15.425593+08:00","close_reason":"5d24874 fix: guard else branch with ctx.Err() check before reconnect log","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-xuq.4","depends_on_id":"hyperindex-xuq","type":"parent-child","created_at":"2026-02-18T17:11:20.028081+08:00","created_by":"einstein.climateai.org"},{"issue_id":"hyperindex-xuq.4","depends_on_id":"hyperindex-xuq.1","type":"blocks","created_at":"2026-02-18T17:11:48.533378+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-xuq.5","title":"Remove static SECRET_KEY_BASE default from docker-compose.yml and docker-compose.postgres.yml","description":"## Files\n- docker-compose.yml (modify)\n- docker-compose.postgres.yml (modify)\n\n## What to do\nThe B8 fix only hardened `docker-compose.tap.yml`. The same insecure static default `development-secret-key-change-in-production-64chars` exists in the other two compose files:\n\n`docker-compose.yml` line 12:\n```yaml\n- SECRET_KEY_BASE=${SECRET_KEY_BASE:-development-secret-key-change-in-production-64chars}\n```\n\n`docker-compose.postgres.yml` line 12:\n```yaml\n- SECRET_KEY_BASE=${SECRET_KEY_BASE:-development-secret-key-change-in-production-64chars}\n```\n\nFix both to use the `:?` syntax like docker-compose.tap.yml:\n```yaml\n- SECRET_KEY_BASE=${SECRET_KEY_BASE:?SECRET_KEY_BASE must be set - generate with: openssl rand -hex 32}\n```\n\n## Dont\n- Do NOT change any other environment variables in these files\n- Do NOT change docker-compose.tap.yml (already fixed in B8)\n- Do NOT change the Dockerfile","acceptance_criteria":"1. docker-compose.yml uses `${SECRET_KEY_BASE:?...}` (no static default)\n2. docker-compose.postgres.yml uses `${SECRET_KEY_BASE:?...}` (no static default)\n3. Both files are valid YAML\n4. docker-compose.tap.yml is unchanged","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":10,"created_at":"2026-02-18T17:11:29.666594+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:17:32.270604+08:00","closed_at":"2026-02-18T17:17:32.270604+08:00","close_reason":"75b4d24 fix: require SECRET_KEY_BASE via :? syntax in compose files","labels":["scope:trivial"],"dependencies":[{"issue_id":"hyperindex-xuq.5","depends_on_id":"hyperindex-xuq","type":"parent-child","created_at":"2026-02-18T17:11:29.667509+08:00","created_by":"einstein.climateai.org"}]}
+{"id":"hyperindex-xuq.6","title":"Improve handler_test.go: fix misleading test name and add delete-path activity status test","description":"## Files\n- internal/tap/handler_test.go (modify)\n\n## What to do\nTwo test quality issues found by reviewers:\n\n### 1. Rename misleading test\n`TestIndexHandler_HandleRecord_DeleteError` (line 332) tests the HAPPY path (delete of non-existent record, which is NOT an error). The name implies it tests error handling. \n\nRename to `TestIndexHandler_HandleRecord_DeleteNonExistent` and update the doc comment to:\n```go\n// TestIndexHandler_HandleRecord_DeleteNonExistent verifies that deleting a record\n// that does not exist is not an error (SQL DELETE of 0 rows is fine) and that\n// pubsub events are still published.\n```\n\n### 2. Add delete-path activity status test\nB7 added `UpdateStatus(\"completed\")` calls for both create and delete paths, but the test only verifies the create path. Add a test `TestIndexHandler_HandleRecord_DeleteActivityCompleted` that:\n1. Creates a record (so there is something to delete)\n2. Deletes the record\n3. Queries `GetRecentActivity(ctx, 1)` \n4. Finds the activity entry with operation=\"delete\" and verifies its Status is \"completed\"\n\nNote: There will be multiple activity entries (create + delete). Filter for the delete one. `GetRecentActivity` returns entries ordered by timestamp DESC, so the delete entry should be first.\n\n## Dont\n- Do NOT change handler.go\n- Do NOT change any existing test logic (only rename + add new test)\n- Do NOT change consumer_test.go or event_test.go","acceptance_criteria":"1. `TestIndexHandler_HandleRecord_DeleteError` is renamed to `TestIndexHandler_HandleRecord_DeleteNonExistent`\n2. `TestIndexHandler_HandleRecord_DeleteActivityCompleted` exists and passes\n3. The new test verifies delete activity status is \"completed\" (not \"pending\")\n4. All existing handler tests still pass\n5. `go test ./internal/tap/...` passes","status":"closed","priority":2,"issue_type":"task","assignee":"einstein.climateai.org","owner":"einstein.climateai.org","estimated_minutes":25,"created_at":"2026-02-18T17:11:43.521265+08:00","created_by":"einstein.climateai.org","updated_at":"2026-02-18T17:17:32.359884+08:00","closed_at":"2026-02-18T17:17:32.359884+08:00","close_reason":"8f394aa test: rename DeleteError test and add delete activity status test","labels":["scope:small"],"dependencies":[{"issue_id":"hyperindex-xuq.6","depends_on_id":"hyperindex-xuq","type":"parent-child","created_at":"2026-02-18T17:11:43.522043+08:00","created_by":"einstein.climateai.org"}]}
diff --git a/.beads/last-touched b/.beads/last-touched
new file mode 100644
index 0000000..90feae8
--- /dev/null
+++ b/.beads/last-touched
@@ -0,0 +1 @@
+hyperindex-3gm
diff --git a/.beads/metadata.json b/.beads/metadata.json
new file mode 100644
index 0000000..c787975
--- /dev/null
+++ b/.beads/metadata.json
@@ -0,0 +1,4 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}
\ No newline at end of file
diff --git a/.env.example b/.env.example
index 865de2a..48ea453 100644
--- a/.env.example
+++ b/.env.example
@@ -72,7 +72,27 @@ ADMIN_DIDS=did:plc:qc42fmqqlsmdq7jiypiiigww
 # LEXICON_DIR=
 
 # =============================================================================
-# Jetstream Configuration
+# Tap Configuration (Recommended — replaces Jetstream+Backfill)
+# =============================================================================
+
+# Enable Tap consumer. When true, Jetstream and Backfill are disabled.
+# TAP_ENABLED=false
+
+# WebSocket URL of the Tap sidecar (default: ws://localhost:2480)
+# TAP_URL=ws://localhost:2480
+
+# Password for Tap's admin HTTP API (used for /repos/add backfill calls)
+# TAP_ADMIN_PASSWORD=
+
+# Disable ack-based delivery (useful for debugging; not recommended in production)
+# TAP_DISABLE_ACKS=false
+
+# Collection NSID for Tap auto-discovery of repos (e.g. app.bsky.feed.post)
+# When set, Tap will automatically discover and index all repos publishing this collection.
+# TAP_SIGNAL_COLLECTION=
+
+# =============================================================================
+# Jetstream Configuration (Legacy Mode)
 # =============================================================================
 
 # Jetstream WebSocket URL (default: wss://jetstream2.us-west.bsky.network/subscribe)
diff --git a/README.md b/README.md
index 3440244..4a485bf 100644
--- a/README.md
+++ b/README.md
@@ -43,6 +43,59 @@ Or place lexicon JSON files in a directory and set `LEXICON_DIR` environment var
 
 ### 2. Start Indexing
 
+#### Using Tap (Recommended)
+
+[Tap](https://github.com/bluesky-social/indigo/tree/main/cmd/tap) is Bluesky's official sidecar utility for consuming AT Protocol events. It is the recommended way to run Hyperindex because it provides:
+
+- **Cryptographic verification** — verifies repo structure, MST integrity, and identity signatures
+- **Ordering guarantees** — strict per-repo event ordering, no backfill/live race conditions
+- **At-least-once delivery** — ack-based protocol ensures no events are lost on crash
+- **Identity tracking** — handle changes and account status updates are handled automatically
+- **Simplified architecture** — Tap manages backfill automatically; no separate backfill worker needed
+
+**Run with Tap sidecar:**
+
+```bash
+# Copy and configure environment
+cp .env.example .env
+# Set TAP_ADMIN_PASSWORD and other vars in .env
+
+# Start Tap + Hyperindex together
+docker compose -f docker-compose.tap.yml up --build
+```
+
+**Add repos to track via Tap admin API:**
+
+```bash
+# Add a specific repo (DID) for Tap to index
+curl -X POST http://localhost:2480/repos/add \
+  -u "admin:${TAP_ADMIN_PASSWORD}" \
+  -H "Content-Type: application/json" \
+  -d '{"dids": ["did:plc:your-did-here"]}'
+```
+
+**Auto-discovery with `TAP_SIGNAL_COLLECTION`:**
+
+Set `TAP_SIGNAL_COLLECTION` to a collection NSID (e.g. `app.bsky.feed.post`) and Tap will automatically discover and index all repos that publish records in that collection. This replaces the need for a manual full-network backfill.
+
+```bash
+TAP_SIGNAL_COLLECTION=app.bsky.feed.post docker compose -f docker-compose.tap.yml up
+```
+
+**Tap environment variables:**
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TAP_ENABLED` | Enable Tap consumer (disables Jetstream+Backfill) | `false` |
+| `TAP_URL` | WebSocket URL of the Tap sidecar | `ws://localhost:2480` |
+| `TAP_ADMIN_PASSWORD` | Password for Tap's admin HTTP API | *(required for docker-compose.tap.yml)* |
+| `TAP_DISABLE_ACKS` | Disable ack-based delivery (useful for debugging) | `false` |
+| `TAP_SIGNAL_COLLECTION` | Collection NSID for auto-discovery of repos | *(empty)* |
+
+#### Legacy Mode: Jetstream + Backfill
+
+> **Note:** Jetstream+Backfill mode is the legacy ingestion path. It lacks cryptographic verification and ordering guarantees. Use Tap (above) for new deployments.
+
 Once lexicons are registered, Hyperindex automatically:
 - **Connects to Jetstream** for real-time events
 - **Indexes matching records** to your database
@@ -65,33 +118,95 @@ mutation {
 Access your indexed data at `/graphql`:
 
 ```graphql
-# Query records by collection
+# Generic query — all records by collection
 query {
-  records(collection: "app.bsky.feed.post") {
+  records(collection: "app.bsky.feed.post", first: 20) {
     edges {
-      node {
-        uri
-        did
-        value  # JSON record data
-      }
+      node { uri did collection value }
+      cursor
     }
+    pageInfo { hasNextPage endCursor }
+    totalCount
   }
 }
 
-# With typed queries (when lexicon schemas are loaded)
+# Typed queries — with filtering, sorting, and field-level access
 query {
-  appBskyFeedPost(first: 10, where: { did: { eq: "did:plc:..." } }) {
+  appBskyFeedPost(
+    where: { text: { contains: "hello" }, did: { eq: "did:plc:..." } }
+    sortBy: "createdAt"
+    sortDirection: DESC
+    first: 10
+  ) {
     edges {
       node {
         uri
+        did
+        rkey
         text
         createdAt
       }
     }
+    totalCount
+    pageInfo { hasNextPage hasPreviousPage endCursor }
+  }
+}
+
+# Backward pagination
+query {
+  appBskyFeedPost(last: 10, before: "cursor_value") {
+    edges { node { uri text } }
+    pageInfo { hasPreviousPage startCursor }
+  }
+}
+
+# Cross-collection text search
+query {
+  search(query: "climate", collection: "app.bsky.feed.post", first: 20) {
+    edges {
+      node { uri did collection value }
+    }
+  }
+}
+```
+
+#### Filtering (`where`)
+
+Typed collection queries accept a `where` argument with per-field filters:
+
+| Operator | Types | Example |
+|----------|-------|---------|
+| `eq` | All | `{ title: { eq: "Hello" } }` |
+| `neq` | All | `{ status: { neq: "draft" } }` |
+| `gt`, `lt`, `gte`, `lte` | Int, Float, DateTime | `{ score: { gt: 5, lte: 100 } }` |
+| `in` | String, Int, Float | `{ type: { in: ["post", "reply"] } }` |
+| `contains` | String | `{ text: { contains: "forest" } }` |
+| `startsWith` | String | `{ name: { startsWith: "Gain" } }` |
+| `isNull` | All | `{ optionalField: { isNull: true } }` |
+
+Every `where` input also includes a `did` field for filtering by author DID.
+
+#### Sorting (`sortBy`, `sortDirection`)
+
+Typed queries support sorting by any scalar field:
+
+```graphql
+query {
+  appBskyFeedPost(sortBy: "createdAt", sortDirection: ASC, first: 10) {
+    edges { node { uri createdAt } }
   }
 }
 ```
 
+Default sort is `indexed_at DESC` (newest first). Available sort fields are generated per-collection from the lexicon schema.
+
+#### Pagination
+
+- **Forward**: `first` + `after` (default: 20, max: 100)
+- **Backward**: `last` + `before`
+- **`totalCount`**: Returned when requested (opt-in, computed only when selected)
+- Cannot use `first`/`after` and `last`/`before` simultaneously
+
 ## Endpoints
 
 | Endpoint | Description |
diff --git a/client/.env.example b/client/.env.example
index a7468af..93e724d 100644
--- a/client/.env.example
+++ b/client/.env.example
@@ -1,5 +1,5 @@
 # =============================================================================
-# Hypergoat Client Configuration
+# Hyperindex Client Configuration
 # =============================================================================
 
 # Backend API URL (the Go server)
@@ -8,7 +8,7 @@
 NEXT_PUBLIC_API_URL=http://localhost:8080
 
 # Same as above, used for server-side API calls
-HYPERGOAT_URL=http://127.0.0.1:8080
+HYPERINDEX_URL=http://127.0.0.1:8080
 
 # =============================================================================
 # OAuth Configuration
diff --git a/client/Dockerfile b/client/Dockerfile
new file mode 100644
index 0000000..acf5e75
--- /dev/null
+++ b/client/Dockerfile
@@ -0,0 +1,47 @@
+# Build stage
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+# Accept build-time env vars for Next.js (NEXT_PUBLIC_* are inlined at build time)
+ARG NEXT_PUBLIC_API_URL
+ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
+
+# Copy package files
+COPY package.json package-lock.json* ./
+
+# Install dependencies
+RUN npm ci
+
+# Copy source
+COPY . .
+
+# Build Next.js
+ENV NEXT_TELEMETRY_DISABLED=1
+RUN npm run build
+
+# Runtime stage
+FROM node:22-alpine AS runner
+
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV NEXT_TELEMETRY_DISABLED=1
+
+# Create non-root user
+RUN addgroup --system --gid 1001 nodejs && \
+    adduser --system --uid 1001 nextjs
+
+# Copy built files
+COPY --from=builder /app/public ./public
+COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
+COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static
+
+USER nextjs
+
+EXPOSE 3000
+
+ENV PORT=3000
+ENV HOSTNAME="0.0.0.0"
+
+CMD ["node", "server.js"]
diff --git a/client/next.config.ts b/client/next.config.ts
index 17a0c6e..7458866 100644
--- a/client/next.config.ts
+++ b/client/next.config.ts
@@ -1,6 +1,8 @@
 import type { NextConfig } from "next";
 
 const nextConfig: NextConfig = {
+  // Enable standalone output for Docker deployment
+  output: "standalone",
   // Allow external images from Bluesky CDN
   images: {
     remotePatterns: [
@@ -11,7 +13,7 @@ const nextConfig: NextConfig = {
       },
     ],
   },
-  // Proxy API requests to Hypergoat backend during development
+  // Proxy API requests to Hyperindex backend during development
   async rewrites() {
     const apiUrl = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8080";
     return [
@@ -23,10 +25,6 @@ const nextConfig: NextConfig = {
         source: "/graphql",
         destination: `${apiUrl}/graphql`,
       },
-      {
-        source: "/graphiql",
-        destination: `${apiUrl}/graphiql`,
-      },
       {
         source: "/oauth/:path*",
         destination: `${apiUrl}/oauth/:path*`,
diff --git a/client/package.json b/client/package.json
index ce11b6c..8218662 100644
--- a/client/package.json
+++ b/client/package.json
@@ -23,6 +23,7 @@
     "react": "19.2.3",
     "react-dom": "19.2.3",
     "recharts": "^3.7.0",
+    "next-themes": "^0.4.6",
     "tailwind-merge": "^3.4.0"
   },
   "devDependencies": {
diff --git a/client/src/app/api/admin/graphql/route.ts b/client/src/app/api/admin/graphql/route.ts
index 9c04eaf..a8009e5 100644
--- a/client/src/app/api/admin/graphql/route.ts
+++ b/client/src/app/api/admin/graphql/route.ts
@@ -6,14 +6,14 @@ export const dynamic = "force-dynamic";
 
 /**
  * Proxy for admin GraphQL requests.
- * Checks session authentication and passes user DID to Hypergoat.
+ * Checks session authentication and passes user DID to Hyperindex.
  */
 export async function POST(request: NextRequest) {
   try {
     const session = await getSession();
     const body = await request.json();
 
-    // Build headers for Hypergoat
+    // Build headers for Hyperindex
     const headers: HeadersInit = {
       "Content-Type": "application/json",
     };
@@ -26,8 +26,8 @@ export async function POST(request: NextRequest) {
       console.log("[admin-graphql] Unauthenticated request - no session DID");
     }
 
-    // Proxy to Hypergoat
-    const response = await fetch(`${env.HYPERGOAT_URL}/admin/graphql`, {
+    // Proxy to Hyperindex
+    const response = await fetch(`${env.HYPERINDEX_URL}/admin/graphql`, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
@@ -35,7 +35,7 @@ export async function POST(request: NextRequest) {
 
     const data = await response.json();
 
-    // Log errors from Hypergoat
+    // Log errors from Hyperindex
     if (data.errors) {
       console.log("[admin-graphql] GraphQL errors:", JSON.stringify(data.errors));
     }
diff --git a/client/src/app/api/graphql/route.ts b/client/src/app/api/graphql/route.ts
index 0649010..05c91b0 100644
--- a/client/src/app/api/graphql/route.ts
+++ b/client/src/app/api/graphql/route.ts
@@ -4,13 +4,13 @@ import { env } from "@/lib/env";
 export const dynamic = "force-dynamic";
 
 /**
- * Proxy for public GraphQL requests to Hypergoat.
+ * Proxy for public GraphQL requests to Hyperindex.
  */
 export async function POST(request: NextRequest) {
   try {
     const body = await request.json();
 
-    const response = await fetch(`${env.HYPERGOAT_URL}/graphql`, {
+    const response = await fetch(`${env.HYPERINDEX_URL}/graphql`, {
       method: "POST",
       headers: {
         "Content-Type": "application/json",
diff --git a/client/src/app/backfill/page.tsx b/client/src/app/backfill/page.tsx
index 03aa2eb..98ac57e 100644
--- a/client/src/app/backfill/page.tsx
+++ b/client/src/app/backfill/page.tsx
@@ -73,10 +73,10 @@ export default function BackfillPage() {
     <div className="pt-8 sm:pt-12 space-y-10">
       {/* Hero Section */}
       <div className="max-w-md">
-        <h2 className="font-[family-name:var(--font-garamond)] text-3xl sm:text-4xl text-zinc-900 leading-tight">
+        <h2 className="font-[family-name:var(--font-syne)] text-3xl sm:text-4xl leading-tight" style={{ color: "var(--foreground)" }}>
           Backfill
         </h2>
-        <p className="text-zinc-500 mt-3 leading-relaxed">
+        <p className="mt-3 leading-relaxed" style={{ color: "var(--muted-foreground)" }}>
           Sync historical data from the AT Protocol relay
         </p>
       </div>
@@ -95,13 +95,13 @@ export default function BackfillPage() {
 
       {/* Status */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Status
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6">
+        <div className="rounded-xl border p-6" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
           {statusLoading ? (
-            <div className="flex items-center gap-2 text-zinc-400">
-              <div className="w-4 h-4 rounded-full border-2 border-zinc-200 border-t-zinc-400 animate-spin" />
+            <div className="flex items-center gap-2" style={{ color: "var(--muted-foreground)" }}>
+              <div className="w-4 h-4 rounded-full border-2 animate-spin" style={{ borderColor: "var(--border)", borderTopColor: "var(--muted-foreground)" }} />
               Checking status...
             </div>
           ) : isBackfilling ? (
@@ -115,13 +115,13 @@ export default function BackfillPage() {
               </div>
             </div>
           ) : (
-            <div className="flex items-center gap-3 p-4 bg-emerald-50/50 border border-emerald-200/60 rounded-lg">
-              <svg className="h-5 w-5 text-emerald-500" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+            <div className="flex items-center gap-3 p-4 rounded-lg border" style={{ backgroundColor: "var(--accent)", borderColor: "var(--border)" }}>
+              <svg className="h-5 w-5" style={{ color: "oklch(0.65 0.15 155)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                 <path strokeLinecap="round" strokeLinejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
               </svg>
               <div>
-                <div className="font-medium text-emerald-700">Idle</div>
-                <div className="text-sm text-emerald-600/70">
+                <div className="font-medium" style={{ color: "oklch(0.65 0.15 155)" }}>Idle</div>
+                <div className="text-sm" style={{ color: "var(--muted-foreground)" }}>
                   No backfill currently running
                 </div>
               </div>
@@ -132,11 +132,11 @@ export default function BackfillPage() {
 
       {/* Full Backfill */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Full Backfill
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6 space-y-4">
-          <p className="text-sm text-zinc-500">
+        <div className="rounded-xl border p-6 space-y-4" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
+          <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
             Trigger a complete backfill of all known actors from the relay.
             This will fetch all historical records for actors that have been seen.
           </p>
@@ -164,7 +164,7 @@ export default function BackfillPage() {
               )}
             </Button>
             {isBackfilling && (
-              <span className="text-sm text-zinc-400">
+              <span className="text-sm" style={{ color: "var(--muted-foreground)" }}>
                 A backfill is already in progress
               </span>
             )}
@@ -187,11 +187,11 @@ export default function BackfillPage() {
 
       {/* Actor Backfill */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Backfill Single Actor
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6 space-y-4">
-          <p className="text-sm text-zinc-500">
+        <div className="rounded-xl border p-6 space-y-4" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
+          <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
             Fetch all historical records for a specific actor by their DID.
             Useful for quickly syncing a single user.
           </p>
diff --git a/client/src/app/docs/agents/route.ts b/client/src/app/docs/agents/route.ts
index 58c8bf5..f66dba0 100644
--- a/client/src/app/docs/agents/route.ts
+++ b/client/src/app/docs/agents/route.ts
@@ -1,18 +1,17 @@
-const API_ENDPOINT = "https://hypergoat-app-production.up.railway.app";
-const WS_ENDPOINT = "wss://hypergoat-app-production.up.railway.app";
+const API_ENDPOINT = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8080";
+const WS_ENDPOINT = (process.env.NEXT_PUBLIC_API_URL || "http://localhost:8080").replace("https://", "wss://").replace("http://", "ws://");
 
-const agentsMd = `# Hyperindex (hi) API - Complete Integration Guide for AI Agents
+const agentsMd = `# Hyperindex API - Complete Integration Guide for AI Agents
 
 ## What is Hyperindex?
 
-**Hyperindex** (short: **hi**, formerly known as Hypergoat) is GainForest's AT Protocol AppView server for the Hypersphere ecosystem. The name "hi" stands for **H**yper**i**ndex -- it indexes Lexicon-defined records from the AT Protocol network and exposes them via a dynamically-generated GraphQL API.
+**Hyperindex** is GainForest's AT Protocol AppView server for the Hypersphere ecosystem. It indexes Lexicon-defined records from the AT Protocol network and exposes them via a dynamically-generated GraphQL API.
 
 ### Key Information
 
 - **Organization**: GainForest (https://gainforest.earth)
 - **Purpose**: Indexes Lexicon-defined records from the AT Protocol network and exposes them via a dynamically-generated GraphQL API
 - **Ecosystem**: Part of the Hypersphere ecosystem for environmental impact tracking
-- **History**: Formerly known as Hypergoat (Hypersphere Go ATProto AppView)
 
 ### Related Resources
 
@@ -311,7 +310,7 @@ query GetTypeFields($typeName: String!) {
 
 ## Common Query Patterns
 
-### Fetch Records by Collection
+### Fetch Records by Collection (Generic)
 
 \`\`\`graphql
 query GetRecords($collection: String!, $first: Int, $after: String) {
@@ -338,6 +337,42 @@ query GetRecords($collection: String!, $first: Int, $after: String) {
 }
 \`\`\`
 
+### Typed Collection Query with Filters
+
+When lexicons are loaded, typed query fields are generated. Each supports \`where\`, \`sortBy\`, and \`sortDirection\` arguments.
+
+\`\`\`graphql
+query GetFilteredPosts($first: Int, $after: String) {
+  appBskyFeedPost(
+    where: {
+      text: { contains: "climate" }
+      did: { eq: "did:plc:abc123" }
+    }
+    sortBy: "createdAt"
+    sortDirection: DESC
+    first: $first
+    after: $after
+  ) {
+    edges {
+      node {
+        uri
+        did
+        rkey
+        text
+        createdAt
+      }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+      hasPreviousPage
+      endCursor
+    }
+    totalCount
+  }
+}
+\`\`\`
+
 ### Fetch Single Record by URI
 
 \`\`\`graphql
@@ -353,55 +388,133 @@ query GetRecord($uri: String!) {
 }
 \`\`\`
 
-### Fetch Records by DID (Author)
+### Cross-Collection Text Search
 
 \`\`\`graphql
-query GetRecordsByAuthor($did: String!, $first: Int) {
-  records(did: $did, first: $first) {
+query SearchRecords($query: String!, $collection: String, $first: Int) {
+  search(query: $query, collection: $collection, first: $first) {
     edges {
       node {
         uri
+        did
         collection
-        record
-        createdAt
+        value
       }
+      cursor
+    }
+    pageInfo {
+      hasNextPage
+      endCursor
     }
+    totalCount
   }
 }
 \`\`\`
 
-### Fetch Records with Filters
+---
+
+## Filtering (\`where\` argument)
+
+Typed collection queries accept a \`where\` argument for field-level filtering. The available filter fields are generated from each lexicon's schema.
+
+### Filter Operators
+
+| Operator | Applicable Types | Description | Example |
+|----------|-----------------|-------------|---------|
+| \`eq\` | String, Int, Float, Boolean, DateTime | Exact equality | \`{ title: { eq: "Hello" } }\` |
+| \`neq\` | String, Int, Float, Boolean, DateTime | Not equal | \`{ status: { neq: "draft" } }\` |
+| \`gt\` | Int, Float, DateTime | Greater than | \`{ score: { gt: 5 } }\` |
+| \`lt\` | Int, Float, DateTime | Less than | \`{ score: { lt: 100 } }\` |
+| \`gte\` | Int, Float, DateTime | Greater or equal | \`{ createdAt: { gte: "2024-01-01" } }\` |
+| \`lte\` | Int, Float, DateTime | Less or equal | \`{ createdAt: { lte: "2024-12-31" } }\` |
+| \`in\` | String, Int, Float | Value in list | \`{ type: { in: ["post", "reply"] } }\` |
+| \`contains\` | String | Substring match | \`{ text: { contains: "forest" } }\` |
+| \`startsWith\` | String | Prefix match | \`{ name: { startsWith: "Gain" } }\` |
+| \`isNull\` | All | Null check | \`{ optionalField: { isNull: true } }\` |
+
+### DID (Author) Filtering
+
+Every \`where\` input includes a \`did\` field for filtering by record author:
 
 \`\`\`graphql
-query GetFilteredRecords(
-  $collection: String
-  $did: String
-  $first: Int
-  $after: String
-) {
-  records(
-    collection: $collection
-    did: $did
-    first: $first
-    after: $after
+query {
+  appBskyFeedPost(where: { did: { eq: "did:plc:abc123" } }) {
+    edges { node { uri text } }
+  }
+}
+\`\`\`
+
+### Combining Filters
+
+Multiple filter fields are ANDed together. Multiple operators on the same field are also ANDed:
+
+\`\`\`graphql
+query {
+  appBskyFeedPost(
+    where: {
+      did: { eq: "did:plc:abc123" }
+      text: { contains: "carbon" }
+      createdAt: { gte: "2024-01-01", lte: "2024-12-31" }
+    }
+    first: 20
   ) {
+    edges { node { uri text createdAt } }
+    totalCount
+  }
+}
+\`\`\`
+
+## Sorting
+
+Typed collection queries support sorting by any scalar field with \`sortBy\` and \`sortDirection\` arguments.
+
+### Arguments
+
+| Argument | Type | Default | Description |
+|----------|------|---------|-------------|
+| \`sortBy\` | Enum (per-collection) | \`indexed_at\` | Field to sort by |
+| \`sortDirection\` | \`ASC\` \| \`DESC\` | \`DESC\` | Sort direction |
+
+### Example
+
+\`\`\`graphql
+query {
+  appBskyFeedPost(sortBy: "createdAt", sortDirection: ASC, first: 10) {
     edges {
-      node {
-        uri
-        did
-        collection
-        record
-      }
+      node { uri text createdAt }
       cursor
     }
-    pageInfo {
-      hasNextPage
-      endCursor
+    pageInfo { hasNextPage endCursor }
+  }
+}
+\`\`\`
+
+Sortable fields are generated per-collection from the lexicon. Only scalar types (string, integer, number, boolean, datetime) are sortable. The meta-field \`indexed_at\` is always available.
+
+## Text Search
+
+Use the \`search\` query for cross-collection or per-collection text search:
+
+\`\`\`graphql
+query {
+  search(query: "carbon credits", collection: "app.bsky.feed.post", first: 20) {
+    edges {
+      node { uri did collection value }
     }
+    totalCount
   }
 }
 \`\`\`
 
+| Argument | Type | Required | Description |
+|----------|------|----------|-------------|
+| \`query\` | String! | Yes | Search text (minimum 2 characters) |
+| \`collection\` | String | No | Restrict search to a collection NSID |
+| \`first\` | Int | No | Page size (default 20, max 100) |
+| \`after\` | String | No | Cursor for pagination |
+
+Search is case-insensitive and matches against the full JSON content of records.
+
 ---
 
 ## Pagination (Relay Specification)
@@ -417,6 +530,29 @@ Hyperindex uses Relay-style cursor-based pagination.
 | \`last\` | Int | Number of items from the end |
 | \`before\` | String | Cursor to start before |
 
+**Note:** The maximum page size is 100. Requests with \`first\` or \`last\` greater than 100 are silently clamped. You cannot use \`first\`/\`after\` and \`last\`/\`before\` simultaneously — doing so returns a GraphQL error.
+
+### totalCount
+
+Connections include an optional \`totalCount\` field. It is **opt-in**: the count query only executes when \`totalCount\` is included in your selection set.
+
+\`\`\`graphql
+# totalCount IS computed (you selected it)
+query {
+  records(collection: "app.bsky.feed.post", first: 10) {
+    edges { node { uri } }
+    totalCount
+  }
+}
+
+# totalCount is NOT computed (not selected — no performance cost)
+query {
+  records(collection: "app.bsky.feed.post", first: 10) {
+    edges { node { uri } }
+  }
+}
+\`\`\`
+
 ### PageInfo Fields
 
 | Field | Type | Description |
diff --git a/client/src/app/docs/page.tsx b/client/src/app/docs/page.tsx
index 3f12816..41e6dc8 100644
--- a/client/src/app/docs/page.tsx
+++ b/client/src/app/docs/page.tsx
@@ -3,7 +3,7 @@
 import { useState } from "react";
 import Link from "next/link";
 
-const API_ENDPOINT = "https://hypergoat-app-production.up.railway.app";
+const API_ENDPOINT = process.env.NEXT_PUBLIC_API_URL || "http://localhost:8080";
 
 type Tab = "http" | "websocket";
 type Language = "javascript" | "python" | "curl";
@@ -312,16 +312,15 @@ function LanguageTabs({
   ];
 
   return (
-    <div className="flex gap-1 mb-4 p-1 bg-zinc-100 rounded-lg w-fit">
+    <div className="flex gap-1 mb-4 p-1 rounded-lg w-fit" style={{ backgroundColor: "var(--muted)" }}>
       {languages.map(({ value, label, icon }) => (
         <button
           key={value}
           onClick={() => onChange(value)}
-          className={`flex items-center gap-2 px-3 py-2 text-sm font-medium rounded-md transition-all ${
-            selected === value
-              ? "bg-white text-zinc-900 shadow-sm"
-              : "text-zinc-500 hover:text-zinc-700"
-          }`}
+          className="flex items-center gap-2 px-3 py-2 text-sm font-medium rounded-md transition-all"
+          style={selected === value
+            ? { backgroundColor: "var(--card)", color: "var(--foreground)" }
+            : { color: "var(--muted-foreground)" }}
         >
           {icon}
           {label}
@@ -624,12 +623,12 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
     <div className="pt-8 sm:pt-12 space-y-10">
       {/* Hero Section */}
       <div className="max-w-xl">
-        <h2 className="font-[family-name:var(--font-garamond)] text-3xl sm:text-4xl text-zinc-900 leading-tight">
+        <h2 className="font-[family-name:var(--font-syne)] text-3xl sm:text-4xl leading-tight" style={{ color: "var(--foreground)" }}>
           API Documentation
         </h2>
-        <p className="text-zinc-500 mt-3 leading-relaxed">
-          <strong className="text-zinc-700">Hyperindex</strong> (<em>hi</em>, formerly Hypergoat) is{" "}
-          <a href="https://gainforest.earth" target="_blank" rel="noopener noreferrer" className="text-emerald-600 hover:underline">GainForest&apos;s</a>{" "}
+        <p className="mt-3 leading-relaxed" style={{ color: "var(--muted-foreground)" }}>
+          <strong style={{ color: "var(--foreground)" }}>Hyperindex</strong> is{" "}
+          <a href="https://gainforest.earth" target="_blank" rel="noopener noreferrer" style={{ color: "var(--primary)" }} className="hover:underline">GainForest&apos;s</a>{" "}
           main AppView for the AT Protocol Hypersphere ecosystem. It indexes Lexicon-defined records and exposes them via a dynamically-generated GraphQL API.
         </p>
         <div className="flex flex-wrap gap-x-4 gap-y-2 mt-4 text-sm">
@@ -637,7 +636,8 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
             href="https://impactindexer.org/"
             target="_blank"
             rel="noopener noreferrer"
-            className="inline-flex items-center gap-1.5 text-zinc-500 hover:text-emerald-600 transition-colors"
+            className="inline-flex items-center gap-1.5 transition-colors"
+            style={{ color: "var(--muted-foreground)" }}
           >
             <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
               <path strokeLinecap="round" strokeLinejoin="round" d="M12 21a9.004 9.004 0 008.716-6.747M12 21a9.004 9.004 0 01-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 017.843 4.582M12 3a8.997 8.997 0 00-7.843 4.582m15.686 0A11.953 11.953 0 0112 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0121 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0112 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 013 12c0-1.605.42-3.113 1.157-4.418" />
@@ -648,7 +648,8 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
             href="https://impactindexer.org/lexicon/"
             target="_blank"
             rel="noopener noreferrer"
-            className="inline-flex items-center gap-1.5 text-zinc-500 hover:text-emerald-600 transition-colors"
+            className="inline-flex items-center gap-1.5 transition-colors"
+            style={{ color: "var(--muted-foreground)" }}
           >
             <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
               <path strokeLinecap="round" strokeLinejoin="round" d="M12 6.042A8.967 8.967 0 006 3.75c-1.052 0-2.062.18-3 .512v14.25A8.987 8.987 0 016 18c2.305 0 4.408.867 6 2.292m0-14.25a8.966 8.966 0 016-2.292c1.052 0 2.062.18 3 .512v14.25A8.987 8.987 0 0018 18a8.967 8.967 0 00-6 2.292m0-14.25v14.25" />
@@ -657,7 +658,8 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
           </a>
           <Link
             href="/docs/agents"
-            className="inline-flex items-center gap-1.5 text-zinc-500 hover:text-emerald-600 transition-colors"
+            className="inline-flex items-center gap-1.5 transition-colors"
+            style={{ color: "var(--muted-foreground)" }}
           >
             <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
               <path strokeLinecap="round" strokeLinejoin="round" d="M9.75 3.104v5.714a2.25 2.25 0 01-.659 1.591L5 14.5M9.75 3.104c-.251.023-.501.05-.75.082m.75-.082a24.301 24.301 0 014.5 0m0 0v5.714c0 .597.237 1.17.659 1.591L19.8 15.3M14.25 3.104c.251.023.501.05.75.082M19.8 15.3l-1.57.393A9.065 9.065 0 0112 15a9.065 9.065 0 00-6.23.693L5 14.5m14.8.8l1.402 1.402c1.232 1.232.65 3.318-1.067 3.611A48.309 48.309 0 0112 21c-2.773 0-5.491-.235-8.135-.687-1.718-.293-2.3-2.379-1.067-3.61L5 14.5" />
@@ -669,12 +671,12 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
 
       {/* Endpoint Info */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Endpoints
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6 space-y-3">
+        <div className="rounded-xl border p-6 space-y-3" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
           <div className="flex flex-col sm:flex-row sm:items-center gap-2 sm:gap-4">
-            <span className="text-sm font-medium text-zinc-500 w-24 flex items-center gap-2">
+            <span className="text-sm font-medium w-24 flex items-center gap-2" style={{ color: "var(--muted-foreground)" }}>
               <span className="w-2 h-2 rounded-full bg-emerald-500" />
               HTTP
             </span>
@@ -683,7 +685,7 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
             </code>
           </div>
           <div className="flex flex-col sm:flex-row sm:items-center gap-2 sm:gap-4">
-            <span className="text-sm font-medium text-zinc-500 w-24 flex items-center gap-2">
+            <span className="text-sm font-medium w-24 flex items-center gap-2" style={{ color: "var(--muted-foreground)" }}>
               <span className="w-2 h-2 rounded-full bg-blue-500" />
               WebSocket
             </span>
@@ -692,7 +694,7 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
             </code>
           </div>
           <div className="flex flex-col sm:flex-row sm:items-center gap-2 sm:gap-4">
-            <span className="text-sm font-medium text-zinc-500 w-24 flex items-center gap-2">
+            <span className="text-sm font-medium w-24 flex items-center gap-2" style={{ color: "var(--muted-foreground)" }}>
               <span className="w-2 h-2 rounded-full bg-purple-500" />
               GraphiQL
             </span>
@@ -710,38 +712,38 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
 
       {/* Protocol Info */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Protocol Details
         </h3>
         <div className="grid gap-4 sm:grid-cols-2">
-          <div className="rounded-xl border border-zinc-200/60 bg-white p-5">
+          <div className="rounded-xl border p-5" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
             <div className="flex items-center gap-2 mb-3">
-              <div className="w-8 h-8 rounded-lg bg-emerald-100 flex items-center justify-center">
-                <svg className="w-4 h-4 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+              <div className="w-8 h-8 rounded-lg flex items-center justify-center" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)" }}>
+                <svg className="w-4 h-4" style={{ color: "oklch(0.55 0.15 155)" }} fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M12 21a9.004 9.004 0 008.716-6.747M12 21a9.004 9.004 0 01-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 017.843 4.582M12 3a8.997 8.997 0 00-7.843 4.582m15.686 0A11.953 11.953 0 0112 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0121 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0112 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 013 12c0-1.605.42-3.113 1.157-4.418" />
                 </svg>
               </div>
-              <span className="font-medium text-zinc-800">HTTP/HTTPS</span>
+              <span className="font-medium" style={{ color: "var(--foreground)" }}>HTTP/HTTPS</span>
             </div>
-            <p className="text-sm text-zinc-500 leading-relaxed">
+            <p className="text-sm leading-relaxed" style={{ color: "var(--muted-foreground)" }}>
               Standard GraphQL over HTTP. Send POST requests with JSON body containing 
-              <code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded mx-1 text-zinc-700">query</code> 
+              <code className="text-xs px-1.5 py-0.5 rounded mx-1" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>query</code> 
               and optional 
-              <code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded mx-1 text-zinc-700">variables</code>.
+              <code className="text-xs px-1.5 py-0.5 rounded mx-1" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>variables</code>.
             </p>
           </div>
-          <div className="rounded-xl border border-zinc-200/60 bg-white p-5">
+          <div className="rounded-xl border p-5" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
             <div className="flex items-center gap-2 mb-3">
-              <div className="w-8 h-8 rounded-lg bg-blue-100 flex items-center justify-center">
-                <svg className="w-4 h-4 text-blue-600" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+              <div className="w-8 h-8 rounded-lg flex items-center justify-center" style={{ backgroundColor: "oklch(0.60 0.15 250 / 0.15)" }}>
+                <svg className="w-4 h-4" style={{ color: "oklch(0.50 0.15 250)" }} fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M7.5 21L3 16.5m0 0L7.5 12M3 16.5h13.5m0-13.5L21 7.5m0 0L16.5 12M21 7.5H7.5" />
                 </svg>
               </div>
-              <span className="font-medium text-zinc-800">WebSocket</span>
+              <span className="font-medium" style={{ color: "var(--foreground)" }}>WebSocket</span>
             </div>
-            <p className="text-sm text-zinc-500 leading-relaxed">
+            <p className="text-sm leading-relaxed" style={{ color: "var(--muted-foreground)" }}>
               Uses the 
-              <code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded mx-1 text-zinc-700">graphql-transport-ws</code> 
+              <code className="text-xs px-1.5 py-0.5 rounded mx-1" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>graphql-transport-ws</code> 
               protocol for subscriptions. Connect with subprotocol header set accordingly.
             </p>
           </div>
@@ -751,27 +753,25 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
       {/* Connection Tabs */}
       <div className="space-y-4">
         <div className="flex flex-col sm:flex-row sm:items-center gap-4">
-          <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+          <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
             Code Examples
           </h3>
-          <div className="flex gap-1 bg-zinc-100 p-1 rounded-lg w-fit">
+          <div className="flex gap-1 p-1 rounded-lg w-fit" style={{ backgroundColor: "var(--muted)" }}>
             <button
               onClick={() => setActiveTab("http")}
-              className={`px-4 py-2 text-sm font-medium rounded-md transition-all ${
-                activeTab === "http"
-                  ? "bg-white text-zinc-900 shadow-sm"
-                  : "text-zinc-500 hover:text-zinc-700"
-              }`}
+              className="px-4 py-2 text-sm font-medium rounded-md transition-all shadow-sm"
+              style={activeTab === "http"
+                ? { backgroundColor: "var(--card)", color: "var(--foreground)" }
+                : { color: "var(--muted-foreground)" }}
             >
               HTTP Queries
             </button>
             <button
               onClick={() => setActiveTab("websocket")}
-              className={`px-4 py-2 text-sm font-medium rounded-md transition-all ${
-                activeTab === "websocket"
-                  ? "bg-white text-zinc-900 shadow-sm"
-                  : "text-zinc-500 hover:text-zinc-700"
-              }`}
+              className="px-4 py-2 text-sm font-medium rounded-md transition-all"
+              style={activeTab === "websocket"
+                ? { backgroundColor: "var(--card)", color: "var(--foreground)" }
+                : { color: "var(--muted-foreground)" }}
             >
               WebSocket Subscriptions
             </button>
@@ -795,96 +795,96 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
 
       {/* WebSocket Protocol Details */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           WebSocket Protocol Reference
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6 space-y-6">
-          <p className="text-sm text-zinc-600 leading-relaxed">
-            Hyperindex implements the <code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded text-zinc-700">graphql-transport-ws</code> protocol. 
+        <div className="rounded-xl border p-6 space-y-6" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
+          <p className="text-sm leading-relaxed" style={{ color: "var(--secondary-foreground)" }}>
+            Hyperindex implements the <code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>graphql-transport-ws</code> protocol. 
             This is the modern standard for GraphQL subscriptions over WebSocket.
           </p>
 
           <div className="space-y-4">
-            <h4 className="font-medium text-zinc-800">Connection Flow</h4>
-            <ol className="space-y-3 text-sm text-zinc-600">
+            <h4 className="font-medium" style={{ color: "var(--foreground)" }}>Connection Flow</h4>
+            <ol className="space-y-3 text-sm" style={{ color: "var(--secondary-foreground)" }}>
               <li className="flex gap-3">
-                <span className="flex-shrink-0 w-6 h-6 rounded-full bg-emerald-100 text-emerald-700 text-xs font-medium flex items-center justify-center">1</span>
+                <span className="flex-shrink-0 w-6 h-6 rounded-full text-xs font-medium flex items-center justify-center" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)", color: "oklch(0.55 0.15 155)" }}>1</span>
                 <div>
-                  <strong>Connect</strong> - Open WebSocket with <code className="text-xs bg-zinc-100 px-1 py-0.5 rounded">Sec-WebSocket-Protocol: graphql-transport-ws</code>
+                  <strong>Connect</strong> - Open WebSocket with <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>Sec-WebSocket-Protocol: graphql-transport-ws</code>
                 </div>
               </li>
               <li className="flex gap-3">
-                <span className="flex-shrink-0 w-6 h-6 rounded-full bg-emerald-100 text-emerald-700 text-xs font-medium flex items-center justify-center">2</span>
+                <span className="flex-shrink-0 w-6 h-6 rounded-full text-xs font-medium flex items-center justify-center" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)", color: "oklch(0.55 0.15 155)" }}>2</span>
                 <div>
-                  <strong>Initialize</strong> - Send <code className="text-xs bg-zinc-100 px-1 py-0.5 rounded">{`{"type":"connection_init"}`}</code>
+                  <strong>Initialize</strong> - Send <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>{`{"type":"connection_init"}`}</code>
                 </div>
               </li>
               <li className="flex gap-3">
-                <span className="flex-shrink-0 w-6 h-6 rounded-full bg-emerald-100 text-emerald-700 text-xs font-medium flex items-center justify-center">3</span>
+                <span className="flex-shrink-0 w-6 h-6 rounded-full text-xs font-medium flex items-center justify-center" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)", color: "oklch(0.55 0.15 155)" }}>3</span>
                 <div>
-                  <strong>Acknowledge</strong> - Receive <code className="text-xs bg-zinc-100 px-1 py-0.5 rounded">{`{"type":"connection_ack"}`}</code>
+                  <strong>Acknowledge</strong> - Receive <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>{`{"type":"connection_ack"}`}</code>
                 </div>
               </li>
               <li className="flex gap-3">
-                <span className="flex-shrink-0 w-6 h-6 rounded-full bg-emerald-100 text-emerald-700 text-xs font-medium flex items-center justify-center">4</span>
+                <span className="flex-shrink-0 w-6 h-6 rounded-full text-xs font-medium flex items-center justify-center" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)", color: "oklch(0.55 0.15 155)" }}>4</span>
                 <div>
                   <strong>Subscribe</strong> - Send subscription with unique ID
                 </div>
               </li>
               <li className="flex gap-3">
-                <span className="flex-shrink-0 w-6 h-6 rounded-full bg-emerald-100 text-emerald-700 text-xs font-medium flex items-center justify-center">5</span>
+                <span className="flex-shrink-0 w-6 h-6 rounded-full text-xs font-medium flex items-center justify-center" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)", color: "oklch(0.55 0.15 155)" }}>5</span>
                 <div>
-                  <strong>Receive</strong> - Get <code className="text-xs bg-zinc-100 px-1 py-0.5 rounded">{`{"type":"next"}`}</code> messages with data
+                  <strong>Receive</strong> - Get <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>{`{"type":"next"}`}</code> messages with data
                 </div>
               </li>
             </ol>
           </div>
 
           <div className="space-y-3">
-            <h4 className="font-medium text-zinc-800">Message Types</h4>
+            <h4 className="font-medium" style={{ color: "var(--foreground)" }}>Message Types</h4>
             <div className="overflow-x-auto -mx-6 px-6">
               <table className="w-full text-sm">
                 <thead>
-                  <tr className="border-b border-zinc-200">
-                    <th className="text-left py-2 pr-4 font-medium text-zinc-700">Type</th>
-                    <th className="text-left py-2 pr-4 font-medium text-zinc-700">Direction</th>
-                    <th className="text-left py-2 font-medium text-zinc-700">Description</th>
+                  <tr className="border-b" style={{ borderColor: "var(--border)" }}>
+                    <th className="text-left py-2 pr-4 font-medium" style={{ color: "var(--foreground)" }}>Type</th>
+                    <th className="text-left py-2 pr-4 font-medium" style={{ color: "var(--foreground)" }}>Direction</th>
+                    <th className="text-left py-2 font-medium" style={{ color: "var(--foreground)" }}>Description</th>
                   </tr>
                 </thead>
-                <tbody className="text-zinc-600">
-                  <tr className="border-b border-zinc-100">
-                    <td className="py-2.5 pr-4"><code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded">connection_init</code></td>
-                    <td className="py-2.5 pr-4 text-zinc-400">Client → Server</td>
+                <tbody style={{ color: "var(--secondary-foreground)" }}>
+                  <tr className="border-b" style={{ borderColor: "var(--border)" }}>
+                    <td className="py-2.5 pr-4"><code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>connection_init</code></td>
+                    <td className="py-2.5 pr-4" style={{ color: "var(--muted-foreground)" }}>Client → Server</td>
                     <td className="py-2.5">Initialize connection</td>
                   </tr>
-                  <tr className="border-b border-zinc-100">
-                    <td className="py-2.5 pr-4"><code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded">connection_ack</code></td>
-                    <td className="py-2.5 pr-4 text-zinc-400">Server → Client</td>
+                  <tr className="border-b" style={{ borderColor: "var(--border)" }}>
+                    <td className="py-2.5 pr-4"><code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>connection_ack</code></td>
+                    <td className="py-2.5 pr-4" style={{ color: "var(--muted-foreground)" }}>Server → Client</td>
                     <td className="py-2.5">Connection accepted</td>
                   </tr>
-                  <tr className="border-b border-zinc-100">
-                    <td className="py-2.5 pr-4"><code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded">subscribe</code></td>
-                    <td className="py-2.5 pr-4 text-zinc-400">Client → Server</td>
+                  <tr className="border-b" style={{ borderColor: "var(--border)" }}>
+                    <td className="py-2.5 pr-4"><code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>subscribe</code></td>
+                    <td className="py-2.5 pr-4" style={{ color: "var(--muted-foreground)" }}>Client → Server</td>
                     <td className="py-2.5">Start subscription</td>
                   </tr>
-                  <tr className="border-b border-zinc-100">
-                    <td className="py-2.5 pr-4"><code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded">next</code></td>
-                    <td className="py-2.5 pr-4 text-zinc-400">Server → Client</td>
+                  <tr className="border-b" style={{ borderColor: "var(--border)" }}>
+                    <td className="py-2.5 pr-4"><code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>next</code></td>
+                    <td className="py-2.5 pr-4" style={{ color: "var(--muted-foreground)" }}>Server → Client</td>
                     <td className="py-2.5">Data payload</td>
                   </tr>
-                  <tr className="border-b border-zinc-100">
-                    <td className="py-2.5 pr-4"><code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded">error</code></td>
-                    <td className="py-2.5 pr-4 text-zinc-400">Server → Client</td>
+                  <tr className="border-b" style={{ borderColor: "var(--border)" }}>
+                    <td className="py-2.5 pr-4"><code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>error</code></td>
+                    <td className="py-2.5 pr-4" style={{ color: "var(--muted-foreground)" }}>Server → Client</td>
                     <td className="py-2.5">Subscription error</td>
                   </tr>
-                  <tr className="border-b border-zinc-100">
-                    <td className="py-2.5 pr-4"><code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded">complete</code></td>
-                    <td className="py-2.5 pr-4 text-zinc-400">Both</td>
+                  <tr className="border-b" style={{ borderColor: "var(--border)" }}>
+                    <td className="py-2.5 pr-4"><code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>complete</code></td>
+                    <td className="py-2.5 pr-4" style={{ color: "var(--muted-foreground)" }}>Both</td>
                     <td className="py-2.5">End subscription</td>
                   </tr>
                   <tr>
-                    <td className="py-2.5 pr-4"><code className="text-xs bg-zinc-100 px-1.5 py-0.5 rounded">ping/pong</code></td>
-                    <td className="py-2.5 pr-4 text-zinc-400">Both</td>
+                    <td className="py-2.5 pr-4"><code className="text-xs px-1.5 py-0.5 rounded" style={{ backgroundColor: "var(--muted)", color: "var(--foreground)" }}>ping/pong</code></td>
+                    <td className="py-2.5 pr-4" style={{ color: "var(--muted-foreground)" }}>Both</td>
                     <td className="py-2.5">Keep-alive</td>
                   </tr>
                 </tbody>
@@ -896,49 +896,49 @@ websocat ${API_ENDPOINT.replace("https://", "wss://")}/graphql \\
 
       {/* Tips */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Tips & Best Practices
         </h3>
-        <div className="rounded-xl border border-emerald-200/60 bg-gradient-to-br from-emerald-50/50 to-white p-6">
-          <ul className="space-y-4 text-sm text-zinc-700">
+        <div className="rounded-xl border p-6" style={{ borderColor: "var(--border)", backgroundColor: "var(--card)" }}>
+          <ul className="space-y-4 text-sm" style={{ color: "var(--foreground)" }}>
             <li className="flex gap-3">
-              <div className="w-6 h-6 rounded-full bg-emerald-100 flex items-center justify-center flex-shrink-0 mt-0.5">
-                <svg className="w-3.5 h-3.5 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
+              <div className="w-6 h-6 rounded-full flex items-center justify-center flex-shrink-0 mt-0.5" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)" }}>
+                <svg className="w-3.5 h-3.5" style={{ color: "oklch(0.55 0.15 155)" }} fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
                 </svg>
               </div>
               <span>
-                <strong className="text-zinc-900">Use GraphiQL</strong> — Explore the schema interactively at <a href={`${API_ENDPOINT}/graphiql`} target="_blank" rel="noopener noreferrer" className="text-emerald-600 hover:underline">/graphiql</a>
+                <strong style={{ color: "var(--foreground)" }}>Use GraphiQL</strong> — Explore the schema interactively at <a href={`${API_ENDPOINT}/graphiql`} target="_blank" rel="noopener noreferrer" style={{ color: "var(--primary)" }} className="hover:underline">/graphiql</a>
               </span>
             </li>
             <li className="flex gap-3">
-              <div className="w-6 h-6 rounded-full bg-emerald-100 flex items-center justify-center flex-shrink-0 mt-0.5">
-                <svg className="w-3.5 h-3.5 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
+              <div className="w-6 h-6 rounded-full flex items-center justify-center flex-shrink-0 mt-0.5" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)" }}>
+                <svg className="w-3.5 h-3.5" style={{ color: "oklch(0.55 0.15 155)" }} fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
                 </svg>
               </div>
               <span>
-                <strong className="text-zinc-900">Schema introspection</strong> — Dynamically generated from uploaded lexicons
+                <strong style={{ color: "var(--foreground)" }}>Schema introspection</strong> — Dynamically generated from uploaded lexicons
               </span>
             </li>
             <li className="flex gap-3">
-              <div className="w-6 h-6 rounded-full bg-emerald-100 flex items-center justify-center flex-shrink-0 mt-0.5">
-                <svg className="w-3.5 h-3.5 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
+              <div className="w-6 h-6 rounded-full flex items-center justify-center flex-shrink-0 mt-0.5" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)" }}>
+                <svg className="w-3.5 h-3.5" style={{ color: "oklch(0.55 0.15 155)" }} fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
                 </svg>
               </div>
               <span>
-                <strong className="text-zinc-900">Relay pagination</strong> — Use <code className="text-xs bg-emerald-100 px-1 py-0.5 rounded">first</code>, <code className="text-xs bg-emerald-100 px-1 py-0.5 rounded">after</code>, <code className="text-xs bg-emerald-100 px-1 py-0.5 rounded">last</code>, <code className="text-xs bg-emerald-100 px-1 py-0.5 rounded">before</code> for cursors
+                <strong style={{ color: "var(--foreground)" }}>Relay pagination</strong> — Use <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--accent)" }}>first</code>, <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--accent)" }}>after</code>, <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--accent)" }}>last</code>, <code className="text-xs px-1 py-0.5 rounded" style={{ backgroundColor: "var(--accent)" }}>before</code> for cursors
               </span>
             </li>
             <li className="flex gap-3">
-              <div className="w-6 h-6 rounded-full bg-emerald-100 flex items-center justify-center flex-shrink-0 mt-0.5">
-                <svg className="w-3.5 h-3.5 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
+              <div className="w-6 h-6 rounded-full flex items-center justify-center flex-shrink-0 mt-0.5" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.15)" }}>
+                <svg className="w-3.5 h-3.5" style={{ color: "oklch(0.55 0.15 155)" }} fill="none" viewBox="0 0 24 24" strokeWidth={2.5} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M4.5 12.75l6 6 9-13.5" />
                 </svg>
               </div>
               <span>
-                <strong className="text-zinc-900">Handle reconnection</strong> — Implement exponential backoff for WebSocket subscriptions
+                <strong style={{ color: "var(--foreground)" }}>Handle reconnection</strong> — Implement exponential backoff for WebSocket subscriptions
               </span>
             </li>
           </ul>
diff --git a/client/src/app/globals.css b/client/src/app/globals.css
index 49a838b..1b212cd 100644
--- a/client/src/app/globals.css
+++ b/client/src/app/globals.css
@@ -1,19 +1,136 @@
 @import "tailwindcss";
 
+@custom-variant dark (&:where(.dark, .dark *));
+
+:root {
+  --font-sans: system-ui, sans-serif;
+  --font-display: var(--font-syne);
+  --font-body: var(--font-outfit);
+  --radius: 0.625rem;
+
+  --background: oklch(0.985 0.002 260);
+  --foreground: oklch(0.16 0.005 260);
+  --card: oklch(0.995 0.001 260);
+  --card-foreground: oklch(0.16 0.005 260);
+  --primary: oklch(0.20 0.005 260);
+  --primary-foreground: oklch(0.98 0.005 260);
+  --secondary: oklch(0.96 0.005 260);
+  --secondary-foreground: oklch(0.20 0.005 260);
+  --muted: oklch(0.96 0.005 260);
+  --muted-foreground: oklch(0.50 0.01 260);
+  --accent: oklch(0.94 0.005 260);
+  --accent-foreground: oklch(0.20 0.005 260);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.91 0.005 260);
+  --input: oklch(0.91 0.005 260);
+  --ring: oklch(0.35 0.01 260);
+}
+
+.dark {
+  --background: oklch(0.13 0.005 260);
+  --foreground: oklch(0.95 0.005 260);
+  --card: oklch(0.17 0.005 260);
+  --card-foreground: oklch(0.95 0.005 260);
+  --primary: oklch(0.82 0.01 260);
+  --primary-foreground: oklch(0.13 0.005 260);
+  --secondary: oklch(0.22 0.01 260);
+  --secondary-foreground: oklch(0.95 0.005 260);
+  --muted: oklch(0.22 0.008 260);
+  --muted-foreground: oklch(0.65 0.01 260);
+  --accent: oklch(0.25 0.008 260);
+  --accent-foreground: oklch(0.95 0.005 260);
+  --destructive: oklch(0.577 0.245 27.325);
+  --border: oklch(0.95 0 0 / 10%);
+  --input: oklch(0.95 0 0 / 15%);
+  --ring: oklch(0.55 0.01 260);
+}
+
 body {
-  font-family: var(--font-inter), system-ui, sans-serif;
+  font-family: var(--font-body), var(--font-sans);
+  background-color: var(--background);
+  color: var(--foreground);
 }
 
 h1, h2, h3, h4, h5, h6 {
-  font-family: var(--font-garamond), 'Times New Roman', serif;
+  font-family: var(--font-display), var(--font-sans);
+}
+
+/* Glass panel utility */
+.glass-panel {
+  background: oklch(1 0 0 / 0.7);
+  backdrop-filter: blur(20px) saturate(1.4);
+  border: 1px solid oklch(0.92 0.005 260 / 0.6);
+}
+
+.dark .glass-panel {
+  background: oklch(0.18 0.005 260 / 0.7);
+  border: 1px solid oklch(0.95 0 0 / 0.08);
+}
+
+/* Noise background */
+.noise-bg {
+  position: relative;
+}
+
+.noise-bg::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  opacity: 0.03;
+  background-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='noise'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.65' numOctaves='3' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23noise)'/%3E%3C/svg%3E");
+  background-size: 256px 256px;
+  pointer-events: none;
+  z-index: 0;
+}
+
+.dark .noise-bg::before {
+  opacity: 0.06;
 }
 
+/* Gradient mesh */
+.gradient-mesh {
+  background:
+    radial-gradient(ellipse at 20% 50%, oklch(0.40 0.01 260 / 0.08), transparent 50%),
+    radial-gradient(ellipse at 80% 20%, oklch(0.50 0.01 250 / 0.06), transparent 50%),
+    radial-gradient(ellipse at 50% 80%, oklch(0.55 0.008 240 / 0.05), transparent 50%);
+}
+
+/* Animation keyframes */
+@keyframes fadeInUp {
+  from { opacity: 0; transform: translateY(12px); }
+  to { opacity: 1; transform: translateY(0); }
+}
+
+@keyframes fadeIn {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+
+.animate-fade-in-up {
+  animation: fadeInUp 0.5s ease-out both;
+}
+
+.animate-fade-in {
+  animation: fadeIn 0.4s ease-out both;
+}
+
+.stagger-children > *:nth-child(1) { animation-delay: 0ms; }
+.stagger-children > *:nth-child(2) { animation-delay: 60ms; }
+.stagger-children > *:nth-child(3) { animation-delay: 120ms; }
+.stagger-children > *:nth-child(4) { animation-delay: 180ms; }
+.stagger-children > *:nth-child(5) { animation-delay: 240ms; }
+.stagger-children > *:nth-child(6) { animation-delay: 300ms; }
+
 /* Custom scrollbar styling */
 .overflow-y-auto {
   scrollbar-width: thin;
   scrollbar-color: #e4e4e7 transparent;
 }
 
+.dark .overflow-y-auto {
+  scrollbar-color: #3f3f46 transparent;
+}
+
 .overflow-y-auto::-webkit-scrollbar {
   width: 5px;
 }
@@ -27,6 +144,10 @@ h1, h2, h3, h4, h5, h6 {
   border-radius: 3px;
 }
 
+.dark .overflow-y-auto::-webkit-scrollbar-thumb {
+  background-color: #3f3f46;
+}
+
 /* Hide scrollbar utility */
 .scrollbar-none {
   -ms-overflow-style: none;
diff --git a/client/src/app/graphiql/route.ts b/client/src/app/graphiql/route.ts
new file mode 100644
index 0000000..804e40f
--- /dev/null
+++ b/client/src/app/graphiql/route.ts
@@ -0,0 +1,12 @@
+import { redirect } from "next/navigation";
+import { env } from "@/lib/env";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * Redirects to the backend's GraphiQL explorer.
+ * This is a server-side route so it reads HYPERINDEX_URL at runtime.
+ */
+export async function GET() {
+  redirect(`${env.HYPERINDEX_URL}/graphiql`);
+}
diff --git a/client/src/app/layout.tsx b/client/src/app/layout.tsx
index 54c4821..7649781 100644
--- a/client/src/app/layout.tsx
+++ b/client/src/app/layout.tsx
@@ -1,28 +1,30 @@
 import type { Metadata } from "next";
-import { Inter, EB_Garamond } from "next/font/google";
+import { Syne, Outfit } from "next/font/google";
 import Image from "next/image";
 import { Header } from "@/components/layout/Header";
 import { GeometricBackground } from "@/components/layout/GeometricBackground";
 import { Providers } from "@/components/Providers";
+import { ThemeProvider } from "@/components/ThemeProvider";
 import "./globals.css";
 
-const inter = Inter({
-  variable: "--font-inter",
+const syne = Syne({
+  variable: "--font-syne",
   subsets: ["latin"],
+  weight: ["400", "500", "600", "700", "800"],
 });
 
-const garamond = EB_Garamond({
-  variable: "--font-garamond",
+const outfit = Outfit({
+  variable: "--font-outfit",
   subsets: ["latin"],
-  weight: ["400", "500", "600", "700"],
+  weight: ["300", "400", "500", "600", "700"],
 });
 
 export const metadata: Metadata = {
   title: "Hyperindex",
   description: "AT Protocol AppView Server",
   icons: {
-    icon: "/gainforest-logo.png",
-    apple: "/gainforest-logo.png",
+    icon: "/hypercerts_logo.png",
+    apple: "/hypercerts_logo.png",
   },
 };
 
@@ -32,48 +34,36 @@ export default function RootLayout({
   children: React.ReactNode;
 }>) {
   return (
-    <html lang="en">
+    <html lang="en" suppressHydrationWarning>
       <body
-        className={`${inter.variable} ${garamond.variable} antialiased bg-white text-zinc-800`}
+        className={`${syne.variable} ${outfit.variable} antialiased`}
       >
         <Providers>
-          <div className="relative min-h-screen overflow-hidden flex flex-col">
-            {/* Animated geometric background */}
-            <GeometricBackground />
-
-            <Header />
-
-            {/* Main content */}
-            <main className="relative flex-1 max-w-3xl w-full mx-auto px-4 sm:px-6 pb-8">
-              {children}
-            </main>
-
-            {/* Footer */}
-            <footer className="relative py-6 mt-auto">
-              <div className="max-w-3xl mx-auto px-4 sm:px-6">
-                <a
-                  href="https://gainforest.earth"
-                  target="_blank"
-                  rel="noopener noreferrer"
-                  className="flex items-center justify-center gap-1.5 hover:opacity-80 transition-opacity"
-                >
-                  <span className="text-[11px] text-zinc-400 tracking-wide">
-                    Made by
-                  </span>
-                  <Image
-                    src="/gainforest-logo.png"
-                    alt="GainForest"
-                    width={14}
-                    height={14}
-                    className="inline-block"
-                  />
-                  <span className="text-[11px] text-emerald-600 font-medium tracking-wide">
-                    GainForest
-                  </span>
-                </a>
-              </div>
-            </footer>
-          </div>
+          <ThemeProvider>
+            <div className="relative min-h-screen overflow-hidden flex flex-col noise-bg">
+              <div className="gradient-mesh fixed inset-0 -z-10 pointer-events-none" />
+              <GeometricBackground />
+              <Header />
+              <main className="relative flex-1 max-w-3xl w-full mx-auto px-4 sm:px-6 pb-8 z-10">
+                {children}
+              </main>
+              {/* Footer */}
+              <footer className="relative py-6 mt-auto z-10">
+                <div className="max-w-3xl mx-auto px-4 sm:px-6">
+                  <a
+                    href="https://gainforest.earth"
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="flex items-center justify-center gap-1.5 hover:opacity-80 transition-opacity"
+                  >
+                    <span className="text-[11px] tracking-wide" style={{ color: "var(--muted-foreground)" }}>Made by</span>
+                    <Image src="/gainforest-logo.png" alt="GainForest" width={14} height={14} className="inline-block" />
+                    <span className="text-[11px] font-medium tracking-wide" style={{ color: "var(--muted-foreground)" }}>GainForest</span>
+                  </a>
+                </div>
+              </footer>
+            </div>
+          </ThemeProvider>
         </Providers>
       </body>
     </html>
diff --git a/client/src/app/lexicons/page.tsx b/client/src/app/lexicons/page.tsx
index 8aedd07..0ee5607 100644
--- a/client/src/app/lexicons/page.tsx
+++ b/client/src/app/lexicons/page.tsx
@@ -114,13 +114,13 @@ function TreeBranch({
           className="flex items-center gap-2 group py-0.5"
         >
           <span
-            className="text-zinc-300 text-xs transition-transform duration-200"
-            style={{ transform: collapsed ? "rotate(-90deg)" : "rotate(0deg)" }}
+            className="text-xs transition-transform duration-200"
+            style={{ transform: collapsed ? "rotate(-90deg)" : "rotate(0deg)", color: "var(--border)" }}
           >
             ▾
           </span>
-          <span className="font-mono text-sm font-medium text-zinc-700">{node.name}</span>
-          <span className="text-zinc-300 text-xs">{countLeaves(node)}</span>
+          <span className="font-mono text-sm font-medium" style={{ color: "var(--foreground)" }}>{node.name}</span>
+          <span className="text-xs" style={{ color: "var(--border)" }}>{countLeaves(node)}</span>
         </button>
         {!collapsed && hasChildren && (
           <div className="mt-1">
@@ -150,18 +150,19 @@ function TreeBranch({
 
     return (
       <div>
-        <div className="group flex items-center py-0.5 hover:bg-zinc-50/50 -mx-1 px-1 rounded transition-colors">
-          <span className="font-mono text-xs text-zinc-200 whitespace-pre select-none shrink-0 hidden sm:inline">
+        <div className="group flex items-center py-0.5 -mx-1 px-1 rounded transition-colors hover:opacity-90">
+          <span className="font-mono text-xs whitespace-pre select-none shrink-0 hidden sm:inline" style={{ color: "var(--border)" }}>
             {prefix}{branch}
           </span>
           <button
             onClick={() => onToggleExpand(node.lexicon!.id)}
-            className="font-mono text-sm text-emerald-600 hover:text-emerald-700 transition-colors text-left"
+            className="font-mono text-sm transition-colors text-left"
+            style={{ color: "var(--primary)" }}
           >
             {node.name}
           </button>
           {description && (
-            <span className="text-xs text-zinc-300 ml-2 truncate hidden sm:inline">
+            <span className="text-xs ml-2 truncate hidden sm:inline" style={{ color: "var(--border)" }}>
               {description}
             </span>
           )}
@@ -171,11 +172,12 @@ function TreeBranch({
               if (!isDeleting) onDelete(node.lexicon!.id);
             }}
             disabled={isDeleting}
-            className="opacity-0 group-hover:opacity-100 ml-auto p-1 text-zinc-300 hover:text-red-400 transition-all disabled:opacity-50"
+            className="opacity-0 group-hover:opacity-100 ml-auto p-1 hover:text-red-400 transition-all disabled:opacity-50"
+            style={{ color: "var(--border)" }}
             title={`Delete ${node.lexicon.id}`}
           >
             {isDeleting ? (
-              <div className="w-3 h-3 rounded-full border-2 border-zinc-300 border-t-zinc-500 animate-spin" />
+              <div className="w-3 h-3 rounded-full border-2 border-t-transparent animate-spin" style={{ borderColor: "var(--border)", borderTopColor: "var(--muted-foreground)" }} />
             ) : (
               <svg className="w-3 h-3" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                 <path strokeLinecap="round" strokeLinejoin="round" d="M6 18 18 6M6 6l12 12" />
@@ -185,7 +187,7 @@ function TreeBranch({
         </div>
         {isExpanded && (
           <div className="ml-4 sm:ml-8 mt-2 mb-3">
-            <pre className="text-xs bg-zinc-50 text-zinc-600 p-3 rounded-lg overflow-x-auto border border-zinc-100">
+            <pre className="text-xs p-3 rounded-lg overflow-x-auto border" style={{ backgroundColor: "var(--muted)", color: "var(--secondary-foreground)", borderColor: "var(--border)" }}>
               {JSON.stringify(JSON.parse(node.lexicon.json), null, 2)}
             </pre>
           </div>
@@ -197,18 +199,18 @@ function TreeBranch({
   // Intermediate directory node
   return (
     <div>
-      <div className="flex items-center py-0.5 hover:bg-zinc-50/50 -mx-1 px-1 rounded transition-colors">
-        <span className="font-mono text-xs text-zinc-200 whitespace-pre select-none shrink-0 hidden sm:inline">
+      <div className="flex items-center py-0.5 -mx-1 px-1 rounded transition-colors hover:opacity-90">
+        <span className="font-mono text-xs whitespace-pre select-none shrink-0 hidden sm:inline" style={{ color: "var(--border)" }}>
           {prefix}{branch}
         </span>
         <button
           onClick={() => setCollapsed(!collapsed)}
           className="flex items-center"
         >
-          <span className="font-mono text-sm text-zinc-500">{node.name}</span>
+          <span className="font-mono text-sm" style={{ color: "var(--muted-foreground)" }}>{node.name}</span>
           <span
-            className="text-zinc-300 text-[10px] ml-1 transition-transform duration-200"
-            style={{ transform: collapsed ? "rotate(-90deg)" : "rotate(0deg)" }}
+            className="text-[10px] ml-1 transition-transform duration-200"
+            style={{ transform: collapsed ? "rotate(-90deg)" : "rotate(0deg)", color: "var(--border)" }}
           >
             ▾
           </span>
@@ -242,6 +244,7 @@ export default function LexiconsPage() {
   const [success, setSuccess] = useState<string | null>(null);
   const [deletingNsid, setDeletingNsid] = useState<string | null>(null);
   const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [batchPending, setBatchPending] = useState(false);
 
   const { data, isLoading, error: fetchError } = useQuery({
     queryKey: ["lexicons"],
@@ -251,17 +254,6 @@ export default function LexiconsPage() {
   const registerMutation = useMutation({
     mutationFn: (nsid: string) =>
       graphqlClient.request(REGISTER_LEXICON, { nsid }),
-    onSuccess: (_, nsid) => {
-      setSuccess(`Registered ${nsid}`);
-      setError(null);
-      setNsidInput("");
-      queryClient.invalidateQueries({ queryKey: ["lexicons"] });
-      setTimeout(() => setSuccess(null), 3000);
-    },
-    onError: (err: Error) => {
-      setError(err.message);
-      setSuccess(null);
-    },
   });
 
   const deleteMutation = useMutation({
@@ -282,18 +274,54 @@ export default function LexiconsPage() {
     onSettled: () => setDeletingNsid(null),
   });
 
-  const handleRegister = (e: React.FormEvent) => {
+  const handleRegister = async (e: React.FormEvent) => {
     e.preventDefault();
-    const trimmed = nsidInput.trim();
-    if (!trimmed) return;
+    if (!nsidInput.trim()) return;
 
-    if (!isValidNsid(trimmed)) {
-      setError("Invalid NSID format. Expected something like org.example.record.type");
+    // Split by commas, newlines, or whitespace; trim and filter empty
+    const nsids = [...new Set(
+      nsidInput.split(/[,\n\s]+/).map((s) => s.trim()).filter(Boolean)
+    )];
+
+    // Validate all NSIDs before submitting any
+    const invalidNsids = nsids.filter((nsid) => !isValidNsid(nsid));
+    if (invalidNsids.length > 0) {
+      setError(`Invalid NSID format: ${invalidNsids.join(", ")}`);
       return;
     }
 
     setError(null);
-    registerMutation.mutate(trimmed);
+    setBatchPending(true);
+
+    let completed = 0;
+    let firstError: string | null = null;
+
+    for (const nsid of nsids) {
+      try {
+        await registerMutation.mutateAsync(nsid);
+        completed++;
+        if (completed < nsids.length) {
+          setSuccess(`Registered ${completed}/${nsids.length} lexicons...`);
+        }
+      } catch (err) {
+        firstError = (err as Error).message;
+        setError(`Failed to register ${nsid}: ${firstError}`);
+        break;
+      }
+    }
+
+    setBatchPending(false);
+
+    if (completed > 0) {
+      queryClient.invalidateQueries({ queryKey: ["lexicons"] });
+      if (!firstError) {
+        setNsidInput("");
+        setSuccess(`Registered ${completed} lexicon${completed !== 1 ? "s" : ""}`);
+        setTimeout(() => setSuccess(null), 3000);
+      } else {
+        setSuccess(`Registered ${completed}/${nsids.length} lexicons (stopped on error)`);
+      }
+    }
   };
 
   const filteredLexicons = useMemo(() => {
@@ -323,10 +351,10 @@ export default function LexiconsPage() {
     <div className="py-8 space-y-6">
       {/* Header */}
       <div>
-        <h2 className="font-[family-name:var(--font-garamond)] text-2xl text-zinc-900">
+        <h2 className="font-[family-name:var(--font-syne)] text-2xl" style={{ color: "var(--foreground)" }}>
           Lexicons
         </h2>
-        <p className="text-sm text-zinc-400 mt-1">
+        <p className="text-sm mt-1" style={{ color: "var(--muted-foreground)" }}>
           Register AT Protocol lexicon schemas for your AppView
         </p>
       </div>
@@ -340,25 +368,29 @@ export default function LexiconsPage() {
       {success && <Alert variant="success">{success}</Alert>}
 
       {/* Register */}
-      <form onSubmit={handleRegister} className="flex gap-2">
-        <input
-          type="text"
+      <form onSubmit={handleRegister} className="flex gap-2 items-start">
+        <textarea
           value={nsidInput}
           onChange={(e) => {
             setNsidInput(e.target.value);
             setError(null);
           }}
-          placeholder="Enter NSID to register..."
-          className="flex-1 px-3 py-1.5 bg-white/50 border border-zinc-200/60 rounded-lg
-                     text-sm text-zinc-800 placeholder-zinc-400 font-mono
-                     focus:outline-none focus:border-emerald-400 focus:ring-1 focus:ring-emerald-100
-                     transition-all"
+          placeholder="Enter NSIDs (comma or newline separated)..."
+          rows={1}
+          className="flex-1 px-3 py-1.5 rounded-lg text-sm font-mono focus:outline-none focus:ring-1 transition-all resize-y"
+          style={{
+            backgroundColor: "var(--card)",
+            borderColor: "var(--border)",
+            color: "var(--foreground)",
+            border: "1px solid var(--border)",
+            minHeight: "2.25rem",
+          }}
         />
         <Button
           type="submit"
           variant="primary"
-          disabled={registerMutation.isPending || !nsidInput.trim()}
-          loading={registerMutation.isPending}
+          disabled={batchPending || !nsidInput.trim()}
+          loading={batchPending}
         >
           Register
         </Button>
@@ -366,7 +398,7 @@ export default function LexiconsPage() {
 
       {/* Search */}
       <div className="relative">
-        <svg className="absolute left-3 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-zinc-300" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+        <svg className="absolute left-3 top-1/2 -translate-y-1/2 h-3.5 w-3.5" style={{ color: "var(--border)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
           <path strokeLinecap="round" strokeLinejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" />
         </svg>
         <input
@@ -374,21 +406,24 @@ export default function LexiconsPage() {
           placeholder="Search..."
           value={searchQuery}
           onChange={(e) => setSearchQuery(e.target.value)}
-          className="w-full pl-9 pr-3 py-1.5 text-sm bg-white/50 border border-zinc-200/60 rounded-lg
-                     text-zinc-800 placeholder:text-zinc-300
-                     focus:outline-none focus:border-emerald-400 focus:ring-1 focus:ring-emerald-100
-                     transition-all"
+          className="w-full pl-9 pr-3 py-1.5 text-sm rounded-lg focus:outline-none focus:ring-1 transition-all"
+          style={{
+            backgroundColor: "var(--card)",
+            borderColor: "var(--border)",
+            color: "var(--foreground)",
+            border: "1px solid var(--border)",
+          }}
         />
       </div>
 
       {/* Tree */}
       {isLoading ? (
         <div className="flex items-center gap-2 py-8 justify-center">
-          <div className="w-3 h-3 border-2 border-zinc-300 border-t-emerald-400 rounded-full animate-spin" />
-          <span className="text-xs text-zinc-400">Loading...</span>
+          <div className="w-3 h-3 border-2 rounded-full animate-spin" style={{ borderColor: "var(--border)", borderTopColor: "var(--primary)" }} />
+          <span className="text-xs" style={{ color: "var(--muted-foreground)" }}>Loading...</span>
         </div>
       ) : roots.length === 0 ? (
-        <p className="text-sm text-zinc-400 py-4 text-center">
+        <p className="text-sm py-4 text-center" style={{ color: "var(--muted-foreground)" }}>
           {searchQuery ? `No lexicons match "${searchQuery}"` : "No lexicons registered yet."}
         </p>
       ) : (
diff --git a/client/src/app/onboarding/page.tsx b/client/src/app/onboarding/page.tsx
index ef61ee9..287b80e 100644
--- a/client/src/app/onboarding/page.tsx
+++ b/client/src/app/onboarding/page.tsx
@@ -124,7 +124,7 @@ export default function OnboardingPage() {
     uploadLexiconsMutation.isPending;
 
   return (
-    <div className="min-h-screen bg-white flex items-center justify-center p-6">
+    <div className="min-h-screen flex items-center justify-center p-6" style={{ backgroundColor: "var(--card)" }}>
       <div className="w-full max-w-lg">
         {/* Progress Steps */}
         <div className="flex items-center justify-center mb-10">
@@ -135,13 +135,12 @@ export default function OnboardingPage() {
             return (
               <div key={step.id} className="flex items-center">
                 <div
-                  className={`
-                    flex items-center justify-center w-8 h-8 rounded-full text-sm font-medium
-                    transition-colors duration-200
-                    ${isActive ? "bg-emerald-600 text-white" : ""}
-                    ${isComplete ? "bg-emerald-100 text-emerald-600" : ""}
-                    ${!isActive && !isComplete ? "bg-zinc-100 text-zinc-400" : ""}
-                  `}
+                  className="flex items-center justify-center w-8 h-8 rounded-full text-sm font-medium transition-colors duration-200"
+                  style={
+                    isActive || isComplete
+                      ? { backgroundColor: "var(--primary)", color: "var(--primary-foreground)" }
+                      : { backgroundColor: "var(--muted)", color: "var(--muted-foreground)" }
+                  }
                 >
                   {isComplete ? (
                     <svg className="w-4 h-4" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
@@ -153,9 +152,8 @@ export default function OnboardingPage() {
                 </div>
                 {index < STEPS.length - 1 && (
                   <div
-                    className={`w-12 h-0.5 mx-2 ${
-                      isComplete ? "bg-emerald-200" : "bg-zinc-100"
-                    }`}
+                    className="w-12 h-0.5 mx-2"
+                    style={{ backgroundColor: isComplete ? "var(--primary)" : "var(--border)" }}
                   />
                 )}
               </div>
@@ -164,9 +162,9 @@ export default function OnboardingPage() {
         </div>
 
         {/* Step Content */}
-        <div className="rounded-xl border border-zinc-200/60 bg-white shadow-sm">
+        <div className="rounded-xl border shadow-sm" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
           {error && (
-            <div className="p-4 border-b border-zinc-100">
+            <div className="p-4 border-b" style={{ borderColor: "var(--border)" }}>
               <Alert variant="error" onClose={() => setError(null)}>
                 {error}
               </Alert>
@@ -176,35 +174,35 @@ export default function OnboardingPage() {
           {/* Welcome Step */}
           {currentStep === 0 && (
             <div className="p-8 text-center">
-              <div className="mx-auto w-16 h-16 bg-emerald-50 rounded-full flex items-center justify-center mb-6">
-                <svg className="h-8 w-8 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+              <div className="mx-auto w-16 h-16 rounded-full flex items-center justify-center mb-6" style={{ backgroundColor: "var(--muted)" }}>
+                <svg className="h-8 w-8" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M15.59 14.37a6 6 0 0 1-5.84 7.38v-4.8m5.84-2.58a14.98 14.98 0 0 0 6.16-12.12A14.98 14.98 0 0 0 9.631 8.41m5.96 5.96a14.926 14.926 0 0 1-5.841 2.58m-.119-8.54a6 6 0 0 0-7.381 5.84h4.8m2.581-5.84a14.927 14.927 0 0 0-2.58 5.84m2.699 2.7c-.103.021-.207.041-.311.06a15.09 15.09 0 0 1-2.448-2.448 14.9 14.9 0 0 1 .06-.312m-2.24 2.39a4.493 4.493 0 0 0-1.757 4.306 4.493 4.493 0 0 0 4.306-1.758M16.5 9a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0Z" />
                 </svg>
               </div>
-              <h2 className="font-[family-name:var(--font-garamond)] text-2xl text-zinc-900 mb-2">
+              <h2 className="font-[family-name:var(--font-syne)] text-2xl mb-2" style={{ color: "var(--foreground)" }}>
                 Welcome to Hyperindex
               </h2>
-              <p className="text-zinc-500 mb-8">
+              <p className="mb-8" style={{ color: "var(--muted-foreground)" }}>
                 Let&apos;s set up your AT Protocol AppView server. This wizard will guide you
                 through the initial configuration.
               </p>
-              <div className="space-y-3 text-sm text-zinc-500">
+              <div className="space-y-3 text-sm" style={{ color: "var(--muted-foreground)" }}>
                 <p>You&apos;ll configure:</p>
                 <ul className="space-y-2">
                   <li className="flex items-center justify-center gap-2">
-                    <svg className="h-4 w-4 text-emerald-500" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                    <svg className="h-4 w-4" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                       <path strokeLinecap="round" strokeLinejoin="round" d="M12 21a9.004 9.004 0 0 0 8.716-6.747M12 21a9.004 9.004 0 0 1-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 0 1 7.843 4.582M12 3a8.997 8.997 0 0 0-7.843 4.582m15.686 0A11.953 11.953 0 0 1 12 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0 1 21 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0 1 12 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 0 1 3 12c0-1.605.42-3.113 1.157-4.418" />
                     </svg>
                     Your domain authority
                   </li>
                   <li className="flex items-center justify-center gap-2">
-                    <svg className="h-4 w-4 text-emerald-500" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                    <svg className="h-4 w-4" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                       <path strokeLinecap="round" strokeLinejoin="round" d="M18 7.5v3m0 0v3m0-3h3m-3 0h-3m-2.25-4.125a3.375 3.375 0 1 1-6.75 0 3.375 3.375 0 0 1 6.75 0ZM3 19.235v-.11a6.375 6.375 0 0 1 12.75 0v.109A12.318 12.318 0 0 1 9.374 21c-2.331 0-4.512-.645-6.374-1.766Z" />
                     </svg>
                     An admin account
                   </li>
                   <li className="flex items-center justify-center gap-2">
-                    <svg className="h-4 w-4 text-emerald-500" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                    <svg className="h-4 w-4" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                       <path strokeLinecap="round" strokeLinejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z" />
                     </svg>
                     Your lexicon definitions
@@ -218,16 +216,16 @@ export default function OnboardingPage() {
           {currentStep === 1 && (
             <div className="p-8">
               <div className="flex items-center gap-3 mb-6">
-                <div className="w-10 h-10 bg-emerald-50 rounded-full flex items-center justify-center">
-                  <svg className="h-5 w-5 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                <div className="w-10 h-10 rounded-full flex items-center justify-center" style={{ backgroundColor: "var(--muted)" }}>
+                  <svg className="h-5 w-5" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                     <path strokeLinecap="round" strokeLinejoin="round" d="M12 21a9.004 9.004 0 0 0 8.716-6.747M12 21a9.004 9.004 0 0 1-8.716-6.747M12 21c2.485 0 4.5-4.03 4.5-9S14.485 3 12 3m0 18c-2.485 0-4.5-4.03-4.5-9S9.515 3 12 3m0 0a8.997 8.997 0 0 1 7.843 4.582M12 3a8.997 8.997 0 0 0-7.843 4.582m15.686 0A11.953 11.953 0 0 1 12 10.5c-2.998 0-5.74-1.1-7.843-2.918m15.686 0A8.959 8.959 0 0 1 21 12c0 .778-.099 1.533-.284 2.253m0 0A17.919 17.919 0 0 1 12 16.5c-3.162 0-6.133-.815-8.716-2.247m0 0A9.015 9.015 0 0 1 3 12c0-1.605.42-3.113 1.157-4.418" />
                   </svg>
                 </div>
                 <div>
-                  <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+                  <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
                     Domain Authority
                   </h3>
-                  <p className="text-sm text-zinc-400">
+                  <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
                     The domain where your AppView will be hosted
                   </p>
                 </div>
@@ -250,16 +248,16 @@ export default function OnboardingPage() {
           {currentStep === 2 && (
             <div className="p-8">
               <div className="flex items-center gap-3 mb-6">
-                <div className="w-10 h-10 bg-emerald-50 rounded-full flex items-center justify-center">
-                  <svg className="h-5 w-5 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                <div className="w-10 h-10 rounded-full flex items-center justify-center" style={{ backgroundColor: "var(--muted)" }}>
+                  <svg className="h-5 w-5" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                     <path strokeLinecap="round" strokeLinejoin="round" d="M18 7.5v3m0 0v3m0-3h3m-3 0h-3m-2.25-4.125a3.375 3.375 0 1 1-6.75 0 3.375 3.375 0 0 1 6.75 0ZM3 19.235v-.11a6.375 6.375 0 0 1 12.75 0v.109A12.318 12.318 0 0 1 9.374 21c-2.331 0-4.512-.645-6.374-1.766Z" />
                   </svg>
                 </div>
                 <div>
-                  <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+                  <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
                     Admin Account
                   </h3>
-                  <p className="text-sm text-zinc-400">
+                  <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
                     Add the first administrator for your AppView
                   </p>
                 </div>
@@ -283,41 +281,41 @@ export default function OnboardingPage() {
           {currentStep === 3 && (
             <div className="p-8">
               <div className="flex items-center gap-3 mb-6">
-                <div className="w-10 h-10 bg-emerald-50 rounded-full flex items-center justify-center">
-                  <svg className="h-5 w-5 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                <div className="w-10 h-10 rounded-full flex items-center justify-center" style={{ backgroundColor: "var(--muted)" }}>
+                  <svg className="h-5 w-5" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                     <path strokeLinecap="round" strokeLinejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z" />
                   </svg>
                 </div>
                 <div>
-                  <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+                  <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
                     Lexicons
                   </h3>
-                  <p className="text-sm text-zinc-400">
+                  <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
                     Upload your AT Protocol lexicon definitions
                   </p>
                 </div>
               </div>
               <div className="space-y-4">
                 {state.lexiconsUploaded ? (
-                  <div className="flex items-center gap-3 p-4 bg-emerald-50/50 border border-emerald-200/60 rounded-lg">
-                    <svg className="h-5 w-5 text-emerald-500" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                  <div className="flex items-center gap-3 p-4 rounded-lg" style={{ backgroundColor: "oklch(0.65 0.15 155 / 0.08)", borderColor: "oklch(0.65 0.15 155 / 0.2)", border: "1px solid" }}>
+                    <svg className="h-5 w-5" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                       <path strokeLinecap="round" strokeLinejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
                     </svg>
                     <div>
-                      <div className="font-medium text-emerald-700">
+                      <div className="font-medium" style={{ color: "var(--primary)" }}>
                         Lexicons uploaded successfully
                       </div>
-                      <div className="text-sm text-emerald-600/70">
+                      <div className="text-sm" style={{ color: "var(--muted-foreground)" }}>
                         You can upload more lexicons later from the Lexicons page
                       </div>
                     </div>
                   </div>
                 ) : (
-                  <div className="border-2 border-dashed border-zinc-200 rounded-lg p-8 text-center">
-                    <svg className="h-10 w-10 text-zinc-300 mx-auto mb-4" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+                  <div className="border-2 border-dashed rounded-lg p-8 text-center" style={{ borderColor: "var(--border)" }}>
+                    <svg className="h-10 w-10 mx-auto mb-4" style={{ color: "var(--border)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                       <path strokeLinecap="round" strokeLinejoin="round" d="M3 16.5v2.25A2.25 2.25 0 0 0 5.25 21h13.5A2.25 2.25 0 0 0 21 18.75V16.5m-13.5-9L12 3m0 0 4.5 4.5M12 3v13.5" />
                     </svg>
-                    <p className="text-zinc-500 mb-4">
+                    <p className="mb-4" style={{ color: "var(--muted-foreground)" }}>
                       Upload a ZIP file containing your lexicon JSON files
                     </p>
                     <input
@@ -340,7 +338,7 @@ export default function OnboardingPage() {
                     </label>
                   </div>
                 )}
-                <p className="text-xs text-zinc-400">
+                <p className="text-xs" style={{ color: "var(--muted-foreground)" }}>
                   You can skip this step and upload lexicons later. Your AppView will only
                   index records matching your installed lexicons.
                 </p>
@@ -351,46 +349,46 @@ export default function OnboardingPage() {
           {/* Complete Step */}
           {currentStep === 4 && (
             <div className="p-8 text-center">
-              <div className="mx-auto w-16 h-16 bg-emerald-50 rounded-full flex items-center justify-center mb-6">
-                <svg className="h-8 w-8 text-emerald-600" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+              <div className="mx-auto w-16 h-16 rounded-full flex items-center justify-center mb-6" style={{ backgroundColor: "var(--muted)" }}>
+                <svg className="h-8 w-8" style={{ color: "var(--primary)" }} fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
                   <path strokeLinecap="round" strokeLinejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
                 </svg>
               </div>
-              <h2 className="font-[family-name:var(--font-garamond)] text-2xl text-zinc-900 mb-2">
+              <h2 className="font-[family-name:var(--font-syne)] text-2xl mb-2" style={{ color: "var(--foreground)" }}>
                 Setup Complete!
               </h2>
-              <p className="text-zinc-500 mb-8">
+              <p className="mb-8" style={{ color: "var(--muted-foreground)" }}>
                 Your Hyperindex AppView is ready to go.
               </p>
-              <div className="bg-zinc-50 rounded-lg p-4 mb-6 text-left">
-                <h4 className="text-sm font-medium text-zinc-600 mb-3">Configuration Summary</h4>
+              <div className="rounded-lg p-4 mb-6 text-left" style={{ backgroundColor: "var(--muted)" }}>
+                <h4 className="text-sm font-medium mb-3" style={{ color: "var(--secondary-foreground)" }}>Configuration Summary</h4>
                 <dl className="space-y-2 text-sm">
                   <div className="flex justify-between">
-                    <dt className="text-zinc-400">Domain:</dt>
-                    <dd className="font-mono text-zinc-800">{state.domainAuthority || "Not set"}</dd>
+                    <dt style={{ color: "var(--muted-foreground)" }}>Domain:</dt>
+                    <dd className="font-mono" style={{ color: "var(--foreground)" }}>{state.domainAuthority || "Not set"}</dd>
                   </div>
                   <div className="flex justify-between">
-                    <dt className="text-zinc-400">Admin:</dt>
-                    <dd className="font-mono text-zinc-800 truncate max-w-[200px]">
+                    <dt style={{ color: "var(--muted-foreground)" }}>Admin:</dt>
+                    <dd className="font-mono truncate max-w-[200px]" style={{ color: "var(--foreground)" }}>
                       {state.adminDid || "Not set"}
                     </dd>
                   </div>
                   <div className="flex justify-between">
-                    <dt className="text-zinc-400">Lexicons:</dt>
-                    <dd className="text-zinc-800">
+                    <dt style={{ color: "var(--muted-foreground)" }}>Lexicons:</dt>
+                    <dd style={{ color: "var(--foreground)" }}>
                       {state.lexiconsUploaded ? "Uploaded" : "Skipped"}
                     </dd>
                   </div>
                 </dl>
               </div>
-              <p className="text-zinc-400 text-sm">
+              <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
                 You can modify these settings anytime from the Settings page.
               </p>
             </div>
           )}
 
           {/* Navigation */}
-          <div className="flex items-center justify-between p-6 border-t border-zinc-100">
+          <div className="flex items-center justify-between p-6 border-t" style={{ borderColor: "var(--border)" }}>
             <Button
               variant="outline"
               onClick={handleBack}
diff --git a/client/src/app/page.tsx b/client/src/app/page.tsx
index e9568ec..982ebf1 100644
--- a/client/src/app/page.tsx
+++ b/client/src/app/page.tsx
@@ -78,10 +78,13 @@ export default function Dashboard() {
     <div className="pt-8 sm:pt-12 space-y-10">
       {/* Hero Section */}
       <div className="max-w-md">
-        <h2 className="font-[family-name:var(--font-garamond)] text-3xl sm:text-4xl text-zinc-900 leading-tight">
+        <h2
+          className="font-[family-name:var(--font-syne)] text-3xl sm:text-4xl leading-tight"
+          style={{ color: "var(--foreground)" }}
+        >
           Dashboard
         </h2>
-        <p className="text-zinc-500 mt-3 leading-relaxed">
+        <p className="mt-3 leading-relaxed" style={{ color: "var(--muted-foreground)" }}>
           Monitor your AppView server. Track records, activity, and manage your AT Protocol deployment.
         </p>
       </div>
@@ -111,25 +114,45 @@ export default function Dashboard() {
         <Link
           href="/settings"
           className="group flex items-center gap-2 py-2 px-3 -mx-3 rounded-lg
-                     hover:bg-zinc-50 transition-colors"
+                     hover:opacity-80 transition-opacity"
         >
-          <svg className="w-5 h-5 text-zinc-400 group-hover:text-emerald-600 transition-colors" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+          <svg
+            className="w-5 h-5 transition-colors"
+            style={{ color: "var(--muted-foreground)" }}
+            fill="none"
+            viewBox="0 0 24 24"
+            strokeWidth={1.5}
+            stroke="currentColor"
+          >
             <path strokeLinecap="round" strokeLinejoin="round" d="M9.594 3.94c.09-.542.56-.94 1.11-.94h2.593c.55 0 1.02.398 1.11.94l.213 1.281c.063.374.313.686.645.87.074.04.147.083.22.127.325.196.72.257 1.075.124l1.217-.456a1.125 1.125 0 0 1 1.37.49l1.296 2.247a1.125 1.125 0 0 1-.26 1.431l-1.003.827c-.293.241-.438.613-.43.992a7.723 7.723 0 0 1 0 .255c-.008.378.137.75.43.991l1.004.827c.424.35.534.955.26 1.43l-1.298 2.247a1.125 1.125 0 0 1-1.369.491l-1.217-.456c-.355-.133-.75-.072-1.076.124a6.47 6.47 0 0 1-.22.128c-.331.183-.581.495-.644.869l-.213 1.281c-.09.543-.56.94-1.11.94h-2.594c-.55 0-1.019-.398-1.11-.94l-.213-1.281c-.062-.374-.312-.686-.644-.87a6.52 6.52 0 0 1-.22-.127c-.325-.196-.72-.257-1.076-.124l-1.217.456a1.125 1.125 0 0 1-1.369-.49l-1.297-2.247a1.125 1.125 0 0 1 .26-1.431l1.004-.827c.292-.24.437-.613.43-.991a6.932 6.932 0 0 1 0-.255c.007-.38-.138-.751-.43-.992l-1.004-.827a1.125 1.125 0 0 1-.26-1.43l1.297-2.247a1.125 1.125 0 0 1 1.37-.491l1.216.456c.356.133.751.072 1.076-.124.072-.044.146-.086.22-.128.332-.183.582-.495.644-.869l.214-1.28Z" />
             <path strokeLinecap="round" strokeLinejoin="round" d="M15 12a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z" />
           </svg>
-          <span className="text-sm font-medium text-zinc-800 group-hover:text-emerald-700 transition-colors">
+          <span
+            className="text-sm font-medium transition-colors"
+            style={{ color: "var(--foreground)" }}
+          >
             Settings
           </span>
         </Link>
         <Link
           href="/backfill"
           className="group flex items-center gap-2 py-2 px-3 rounded-lg
-                     hover:bg-zinc-50 transition-colors"
+                     hover:opacity-80 transition-opacity"
         >
-          <svg className="w-5 h-5 text-zinc-400 group-hover:text-emerald-600 transition-colors" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+          <svg
+            className="w-5 h-5 transition-colors"
+            style={{ color: "var(--muted-foreground)" }}
+            fill="none"
+            viewBox="0 0 24 24"
+            strokeWidth={1.5}
+            stroke="currentColor"
+          >
             <path strokeLinecap="round" strokeLinejoin="round" d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0 3.181 3.183a8.25 8.25 0 0 0 13.803-3.7M4.031 9.865a8.25 8.25 0 0 1 13.803-3.7l3.181 3.182m0-4.991v4.99" />
           </svg>
-          <span className="text-sm font-medium text-zinc-800 group-hover:text-emerald-700 transition-colors">
+          <span
+            className="text-sm font-medium transition-colors"
+            style={{ color: "var(--foreground)" }}
+          >
             Backfill
           </span>
         </Link>
@@ -138,12 +161,22 @@ export default function Dashboard() {
           target="_blank"
           rel="noopener noreferrer"
           className="group flex items-center gap-2 py-2 px-3 rounded-lg
-                     hover:bg-zinc-50 transition-colors"
+                     hover:opacity-80 transition-opacity"
         >
-          <svg className="w-5 h-5 text-zinc-400 group-hover:text-emerald-600 transition-colors" fill="none" viewBox="0 0 24 24" strokeWidth={1.5} stroke="currentColor">
+          <svg
+            className="w-5 h-5 transition-colors"
+            style={{ color: "var(--muted-foreground)" }}
+            fill="none"
+            viewBox="0 0 24 24"
+            strokeWidth={1.5}
+            stroke="currentColor"
+          >
             <path strokeLinecap="round" strokeLinejoin="round" d="M17.25 6.75 22.5 12l-5.25 5.25m-10.5 0L1.5 12l5.25-5.25m7.5-3-4.5 16.5" />
           </svg>
-          <span className="text-sm font-medium text-zinc-800 group-hover:text-emerald-700 transition-colors">
+          <span
+            className="text-sm font-medium transition-colors"
+            style={{ color: "var(--foreground)" }}
+          >
             GraphiQL
           </span>
         </a>
@@ -176,7 +209,8 @@ export default function Dashboard() {
         <button
           onClick={() => populateActivity.mutate()}
           disabled={populateActivity.isPending}
-          className="text-xs text-zinc-400 hover:text-zinc-600 transition-colors disabled:opacity-50"
+          className="text-xs transition-colors disabled:opacity-50"
+          style={{ color: "var(--muted-foreground)" }}
         >
           {populateActivity.isPending ? "Rebuilding..." : "Rebuild activity from records"}
         </button>
diff --git a/client/src/app/settings/page.tsx b/client/src/app/settings/page.tsx
index 757ecef..088de16 100644
--- a/client/src/app/settings/page.tsx
+++ b/client/src/app/settings/page.tsx
@@ -103,7 +103,7 @@ export default function SettingsPage() {
     return (
       <div className="pt-8 sm:pt-12 space-y-6">
         {[...Array(3)].map((_, i) => (
-          <div key={i} className="h-48 animate-pulse rounded-xl bg-zinc-100" />
+          <div key={i} className="h-48 animate-pulse rounded-xl" style={{ backgroundColor: "var(--muted)" }} />
         ))}
       </div>
     );
@@ -113,10 +113,10 @@ export default function SettingsPage() {
     <div className="pt-8 sm:pt-12 space-y-10">
       {/* Hero Section */}
       <div className="max-w-md">
-        <h2 className="font-[family-name:var(--font-garamond)] text-3xl sm:text-4xl text-zinc-900 leading-tight">
+        <h2 className="font-[family-name:var(--font-syne)] text-3xl sm:text-4xl leading-tight" style={{ color: "var(--foreground)" }}>
           Settings
         </h2>
-        <p className="text-zinc-500 mt-3 leading-relaxed">
+        <p className="mt-3 leading-relaxed" style={{ color: "var(--muted-foreground)" }}>
           Configure your Hyperindex AppView instance
         </p>
       </div>
@@ -129,10 +129,10 @@ export default function SettingsPage() {
 
       {/* Basic Settings */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Basic Settings
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6 space-y-4">
+        <div className="rounded-xl border p-6 space-y-4" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
           <Input
             label="Domain Authority"
             placeholder="your-domain.com"
@@ -154,10 +154,10 @@ export default function SettingsPage() {
 
       {/* External Services */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           External Services
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6 space-y-4">
+        <div className="rounded-xl border p-6 space-y-4" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
           <Input
             label="Relay URL"
             placeholder="https://relay1.us-west.bsky.network"
@@ -196,19 +196,19 @@ export default function SettingsPage() {
 
       {/* Admin DIDs */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           Administrators
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6">
+        <div className="rounded-xl border p-6" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
           {settings?.adminDids.length === 0 ? (
-            <p className="text-sm text-zinc-400">
+            <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
               No administrators configured
             </p>
           ) : (
-            <ul className="divide-y divide-zinc-100">
+            <ul className="divide-y" style={{ borderColor: "var(--border)" }}>
               {settings?.adminDids.map((did) => (
                 <li key={did} className="flex items-center justify-between py-3 first:pt-0 last:pb-0">
-                  <code className="text-sm text-zinc-600 font-mono">{did}</code>
+                  <code className="text-sm font-mono" style={{ color: "var(--secondary-foreground)" }}>{did}</code>
                 </li>
               ))}
             </ul>
@@ -218,26 +218,26 @@ export default function SettingsPage() {
 
       {/* OAuth Clients */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl" style={{ color: "var(--foreground)" }}>
           OAuth Clients
         </h3>
-        <div className="rounded-xl border border-zinc-200/60 bg-white p-6">
+        <div className="rounded-xl border p-6" style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}>
           {oauthClients.length === 0 ? (
-            <p className="text-sm text-zinc-400">
+            <p className="text-sm" style={{ color: "var(--muted-foreground)" }}>
               No OAuth clients registered
             </p>
           ) : (
-            <ul className="divide-y divide-zinc-100">
+            <ul className="divide-y" style={{ borderColor: "var(--border)" }}>
               {oauthClients.map((client) => (
                 <li key={client.clientId} className="py-3 first:pt-0 last:pb-0">
                   <div className="flex items-center justify-between">
                     <div>
-                      <p className="font-medium text-zinc-800">
+                      <p className="font-medium" style={{ color: "var(--foreground)" }}>
                         {client.clientName}
                       </p>
-                      <code className="text-xs text-zinc-400 font-mono">{client.clientId}</code>
+                      <code className="text-xs font-mono" style={{ color: "var(--muted-foreground)" }}>{client.clientId}</code>
                     </div>
-                    <span className="rounded-full bg-zinc-100 px-2 py-1 text-xs text-zinc-600">
+                    <span className="rounded-full px-2 py-1 text-xs" style={{ backgroundColor: "var(--muted)", color: "var(--secondary-foreground)" }}>
                       {client.clientType}
                     </span>
                   </div>
@@ -250,11 +250,11 @@ export default function SettingsPage() {
 
       {/* Danger Zone */}
       <div className="space-y-4">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-red-600">
+        <h3 className="font-[family-name:var(--font-syne)] text-xl text-red-600">
           Danger Zone
         </h3>
         <div className="rounded-xl border border-red-200/60 bg-red-50/30 p-6 space-y-4">
-          <p className="text-sm text-zinc-600">
+          <p className="text-sm" style={{ color: "var(--secondary-foreground)" }}>
             Reset all data including records, actors, and activity. This action cannot be undone.
           </p>
           <div className="flex flex-col sm:flex-row items-start sm:items-end gap-4">
diff --git a/client/src/components/ThemeProvider.tsx b/client/src/components/ThemeProvider.tsx
new file mode 100644
index 0000000..b7a43dd
--- /dev/null
+++ b/client/src/components/ThemeProvider.tsx
@@ -0,0 +1,11 @@
+"use client"
+
+import { ThemeProvider as NextThemesProvider } from "next-themes"
+
+export function ThemeProvider({ children }: { children: React.ReactNode }) {
+  return (
+    <NextThemesProvider attribute="class" defaultTheme="light" enableSystem={false}>
+      {children}
+    </NextThemesProvider>
+  )
+}
diff --git a/client/src/components/ThemeToggle.tsx b/client/src/components/ThemeToggle.tsx
new file mode 100644
index 0000000..9636011
--- /dev/null
+++ b/client/src/components/ThemeToggle.tsx
@@ -0,0 +1,37 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { useTheme } from "next-themes"
+
+export function ThemeToggle() {
+  const { theme, setTheme } = useTheme()
+  const [mounted, setMounted] = useState(false)
+
+  useEffect(() => setMounted(true), [])
+
+  if (!mounted) {
+    return <div className="w-9 h-9" />
+  }
+
+  const isDark = theme === "dark"
+
+  return (
+    <button
+      onClick={() => setTheme(isDark ? "light" : "dark")}
+      className="p-2 rounded-full transition-colors cursor-pointer"
+      style={{ color: "var(--muted-foreground)" }}
+      aria-label={isDark ? "Switch to light mode" : "Switch to dark mode"}
+      title={isDark ? "Switch to light mode" : "Switch to dark mode"}
+    >
+      {isDark ? (
+        <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 3v2.25m6.364.386l-1.591 1.591M21 12h-2.25m-.386 6.364l-1.591-1.591M12 18.75V21m-4.773-4.227l-1.591 1.591M5.25 12H3m4.227-4.773L5.636 5.636M15.75 12a3.75 3.75 0 11-7.5 0 3.75 3.75 0 017.5 0z" />
+        </svg>
+      ) : (
+        <svg className="w-5 h-5" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+          <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M21.752 15.002A9.718 9.718 0 0118 15.75c-5.385 0-9.75-4.365-9.75-9.75 0-1.33.266-2.597.748-3.752A9.753 9.753 0 003 11.25C3 16.635 7.365 21 12.75 21a9.753 9.753 0 009.002-5.998z" />
+        </svg>
+      )}
+    </button>
+  )
+}
diff --git a/client/src/components/dashboard/ActivityChart.tsx b/client/src/components/dashboard/ActivityChart.tsx
index 0ed06d8..0926597 100644
--- a/client/src/components/dashboard/ActivityChart.tsx
+++ b/client/src/components/dashboard/ActivityChart.tsx
@@ -44,7 +44,10 @@ export function ActivityChart({
   return (
     <div className="space-y-4">
       <div className="flex items-center justify-between">
-        <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+        <h3
+          className="font-[family-name:var(--font-syne)] text-xl"
+          style={{ color: "var(--foreground)" }}
+        >
           Activity
         </h3>
         <div className="flex items-center gap-1">
@@ -52,11 +55,12 @@ export function ActivityChart({
             <button
               key={range.value}
               onClick={() => onTimeRangeChange(range.value)}
-              className={`px-2 py-0.5 rounded text-xs transition-colors cursor-pointer ${
+              className="px-2 py-0.5 rounded text-xs transition-colors cursor-pointer"
+              style={
                 timeRange === range.value
-                  ? "bg-emerald-50 text-emerald-600 font-medium"
-                  : "text-zinc-400 hover:text-zinc-600"
-              }`}
+                  ? { backgroundColor: "var(--accent)", color: "var(--primary)", fontWeight: 500 }
+                  : { color: "var(--muted-foreground)" }
+              }
             >
               {range.label}
             </button>
@@ -64,41 +68,50 @@ export function ActivityChart({
         </div>
       </div>
 
-      <div className="rounded-xl border border-zinc-200/60 bg-white p-4">
+      <div
+        className="rounded-xl border p-4"
+        style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}
+      >
         {isLoading ? (
-          <div className="h-48 animate-pulse rounded-lg bg-zinc-50" />
+          <div
+            className="h-48 animate-pulse rounded-lg"
+            style={{ backgroundColor: "var(--muted)" }}
+          />
         ) : data.length === 0 ? (
-          <div className="flex h-48 items-center justify-center text-sm text-zinc-400">
+          <div
+            className="flex h-48 items-center justify-center text-sm"
+            style={{ color: "var(--muted-foreground)" }}
+          >
             No activity data available
           </div>
         ) : (
           <div className="h-48">
             <ResponsiveContainer width="100%" height="100%">
               <AreaChart data={chartData}>
-                <CartesianGrid strokeDasharray="3 3" stroke="#f4f4f5" />
+                <CartesianGrid strokeDasharray="3 3" stroke="var(--border)" />
                 <XAxis
                   dataKey="timestamp"
                   tickFormatter={(value) =>
                     format(new Date(value), timeRange === "SEVEN_DAYS" ? "MMM d" : "HH:mm")
                   }
                   fontSize={11}
-                  stroke="#a1a1aa"
+                  stroke="var(--muted-foreground)"
                   tickLine={false}
                   axisLine={false}
                 />
                 <YAxis
                   fontSize={11}
-                  stroke="#a1a1aa"
+                  stroke="var(--muted-foreground)"
                   tickLine={false}
                   axisLine={false}
                 />
                 <Tooltip
                   contentStyle={{
-                    backgroundColor: "#fff",
-                    border: "1px solid #e4e4e7",
+                    backgroundColor: "var(--card)",
+                    border: "1px solid var(--border)",
                     borderRadius: "0.75rem",
                     fontSize: "12px",
-                    boxShadow: "0 4px 6px -1px rgb(0 0 0 / 0.05)",
+                    color: "var(--foreground)",
                   }}
                   labelFormatter={(value) =>
                     format(new Date(value), "MMM d, yyyy HH:mm")
diff --git a/client/src/components/dashboard/RecentActivity.tsx b/client/src/components/dashboard/RecentActivity.tsx
index 5257f8d..7f1ebe7 100644
--- a/client/src/components/dashboard/RecentActivity.tsx
+++ b/client/src/components/dashboard/RecentActivity.tsx
@@ -27,28 +27,39 @@ function getRecordUrl(entry: ActivityEntry): string | null {
 export function RecentActivity({ entries, isLoading }: RecentActivityProps) {
   return (
     <div className="space-y-4">
-      <h3 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900">
+      <h3
+        className="font-[family-name:var(--font-syne)] text-xl"
+        style={{ color: "var(--foreground)" }}
+      >
         Recent Activity
       </h3>
 
-      <div className="rounded-xl border border-zinc-200/60 bg-white">
+      <div
+        className="rounded-xl border"
+        style={{ backgroundColor: "var(--card)", borderColor: "var(--border)" }}
+      >
         {isLoading ? (
           <div className="p-4 space-y-3">
             {[...Array(5)].map((_, i) => (
               <div
                 key={i}
-                className="h-10 animate-pulse rounded-lg bg-zinc-50"
+                className="h-10 animate-pulse rounded-lg"
+                style={{ backgroundColor: "var(--muted)" }}
               />
             ))}
           </div>
         ) : entries.length === 0 ? (
-          <div className="py-12 text-center text-sm text-zinc-400">
+          <div
+            className="py-12 text-center text-sm"
+            style={{ color: "var(--muted-foreground)" }}
+          >
             No recent activity
           </div>
         ) : (
-          <div className="divide-y divide-zinc-100">
-            {entries.slice(0, 10).map((entry) => {
+          <div>
+            {entries.slice(0, 10).map((entry, idx) => {
               const recordUrl = getRecordUrl(entry);
+              const isLast = idx === Math.min(entries.length, 10) - 1;
               const content = (
                 <>
                   <div className="flex items-center gap-3 min-w-0">
@@ -56,27 +67,46 @@ export function RecentActivity({ entries, isLoading }: RecentActivityProps) {
                     <div className="min-w-0">
                       <div className="flex items-center gap-2">
                         <span
-                          className={`px-1.5 py-0.5 rounded text-[10px] font-medium uppercase tracking-wide ${
+                          className="px-1.5 py-0.5 rounded text-[10px] font-medium uppercase tracking-wide"
+                          style={
                             entry.operation === "create"
-                              ? "bg-emerald-50 text-emerald-600"
+                              ? {
+                                  backgroundColor: "oklch(0.65 0.15 155 / 0.1)",
+                                  color: "oklch(0.55 0.15 155)",
+                                }
                               : entry.operation === "update"
-                              ? "bg-blue-50 text-blue-600"
-                              : "bg-amber-50 text-amber-600"
-                          }`}
+                              ? {
+                                  backgroundColor: "oklch(0.60 0.15 250 / 0.1)",
+                                  color: "oklch(0.50 0.15 250)",
+                                }
+                              : {
+                                  backgroundColor: "oklch(0.75 0.15 75 / 0.1)",
+                                  color: "oklch(0.60 0.15 75)",
+                                }
+                          }
                         >
                           {entry.operation}
                         </span>
-                        <span className="text-sm font-medium text-zinc-800 truncate">
+                        <span
+                          className="text-sm font-medium truncate"
+                          style={{ color: "var(--foreground)" }}
+                        >
                           {entry.collection}
                         </span>
                       </div>
-                      <p className="text-xs text-zinc-400 truncate font-mono">
+                      <p
+                        className="text-xs truncate font-mono"
+                        style={{ color: "var(--muted-foreground)" }}
+                      >
                         {entry.did.slice(0, 32)}...
                       </p>
                     </div>
                   </div>
                   <div className="text-right shrink-0 ml-4">
-                    <p className="text-xs text-zinc-400 font-mono">
+                    <p
+                      className="text-xs font-mono"
+                      style={{ color: "var(--muted-foreground)" }}
+                    >
                       {formatTimestamp(entry.timestamp)}
                     </p>
                     {entry.errorMessage && (
@@ -88,6 +118,10 @@ export function RecentActivity({ entries, isLoading }: RecentActivityProps) {
                 </>
               );
 
+              const rowStyle: React.CSSProperties = {
+                borderBottom: isLast ? undefined : "1px solid var(--border)",
+              };
+
               if (recordUrl) {
                 return (
                   <a
@@ -95,7 +129,8 @@ export function RecentActivity({ entries, isLoading }: RecentActivityProps) {
                     href={recordUrl}
                     target="_blank"
                     rel="noopener noreferrer"
-                    className="flex items-center justify-between px-4 py-3 hover:bg-zinc-50 transition-colors cursor-pointer"
+                    className="flex items-center justify-between px-4 py-3 hover:opacity-90 transition-opacity cursor-pointer"
+                    style={rowStyle}
                   >
                     {content}
                   </a>
@@ -106,6 +141,7 @@ export function RecentActivity({ entries, isLoading }: RecentActivityProps) {
                 <div
                   key={entry.id}
                   className="flex items-center justify-between px-4 py-3"
+                  style={rowStyle}
                 >
                   {content}
                 </div>
@@ -119,15 +155,17 @@ export function RecentActivity({ entries, isLoading }: RecentActivityProps) {
 }
 
 function StatusDot({ status }: { status: string }) {
+  const dotStyle: React.CSSProperties =
+    status === "success"
+      ? { backgroundColor: "oklch(0.65 0.15 155)" }
+      : status === "error"
+      ? { backgroundColor: "oklch(0.60 0.20 25)" }
+      : { backgroundColor: "oklch(0.75 0.15 75)" };
+
   return (
     <span
-      className={`w-2 h-2 rounded-full shrink-0 ${
-        status === "success"
-          ? "bg-emerald-400"
-          : status === "error"
-          ? "bg-red-400"
-          : "bg-amber-400"
-      }`}
+      className="w-2 h-2 rounded-full shrink-0"
+      style={dotStyle}
     />
   );
 }
diff --git a/client/src/components/dashboard/StatsCards.tsx b/client/src/components/dashboard/StatsCards.tsx
index 524989f..1b0b90a 100644
--- a/client/src/components/dashboard/StatsCards.tsx
+++ b/client/src/components/dashboard/StatsCards.tsx
@@ -19,20 +19,17 @@ export function StatsCards({
     {
       name: "Records",
       value: recordCount,
-      color: "text-emerald-600",
-      bg: "bg-emerald-50",
+      colorStyle: { color: "oklch(0.65 0.15 155)" },
     },
     {
       name: "Actors",
       value: actorCount,
-      color: "text-blue-600",
-      bg: "bg-blue-50",
+      colorStyle: { color: "oklch(0.55 0.15 250)" },
     },
     {
       name: "Lexicons",
       value: lexiconCount,
-      color: "text-purple-600",
-      bg: "bg-purple-50",
+      colorStyle: { color: "oklch(0.55 0.15 310)" },
     },
   ];
 
@@ -41,17 +38,20 @@ export function StatsCards({
       {stats.map((stat, index) => (
         <div key={stat.name} className="flex items-center gap-2">
           {isLoading ? (
-            <div className="h-5 w-16 animate-pulse rounded bg-zinc-100" />
+            <div
+              className="h-5 w-16 animate-pulse rounded"
+              style={{ backgroundColor: "var(--muted)" }}
+            />
           ) : (
             <>
-              <span className={`font-medium tabular-nums ${stat.color}`}>
+              <span className="font-medium tabular-nums" style={stat.colorStyle}>
                 {formatNumber(stat.value)}
               </span>
-              <span className="text-zinc-400">{stat.name}</span>
+              <span style={{ color: "var(--muted-foreground)" }}>{stat.name}</span>
             </>
           )}
           {index < stats.length - 1 && (
-            <span className="text-zinc-200 ml-4">&middot;</span>
+            <span className="ml-4" style={{ color: "var(--border)" }}>&middot;</span>
           )}
         </div>
       ))}
diff --git a/client/src/components/layout/GeometricBackground.tsx b/client/src/components/layout/GeometricBackground.tsx
index 78f1a35..ee4634c 100644
--- a/client/src/components/layout/GeometricBackground.tsx
+++ b/client/src/components/layout/GeometricBackground.tsx
@@ -1,19 +1,16 @@
-'use client'
+"use client"
 
-import { useState, useEffect } from 'react'
+import { useState, useEffect } from "react"
 
 export function GeometricBackground() {
   const [showLogo, setShowLogo] = useState(false)
 
-  // Show logo every 30 seconds
   useEffect(() => {
     const interval = setInterval(() => {
       setShowLogo(true)
-      // Hide after animation completes (8s flow down)
       setTimeout(() => setShowLogo(false), 8000)
     }, 30000)
 
-    // Show once on initial load after a short delay
     const initialTimeout = setTimeout(() => {
       setShowLogo(true)
       setTimeout(() => setShowLogo(false), 8000)
@@ -26,72 +23,29 @@ export function GeometricBackground() {
   }, [])
 
   return (
-    <div 
-      className="fixed inset-0 pointer-events-none select-none overflow-hidden"
+    <div
+      className="fixed inset-0 pointer-events-none select-none overflow-hidden z-0"
       aria-hidden="true"
     >
-      {/* Flow column 1 */}
+      {/* Subtle flowing lines using theme-aware colors */}
       <div className="absolute right-[220px] top-0">
-        <div className="w-1 h-20 bg-gradient-to-b from-transparent via-emerald-400/40 to-transparent rounded-full animate-[flowDown_9s_linear_infinite] [animation-fill-mode:backwards]" />
-        <div className="absolute w-6 h-6 border-[1.5px] border-emerald-400/50 animate-[flowDown_12s_linear_infinite_1s] [animation-fill-mode:backwards]" />
-        <svg className="absolute w-3 h-3 animate-[flowDown_8s_linear_infinite_5s] [animation-fill-mode:backwards]" viewBox="0 0 12 12">
-          <polygon points="6,0 12,12 0,12" fill="rgb(52, 211, 153)" opacity="0.4" />
-        </svg>
+        <div className="w-0.5 h-20 rounded-full animate-[flowDown_9s_linear_infinite] [animation-fill-mode:backwards]"
+             style={{ background: "linear-gradient(to bottom, transparent, var(--border), transparent)" }} />
       </div>
-
-      {/* Flow column 2 */}
       <div className="absolute right-[150px] top-0">
-        <div className="w-1 h-16 bg-gradient-to-b from-transparent via-emerald-400/40 to-transparent rounded-full animate-[flowDown_7s_linear_infinite_2s] [animation-fill-mode:backwards]" />
-        <svg className="absolute w-5 h-5 animate-[flowDown_10s_linear_infinite] [animation-fill-mode:backwards]" viewBox="0 0 16 16">
-          <polygon points="8,0 16,16 0,16" fill="none" stroke="rgb(52, 211, 153)" strokeWidth="1.5" opacity="0.5" />
-        </svg>
-        <div className="absolute w-3 h-3 bg-emerald-400/30 animate-[flowDown_15s_linear_infinite_4s] [animation-fill-mode:backwards]" />
+        <div className="w-0.5 h-16 rounded-full animate-[flowDown_7s_linear_infinite_2s] [animation-fill-mode:backwards]"
+             style={{ background: "linear-gradient(to bottom, transparent, var(--border), transparent)" }} />
       </div>
-
-      {/* Flow column 3 */}
       <div className="absolute right-[80px] top-0">
-        <div className="w-1 h-[70px] bg-gradient-to-b from-transparent via-emerald-400/40 to-transparent rounded-full animate-[flowDown_11s_linear_infinite_4s] [animation-fill-mode:backwards]" />
-        <div className="absolute w-4 h-4 border-[1.5px] border-emerald-400/50 animate-[flowDown_14s_linear_infinite_3s] [animation-fill-mode:backwards]" />
-        <svg className="absolute w-4 h-4 animate-[flowDown_18s_linear_infinite_2s] [animation-fill-mode:backwards]" viewBox="0 0 12 12">
-          <polygon points="6,0 12,12 0,12" fill="none" stroke="rgb(52, 211, 153)" strokeWidth="1.5" opacity="0.4" />
-        </svg>
+        <div className="w-0.5 h-[70px] rounded-full animate-[flowDown_11s_linear_infinite_4s] [animation-fill-mode:backwards]"
+             style={{ background: "linear-gradient(to bottom, transparent, var(--border), transparent)" }} />
       </div>
 
-      {/* GainForest logo - appears every 30s */}
+      {/* Hypercerts logo flow - appears every 30s */}
       {showLogo && (
-        <div className="absolute right-[140px] top-0 animate-[flowDownLogo_8s_ease-in-out_forwards]">
-          <svg 
-            className="w-10 h-10 opacity-40" 
-            viewBox="0 0 200 200" 
-            fill="none"
-          >
-            <path 
-              fill="#34d399" 
-              d="M108.186920,157.196320 
-                C118.768028,146.561264 129.156982,136.234772 139.404739,125.769997 
-                C150.157120,114.789909 152.155594,97.886940 144.131287,83.621307 
-                C138.375931,89.289230 132.819656,94.910568 127.099205,100.359543 
-                C118.552223,108.500908 108.333878,110.164650 98.189201,105.083656 
-                C96.006401,103.990395 94.086143,102.372932 92.418434,101.248711 
-                C110.258148,83.349327 127.828522,65.720184 145.423294,48.066566 
-                C181.375259,75.208214 182.268341,118.425926 156.024506,144.623352 
-                C137.644089,162.971252 119.186386,181.241745 99.898994,200.405502 
-                C95.099167,195.322769 90.324440,190.069946 85.339081,185.025314 
-                C71.875595,171.401749 58.280392,157.908356 44.814175,144.287445 
-                C21.163662,120.365242 21.230278,82.262932 44.945442,58.452305 
-                C62.106354,41.222309 79.317841,24.042683 96.515533,6.849345 
-                C97.795906,5.569302 99.146828,4.359818 100.760529,2.838964 
-                C109.526825,11.915108 118.168358,20.862080 126.476990,29.464386 
-                C121.129425,35.018162 115.522278,40.841518 109.320015,47.282944 
-                C106.720047,44.115860 104.101326,40.925930 101.008034,37.157913 
-                C87.763069,50.551346 75.358055,63.057655 62.996449,75.606720 
-                C51.793400,86.979660 48.934738,102.634224 55.802773,117.020897 
-                C57.558064,120.697754 60.168159,124.150711 63.023388,127.086090 
-                C74.750366,139.142258 86.720108,150.962357 98.616280,162.853561 
-                C99.181381,163.418427 99.896935,163.832779 101.470276,165.013596 
-                C103.633583,162.479706 105.783142,159.961914 108.186920,157.196320z"
-            />
-          </svg>
+        <div className="absolute right-[140px] top-0 animate-[flowDownLogo_8s_ease-in-out_forwards] opacity-20">
+          {/* eslint-disable-next-line @next/next/no-img-element */}
+          <img src="/hypercerts_logo.png" alt="" width={40} height={40} className="opacity-40" />
         </div>
       )}
 
@@ -101,20 +55,10 @@ export function GeometricBackground() {
           100% { transform: translateY(100vh); }
         }
         @keyframes flowDownLogo {
-          0% { 
-            transform: translateY(-60px); 
-            opacity: 0;
-          }
-          10% {
-            opacity: 1;
-          }
-          90% {
-            opacity: 1;
-          }
-          100% { 
-            transform: translateY(100vh); 
-            opacity: 0;
-          }
+          0% { transform: translateY(-60px); opacity: 0; }
+          10% { opacity: 1; }
+          90% { opacity: 1; }
+          100% { transform: translateY(100vh); opacity: 0; }
         }
       `}</style>
     </div>
diff --git a/client/src/components/layout/Header.tsx b/client/src/components/layout/Header.tsx
index e339685..00552ea 100644
--- a/client/src/components/layout/Header.tsx
+++ b/client/src/components/layout/Header.tsx
@@ -5,6 +5,7 @@ import Link from 'next/link'
 import Image from 'next/image'
 import { usePathname } from 'next/navigation'
 import { useAuth } from '@/lib/auth'
+import { ThemeToggle } from '@/components/ThemeToggle'
 
 const navLinks = [
   { href: '/', label: 'Dashboard' },
@@ -60,44 +61,48 @@ export function Header() {
 
   return (
     <>
-      <nav className="relative z-10 py-6">
-        <div className="max-w-3xl mx-auto px-4 sm:px-6">
-          <div className="flex items-center">
-            {/* Logo */}
-            <Link href="/" className="flex items-center gap-2.5">
-              <Image
-                src="/logo.png"
-                alt="Hyperindex"
-                width={20}
-                height={20}
-                className="opacity-80"
-              />
-              <span className="text-lg font-medium text-zinc-800 tracking-tight">
-                hi
-              </span>
-            </Link>
+      <nav className="sticky top-0 z-50 glass-panel border-b" style={{ borderColor: 'var(--border)' }}>
+        <div className="h-16 max-w-3xl mx-auto px-4 sm:px-6 flex items-center">
+          {/* Logo */}
+          <Link href="/" className="flex items-center gap-2.5">
+            <Image
+              src="/hypercerts_logo.png"
+              alt="Hyperindex"
+              width={22}
+              height={22}
+            />
+            <span
+              className="text-lg font-[family-name:var(--font-syne)] font-bold tracking-tight"
+              style={{ color: 'var(--foreground)' }}
+            >
+              Hyperindex
+            </span>
+          </Link>
 
-            {/* Nav Links */}
-            <div className="hidden sm:flex items-center gap-1 ml-8">
-              {navLinks.map(({ href, label }) => (
-                <Link
-                  key={href}
-                  href={href}
-                  className={`px-3 py-1.5 text-sm rounded-lg transition-colors ${
-                    isActive(href)
-                      ? 'text-zinc-900 font-medium'
-                      : 'text-zinc-400 hover:text-zinc-600'
-                  }`}
-                >
-                  {label}
-                </Link>
-              ))}
-            </div>
+          {/* Nav Links */}
+          <div className="hidden sm:flex items-center gap-1 ml-8">
+            {navLinks.map(({ href, label }) => (
+              <Link
+                key={href}
+                href={href}
+                className={`px-3 py-1.5 text-sm rounded-lg transition-colors font-[family-name:var(--font-outfit)] ${
+                  isActive(href) ? 'font-medium' : ''
+                }`}
+                style={{ color: isActive(href) ? 'var(--foreground)' : 'var(--muted-foreground)' }}
+              >
+                {label}
+              </Link>
+            ))}
+          </div>
 
-            {/* Right side - User menu */}
-            <div className="relative ml-auto" ref={dropdownRef}>
+          {/* Right side */}
+          <div className="flex items-center gap-2 ml-auto">
+            <ThemeToggle />
+
+            {/* User menu */}
+            <div className="relative" ref={dropdownRef}>
               {isLoading ? (
-                <div className="w-8 h-8 rounded-full bg-zinc-100 animate-pulse" />
+                <div className="w-8 h-8 rounded-full animate-pulse" style={{ backgroundColor: 'var(--accent)' }} />
               ) : (
                 <button
                   onClick={() => setShowDropdown(!showDropdown)}
@@ -113,12 +118,18 @@ export function Header() {
                         className="rounded-full"
                       />
                     ) : (
-                      <div className="w-[30px] h-[30px] rounded-full bg-emerald-100 flex items-center justify-center text-sm font-medium text-emerald-700">
+                      <div
+                        className="w-[30px] h-[30px] rounded-full flex items-center justify-center text-sm font-[family-name:var(--font-syne)] font-semibold"
+                        style={{ backgroundColor: 'var(--accent)', color: 'var(--accent-foreground)' }}
+                      >
                         {(session.displayName || session.handle).charAt(0).toUpperCase()}
                       </div>
                     )
                   ) : (
-                    <span className="text-sm text-zinc-400 hover:text-zinc-600 transition-colors">
+                    <span
+                      className="text-sm transition-colors"
+                      style={{ color: 'var(--muted-foreground)' }}
+                    >
                       Sign in
                     </span>
                   )}
@@ -127,31 +138,31 @@ export function Header() {
 
               {/* Dropdown Menu */}
               {showDropdown && (
-                <div className="absolute right-0 top-full mt-2 w-48 bg-white rounded-xl shadow-lg border border-zinc-200/60 py-2 z-50">
+                <div
+                  className="absolute right-0 top-full mt-2 w-48 glass-panel rounded-xl shadow-lg py-2 z-50"
+                  style={{ borderColor: 'var(--border)' }}
+                >
                   {/* User info (if authenticated) */}
                   {isAuthenticated && session && (
-                    <div className="px-4 py-2 border-b border-zinc-100 mb-1">
-                      <p className="text-sm font-medium text-zinc-800 truncate">
+                    <div className="px-4 py-2 mb-1" style={{ borderBottom: '1px solid var(--border)' }}>
+                      <p className="text-sm font-medium truncate" style={{ color: 'var(--foreground)' }}>
                         {session.displayName || session.handle}
                       </p>
-                      <p className="text-xs text-zinc-400 truncate">
+                      <p className="text-xs truncate" style={{ color: 'var(--muted-foreground)' }}>
                         @{session.handle}
                       </p>
                     </div>
                   )}
 
                   {/* Mobile nav (only show on small screens) */}
-                  <div className="sm:hidden py-1 border-b border-zinc-100 mb-1">
+                  <div className="sm:hidden py-1 mb-1" style={{ borderBottom: '1px solid var(--border)' }}>
                     {navLinks.map(({ href, label }) => (
                       <Link
                         key={href}
                         href={href}
                         onClick={() => setShowDropdown(false)}
-                        className={`block px-4 py-2 text-sm transition-colors ${
-                          isActive(href)
-                            ? 'text-emerald-600 bg-emerald-50/50'
-                            : 'text-zinc-600 hover:bg-zinc-50'
-                        }`}
+                        className="block px-4 py-2 text-sm transition-colors"
+                        style={{ color: isActive(href) ? 'var(--primary)' : 'var(--foreground)' }}
                       >
                         {label}
                       </Link>
@@ -163,11 +174,8 @@ export function Header() {
                     <Link
                       href="/settings"
                       onClick={() => setShowDropdown(false)}
-                      className={`block px-4 py-2 text-sm transition-colors ${
-                        isActive('/settings')
-                          ? 'text-emerald-600 bg-emerald-50/50'
-                          : 'text-zinc-600 hover:bg-zinc-50'
-                      }`}
+                      className="block px-4 py-2 text-sm transition-colors"
+                      style={{ color: isActive('/settings') ? 'var(--primary)' : 'var(--foreground)' }}
                     >
                       Settings
                     </Link>
@@ -176,21 +184,23 @@ export function Header() {
                       target="_blank"
                       rel="noopener noreferrer"
                       onClick={() => setShowDropdown(false)}
-                      className="flex items-center justify-between px-4 py-2 text-sm text-zinc-600 hover:bg-zinc-50 transition-colors"
+                      className="flex items-center justify-between px-4 py-2 text-sm transition-colors"
+                      style={{ color: 'var(--foreground)' }}
                     >
                       GraphiQL
-                      <svg className="w-3 h-3 text-zinc-300" fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
+                      <svg className="w-3 h-3" style={{ color: 'var(--muted-foreground)' }} fill="none" viewBox="0 0 24 24" strokeWidth={2} stroke="currentColor">
                         <path strokeLinecap="round" strokeLinejoin="round" d="m4.5 19.5 15-15m0 0H8.25m11.25 0v11.25" />
                       </svg>
                     </a>
                   </div>
 
                   {/* Auth action */}
-                  <div className="border-t border-zinc-100 mt-1 pt-1">
+                  <div className="mt-1 pt-1" style={{ borderTop: '1px solid var(--border)' }}>
                     {isAuthenticated ? (
                       <button
                         onClick={handleLogout}
-                        className="block w-full text-left px-4 py-2 text-sm text-zinc-500 hover:text-zinc-700 hover:bg-zinc-50 transition-colors"
+                        className="block w-full text-left px-4 py-2 text-sm transition-colors"
+                        style={{ color: 'var(--muted-foreground)' }}
                       >
                         Sign out
                       </button>
@@ -200,7 +210,8 @@ export function Header() {
                           setShowDropdown(false)
                           setShowLoginModal(true)
                         }}
-                        className="block w-full text-left px-4 py-2 text-sm text-emerald-600 hover:bg-emerald-50/50 transition-colors"
+                        className="block w-full text-left px-4 py-2 text-sm transition-colors"
+                        style={{ color: 'var(--primary)' }}
                       >
                         Sign in
                       </button>
@@ -221,18 +232,25 @@ export function Header() {
         >
           <div className="absolute inset-0 bg-black/20 backdrop-blur-sm" />
           <div
-            className="relative w-full max-w-sm mx-4 bg-white rounded-xl shadow-lg border border-zinc-200/60 p-6"
+            className="relative w-full max-w-sm mx-4 glass-panel rounded-xl shadow-lg p-6"
             onClick={(e) => e.stopPropagation()}
           >
-            <h2 className="font-[family-name:var(--font-garamond)] text-xl text-zinc-900 mb-1">
+            <h2
+              className="font-[family-name:var(--font-syne)] text-xl mb-1"
+              style={{ color: 'var(--foreground)' }}
+            >
               Sign in with ATProto
             </h2>
-            <p className="text-sm text-zinc-400 mb-5">
+            <p className="text-sm mb-5" style={{ color: 'var(--muted-foreground)' }}>
               Enter your Bluesky handle to connect.
             </p>
 
             <form onSubmit={handleLogin}>
-              <label htmlFor="auth-handle" className="block text-sm text-zinc-600 mb-1.5">
+              <label
+                htmlFor="auth-handle"
+                className="block text-sm mb-1.5"
+                style={{ color: 'var(--foreground)' }}
+              >
                 Handle
               </label>
               <input
@@ -243,12 +261,16 @@ export function Header() {
                 placeholder="alice.bsky.social"
                 disabled={isSubmitting}
                 autoFocus
-                className="w-full px-3 py-2 text-sm bg-white border border-zinc-200/60 rounded-lg
-                           placeholder:text-zinc-300
-                           focus:outline-none focus:ring-2 focus:ring-emerald-500/30 focus:border-emerald-400
+                className="w-full px-3 py-2 text-sm rounded-lg
+                           focus:outline-none focus:ring-2
                            disabled:opacity-50 disabled:cursor-not-allowed"
+                style={{
+                  backgroundColor: 'var(--background)',
+                  border: '1px solid var(--border)',
+                  color: 'var(--foreground)',
+                }}
               />
-              <p className="text-xs text-zinc-300 mt-1.5">
+              <p className="text-xs mt-1.5" style={{ color: 'var(--muted-foreground)' }}>
                 Just a username? We&apos;ll add .bsky.social for you.
               </p>
 
@@ -261,18 +283,24 @@ export function Header() {
                   type="button"
                   onClick={() => setShowLoginModal(false)}
                   disabled={isSubmitting}
-                  className="flex-1 px-3 py-2 text-sm text-zinc-600 bg-zinc-50 rounded-lg
-                             hover:bg-zinc-100 transition-colors
+                  className="flex-1 px-3 py-2 text-sm rounded-lg transition-colors
                              disabled:opacity-50 disabled:cursor-not-allowed"
+                  style={{
+                    backgroundColor: 'var(--secondary)',
+                    color: 'var(--secondary-foreground)',
+                  }}
                 >
                   Cancel
                 </button>
                 <button
                   type="submit"
                   disabled={isSubmitting || !handle.trim()}
-                  className="flex-1 px-3 py-2 text-sm text-white bg-emerald-600 rounded-lg
-                             hover:bg-emerald-700 transition-colors
+                  className="flex-1 px-3 py-2 text-sm rounded-lg transition-colors
                              disabled:opacity-50 disabled:cursor-not-allowed"
+                  style={{
+                    backgroundColor: 'var(--primary)',
+                    color: 'var(--primary-foreground)',
+                  }}
                 >
                   {isSubmitting ? 'Connecting...' : 'Connect'}
                 </button>
diff --git a/client/src/components/ui/Alert.tsx b/client/src/components/ui/Alert.tsx
index 8a533ee..c53d4bb 100644
--- a/client/src/components/ui/Alert.tsx
+++ b/client/src/components/ui/Alert.tsx
@@ -1,5 +1,5 @@
 import { cn } from "@/lib/utils";
-import { HTMLAttributes, forwardRef } from "react";
+import { CSSProperties, HTMLAttributes, forwardRef } from "react";
 
 interface AlertProps extends HTMLAttributes<HTMLDivElement> {
   variant?: "info" | "success" | "warning" | "error";
@@ -7,21 +7,21 @@ interface AlertProps extends HTMLAttributes<HTMLDivElement> {
 }
 
 const variants = {
-  info: "bg-blue-50/50 text-blue-700 border-blue-200/60",
-  success: "bg-emerald-50/50 text-emerald-700 border-emerald-200/60",
-  warning: "bg-amber-50/50 text-amber-700 border-amber-200/60",
-  error: "bg-red-50/50 text-red-700 border-red-200/60",
+  info: "border",
+  success: "border",
+  warning: "border",
+  error: "border",
 };
 
-const iconColors = {
-  info: "text-blue-400",
-  success: "text-emerald-400",
-  warning: "text-amber-400",
-  error: "text-red-400",
+const variantStyles: Record<string, CSSProperties> = {
+  info: { backgroundColor: "oklch(0.60 0.15 250 / 0.08)", color: "oklch(0.45 0.15 250)", borderColor: "oklch(0.60 0.15 250 / 0.2)" },
+  success: { backgroundColor: "oklch(0.65 0.15 155 / 0.08)", color: "oklch(0.45 0.15 155)", borderColor: "oklch(0.65 0.15 155 / 0.2)" },
+  warning: { backgroundColor: "oklch(0.75 0.15 75 / 0.08)", color: "oklch(0.55 0.15 75)", borderColor: "oklch(0.75 0.15 75 / 0.2)" },
+  error: { backgroundColor: "oklch(0.60 0.20 25 / 0.08)", color: "oklch(0.50 0.20 25)", borderColor: "oklch(0.60 0.20 25 / 0.2)" },
 };
 
 export const Alert = forwardRef<HTMLDivElement, AlertProps>(
-  ({ className, variant = "info", children, onClose, ...props }, ref) => {
+  ({ className, variant = "info", children, onClose, style, ...props }, ref) => {
     return (
       <div
         ref={ref}
@@ -31,10 +31,11 @@ export const Alert = forwardRef<HTMLDivElement, AlertProps>(
           variants[variant],
           className
         )}
+        style={{ ...variantStyles[variant], ...style }}
         {...props}
       >
         <svg
-          className={cn("h-5 w-5 flex-shrink-0", iconColors[variant])}
+          className="h-5 w-5 flex-shrink-0"
           fill="none"
           viewBox="0 0 24 24"
           strokeWidth={1.5}
diff --git a/client/src/components/ui/Button.tsx b/client/src/components/ui/Button.tsx
index b5c8e6b..eac2855 100644
--- a/client/src/components/ui/Button.tsx
+++ b/client/src/components/ui/Button.tsx
@@ -1,7 +1,7 @@
 "use client";
 
 import { cn } from "@/lib/utils";
-import { ButtonHTMLAttributes, forwardRef, ElementType, ComponentPropsWithoutRef } from "react";
+import { ButtonHTMLAttributes, forwardRef, ElementType, ComponentPropsWithoutRef, CSSProperties } from "react";
 
 type ButtonBaseProps = {
   variant?: "default" | "outline" | "ghost" | "destructive" | "primary";
@@ -14,11 +14,19 @@ type ButtonProps<T extends ElementType = "button"> = ButtonBaseProps &
   Omit<ComponentPropsWithoutRef<T>, keyof ButtonBaseProps>;
 
 const buttonVariants = {
-  default: "bg-zinc-900 text-white hover:bg-zinc-800",
-  primary: "bg-emerald-600 text-white hover:bg-emerald-700",
-  outline: "border border-zinc-200/60 bg-transparent text-zinc-600 hover:bg-zinc-50",
-  ghost: "bg-transparent text-zinc-600 hover:bg-zinc-50",
-  destructive: "bg-red-600 text-white hover:bg-red-700",
+  default: "",
+  primary: "",
+  outline: "border bg-transparent",
+  ghost: "bg-transparent",
+  destructive: "",
+};
+
+const variantStyles: Record<string, CSSProperties> = {
+  default: { backgroundColor: "var(--primary)", color: "var(--primary-foreground)" },
+  primary: { backgroundColor: "var(--primary)", color: "var(--primary-foreground)" },
+  outline: { borderColor: "var(--border)", color: "var(--foreground)" },
+  ghost: { color: "var(--foreground)" },
+  destructive: { backgroundColor: "var(--destructive)", color: "#fff" },
 };
 
 const buttonSizes = {
@@ -31,6 +39,7 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
   (
     {
       className,
+      style,
       variant = "default",
       size = "md",
       loading,
@@ -48,13 +57,14 @@ export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
       <Component
         ref={ref}
         className={cn(
-          "inline-flex items-center justify-center gap-2 rounded-lg font-medium transition-colors",
-          "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500/30 focus-visible:border-emerald-400",
+          "inline-flex items-center justify-center gap-2 rounded-lg font-[family-name:var(--font-outfit)] font-medium transition-colors hover:opacity-90",
+          "focus-visible:outline-none focus-visible:ring-2",
           "disabled:opacity-50 disabled:cursor-not-allowed",
           buttonVariants[variant],
           buttonSizes[size],
           className
         )}
+        style={{ ...variantStyles[variant], outline: "var(--ring)", ...style }}
         {...(isButton ? { disabled: disabled || loading } : {})}
         {...props}
       >
diff --git a/client/src/components/ui/Card.tsx b/client/src/components/ui/Card.tsx
index 21e49f6..e305d6d 100644
--- a/client/src/components/ui/Card.tsx
+++ b/client/src/components/ui/Card.tsx
@@ -4,13 +4,11 @@ import { HTMLAttributes, forwardRef } from "react";
 interface CardProps extends HTMLAttributes<HTMLDivElement> {}
 
 export const Card = forwardRef<HTMLDivElement, CardProps>(
-  ({ className, ...props }, ref) => (
+  ({ className, style, ...props }, ref) => (
     <div
       ref={ref}
-      className={cn(
-        "rounded-xl border border-zinc-200/60 bg-white shadow-sm",
-        className
-      )}
+      className={cn("rounded-xl border shadow-sm", className)}
+      style={{ backgroundColor: "var(--card)", borderColor: "var(--border)", color: "var(--card-foreground)", ...style }}
       {...props}
     />
   )
@@ -29,13 +27,14 @@ export const CardHeader = forwardRef<HTMLDivElement, CardProps>(
 CardHeader.displayName = "CardHeader";
 
 export const CardTitle = forwardRef<HTMLHeadingElement, HTMLAttributes<HTMLHeadingElement>>(
-  ({ className, ...props }, ref) => (
+  ({ className, style, ...props }, ref) => (
     <h3
       ref={ref}
       className={cn(
-        "font-[family-name:var(--font-garamond)] text-xl text-zinc-900 leading-none tracking-tight",
+        "font-[family-name:var(--font-syne)] text-xl leading-none tracking-tight",
         className
       )}
+      style={{ color: "var(--card-foreground)", ...style }}
       {...props}
     />
   )
@@ -43,10 +42,11 @@ export const CardTitle = forwardRef<HTMLHeadingElement, HTMLAttributes<HTMLHeadi
 CardTitle.displayName = "CardTitle";
 
 export const CardDescription = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
-  ({ className, ...props }, ref) => (
+  ({ className, style, ...props }, ref) => (
     <p
       ref={ref}
-      className={cn("text-sm text-zinc-400", className)}
+      className={cn("text-sm", className)}
+      style={{ color: "var(--muted-foreground)", ...style }}
       {...props}
     />
   )
diff --git a/client/src/components/ui/Input.tsx b/client/src/components/ui/Input.tsx
index 2c9bab6..3081265 100644
--- a/client/src/components/ui/Input.tsx
+++ b/client/src/components/ui/Input.tsx
@@ -10,13 +10,14 @@ interface InputProps extends InputHTMLAttributes<HTMLInputElement> {
 }
 
 export const Input = forwardRef<HTMLInputElement, InputProps>(
-  ({ className, label, error, hint, id, ...props }, ref) => {
+  ({ className, label, error, hint, id, style, ...props }, ref) => {
     return (
       <div className="space-y-1.5">
         {label && (
           <label
             htmlFor={id}
-            className="block text-sm text-zinc-600"
+            className="block text-sm"
+            style={{ color: "var(--foreground)" }}
           >
             {label}
           </label>
@@ -25,18 +26,20 @@ export const Input = forwardRef<HTMLInputElement, InputProps>(
           id={id}
           ref={ref}
           className={cn(
-            "w-full px-3 py-2 text-sm bg-white/50 border border-zinc-200/60 rounded-lg",
-            "text-zinc-800 placeholder:text-zinc-300",
-            "focus:outline-none focus:ring-2 focus:ring-emerald-500/30 focus:border-emerald-400",
-            "focus:bg-white/70 transition-all",
+            "w-full px-3 py-2 text-sm border rounded-lg focus:outline-none focus:ring-2 transition-all",
             "disabled:opacity-50 disabled:cursor-not-allowed",
-            error && "border-red-400 focus:ring-red-500/30 focus:border-red-400",
             className
           )}
+          style={{
+            backgroundColor: "var(--card)",
+            borderColor: error ? "var(--destructive)" : "var(--input)",
+            color: "var(--foreground)",
+            ...style,
+          }}
           {...props}
         />
         {hint && !error && (
-          <p className="text-xs text-zinc-300">{hint}</p>
+          <p className="text-xs" style={{ color: "var(--muted-foreground)" }}>{hint}</p>
         )}
         {error && (
           <p className="text-sm text-red-500">{error}</p>
diff --git a/client/src/lib/env.ts b/client/src/lib/env.ts
index 7062c70..cd5be9f 100644
--- a/client/src/lib/env.ts
+++ b/client/src/lib/env.ts
@@ -25,6 +25,6 @@ export const env = {
   // Private JWK for confidential OAuth client (optional, for production)
   ATPROTO_JWK_PRIVATE: getEnv("ATPROTO_JWK_PRIVATE", ""),
   
-  // Hypergoat backend URL
-  HYPERGOAT_URL: getEnv("HYPERGOAT_URL", "http://127.0.0.1:8080"),
+  // Hyperindex backend URL
+  HYPERINDEX_URL: getEnv("HYPERINDEX_URL", getEnv("HYPERGOAT_URL", "http://127.0.0.1:8080")),
 };
diff --git a/client/src/lib/graphql/client.ts b/client/src/lib/graphql/client.ts
index 24e558c..4e59756 100644
--- a/client/src/lib/graphql/client.ts
+++ b/client/src/lib/graphql/client.ts
@@ -10,9 +10,9 @@ function getBaseUrl(): string {
   return "http://127.0.0.1:3000";
 }
 
-// Get Hypergoat URL for direct backend access (public API)
-function getHypergoatUrl(): string {
-  return process.env.HYPERGOAT_URL || "http://127.0.0.1:8080";
+// Get Hyperindex URL for direct backend access (public API)
+function getHyperindexUrl(): string {
+  return process.env.HYPERINDEX_URL || process.env.HYPERGOAT_URL || "http://127.0.0.1:8080";
 }
 
 // Lazy-initialized clients to ensure proper URL detection after hydration
@@ -35,15 +35,15 @@ export const graphqlClient = {
 };
 
 /**
- * Public GraphQL client - direct to Hypergoat for unauthenticated queries
+ * Public GraphQL client - direct to Hyperindex for unauthenticated queries
  */
 export const publicGraphqlClient = {
   request: <T>(document: string, variables?: Record<string, unknown>): Promise<T> => {
     if (!_publicGraphqlClient) {
-      // For SSR, go directly to Hypergoat; for client, use proxy
+      // For SSR, go directly to Hyperindex; for client, use proxy
       const url = typeof window !== "undefined" 
         ? `${getBaseUrl()}/api/graphql`
-        : `${getHypergoatUrl()}/graphql`;
+        : `${getHyperindexUrl()}/graphql`;
       _publicGraphqlClient = new GraphQLClient(url, {
         credentials: "include",
       });
diff --git a/cmd/hypergoat/main.go b/cmd/hypergoat/main.go
index 63c0151..577e0b4 100644
--- a/cmd/hypergoat/main.go
+++ b/cmd/hypergoat/main.go
@@ -11,6 +11,7 @@ import (
 	"context"
 	"encoding/json"
 	"errors"
+	"fmt"
 	"log/slog"
 	"net/http"
 	"os"
@@ -37,6 +38,7 @@ import (
 	"github.com/GainForest/hypergoat/internal/lexicon"
 	"github.com/GainForest/hypergoat/internal/oauth"
 	"github.com/GainForest/hypergoat/internal/server"
+	"github.com/GainForest/hypergoat/internal/tap"
 	"github.com/GainForest/hypergoat/internal/workers"
 )
 
@@ -70,6 +72,9 @@ type backgroundServices struct {
 	workersCancel      context.CancelFunc
 	jsConsumer         *jetstream.Consumer
 	jsCancel           context.CancelFunc
+	tapConsumer        *tap.Consumer
+	tapCancel          context.CancelFunc
+	tapAdminClient     *tap.AdminClient // reused for health checks; nil when TAP_ENABLED=false
 }
 
 // Stop cleanly shuts down all background services.
@@ -86,6 +91,12 @@ func (bg *backgroundServices) Stop() {
 	if bg.jsCancel != nil {
 		bg.jsCancel()
 	}
+	if bg.tapConsumer != nil {
+		bg.tapConsumer.Stop()
+	}
+	if bg.tapCancel != nil {
+		bg.tapCancel()
+	}
 }
 
 func run() error {
@@ -95,7 +106,7 @@ func run() error {
 	}))
 	slog.SetDefault(logger)
 
-	slog.Info("Starting Hypergoat - AT Protocol AppView Server")
+	slog.Info("Starting Hyperindex - AT Protocol AppView Server")
 
 	// Load and validate configuration
 	cfg, err := config.Load()
@@ -114,13 +125,13 @@ func run() error {
 	}
 	defer svc.db.Close()
 
-	// Set up HTTP router with middleware and basic endpoints
-	r := setupRouter(cfg, svc)
-
 	// Track background services for clean shutdown
 	bg := &backgroundServices{}
 	defer bg.Stop()
 
+	// Set up HTTP router with middleware and basic endpoints
+	r := setupRouter(cfg, svc, bg)
+
 	// Set up OAuth endpoints
 	setupOAuth(r, cfg, svc, bg)
 
@@ -134,11 +145,16 @@ func run() error {
 	// Start background workers (activity cleanup)
 	startWorkers(svc, bg)
 
-	// Start Jetstream consumer for real-time events
-	startJetstream(cfg, svc, pubsub, collections, adminHandler, bg)
+	if cfg.TapEnabled {
+		// Start Tap consumer instead of Jetstream+Backfill
+		startTap(cfg, svc, pubsub, adminHandler, bg)
+	} else {
+		// Start Jetstream consumer for real-time events
+		startJetstream(cfg, svc, pubsub, collections, adminHandler, bg)
 
-	// Start backfill if configured
-	startBackfill(cfg, svc)
+		// Start backfill if configured
+		startBackfill(cfg, svc)
+	}
 
 	// Run HTTP server with graceful shutdown
 	return serve(r, cfg, bg)
@@ -233,7 +249,9 @@ func populateActivityIfEmpty(ctx context.Context, svc *services) {
 
 // setupRouter creates the chi router with middleware and basic HTTP endpoints
 // (health, stats, root info, XRPC placeholder).
-func setupRouter(cfg *config.Config, svc *services) *chi.Mux {
+// bg is passed so that health/stats handlers can access the Tap admin client
+// once it is wired up by startTap (after setupRouter returns).
+func setupRouter(cfg *config.Config, svc *services, bg *backgroundServices) *chi.Mux {
 	r := chi.NewRouter()
 
 	// Middleware
@@ -259,6 +277,25 @@ func setupRouter(cfg *config.Config, svc *services) *chi.Mux {
 	r.Get("/health", func(w http.ResponseWriter, req *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusOK)
+
+		if cfg.TapEnabled && bg.tapAdminClient != nil {
+			if err := bg.tapAdminClient.Health(req.Context()); err != nil {
+				_ = json.NewEncoder(w).Encode(map[string]any{
+					"status": "degraded",
+					"tap":    "unreachable",
+					"error":  err.Error(),
+					"time":   time.Now().UTC().Format(time.RFC3339),
+				})
+				return
+			}
+			_ = json.NewEncoder(w).Encode(map[string]any{
+				"status": "ok",
+				"tap":    "ok",
+				"time":   time.Now().UTC().Format(time.RFC3339),
+			})
+			return
+		}
+
 		_ = json.NewEncoder(w).Encode(map[string]string{
 			"status": "healthy",
 			"time":   time.Now().UTC().Format(time.RFC3339),
@@ -287,20 +324,34 @@ func setupRouter(cfg *config.Config, svc *services) *chi.Mux {
 			lexiconCount = -1
 		}
 
-		w.Header().Set("Content-Type", "application/json")
-		_ = json.NewEncoder(w).Encode(map[string]any{
+		stats := map[string]any{
 			"records":  recordCount,
 			"actors":   actorCount,
 			"lexicons": lexiconCount,
 			"time":     time.Now().UTC().Format(time.RFC3339),
-		})
+		}
+
+		if cfg.TapEnabled && bg.tapConsumer != nil {
+			tapStats := bg.tapConsumer.Stats()
+			stats["tap"] = map[string]any{
+				"events_received": tapStats.EventsReceived,
+				"records_created": tapStats.RecordsCreated,
+				"records_updated": tapStats.RecordsUpdated,
+				"records_deleted": tapStats.RecordsDeleted,
+				"identity_events": tapStats.IdentityEvents,
+				"errors":          tapStats.Errors,
+			}
+		}
+
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(stats)
 	})
 
 	// Root endpoint - server info
 	r.Get("/", func(w http.ResponseWriter, req *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
 		_ = json.NewEncoder(w).Encode(map[string]string{
-			"name":        "Hypergoat",
+			"name":        "Hyperindex",
 			"description": "AT Protocol AppView Server",
 			"version":     "0.1.0-dev",
 			"docs":        cfg.ExternalBaseURL + "/docs",
@@ -354,7 +405,7 @@ func setupOAuth(r *chi.Mux, cfg *config.Config, svc *services, bg *backgroundSer
 	// Client metadata (this server as an OAuth client)
 	r.Get("/oauth-client-metadata.json", server.HandleClientMetadata(server.ClientMetadataConfig{
 		ExternalBaseURL: cfg.ExternalBaseURL,
-		ClientName:      "Hypergoat",
+		ClientName:      "Hyperindex",
 		Scope:           "atproto transition:generic",
 	}))
 
@@ -433,8 +484,8 @@ func setupAdmin(r *chi.Mux, cfg *config.Config, svc *services) *admin.Handler {
 	r.Get("/graphiql", server.HandleGraphiQL(server.GraphiQLConfig{
 		Endpoint:             cfg.ExternalBaseURL + "/graphql",
 		SubscriptionEndpoint: strings.Replace(cfg.ExternalBaseURL, "http", "ws", 1) + "/graphql/ws",
-		Title:                "Hypergoat GraphQL",
-		DefaultQuery: `# Hypergoat GraphQL API
+		Title:                "Hyperindex GraphQL",
+		DefaultQuery: `# Hyperindex GraphQL API
 # 
 # Explore the AT Protocol data indexed by this AppView.
 # Try querying for records from your configured lexicons.
@@ -452,8 +503,8 @@ func setupAdmin(r *chi.Mux, cfg *config.Config, svc *services) *admin.Handler {
 
 	r.Get("/graphiql/admin", server.HandleGraphiQL(server.GraphiQLConfig{
 		Endpoint: cfg.ExternalBaseURL + "/admin/graphql",
-		Title:    "Hypergoat Admin",
-		DefaultQuery: `# Hypergoat Admin API
+		Title:    "Hyperindex Admin",
+		DefaultQuery: `# Hyperindex Admin API
 #
 # Administrative operations for managing the AppView.
 # Note: Some operations require authentication.
@@ -739,6 +790,58 @@ func startBackfill(cfg *config.Config, svc *services) {
 	}()
 }
 
+// startTap creates and starts the Tap consumer as a replacement for Jetstream+Backfill.
+// It also wires admin backfill callbacks to use Tap's /repos/add HTTP API.
+func startTap(
+	cfg *config.Config,
+	svc *services,
+	pubsub *subscription.PubSub,
+	adminHandler *admin.Handler,
+	bg *backgroundServices,
+) {
+	tapURL := cfg.TapURL
+
+	// Create handler that stores records and publishes to subscriptions.
+	handler := tap.NewIndexHandler(svc.records, svc.actors, svc.activity, pubsub)
+
+	// Create consumer.
+	consumer := tap.NewConsumer(tap.ConsumerConfig{
+		TapURL:      tapURL,
+		DisableAcks: cfg.TapDisableAcks,
+	}, handler)
+
+	// Store consumer reference for clean shutdown.
+	bg.tapConsumer = consumer
+
+	tapCtx, tapCancel := context.WithCancel(context.Background())
+	bg.tapCancel = tapCancel
+
+	go func() {
+		slog.Info("Starting Tap consumer", "url", tapURL, "disable_acks", cfg.TapDisableAcks)
+		if err := consumer.Start(tapCtx); err != nil {
+			slog.Error("Tap consumer error", "error", err)
+		}
+	}()
+
+	// Create a shared admin client for health checks and backfill callbacks.
+	tapHTTPURL := strings.Replace(strings.Replace(tapURL, "ws://", "http://", 1), "wss://", "https://", 1)
+	adminClient := tap.NewAdminClient(tapHTTPURL, cfg.TapAdminPassword)
+	bg.tapAdminClient = adminClient
+
+	// Wire admin backfill callbacks to use Tap's /repos/add API.
+	if adminHandler != nil {
+		adminHandler.Resolver().SetBackfillCallback(func(ctx context.Context, did string) error {
+			return adminClient.AddRepos(ctx, []string{did})
+		})
+
+		adminHandler.Resolver().SetFullBackfillCallback(func(_ context.Context) error {
+			return fmt.Errorf("full network backfill not supported via Tap admin API — configure TAP_SIGNAL_COLLECTION or TAP_FULL_NETWORK on the Tap sidecar instead")
+		})
+	}
+
+	slog.Info("Tap consumer started (replaces Jetstream + Backfill)")
+}
+
 // serve starts the HTTP server and blocks until a shutdown signal is received,
 // then performs a graceful shutdown with a 30-second timeout.
 func serve(r *chi.Mux, cfg *config.Config, bg *backgroundServices) error {
diff --git a/docker-compose.postgres.yml b/docker-compose.postgres.yml
index 4b04ba8..e53b662 100644
--- a/docker-compose.postgres.yml
+++ b/docker-compose.postgres.yml
@@ -9,7 +9,7 @@ services:
       - HOST=0.0.0.0
       - PORT=8080
       - DATABASE_URL=postgres://hypergoat:hypergoat@postgres:5432/hypergoat?sslmode=disable
-      - SECRET_KEY_BASE=${SECRET_KEY_BASE:-development-secret-key-change-in-production-64chars}
+      - SECRET_KEY_BASE=${SECRET_KEY_BASE:?SECRET_KEY_BASE must be set - generate with: openssl rand -hex 32}
       - EXTERNAL_BASE_URL=${EXTERNAL_BASE_URL:-http://localhost:8080}
       - OAUTH_LOOPBACK_MODE=${OAUTH_LOOPBACK_MODE:-true}
     depends_on:
diff --git a/docker-compose.tap.yml b/docker-compose.tap.yml
new file mode 100644
index 0000000..c4e6dd2
--- /dev/null
+++ b/docker-compose.tap.yml
@@ -0,0 +1,41 @@
+version: "3.8"
+
+services:
+  tap:
+    image: ghcr.io/bluesky-social/indigo/tap:latest
+    ports:
+      - "127.0.0.1:2480:2480"
+    volumes:
+      - tap-data:/data
+    environment:
+      TAP_DATABASE_URL: "sqlite:///data/tap.db"
+      TAP_COLLECTION_FILTERS: "${JETSTREAM_COLLECTIONS}"
+      TAP_SIGNAL_COLLECTION: "${TAP_SIGNAL_COLLECTION:-}"
+      TAP_DISABLE_ACKS: "false"
+      TAP_ADMIN_PASSWORD: "${TAP_ADMIN_PASSWORD:?TAP_ADMIN_PASSWORD must be set}"
+    restart: unless-stopped
+
+  hyperindex:
+    build: .
+    ports:
+      - "8080:8080"
+    depends_on:
+      - tap
+    environment:
+      HOST: "0.0.0.0"
+      PORT: "8080"
+      TAP_ENABLED: "true"
+      TAP_URL: "ws://tap:2480"
+      TAP_ADMIN_PASSWORD: "${TAP_ADMIN_PASSWORD:?TAP_ADMIN_PASSWORD must be set}"
+      DATABASE_URL: "${DATABASE_URL:-sqlite:data/hypergoat.db}"
+      SECRET_KEY_BASE: "${SECRET_KEY_BASE:?SECRET_KEY_BASE must be set - generate with: openssl rand -hex 32}"
+      EXTERNAL_BASE_URL: "${EXTERNAL_BASE_URL:-http://localhost:8080}"
+      OAUTH_LOOPBACK_MODE: "${OAUTH_LOOPBACK_MODE:-true}"
+      ADMIN_DIDS: "${ADMIN_DIDS:-}"
+    volumes:
+      - hyperindex-data:/app/data
+    restart: unless-stopped
+
+volumes:
+  tap-data:
+  hyperindex-data:
diff --git a/docker-compose.yml b/docker-compose.yml
index fb31f63..bff48a3 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -9,7 +9,7 @@ services:
       - HOST=0.0.0.0
       - PORT=8080
       - DATABASE_URL=sqlite:/app/data/hypergoat.db
-      - SECRET_KEY_BASE=${SECRET_KEY_BASE:-development-secret-key-change-in-production-64chars}
+      - SECRET_KEY_BASE=${SECRET_KEY_BASE:?SECRET_KEY_BASE must be set - generate with: openssl rand -hex 32}
       - EXTERNAL_BASE_URL=${EXTERNAL_BASE_URL:-http://localhost:8080}
       - OAUTH_LOOPBACK_MODE=${OAUTH_LOOPBACK_MODE:-true}
     volumes:
diff --git a/internal/config/config.go b/internal/config/config.go
index 6dc2ab8..50228ec 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -56,6 +56,12 @@ type Config struct {
 	BackfillMaxRepos          int
 	BackfillRepoTimeoutMS     int
 
+	// Tap (replaces Jetstream + Backfill)
+	TapURL           string // Tap WebSocket URL (default: ws://localhost:2480)
+	TapAdminPassword string // Tap admin API password for Basic auth
+	TapDisableAcks   bool   // Fire-and-forget mode (default: false)
+	TapEnabled       bool   // Use Tap instead of Jetstream+Backfill (default: false)
+
 	// PLC Directory
 	PLCDirectoryURL string // PLC directory URL for DID resolution
 }
@@ -108,6 +114,12 @@ func Load() (*Config, error) {
 		BackfillMaxRepos:          getEnvInt("BACKFILL_MAX_REPOS", 50),
 		BackfillRepoTimeoutMS:     getEnvInt("BACKFILL_REPO_TIMEOUT", 60000),
 
+		// Tap
+		TapURL:           getEnv("TAP_URL", "ws://localhost:2480"),
+		TapAdminPassword: getEnv("TAP_ADMIN_PASSWORD", ""),
+		TapDisableAcks:   getEnvBool("TAP_DISABLE_ACKS", false),
+		TapEnabled:       getEnvBool("TAP_ENABLED", false),
+
 		// PLC Directory
 		PLCDirectoryURL: getEnv("PLC_DIRECTORY_URL", ""),
 	}
@@ -161,6 +173,10 @@ func (c *Config) LogConfig() {
 		"backfill_on_start", c.BackfillOnStart,
 		"trust_proxy_headers", c.TrustProxyHeaders,
 		"allowed_origins", c.AllowedOrigins,
+		"tap_enabled", c.TapEnabled,
+		"tap_url", c.TapURL,
+		"tap_admin_password_set", c.TapAdminPassword != "",
+		"tap_disable_acks", c.TapDisableAcks,
 	)
 
 	if c.TrustProxyHeaders {
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index febe8f3..c3487c6 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -329,6 +329,94 @@ func TestConfigAddress(t *testing.T) {
 	}
 }
 
+func TestTapConfigDefaults(t *testing.T) {
+	// Ensure TAP env vars are unset before testing defaults
+	for _, key := range []string{"TAP_URL", "TAP_ADMIN_PASSWORD", "TAP_DISABLE_ACKS", "TAP_ENABLED"} {
+		os.Unsetenv(key)
+	}
+
+	tapURL := getEnv("TAP_URL", "ws://localhost:2480")
+	if tapURL != "ws://localhost:2480" {
+		t.Errorf("TAP_URL default = %q, want %q", tapURL, "ws://localhost:2480")
+	}
+
+	tapAdminPassword := getEnv("TAP_ADMIN_PASSWORD", "")
+	if tapAdminPassword != "" {
+		t.Errorf("TAP_ADMIN_PASSWORD default = %q, want %q", tapAdminPassword, "")
+	}
+
+	tapDisableAcks := getEnvBool("TAP_DISABLE_ACKS", false)
+	if tapDisableAcks != false {
+		t.Errorf("TAP_DISABLE_ACKS default = %v, want false", tapDisableAcks)
+	}
+
+	tapEnabled := getEnvBool("TAP_ENABLED", false)
+	if tapEnabled != false {
+		t.Errorf("TAP_ENABLED default = %v, want false", tapEnabled)
+	}
+}
+
+func TestTapConfigEnvVars(t *testing.T) {
+	os.Setenv("TAP_URL", "ws://tap.example.com:2480")
+	os.Setenv("TAP_ADMIN_PASSWORD", "secret")
+	os.Setenv("TAP_DISABLE_ACKS", "true")
+	os.Setenv("TAP_ENABLED", "true")
+	defer func() {
+		os.Unsetenv("TAP_URL")
+		os.Unsetenv("TAP_ADMIN_PASSWORD")
+		os.Unsetenv("TAP_DISABLE_ACKS")
+		os.Unsetenv("TAP_ENABLED")
+	}()
+
+	tapURL := getEnv("TAP_URL", "ws://localhost:2480")
+	if tapURL != "ws://tap.example.com:2480" {
+		t.Errorf("TAP_URL = %q, want %q", tapURL, "ws://tap.example.com:2480")
+	}
+
+	tapAdminPassword := getEnv("TAP_ADMIN_PASSWORD", "")
+	if tapAdminPassword != "secret" {
+		t.Errorf("TAP_ADMIN_PASSWORD = %q, want %q", tapAdminPassword, "secret")
+	}
+
+	tapDisableAcks := getEnvBool("TAP_DISABLE_ACKS", false)
+	if !tapDisableAcks {
+		t.Errorf("TAP_DISABLE_ACKS = %v, want true", tapDisableAcks)
+	}
+
+	tapEnabled := getEnvBool("TAP_ENABLED", false)
+	if !tapEnabled {
+		t.Errorf("TAP_ENABLED = %v, want true", tapEnabled)
+	}
+}
+
+func TestTapConfigFields(t *testing.T) {
+	cfg := Config{
+		TapURL:           "ws://localhost:2480",
+		TapAdminPassword: "mypassword",
+		TapDisableAcks:   false,
+		TapEnabled:       true,
+	}
+
+	if cfg.TapURL != "ws://localhost:2480" {
+		t.Errorf("TapURL = %q, want %q", cfg.TapURL, "ws://localhost:2480")
+	}
+	if cfg.TapAdminPassword != "mypassword" {
+		t.Errorf("TapAdminPassword = %q, want %q", cfg.TapAdminPassword, "mypassword")
+	}
+	if cfg.TapDisableAcks != false {
+		t.Errorf("TapDisableAcks = %v, want false", cfg.TapDisableAcks)
+	}
+	if cfg.TapEnabled != true {
+		t.Errorf("TapEnabled = %v, want true", cfg.TapEnabled)
+	}
+
+	// Verify password is not directly logged (tap_admin_password_set pattern)
+	passwordSet := cfg.TapAdminPassword != ""
+	if !passwordSet {
+		t.Error("TapAdminPassword should be set but tap_admin_password_set is false")
+	}
+}
+
 func TestGenerateRandomKey(t *testing.T) {
 	tests := []struct {
 		name   string
diff --git a/internal/database/migrations/postgres/006_add_composite_index.down.sql b/internal/database/migrations/postgres/006_add_composite_index.down.sql
new file mode 100644
index 0000000..3dcfab8
--- /dev/null
+++ b/internal/database/migrations/postgres/006_add_composite_index.down.sql
@@ -0,0 +1 @@
+DROP INDEX IF EXISTS idx_record_collection_keyset;
diff --git a/internal/database/migrations/postgres/006_add_composite_index.up.sql b/internal/database/migrations/postgres/006_add_composite_index.up.sql
new file mode 100644
index 0000000..e39ec8d
--- /dev/null
+++ b/internal/database/migrations/postgres/006_add_composite_index.up.sql
@@ -0,0 +1,2 @@
+-- Composite index for keyset pagination: covers WHERE collection = ? ORDER BY indexed_at DESC, uri DESC
+CREATE INDEX IF NOT EXISTS idx_record_collection_keyset ON record(collection, indexed_at DESC, uri DESC);
diff --git a/internal/database/migrations/sqlite/006_add_composite_index.down.sql b/internal/database/migrations/sqlite/006_add_composite_index.down.sql
new file mode 100644
index 0000000..3dcfab8
--- /dev/null
+++ b/internal/database/migrations/sqlite/006_add_composite_index.down.sql
@@ -0,0 +1 @@
+DROP INDEX IF EXISTS idx_record_collection_keyset;
diff --git a/internal/database/migrations/sqlite/006_add_composite_index.up.sql b/internal/database/migrations/sqlite/006_add_composite_index.up.sql
new file mode 100644
index 0000000..e39ec8d
--- /dev/null
+++ b/internal/database/migrations/sqlite/006_add_composite_index.up.sql
@@ -0,0 +1,2 @@
+-- Composite index for keyset pagination: covers WHERE collection = ? ORDER BY indexed_at DESC, uri DESC
+CREATE INDEX IF NOT EXISTS idx_record_collection_keyset ON record(collection, indexed_at DESC, uri DESC);
diff --git a/internal/database/repositories/records.go b/internal/database/repositories/records.go
index 1f696e7..58ad9d9 100644
--- a/internal/database/repositories/records.go
+++ b/internal/database/repositories/records.go
@@ -23,6 +23,18 @@ const (
 
 	// DefaultIterateBatchSize is the default batch size for IterateAll when none specified.
 	DefaultIterateBatchSize = 1000
+
+	// SearchTimeout is the maximum duration for a search query.
+	SearchTimeout = 10 * time.Second
+
+	// MaxINListSize is the maximum number of values allowed in an IN filter clause.
+	// SQLite has a hard 999 parameter limit (SQLITE_MAX_VARIABLE_NUMBER).
+	// We cap well below that to leave room for other query parameters.
+	MaxINListSize = 100
+
+	// MaxFilterConditions is the maximum number of individual filter conditions allowed per query.
+	// The DID filter does not count toward this cap.
+	MaxFilterConditions = 20
 )
 
 // Record represents an AT Protocol record stored in the database.
@@ -36,6 +48,33 @@ type Record struct {
 	RKey       string
 }
 
+// FieldFilter represents a single filter condition on a JSON field.
+type FieldFilter struct {
+	Field     string      // JSON field name (e.g., "title", "createdAt"). Must be a valid field name.
+	Operator  string      // One of: "eq", "neq", "gt", "lt", "gte", "lte", "in", "contains", "startsWith", "isNull"
+	Value     interface{} // The comparison value. For "in", must be []interface{}. For "isNull", must be bool.
+	FieldType string      // Lexicon type: "string", "integer", "number", "boolean", "datetime"
+}
+
+// DIDFilter represents a filter on the did column.
+// Only eq and in are supported (column-level filter, not JSON).
+// If both EQ and IN are set, EQ takes precedence.
+type DIDFilter struct {
+	EQ string   // Exact match (empty means no eq filter)
+	IN []string // In list (nil/empty means no in filter)
+}
+
+// IsEmpty reports whether the DIDFilter has no conditions set.
+func (d DIDFilter) IsEmpty() bool {
+	return d.EQ == "" && len(d.IN) == 0
+}
+
+// SortOption specifies a sort field and direction for record queries.
+type SortOption struct {
+	Field     string // Field name. If "indexed_at", "uri", "did", "collection", "cid", "rkey" — use column directly. Otherwise, use JSONExtract.
+	Direction string // "ASC" or "DESC"
+}
+
 // CollectionStat represents statistics for a collection.
 type CollectionStat struct {
 	Collection string
@@ -327,6 +366,491 @@ func (r *RecordsRepository) GetByCollectionWithKeysetCursor(ctx context.Context,
 	return scanRecords(rows)
 }
 
+// buildFilterClause builds a SQL WHERE clause fragment from a slice of FieldFilters.
+// startPlaceholder is the 1-based index of the first placeholder to use.
+// Returns the clause string (without leading "AND") and the parameter values.
+// Returns an empty string and nil params if filters is empty.
+func (r *RecordsRepository) buildFilterClause(filters []FieldFilter, startPlaceholder int) (string, []database.Value, error) {
+	if len(filters) == 0 {
+		return "", nil, nil
+	}
+
+	var conditions []string
+	var params []database.Value
+	placeholderIdx := startPlaceholder
+
+	for _, f := range filters {
+		extract := r.db.JSONExtract("json", f.Field)
+
+		// Wrap numeric types in a CAST for proper comparison
+		isNumeric := f.FieldType == "integer" || f.FieldType == "number"
+		if isNumeric {
+			switch r.db.Dialect() {
+			case database.PostgreSQL:
+				extract = fmt.Sprintf("(%s)::numeric", extract)
+			default:
+				extract = fmt.Sprintf("CAST(%s AS REAL)", extract)
+			}
+		}
+
+		switch f.Operator {
+		case "eq":
+			conditions = append(conditions, fmt.Sprintf("%s = %s", extract, r.db.Placeholder(placeholderIdx)))
+			params = append(params, toDBValue(f.Value))
+			placeholderIdx++
+		case "neq":
+			conditions = append(conditions, fmt.Sprintf("%s != %s", extract, r.db.Placeholder(placeholderIdx)))
+			params = append(params, toDBValue(f.Value))
+			placeholderIdx++
+		case "gt":
+			conditions = append(conditions, fmt.Sprintf("%s > %s", extract, r.db.Placeholder(placeholderIdx)))
+			params = append(params, toDBValue(f.Value))
+			placeholderIdx++
+		case "lt":
+			conditions = append(conditions, fmt.Sprintf("%s < %s", extract, r.db.Placeholder(placeholderIdx)))
+			params = append(params, toDBValue(f.Value))
+			placeholderIdx++
+		case "gte":
+			conditions = append(conditions, fmt.Sprintf("%s >= %s", extract, r.db.Placeholder(placeholderIdx)))
+			params = append(params, toDBValue(f.Value))
+			placeholderIdx++
+		case "lte":
+			conditions = append(conditions, fmt.Sprintf("%s <= %s", extract, r.db.Placeholder(placeholderIdx)))
+			params = append(params, toDBValue(f.Value))
+			placeholderIdx++
+		case "contains":
+			likeOp := "LIKE"
+			if r.db.Dialect() == database.PostgreSQL {
+				likeOp = "ILIKE"
+			}
+			conditions = append(conditions, fmt.Sprintf("%s %s %s ESCAPE '\\'", extract, likeOp, r.db.Placeholder(placeholderIdx)))
+			val := fmt.Sprintf("%%%s%%", escapeLIKE(fmt.Sprintf("%v", f.Value)))
+			params = append(params, database.Text(val))
+			placeholderIdx++
+		case "startsWith":
+			likeOp := "LIKE"
+			if r.db.Dialect() == database.PostgreSQL {
+				likeOp = "ILIKE"
+			}
+			conditions = append(conditions, fmt.Sprintf("%s %s %s ESCAPE '\\'", extract, likeOp, r.db.Placeholder(placeholderIdx)))
+			val := fmt.Sprintf("%s%%", escapeLIKE(fmt.Sprintf("%v", f.Value)))
+			params = append(params, database.Text(val))
+			placeholderIdx++
+		case "isNull":
+			isNull, _ := f.Value.(bool)
+			if isNull {
+				conditions = append(conditions, fmt.Sprintf("%s IS NULL", extract))
+			} else {
+				conditions = append(conditions, fmt.Sprintf("%s IS NOT NULL", extract))
+			}
+		case "in":
+			inVals, _ := f.Value.([]interface{})
+			if len(inVals) == 0 {
+				// Empty IN list — always false
+				conditions = append(conditions, "1 = 0")
+				continue
+			}
+			if len(inVals) > MaxINListSize {
+				return "", nil, fmt.Errorf("IN filter on field %q exceeds maximum of %d values", f.Field, MaxINListSize)
+			}
+			placeholders := r.db.Placeholders(len(inVals), placeholderIdx)
+			conditions = append(conditions, fmt.Sprintf("%s IN (%s)", extract, placeholders))
+			for _, v := range inVals {
+				params = append(params, toDBValue(v))
+				placeholderIdx++
+			}
+		}
+	}
+
+	return strings.Join(conditions, " AND "), params, nil
+}
+
+// buildDIDFilterClause builds a SQL WHERE clause fragment for a DIDFilter.
+// startPlaceholder is the 1-based index of the first placeholder to use.
+// Returns the clause string (without leading "AND"), the parameter values, and
+// the number of placeholders consumed. Returns empty string and nil params if
+// the filter is empty.
+func (r *RecordsRepository) buildDIDFilterClause(f DIDFilter, startPlaceholder int) (string, []database.Value, int) {
+	if f.IsEmpty() {
+		return "", nil, 0
+	}
+
+	// EQ takes precedence over IN when both are set.
+	if f.EQ != "" {
+		clause := fmt.Sprintf("did = %s", r.db.Placeholder(startPlaceholder))
+		return clause, []database.Value{database.Text(f.EQ)}, 1
+	}
+
+	// IN list
+	if len(f.IN) == 0 {
+		// Empty IN list — always false
+		return "1 = 0", nil, 0
+	}
+	placeholders := r.db.Placeholders(len(f.IN), startPlaceholder)
+	clause := fmt.Sprintf("did IN (%s)", placeholders)
+	params := make([]database.Value, len(f.IN))
+	for i, did := range f.IN {
+		params[i] = database.Text(did)
+	}
+	return clause, params, len(f.IN)
+}
+
+// toDBValue converts an interface{} value to a database.Value.
+func toDBValue(v interface{}) database.Value {
+	switch val := v.(type) {
+	case string:
+		return database.Text(val)
+	case int:
+		return database.Int(int64(val))
+	case int64:
+		return database.Int(val)
+	case float64:
+		return database.Float(val)
+	case bool:
+		return database.Bool(val)
+	case nil:
+		return database.Null()
+	default:
+		return database.Text(fmt.Sprintf("%v", val))
+	}
+}
+
+// GetByCollectionFilteredWithKeysetCursor retrieves records for a collection with
+// optional field-level filters and keyset-based pagination.
+// Filters are applied as AND conditions on JSON fields.
+// If didFilter is non-empty, results are further filtered by DID.
+// Records are ordered by (indexed_at DESC, uri DESC).
+func (r *RecordsRepository) GetByCollectionFilteredWithKeysetCursor(
+	ctx context.Context,
+	collection string,
+	filters []FieldFilter,
+	didFilter DIDFilter,
+	limit int,
+	afterTimestamp string,
+	afterURI string,
+) ([]*Record, error) {
+	// Build the base WHERE clause
+	// collection = ? is always param 1
+	var whereParts []string
+	var args []any
+
+	whereParts = append(whereParts, fmt.Sprintf("collection = %s", r.db.Placeholder(1)))
+	args = append(args, collection)
+
+	nextPlaceholder := 2
+
+	// Keyset cursor condition
+	if afterTimestamp != "" && afterURI != "" {
+		p2 := r.db.Placeholder(nextPlaceholder)
+		p3 := r.db.Placeholder(nextPlaceholder + 1)
+		p4 := r.db.Placeholder(nextPlaceholder + 2)
+		whereParts = append(whereParts, fmt.Sprintf("(indexed_at < %s OR (indexed_at = %s AND uri < %s))", p2, p3, p4))
+		args = append(args, afterTimestamp, afterTimestamp, afterURI)
+		nextPlaceholder += 3
+	}
+
+	// Field filters
+	filterClause, filterParams, err := r.buildFilterClause(filters, nextPlaceholder)
+	if err != nil {
+		return nil, fmt.Errorf("failed to build filter clause: %w", err)
+	}
+	if filterClause != "" {
+		whereParts = append(whereParts, filterClause)
+		for _, p := range filterParams {
+			args = append(args, r.db.ConvertParams([]database.Value{p})[0])
+			nextPlaceholder++
+		}
+	}
+
+	// DID filter
+	if didClause, didParams, _ := r.buildDIDFilterClause(didFilter, nextPlaceholder); didClause != "" {
+		whereParts = append(whereParts, didClause)
+		for _, p := range didParams {
+			args = append(args, r.db.ConvertParams([]database.Value{p})[0])
+		}
+	}
+
+	whereClause := strings.Join(whereParts, " AND ")
+	sqlStr := fmt.Sprintf("SELECT %s FROM record WHERE %s ORDER BY indexed_at DESC, uri DESC LIMIT %d",
+		r.recordColumns(), whereClause, limit)
+
+	rows, err := r.db.DB().QueryContext(ctx, sqlStr, args...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to query filtered records: %w", err)
+	}
+	defer rows.Close()
+
+	return scanRecords(rows)
+}
+
+// directSortColumns is the set of column names that can be used directly in ORDER BY
+// without JSON extraction.
+var directSortColumns = map[string]bool{
+	"indexed_at": true,
+	"uri":        true,
+	"did":        true,
+	"collection": true,
+	"cid":        true,
+	"rkey":       true,
+}
+
+// buildSortExpr builds the ORDER BY expression for a given SortOption.
+// If sort is nil, returns the default "indexed_at DESC, uri DESC".
+// If sort.Field is a direct column, uses it as-is; otherwise uses JSONExtract.
+// Always appends ", uri <direction>" as a tiebreaker unless the sort field IS uri.
+// The uri tiebreaker direction matches the primary sort direction.
+func (r *RecordsRepository) buildSortExpr(sort *SortOption) string {
+	if sort == nil {
+		return "indexed_at DESC, uri DESC"
+	}
+
+	dir := sort.Direction
+	if dir != "ASC" && dir != "DESC" {
+		dir = "DESC"
+	}
+
+	var fieldExpr string
+	if directSortColumns[sort.Field] {
+		fieldExpr = sort.Field
+	} else {
+		fieldExpr = r.db.JSONExtract("json", sort.Field)
+	}
+
+	expr := fmt.Sprintf("%s %s", fieldExpr, dir)
+
+	// Append uri tiebreaker unless the primary sort field is already uri
+	if sort.Field != "uri" {
+		expr += fmt.Sprintf(", uri %s", dir)
+	}
+
+	return expr
+}
+
+// GetByCollectionSortedWithKeysetCursor retrieves records for a collection with
+// optional field-level filters, a configurable sort order, and keyset-based pagination.
+// The sort field and direction are specified via the sort parameter (nil = default indexed_at DESC).
+// afterCursorValues is [sortFieldValue, uri] for keyset pagination; empty means first page.
+// If didFilter is non-empty, results are further filtered by DID.
+func (r *RecordsRepository) GetByCollectionSortedWithKeysetCursor(
+	ctx context.Context,
+	collection string,
+	filters []FieldFilter,
+	didFilter DIDFilter,
+	sort *SortOption,
+	limit int,
+	afterCursorValues []string,
+) ([]*Record, error) {
+	var whereParts []string
+	var args []any
+
+	// collection = ? is always param 1
+	whereParts = append(whereParts, fmt.Sprintf("collection = %s", r.db.Placeholder(1)))
+	args = append(args, collection)
+
+	nextPlaceholder := 2
+
+	// Keyset cursor condition
+	if len(afterCursorValues) == 2 {
+		afterSortVal := afterCursorValues[0]
+		afterURI := afterCursorValues[1]
+
+		// Determine the sort field expression and comparison operator
+		var sortFieldExpr string
+		if sort == nil || directSortColumns[sort.Field] {
+			if sort == nil {
+				sortFieldExpr = "indexed_at"
+			} else {
+				sortFieldExpr = sort.Field
+			}
+		} else {
+			sortFieldExpr = r.db.JSONExtract("json", sort.Field)
+		}
+
+		// DESC uses <, ASC uses >
+		var cmp string
+		if sort == nil || sort.Direction == "DESC" {
+			cmp = "<"
+		} else {
+			cmp = ">"
+		}
+
+		p1 := r.db.Placeholder(nextPlaceholder)
+		p2 := r.db.Placeholder(nextPlaceholder + 1)
+		p3 := r.db.Placeholder(nextPlaceholder + 2)
+
+		// Composite keyset: (sortField op afterSortVal) OR (sortField = afterSortVal AND uri op afterURI)
+		whereParts = append(whereParts, fmt.Sprintf(
+			"(%s %s %s OR (%s = %s AND uri %s %s))",
+			sortFieldExpr, cmp, p1,
+			sortFieldExpr, p2,
+			cmp, p3,
+		))
+		args = append(args, afterSortVal, afterSortVal, afterURI)
+		nextPlaceholder += 3
+	}
+
+	// Field filters
+	filterClause, filterParams, err := r.buildFilterClause(filters, nextPlaceholder)
+	if err != nil {
+		return nil, fmt.Errorf("failed to build filter clause: %w", err)
+	}
+	if filterClause != "" {
+		whereParts = append(whereParts, filterClause)
+		for _, p := range filterParams {
+			args = append(args, r.db.ConvertParams([]database.Value{p})[0])
+			nextPlaceholder++
+		}
+	}
+
+	// DID filter
+	if didClause, didParams, _ := r.buildDIDFilterClause(didFilter, nextPlaceholder); didClause != "" {
+		whereParts = append(whereParts, didClause)
+		for _, p := range didParams {
+			args = append(args, r.db.ConvertParams([]database.Value{p})[0])
+		}
+	}
+
+	whereClause := strings.Join(whereParts, " AND ")
+	orderBy := r.buildSortExpr(sort)
+	sqlStr := fmt.Sprintf("SELECT %s FROM record WHERE %s ORDER BY %s LIMIT %d",
+		r.recordColumns(), whereClause, orderBy, limit)
+
+	rows, err := r.db.DB().QueryContext(ctx, sqlStr, args...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to query sorted records: %w", err)
+	}
+	defer rows.Close()
+
+	return scanRecords(rows)
+}
+
+// GetByCollectionReversedWithKeysetCursor retrieves records for backward pagination
+// per the Relay Connection Spec (last/before).
+//
+// Algorithm:
+//  1. Reverse the sort direction (DESC→ASC, ASC→DESC)
+//  2. Reverse the cursor comparison operator (DESC's < becomes >, ASC's > becomes <)
+//  3. Fetch limit records with LIMIT
+//  4. Reverse the result slice in-memory to restore the original sort order
+//
+// This ensures that `last N` returns the last N edges in the connection, and
+// `last N, before cursor` returns the N edges immediately before the cursor.
+//
+// Fetches limit+1 to allow the caller to detect hasPreviousPage.
+// If didFilter is non-empty, results are further filtered by DID.
+func (r *RecordsRepository) GetByCollectionReversedWithKeysetCursor(
+	ctx context.Context,
+	collection string,
+	filters []FieldFilter,
+	didFilter DIDFilter,
+	sort *SortOption,
+	limit int,
+	beforeCursorValues []string,
+) ([]*Record, error) {
+	// Build the reversed sort option: flip direction
+	var reversedSort *SortOption
+	if sort == nil {
+		// Default is indexed_at DESC → reverse to ASC
+		reversedSort = &SortOption{Field: "indexed_at", Direction: "ASC"}
+	} else {
+		dir := "ASC"
+		if sort.Direction == "ASC" {
+			dir = "DESC"
+		}
+		reversedSort = &SortOption{Field: sort.Field, Direction: dir}
+	}
+
+	var whereParts []string
+	var args []any
+
+	// collection = ? is always param 1
+	whereParts = append(whereParts, fmt.Sprintf("collection = %s", r.db.Placeholder(1)))
+	args = append(args, collection)
+
+	nextPlaceholder := 2
+
+	// Keyset cursor condition with reversed comparison operator.
+	// For DESC original (reversed to ASC): forward DESC uses <, so reversed uses >
+	// For ASC original (reversed to DESC): forward ASC uses >, so reversed uses <
+	if len(beforeCursorValues) == 2 {
+		beforeSortVal := beforeCursorValues[0]
+		beforeURI := beforeCursorValues[1]
+
+		// Determine the sort field expression using the reversed sort's field
+		var sortFieldExpr string
+		if directSortColumns[reversedSort.Field] {
+			sortFieldExpr = reversedSort.Field
+		} else {
+			sortFieldExpr = r.db.JSONExtract("json", reversedSort.Field)
+		}
+
+		// Reversed comparison: ASC reversed direction uses >, DESC reversed direction uses <
+		var cmp string
+		if reversedSort.Direction == "ASC" {
+			cmp = ">"
+		} else {
+			cmp = "<"
+		}
+
+		p1 := r.db.Placeholder(nextPlaceholder)
+		p2 := r.db.Placeholder(nextPlaceholder + 1)
+		p3 := r.db.Placeholder(nextPlaceholder + 2)
+
+		whereParts = append(whereParts, fmt.Sprintf(
+			"(%s %s %s OR (%s = %s AND uri %s %s))",
+			sortFieldExpr, cmp, p1,
+			sortFieldExpr, p2,
+			cmp, p3,
+		))
+		args = append(args, beforeSortVal, beforeSortVal, beforeURI)
+		nextPlaceholder += 3
+	}
+
+	// Field filters
+	filterClause, filterParams, err := r.buildFilterClause(filters, nextPlaceholder)
+	if err != nil {
+		return nil, fmt.Errorf("failed to build filter clause: %w", err)
+	}
+	if filterClause != "" {
+		whereParts = append(whereParts, filterClause)
+		for _, p := range filterParams {
+			args = append(args, r.db.ConvertParams([]database.Value{p})[0])
+			nextPlaceholder++
+		}
+	}
+
+	// DID filter
+	if didClause, didParams, _ := r.buildDIDFilterClause(didFilter, nextPlaceholder); didClause != "" {
+		whereParts = append(whereParts, didClause)
+		for _, p := range didParams {
+			args = append(args, r.db.ConvertParams([]database.Value{p})[0])
+		}
+	}
+
+	whereClause := strings.Join(whereParts, " AND ")
+	orderBy := r.buildSortExpr(reversedSort)
+	sqlStr := fmt.Sprintf("SELECT %s FROM record WHERE %s ORDER BY %s LIMIT %d",
+		r.recordColumns(), whereClause, orderBy, limit)
+
+	rows, err := r.db.DB().QueryContext(ctx, sqlStr, args...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to query reversed records: %w", err)
+	}
+	defer rows.Close()
+
+	records, err := scanRecords(rows)
+	if err != nil {
+		return nil, err
+	}
+
+	// Reverse the result slice to restore the original sort order
+	for i, j := 0, len(records)-1; i < j; i, j = i+1, j-1 {
+		records[i], records[j] = records[j], records[i]
+	}
+
+	return records, nil
+}
+
 // GetByDID retrieves all records for a specific DID.
 func (r *RecordsRepository) GetByDID(ctx context.Context, did string) ([]*Record, error) {
 	sqlStr := fmt.Sprintf("SELECT %s FROM record WHERE did = %s ORDER BY indexed_at DESC",
@@ -361,6 +885,51 @@ func (r *RecordsRepository) GetCount(ctx context.Context) (int64, error) {
 	return count, err
 }
 
+// GetCollectionCount returns the total record count for a collection.
+func (r *RecordsRepository) GetCollectionCount(ctx context.Context, collection string) (int64, error) {
+	sqlStr := fmt.Sprintf("SELECT COUNT(*) FROM record WHERE collection = %s", r.db.Placeholder(1))
+	var count int64
+	err := r.db.QueryRow(ctx, sqlStr, []database.Value{database.Text(collection)}, &count)
+	return count, err
+}
+
+// GetCollectionCountFiltered returns the count with optional DID and field filters applied.
+func (r *RecordsRepository) GetCollectionCountFiltered(
+	ctx context.Context, collection string, filters []FieldFilter, didFilter DIDFilter,
+) (int64, error) {
+	var whereParts []string
+	var params []database.Value
+
+	whereParts = append(whereParts, fmt.Sprintf("collection = %s", r.db.Placeholder(1)))
+	params = append(params, database.Text(collection))
+
+	nextPlaceholder := 2
+
+	// Field filters
+	filterClause, filterParams, err := r.buildFilterClause(filters, nextPlaceholder)
+	if err != nil {
+		return 0, fmt.Errorf("failed to build filter clause: %w", err)
+	}
+	if filterClause != "" {
+		whereParts = append(whereParts, filterClause)
+		params = append(params, filterParams...)
+		nextPlaceholder += len(filterParams)
+	}
+
+	// DID filter
+	if didClause, didParams, _ := r.buildDIDFilterClause(didFilter, nextPlaceholder); didClause != "" {
+		whereParts = append(whereParts, didClause)
+		params = append(params, didParams...)
+	}
+
+	whereClause := strings.Join(whereParts, " AND ")
+	sqlStr := fmt.Sprintf("SELECT COUNT(*) FROM record WHERE %s", whereClause)
+
+	var count int64
+	err = r.db.QueryRow(ctx, sqlStr, params, &count)
+	return count, err
+}
+
 // GetCollectionStats returns statistics for all collections.
 func (r *RecordsRepository) GetCollectionStats(ctx context.Context) ([]CollectionStat, error) {
 	sqlStr := "SELECT collection, COUNT(*) as count FROM record GROUP BY collection ORDER BY count DESC"
@@ -591,6 +1160,78 @@ func (r *RecordsRepository) GetExistingCIDs(ctx context.Context, cids []string)
 	return result, nil
 }
 
+// escapeLIKE escapes special LIKE wildcard characters (%, _) in a user-provided search string.
+// This prevents wildcard injection where user input could match unintended patterns.
+func escapeLIKE(s string) string {
+	s = strings.ReplaceAll(s, `\`, `\\`)
+	s = strings.ReplaceAll(s, "%", `\%`)
+	s = strings.ReplaceAll(s, "_", `\_`)
+	return s
+}
+
+// Search performs a LIKE-based text search on record JSON content.
+// On PostgreSQL, uses case-insensitive ILIKE. On SQLite, LIKE is already case-insensitive for ASCII.
+// collection is optional; if empty, searches across all collections.
+// Supports keyset pagination via afterTimestamp and afterURI.
+func (r *RecordsRepository) Search(
+	ctx context.Context,
+	searchQuery string,
+	collection string,
+	limit int,
+	afterTimestamp string,
+	afterURI string,
+) ([]*Record, error) {
+	ctx, cancel := context.WithTimeout(ctx, SearchTimeout)
+	defer cancel()
+
+	escaped := escapeLIKE(searchQuery)
+	likeValue := "%" + escaped + "%"
+
+	var conditions []string
+	var params []database.Value
+	paramIdx := 1
+
+	// JSON LIKE/ILIKE condition
+	switch r.db.Dialect() {
+	case database.PostgreSQL:
+		conditions = append(conditions, fmt.Sprintf("json::text ILIKE %s ESCAPE '\\'", r.db.Placeholder(paramIdx)))
+	default:
+		conditions = append(conditions, fmt.Sprintf("json LIKE %s ESCAPE '\\'", r.db.Placeholder(paramIdx)))
+	}
+	params = append(params, database.Text(likeValue))
+	paramIdx++
+
+	// Optional collection filter
+	if collection != "" {
+		conditions = append(conditions, fmt.Sprintf("collection = %s", r.db.Placeholder(paramIdx)))
+		params = append(params, database.Text(collection))
+		paramIdx++
+	}
+
+	// Keyset cursor
+	if afterTimestamp != "" && afterURI != "" {
+		conditions = append(conditions, fmt.Sprintf(
+			"(indexed_at < %s OR (indexed_at = %s AND uri < %s))",
+			r.db.Placeholder(paramIdx),
+			r.db.Placeholder(paramIdx+1),
+			r.db.Placeholder(paramIdx+2),
+		))
+		params = append(params, database.Text(afterTimestamp), database.Text(afterTimestamp), database.Text(afterURI))
+	}
+
+	whereClause := "WHERE " + strings.Join(conditions, " AND ")
+	sqlStr := fmt.Sprintf("SELECT %s FROM record %s ORDER BY indexed_at DESC, uri DESC LIMIT %d",
+		r.recordColumns(), whereClause, limit)
+
+	rows, err := r.db.DB().QueryContext(ctx, sqlStr, r.db.ConvertParams(params)...)
+	if err != nil {
+		return nil, fmt.Errorf("failed to search records: %w", err)
+	}
+	defer rows.Close()
+
+	return scanRecords(rows)
+}
+
 // Helper functions
 
 func (r *RecordsRepository) getCIDByURI(ctx context.Context, uri string) (string, error) {
diff --git a/internal/database/repositories/records_filter_test.go b/internal/database/repositories/records_filter_test.go
new file mode 100644
index 0000000..f659806
--- /dev/null
+++ b/internal/database/repositories/records_filter_test.go
@@ -0,0 +1,842 @@
+// Package repositories contains data access layer implementations.
+package repositories
+
+import (
+	"context"
+	"strings"
+	"testing"
+
+	"github.com/GainForest/hypergoat/internal/database"
+	"github.com/GainForest/hypergoat/internal/database/sqlite"
+)
+
+// newTestRepo creates a RecordsRepository backed by an in-memory SQLite executor for unit tests.
+func newTestRepo(t *testing.T) *RecordsRepository {
+	t.Helper()
+	exec, err := sqlite.NewExecutor("sqlite::memory:")
+	if err != nil {
+		t.Fatalf("failed to create sqlite executor: %v", err)
+	}
+	t.Cleanup(func() { exec.Close() })
+	return NewRecordsRepository(exec)
+}
+
+func TestBuildFilterClause_EmptyFilters(t *testing.T) {
+	repo := newTestRepo(t)
+	clause, params, _ := repo.buildFilterClause(nil, 1)
+	if clause != "" {
+		t.Errorf("empty filters: clause = %q, want empty string", clause)
+	}
+	if params != nil {
+		t.Errorf("empty filters: params = %v, want nil", params)
+	}
+
+	clause2, params2, _ := repo.buildFilterClause([]FieldFilter{}, 1)
+	if clause2 != "" {
+		t.Errorf("empty slice: clause = %q, want empty string", clause2)
+	}
+	if params2 != nil {
+		t.Errorf("empty slice: params = %v, want nil", params2)
+	}
+}
+
+func TestBuildFilterClause_Operators(t *testing.T) {
+	repo := newTestRepo(t)
+
+	tests := []struct {
+		name         string
+		filter       FieldFilter
+		wantContains string // substring expected in the clause
+		wantParams   int    // number of params expected
+	}{
+		{
+			name:         "eq operator",
+			filter:       FieldFilter{Field: "title", Operator: "eq", Value: "hello", FieldType: "string"},
+			wantContains: "= ?",
+			wantParams:   1,
+		},
+		{
+			name:         "neq operator",
+			filter:       FieldFilter{Field: "title", Operator: "neq", Value: "hello", FieldType: "string"},
+			wantContains: "!= ?",
+			wantParams:   1,
+		},
+		{
+			name:         "gt operator",
+			filter:       FieldFilter{Field: "score", Operator: "gt", Value: 5, FieldType: "integer"},
+			wantContains: "> ?",
+			wantParams:   1,
+		},
+		{
+			name:         "lt operator",
+			filter:       FieldFilter{Field: "score", Operator: "lt", Value: 10, FieldType: "integer"},
+			wantContains: "< ?",
+			wantParams:   1,
+		},
+		{
+			name:         "gte operator",
+			filter:       FieldFilter{Field: "score", Operator: "gte", Value: 5, FieldType: "number"},
+			wantContains: ">= ?",
+			wantParams:   1,
+		},
+		{
+			name:         "lte operator",
+			filter:       FieldFilter{Field: "score", Operator: "lte", Value: 10, FieldType: "number"},
+			wantContains: "<= ?",
+			wantParams:   1,
+		},
+		{
+			name:         "contains operator wraps value in percent",
+			filter:       FieldFilter{Field: "body", Operator: "contains", Value: "world", FieldType: "string"},
+			wantContains: "LIKE ?",
+			wantParams:   1,
+		},
+		{
+			name:         "startsWith operator appends percent",
+			filter:       FieldFilter{Field: "body", Operator: "startsWith", Value: "hello", FieldType: "string"},
+			wantContains: "LIKE ?",
+			wantParams:   1,
+		},
+		{
+			name:         "isNull true generates IS NULL",
+			filter:       FieldFilter{Field: "deletedAt", Operator: "isNull", Value: true, FieldType: "string"},
+			wantContains: "IS NULL",
+			wantParams:   0,
+		},
+		{
+			name:         "isNull false generates IS NOT NULL",
+			filter:       FieldFilter{Field: "deletedAt", Operator: "isNull", Value: false, FieldType: "string"},
+			wantContains: "IS NOT NULL",
+			wantParams:   0,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			clause, params, _ := repo.buildFilterClause([]FieldFilter{tt.filter}, 1)
+			if clause == "" {
+				t.Fatalf("clause is empty, want non-empty")
+			}
+			if !strings.Contains(clause, tt.wantContains) {
+				t.Errorf("clause = %q, want to contain %q", clause, tt.wantContains)
+			}
+			if len(params) != tt.wantParams {
+				t.Errorf("params count = %d, want %d", len(params), tt.wantParams)
+			}
+		})
+	}
+}
+
+func TestBuildFilterClause_ContainsWrapsValue(t *testing.T) {
+	repo := newTestRepo(t)
+	filters := []FieldFilter{
+		{Field: "body", Operator: "contains", Value: "world", FieldType: "string"},
+	}
+	_, params, _ := repo.buildFilterClause(filters, 1)
+	if len(params) != 1 {
+		t.Fatalf("expected 1 param, got %d", len(params))
+	}
+	tv, ok := params[0].(database.TextValue)
+	if !ok {
+		t.Fatalf("param is not TextValue, got %T", params[0])
+	}
+	if string(tv) != "%world%" {
+		t.Errorf("contains param = %q, want %%world%%", string(tv))
+	}
+}
+
+func TestBuildFilterClause_StartsWithAppendsPercent(t *testing.T) {
+	repo := newTestRepo(t)
+	filters := []FieldFilter{
+		{Field: "body", Operator: "startsWith", Value: "hello", FieldType: "string"},
+	}
+	_, params, _ := repo.buildFilterClause(filters, 1)
+	if len(params) != 1 {
+		t.Fatalf("expected 1 param, got %d", len(params))
+	}
+	tv, ok := params[0].(database.TextValue)
+	if !ok {
+		t.Fatalf("param is not TextValue, got %T", params[0])
+	}
+	if string(tv) != "hello%" {
+		t.Errorf("startsWith param = %q, want hello%%", string(tv))
+	}
+}
+
+func TestBuildFilterClause_InOperator(t *testing.T) {
+	repo := newTestRepo(t)
+	filters := []FieldFilter{
+		{Field: "status", Operator: "in", Value: []interface{}{"active", "pending", "closed"}, FieldType: "string"},
+	}
+	clause, params, _ := repo.buildFilterClause(filters, 1)
+	if !strings.Contains(clause, "IN (") {
+		t.Errorf("clause = %q, want to contain IN (", clause)
+	}
+	if len(params) != 3 {
+		t.Errorf("params count = %d, want 3", len(params))
+	}
+}
+
+func TestBuildFilterClause_NumericCast(t *testing.T) {
+	repo := newTestRepo(t)
+
+	t.Run("integer type uses CAST AS REAL in SQLite", func(t *testing.T) {
+		filters := []FieldFilter{
+			{Field: "score", Operator: "gt", Value: 5, FieldType: "integer"},
+		}
+		clause, _, _ := repo.buildFilterClause(filters, 1)
+		if !strings.Contains(clause, "CAST(") {
+			t.Errorf("integer filter clause = %q, want CAST(...)", clause)
+		}
+		if !strings.Contains(clause, "AS REAL") {
+			t.Errorf("integer filter clause = %q, want AS REAL", clause)
+		}
+	})
+
+	t.Run("number type uses CAST AS REAL in SQLite", func(t *testing.T) {
+		filters := []FieldFilter{
+			{Field: "price", Operator: "lte", Value: 99.99, FieldType: "number"},
+		}
+		clause, _, _ := repo.buildFilterClause(filters, 1)
+		if !strings.Contains(clause, "CAST(") {
+			t.Errorf("number filter clause = %q, want CAST(...)", clause)
+		}
+		if !strings.Contains(clause, "AS REAL") {
+			t.Errorf("number filter clause = %q, want AS REAL", clause)
+		}
+	})
+
+	t.Run("string type does not use CAST", func(t *testing.T) {
+		filters := []FieldFilter{
+			{Field: "title", Operator: "eq", Value: "hello", FieldType: "string"},
+		}
+		clause, _, _ := repo.buildFilterClause(filters, 1)
+		if strings.Contains(clause, "CAST(") {
+			t.Errorf("string filter clause = %q, should not contain CAST", clause)
+		}
+	})
+}
+
+func TestBuildFilterClause_MultipleFilters(t *testing.T) {
+	repo := newTestRepo(t)
+	filters := []FieldFilter{
+		{Field: "title", Operator: "eq", Value: "hello", FieldType: "string"},
+		{Field: "score", Operator: "gt", Value: 5, FieldType: "integer"},
+		{Field: "deletedAt", Operator: "isNull", Value: true, FieldType: "string"},
+	}
+	clause, params, _ := repo.buildFilterClause(filters, 1)
+
+	// Should be joined with AND
+	parts := strings.Split(clause, " AND ")
+	if len(parts) != 3 {
+		t.Errorf("expected 3 AND-joined conditions, got %d in clause: %q", len(parts), clause)
+	}
+	// Two params: eq and gt (isNull has no param)
+	if len(params) != 2 {
+		t.Errorf("params count = %d, want 2", len(params))
+	}
+}
+
+// newSortTestRepo creates a RecordsRepository with a fresh in-memory SQLite DB and the record table.
+// Returns the repo and a helper function for running raw SQL (e.g., to set indexed_at).
+func newSortTestRepo(t *testing.T) (*RecordsRepository, func(query string, args ...any)) {
+	t.Helper()
+	exec, err := sqlite.NewExecutor("sqlite::memory:")
+	if err != nil {
+		t.Fatalf("failed to create executor: %v", err)
+	}
+	t.Cleanup(func() { exec.Close() })
+	rawDB := exec.DB()
+	_, err = rawDB.ExecContext(context.Background(), `
+		CREATE TABLE IF NOT EXISTS record (
+			uri TEXT PRIMARY KEY,
+			cid TEXT NOT NULL,
+			did TEXT NOT NULL,
+			collection TEXT NOT NULL,
+			json TEXT NOT NULL DEFAULT '{}',
+			indexed_at TEXT NOT NULL DEFAULT (datetime('now')),
+			rkey TEXT NOT NULL DEFAULT ''
+		)`)
+	if err != nil {
+		t.Fatalf("failed to create record table: %v", err)
+	}
+	execFn := func(query string, args ...any) {
+		_, _ = rawDB.ExecContext(context.Background(), query, args...)
+	}
+	return NewRecordsRepository(exec), execFn
+}
+
+func insertSortRecord(t *testing.T, repo *RecordsRepository, uri, cid, did, collection, jsonData string) {
+	t.Helper()
+	_, err := repo.Insert(context.Background(), uri, cid, did, collection, jsonData)
+	if err != nil {
+		t.Fatalf("failed to insert record %s: %v", uri, err)
+	}
+}
+
+func TestBuildSortExpr_NilSortOption(t *testing.T) {
+	repo := newTestRepo(t)
+	expr := repo.buildSortExpr(nil)
+	want := "indexed_at DESC, uri DESC"
+	if expr != want {
+		t.Errorf("buildSortExpr(nil) = %q, want %q", expr, want)
+	}
+}
+
+func TestBuildSortExpr_IndexedAtASC(t *testing.T) {
+	repo := newTestRepo(t)
+	sort := &SortOption{Field: "indexed_at", Direction: "ASC"}
+	expr := repo.buildSortExpr(sort)
+	want := "indexed_at ASC, uri ASC"
+	if expr != want {
+		t.Errorf("buildSortExpr(indexed_at ASC) = %q, want %q", expr, want)
+	}
+}
+
+func TestBuildSortExpr_IndexedAtDESC(t *testing.T) {
+	repo := newTestRepo(t)
+	sort := &SortOption{Field: "indexed_at", Direction: "DESC"}
+	expr := repo.buildSortExpr(sort)
+	want := "indexed_at DESC, uri DESC"
+	if expr != want {
+		t.Errorf("buildSortExpr(indexed_at DESC) = %q, want %q", expr, want)
+	}
+}
+
+func TestBuildSortExpr_URIField(t *testing.T) {
+	repo := newTestRepo(t)
+	sort := &SortOption{Field: "uri", Direction: "ASC"}
+	expr := repo.buildSortExpr(sort)
+	// uri is the sort field itself — no tiebreaker appended
+	if !strings.Contains(expr, "uri ASC") {
+		t.Errorf("buildSortExpr(uri ASC) = %q, want to contain 'uri ASC'", expr)
+	}
+	// Should NOT have a second uri reference (no tiebreaker)
+	if strings.Count(expr, "uri") > 1 {
+		t.Errorf("buildSortExpr(uri ASC) = %q, should not have duplicate uri", expr)
+	}
+}
+
+func TestBuildSortExpr_JSONField(t *testing.T) {
+	repo := newTestRepo(t)
+	sort := &SortOption{Field: "createdAt", Direction: "DESC"}
+	expr := repo.buildSortExpr(sort)
+	// Should use JSONExtract (json_extract for SQLite)
+	if !strings.Contains(expr, "json_extract") && !strings.Contains(expr, "->>'") {
+		t.Errorf("buildSortExpr(createdAt DESC) = %q, want JSONExtract expression", expr)
+	}
+	if !strings.Contains(expr, "DESC") {
+		t.Errorf("buildSortExpr(createdAt DESC) = %q, want DESC", expr)
+	}
+	// Should have uri tiebreaker
+	if !strings.Contains(expr, "uri DESC") {
+		t.Errorf("buildSortExpr(createdAt DESC) = %q, want uri DESC tiebreaker", expr)
+	}
+}
+
+func TestBuildSortExpr_DirectColumnDID(t *testing.T) {
+	repo := newTestRepo(t)
+	sort := &SortOption{Field: "did", Direction: "ASC"}
+	expr := repo.buildSortExpr(sort)
+	if !strings.Contains(expr, "did ASC") {
+		t.Errorf("buildSortExpr(did ASC) = %q, want 'did ASC'", expr)
+	}
+	if !strings.Contains(expr, "uri ASC") {
+		t.Errorf("buildSortExpr(did ASC) = %q, want 'uri ASC' tiebreaker", expr)
+	}
+}
+
+func TestGetByCollectionSortedWithKeysetCursor_DefaultSort(t *testing.T) {
+	repo, execSQL := newSortTestRepo(t)
+	ctx := context.Background()
+
+	insertSortRecord(t, repo, "at://did:plc:test/col/r1", "cid1", "did:plc:test", "col", `{"val":"a"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T10:00:00Z' WHERE uri = 'at://did:plc:test/col/r1'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r2", "cid2", "did:plc:test", "col", `{"val":"b"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T11:00:00Z' WHERE uri = 'at://did:plc:test/col/r2'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r3", "cid3", "did:plc:test", "col", `{"val":"c"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T12:00:00Z' WHERE uri = 'at://did:plc:test/col/r3'`)
+
+	// nil sort → indexed_at DESC (newest first)
+	records, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", nil, DIDFilter{}, nil, 10, nil)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	if len(records) != 3 {
+		t.Fatalf("got %d records, want 3", len(records))
+	}
+	// Newest first: r3, r2, r1
+	if records[0].URI != "at://did:plc:test/col/r3" {
+		t.Errorf("records[0].URI = %q, want r3", records[0].URI)
+	}
+	if records[1].URI != "at://did:plc:test/col/r2" {
+		t.Errorf("records[1].URI = %q, want r2", records[1].URI)
+	}
+	if records[2].URI != "at://did:plc:test/col/r1" {
+		t.Errorf("records[2].URI = %q, want r1", records[2].URI)
+	}
+}
+
+func TestGetByCollectionSortedWithKeysetCursor_IndexedAtASC(t *testing.T) {
+	repo, execSQL := newSortTestRepo(t)
+	ctx := context.Background()
+
+	insertSortRecord(t, repo, "at://did:plc:test/col/r1", "cid1", "did:plc:test", "col", `{"val":"a"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T10:00:00Z' WHERE uri = 'at://did:plc:test/col/r1'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r2", "cid2", "did:plc:test", "col", `{"val":"b"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T11:00:00Z' WHERE uri = 'at://did:plc:test/col/r2'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r3", "cid3", "did:plc:test", "col", `{"val":"c"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T12:00:00Z' WHERE uri = 'at://did:plc:test/col/r3'`)
+
+	sort := &SortOption{Field: "indexed_at", Direction: "ASC"}
+	records, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", nil, DIDFilter{}, sort, 10, nil)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	if len(records) != 3 {
+		t.Fatalf("got %d records, want 3", len(records))
+	}
+	// Oldest first: r1, r2, r3
+	if records[0].URI != "at://did:plc:test/col/r1" {
+		t.Errorf("records[0].URI = %q, want r1", records[0].URI)
+	}
+	if records[2].URI != "at://did:plc:test/col/r3" {
+		t.Errorf("records[2].URI = %q, want r3", records[2].URI)
+	}
+}
+
+func TestGetByCollectionSortedWithKeysetCursor_JSONFieldSort(t *testing.T) {
+	repo, _ := newSortTestRepo(t)
+	ctx := context.Background()
+
+	// Insert records with different createdAt values in JSON
+	insertSortRecord(t, repo, "at://did:plc:test/col/r1", "cid1", "did:plc:test", "col", `{"createdAt":"2026-01-15T10:00:00Z"}`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r2", "cid2", "did:plc:test", "col", `{"createdAt":"2026-01-15T12:00:00Z"}`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r3", "cid3", "did:plc:test", "col", `{"createdAt":"2026-01-15T11:00:00Z"}`)
+
+	// Sort by JSON field createdAt DESC
+	sort := &SortOption{Field: "createdAt", Direction: "DESC"}
+	records, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", nil, DIDFilter{}, sort, 10, nil)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	if len(records) != 3 {
+		t.Fatalf("got %d records, want 3", len(records))
+	}
+	// DESC: r2 (12:00), r3 (11:00), r1 (10:00)
+	if records[0].URI != "at://did:plc:test/col/r2" {
+		t.Errorf("records[0].URI = %q, want r2 (newest createdAt)", records[0].URI)
+	}
+	if records[1].URI != "at://did:plc:test/col/r3" {
+		t.Errorf("records[1].URI = %q, want r3", records[1].URI)
+	}
+	if records[2].URI != "at://did:plc:test/col/r1" {
+		t.Errorf("records[2].URI = %q, want r1 (oldest createdAt)", records[2].URI)
+	}
+}
+
+func TestGetByCollectionSortedWithKeysetCursor_KeysetCursorASC(t *testing.T) {
+	repo, execSQL := newSortTestRepo(t)
+	ctx := context.Background()
+
+	insertSortRecord(t, repo, "at://did:plc:test/col/r1", "cid1", "did:plc:test", "col", `{"val":"a"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T10:00:00Z' WHERE uri = 'at://did:plc:test/col/r1'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r2", "cid2", "did:plc:test", "col", `{"val":"b"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T11:00:00Z' WHERE uri = 'at://did:plc:test/col/r2'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r3", "cid3", "did:plc:test", "col", `{"val":"c"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T12:00:00Z' WHERE uri = 'at://did:plc:test/col/r3'`)
+
+	// ASC sort: r1, r2, r3. Cursor after r1 → should return r2, r3
+	sort := &SortOption{Field: "indexed_at", Direction: "ASC"}
+	cursor := []string{"2026-01-15T10:00:00Z", "at://did:plc:test/col/r1"}
+	records, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", nil, DIDFilter{}, sort, 10, cursor)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	if len(records) != 2 {
+		t.Fatalf("got %d records, want 2", len(records))
+	}
+	if records[0].URI != "at://did:plc:test/col/r2" {
+		t.Errorf("records[0].URI = %q, want r2", records[0].URI)
+	}
+	if records[1].URI != "at://did:plc:test/col/r3" {
+		t.Errorf("records[1].URI = %q, want r3", records[1].URI)
+	}
+}
+
+func TestGetByCollectionSortedWithKeysetCursor_KeysetCursorDESC(t *testing.T) {
+	repo, execSQL := newSortTestRepo(t)
+	ctx := context.Background()
+
+	insertSortRecord(t, repo, "at://did:plc:test/col/r1", "cid1", "did:plc:test", "col", `{"val":"a"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T10:00:00Z' WHERE uri = 'at://did:plc:test/col/r1'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r2", "cid2", "did:plc:test", "col", `{"val":"b"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T11:00:00Z' WHERE uri = 'at://did:plc:test/col/r2'`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r3", "cid3", "did:plc:test", "col", `{"val":"c"}`)
+	execSQL(`UPDATE record SET indexed_at = '2026-01-15T12:00:00Z' WHERE uri = 'at://did:plc:test/col/r3'`)
+
+	// DESC sort: r3, r2, r1. Cursor after r3 → should return r2, r1
+	sort := &SortOption{Field: "indexed_at", Direction: "DESC"}
+	cursor := []string{"2026-01-15T12:00:00Z", "at://did:plc:test/col/r3"}
+	records, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", nil, DIDFilter{}, sort, 10, cursor)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	if len(records) != 2 {
+		t.Fatalf("got %d records, want 2", len(records))
+	}
+	if records[0].URI != "at://did:plc:test/col/r2" {
+		t.Errorf("records[0].URI = %q, want r2", records[0].URI)
+	}
+	if records[1].URI != "at://did:plc:test/col/r1" {
+		t.Errorf("records[1].URI = %q, want r1", records[1].URI)
+	}
+}
+
+func TestGetByCollectionSortedWithKeysetCursor_SortAndFilters(t *testing.T) {
+	repo, _ := newSortTestRepo(t)
+	ctx := context.Background()
+
+	// Insert records: some with tag "go", some without
+	insertSortRecord(t, repo, "at://did:plc:test/col/r1", "cid1", "did:plc:test", "col", `{"tag":"go","createdAt":"2026-01-15T10:00:00Z"}`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r2", "cid2", "did:plc:test", "col", `{"tag":"rust","createdAt":"2026-01-15T11:00:00Z"}`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r3", "cid3", "did:plc:test", "col", `{"tag":"go","createdAt":"2026-01-15T12:00:00Z"}`)
+	insertSortRecord(t, repo, "at://did:plc:test/col/r4", "cid4", "did:plc:test", "col", `{"tag":"go","createdAt":"2026-01-15T09:00:00Z"}`)
+
+	// Filter by tag=go, sort by createdAt ASC
+	filters := []FieldFilter{
+		{Field: "tag", Operator: "eq", Value: "go", FieldType: "string"},
+	}
+	sort := &SortOption{Field: "createdAt", Direction: "ASC"}
+	records, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", filters, DIDFilter{}, sort, 10, nil)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	// Should return r4, r1, r3 (tag=go, sorted by createdAt ASC)
+	if len(records) != 3 {
+		t.Fatalf("got %d records, want 3", len(records))
+	}
+	if records[0].URI != "at://did:plc:test/col/r4" {
+		t.Errorf("records[0].URI = %q, want r4 (09:00)", records[0].URI)
+	}
+	if records[1].URI != "at://did:plc:test/col/r1" {
+		t.Errorf("records[1].URI = %q, want r1 (10:00)", records[1].URI)
+	}
+	if records[2].URI != "at://did:plc:test/col/r3" {
+		t.Errorf("records[2].URI = %q, want r3 (12:00)", records[2].URI)
+	}
+
+	// Verify r2 (tag=rust) is excluded
+	for _, rec := range records {
+		if rec.URI == "at://did:plc:test/col/r2" {
+			t.Error("r2 (tag=rust) should not be in results")
+		}
+	}
+}
+
+func TestBuildFilterClause_LIKEEscape(t *testing.T) {
+	repo := newTestRepo(t)
+
+	tests := []struct {
+		name       string
+		operator   string
+		value      string
+		wantParam  string // expected SQL parameter value
+		wantEscape bool   // clause must contain ESCAPE
+	}{
+		{
+			name:       "contains with percent is escaped",
+			operator:   "contains",
+			value:      "100%",
+			wantParam:  `%100\%%`,
+			wantEscape: true,
+		},
+		{
+			name:       "contains with underscore is escaped",
+			operator:   "contains",
+			value:      "test_value",
+			wantParam:  `%test\_value%`,
+			wantEscape: true,
+		},
+		{
+			name:       "contains with backslash is escaped",
+			operator:   "contains",
+			value:      `path\to`,
+			wantParam:  `%path\\to%`,
+			wantEscape: true,
+		},
+		{
+			name:       "contains with no special chars is unchanged",
+			operator:   "contains",
+			value:      "hello",
+			wantParam:  "%hello%",
+			wantEscape: true,
+		},
+		{
+			name:       "startsWith with percent is escaped",
+			operator:   "startsWith",
+			value:      "100%",
+			wantParam:  `100\%%`,
+			wantEscape: true,
+		},
+		{
+			name:       "startsWith with underscore is escaped",
+			operator:   "startsWith",
+			value:      "test_",
+			wantParam:  `test\_%`,
+			wantEscape: true,
+		},
+		{
+			name:       "startsWith with backslash is escaped",
+			operator:   "startsWith",
+			value:      `C:\Users`,
+			wantParam:  `C:\\Users%`,
+			wantEscape: true,
+		},
+		{
+			name:       "startsWith with no special chars is unchanged",
+			operator:   "startsWith",
+			value:      "hello",
+			wantParam:  "hello%",
+			wantEscape: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			filters := []FieldFilter{
+				{Field: "title", Operator: tt.operator, Value: tt.value, FieldType: "string"},
+			}
+			clause, params, err := repo.buildFilterClause(filters, 1)
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if clause == "" {
+				t.Fatalf("clause is empty")
+			}
+
+			// Verify ESCAPE clause is present
+			if tt.wantEscape && !strings.Contains(clause, "ESCAPE") {
+				t.Errorf("clause = %q, want to contain ESCAPE", clause)
+			}
+
+			// Verify the parameter value is correctly escaped
+			if len(params) != 1 {
+				t.Fatalf("expected 1 param, got %d", len(params))
+			}
+			tv, ok := params[0].(database.TextValue)
+			if !ok {
+				t.Fatalf("param is not TextValue, got %T", params[0])
+			}
+			if string(tv) != tt.wantParam {
+				t.Errorf("param = %q, want %q", string(tv), tt.wantParam)
+			}
+		})
+	}
+}
+
+// TestDIDFilter_IsEmpty verifies the IsEmpty helper.
+func TestDIDFilter_IsEmpty(t *testing.T) {
+	tests := []struct {
+		name      string
+		filter    DIDFilter
+		wantEmpty bool
+	}{
+		{name: "zero value is empty", filter: DIDFilter{}, wantEmpty: true},
+		{name: "EQ set is not empty", filter: DIDFilter{EQ: "did:plc:abc"}, wantEmpty: false},
+		{name: "IN set is not empty", filter: DIDFilter{IN: []string{"did:plc:abc"}}, wantEmpty: false},
+		{name: "both set is not empty", filter: DIDFilter{EQ: "did:plc:abc", IN: []string{"did:plc:def"}}, wantEmpty: false},
+		{name: "empty EQ and nil IN is empty", filter: DIDFilter{EQ: "", IN: nil}, wantEmpty: true},
+		{name: "empty EQ and empty IN is empty", filter: DIDFilter{EQ: "", IN: []string{}}, wantEmpty: true},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.filter.IsEmpty(); got != tt.wantEmpty {
+				t.Errorf("IsEmpty() = %v, want %v", got, tt.wantEmpty)
+			}
+		})
+	}
+}
+
+// TestBuildDIDFilterClause verifies the SQL clause generation for DIDFilter.
+func TestBuildDIDFilterClause(t *testing.T) {
+	repo := newTestRepo(t)
+
+	tests := []struct {
+		name         string
+		filter       DIDFilter
+		wantClause   string // expected substring in clause (empty means empty clause)
+		wantParams   int
+		wantConsumed int
+	}{
+		{
+			name:         "empty filter returns empty clause",
+			filter:       DIDFilter{},
+			wantClause:   "",
+			wantParams:   0,
+			wantConsumed: 0,
+		},
+		{
+			name:         "EQ filter generates did = ?",
+			filter:       DIDFilter{EQ: "did:plc:abc"},
+			wantClause:   "did = ?",
+			wantParams:   1,
+			wantConsumed: 1,
+		},
+		{
+			name:         "IN filter generates did IN (?)",
+			filter:       DIDFilter{IN: []string{"did:plc:abc", "did:plc:def"}},
+			wantClause:   "did IN (?,?)",
+			wantParams:   2,
+			wantConsumed: 2,
+		},
+		{
+			name:         "empty IN list is treated as empty filter (no clause)",
+			filter:       DIDFilter{IN: []string{}},
+			wantClause:   "",
+			wantParams:   0,
+			wantConsumed: 0,
+		},
+		{
+			name:         "EQ takes precedence over IN when both set",
+			filter:       DIDFilter{EQ: "did:plc:abc", IN: []string{"did:plc:def"}},
+			wantClause:   "did = ?",
+			wantParams:   1,
+			wantConsumed: 1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			clause, params, consumed := repo.buildDIDFilterClause(tt.filter, 1)
+
+			if tt.wantClause == "" {
+				if clause != "" {
+					t.Errorf("clause = %q, want empty", clause)
+				}
+				return
+			}
+
+			// Normalize placeholders for comparison (SQLite uses ?)
+			if !strings.Contains(clause, strings.Split(tt.wantClause, "?")[0]) {
+				t.Errorf("clause = %q, want to contain %q", clause, tt.wantClause)
+			}
+			if len(params) != tt.wantParams {
+				t.Errorf("params count = %d, want %d", len(params), tt.wantParams)
+			}
+			if consumed != tt.wantConsumed {
+				t.Errorf("consumed = %d, want %d", consumed, tt.wantConsumed)
+			}
+		})
+	}
+}
+
+// TestGetByCollectionSortedWithKeysetCursor_DIDFilterIN verifies that the DID "in"
+// filter correctly returns records from multiple DIDs.
+func TestGetByCollectionSortedWithKeysetCursor_DIDFilterIN(t *testing.T) {
+	repo, _ := newSortTestRepo(t)
+	ctx := context.Background()
+
+	// Insert records from 3 different DIDs
+	insertSortRecord(t, repo, "at://did:plc:alice/col/r1", "cid1", "did:plc:alice", "col", `{}`)
+	insertSortRecord(t, repo, "at://did:plc:bob/col/r2", "cid2", "did:plc:bob", "col", `{}`)
+	insertSortRecord(t, repo, "at://did:plc:carol/col/r3", "cid3", "did:plc:carol", "col", `{}`)
+
+	// Filter by DID in [alice, bob] — should return 2 records
+	didFilter := DIDFilter{IN: []string{"did:plc:alice", "did:plc:bob"}}
+	records, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", nil, didFilter, nil, 10, nil)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	if len(records) != 2 {
+		t.Fatalf("got %d records, want 2", len(records))
+	}
+	for _, rec := range records {
+		if rec.DID != "did:plc:alice" && rec.DID != "did:plc:bob" {
+			t.Errorf("unexpected DID %q, want alice or bob", rec.DID)
+		}
+	}
+
+	// Filter by DID eq alice — should return 1 record
+	didFilterEQ := DIDFilter{EQ: "did:plc:alice"}
+	records2, err := repo.GetByCollectionSortedWithKeysetCursor(ctx, "col", nil, didFilterEQ, nil, 10, nil)
+	if err != nil {
+		t.Fatalf("error: %v", err)
+	}
+	if len(records2) != 1 {
+		t.Fatalf("got %d records, want 1", len(records2))
+	}
+	if records2[0].DID != "did:plc:alice" {
+		t.Errorf("DID = %q, want did:plc:alice", records2[0].DID)
+	}
+}
+
+func TestBuildFilterClause_INLimit(t *testing.T) {
+	repo := newTestRepo(t)
+
+	tests := []struct {
+		name     string
+		values   []interface{}
+		wantErr  bool
+		wantCond string // expected condition substring (when no error)
+	}{
+		{
+			name:     "0 values returns 1 = 0",
+			values:   []interface{}{},
+			wantErr:  false,
+			wantCond: "1 = 0",
+		},
+		{
+			name:     "1 value succeeds",
+			values:   []interface{}{"a"},
+			wantErr:  false,
+			wantCond: "IN (",
+		},
+		{
+			name: "100 values (boundary) succeeds",
+			values: func() []interface{} {
+				vals := make([]interface{}, 100)
+				for i := range vals {
+					vals[i] = i
+				}
+				return vals
+			}(),
+			wantErr:  false,
+			wantCond: "IN (",
+		},
+		{
+			name: "101 values (over limit) returns error",
+			values: func() []interface{} {
+				vals := make([]interface{}, 101)
+				for i := range vals {
+					vals[i] = i
+				}
+				return vals
+			}(),
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			filters := []FieldFilter{
+				{Field: "status", Operator: "in", Value: tt.values, FieldType: "string"},
+			}
+			clause, _, err := repo.buildFilterClause(filters, 1)
+			if tt.wantErr {
+				if err == nil {
+					t.Errorf("expected error, got nil (clause=%q)", clause)
+				} else if !strings.Contains(err.Error(), "exceeds maximum") {
+					t.Errorf("error = %q, want to contain \"exceeds maximum\"", err.Error())
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if tt.wantCond != "" && !strings.Contains(clause, tt.wantCond) {
+				t.Errorf("clause = %q, want to contain %q", clause, tt.wantCond)
+			}
+		})
+	}
+}
diff --git a/internal/database/repositories/records_test.go b/internal/database/repositories/records_test.go
index 48eced2..9051cc1 100644
--- a/internal/database/repositories/records_test.go
+++ b/internal/database/repositories/records_test.go
@@ -6,6 +6,7 @@ import (
 	"errors"
 	"fmt"
 	"testing"
+	"time"
 
 	"github.com/GainForest/hypergoat/internal/database/repositories"
 	"github.com/GainForest/hypergoat/internal/testutil"
@@ -863,6 +864,139 @@ func TestRecordsRepository_GetExistingCIDs(t *testing.T) {
 	}
 }
 
+func TestRecordsRepository_GetByCollectionFilteredWithKeysetCursor(t *testing.T) {
+	env := setupRecordsTestEnv(t)
+	repo := env.repo
+	ctx := context.Background()
+
+	sqlDB := env.db.Executor.DB()
+
+	// Insert records with distinct indexed_at timestamps and varied JSON fields
+	insertTestRecord(t, repo, "at://did:plc:alice/app.bsky.feed.post/f1", "bafyreif1", "did:plc:alice", "app.bsky.feed.post", `{"text":"hello world","score":10}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T10:00:00Z' WHERE uri = 'at://did:plc:alice/app.bsky.feed.post/f1'`)
+
+	insertTestRecord(t, repo, "at://did:plc:alice/app.bsky.feed.post/f2", "bafyreif2", "did:plc:alice", "app.bsky.feed.post", `{"text":"goodbye world","score":20}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T11:00:00Z' WHERE uri = 'at://did:plc:alice/app.bsky.feed.post/f2'`)
+
+	insertTestRecord(t, repo, "at://did:plc:bob/app.bsky.feed.post/f3", "bafyreif3", "did:plc:bob", "app.bsky.feed.post", `{"text":"hello again"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T12:00:00Z' WHERE uri = 'at://did:plc:bob/app.bsky.feed.post/f3'`)
+
+	insertTestRecord(t, repo, "at://did:plc:bob/app.bsky.feed.post/f4", "bafyreif4", "did:plc:bob", "app.bsky.feed.post", `{"text":"no greeting"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T13:00:00Z' WHERE uri = 'at://did:plc:bob/app.bsky.feed.post/f4'`)
+
+	t.Run("no filters returns all records", func(t *testing.T) {
+		records, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{}, 100, "", "")
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 4 {
+			t.Errorf("got %d records, want 4", len(records))
+		}
+	})
+
+	t.Run("filter by string eq", func(t *testing.T) {
+		filters := []repositories.FieldFilter{
+			{Field: "text", Operator: "eq", Value: "hello world", FieldType: "string"},
+		}
+		records, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", filters, repositories.DIDFilter{}, 100, "", "")
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 1 {
+			t.Fatalf("got %d records, want 1", len(records))
+		}
+		if records[0].URI != "at://did:plc:alice/app.bsky.feed.post/f1" {
+			t.Errorf("unexpected URI %q", records[0].URI)
+		}
+	})
+
+	t.Run("filter by isNull true returns records without field", func(t *testing.T) {
+		filters := []repositories.FieldFilter{
+			{Field: "score", Operator: "isNull", Value: true, FieldType: "integer"},
+		}
+		records, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", filters, repositories.DIDFilter{}, 100, "", "")
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		// f3 and f4 have no score field
+		if len(records) != 2 {
+			t.Errorf("got %d records, want 2", len(records))
+		}
+	})
+
+	t.Run("filter with DID omits when empty", func(t *testing.T) {
+		records, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{}, 100, "", "")
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 4 {
+			t.Errorf("got %d records, want 4 (no DID filter)", len(records))
+		}
+	})
+
+	t.Run("filter with DID adds AND did = ? when non-empty", func(t *testing.T) {
+		records, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{EQ: "did:plc:alice"}, 100, "", "")
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 2 {
+			t.Errorf("got %d records, want 2", len(records))
+		}
+		for _, rec := range records {
+			if rec.DID != "did:plc:alice" {
+				t.Errorf("unexpected DID %q, want did:plc:alice", rec.DID)
+			}
+		}
+	})
+
+	t.Run("filter with DID and field filter combined", func(t *testing.T) {
+		filters := []repositories.FieldFilter{
+			{Field: "text", Operator: "contains", Value: "hello", FieldType: "string"},
+		}
+		records, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", filters, repositories.DIDFilter{EQ: "did:plc:alice"}, 100, "", "")
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 1 {
+			t.Fatalf("got %d records, want 1", len(records))
+		}
+		if records[0].URI != "at://did:plc:alice/app.bsky.feed.post/f1" {
+			t.Errorf("unexpected URI %q", records[0].URI)
+		}
+	})
+
+	t.Run("pagination with filters", func(t *testing.T) {
+		filters := []repositories.FieldFilter{
+			{Field: "text", Operator: "contains", Value: "hello", FieldType: "string"},
+		}
+		// f3 (2026-01-15T12:00:00Z) and f1 (2026-01-15T10:00:00Z) contain "hello"
+		// First page: limit 1 → f3 (newest)
+		page1, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", filters, repositories.DIDFilter{}, 1, "", "")
+		if err != nil {
+			t.Fatalf("page1 error: %v", err)
+		}
+		if len(page1) != 1 {
+			t.Fatalf("page1: got %d records, want 1", len(page1))
+		}
+		if page1[0].URI != "at://did:plc:bob/app.bsky.feed.post/f3" {
+			t.Errorf("page1[0] URI = %q, want f3", page1[0].URI)
+		}
+
+		// Second page using cursor from f3
+		afterTS := page1[0].IndexedAt.UTC().Format("2006-01-02T15:04:05Z")
+		page2, err := repo.GetByCollectionFilteredWithKeysetCursor(ctx, "app.bsky.feed.post", filters, repositories.DIDFilter{}, 1, afterTS, page1[0].URI)
+		if err != nil {
+			t.Fatalf("page2 error: %v", err)
+		}
+		if len(page2) != 1 {
+			t.Fatalf("page2: got %d records, want 1", len(page2))
+		}
+		if page2[0].URI != "at://did:plc:alice/app.bsky.feed.post/f1" {
+			t.Errorf("page2[0] URI = %q, want f1", page2[0].URI)
+		}
+	})
+}
+
 func TestRecordsRepository_IterateAll(t *testing.T) {
 	t.Run("empty database returns 0 processed", func(t *testing.T) {
 		repo := setupRecordsTest(t)
@@ -962,3 +1096,352 @@ func TestRecordsRepository_IterateAll(t *testing.T) {
 		}
 	})
 }
+
+func TestRecordsRepository_Search(t *testing.T) {
+	tests := []struct {
+		name           string
+		setup          func(*repositories.RecordsRepository)
+		query          string
+		collection     string
+		limit          int
+		afterTimestamp string
+		afterURI       string
+		wantCount      int
+		wantURIs       []string
+	}{
+		{
+			name: "returns records containing search term",
+			setup: func(repo *repositories.RecordsRepository) {
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sr1", "bafyreisr1", "did:plc:test1", "app.bsky.feed.post", `{"text":"hello world"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sr2", "bafyreisr2", "did:plc:test1", "app.bsky.feed.post", `{"text":"goodbye world"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sr3", "bafyreisr3", "did:plc:test1", "app.bsky.feed.post", `{"text":"hello again"}`)
+			},
+			query:     "hello",
+			limit:     10,
+			wantCount: 2,
+		},
+		{
+			name: "search with collection filter narrows results",
+			setup: func(repo *repositories.RecordsRepository) {
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sc1", "bafyreisc1", "did:plc:test1", "app.bsky.feed.post", `{"text":"hello post"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.like/sc2", "bafyreisc2", "did:plc:test1", "app.bsky.feed.like", `{"text":"hello like"}`)
+			},
+			query:      "hello",
+			collection: "app.bsky.feed.post",
+			limit:      10,
+			wantCount:  1,
+		},
+		{
+			name: "search returns no results when term not found",
+			setup: func(repo *repositories.RecordsRepository) {
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sn1", "bafyreisn1", "did:plc:test1", "app.bsky.feed.post", `{"text":"nothing here"}`)
+			},
+			query:     "xyzzy",
+			limit:     10,
+			wantCount: 0,
+		},
+		{
+			name: "search is case-insensitive",
+			setup: func(repo *repositories.RecordsRepository) {
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/si1", "bafyreisi1", "did:plc:test1", "app.bsky.feed.post", `{"text":"Hello World"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/si2", "bafyreisi2", "did:plc:test1", "app.bsky.feed.post", `{"text":"HELLO WORLD"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/si3", "bafyreisi3", "did:plc:test1", "app.bsky.feed.post", `{"text":"hello world"}`)
+			},
+			query:     "hello",
+			limit:     10,
+			wantCount: 3,
+		},
+		{
+			name: "search with pagination limit",
+			setup: func(repo *repositories.RecordsRepository) {
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sp1", "bafyreisp1", "did:plc:test1", "app.bsky.feed.post", `{"text":"paginate me one"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sp2", "bafyreisp2", "did:plc:test1", "app.bsky.feed.post", `{"text":"paginate me two"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sp3", "bafyreisp3", "did:plc:test1", "app.bsky.feed.post", `{"text":"paginate me three"}`)
+			},
+			query:     "paginate",
+			limit:     2,
+			wantCount: 2,
+		},
+		{
+			name: "search escapes percent wildcard in query",
+			setup: func(repo *repositories.RecordsRepository) {
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sw1", "bafyreisw1", "did:plc:test1", "app.bsky.feed.post", `{"text":"100% complete"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/sw2", "bafyreisw2", "did:plc:test1", "app.bsky.feed.post", `{"text":"anything else"}`)
+			},
+			query:     "100%",
+			limit:     10,
+			wantCount: 1,
+		},
+		{
+			name: "search escapes underscore wildcard in query",
+			setup: func(repo *repositories.RecordsRepository) {
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/su1", "bafyreisu1", "did:plc:test1", "app.bsky.feed.post", `{"text":"hello_world"}`)
+				insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/su2", "bafyreisu2", "did:plc:test1", "app.bsky.feed.post", `{"text":"helloXworld"}`)
+			},
+			query:     "hello_world",
+			limit:     10,
+			wantCount: 1,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			repo := setupRecordsTest(t)
+			ctx := context.Background()
+
+			if tt.setup != nil {
+				tt.setup(repo)
+			}
+
+			records, err := repo.Search(ctx, tt.query, tt.collection, tt.limit, tt.afterTimestamp, tt.afterURI)
+			if err != nil {
+				t.Fatalf("Search() error: %v", err)
+			}
+			if len(records) != tt.wantCount {
+				t.Errorf("Search() returned %d records, want %d", len(records), tt.wantCount)
+			}
+
+			// Verify specific URIs if provided
+			if len(tt.wantURIs) > 0 {
+				uriSet := make(map[string]bool)
+				for _, rec := range records {
+					uriSet[rec.URI] = true
+				}
+				for _, uri := range tt.wantURIs {
+					if !uriSet[uri] {
+						t.Errorf("Search() missing expected URI %s", uri)
+					}
+				}
+			}
+		})
+	}
+}
+
+func TestRecordsRepository_Search_Pagination(t *testing.T) {
+	env := setupRecordsTestEnv(t)
+	repo := env.repo
+	ctx := context.Background()
+
+	sqlDB := env.db.Executor.DB()
+
+	// Insert records with distinct indexed_at timestamps
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/pg1", "bafyreipg1", "did:plc:test1", "app.bsky.feed.post", `{"text":"search term alpha"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T10:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/pg1'`)
+
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/pg2", "bafyreipg2", "did:plc:test1", "app.bsky.feed.post", `{"text":"search term beta"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T11:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/pg2'`)
+
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/pg3", "bafyreipg3", "did:plc:test1", "app.bsky.feed.post", `{"text":"search term gamma"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T12:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/pg3'`)
+
+	t.Run("first page returns newest first", func(t *testing.T) {
+		records, err := repo.Search(ctx, "search term", "", 2, "", "")
+		if err != nil {
+			t.Fatalf("Search() error: %v", err)
+		}
+		if len(records) != 2 {
+			t.Fatalf("got %d records, want 2", len(records))
+		}
+		// Newest first: pg3, pg2
+		if records[0].URI != "at://did:plc:test1/app.bsky.feed.post/pg3" {
+			t.Errorf("first record URI = %q, want pg3", records[0].URI)
+		}
+		if records[1].URI != "at://did:plc:test1/app.bsky.feed.post/pg2" {
+			t.Errorf("second record URI = %q, want pg2", records[1].URI)
+		}
+	})
+
+	t.Run("second page with keyset cursor returns older records", func(t *testing.T) {
+		// Cursor after pg2 (indexed_at=2026-01-15T11:00:00Z)
+		records, err := repo.Search(ctx, "search term", "", 10,
+			"2026-01-15T11:00:00Z", "at://did:plc:test1/app.bsky.feed.post/pg2")
+		if err != nil {
+			t.Fatalf("Search() error: %v", err)
+		}
+		if len(records) != 1 {
+			t.Fatalf("got %d records, want 1", len(records))
+		}
+		if records[0].URI != "at://did:plc:test1/app.bsky.feed.post/pg1" {
+			t.Errorf("record URI = %q, want pg1", records[0].URI)
+		}
+	})
+}
+
+func TestRecordsRepository_GetByCollectionReversedWithKeysetCursor(t *testing.T) {
+	env := setupRecordsTestEnv(t)
+	repo := env.repo
+	ctx := context.Background()
+
+	sqlDB := env.db.Executor.DB()
+
+	// Insert 5 records with distinct indexed_at timestamps (oldest = r1, newest = r5)
+	// Default DESC order: r5, r4, r3, r2, r1
+	// Backward pagination (last N) returns the last N edges in the connection.
+	// "last 3" without cursor returns r3, r2, r1 (the 3 oldest in DESC order).
+	// "last 2, before r1" returns r3, r2 (the 2 edges just before r1 in the DESC connection).
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/r1", "bafyreir1", "did:plc:test1", "app.bsky.feed.post", `{"text":"r1"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T10:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/r1'`)
+
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/r2", "bafyreir2", "did:plc:test1", "app.bsky.feed.post", `{"text":"r2"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T11:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/r2'`)
+
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/r3", "bafyreir3", "did:plc:test1", "app.bsky.feed.post", `{"text":"r3"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T12:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/r3'`)
+
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/r4", "bafyreir4", "did:plc:test1", "app.bsky.feed.post", `{"text":"r4"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T13:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/r4'`)
+
+	insertTestRecord(t, repo, "at://did:plc:test1/app.bsky.feed.post/r5", "bafyreir5", "did:plc:test1", "app.bsky.feed.post", `{"text":"r5"}`)
+	_, _ = sqlDB.ExecContext(ctx, `UPDATE record SET indexed_at = '2026-01-15T14:00:00Z' WHERE uri = 'at://did:plc:test1/app.bsky.feed.post/r5'`)
+
+	t.Run("last 3 without cursor returns oldest 3 in DESC order", func(t *testing.T) {
+		// Default DESC order: r5, r4, r3, r2, r1
+		// last 3 = r3, r2, r1 (the last 3 edges in the connection)
+		// Algorithm: reversed sort=ASC, LIMIT 3 → r1,r2,r3 → reverse → r3,r2,r1
+		records, err := repo.GetByCollectionReversedWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{}, nil, 3, nil)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 3 {
+			t.Fatalf("got %d records, want 3", len(records))
+		}
+		// Result in DESC order: r3, r2, r1
+		if records[0].URI != "at://did:plc:test1/app.bsky.feed.post/r3" {
+			t.Errorf("records[0].URI = %q, want r3", records[0].URI)
+		}
+		if records[1].URI != "at://did:plc:test1/app.bsky.feed.post/r2" {
+			t.Errorf("records[1].URI = %q, want r2", records[1].URI)
+		}
+		if records[2].URI != "at://did:plc:test1/app.bsky.feed.post/r1" {
+			t.Errorf("records[2].URI = %q, want r1", records[2].URI)
+		}
+	})
+
+	t.Run("last N+1 allows hasPreviousPage detection", func(t *testing.T) {
+		// Fetch 4 (last 3 + 1 extra) — should return 4 records
+		// Algorithm: reversed sort=ASC, LIMIT 4 → r1,r2,r3,r4 → reverse → r4,r3,r2,r1
+		records, err := repo.GetByCollectionReversedWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{}, nil, 4, nil)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		// 4 records returned means there are more (hasPreviousPage = true when caller uses last=3)
+		if len(records) != 4 {
+			t.Fatalf("got %d records, want 4", len(records))
+		}
+	})
+
+	t.Run("before r1 returns edges before r1 in DESC connection", func(t *testing.T) {
+		// DESC connection: r5, r4, r3, r2, r1
+		// "before r1" = edges that come before r1 in the list = r5, r4, r3, r2
+		// Algorithm: reversed sort=ASC, comparison=>, WHERE indexed_at > 10:00
+		//   → r2,r3,r4,r5 → reverse → r5,r4,r3,r2
+		beforeCursor := []string{"2026-01-15T10:00:00Z", "at://did:plc:test1/app.bsky.feed.post/r1"}
+		records, err := repo.GetByCollectionReversedWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{}, nil, 10, beforeCursor)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 4 {
+			t.Fatalf("got %d records, want 4", len(records))
+		}
+		// Result in DESC order: r5, r4, r3, r2
+		if records[0].URI != "at://did:plc:test1/app.bsky.feed.post/r5" {
+			t.Errorf("records[0].URI = %q, want r5", records[0].URI)
+		}
+		if records[3].URI != "at://did:plc:test1/app.bsky.feed.post/r2" {
+			t.Errorf("records[3].URI = %q, want r2", records[3].URI)
+		}
+	})
+
+	t.Run("last 2 before r1 returns 2 edges just before r1", func(t *testing.T) {
+		// DESC connection: r5, r4, r3, r2, r1
+		// "before r1" = r5, r4, r3, r2; last 2 = r3, r2
+		// Algorithm: reversed sort=ASC, comparison=>, WHERE indexed_at > 10:00, LIMIT 2
+		//   → r2,r3 → reverse → r3,r2
+		beforeCursor := []string{"2026-01-15T10:00:00Z", "at://did:plc:test1/app.bsky.feed.post/r1"}
+		records, err := repo.GetByCollectionReversedWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{}, nil, 2, beforeCursor)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 2 {
+			t.Fatalf("got %d records, want 2", len(records))
+		}
+		// Result in DESC order: r3, r2 (the 2 edges just before r1)
+		if records[0].URI != "at://did:plc:test1/app.bsky.feed.post/r3" {
+			t.Errorf("records[0].URI = %q, want r3", records[0].URI)
+		}
+		if records[1].URI != "at://did:plc:test1/app.bsky.feed.post/r2" {
+			t.Errorf("records[1].URI = %q, want r2", records[1].URI)
+		}
+	})
+
+	t.Run("all records returned when limit exceeds total", func(t *testing.T) {
+		// Algorithm: reversed sort=ASC, LIMIT 100 → r1,r2,r3,r4,r5 → reverse → r5,r4,r3,r2,r1
+		records, err := repo.GetByCollectionReversedWithKeysetCursor(ctx, "app.bsky.feed.post", nil, repositories.DIDFilter{}, nil, 100, nil)
+		if err != nil {
+			t.Fatalf("error: %v", err)
+		}
+		if len(records) != 5 {
+			t.Fatalf("got %d records, want 5", len(records))
+		}
+		// Should be in DESC order: r5, r4, r3, r2, r1
+		if records[0].URI != "at://did:plc:test1/app.bsky.feed.post/r5" {
+			t.Errorf("records[0].URI = %q, want r5", records[0].URI)
+		}
+		if records[4].URI != "at://did:plc:test1/app.bsky.feed.post/r1" {
+			t.Errorf("records[4].URI = %q, want r1", records[4].URI)
+		}
+	})
+}
+
+// TestSearchTimeout verifies that the Search method applies a context deadline.
+func TestSearchTimeout(t *testing.T) {
+	tests := []struct {
+		name        string
+		ctxTimeout  time.Duration
+		wantTimeout bool
+	}{
+		{
+			name:        "already-cancelled context returns error immediately",
+			ctxTimeout:  0, // will be cancelled before call
+			wantTimeout: true,
+		},
+		{
+			name:        "context with ample time succeeds",
+			ctxTimeout:  30 * time.Second,
+			wantTimeout: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			repo := setupRecordsTest(t)
+
+			ctx, cancel := context.WithTimeout(context.Background(), repositories.SearchTimeout)
+			defer cancel()
+
+			// Verify that the Search method wraps the context with a deadline.
+			// We do this by checking that a pre-cancelled context causes an error.
+			if tt.wantTimeout {
+				cancelledCtx, cancelFn := context.WithCancel(context.Background())
+				cancelFn() // cancel immediately
+				_, err := repo.Search(cancelledCtx, "hello", "", 10, "", "")
+				if err == nil {
+					t.Error("Search() with cancelled context should return an error, got nil")
+				}
+			} else {
+				// Normal call with a fresh context should succeed (even with empty results).
+				_, err := repo.Search(ctx, "hello", "", 10, "", "")
+				if err != nil {
+					t.Errorf("Search() with valid context returned unexpected error: %v", err)
+				}
+			}
+		})
+	}
+
+	// Verify the exported constant value.
+	t.Run("SearchTimeout constant is 10 seconds", func(t *testing.T) {
+		if repositories.SearchTimeout != 10*time.Second {
+			t.Errorf("SearchTimeout = %v, want 10s", repositories.SearchTimeout)
+		}
+	})
+}
diff --git a/internal/graphql/admin/schema.go b/internal/graphql/admin/schema.go
index 93ab7d0..160359b 100644
--- a/internal/graphql/admin/schema.go
+++ b/internal/graphql/admin/schema.go
@@ -58,11 +58,8 @@ func (b *SchemaBuilder) buildQueryType() *graphql.Object {
 			},
 			"statistics": &graphql.Field{
 				Type:        graphql.NewNonNull(StatisticsType),
-				Description: "Get system statistics (admin only)",
+				Description: "Get system statistics (public)",
 				Resolve: func(p graphql.ResolveParams) (interface{}, error) {
-					if err := requireAdmin(p.Context); err != nil {
-						return nil, err
-					}
 					return b.resolver.Statistics(p.Context)
 				},
 			},
@@ -108,7 +105,7 @@ func (b *SchemaBuilder) buildQueryType() *graphql.Object {
 			},
 			"activityBuckets": &graphql.Field{
 				Type:        graphql.NewNonNull(graphql.NewList(graphql.NewNonNull(ActivityBucketType))),
-				Description: "Get aggregated activity data for a time range (admin only)",
+				Description: "Get aggregated activity data for a time range (public)",
 				Args: graphql.FieldConfigArgument{
 					"range": &graphql.ArgumentConfig{
 						Type:        graphql.NewNonNull(TimeRangeEnum),
@@ -116,16 +113,13 @@ func (b *SchemaBuilder) buildQueryType() *graphql.Object {
 					},
 				},
 				Resolve: func(p graphql.ResolveParams) (interface{}, error) {
-					if err := requireAdmin(p.Context); err != nil {
-						return nil, err
-					}
 					timeRange, _ := p.Args["range"].(string)
 					return b.resolver.ActivityBuckets(p.Context, timeRange)
 				},
 			},
 			"recentActivity": &graphql.Field{
 				Type:        graphql.NewNonNull(graphql.NewList(graphql.NewNonNull(ActivityEntryType))),
-				Description: "Get recent activity entries (admin only)",
+				Description: "Get recent activity entries (public)",
 				Args: graphql.FieldConfigArgument{
 					"hours": &graphql.ArgumentConfig{
 						Type:         graphql.NewNonNull(graphql.Int),
@@ -134,9 +128,6 @@ func (b *SchemaBuilder) buildQueryType() *graphql.Object {
 					},
 				},
 				Resolve: func(p graphql.ResolveParams) (interface{}, error) {
-					if err := requireAdmin(p.Context); err != nil {
-						return nil, err
-					}
 					hours, _ := p.Args["hours"].(int)
 					if hours < 1 {
 						hours = 1
diff --git a/internal/graphql/query/connection.go b/internal/graphql/query/connection.go
index a943b60..1fd6186 100644
--- a/internal/graphql/query/connection.go
+++ b/internal/graphql/query/connection.go
@@ -5,6 +5,24 @@ import (
 	"github.com/graphql-go/graphql"
 )
 
+const (
+	// DefaultPageSize is the number of records returned when no first argument is provided.
+	DefaultPageSize = 20
+	// MaxPageSize is the maximum number of records that can be requested in a single page.
+	MaxPageSize = 100
+)
+
+// ClampPageSize returns a valid page size within [1, MaxPageSize], defaulting to DefaultPageSize.
+func ClampPageSize(first int) int {
+	if first <= 0 {
+		return DefaultPageSize
+	}
+	if first > MaxPageSize {
+		return MaxPageSize
+	}
+	return first
+}
+
 // PageInfoType defines the Relay-style pagination info GraphQL type.
 var PageInfoType = graphql.NewObject(graphql.ObjectConfig{
 	Name:        "PageInfo",
@@ -29,7 +47,7 @@ var PageInfoType = graphql.NewObject(graphql.ObjectConfig{
 	},
 })
 
-// ConnectionArgs returns standard Relay connection arguments for forward pagination.
+// ConnectionArgs returns standard Relay connection arguments for forward and backward pagination.
 func ConnectionArgs() graphql.FieldConfigArgument {
 	return graphql.FieldConfigArgument{
 		"first": &graphql.ArgumentConfig{
@@ -40,6 +58,14 @@ func ConnectionArgs() graphql.FieldConfigArgument {
 			Type:        graphql.String,
 			Description: "Cursor to start after (forward pagination)",
 		},
+		"last": &graphql.ArgumentConfig{
+			Type:        graphql.Int,
+			Description: "Number of items to return from the end",
+		},
+		"before": &graphql.ArgumentConfig{
+			Type:        graphql.String,
+			Description: "Cursor to paginate before (backward pagination)",
+		},
 	}
 }
 
@@ -61,6 +87,61 @@ func BuildEdgeType(nodeType *graphql.Object) *graphql.Object {
 	})
 }
 
+// SortDirectionEnum defines the sort direction for collection queries.
+var SortDirectionEnum = graphql.NewEnum(graphql.EnumConfig{
+	Name:        "SortDirection",
+	Description: "Sort direction",
+	Values: graphql.EnumValueConfigMap{
+		"ASC":  &graphql.EnumValueConfig{Value: "ASC", Description: "Ascending order"},
+		"DESC": &graphql.EnumValueConfig{Value: "DESC", Description: "Descending order (default)"},
+	},
+})
+
+// SortableProperty holds the name and type info needed to build a sort enum.
+type SortableProperty struct {
+	Name   string
+	Type   string
+	Format string
+}
+
+// isSortableProperty returns true if the given property type is sortable.
+// Only scalar types are sortable: string (any format), integer, number, boolean.
+func isSortableProperty(propType string) bool {
+	switch propType {
+	case "string", "integer", "number", "boolean":
+		return true
+	default:
+		return false
+	}
+}
+
+// BuildSortFieldEnum creates a per-collection enum of fields that can be used for sorting.
+// Only scalar types are sortable (string, integer, number, boolean).
+// Always includes "indexed_at" as a sortable meta-field.
+func BuildSortFieldEnum(typeName string, properties []SortableProperty) *graphql.Enum {
+	values := graphql.EnumValueConfigMap{
+		"indexed_at": &graphql.EnumValueConfig{
+			Value:       "indexed_at",
+			Description: "Sort by the time the record was indexed",
+		},
+	}
+
+	for _, prop := range properties {
+		if isSortableProperty(prop.Type) {
+			values[prop.Name] = &graphql.EnumValueConfig{
+				Value:       prop.Name,
+				Description: "Sort by " + prop.Name,
+			}
+		}
+	}
+
+	return graphql.NewEnum(graphql.EnumConfig{
+		Name:        typeName + "SortField",
+		Description: "Fields available for sorting " + typeName + " records",
+		Values:      values,
+	})
+}
+
 // BuildConnectionType creates a Connection type for a given node type.
 func BuildConnectionType(nodeType *graphql.Object) *graphql.Object {
 	edgeType := BuildEdgeType(nodeType)
diff --git a/internal/graphql/query/connection_test.go b/internal/graphql/query/connection_test.go
new file mode 100644
index 0000000..08b7ba3
--- /dev/null
+++ b/internal/graphql/query/connection_test.go
@@ -0,0 +1,71 @@
+// Package query provides GraphQL query type building.
+package query
+
+import (
+	"testing"
+)
+
+// TestClampPageSize verifies that ClampPageSize returns a valid page size
+// within [1, MaxPageSize], defaulting to DefaultPageSize for non-positive inputs.
+func TestClampPageSize(t *testing.T) {
+	tests := []struct {
+		name  string
+		input int
+		want  int
+	}{
+		{
+			name:  "zero returns default",
+			input: 0,
+			want:  DefaultPageSize,
+		},
+		{
+			name:  "negative returns default",
+			input: -1,
+			want:  DefaultPageSize,
+		},
+		{
+			name:  "large negative returns default",
+			input: -100,
+			want:  DefaultPageSize,
+		},
+		{
+			name:  "one returns one",
+			input: 1,
+			want:  1,
+		},
+		{
+			name:  "default page size returns default page size",
+			input: DefaultPageSize,
+			want:  DefaultPageSize,
+		},
+		{
+			name:  "50 returns 50",
+			input: 50,
+			want:  50,
+		},
+		{
+			name:  "max page size returns max page size",
+			input: MaxPageSize,
+			want:  MaxPageSize,
+		},
+		{
+			name:  "one over max returns max",
+			input: MaxPageSize + 1,
+			want:  MaxPageSize,
+		},
+		{
+			name:  "200 returns max",
+			input: 200,
+			want:  MaxPageSize,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ClampPageSize(tt.input)
+			if got != tt.want {
+				t.Errorf("ClampPageSize(%d) = %d, want %d", tt.input, got, tt.want)
+			}
+		})
+	}
+}
diff --git a/internal/graphql/schema/builder.go b/internal/graphql/schema/builder.go
index ad9f317..7be57b1 100644
--- a/internal/graphql/schema/builder.go
+++ b/internal/graphql/schema/builder.go
@@ -7,9 +7,12 @@ import (
 	"encoding/json"
 	"errors"
 	"fmt"
+	"log/slog"
 	"strings"
+	"unicode/utf8"
 
 	"github.com/graphql-go/graphql"
+	"github.com/graphql-go/graphql/language/ast"
 
 	"github.com/GainForest/hypergoat/internal/database/repositories"
 	"github.com/GainForest/hypergoat/internal/graphql/query"
@@ -26,8 +29,10 @@ type Builder struct {
 	objectBuilder *types.ObjectBuilder
 
 	// Built types
-	recordTypes     map[string]*graphql.Object // lexiconID -> record type
-	connectionTypes map[string]*graphql.Object // lexiconID -> connection type
+	recordTypes     map[string]*graphql.Object      // lexiconID -> record type
+	connectionTypes map[string]*graphql.Object      // lexiconID -> connection type
+	sortFieldEnums  map[string]*graphql.Enum        // lexiconID -> sort field enum
+	whereInputTypes map[string]*graphql.InputObject // lexiconID -> where input type
 }
 
 // NewBuilder creates a new schema builder.
@@ -39,6 +44,8 @@ func NewBuilder(registry *lexicon.Registry) *Builder {
 		objectBuilder:   types.NewObjectBuilder(mapper, registry),
 		recordTypes:     make(map[string]*graphql.Object),
 		connectionTypes: make(map[string]*graphql.Object),
+		sortFieldEnums:  make(map[string]*graphql.Enum),
+		whereInputTypes: make(map[string]*graphql.InputObject),
 	}
 }
 
@@ -50,9 +57,15 @@ func (b *Builder) Build() (*graphql.Schema, error) {
 	// Phase 2: Build all record types
 	b.buildRecordTypes()
 
+	// Phase 2b: Build per-collection WhereInput types
+	b.buildWhereInputTypes()
+
 	// Phase 3: Build connection types
 	b.buildConnectionTypes()
 
+	// Phase 3b: Build sort field enums for each collection
+	b.buildSortFieldEnums()
+
 	// Phase 4: Build Query type
 	queryType := b.buildQueryType()
 
@@ -112,6 +125,81 @@ func (b *Builder) buildConnectionTypes() {
 	}
 }
 
+// buildSortFieldEnums builds per-collection sort field enums from lexicon properties.
+func (b *Builder) buildSortFieldEnums() {
+	for _, lex := range b.registry.GetCollectionLexicons() {
+		if lex.Defs.Main == nil {
+			continue
+		}
+
+		recordType, ok := b.recordTypes[lex.ID]
+		if !ok {
+			continue
+		}
+
+		// Collect sortable properties from the lexicon's main record definition
+		var sortableProps []query.SortableProperty
+		for _, entry := range lex.Defs.Main.Properties {
+			sortableProps = append(sortableProps, query.SortableProperty{
+				Name:   entry.Name,
+				Type:   entry.Property.Type,
+				Format: entry.Property.Format,
+			})
+		}
+
+		sortEnum := query.BuildSortFieldEnum(recordType.Name(), sortableProps)
+		b.sortFieldEnums[lex.ID] = sortEnum
+	}
+}
+
+// buildWhereInputTypes builds per-collection WhereInput GraphQL InputObject types.
+// For each collection lexicon, it creates a WhereInput type with a field for each
+// filterable property (string, integer, number, boolean, datetime) plus a `did` field.
+func (b *Builder) buildWhereInputTypes() {
+	for _, lex := range b.registry.GetCollectionLexicons() {
+		if lex.Defs.Main == nil {
+			continue
+		}
+
+		typeName := lexicon.ToTypeName(lex.ID) + "WhereInput"
+		fields := graphql.InputObjectConfigFieldMap{}
+
+		// Always include did as a filterable metadata field.
+		// Uses DIDFilterInput (restricted to eq and in only) because DID is a
+		// column-level filter — operators like contains/startsWith are not meaningful.
+		fields["did"] = &graphql.InputObjectFieldConfig{
+			Type:        types.DIDFilterInput,
+			Description: "Filter by DID (record author)",
+		}
+
+		// Add a field for each filterable property
+		for _, entry := range lex.Defs.Main.Properties {
+			if entry.Name == "did" {
+				continue // did is handled separately as a metadata filter
+			}
+			if types.ReservedRecordFields[entry.Name] {
+				continue // Skip properties that collide with reserved metadata fields
+			}
+			filterInput := types.FilterInputForLexiconType(entry.Property.Type, entry.Property.Format)
+			if filterInput == nil {
+				continue // Non-filterable type (array, ref, union, blob, unknown, etc.)
+			}
+			fields[entry.Name] = &graphql.InputObjectFieldConfig{
+				Type:        filterInput,
+				Description: fmt.Sprintf("Filter by %s", entry.Name),
+			}
+		}
+
+		whereInput := graphql.NewInputObject(graphql.InputObjectConfig{
+			Name:        typeName,
+			Description: fmt.Sprintf("Filter conditions for %s queries", lex.ID),
+			Fields:      fields,
+		})
+
+		b.whereInputTypes[lex.ID] = whereInput
+	}
+}
+
 // RecordEvent GraphQL type for subscriptions
 var recordEventType = graphql.NewObject(graphql.ObjectConfig{
 	Name:        "RecordEvent",
@@ -244,6 +332,9 @@ func (b *Builder) buildSubscriptionType() *graphql.Object {
 				if event.Collection != collection {
 					return nil, nil
 				}
+				if event.Record != nil {
+					b.coerceRequiredFields(event.Record, collection)
+				}
 				return event.Record, nil
 			},
 		}
@@ -300,8 +391,9 @@ var genericRecordEdgeType = graphql.NewObject(graphql.ObjectConfig{
 var genericRecordConnectionType = graphql.NewObject(graphql.ObjectConfig{
 	Name: "GenericRecordConnection",
 	Fields: graphql.Fields{
-		"edges":    &graphql.Field{Type: graphql.NewList(genericRecordEdgeType)},
-		"pageInfo": &graphql.Field{Type: query.PageInfoType},
+		"edges":      &graphql.Field{Type: graphql.NewList(genericRecordEdgeType)},
+		"pageInfo":   &graphql.Field{Type: query.PageInfoType},
+		"totalCount": &graphql.Field{Type: graphql.Int, Description: "Total number of items (if known)"},
 	},
 })
 
@@ -319,18 +411,49 @@ func (b *Builder) buildQueryType() *graphql.Object {
 				Description: "Collection NSID (e.g., org.impactindexer.review.like)",
 			},
 			"first": &graphql.ArgumentConfig{
-				Type:         graphql.Int,
-				DefaultValue: 20,
-				Description:  "Number of records to return",
+				Type:        graphql.Int,
+				Description: "Number of records to return (default 20, max 100)",
 			},
 			"after": &graphql.ArgumentConfig{
 				Type:        graphql.String,
-				Description: "Cursor for pagination",
+				Description: "Cursor for forward pagination",
+			},
+			"last": &graphql.ArgumentConfig{
+				Type:        graphql.Int,
+				Description: "Number of items to return from the end",
+			},
+			"before": &graphql.ArgumentConfig{
+				Type:        graphql.String,
+				Description: "Cursor to paginate before (backward pagination)",
 			},
 		},
 		Resolve: b.createGenericRecordsResolver(),
 	}
 
+	// Add search query for cross-collection text search
+	fields["search"] = &graphql.Field{
+		Type:        genericRecordConnectionType,
+		Description: "Search records by text content",
+		Args: graphql.FieldConfigArgument{
+			"query": &graphql.ArgumentConfig{
+				Type:        graphql.NewNonNull(graphql.String),
+				Description: "Search text (matched against record JSON content)",
+			},
+			"collection": &graphql.ArgumentConfig{
+				Type:        graphql.String,
+				Description: "Optional collection NSID to restrict search",
+			},
+			"first": &graphql.ArgumentConfig{
+				Type:         graphql.Int,
+				DefaultValue: 20,
+			},
+			"after": &graphql.ArgumentConfig{
+				Type: graphql.String,
+			},
+		},
+		Resolve: b.createSearchResolver(),
+	}
+
 	// Add collectionStats query for efficient aggregate counts
 	fields["collectionStats"] = &graphql.Field{
 		Type:        graphql.NewNonNull(graphql.NewList(graphql.NewNonNull(collectionStatType))),
@@ -360,10 +483,29 @@ func (b *Builder) buildQueryType() *graphql.Object {
 	for lexiconID, connectionType := range b.connectionTypes {
 		fieldName := lexicon.ToFieldName(lexiconID)
 
+		// Build args: start with standard connection args, then add sort args if available
+		args := query.ConnectionArgs()
+		if sortEnum, ok := b.sortFieldEnums[lexiconID]; ok {
+			args["sortBy"] = &graphql.ArgumentConfig{
+				Type:        sortEnum,
+				Description: "Field to sort by (default: indexed_at)",
+			}
+			args["sortDirection"] = &graphql.ArgumentConfig{
+				Type:        query.SortDirectionEnum,
+				Description: "Sort direction (default: DESC)",
+			}
+		}
+		if whereInput, ok := b.whereInputTypes[lexiconID]; ok {
+			args["where"] = &graphql.ArgumentConfig{
+				Type:        whereInput,
+				Description: "Filter conditions",
+			}
+		}
+
 		fields[fieldName] = &graphql.Field{
 			Type:        connectionType,
 			Description: fmt.Sprintf("Query %s records", lexiconID),
-			Args:        query.ConnectionArgs(),
+			Args:        args,
 			Resolve:     b.createCollectionResolver(lexiconID),
 		}
 
@@ -391,8 +533,143 @@ func (b *Builder) buildQueryType() *graphql.Object {
 // nodeBuilder transforms a Record and its parsed JSON into a GraphQL node.
 type nodeBuilder func(rec *repositories.Record, value map[string]interface{}) (interface{}, bool)
 
+// extractFilters extracts FieldFilter conditions and an optional DIDFilter from
+// the GraphQL `where` argument. The whereArg is expected to be a
+// map[string]interface{} where each key is a field name and each value is a
+// map[string]interface{} of operator→value pairs (e.g. {"eq": "hello"}).
+//
+// The special key "did" is extracted separately as a DID column filter rather
+// than a JSON field filter. DIDFilterInput only exposes "eq" and "in", so only
+// those operators are handled. All other keys are looked up in the lexicon registry
+// to determine the correct FieldType for SQL casting.
+func extractFilters(whereArg interface{}, lexiconID string, registry *lexicon.Registry) ([]repositories.FieldFilter, repositories.DIDFilter, error) {
+	whereMap, ok := whereArg.(map[string]interface{})
+	if !ok || len(whereMap) == 0 {
+		return nil, repositories.DIDFilter{}, nil
+	}
+
+	var filters []repositories.FieldFilter
+	var didFilter repositories.DIDFilter
+
+	// Look up the record definition once for property type resolution
+	recordDef, _ := registry.GetRecordDef(lexiconID)
+
+	for fieldName, filterVal := range whereMap {
+		filterMap, ok := filterVal.(map[string]interface{})
+		if !ok || filterMap == nil {
+			continue
+		}
+
+		if fieldName == "did" {
+			// DID is a column filter, not a JSON field filter.
+			// DIDFilterInput only exposes "eq" and "in".
+			// The DID filter does not count toward MaxFilterConditions.
+			if eqVal, ok := filterMap["eq"].(string); ok && eqVal != "" {
+				didFilter.EQ = eqVal
+			}
+			if inVals, ok := filterMap["in"].([]interface{}); ok {
+				for _, v := range inVals {
+					if s, ok := v.(string); ok && s != "" {
+						didFilter.IN = append(didFilter.IN, s)
+					}
+				}
+			}
+			continue
+		}
+
+		// Determine the lexicon type for this field so the repository can CAST correctly.
+		fieldType := "string" // default
+		if recordDef != nil {
+			if prop := recordDef.GetProperty(fieldName); prop != nil {
+				if prop.Format == "datetime" {
+					fieldType = "datetime"
+				} else {
+					fieldType = prop.Type
+				}
+			}
+		}
+
+		// Each key in filterMap is an operator (eq, neq, gt, lt, gte, lte, in, contains, startsWith, isNull).
+		for op, val := range filterMap {
+			if val == nil {
+				continue
+			}
+			filters = append(filters, repositories.FieldFilter{
+				Field:     fieldName,
+				Operator:  op,
+				Value:     val,
+				FieldType: fieldType,
+			})
+		}
+	}
+
+	if len(filters) > repositories.MaxFilterConditions {
+		return nil, repositories.DIDFilter{}, fmt.Errorf("too many filter conditions: %d (maximum %d)", len(filters), repositories.MaxFilterConditions)
+	}
+
+	return filters, didFilter, nil
+}
+
+// isTotalCountRequested checks whether the GraphQL query selected the totalCount field.
+// This is used to avoid executing an expensive COUNT query when totalCount is not needed.
+func isTotalCountRequested(p graphql.ResolveParams) bool {
+	for _, field := range p.Info.FieldASTs {
+		if field.SelectionSet == nil {
+			continue
+		}
+		for _, sel := range field.SelectionSet.Selections {
+			if f, ok := sel.(*ast.Field); ok && f.Name.Value == "totalCount" {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// buildSortAwareCursor builds a sort-aware cursor string for a record.
+// directSortCols mirrors the repository's directSortColumns set.
+var directSortCols = map[string]bool{
+	"indexed_at": true,
+	"uri":        true,
+	"did":        true,
+	"collection": true,
+	"cid":        true,
+	"rkey":       true,
+}
+
+// sortFieldValueForRecord extracts the sort field value from a record for cursor building.
+func sortFieldValueForRecord(rec *repositories.Record, value map[string]interface{}, sortOpt *repositories.SortOption) string {
+	if sortOpt == nil {
+		return rec.IndexedAt.Format("2006-01-02T15:04:05Z")
+	}
+	if directSortCols[sortOpt.Field] {
+		switch sortOpt.Field {
+		case "indexed_at":
+			return rec.IndexedAt.Format("2006-01-02T15:04:05Z")
+		case "uri":
+			return rec.URI
+		case "did":
+			return rec.DID
+		case "collection":
+			return rec.Collection
+		case "cid":
+			return rec.CID
+		case "rkey":
+			return rec.RKey
+		default:
+			return rec.IndexedAt.Format("2006-01-02T15:04:05Z")
+		}
+	}
+	// JSON field
+	if v, exists := value[sortOpt.Field]; exists && v != nil {
+		return fmt.Sprintf("%v", v)
+	}
+	return ""
+}
+
 // resolveRecordConnection is the shared implementation for paginated record queries.
-// It uses deterministic keyset pagination with a composite (indexed_at, uri) cursor.
+// It uses deterministic keyset pagination with a composite (sortField, uri) cursor.
+// Supports both forward pagination (first/after) and backward pagination (last/before).
 func (b *Builder) resolveRecordConnection(
 	p graphql.ResolveParams,
 	collection string,
@@ -404,24 +681,134 @@ func (b *Builder) resolveRecordConnection(
 	}
 
 	// Extract pagination args
-	first, _ := p.Args["first"].(int)
-	if first == 0 {
-		first = 20
-	}
+	firstArg, hasFirst := p.Args["first"].(int)
 	after, _ := p.Args["after"].(string)
+	lastArg, hasLast := p.Args["last"].(int)
+	before, _ := p.Args["before"].(string)
+
+	// Validate: cannot use both first/after and last/before
+	if (hasFirst || after != "") && (hasLast || before != "") {
+		return nil, fmt.Errorf("cannot use both first/after and last/before")
+	}
+
+	// Extract where filters if present (typed collection queries only)
+	var filters []repositories.FieldFilter
+	var didFilter repositories.DIDFilter
+	if whereArg, ok := p.Args["where"]; ok && whereArg != nil {
+		var err error
+		filters, didFilter, err = extractFilters(whereArg, collection, b.registry)
+		if err != nil {
+			return nil, err
+		}
+	}
+
+	// Extract sort args if present (typed collection queries only)
+	var sortOpt *repositories.SortOption
+	if sortByArg, ok := p.Args["sortBy"].(string); ok && sortByArg != "" {
+		direction := "DESC" // default
+		if dirArg, ok := p.Args["sortDirection"].(string); ok && dirArg != "" {
+			direction = dirArg
+		}
+		sortOpt = &repositories.SortOption{Field: sortByArg, Direction: direction}
+	}
+
+	// Backward pagination path
+	if hasLast || before != "" {
+		last := query.ClampPageSize(lastArg)
+
+		// Decode before cursor if provided
+		var beforeCursorValues []string
+		if before != "" {
+			parts, err := decodeCursorValues(before)
+			if err != nil {
+				return nil, fmt.Errorf("invalid cursor: %w", err)
+			}
+			if len(parts) != 2 {
+				return nil, fmt.Errorf("invalid cursor: expected 2 components")
+			}
+			beforeCursorValues = parts
+		}
+
+		// Fetch last+1 to detect hasPreviousPage
+		records, err := repos.Records.GetByCollectionReversedWithKeysetCursor(p.Context, collection, filters, didFilter, sortOpt, last+1, beforeCursorValues)
+		if err != nil {
+			return nil, fmt.Errorf("failed to query records: %w", err)
+		}
+
+		// Determine if there are more results before the returned page.
+		// After reversal, the extra record is at the front (oldest end).
+		hasPreviousPage := len(records) > last
+		if hasPreviousPage {
+			records = records[1:]
+		}
+
+		// Build edges
+		edges := make([]interface{}, 0, len(records))
+		var startCursor, endCursor string
+
+		for _, rec := range records {
+			var value map[string]interface{}
+			if err := json.Unmarshal([]byte(rec.JSON), &value); err != nil {
+				slog.Warn("Skipping record with invalid JSON", "uri", rec.URI, "error", err)
+				continue
+			}
+
+			node, ok := buildNode(rec, value)
+			if !ok {
+				continue
+			}
+
+			cursor := encodeCursorValues(sortFieldValueForRecord(rec, value, sortOpt), rec.URI)
+			if startCursor == "" {
+				startCursor = cursor
+			}
+			endCursor = cursor
+
+			edges = append(edges, map[string]interface{}{
+				"cursor": cursor,
+				"node":   node,
+			})
+		}
+
+		result := map[string]interface{}{
+			"edges": edges,
+			"pageInfo": map[string]interface{}{
+				"hasNextPage":     before != "",
+				"hasPreviousPage": hasPreviousPage,
+				"startCursor":     startCursor,
+				"endCursor":       endCursor,
+			},
+		}
+
+		if isTotalCountRequested(p) {
+			count, err := repos.Records.GetCollectionCountFiltered(p.Context, collection, filters, didFilter)
+			if err == nil {
+				result["totalCount"] = int(count)
+			}
+		}
+
+		return result, nil
+	}
+
+	// Forward pagination path (default)
+	first := query.ClampPageSize(firstArg)
 
 	// Decode composite cursor if provided
-	var afterTimestamp, afterURI string
+	var afterCursorValues []string
 	if after != "" {
 		var err error
-		afterTimestamp, afterURI, err = decodeCursor(after)
+		afterCursorValues, err = decodeCursorValues(after)
 		if err != nil {
 			return nil, fmt.Errorf("invalid cursor: %w", err)
 		}
+		// Ensure we have exactly 2 values for keyset pagination
+		if len(afterCursorValues) != 2 {
+			return nil, fmt.Errorf("invalid cursor: expected 2 components")
+		}
 	}
 
-	// Fetch first+1 to determine hasNextPage
-	records, err := repos.Records.GetByCollectionWithKeysetCursor(p.Context, collection, first+1, afterTimestamp, afterURI)
+	// Fetch first+1 to determine hasNextPage using the sorted method
+	records, err := repos.Records.GetByCollectionSortedWithKeysetCursor(p.Context, collection, filters, didFilter, sortOpt, first+1, afterCursorValues)
 	if err != nil {
 		return nil, fmt.Errorf("failed to query records: %w", err)
 	}
@@ -432,14 +819,15 @@ func (b *Builder) resolveRecordConnection(
 		records = records[:first]
 	}
 
-	// Build edges
+	// Build edges with sort-aware cursors
 	edges := make([]interface{}, 0, len(records))
 	var startCursor, endCursor string
 
 	for _, rec := range records {
 		var value map[string]interface{}
 		if err := json.Unmarshal([]byte(rec.JSON), &value); err != nil {
-			continue // Skip records with invalid JSON
+			slog.Warn("Skipping record with invalid JSON", "uri", rec.URI, "error", err)
+			continue
 		}
 
 		node, ok := buildNode(rec, value)
@@ -447,7 +835,7 @@ func (b *Builder) resolveRecordConnection(
 			continue
 		}
 
-		cursor := encodeCursor(rec.IndexedAt.Format("2006-01-02T15:04:05Z"), rec.URI)
+		cursor := encodeCursorValues(sortFieldValueForRecord(rec, value, sortOpt), rec.URI)
 		if startCursor == "" {
 			startCursor = cursor
 		}
@@ -459,7 +847,7 @@ func (b *Builder) resolveRecordConnection(
 		})
 	}
 
-	return map[string]interface{}{
+	result := map[string]interface{}{
 		"edges": edges,
 		"pageInfo": map[string]interface{}{
 			"hasNextPage":     hasNextPage,
@@ -467,7 +855,97 @@ func (b *Builder) resolveRecordConnection(
 			"startCursor":     startCursor,
 			"endCursor":       endCursor,
 		},
-	}, nil
+	}
+
+	if isTotalCountRequested(p) {
+		count, err := repos.Records.GetCollectionCountFiltered(p.Context, collection, filters, didFilter)
+		if err == nil {
+			result["totalCount"] = int(count)
+		}
+	}
+
+	return result, nil
+}
+
+// createSearchResolver creates a resolver for the search query.
+// It validates the query string (minimum 3 runes) and calls the Search repository method.
+func (b *Builder) createSearchResolver() graphql.FieldResolveFn {
+	return func(p graphql.ResolveParams) (interface{}, error) {
+		searchQuery, _ := p.Args["query"].(string)
+		if utf8.RuneCountInString(searchQuery) < 3 {
+			return nil, fmt.Errorf("search query must be at least 3 characters")
+		}
+
+		collection, _ := p.Args["collection"].(string)
+
+		firstArg, _ := p.Args["first"].(int)
+		first := query.ClampPageSize(firstArg)
+
+		after, _ := p.Args["after"].(string)
+
+		var afterTimestamp, afterURI string
+		if after != "" {
+			var err error
+			afterTimestamp, afterURI, err = decodeCursor(after)
+			if err != nil {
+				return nil, fmt.Errorf("invalid cursor: %w", err)
+			}
+		}
+
+		repos := resolver.GetRepositories(p.Context)
+		if repos == nil || repos.Records == nil {
+			return emptyConnection(), nil
+		}
+
+		records, err := repos.Records.Search(p.Context, searchQuery, collection, first+1, afterTimestamp, afterURI)
+		if err != nil {
+			return nil, fmt.Errorf("failed to search records: %w", err)
+		}
+
+		hasNextPage := len(records) > first
+		if hasNextPage {
+			records = records[:first]
+		}
+
+		edges := make([]interface{}, 0, len(records))
+		var startCursor, endCursor string
+
+		for _, rec := range records {
+			var value map[string]interface{}
+			if err := json.Unmarshal([]byte(rec.JSON), &value); err != nil {
+				slog.Warn("Skipping record with invalid JSON", "uri", rec.URI, "error", err)
+				continue
+			}
+
+			cursor := encodeCursor(rec.IndexedAt.Format("2006-01-02T15:04:05Z"), rec.URI)
+			if startCursor == "" {
+				startCursor = cursor
+			}
+			endCursor = cursor
+
+			edges = append(edges, map[string]interface{}{
+				"cursor": cursor,
+				"node": map[string]interface{}{
+					"uri":        rec.URI,
+					"cid":        rec.CID,
+					"did":        rec.DID,
+					"collection": rec.Collection,
+					"rkey":       rec.RKey,
+					"value":      value,
+				},
+			})
+		}
+
+		return map[string]interface{}{
+			"edges": edges,
+			"pageInfo": map[string]interface{}{
+				"hasNextPage":     hasNextPage,
+				"hasPreviousPage": after != "",
+				"startCursor":     startCursor,
+				"endCursor":       endCursor,
+			},
+		}, nil
+	}
 }
 
 // createGenericRecordsResolver creates a resolver for the generic records query.
@@ -492,6 +970,32 @@ func (b *Builder) createGenericRecordsResolver() graphql.FieldResolveFn {
 	}
 }
 
+// coerceRequiredFields fills in zero values for required fields that are missing or null.
+// This prevents NonNull violations when historical records lack fields that became required.
+func (b *Builder) coerceRequiredFields(data map[string]interface{}, collection string) {
+	recordDef, ok := b.registry.GetRecordDef(collection)
+	if !ok {
+		return
+	}
+	for _, entry := range recordDef.RequiredProperties() {
+		val, exists := data[entry.Name]
+		if exists && val != nil {
+			continue
+		}
+		zero := lexicon.ZeroValueForType(entry.Property.Type)
+		if zero == nil {
+			// Complex type (ref, union, blob, etc.) — skip, keep nil
+			continue
+		}
+		slog.Debug("Coercing missing required field to zero value",
+			"collection", collection,
+			"field", entry.Name,
+			"type", entry.Property.Type,
+		)
+		data[entry.Name] = zero
+	}
+}
+
 // createCollectionResolver creates a resolver for querying a typed collection.
 func (b *Builder) createCollectionResolver(lexiconID string) graphql.FieldResolveFn {
 	return func(p graphql.ResolveParams) (interface{}, error) {
@@ -500,6 +1004,9 @@ func (b *Builder) createCollectionResolver(lexiconID string) graphql.FieldResolv
 				// Inject standard record fields into the flat data
 				data["uri"] = rec.URI
 				data["cid"] = rec.CID
+				data["did"] = rec.DID
+				data["rkey"] = rec.RKey
+				b.coerceRequiredFields(data, lexiconID)
 				return data, true
 			})
 	}
@@ -537,6 +1044,9 @@ func (b *Builder) createSingleRecordResolver(lexiconID string) graphql.FieldReso
 		// Add standard record fields
 		data["uri"] = rec.URI
 		data["cid"] = rec.CID
+		data["did"] = rec.DID
+		data["rkey"] = rec.RKey
+		b.coerceRequiredFields(data, lexiconID)
 
 		return data, nil
 	}
@@ -633,18 +1143,45 @@ func emptyConnection() map[string]interface{} {
 	}
 }
 
+// encodeCursorValues encodes multiple cursor component values into a base64 string.
+// Uses JSON array encoding to safely handle values that contain the pipe character.
+func encodeCursorValues(values ...string) string {
+	jsonBytes, _ := json.Marshal(values)
+	return base64.URLEncoding.EncodeToString(jsonBytes)
+}
+
+// decodeCursorValues decodes a base64 cursor into its component values.
+// Supports both the current JSON array format and the legacy pipe-delimited format
+// for backward compatibility with cursors issued before the JSON encoding change.
+func decodeCursorValues(cursor string) ([]string, error) {
+	data, err := base64.URLEncoding.DecodeString(cursor)
+	if err != nil {
+		return nil, fmt.Errorf("invalid cursor")
+	}
+	var parts []string
+	if err := json.Unmarshal(data, &parts); err != nil {
+		// Backward compatibility: try legacy pipe-delimited format.
+		parts = strings.Split(string(data), "|")
+		if len(parts) < 2 {
+			return nil, fmt.Errorf("invalid cursor format")
+		}
+	}
+	return parts, nil
+}
+
 // encodeCursor encodes a composite (indexed_at, uri) cursor as base64.
+// Kept for backward compatibility; delegates to encodeCursorValues.
 func encodeCursor(indexedAt, uri string) string {
-	return base64.URLEncoding.EncodeToString([]byte(indexedAt + "|" + uri))
+	return encodeCursorValues(indexedAt, uri)
 }
 
 // decodeCursor decodes a base64 cursor into (indexed_at, uri) components.
+// Kept for backward compatibility; delegates to decodeCursorValues.
 func decodeCursor(cursor string) (string, string, error) {
-	data, err := base64.URLEncoding.DecodeString(cursor)
+	parts, err := decodeCursorValues(cursor)
 	if err != nil {
 		return "", "", err
 	}
-	parts := strings.SplitN(string(data), "|", 2)
 	if len(parts) != 2 {
 		return "", "", fmt.Errorf("malformed cursor: expected 'timestamp|uri'")
 	}
diff --git a/internal/graphql/schema/builder_test.go b/internal/graphql/schema/builder_test.go
index 93d9e60..c6e764d 100644
--- a/internal/graphql/schema/builder_test.go
+++ b/internal/graphql/schema/builder_test.go
@@ -2,14 +2,21 @@ package schema
 
 import (
 	"context"
+	"encoding/base64"
 	"encoding/json"
+	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
+	"time"
 
 	"github.com/graphql-go/graphql"
 
+	"github.com/GainForest/hypergoat/internal/database/migrations"
+	"github.com/GainForest/hypergoat/internal/database/repositories"
+	"github.com/GainForest/hypergoat/internal/database/sqlite"
+	"github.com/GainForest/hypergoat/internal/graphql/resolver"
 	"github.com/GainForest/hypergoat/internal/lexicon"
 )
 
@@ -43,6 +50,99 @@ func loadLexiconsFromDir(dir string) ([]*lexicon.Lexicon, error) {
 	return lexicons, err
 }
 
+// TestEncodeDecode verifies that encodeCursorValues and decodeCursorValues
+// correctly round-trip values, handle pipe characters in values, and maintain
+// backward compatibility with the legacy pipe-delimited format.
+func TestEncodeDecode(t *testing.T) {
+	t.Run("round-trip normal values", func(t *testing.T) {
+		input := []string{"hello", "at://did:plc:abc/col/rkey"}
+		cursor := encodeCursorValues(input...)
+		got, err := decodeCursorValues(cursor)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(got) != len(input) {
+			t.Fatalf("expected %d parts, got %d", len(input), len(got))
+		}
+		for i, v := range input {
+			if got[i] != v {
+				t.Errorf("part[%d]: want %q, got %q", i, v, got[i])
+			}
+		}
+	})
+
+	t.Run("values containing pipe characters", func(t *testing.T) {
+		input := []string{"hello|world", "at://did:plc:abc/col/rkey"}
+		cursor := encodeCursorValues(input...)
+		got, err := decodeCursorValues(cursor)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(got) != len(input) {
+			t.Fatalf("expected %d parts, got %d", len(input), len(got))
+		}
+		for i, v := range input {
+			if got[i] != v {
+				t.Errorf("part[%d]: want %q, got %q", i, v, got[i])
+			}
+		}
+	})
+
+	t.Run("empty strings", func(t *testing.T) {
+		input := []string{"", ""}
+		cursor := encodeCursorValues(input...)
+		got, err := decodeCursorValues(cursor)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(got) != len(input) {
+			t.Fatalf("expected %d parts, got %d", len(input), len(got))
+		}
+		for i, v := range input {
+			if got[i] != v {
+				t.Errorf("part[%d]: want %q, got %q", i, v, got[i])
+			}
+		}
+	})
+
+	t.Run("single value", func(t *testing.T) {
+		input := []string{"only-one"}
+		cursor := encodeCursorValues(input...)
+		got, err := decodeCursorValues(cursor)
+		if err != nil {
+			t.Fatalf("unexpected error: %v", err)
+		}
+		if len(got) != 1 || got[0] != input[0] {
+			t.Errorf("want %v, got %v", input, got)
+		}
+	})
+
+	t.Run("legacy pipe-delimited format (backward compatibility)", func(t *testing.T) {
+		// Simulate a cursor produced by the old pipe-delimited implementation.
+		legacyCursor := base64.URLEncoding.EncodeToString([]byte("2024-01-01T00:00:00Z|at://did:plc:abc/col/rkey"))
+		got, err := decodeCursorValues(legacyCursor)
+		if err != nil {
+			t.Fatalf("unexpected error decoding legacy cursor: %v", err)
+		}
+		if len(got) != 2 {
+			t.Fatalf("expected 2 parts, got %d", len(got))
+		}
+		if got[0] != "2024-01-01T00:00:00Z" {
+			t.Errorf("part[0]: want %q, got %q", "2024-01-01T00:00:00Z", got[0])
+		}
+		if got[1] != "at://did:plc:abc/col/rkey" {
+			t.Errorf("part[1]: want %q, got %q", "at://did:plc:abc/col/rkey", got[1])
+		}
+	})
+
+	t.Run("invalid base64 returns error", func(t *testing.T) {
+		_, err := decodeCursorValues("!!!invalid!!!")
+		if err == nil {
+			t.Error("expected error for invalid base64, got nil")
+		}
+	})
+}
+
 func TestBuildSchemaFromHypercertsLexicons(t *testing.T) {
 	// Load all hypercerts lexicons
 	lexicons, err := loadLexiconsFromDir("../../../testdata/lexicons")
@@ -296,3 +396,833 @@ func TestSchemaIntrospection(t *testing.T) {
 	jsonResult, _ := json.MarshalIndent(result.Data, "", "  ")
 	t.Logf("Introspection result:\n%s", jsonResult)
 }
+
+// buildReservedCollisionLexicon creates a Lexicon whose main record definition
+// contains properties that collide with reserved metadata field names.
+func buildReservedCollisionLexicon(id string, collidingProps []string) *lexicon.Lexicon {
+	props := []lexicon.PropertyEntry{
+		// A normal, non-colliding property that must always appear.
+		{
+			Name: "title",
+			Property: lexicon.Property{
+				Type: "string",
+			},
+		},
+	}
+	for _, name := range collidingProps {
+		props = append(props, lexicon.PropertyEntry{
+			Name: name,
+			Property: lexicon.Property{
+				// Use integer so we can detect if the metadata field (String!) was replaced.
+				Type:        "integer",
+				Description: "Colliding property — must be skipped",
+			},
+		})
+	}
+	return &lexicon.Lexicon{
+		ID: id,
+		Defs: lexicon.Defs{
+			Main: &lexicon.RecordDef{
+				Type:       "record",
+				Key:        "tid",
+				Properties: props,
+			},
+		},
+	}
+}
+
+func TestBuildRecordType_ReservedFieldCollision(t *testing.T) {
+	tests := []struct {
+		name      string
+		colliding string // reserved property name the lexicon tries to define
+	}{
+		{name: "uri collision", colliding: "uri"},
+		{name: "did collision", colliding: "did"},
+		{name: "cid collision", colliding: "cid"},
+		{name: "rkey collision", colliding: "rkey"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			lexiconID := "com.example.reserved." + tt.colliding
+
+			lex := buildReservedCollisionLexicon(lexiconID, []string{tt.colliding})
+			registry := lexicon.NewRegistry()
+			registry.Register(lex)
+
+			builder := NewBuilder(registry)
+			_, err := builder.Build()
+			if err != nil {
+				t.Fatalf("Build() failed: %v", err)
+			}
+
+			recordType := builder.GetRecordType(lexiconID)
+			if recordType == nil {
+				t.Fatal("record type not found after Build()")
+			}
+
+			fields := recordType.Fields()
+
+			// The reserved metadata field must still be present and be NonNull String.
+			metaField, ok := fields[tt.colliding]
+			if !ok {
+				t.Fatalf("metadata field %q is missing from the type", tt.colliding)
+			}
+			if metaField.Type.String() != "String!" {
+				t.Errorf("metadata field %q type = %q, want %q (lexicon property must not overwrite it)",
+					tt.colliding, metaField.Type.String(), "String!")
+			}
+
+			// The normal non-colliding property must still be present.
+			if _, ok := fields["title"]; !ok {
+				t.Error("non-colliding property 'title' is missing from the type")
+			}
+		})
+	}
+}
+
+func TestBuildWhereInput_ReservedFieldCollision(t *testing.T) {
+	tests := []struct {
+		name      string
+		colliding string // reserved property name the lexicon tries to define
+	}{
+		{name: "uri collision in WhereInput", colliding: "uri"},
+		{name: "cid collision in WhereInput", colliding: "cid"},
+		{name: "rkey collision in WhereInput", colliding: "rkey"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			lexiconID := "com.example.whereinput." + tt.colliding
+
+			lex := buildReservedCollisionLexicon(lexiconID, []string{tt.colliding})
+			registry := lexicon.NewRegistry()
+			registry.Register(lex)
+
+			builder := NewBuilder(registry)
+			_, err := builder.Build()
+			if err != nil {
+				t.Fatalf("Build() failed: %v", err)
+			}
+
+			whereInput, ok := builder.whereInputTypes[lexiconID]
+			if !ok {
+				t.Fatal("WhereInput type not found after Build()")
+			}
+
+			inputFields := whereInput.Fields()
+
+			// The colliding property must NOT appear as a filter field in the WhereInput.
+			// (The reserved metadata field "uri"/"cid"/"rkey" is not added to WhereInput
+			// by default — only "did" is added as a metadata filter.)
+			// So the colliding property should simply be absent.
+			if _, exists := inputFields[tt.colliding]; exists {
+				t.Errorf("WhereInput has field %q which should have been skipped (reserved name collision)", tt.colliding)
+			}
+
+			// The normal non-colliding property must still appear as a filter.
+			if _, exists := inputFields["title"]; !exists {
+				t.Error("non-colliding property 'title' is missing from WhereInput")
+			}
+		})
+	}
+}
+
+// TestExtractFilters_DIDFilter verifies that extractFilters correctly populates
+// DIDFilter for both eq and in operators, and does not treat DID as a JSON field filter.
+func TestExtractFilters_DIDFilter(t *testing.T) {
+	registry := lexicon.NewRegistry()
+
+	tests := []struct {
+		name        string
+		whereArg    interface{}
+		wantDIDEQ   string
+		wantDIDIN   []string
+		wantFilters int // number of FieldFilters (non-DID)
+	}{
+		{
+			name:     "nil whereArg returns empty",
+			whereArg: nil,
+		},
+		{
+			name:     "empty map returns empty",
+			whereArg: map[string]interface{}{},
+		},
+		{
+			name: "did eq filter",
+			whereArg: map[string]interface{}{
+				"did": map[string]interface{}{
+					"eq": "did:plc:abc",
+				},
+			},
+			wantDIDEQ: "did:plc:abc",
+		},
+		{
+			name: "did in filter",
+			whereArg: map[string]interface{}{
+				"did": map[string]interface{}{
+					"in": []interface{}{"did:plc:abc", "did:plc:def"},
+				},
+			},
+			wantDIDIN: []string{"did:plc:abc", "did:plc:def"},
+		},
+		{
+			name: "did eq takes precedence when both set",
+			whereArg: map[string]interface{}{
+				"did": map[string]interface{}{
+					"eq": "did:plc:abc",
+					"in": []interface{}{"did:plc:xyz"},
+				},
+			},
+			wantDIDEQ: "did:plc:abc",
+			wantDIDIN: []string{"did:plc:xyz"},
+		},
+		{
+			name: "non-did field filter is not treated as DID",
+			whereArg: map[string]interface{}{
+				"title": map[string]interface{}{
+					"eq": "hello",
+				},
+			},
+			wantFilters: 1,
+		},
+		{
+			name: "did and non-did field filters together",
+			whereArg: map[string]interface{}{
+				"did": map[string]interface{}{
+					"eq": "did:plc:abc",
+				},
+				"title": map[string]interface{}{
+					"eq": "hello",
+				},
+			},
+			wantDIDEQ:   "did:plc:abc",
+			wantFilters: 1,
+		},
+		{
+			name: "empty did eq is ignored",
+			whereArg: map[string]interface{}{
+				"did": map[string]interface{}{
+					"eq": "",
+				},
+			},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			filters, didFilter, err := extractFilters(tt.whereArg, "com.example.test", registry)
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+
+			if didFilter.EQ != tt.wantDIDEQ {
+				t.Errorf("DIDFilter.EQ = %q, want %q", didFilter.EQ, tt.wantDIDEQ)
+			}
+
+			if len(didFilter.IN) != len(tt.wantDIDIN) {
+				t.Errorf("DIDFilter.IN = %v, want %v", didFilter.IN, tt.wantDIDIN)
+			} else {
+				for i, v := range tt.wantDIDIN {
+					if didFilter.IN[i] != v {
+						t.Errorf("DIDFilter.IN[%d] = %q, want %q", i, didFilter.IN[i], v)
+					}
+				}
+			}
+
+			if len(filters) != tt.wantFilters {
+				t.Errorf("len(filters) = %d, want %d (filters: %v)", len(filters), tt.wantFilters, filters)
+			}
+		})
+	}
+}
+
+// TestBuildWhereInput_UsesDIDFilterInput verifies that the WhereInput for a collection
+// uses DIDFilterInput (not StringFilterInput) for the did field, and that DIDFilterInput
+// only exposes eq and in operators.
+func TestBuildWhereInput_UsesDIDFilterInput(t *testing.T) {
+	lexiconID := "com.example.didfilter.post"
+	lex := &lexicon.Lexicon{
+		ID: lexiconID,
+		Defs: lexicon.Defs{
+			Main: &lexicon.RecordDef{
+				Type: "record",
+				Key:  "tid",
+				Properties: []lexicon.PropertyEntry{
+					{Name: "title", Property: lexicon.Property{Type: "string"}},
+				},
+			},
+		},
+	}
+
+	registry := lexicon.NewRegistry()
+	registry.Register(lex)
+
+	builder := NewBuilder(registry)
+	_, err := builder.Build()
+	if err != nil {
+		t.Fatalf("Build() failed: %v", err)
+	}
+
+	whereInput, ok := builder.whereInputTypes[lexiconID]
+	if !ok {
+		t.Fatal("WhereInput type not found after Build()")
+	}
+
+	inputFields := whereInput.Fields()
+
+	// did field must be present
+	didField, ok := inputFields["did"]
+	if !ok {
+		t.Fatal("WhereInput is missing the 'did' field")
+	}
+
+	// The type must be DIDFilterInput (named "DIDFilterInput")
+	inputObj, ok := didField.Type.(*graphql.InputObject)
+	if !ok {
+		t.Fatalf("WhereInput 'did' field type = %T, want *graphql.InputObject", didField.Type)
+	}
+	if inputObj.Name() != "DIDFilterInput" {
+		t.Errorf("WhereInput 'did' field type name = %q, want %q", inputObj.Name(), "DIDFilterInput")
+	}
+
+	// DIDFilterInput must only have eq and in
+	didFilterFields := inputObj.Fields()
+	if _, ok := didFilterFields["eq"]; !ok {
+		t.Error("DIDFilterInput: missing 'eq' field")
+	}
+	if _, ok := didFilterFields["in"]; !ok {
+		t.Error("DIDFilterInput: missing 'in' field")
+	}
+	// Must NOT have contains, startsWith, neq, etc.
+	for _, absent := range []string{"contains", "startsWith", "neq", "isNull", "gt", "lt"} {
+		if _, ok := didFilterFields[absent]; ok {
+			t.Errorf("DIDFilterInput: field %q should be absent", absent)
+		}
+	}
+}
+
+func TestBuildWhereInput_DidHandledSeparately(t *testing.T) {
+	// A lexicon with a "did" property must not result in a duplicate "did" filter.
+	// The "did" metadata filter is always added; the lexicon property "did" must be skipped.
+	lexiconID := "com.example.whereinput.did"
+
+	lex := buildReservedCollisionLexicon(lexiconID, []string{"did"})
+	registry := lexicon.NewRegistry()
+	registry.Register(lex)
+
+	builder := NewBuilder(registry)
+	_, err := builder.Build()
+	if err != nil {
+		t.Fatalf("Build() failed: %v", err)
+	}
+
+	whereInput, ok := builder.whereInputTypes[lexiconID]
+	if !ok {
+		t.Fatal("WhereInput type not found after Build()")
+	}
+
+	inputFields := whereInput.Fields()
+
+	// "did" must appear exactly once (as the metadata filter).
+	if _, exists := inputFields["did"]; !exists {
+		t.Error("WhereInput is missing the 'did' metadata filter field")
+	}
+
+	// "title" must still appear.
+	if _, exists := inputFields["title"]; !exists {
+		t.Error("non-colliding property 'title' is missing from WhereInput")
+	}
+}
+
+// TestSortFieldValueForRecord verifies that sortFieldValueForRecord extracts the
+// correct sort field value from a record for cursor building.
+func TestSortFieldValueForRecord(t *testing.T) {
+	now := time.Date(2024, 6, 15, 12, 0, 0, 0, time.UTC)
+	rec := &repositories.Record{
+		URI:        "at://did:plc:abc/com.example.post/rkey123",
+		CID:        "bafyreiabcdef",
+		DID:        "did:plc:abc",
+		Collection: "com.example.post",
+		RKey:       "rkey123",
+		IndexedAt:  now,
+	}
+
+	tests := []struct {
+		name    string
+		sortOpt *repositories.SortOption
+		value   map[string]interface{}
+		want    string
+	}{
+		{
+			name:    "nil sortOpt returns indexed_at",
+			sortOpt: nil,
+			value:   map[string]interface{}{},
+			want:    "2024-06-15T12:00:00Z",
+		},
+		{
+			name:    "indexed_at field returns formatted time",
+			sortOpt: &repositories.SortOption{Field: "indexed_at", Direction: "DESC"},
+			value:   map[string]interface{}{},
+			want:    "2024-06-15T12:00:00Z",
+		},
+		{
+			name:    "uri field returns record URI",
+			sortOpt: &repositories.SortOption{Field: "uri", Direction: "DESC"},
+			value:   map[string]interface{}{},
+			want:    "at://did:plc:abc/com.example.post/rkey123",
+		},
+		{
+			name:    "did field returns record DID",
+			sortOpt: &repositories.SortOption{Field: "did", Direction: "ASC"},
+			value:   map[string]interface{}{},
+			want:    "did:plc:abc",
+		},
+		{
+			name:    "cid field returns record CID",
+			sortOpt: &repositories.SortOption{Field: "cid", Direction: "DESC"},
+			value:   map[string]interface{}{},
+			want:    "bafyreiabcdef",
+		},
+		{
+			name:    "rkey field returns record RKey",
+			sortOpt: &repositories.SortOption{Field: "rkey", Direction: "DESC"},
+			value:   map[string]interface{}{},
+			want:    "rkey123",
+		},
+		{
+			name:    "collection field returns record Collection",
+			sortOpt: &repositories.SortOption{Field: "collection", Direction: "DESC"},
+			value:   map[string]interface{}{},
+			want:    "com.example.post",
+		},
+		{
+			name:    "JSON field present returns its value",
+			sortOpt: &repositories.SortOption{Field: "title", Direction: "DESC"},
+			value:   map[string]interface{}{"title": "Hello World"},
+			want:    "Hello World",
+		},
+		{
+			name:    "JSON field missing returns empty string",
+			sortOpt: &repositories.SortOption{Field: "title", Direction: "DESC"},
+			value:   map[string]interface{}{},
+			want:    "",
+		},
+		{
+			name:    "JSON field with nil value returns empty string",
+			sortOpt: &repositories.SortOption{Field: "title", Direction: "DESC"},
+			value:   map[string]interface{}{"title": nil},
+			want:    "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := sortFieldValueForRecord(rec, tt.value, tt.sortOpt)
+			if got != tt.want {
+				t.Errorf("sortFieldValueForRecord() = %q, want %q", got, tt.want)
+			}
+		})
+	}
+}
+
+// TestEmptyConnection verifies that emptyConnection returns a well-formed
+// Relay connection with empty edges, all-false pageInfo, and totalCount of 0.
+func TestEmptyConnection(t *testing.T) {
+	result := emptyConnection()
+
+	// Verify edges is an empty (non-nil) slice
+	edges, ok := result["edges"]
+	if !ok {
+		t.Fatal("emptyConnection: missing 'edges' key")
+	}
+	edgeSlice, ok := edges.([]interface{})
+	if !ok {
+		t.Fatalf("emptyConnection: edges is %T, want []interface{}", edges)
+	}
+	if len(edgeSlice) != 0 {
+		t.Errorf("emptyConnection: edges length = %d, want 0", len(edgeSlice))
+	}
+
+	// Verify pageInfo structure
+	pageInfoRaw, ok := result["pageInfo"]
+	if !ok {
+		t.Fatal("emptyConnection: missing 'pageInfo' key")
+	}
+	pageInfo, ok := pageInfoRaw.(map[string]interface{})
+	if !ok {
+		t.Fatalf("emptyConnection: pageInfo is %T, want map[string]interface{}", pageInfoRaw)
+	}
+
+	if v, ok := pageInfo["hasNextPage"].(bool); !ok || v {
+		t.Errorf("emptyConnection: hasNextPage = %v, want false", pageInfo["hasNextPage"])
+	}
+	if v, ok := pageInfo["hasPreviousPage"].(bool); !ok || v {
+		t.Errorf("emptyConnection: hasPreviousPage = %v, want false", pageInfo["hasPreviousPage"])
+	}
+	if pageInfo["startCursor"] != nil {
+		t.Errorf("emptyConnection: startCursor = %v, want nil", pageInfo["startCursor"])
+	}
+	if pageInfo["endCursor"] != nil {
+		t.Errorf("emptyConnection: endCursor = %v, want nil", pageInfo["endCursor"])
+	}
+
+	// Verify totalCount is 0
+	totalCount, ok := result["totalCount"]
+	if !ok {
+		t.Fatal("emptyConnection: missing 'totalCount' key")
+	}
+	if totalCount != 0 {
+		t.Errorf("emptyConnection: totalCount = %v, want 0", totalCount)
+	}
+}
+
+// setupCoercionTestDB creates an in-memory SQLite database with migrations applied,
+// inserts a single org.hypercerts.claim.activity record with the given JSON payload,
+// and returns a context that carries the repositories.
+func setupCoercionTestDB(t *testing.T, recordJSON string) context.Context {
+	t.Helper()
+
+	exec, err := sqlite.NewExecutor("sqlite::memory:")
+	if err != nil {
+		t.Fatalf("setupCoercionTestDB: failed to create SQLite executor: %v", err)
+	}
+	t.Cleanup(func() { exec.Close() })
+
+	ctx := context.Background()
+	if err := migrations.Run(ctx, exec); err != nil {
+		t.Fatalf("setupCoercionTestDB: failed to run migrations: %v", err)
+	}
+
+	records := repositories.NewRecordsRepository(exec)
+	rec := &repositories.Record{
+		URI:        "at://did:plc:test/org.hypercerts.claim.activity/rkey1",
+		CID:        "bafyreiabc123",
+		DID:        "did:plc:test",
+		Collection: "org.hypercerts.claim.activity",
+		JSON:       recordJSON,
+		RKey:       "rkey1",
+	}
+	if err := records.BatchInsert(ctx, []*repositories.Record{rec}); err != nil {
+		t.Fatalf("setupCoercionTestDB: failed to insert record: %v", err)
+	}
+
+	repos := &resolver.Repositories{
+		Records: records,
+	}
+	return resolver.WithRepositories(ctx, repos)
+}
+
+// buildActivitySchema builds a GraphQL schema from the org.hypercerts.claim.activity lexicon.
+func buildActivitySchema(t *testing.T) *graphql.Schema {
+	t.Helper()
+
+	data, err := os.ReadFile("../../../testdata/lexicons/org/hypercerts/claim/activity.json")
+	if err != nil {
+		t.Fatalf("buildActivitySchema: failed to read activity.json: %v", err)
+	}
+	lex, err := lexicon.ParseBytes(data)
+	if err != nil {
+		t.Fatalf("buildActivitySchema: failed to parse activity.json: %v", err)
+	}
+
+	registry := lexicon.NewRegistry()
+	registry.Register(lex)
+
+	schema, err := NewBuilder(registry).Build()
+	if err != nil {
+		t.Fatalf("buildActivitySchema: failed to build schema: %v", err)
+	}
+	return schema
+}
+
+// TestCoerceRequiredFields_MissingFields verifies that required string fields that are
+// absent from the stored JSON are coerced to their zero value ("") when resolved.
+func TestCoerceRequiredFields_MissingFields(t *testing.T) {
+	// Record is missing "title" and "shortDescription" — only "createdAt" is present.
+	ctx := setupCoercionTestDB(t, `{"createdAt":"2025-01-01T00:00:00Z"}`)
+	schema := buildActivitySchema(t)
+
+	query := `{
+		orgHypercertsClaimActivity(first: 10) {
+			edges {
+				node {
+					title
+					shortDescription
+				}
+			}
+		}
+	}`
+
+	result := graphql.Do(graphql.Params{
+		Schema:        *schema,
+		RequestString: query,
+		Context:       ctx,
+	})
+
+	if len(result.Errors) > 0 {
+		t.Fatalf("TestCoerceRequiredFields_MissingFields: unexpected GraphQL errors: %v", result.Errors)
+	}
+
+	data, ok := result.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("result.Data is %T, want map[string]interface{}", result.Data)
+	}
+
+	conn, ok := data["orgHypercertsClaimActivity"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("orgHypercertsClaimActivity is %T", data["orgHypercertsClaimActivity"])
+	}
+
+	edges, ok := conn["edges"].([]interface{})
+	if !ok || len(edges) == 0 {
+		t.Fatalf("expected at least one edge, got %v", conn["edges"])
+	}
+
+	edge, ok := edges[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("edge[0] is %T", edges[0])
+	}
+	node, ok := edge["node"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("node is %T", edge["node"])
+	}
+
+	if title, ok := node["title"]; !ok || title != "" {
+		t.Errorf("title = %v (%T), want \"\" (coerced zero value)", title, title)
+	}
+	if sd, ok := node["shortDescription"]; !ok || sd != "" {
+		t.Errorf("shortDescription = %v (%T), want \"\" (coerced zero value)", sd, sd)
+	}
+}
+
+// TestCoerceRequiredFields_PresentFields verifies that required fields that are already
+// present in the stored JSON are returned unchanged.
+func TestCoerceRequiredFields_PresentFields(t *testing.T) {
+	ctx := setupCoercionTestDB(t, `{"title":"My Title","shortDescription":"My Desc","createdAt":"2025-01-01T00:00:00Z"}`)
+	schema := buildActivitySchema(t)
+
+	query := `{
+		orgHypercertsClaimActivity(first: 10) {
+			edges {
+				node {
+					title
+					shortDescription
+				}
+			}
+		}
+	}`
+
+	result := graphql.Do(graphql.Params{
+		Schema:        *schema,
+		RequestString: query,
+		Context:       ctx,
+	})
+
+	if len(result.Errors) > 0 {
+		t.Fatalf("TestCoerceRequiredFields_PresentFields: unexpected GraphQL errors: %v", result.Errors)
+	}
+
+	data, ok := result.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("result.Data is %T, want map[string]interface{}", result.Data)
+	}
+
+	conn, ok := data["orgHypercertsClaimActivity"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("orgHypercertsClaimActivity is %T", data["orgHypercertsClaimActivity"])
+	}
+
+	edges, ok := conn["edges"].([]interface{})
+	if !ok || len(edges) == 0 {
+		t.Fatalf("expected at least one edge, got %v", conn["edges"])
+	}
+
+	edge, ok := edges[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("edge[0] is %T", edges[0])
+	}
+	node, ok := edge["node"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("node is %T", edge["node"])
+	}
+
+	if title, ok := node["title"]; !ok || title != "My Title" {
+		t.Errorf("title = %v, want %q (original value preserved)", title, "My Title")
+	}
+	if sd, ok := node["shortDescription"]; !ok || sd != "My Desc" {
+		t.Errorf("shortDescription = %v, want %q (original value preserved)", sd, "My Desc")
+	}
+}
+
+// TestCoerceRequiredFields_NullFields verifies that required fields that are explicitly
+// set to null in the stored JSON are coerced to their zero value ("") when resolved.
+func TestCoerceRequiredFields_NullFields(t *testing.T) {
+	ctx := setupCoercionTestDB(t, `{"title":null,"shortDescription":null,"createdAt":"2025-01-01T00:00:00Z"}`)
+	schema := buildActivitySchema(t)
+
+	query := `{
+		orgHypercertsClaimActivity(first: 10) {
+			edges {
+				node {
+					title
+					shortDescription
+				}
+			}
+		}
+	}`
+
+	result := graphql.Do(graphql.Params{
+		Schema:        *schema,
+		RequestString: query,
+		Context:       ctx,
+	})
+
+	if len(result.Errors) > 0 {
+		t.Fatalf("TestCoerceRequiredFields_NullFields: unexpected GraphQL errors: %v", result.Errors)
+	}
+
+	data, ok := result.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("result.Data is %T, want map[string]interface{}", result.Data)
+	}
+
+	conn, ok := data["orgHypercertsClaimActivity"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("orgHypercertsClaimActivity is %T", data["orgHypercertsClaimActivity"])
+	}
+
+	edges, ok := conn["edges"].([]interface{})
+	if !ok || len(edges) == 0 {
+		t.Fatalf("expected at least one edge, got %v", conn["edges"])
+	}
+
+	edge, ok := edges[0].(map[string]interface{})
+	if !ok {
+		t.Fatalf("edge[0] is %T", edges[0])
+	}
+	node, ok := edge["node"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("node is %T", edge["node"])
+	}
+
+	if title, ok := node["title"]; !ok || title != "" {
+		t.Errorf("title = %v (%T), want \"\" (coerced from null)", title, title)
+	}
+	if sd, ok := node["shortDescription"]; !ok || sd != "" {
+		t.Errorf("shortDescription = %v (%T), want \"\" (coerced from null)", sd, sd)
+	}
+}
+
+// TestCoerceRequiredFields_SingleRecordResolver verifies that the ByUri (single record)
+// resolver path also coerces missing required fields to their zero values.
+func TestCoerceRequiredFields_SingleRecordResolver(t *testing.T) {
+	// Record is missing "title" and "shortDescription" — only "createdAt" is present.
+	ctx := setupCoercionTestDB(t, `{"createdAt":"2025-01-01T00:00:00Z"}`)
+	schema := buildActivitySchema(t)
+
+	query := `{
+		orgHypercertsClaimActivityByUri(uri: "at://did:plc:test/org.hypercerts.claim.activity/rkey1") {
+			title
+			shortDescription
+		}
+	}`
+
+	result := graphql.Do(graphql.Params{
+		Schema:        *schema,
+		RequestString: query,
+		Context:       ctx,
+	})
+
+	if len(result.Errors) > 0 {
+		t.Fatalf("TestCoerceRequiredFields_SingleRecordResolver: unexpected GraphQL errors: %v", result.Errors)
+	}
+
+	data, ok := result.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("result.Data is %T, want map[string]interface{}", result.Data)
+	}
+
+	record, ok := data["orgHypercertsClaimActivityByUri"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("orgHypercertsClaimActivityByUri is %T, want map[string]interface{}", data["orgHypercertsClaimActivityByUri"])
+	}
+
+	if title, ok := record["title"]; !ok || title != "" {
+		t.Errorf("title = %v (%T), want \"\" (coerced zero value)", title, title)
+	}
+	if sd, ok := record["shortDescription"]; !ok || sd != "" {
+		t.Errorf("shortDescription = %v (%T), want \"\" (coerced zero value)", sd, sd)
+	}
+}
+
+// TestExtractFilters_MaxFilterConditions verifies that extractFilters enforces the
+// MaxFilterConditions cap and that the DID filter does not count toward the cap.
+func TestExtractFilters_MaxFilterConditions(t *testing.T) {
+	registry := lexicon.NewRegistry()
+
+	// Helper to build a whereArg with n distinct field filters (each with one operator).
+	buildFieldFilters := func(n int) map[string]interface{} {
+		m := map[string]interface{}{}
+		for i := 0; i < n; i++ {
+			m[fmt.Sprintf("field%d", i)] = map[string]interface{}{"eq": "value"}
+		}
+		return m
+	}
+
+	tests := []struct {
+		name        string
+		whereArg    interface{}
+		wantErr     bool
+		wantErrMsg  string
+		wantFilters int
+	}{
+		{
+			name:        "zero filter conditions succeeds",
+			whereArg:    map[string]interface{}{},
+			wantFilters: 0,
+		},
+		{
+			name:        "exactly MaxFilterConditions succeeds",
+			whereArg:    buildFieldFilters(repositories.MaxFilterConditions),
+			wantFilters: repositories.MaxFilterConditions,
+		},
+		{
+			name:       "one over MaxFilterConditions returns error",
+			whereArg:   buildFieldFilters(repositories.MaxFilterConditions + 1),
+			wantErr:    true,
+			wantErrMsg: "too many filter conditions",
+		},
+		{
+			name: "DID filter does not count toward cap",
+			whereArg: func() map[string]interface{} {
+				// MaxFilterConditions field filters + a DID filter: should still succeed.
+				m := buildFieldFilters(repositories.MaxFilterConditions)
+				m["did"] = map[string]interface{}{"eq": "did:plc:abc"}
+				return m
+			}(),
+			wantFilters: repositories.MaxFilterConditions,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			filters, _, err := extractFilters(tt.whereArg, "com.example.test", registry)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("expected error containing %q, got nil", tt.wantErrMsg)
+				}
+				if tt.wantErrMsg != "" && !strings.Contains(err.Error(), tt.wantErrMsg) {
+					t.Errorf("error = %q, want it to contain %q", err.Error(), tt.wantErrMsg)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if len(filters) != tt.wantFilters {
+				t.Errorf("len(filters) = %d, want %d", len(filters), tt.wantFilters)
+			}
+		})
+	}
+}
diff --git a/internal/graphql/types/filters.go b/internal/graphql/types/filters.go
new file mode 100644
index 0000000..b47e8e7
--- /dev/null
+++ b/internal/graphql/types/filters.go
@@ -0,0 +1,207 @@
+// Package types provides GraphQL type mapping and building utilities.
+// This file defines shared filter InputObject types for field-level filtering,
+// reused across all collection query types.
+package types //nolint:revive // package name is descriptive within graphql context
+
+import (
+	"github.com/graphql-go/graphql"
+)
+
+// StringFilterInput is a GraphQL InputObject for filtering string fields.
+var StringFilterInput = graphql.NewInputObject(graphql.InputObjectConfig{
+	Name:        "StringFilterInput",
+	Description: "Filter conditions for string fields",
+	Fields: graphql.InputObjectConfigFieldMap{
+		"eq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.String,
+			Description: "Equal to",
+		},
+		"neq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.String,
+			Description: "Not equal to",
+		},
+		"in": &graphql.InputObjectFieldConfig{
+			Type:        graphql.NewList(graphql.NewNonNull(graphql.String)),
+			Description: "Value is in list",
+		},
+		"contains": &graphql.InputObjectFieldConfig{
+			Type:        graphql.String,
+			Description: "Contains substring",
+		},
+		"startsWith": &graphql.InputObjectFieldConfig{
+			Type:        graphql.String,
+			Description: "Starts with prefix",
+		},
+		"isNull": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Boolean,
+			Description: "Field is null",
+		},
+	},
+})
+
+// IntFilterInput is a GraphQL InputObject for filtering integer fields.
+var IntFilterInput = graphql.NewInputObject(graphql.InputObjectConfig{
+	Name:        "IntFilterInput",
+	Description: "Filter conditions for integer fields",
+	Fields: graphql.InputObjectConfigFieldMap{
+		"eq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Int,
+			Description: "Equal to",
+		},
+		"neq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Int,
+			Description: "Not equal to",
+		},
+		"gt": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Int,
+			Description: "Greater than",
+		},
+		"lt": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Int,
+			Description: "Less than",
+		},
+		"gte": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Int,
+			Description: "Greater than or equal to",
+		},
+		"lte": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Int,
+			Description: "Less than or equal to",
+		},
+		"in": &graphql.InputObjectFieldConfig{
+			Type:        graphql.NewList(graphql.NewNonNull(graphql.Int)),
+			Description: "Value is in list",
+		},
+		"isNull": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Boolean,
+			Description: "Field is null",
+		},
+	},
+})
+
+// FloatFilterInput is a GraphQL InputObject for filtering float/number fields.
+var FloatFilterInput = graphql.NewInputObject(graphql.InputObjectConfig{
+	Name:        "FloatFilterInput",
+	Description: "Filter conditions for float fields",
+	Fields: graphql.InputObjectConfigFieldMap{
+		"eq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Float,
+			Description: "Equal to",
+		},
+		"neq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Float,
+			Description: "Not equal to",
+		},
+		"gt": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Float,
+			Description: "Greater than",
+		},
+		"lt": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Float,
+			Description: "Less than",
+		},
+		"gte": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Float,
+			Description: "Greater than or equal to",
+		},
+		"lte": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Float,
+			Description: "Less than or equal to",
+		},
+		"isNull": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Boolean,
+			Description: "Field is null",
+		},
+	},
+})
+
+// BooleanFilterInput is a GraphQL InputObject for filtering boolean fields.
+var BooleanFilterInput = graphql.NewInputObject(graphql.InputObjectConfig{
+	Name:        "BooleanFilterInput",
+	Description: "Filter conditions for boolean fields",
+	Fields: graphql.InputObjectConfigFieldMap{
+		"eq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Boolean,
+			Description: "Equal to",
+		},
+		"isNull": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Boolean,
+			Description: "Field is null",
+		},
+	},
+})
+
+// DateTimeFilterInput is a GraphQL InputObject for filtering datetime fields.
+var DateTimeFilterInput = graphql.NewInputObject(graphql.InputObjectConfig{
+	Name:        "DateTimeFilterInput",
+	Description: "Filter conditions for datetime fields",
+	Fields: graphql.InputObjectConfigFieldMap{
+		"eq": &graphql.InputObjectFieldConfig{
+			Type:        DateTimeScalar,
+			Description: "Equal to",
+		},
+		"neq": &graphql.InputObjectFieldConfig{
+			Type:        DateTimeScalar,
+			Description: "Not equal to",
+		},
+		"gt": &graphql.InputObjectFieldConfig{
+			Type:        DateTimeScalar,
+			Description: "Greater than",
+		},
+		"lt": &graphql.InputObjectFieldConfig{
+			Type:        DateTimeScalar,
+			Description: "Less than",
+		},
+		"gte": &graphql.InputObjectFieldConfig{
+			Type:        DateTimeScalar,
+			Description: "Greater than or equal to",
+		},
+		"lte": &graphql.InputObjectFieldConfig{
+			Type:        DateTimeScalar,
+			Description: "Less than or equal to",
+		},
+		"isNull": &graphql.InputObjectFieldConfig{
+			Type:        graphql.Boolean,
+			Description: "Field is null",
+		},
+	},
+})
+
+// DIDFilterInput is a restricted GraphQL InputObject for filtering DID fields.
+// DID is a column-level filter (not a JSON field), so only eq and in are meaningful.
+// Operators like contains or startsWith are not supported for DIDs.
+var DIDFilterInput = graphql.NewInputObject(graphql.InputObjectConfig{
+	Name:        "DIDFilterInput",
+	Description: "Filter conditions for DID fields (column-level). Only eq and in are supported.",
+	Fields: graphql.InputObjectConfigFieldMap{
+		"eq": &graphql.InputObjectFieldConfig{
+			Type:        graphql.String,
+			Description: "Equals",
+		},
+		"in": &graphql.InputObjectFieldConfig{
+			Type:        graphql.NewList(graphql.NewNonNull(graphql.String)),
+			Description: "In list",
+		},
+	},
+})
+
+// FilterInputForLexiconType maps a lexicon property type and format to the
+// appropriate GraphQL filter InputObject. Returns nil for non-filterable types.
+func FilterInputForLexiconType(lexiconType, format string) *graphql.InputObject {
+	switch lexiconType {
+	case "string":
+		if format == "datetime" {
+			return DateTimeFilterInput
+		}
+		return StringFilterInput
+	case "integer":
+		return IntFilterInput
+	case "number":
+		return FloatFilterInput
+	case "boolean":
+		return BooleanFilterInput
+	default:
+		// blob, bytes, unknown, ref, union, array, object, record — not filterable
+		return nil
+	}
+}
diff --git a/internal/graphql/types/filters_test.go b/internal/graphql/types/filters_test.go
new file mode 100644
index 0000000..3abb969
--- /dev/null
+++ b/internal/graphql/types/filters_test.go
@@ -0,0 +1,298 @@
+package types //nolint:revive // package name is descriptive within graphql context
+
+import (
+	"testing"
+
+	"github.com/graphql-go/graphql"
+)
+
+// TestFilterInputTypes verifies that each of the 5 filter InputObject types
+// has exactly the fields specified in the issue.
+func TestFilterInputTypes(t *testing.T) {
+	tests := []struct {
+		name       string
+		inputObj   *graphql.InputObject
+		wantFields []string
+		wantAbsent []string
+	}{
+		{
+			name:       "StringFilterInput fields",
+			inputObj:   StringFilterInput,
+			wantFields: []string{"eq", "neq", "in", "contains", "startsWith", "isNull"},
+		},
+		{
+			name:       "IntFilterInput fields",
+			inputObj:   IntFilterInput,
+			wantFields: []string{"eq", "neq", "gt", "lt", "gte", "lte", "in", "isNull"},
+			wantAbsent: []string{"contains", "startsWith"},
+		},
+		{
+			name:       "FloatFilterInput fields",
+			inputObj:   FloatFilterInput,
+			wantFields: []string{"eq", "neq", "gt", "lt", "gte", "lte", "isNull"},
+			wantAbsent: []string{"in", "contains", "startsWith"},
+		},
+		{
+			name:       "BooleanFilterInput fields",
+			inputObj:   BooleanFilterInput,
+			wantFields: []string{"eq", "isNull"},
+			wantAbsent: []string{"neq", "gt", "lt", "gte", "lte", "in", "contains", "startsWith"},
+		},
+		{
+			name:       "DateTimeFilterInput fields",
+			inputObj:   DateTimeFilterInput,
+			wantFields: []string{"eq", "neq", "gt", "lt", "gte", "lte", "isNull"},
+			wantAbsent: []string{"in", "contains", "startsWith"},
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.inputObj == nil {
+				t.Fatal("input object is nil")
+			}
+
+			fields := tt.inputObj.Fields()
+
+			for _, fieldName := range tt.wantFields {
+				if _, ok := fields[fieldName]; !ok {
+					t.Errorf("expected field %q to be present in %s", fieldName, tt.inputObj.Name())
+				}
+			}
+
+			for _, fieldName := range tt.wantAbsent {
+				if _, ok := fields[fieldName]; ok {
+					t.Errorf("expected field %q to be absent from %s", fieldName, tt.inputObj.Name())
+				}
+			}
+		})
+	}
+}
+
+// TestStringFilterInput_FieldTypes verifies the GraphQL types of StringFilterInput fields.
+func TestStringFilterInput_FieldTypes(t *testing.T) {
+	fields := StringFilterInput.Fields()
+
+	// eq, neq, contains, startsWith should be String
+	for _, name := range []string{"eq", "neq", "contains", "startsWith"} {
+		f, ok := fields[name]
+		if !ok {
+			t.Fatalf("missing field %q", name)
+		}
+		if f.Type != graphql.String {
+			t.Errorf("field %q type = %v, want String", name, f.Type)
+		}
+	}
+
+	// in should be [String!]
+	inField, ok := fields["in"]
+	if !ok {
+		t.Fatal("missing field 'in'")
+	}
+	list, ok := inField.Type.(*graphql.List)
+	if !ok {
+		t.Fatalf("field 'in' type = %T, want *graphql.List", inField.Type)
+	}
+	if _, ok := list.OfType.(*graphql.NonNull); !ok {
+		t.Errorf("field 'in' list element type = %T, want *graphql.NonNull", list.OfType)
+	}
+
+	// isNull should be Boolean
+	isNullField, ok := fields["isNull"]
+	if !ok {
+		t.Fatal("missing field 'isNull'")
+	}
+	if isNullField.Type != graphql.Boolean {
+		t.Errorf("field 'isNull' type = %v, want Boolean", isNullField.Type)
+	}
+}
+
+// TestIntFilterInput_FieldTypes verifies the GraphQL types of IntFilterInput fields.
+func TestIntFilterInput_FieldTypes(t *testing.T) {
+	fields := IntFilterInput.Fields()
+
+	// eq, neq, gt, lt, gte, lte should be Int
+	for _, name := range []string{"eq", "neq", "gt", "lt", "gte", "lte"} {
+		f, ok := fields[name]
+		if !ok {
+			t.Fatalf("missing field %q", name)
+		}
+		if f.Type != graphql.Int {
+			t.Errorf("field %q type = %v, want Int", name, f.Type)
+		}
+	}
+
+	// in should be [Int!]
+	inField, ok := fields["in"]
+	if !ok {
+		t.Fatal("missing field 'in'")
+	}
+	list, ok := inField.Type.(*graphql.List)
+	if !ok {
+		t.Fatalf("field 'in' type = %T, want *graphql.List", inField.Type)
+	}
+	if _, ok := list.OfType.(*graphql.NonNull); !ok {
+		t.Errorf("field 'in' list element type = %T, want *graphql.NonNull", list.OfType)
+	}
+}
+
+// TestFloatFilterInput_FieldTypes verifies the GraphQL types of FloatFilterInput fields.
+func TestFloatFilterInput_FieldTypes(t *testing.T) {
+	fields := FloatFilterInput.Fields()
+
+	for _, name := range []string{"eq", "neq", "gt", "lt", "gte", "lte"} {
+		f, ok := fields[name]
+		if !ok {
+			t.Fatalf("missing field %q", name)
+		}
+		if f.Type != graphql.Float {
+			t.Errorf("field %q type = %v, want Float", name, f.Type)
+		}
+	}
+}
+
+// TestDateTimeFilterInput_FieldTypes verifies that DateTimeFilterInput uses DateTimeScalar.
+func TestDateTimeFilterInput_FieldTypes(t *testing.T) {
+	fields := DateTimeFilterInput.Fields()
+
+	for _, name := range []string{"eq", "neq", "gt", "lt", "gte", "lte"} {
+		f, ok := fields[name]
+		if !ok {
+			t.Fatalf("missing field %q", name)
+		}
+		if f.Type != DateTimeScalar {
+			t.Errorf("field %q type = %v, want DateTimeScalar", name, f.Type)
+		}
+	}
+}
+
+// TestFilterInputForLexiconType verifies the mapping from lexicon types to filter inputs.
+func TestFilterInputForLexiconType(t *testing.T) {
+	tests := []struct {
+		name        string
+		lexiconType string
+		format      string
+		wantInput   *graphql.InputObject
+		wantNil     bool
+	}{
+		// Filterable types
+		{name: "string no format", lexiconType: "string", format: "", wantInput: StringFilterInput},
+		{name: "string uri format", lexiconType: "string", format: "uri", wantInput: StringFilterInput},
+		{name: "string handle format", lexiconType: "string", format: "handle", wantInput: StringFilterInput},
+		{name: "string datetime format", lexiconType: "string", format: "datetime", wantInput: DateTimeFilterInput},
+		{name: "integer", lexiconType: "integer", format: "", wantInput: IntFilterInput},
+		{name: "number", lexiconType: "number", format: "", wantInput: FloatFilterInput},
+		{name: "boolean", lexiconType: "boolean", format: "", wantInput: BooleanFilterInput},
+
+		// Non-filterable types — must return nil
+		{name: "blob", lexiconType: "blob", format: "", wantNil: true},
+		{name: "bytes", lexiconType: "bytes", format: "", wantNil: true},
+		{name: "unknown", lexiconType: "unknown", format: "", wantNil: true},
+		{name: "ref", lexiconType: "ref", format: "", wantNil: true},
+		{name: "union", lexiconType: "union", format: "", wantNil: true},
+		{name: "array", lexiconType: "array", format: "", wantNil: true},
+		{name: "object", lexiconType: "object", format: "", wantNil: true},
+		{name: "record", lexiconType: "record", format: "", wantNil: true},
+		{name: "empty type", lexiconType: "", format: "", wantNil: true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := FilterInputForLexiconType(tt.lexiconType, tt.format)
+
+			if tt.wantNil {
+				if got != nil {
+					t.Errorf("FilterInputForLexiconType(%q, %q) = %v, want nil",
+						tt.lexiconType, tt.format, got.Name())
+				}
+				return
+			}
+
+			if got == nil {
+				t.Fatalf("FilterInputForLexiconType(%q, %q) = nil, want %v",
+					tt.lexiconType, tt.format, tt.wantInput.Name())
+			}
+
+			if got != tt.wantInput {
+				t.Errorf("FilterInputForLexiconType(%q, %q) = %v, want %v",
+					tt.lexiconType, tt.format, got.Name(), tt.wantInput.Name())
+			}
+		})
+	}
+}
+
+// TestFilterInputNames verifies the Name() of each filter input type.
+func TestFilterInputNames(t *testing.T) {
+	tests := []struct {
+		inputObj *graphql.InputObject
+		wantName string
+	}{
+		{StringFilterInput, "StringFilterInput"},
+		{IntFilterInput, "IntFilterInput"},
+		{FloatFilterInput, "FloatFilterInput"},
+		{BooleanFilterInput, "BooleanFilterInput"},
+		{DateTimeFilterInput, "DateTimeFilterInput"},
+		{DIDFilterInput, "DIDFilterInput"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.wantName, func(t *testing.T) {
+			if tt.inputObj.Name() != tt.wantName {
+				t.Errorf("Name() = %q, want %q", tt.inputObj.Name(), tt.wantName)
+			}
+		})
+	}
+}
+
+// TestDIDFilterInput verifies that DIDFilterInput has exactly eq and in fields,
+// and that unsupported operators (contains, startsWith, neq, isNull, gt, lt) are absent.
+func TestDIDFilterInput(t *testing.T) {
+	if DIDFilterInput == nil {
+		t.Fatal("DIDFilterInput is nil")
+	}
+
+	fields := DIDFilterInput.Fields()
+
+	// Must have eq and in
+	wantPresent := []string{"eq", "in"}
+	for _, name := range wantPresent {
+		if _, ok := fields[name]; !ok {
+			t.Errorf("DIDFilterInput: expected field %q to be present", name)
+		}
+	}
+
+	// Must NOT have any other operators
+	wantAbsent := []string{"neq", "contains", "startsWith", "isNull", "gt", "lt", "gte", "lte"}
+	for _, name := range wantAbsent {
+		if _, ok := fields[name]; ok {
+			t.Errorf("DIDFilterInput: expected field %q to be absent", name)
+		}
+	}
+}
+
+// TestDIDFilterInput_FieldTypes verifies the GraphQL types of DIDFilterInput fields.
+func TestDIDFilterInput_FieldTypes(t *testing.T) {
+	fields := DIDFilterInput.Fields()
+
+	// eq should be String
+	eqField, ok := fields["eq"]
+	if !ok {
+		t.Fatal("DIDFilterInput: missing field 'eq'")
+	}
+	if eqField.Type != graphql.String {
+		t.Errorf("DIDFilterInput: field 'eq' type = %v, want String", eqField.Type)
+	}
+
+	// in should be [String!]
+	inField, ok := fields["in"]
+	if !ok {
+		t.Fatal("DIDFilterInput: missing field 'in'")
+	}
+	list, ok := inField.Type.(*graphql.List)
+	if !ok {
+		t.Fatalf("DIDFilterInput: field 'in' type = %T, want *graphql.List", inField.Type)
+	}
+	if _, ok := list.OfType.(*graphql.NonNull); !ok {
+		t.Errorf("DIDFilterInput: field 'in' list element type = %T, want *graphql.NonNull", list.OfType)
+	}
+}
diff --git a/internal/graphql/types/mapper.go b/internal/graphql/types/mapper.go
index f2b2b45..bcf0876 100644
--- a/internal/graphql/types/mapper.go
+++ b/internal/graphql/types/mapper.go
@@ -1,5 +1,5 @@
 // Package types provides GraphQL type mapping and building utilities.
-package types
+package types //nolint:revive // package name is descriptive within graphql context
 
 import (
 	"github.com/graphql-go/graphql"
diff --git a/internal/graphql/types/object.go b/internal/graphql/types/object.go
index b583b10..4f696fa 100644
--- a/internal/graphql/types/object.go
+++ b/internal/graphql/types/object.go
@@ -2,12 +2,21 @@ package types //nolint:revive // package name is descriptive within graphql cont
 
 import (
 	"fmt"
+	"log/slog"
 
 	"github.com/graphql-go/graphql"
 
 	"github.com/GainForest/hypergoat/internal/lexicon"
 )
 
+// ReservedRecordFields are field names injected as metadata and must not be overwritten by lexicon properties.
+var ReservedRecordFields = map[string]bool{
+	"uri":  true,
+	"cid":  true,
+	"did":  true,
+	"rkey": true,
+}
+
 // ObjectBuilder builds GraphQL object types from lexicon definitions.
 type ObjectBuilder struct {
 	mapper   *Mapper
@@ -100,6 +109,14 @@ func (b *ObjectBuilder) buildRecordFields(lexiconID string, def *lexicon.RecordD
 			Type:        graphql.NewNonNull(graphql.String),
 			Description: "CID of this record version",
 		},
+		"did": &graphql.Field{
+			Type:        graphql.NewNonNull(graphql.String),
+			Description: "DID of the record author",
+		},
+		"rkey": &graphql.Field{
+			Type:        graphql.NewNonNull(graphql.String),
+			Description: "Record key (last segment of AT-URI)",
+		},
 	}
 
 	// Build required set for quick lookup
@@ -111,6 +128,11 @@ func (b *ObjectBuilder) buildRecordFields(lexiconID string, def *lexicon.RecordD
 	}
 
 	for _, entry := range def.Properties {
+		if ReservedRecordFields[entry.Name] {
+			slog.Warn("Skipping lexicon property that collides with reserved field name",
+				"lexicon", lexiconID, "property", entry.Name)
+			continue
+		}
 		field := b.buildField(lexiconID, entry.Name, &entry.Property, requiredSet[entry.Name])
 		if field != nil {
 			fields[entry.Name] = field
diff --git a/internal/graphql/types/types_test.go b/internal/graphql/types/types_test.go
index 91f4e68..dcbaef9 100644
--- a/internal/graphql/types/types_test.go
+++ b/internal/graphql/types/types_test.go
@@ -241,6 +241,77 @@ func TestObjectBuilder_BuildRecordType(t *testing.T) {
 	}
 }
 
+func TestObjectBuilder_BuildRecordType_SkipsReservedFields(t *testing.T) {
+	// A lexicon that defines properties named "uri", "did", "cid", "rkey" — all reserved.
+	// These must NOT overwrite the metadata fields injected by buildRecordFields.
+	tests := []struct {
+		name         string
+		colliding    string // the reserved property name the lexicon tries to define
+		wantMetaType string // the metadata field's type should remain NonNull String
+	}{
+		{name: "uri collision", colliding: "uri", wantMetaType: "String!"},
+		{name: "did collision", colliding: "did", wantMetaType: "String!"},
+		{name: "cid collision", colliding: "cid", wantMetaType: "String!"},
+		{name: "rkey collision", colliding: "rkey", wantMetaType: "String!"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			registry := lexicon.NewRegistry()
+			mapper := NewMapper()
+			builder := NewObjectBuilder(mapper, registry)
+
+			// Build a unique lexicon ID per sub-test to avoid cache collisions.
+			lexiconID := "com.example.test." + tt.colliding + "collision"
+
+			recordDef := &lexicon.RecordDef{
+				Type: "record",
+				Key:  "tid",
+				Properties: []lexicon.PropertyEntry{
+					{
+						// This property collides with a reserved metadata field.
+						// It should be silently skipped.
+						Name: tt.colliding,
+						Property: lexicon.Property{
+							Type:        "integer", // intentionally different type from the metadata field
+							Description: "Colliding property",
+						},
+					},
+					{
+						// A normal, non-colliding property that must still appear.
+						Name: "title",
+						Property: lexicon.Property{
+							Type: "string",
+						},
+					},
+				},
+			}
+
+			obj := builder.BuildRecordType(lexiconID, recordDef)
+			if obj == nil {
+				t.Fatal("BuildRecordType returned nil")
+			}
+
+			fields := obj.Fields()
+
+			// The reserved metadata field must still be present and be NonNull String.
+			metaField, ok := fields[tt.colliding]
+			if !ok {
+				t.Fatalf("metadata field %q is missing from the type", tt.colliding)
+			}
+			if metaField.Type.String() != tt.wantMetaType {
+				t.Errorf("metadata field %q type = %q, want %q (lexicon property must not overwrite it)",
+					tt.colliding, metaField.Type.String(), tt.wantMetaType)
+			}
+
+			// The normal non-colliding property must still be present.
+			if _, ok := fields["title"]; !ok {
+				t.Error("non-colliding property 'title' is missing from the type")
+			}
+		})
+	}
+}
+
 func TestObjectBuilder_BuildObjectType(t *testing.T) {
 	registry := lexicon.NewRegistry()
 	mapper := NewMapper()
diff --git a/internal/integration/graphql_filter_test.go b/internal/integration/graphql_filter_test.go
new file mode 100644
index 0000000..ea26657
--- /dev/null
+++ b/internal/integration/graphql_filter_test.go
@@ -0,0 +1,1222 @@
+//go:build integration
+
+// Package integration provides end-to-end integration tests for hypergoat.
+package integration
+
+import (
+	"context"
+	"fmt"
+	"testing"
+
+	"github.com/graphql-go/graphql"
+
+	"github.com/GainForest/hypergoat/internal/database/repositories"
+	"github.com/GainForest/hypergoat/internal/graphql/resolver"
+	"github.com/GainForest/hypergoat/internal/graphql/schema"
+	"github.com/GainForest/hypergoat/internal/lexicon"
+)
+
+// testLexiconJSON is a minimal lexicon with string, integer, datetime, and boolean fields.
+const testLexiconJSON = `{
+	"lexicon": 1,
+	"id": "test.collection",
+	"defs": {
+		"main": {
+			"type": "record",
+			"key": "tid",
+			"record": {
+				"type": "object",
+				"required": ["title"],
+				"properties": {
+					"title": {"type": "string"},
+					"score": {"type": "integer"},
+					"createdAt": {"type": "string", "format": "datetime"},
+					"active": {"type": "boolean"},
+					"optionalField": {"type": "string"}
+				}
+			}
+		}
+	}
+}`
+
+// filterTestEnv holds the test environment for filter/sort/search tests.
+type filterTestEnv struct {
+	db     *testDB
+	schema *graphql.Schema
+	ctx    context.Context
+}
+
+// setupFilterTestEnv creates a complete test environment with DB, lexicon, records, and schema.
+func setupFilterTestEnv(t *testing.T) *filterTestEnv {
+	t.Helper()
+
+	db := setupTestDB(t)
+	ctx := context.Background()
+
+	// Parse and register the test lexicon
+	registry := lexicon.NewRegistry()
+	lex, err := lexicon.Parse(testLexiconJSON)
+	if err != nil {
+		t.Fatalf("Failed to parse test lexicon: %v", err)
+	}
+	registry.Register(lex)
+
+	// Insert test records with known content
+	// Use different indexed_at times so ordering is deterministic
+	records := []*repositories.Record{
+		{
+			URI:        "at://did:plc:test123/test.collection/1",
+			CID:        "cid1",
+			DID:        "did:plc:test123",
+			Collection: "test.collection",
+			JSON:       `{"title": "Test Record", "score": 7, "createdAt": "2026-01-01T10:00:00Z", "active": true}`,
+			RKey:       "1",
+		},
+		{
+			URI:        "at://did:plc:test123/test.collection/2",
+			CID:        "cid2",
+			DID:        "did:plc:test123",
+			Collection: "test.collection",
+			JSON:       `{"title": "Another Record", "score": 3, "createdAt": "2026-01-02T10:00:00Z", "active": false}`,
+			RKey:       "2",
+		},
+		{
+			URI:        "at://did:plc:other456/test.collection/1",
+			CID:        "cid3",
+			DID:        "did:plc:other456",
+			Collection: "test.collection",
+			JSON:       `{"title": "Other User Record", "score": 15, "createdAt": "2026-01-03T10:00:00Z", "active": true}`,
+			RKey:       "1",
+		},
+		{
+			URI:        "at://did:plc:test123/test.collection/3",
+			CID:        "cid4",
+			DID:        "did:plc:test123",
+			Collection: "test.collection",
+			JSON:       `{"title": "Searchable Content", "score": 8, "createdAt": "2026-01-04T10:00:00Z", "active": true}`,
+			RKey:       "3",
+		},
+		{
+			URI:        "at://did:plc:other456/test.collection/2",
+			CID:        "cid5",
+			DID:        "did:plc:other456",
+			Collection: "test.collection",
+			JSON:       `{"title": "No Optional", "score": 20, "createdAt": "2026-01-05T10:00:00Z", "active": false}`,
+			RKey:       "2",
+		},
+	}
+
+	if err := db.Records.BatchInsert(ctx, records); err != nil {
+		t.Fatalf("Failed to insert test records: %v", err)
+	}
+
+	// Set deterministic indexed_at times so ordering tests are reliable
+	rawDB := db.Executor.DB()
+	times := []string{
+		"2026-01-01T10:00:00Z",
+		"2026-01-02T10:00:00Z",
+		"2026-01-03T10:00:00Z",
+		"2026-01-04T10:00:00Z",
+		"2026-01-05T10:00:00Z",
+	}
+	uris := []string{
+		"at://did:plc:test123/test.collection/1",
+		"at://did:plc:test123/test.collection/2",
+		"at://did:plc:other456/test.collection/1",
+		"at://did:plc:test123/test.collection/3",
+		"at://did:plc:other456/test.collection/2",
+	}
+	for i, uri := range uris {
+		_, err := rawDB.ExecContext(ctx, `UPDATE record SET indexed_at = ? WHERE uri = ?`, times[i], uri)
+		if err != nil {
+			t.Fatalf("Failed to set indexed_at for %s: %v", uri, err)
+		}
+	}
+
+	// Build the GraphQL schema
+	builder := schema.NewBuilder(registry)
+	gqlSchema, err := builder.Build()
+	if err != nil {
+		t.Fatalf("Failed to build GraphQL schema: %v", err)
+	}
+
+	// Create context with repositories
+	repos := &resolver.Repositories{
+		Records:  db.Records,
+		Actors:   db.Actors,
+		Lexicons: db.Lexicons,
+	}
+	repoCtx := resolver.WithRepositories(ctx, repos)
+
+	return &filterTestEnv{
+		db:     db,
+		schema: gqlSchema,
+		ctx:    repoCtx,
+	}
+}
+
+// runQuery executes a GraphQL query in the filter test environment.
+func (env *filterTestEnv) runQuery(query string) *graphql.Result {
+	return graphql.Do(graphql.Params{
+		Schema:        *env.schema,
+		RequestString: query,
+		Context:       env.ctx,
+	})
+}
+
+// getEdges extracts the edges array from a connection result.
+func getEdges(t *testing.T, result *graphql.Result, fieldName string) []interface{} {
+	t.Helper()
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+	data, ok := result.Data.(map[string]interface{})
+	if !ok {
+		t.Fatalf("Expected data map, got %T", result.Data)
+	}
+	conn, ok := data[fieldName].(map[string]interface{})
+	if !ok {
+		t.Fatalf("Expected connection map for %s, got %T: %v", fieldName, data[fieldName], data[fieldName])
+	}
+	edges, ok := conn["edges"].([]interface{})
+	if !ok {
+		t.Fatalf("Expected edges slice, got %T", conn["edges"])
+	}
+	return edges
+}
+
+// getNodeField extracts a field value from an edge node.
+func getNodeField(t *testing.T, edge interface{}, field string) interface{} {
+	t.Helper()
+	edgeMap, ok := edge.(map[string]interface{})
+	if !ok {
+		t.Fatalf("Expected edge map, got %T", edge)
+	}
+	node, ok := edgeMap["node"].(map[string]interface{})
+	if !ok {
+		t.Fatalf("Expected node map, got %T", edgeMap["node"])
+	}
+	return node[field]
+}
+
+// TestFilterSort_FilterByStringEq tests filtering by string equality.
+func TestFilterSort_FilterByStringEq(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		testCollection(where: {title: {eq: "Test Record"}}) {
+			edges {
+				node {
+					uri
+					title
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	if len(edges) != 1 {
+		t.Errorf("Expected 1 record, got %d", len(edges))
+	}
+	if len(edges) > 0 {
+		uri := getNodeField(t, edges[0], "uri")
+		if uri != "at://did:plc:test123/test.collection/1" {
+			t.Errorf("Expected uri for 'Test Record', got %v", uri)
+		}
+	}
+}
+
+// TestFilterSort_FilterByStringContains tests filtering by string substring.
+func TestFilterSort_FilterByStringContains(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		testCollection(where: {title: {contains: "est"}}) {
+			edges {
+				node {
+					uri
+					title
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	// "Test Record" and "Searchable Content" both contain "est" (case-insensitive in SQLite)
+	// Actually: "Test Record" contains "est", "Searchable Content" does not
+	// Let's check: "Test" -> "est" yes, "Searchable" -> no, "Other" -> no, "Another" -> no, "No Optional" -> no
+	// Only "Test Record" matches
+	if len(edges) != 1 {
+		t.Errorf("Expected 1 record containing 'est', got %d", len(edges))
+		for _, e := range edges {
+			t.Logf("  edge: %v", getNodeField(t, e, "title"))
+		}
+	}
+}
+
+// TestFilterSort_FilterByIntegerGtLt tests filtering by integer range.
+func TestFilterSort_FilterByIntegerGtLt(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// score > 5 AND score < 10 → should match score=7 and score=8
+	query := `{
+		testCollection(where: {score: {gt: 5, lt: 10}}) {
+			edges {
+				node {
+					uri
+					score
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	if len(edges) != 2 {
+		t.Errorf("Expected 2 records with score > 5 and < 10, got %d", len(edges))
+		for _, e := range edges {
+			t.Logf("  edge score: %v", getNodeField(t, e, "score"))
+		}
+	}
+
+	// Verify scores are in range
+	for _, edge := range edges {
+		score := toInt(getNodeField(t, edge, "score"))
+		if score <= 5 || score >= 10 {
+			t.Errorf("Score %d is not in range (5, 10)", score)
+		}
+	}
+}
+
+// TestFilterSort_FilterByDID tests filtering by DID (author).
+func TestFilterSort_FilterByDID(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		testCollection(where: {did: {eq: "did:plc:test123"}}) {
+			edges {
+				node {
+					uri
+					did
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	// did:plc:test123 has 3 records
+	if len(edges) != 3 {
+		t.Errorf("Expected 3 records for did:plc:test123, got %d", len(edges))
+	}
+
+	for _, edge := range edges {
+		did := getNodeField(t, edge, "did")
+		if did != "did:plc:test123" {
+			t.Errorf("Expected did:plc:test123, got %v", did)
+		}
+	}
+}
+
+// TestFilterSort_FilterByIsNull tests filtering by null field.
+func TestFilterSort_FilterByIsNull(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// All 5 records don't have optionalField set, so isNull: true should return all
+	query := `{
+		testCollection(where: {optionalField: {isNull: true}}) {
+			edges {
+				node {
+					uri
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	// All records have no optionalField in their JSON
+	if len(edges) != 5 {
+		t.Errorf("Expected 5 records with optionalField isNull, got %d", len(edges))
+	}
+}
+
+// TestFilterSort_SortByFieldASC tests sorting by a field in ascending order.
+func TestFilterSort_SortByFieldASC(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		testCollection(sortBy: title, sortDirection: ASC) {
+			edges {
+				node {
+					title
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	if len(edges) != 5 {
+		t.Fatalf("Expected 5 records, got %d", len(edges))
+	}
+
+	// Verify ascending order by title
+	titles := make([]string, len(edges))
+	for i, edge := range edges {
+		titles[i] = fmt.Sprintf("%v", getNodeField(t, edge, "title"))
+	}
+
+	for i := 1; i < len(titles); i++ {
+		if titles[i] < titles[i-1] {
+			t.Errorf("Records not in ASC order: %q comes after %q", titles[i], titles[i-1])
+		}
+	}
+}
+
+// TestFilterSort_SortByIndexedAtDESC tests sorting by indexed_at in descending order.
+func TestFilterSort_SortByIndexedAtDESC(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		testCollection(sortBy: indexed_at, sortDirection: DESC) {
+			edges {
+				node {
+					uri
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	if len(edges) != 5 {
+		t.Fatalf("Expected 5 records, got %d", len(edges))
+	}
+
+	// Newest first: record 5 (2026-01-05), 4 (2026-01-04), 3 (2026-01-03), 2 (2026-01-02), 1 (2026-01-01)
+	expectedURIs := []string{
+		"at://did:plc:other456/test.collection/2",
+		"at://did:plc:test123/test.collection/3",
+		"at://did:plc:other456/test.collection/1",
+		"at://did:plc:test123/test.collection/2",
+		"at://did:plc:test123/test.collection/1",
+	}
+
+	for i, edge := range edges {
+		uri := getNodeField(t, edge, "uri")
+		if uri != expectedURIs[i] {
+			t.Errorf("Edge %d: expected URI %s, got %v", i, expectedURIs[i], uri)
+		}
+	}
+}
+
+// TestFilterSort_SortWithPagination tests sort + cursor-based pagination.
+func TestFilterSort_SortWithPagination(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// First page: get 2 records sorted by indexed_at ASC
+	firstPageQuery := `{
+		testCollection(sortBy: indexed_at, sortDirection: ASC, first: 2) {
+			edges {
+				cursor
+				node {
+					uri
+				}
+			}
+			pageInfo {
+				hasNextPage
+				endCursor
+			}
+		}
+	}`
+
+	result := env.runQuery(firstPageQuery)
+	if len(result.Errors) > 0 {
+		t.Fatalf("First page errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["testCollection"].(map[string]interface{})
+	edges := conn["edges"].([]interface{})
+	pageInfo := conn["pageInfo"].(map[string]interface{})
+
+	if len(edges) != 2 {
+		t.Fatalf("Expected 2 edges on first page, got %d", len(edges))
+	}
+
+	hasNextPage, _ := pageInfo["hasNextPage"].(bool)
+	if !hasNextPage {
+		t.Error("Expected hasNextPage to be true")
+	}
+
+	endCursor, _ := pageInfo["endCursor"].(string)
+	if endCursor == "" {
+		t.Fatal("Expected non-empty endCursor")
+	}
+
+	// Verify first page has oldest records (ASC order)
+	firstURI := getNodeField(t, edges[0], "uri")
+	if firstURI != "at://did:plc:test123/test.collection/1" {
+		t.Errorf("Expected oldest record first, got %v", firstURI)
+	}
+
+	// Second page: use cursor from first page
+	secondPageQuery := fmt.Sprintf(`{
+		testCollection(sortBy: indexed_at, sortDirection: ASC, first: 2, after: "%s") {
+			edges {
+				node {
+					uri
+				}
+			}
+			pageInfo {
+				hasNextPage
+				hasPreviousPage
+			}
+		}
+	}`, endCursor)
+
+	result2 := env.runQuery(secondPageQuery)
+	if len(result2.Errors) > 0 {
+		t.Fatalf("Second page errors: %v", result2.Errors)
+	}
+
+	data2 := result2.Data.(map[string]interface{})
+	conn2 := data2["testCollection"].(map[string]interface{})
+	edges2 := conn2["edges"].([]interface{})
+	pageInfo2 := conn2["pageInfo"].(map[string]interface{})
+
+	if len(edges2) != 2 {
+		t.Fatalf("Expected 2 edges on second page, got %d", len(edges2))
+	}
+
+	hasPreviousPage, _ := pageInfo2["hasPreviousPage"].(bool)
+	if !hasPreviousPage {
+		t.Error("Expected hasPreviousPage to be true on second page")
+	}
+
+	// Second page should have records 3 and 4 (by indexed_at ASC)
+	secondURI := getNodeField(t, edges2[0], "uri")
+	if secondURI != "at://did:plc:other456/test.collection/1" {
+		t.Errorf("Expected 3rd oldest record on second page, got %v", secondURI)
+	}
+}
+
+// TestFilterSort_TotalCountOptIn tests that totalCount is returned when requested.
+func TestFilterSort_TotalCountOptIn(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		testCollection {
+			edges {
+				node { uri }
+			}
+			totalCount
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["testCollection"].(map[string]interface{})
+
+	totalCount, ok := conn["totalCount"]
+	if !ok {
+		t.Fatal("Expected totalCount in response")
+	}
+
+	count := toInt(totalCount)
+	if count != 5 {
+		t.Errorf("Expected totalCount = 5, got %d", count)
+	}
+}
+
+// TestFilterSort_TotalCountOmitted tests that totalCount is null when not requested.
+func TestFilterSort_TotalCountOmitted(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// Query WITHOUT selecting totalCount
+	query := `{
+		testCollection {
+			edges {
+				node { uri }
+			}
+			pageInfo {
+				hasNextPage
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["testCollection"].(map[string]interface{})
+
+	// totalCount should not be present (or be nil) when not requested
+	totalCount, exists := conn["totalCount"]
+	if exists && totalCount != nil {
+		t.Errorf("Expected totalCount to be nil when not requested, got %v", totalCount)
+	}
+}
+
+// TestFilterSort_MaxPageSize tests that first: 500 is clamped to 100.
+func TestFilterSort_MaxPageSize(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// Insert enough records to test clamping (we have 5, so just verify we get at most 100)
+	query := `{
+		testCollection(first: 500) {
+			edges {
+				node { uri }
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	// We only have 5 records, but the query should be clamped to 100 max
+	// Since we have fewer than 100, we get all 5
+	if len(edges) > 100 {
+		t.Errorf("Expected at most 100 records, got %d", len(edges))
+	}
+
+	// Verify we get all 5 records (since 5 < 100)
+	if len(edges) != 5 {
+		t.Errorf("Expected 5 records (all available), got %d", len(edges))
+	}
+}
+
+// TestFilterSort_Search tests basic text search.
+func TestFilterSort_Search(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		search(query: "Searchable") {
+			edges {
+				node {
+					uri
+					collection
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["search"].(map[string]interface{})
+	edges := conn["edges"].([]interface{})
+
+	if len(edges) != 1 {
+		t.Errorf("Expected 1 search result for 'Searchable', got %d", len(edges))
+	}
+
+	if len(edges) > 0 {
+		uri := getNodeField(t, edges[0], "uri")
+		if uri != "at://did:plc:test123/test.collection/3" {
+			t.Errorf("Expected URI for 'Searchable Content', got %v", uri)
+		}
+	}
+}
+
+// TestFilterSort_SearchWithCollectionFilter tests search with collection filter.
+func TestFilterSort_SearchWithCollectionFilter(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// Insert a record in a different collection that also matches the search term
+	otherRecord := []*repositories.Record{
+		{
+			URI:        "at://did:plc:test123/other.collection/1",
+			CID:        "cid_other",
+			DID:        "did:plc:test123",
+			Collection: "other.collection",
+			JSON:       `{"content": "Searchable in other collection"}`,
+			RKey:       "1",
+		},
+	}
+	if err := env.db.Records.BatchInsert(env.ctx, otherRecord); err != nil {
+		t.Fatalf("Failed to insert other collection record: %v", err)
+	}
+
+	// Search with collection filter — should only return test.collection results
+	query := `{
+		search(query: "Searchable", collection: "test.collection") {
+			edges {
+				node {
+					uri
+					collection
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["search"].(map[string]interface{})
+	edges := conn["edges"].([]interface{})
+
+	// Should only find the test.collection record, not the other.collection one
+	for _, edge := range edges {
+		coll := getNodeField(t, edge, "collection")
+		if coll != "test.collection" {
+			t.Errorf("Expected collection 'test.collection', got %v", coll)
+		}
+	}
+
+	if len(edges) != 1 {
+		t.Errorf("Expected 1 result in test.collection, got %d", len(edges))
+	}
+}
+
+// TestFilterSort_BackwardCompatibility tests that queries without where/sort args work as before.
+func TestFilterSort_BackwardCompatibility(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// Query without any where/sort args — should return all records in default order (indexed_at DESC)
+	query := `{
+		testCollection {
+			edges {
+				node {
+					uri
+				}
+			}
+			pageInfo {
+				hasNextPage
+				hasPreviousPage
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["testCollection"].(map[string]interface{})
+	edges := conn["edges"].([]interface{})
+	pageInfo := conn["pageInfo"].(map[string]interface{})
+
+	// Should return all 5 records
+	if len(edges) != 5 {
+		t.Errorf("Expected 5 records, got %d", len(edges))
+	}
+
+	// Default order is indexed_at DESC (newest first)
+	firstURI := getNodeField(t, edges[0], "uri")
+	if firstURI != "at://did:plc:other456/test.collection/2" {
+		t.Errorf("Expected newest record first (indexed_at DESC), got %v", firstURI)
+	}
+
+	// No pagination cursors used, so hasPreviousPage should be false
+	hasPreviousPage, _ := pageInfo["hasPreviousPage"].(bool)
+	if hasPreviousPage {
+		t.Error("Expected hasPreviousPage to be false for first page")
+	}
+
+	hasNextPage, _ := pageInfo["hasNextPage"].(bool)
+	if hasNextPage {
+		t.Error("Expected hasNextPage to be false when all records fit on one page")
+	}
+}
+
+// TestFilterSort_EmptyResults tests that filters returning no results work correctly.
+func TestFilterSort_EmptyResults(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		testCollection(where: {title: {eq: "NonExistentTitle"}}) {
+			edges {
+				node { uri }
+			}
+			pageInfo {
+				hasNextPage
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["testCollection"].(map[string]interface{})
+	edges := conn["edges"].([]interface{})
+
+	if len(edges) != 0 {
+		t.Errorf("Expected 0 records for non-existent title, got %d", len(edges))
+	}
+
+	pageInfo := conn["pageInfo"].(map[string]interface{})
+	hasNextPage, _ := pageInfo["hasNextPage"].(bool)
+	if hasNextPage {
+		t.Error("Expected hasNextPage to be false for empty results")
+	}
+}
+
+// TestFilterSort_SearchShortQueryError tests that search with < 3 runes returns an error.
+func TestFilterSort_SearchShortQueryError(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	tests := []struct {
+		name  string
+		query string
+	}{
+		{
+			name:  "empty query",
+			query: `{ search(query: "") { edges { node { uri } } } }`,
+		},
+		{
+			name:  "single char query",
+			query: `{ search(query: "a") { edges { node { uri } } } }`,
+		},
+		{
+			name:  "two char query",
+			query: `{ search(query: "ab") { edges { node { uri } } } }`,
+		},
+		{
+			name:  "two multi-byte char query",
+			query: `{ search(query: "éé") { edges { node { uri } } } }`,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := env.runQuery(tt.query)
+			if len(result.Errors) == 0 {
+				t.Error("Expected error for short search query, got none")
+			}
+		})
+	}
+}
+
+// TestFilterSort_TotalCountWithFilter tests totalCount with active filters.
+func TestFilterSort_TotalCountWithFilter(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// Filter by DID and request totalCount
+	query := `{
+		testCollection(where: {did: {eq: "did:plc:test123"}}) {
+			edges {
+				node { uri }
+			}
+			totalCount
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["testCollection"].(map[string]interface{})
+
+	totalCount := toInt(conn["totalCount"])
+	if totalCount != 3 {
+		t.Errorf("Expected totalCount = 3 for did:plc:test123, got %d", totalCount)
+	}
+
+	edges := conn["edges"].([]interface{})
+	if len(edges) != 3 {
+		t.Errorf("Expected 3 edges, got %d", len(edges))
+	}
+}
+
+// TestFilterSort_GenericRecordsQuery tests the generic records query still works.
+func TestFilterSort_GenericRecordsQuery(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	query := `{
+		records(collection: "test.collection", first: 10) {
+			edges {
+				node {
+					uri
+					collection
+					did
+				}
+			}
+			pageInfo {
+				hasNextPage
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	if len(result.Errors) > 0 {
+		t.Fatalf("GraphQL errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["records"].(map[string]interface{})
+	edges := conn["edges"].([]interface{})
+
+	if len(edges) != 5 {
+		t.Errorf("Expected 5 records from generic query, got %d", len(edges))
+	}
+
+	// Verify all records are from the correct collection
+	for _, edge := range edges {
+		coll := getNodeField(t, edge, "collection")
+		if coll != "test.collection" {
+			t.Errorf("Expected collection 'test.collection', got %v", coll)
+		}
+	}
+}
+
+// TestFilterSort_MultipleFiltersANDed tests that multiple filter fields are ANDed.
+func TestFilterSort_MultipleFiltersANDed(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// Filter by DID AND score > 5 — should return records from did:plc:test123 with score > 5
+	// did:plc:test123 records: score=7, score=3, score=8
+	// After score > 5: score=7 and score=8
+	query := `{
+		testCollection(where: {did: {eq: "did:plc:test123"}, score: {gt: 5}}) {
+			edges {
+				node {
+					uri
+					score
+					did
+				}
+			}
+		}
+	}`
+
+	result := env.runQuery(query)
+	edges := getEdges(t, result, "testCollection")
+
+	if len(edges) != 2 {
+		t.Errorf("Expected 2 records (DID filter AND score > 5), got %d", len(edges))
+		for _, e := range edges {
+			t.Logf("  uri=%v score=%v did=%v", getNodeField(t, e, "uri"), getNodeField(t, e, "score"), getNodeField(t, e, "did"))
+		}
+	}
+
+	for _, edge := range edges {
+		did := getNodeField(t, edge, "did")
+		score := toInt(getNodeField(t, edge, "score"))
+		if did != "did:plc:test123" {
+			t.Errorf("Expected did:plc:test123, got %v", did)
+		}
+		if score <= 5 {
+			t.Errorf("Expected score > 5, got %d", score)
+		}
+	}
+}
+
+// TestFilterSort_SearchPagination tests pagination on search results.
+func TestFilterSort_SearchPagination(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	// Search for "Record" which appears in multiple titles
+	// "Test Record", "Another Record", "Other User Record"
+	firstPageQuery := `{
+		search(query: "Record", first: 2) {
+			edges {
+				cursor
+				node { uri }
+			}
+			pageInfo {
+				hasNextPage
+				endCursor
+			}
+		}
+	}`
+
+	result := env.runQuery(firstPageQuery)
+	if len(result.Errors) > 0 {
+		t.Fatalf("First page errors: %v", result.Errors)
+	}
+
+	data := result.Data.(map[string]interface{})
+	conn := data["search"].(map[string]interface{})
+	edges := conn["edges"].([]interface{})
+	pageInfo := conn["pageInfo"].(map[string]interface{})
+
+	if len(edges) != 2 {
+		t.Fatalf("Expected 2 edges on first page, got %d", len(edges))
+	}
+
+	hasNextPage, _ := pageInfo["hasNextPage"].(bool)
+	if !hasNextPage {
+		t.Error("Expected hasNextPage to be true")
+	}
+
+	endCursor, _ := pageInfo["endCursor"].(string)
+	if endCursor == "" {
+		t.Fatal("Expected non-empty endCursor")
+	}
+
+	// Second page
+	secondPageQuery := fmt.Sprintf(`{
+		search(query: "Record", first: 2, after: "%s") {
+			edges {
+				node { uri }
+			}
+			pageInfo {
+				hasNextPage
+			}
+		}
+	}`, endCursor)
+
+	result2 := env.runQuery(secondPageQuery)
+	if len(result2.Errors) > 0 {
+		t.Fatalf("Second page errors: %v", result2.Errors)
+	}
+
+	data2 := result2.Data.(map[string]interface{})
+	conn2 := data2["search"].(map[string]interface{})
+	edges2 := conn2["edges"].([]interface{})
+
+	// Should have 1 remaining record
+	if len(edges2) != 1 {
+		t.Errorf("Expected 1 edge on second page, got %d", len(edges2))
+	}
+}
+
+// TestFilterSort_IndependentTests verifies that each test case is independent.
+// This test inserts its own records and verifies isolation.
+func TestFilterSort_IndependentTests(t *testing.T) {
+	// Each call to setupFilterTestEnv creates a fresh DB
+	env1 := setupFilterTestEnv(t)
+	env2 := setupFilterTestEnv(t)
+
+	// Both environments should have exactly 5 records
+	query := `{ testCollection { edges { node { uri } } } }`
+
+	result1 := env1.runQuery(query)
+	result2 := env2.runQuery(query)
+
+	edges1 := getEdges(t, result1, "testCollection")
+	edges2 := getEdges(t, result2, "testCollection")
+
+	if len(edges1) != 5 {
+		t.Errorf("env1: expected 5 records, got %d", len(edges1))
+	}
+	if len(edges2) != 5 {
+		t.Errorf("env2: expected 5 records, got %d", len(edges2))
+	}
+
+	// Modifying env1 should not affect env2
+	newRecord := []*repositories.Record{
+		{
+			URI:        "at://did:plc:extra/test.collection/1",
+			CID:        "cid_extra",
+			DID:        "did:plc:extra",
+			Collection: "test.collection",
+			JSON:       `{"title": "Extra Record", "score": 1}`,
+			RKey:       "1",
+		},
+	}
+	if err := env1.db.Records.BatchInsert(env1.ctx, newRecord); err != nil {
+		t.Fatalf("Failed to insert extra record: %v", err)
+	}
+
+	result1After := env1.runQuery(query)
+	result2After := env2.runQuery(query)
+
+	edges1After := getEdges(t, result1After, "testCollection")
+	edges2After := getEdges(t, result2After, "testCollection")
+
+	if len(edges1After) != 6 {
+		t.Errorf("env1 after insert: expected 6 records, got %d", len(edges1After))
+	}
+	if len(edges2After) != 5 {
+		t.Errorf("env2 after env1 insert: expected 5 records (unchanged), got %d", len(edges2After))
+	}
+}
+
+// TestFilterSort_TableDriven is a table-driven test covering multiple filter scenarios.
+func TestFilterSort_TableDriven(t *testing.T) {
+	tests := []struct {
+		name          string
+		query         string
+		wantEdgeCount int
+		wantErrors    bool
+	}{
+		{
+			name: "no filters returns all",
+			query: `{
+				testCollection {
+					edges { node { uri } }
+				}
+			}`,
+			wantEdgeCount: 5,
+		},
+		{
+			name: "filter by active true",
+			query: `{
+				testCollection(where: {active: {eq: true}}) {
+					edges { node { uri } }
+				}
+			}`,
+			wantEdgeCount: 3, // records 1, 3, 4 have active: true
+		},
+		{
+			name: "filter by active false",
+			query: `{
+				testCollection(where: {active: {eq: false}}) {
+					edges { node { uri } }
+				}
+			}`,
+			wantEdgeCount: 2, // records 2, 5 have active: false
+		},
+		{
+			name: "filter by score gte 15",
+			query: `{
+				testCollection(where: {score: {gte: 15}}) {
+					edges { node { uri } }
+				}
+			}`,
+			wantEdgeCount: 2, // score=15 and score=20
+		},
+		{
+			name: "filter by score lte 3",
+			query: `{
+				testCollection(where: {score: {lte: 3}}) {
+					edges { node { uri } }
+				}
+			}`,
+			wantEdgeCount: 1, // score=3
+		},
+		{
+			name: "filter by title startsWith",
+			query: `{
+				testCollection(where: {title: {startsWith: "Test"}}) {
+					edges { node { uri } }
+				}
+			}`,
+			wantEdgeCount: 1, // "Test Record"
+		},
+		{
+			name: "search with valid query",
+			query: `{
+				search(query: "Other") {
+					edges { node { uri } }
+				}
+			}`,
+			// SQLite LIKE is case-insensitive: "Other User Record" and "Another Record" both match "Other"
+			wantEdgeCount: 2,
+		},
+		{
+			name: "search returns empty for no match",
+			query: `{
+				search(query: "zzznomatch") {
+					edges { node { uri } }
+				}
+			}`,
+			wantEdgeCount: 0,
+		},
+		{
+			name:       "search with empty query returns error",
+			query:      `{ search(query: "") { edges { node { uri } } } }`,
+			wantErrors: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			env := setupFilterTestEnv(t)
+			result := env.runQuery(tt.query)
+
+			if tt.wantErrors {
+				if len(result.Errors) == 0 {
+					t.Error("Expected errors but got none")
+				}
+				return
+			}
+
+			if len(result.Errors) > 0 {
+				t.Fatalf("Unexpected errors: %v", result.Errors)
+			}
+
+			// Determine the connection field name
+			data := result.Data.(map[string]interface{})
+			var edges []interface{}
+			for _, v := range data {
+				if conn, ok := v.(map[string]interface{}); ok {
+					if e, ok := conn["edges"].([]interface{}); ok {
+						edges = e
+						break
+					}
+				}
+			}
+
+			if len(edges) != tt.wantEdgeCount {
+				t.Errorf("Expected %d edges, got %d", tt.wantEdgeCount, len(edges))
+				for _, e := range edges {
+					if em, ok := e.(map[string]interface{}); ok {
+						if node, ok := em["node"].(map[string]interface{}); ok {
+							t.Logf("  uri=%v", node["uri"])
+						}
+					}
+				}
+			}
+		})
+	}
+}
+
+// TestFilterSort_SearchCaseInsensitive tests that search is case-insensitive.
+func TestFilterSort_SearchCaseInsensitive(t *testing.T) {
+	env := setupFilterTestEnv(t)
+
+	tests := []struct {
+		name  string
+		query string
+	}{
+		{name: "lowercase", query: "searchable"},
+		{name: "uppercase", query: "SEARCHABLE"},
+		{name: "mixed case", query: "Searchable"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			gqlQuery := fmt.Sprintf(`{
+				search(query: "%s") {
+					edges {
+						node { uri }
+					}
+				}
+			}`, tt.query)
+
+			result := env.runQuery(gqlQuery)
+			if len(result.Errors) > 0 {
+				t.Fatalf("GraphQL errors: %v", result.Errors)
+			}
+
+			data := result.Data.(map[string]interface{})
+			conn := data["search"].(map[string]interface{})
+			edges := conn["edges"].([]interface{})
+
+			// SQLite LIKE is case-insensitive for ASCII characters
+			if len(edges) != 1 {
+				t.Errorf("Expected 1 result for case-insensitive search %q, got %d", tt.query, len(edges))
+			}
+		})
+	}
+}
diff --git a/internal/lexicon/types.go b/internal/lexicon/types.go
index 03de3c1..f68faaf 100644
--- a/internal/lexicon/types.go
+++ b/internal/lexicon/types.go
@@ -219,3 +219,34 @@ func (p *Property) GetRefs() []string {
 	}
 	return nil
 }
+
+// ZeroValueForType returns the appropriate Go zero value for a given lexicon property type.
+// For complex types (ref, union, blob, bytes, cid-link, unknown, object) it returns nil,
+// as these cannot have a meaningful scalar zero value.
+func ZeroValueForType(propType string) interface{} {
+	switch propType {
+	case TypeString:
+		return ""
+	case TypeInteger:
+		return 0
+	case TypeBoolean:
+		return false
+	case TypeArray:
+		return []interface{}{}
+	default:
+		// ref, union, blob, bytes, cid-link, unknown, object — return nil
+		// These are complex types that cannot have a meaningful zero value
+		return nil
+	}
+}
+
+// RequiredProperties returns all properties that are marked as required.
+func (r *RecordDef) RequiredProperties() []PropertyEntry {
+	var result []PropertyEntry
+	for _, entry := range r.Properties {
+		if entry.Property.Required {
+			result = append(result, entry)
+		}
+	}
+	return result
+}
diff --git a/internal/lexicon/types_test.go b/internal/lexicon/types_test.go
new file mode 100644
index 0000000..c480556
--- /dev/null
+++ b/internal/lexicon/types_test.go
@@ -0,0 +1,87 @@
+package lexicon
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestZeroValueForType(t *testing.T) {
+	tests := []struct {
+		name     string
+		propType string
+		want     interface{}
+	}{
+		{name: "string no format", propType: "string", want: ""},
+		{name: "string datetime format", propType: "string", want: ""},
+		{name: "integer", propType: "integer", want: 0},
+		{name: "boolean", propType: "boolean", want: false},
+		{name: "array", propType: "array", want: []interface{}{}},
+		{name: "ref", propType: "ref", want: nil},
+		{name: "union", propType: "union", want: nil},
+		{name: "blob", propType: "blob", want: nil},
+		{name: "bytes", propType: "bytes", want: nil},
+		{name: "cid-link", propType: "cid-link", want: nil},
+		{name: "unknown", propType: "unknown", want: nil},
+		{name: "object", propType: "object", want: nil},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := ZeroValueForType(tt.propType)
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("ZeroValueForType(%q) = %v (%T), want %v (%T)",
+					tt.propType, got, got, tt.want, tt.want)
+			}
+		})
+	}
+}
+
+func TestRecordDefRequiredProperties(t *testing.T) {
+	rec := &RecordDef{
+		Type: "record",
+		Properties: []PropertyEntry{
+			{Name: "title", Property: Property{Type: TypeString, Required: true}},
+			{Name: "description", Property: Property{Type: TypeString, Required: false}},
+			{Name: "count", Property: Property{Type: TypeInteger, Required: true}},
+			{Name: "tags", Property: Property{Type: TypeArray, Required: false}},
+		},
+	}
+
+	required := rec.RequiredProperties()
+
+	if len(required) != 2 {
+		t.Fatalf("expected 2 required properties, got %d", len(required))
+	}
+
+	names := make([]string, len(required))
+	for i, e := range required {
+		names[i] = e.Name
+	}
+
+	if names[0] != "title" {
+		t.Errorf("expected first required property to be 'title', got %q", names[0])
+	}
+	if names[1] != "count" {
+		t.Errorf("expected second required property to be 'count', got %q", names[1])
+	}
+
+	// Verify non-required properties are excluded
+	for _, e := range required {
+		if !e.Property.Required {
+			t.Errorf("property %q is not required but was returned by RequiredProperties()", e.Name)
+		}
+	}
+}
+
+func TestRecordDefRequiredPropertiesEmpty(t *testing.T) {
+	rec := &RecordDef{
+		Type: "record",
+		Properties: []PropertyEntry{
+			{Name: "optional", Property: Property{Type: TypeString, Required: false}},
+		},
+	}
+
+	required := rec.RequiredProperties()
+	if len(required) != 0 {
+		t.Errorf("expected 0 required properties, got %d", len(required))
+	}
+}
diff --git a/internal/server/graphiql.go b/internal/server/graphiql.go
index 0dba001..2fb6655 100644
--- a/internal/server/graphiql.go
+++ b/internal/server/graphiql.go
@@ -1,4 +1,4 @@
-// Package server contains HTTP handlers for the hypergoat server.
+// Package server contains HTTP handlers for the Hyperindex server.
 // GraphiQL playground handler using CDN-hosted resources.
 package server
 
diff --git a/internal/server/handlers_test.go b/internal/server/handlers_test.go
index 5e27957..d7a789d 100644
--- a/internal/server/handlers_test.go
+++ b/internal/server/handlers_test.go
@@ -315,7 +315,7 @@ func TestHandleClientMetadata(t *testing.T) {
 func TestHandleGraphiQL(t *testing.T) {
 	baseCfg := GraphiQLConfig{
 		Endpoint: "/graphql",
-		Title:    "Hypergoat GraphiQL",
+		Title:    "Hyperindex GraphiQL",
 	}
 
 	t.Run("GET returns 200 with text/html content type", func(t *testing.T) {
@@ -356,7 +356,7 @@ func TestHandleGraphiQL(t *testing.T) {
 		handler.ServeHTTP(rec, req)
 
 		body := rec.Body.String()
-		if !strings.Contains(body, "Hypergoat GraphiQL") {
+		if !strings.Contains(body, "Hyperindex GraphiQL") {
 			t.Error("response body does not contain title")
 		}
 	})
diff --git a/internal/tap/admin.go b/internal/tap/admin.go
new file mode 100644
index 0000000..6467bba
--- /dev/null
+++ b/internal/tap/admin.go
@@ -0,0 +1,159 @@
+// Package tap provides a client for the Tap sidecar HTTP and WebSocket APIs.
+package tap
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"time"
+)
+
+const (
+	// defaultHTTPTimeout is the timeout for all Tap admin HTTP requests.
+	defaultHTTPTimeout = 30 * time.Second
+)
+
+// AdminClient communicates with Tap's HTTP API for repo management.
+type AdminClient struct {
+	baseURL  string // e.g., "http://localhost:2480"
+	password string // Basic auth password (empty = no auth)
+	client   *http.Client
+}
+
+// NewAdminClient creates a new Tap admin HTTP client.
+func NewAdminClient(baseURL, password string) *AdminClient {
+	return &AdminClient{
+		baseURL:  baseURL,
+		password: password,
+		client: &http.Client{
+			Timeout: defaultHTTPTimeout,
+		},
+	}
+}
+
+// RepoInfoResponse holds the response from GET /info/:did.
+type RepoInfoResponse struct {
+	DID    string `json:"did"`
+	Status string `json:"status"`
+	Rev    string `json:"rev,omitempty"`
+}
+
+// didsBody is the JSON body for /repos/add and /repos/remove.
+type didsBody struct {
+	DIDs []string `json:"dids"`
+}
+
+// healthResponse is the expected JSON body from GET /health.
+type healthResponse struct {
+	Status string `json:"status"`
+}
+
+// AddRepos adds DIDs to Tap's tracking list, triggering backfill.
+// POST /repos/add with body {"dids": ["did:plc:abc", ...]}
+func (c *AdminClient) AddRepos(ctx context.Context, dids []string) error {
+	return c.postDIDs(ctx, "/repos/add", dids)
+}
+
+// RemoveRepos removes DIDs from Tap's tracking list.
+// POST /repos/remove with body {"dids": ["did:plc:abc", ...]}
+func (c *AdminClient) RemoveRepos(ctx context.Context, dids []string) error {
+	return c.postDIDs(ctx, "/repos/remove", dids)
+}
+
+// Health checks if Tap is healthy.
+// GET /health — expects {"status":"ok"}
+func (c *AdminClient) Health(ctx context.Context) error {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/health", http.NoBody)
+	if err != nil {
+		return fmt.Errorf("failed to create health request: %w", err)
+	}
+	c.setAuth(req)
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return fmt.Errorf("health request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("health check returned HTTP %d", resp.StatusCode)
+	}
+
+	var body healthResponse
+	if err := json.NewDecoder(resp.Body).Decode(&body); err != nil {
+		return fmt.Errorf("failed to decode health response: %w", err)
+	}
+
+	if body.Status != "ok" {
+		return fmt.Errorf("tap reported unhealthy status: %q", body.Status)
+	}
+
+	return nil
+}
+
+// RepoInfo gets info about a tracked repo.
+// GET /info/:did
+func (c *AdminClient) RepoInfo(ctx context.Context, did string) (*RepoInfoResponse, error) {
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/info/"+did, http.NoBody)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create repo info request: %w", err)
+	}
+	c.setAuth(req)
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("repo info request failed: %w", err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("repo info returned HTTP %d", resp.StatusCode)
+	}
+
+	var info RepoInfoResponse
+	if err := json.NewDecoder(resp.Body).Decode(&info); err != nil {
+		return nil, fmt.Errorf("failed to decode repo info response: %w", err)
+	}
+
+	return &info, nil
+}
+
+// postDIDs sends a POST request with a {"dids": [...]} body to the given path.
+func (c *AdminClient) postDIDs(ctx context.Context, path string, dids []string) error {
+	body, err := json.Marshal(didsBody{DIDs: dids})
+	if err != nil {
+		return fmt.Errorf("failed to marshal request body: %w", err)
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, c.baseURL+path, bytes.NewReader(body))
+	if err != nil {
+		return fmt.Errorf("failed to create request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	c.setAuth(req)
+
+	resp, err := c.client.Do(req)
+	if err != nil {
+		return fmt.Errorf("request to %s failed: %w", path, err)
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return fmt.Errorf("request to %s returned HTTP %d", path, resp.StatusCode)
+	}
+
+	return nil
+}
+
+// setAuth adds a Basic auth header if a password is configured.
+// The username is always "admin".
+func (c *AdminClient) setAuth(req *http.Request) {
+	if c.password == "" {
+		return
+	}
+	creds := base64.StdEncoding.EncodeToString([]byte("admin:" + c.password))
+	req.Header.Set("Authorization", "Basic "+creds)
+}
diff --git a/internal/tap/admin_test.go b/internal/tap/admin_test.go
new file mode 100644
index 0000000..3bd63de
--- /dev/null
+++ b/internal/tap/admin_test.go
@@ -0,0 +1,330 @@
+package tap
+
+import (
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+)
+
+// TestAdminClient_AddRepos verifies POST /repos/add sends the correct JSON body.
+func TestAdminClient_AddRepos(t *testing.T) {
+	tests := []struct {
+		name     string
+		dids     []string
+		password string
+		status   int
+		wantErr  bool
+	}{
+		{
+			name:    "success with multiple DIDs",
+			dids:    []string{"did:plc:abc", "did:plc:def"},
+			status:  http.StatusOK,
+			wantErr: false,
+		},
+		{
+			name:    "success with single DID",
+			dids:    []string{"did:plc:abc"},
+			status:  http.StatusOK,
+			wantErr: false,
+		},
+		{
+			name:    "server error returns error",
+			dids:    []string{"did:plc:abc"},
+			status:  http.StatusInternalServerError,
+			wantErr: true,
+		},
+		{
+			name:    "bad request returns error",
+			dids:    []string{"did:plc:abc"},
+			status:  http.StatusBadRequest,
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var gotBody didsBody
+			var gotPath string
+
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				gotPath = r.URL.Path
+				if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
+					http.Error(w, "bad body", http.StatusBadRequest)
+					return
+				}
+				w.WriteHeader(tt.status)
+			}))
+			defer srv.Close()
+
+			c := NewAdminClient(srv.URL, tt.password)
+			err := c.AddRepos(context.Background(), tt.dids)
+
+			if (err != nil) != tt.wantErr {
+				t.Errorf("AddRepos() error = %v, wantErr %v", err, tt.wantErr)
+			}
+
+			if !tt.wantErr {
+				if gotPath != "/repos/add" {
+					t.Errorf("expected path /repos/add, got %s", gotPath)
+				}
+				if len(gotBody.DIDs) != len(tt.dids) {
+					t.Errorf("expected %d DIDs, got %d", len(tt.dids), len(gotBody.DIDs))
+				}
+				for i, did := range tt.dids {
+					if gotBody.DIDs[i] != did {
+						t.Errorf("DID[%d]: expected %s, got %s", i, did, gotBody.DIDs[i])
+					}
+				}
+			}
+		})
+	}
+}
+
+// TestAdminClient_RemoveRepos verifies POST /repos/remove sends the correct JSON body.
+func TestAdminClient_RemoveRepos(t *testing.T) {
+	tests := []struct {
+		name    string
+		dids    []string
+		status  int
+		wantErr bool
+	}{
+		{
+			name:    "success",
+			dids:    []string{"did:plc:abc"},
+			status:  http.StatusOK,
+			wantErr: false,
+		},
+		{
+			name:    "server error returns error",
+			dids:    []string{"did:plc:abc"},
+			status:  http.StatusInternalServerError,
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var gotBody didsBody
+			var gotPath string
+
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				gotPath = r.URL.Path
+				if err := json.NewDecoder(r.Body).Decode(&gotBody); err != nil {
+					http.Error(w, "bad body", http.StatusBadRequest)
+					return
+				}
+				w.WriteHeader(tt.status)
+			}))
+			defer srv.Close()
+
+			c := NewAdminClient(srv.URL, "")
+			err := c.RemoveRepos(context.Background(), tt.dids)
+
+			if (err != nil) != tt.wantErr {
+				t.Errorf("RemoveRepos() error = %v, wantErr %v", err, tt.wantErr)
+			}
+
+			if !tt.wantErr {
+				if gotPath != "/repos/remove" {
+					t.Errorf("expected path /repos/remove, got %s", gotPath)
+				}
+				if len(gotBody.DIDs) != len(tt.dids) {
+					t.Errorf("expected %d DIDs, got %d", len(tt.dids), len(gotBody.DIDs))
+				}
+			}
+		})
+	}
+}
+
+// TestAdminClient_Health verifies GET /health and status parsing.
+func TestAdminClient_Health(t *testing.T) {
+	tests := []struct {
+		name       string
+		statusCode int
+		body       string
+		wantErr    bool
+	}{
+		{
+			name:       "healthy",
+			statusCode: http.StatusOK,
+			body:       `{"status":"ok"}`,
+			wantErr:    false,
+		},
+		{
+			name:       "unhealthy status value",
+			statusCode: http.StatusOK,
+			body:       `{"status":"degraded"}`,
+			wantErr:    true,
+		},
+		{
+			name:       "non-200 response",
+			statusCode: http.StatusServiceUnavailable,
+			body:       `{"status":"ok"}`,
+			wantErr:    true,
+		},
+		{
+			name:       "invalid JSON body",
+			statusCode: http.StatusOK,
+			body:       `not-json`,
+			wantErr:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				w.WriteHeader(tt.statusCode)
+				_, _ = w.Write([]byte(tt.body))
+			}))
+			defer srv.Close()
+
+			c := NewAdminClient(srv.URL, "")
+			err := c.Health(context.Background())
+
+			if (err != nil) != tt.wantErr {
+				t.Errorf("Health() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+// TestAdminClient_RepoInfo verifies GET /info/:did.
+func TestAdminClient_RepoInfo(t *testing.T) {
+	tests := []struct {
+		name       string
+		did        string
+		statusCode int
+		body       string
+		wantErr    bool
+		wantDID    string
+	}{
+		{
+			name:       "success",
+			did:        "did:plc:abc",
+			statusCode: http.StatusOK,
+			body:       `{"did":"did:plc:abc","status":"active","rev":"abc123"}`,
+			wantErr:    false,
+			wantDID:    "did:plc:abc",
+		},
+		{
+			name:       "not found",
+			did:        "did:plc:unknown",
+			statusCode: http.StatusNotFound,
+			body:       `{"error":"not found"}`,
+			wantErr:    true,
+		},
+		{
+			name:       "invalid JSON",
+			did:        "did:plc:abc",
+			statusCode: http.StatusOK,
+			body:       `not-json`,
+			wantErr:    true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var gotPath string
+
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				gotPath = r.URL.Path
+				w.WriteHeader(tt.statusCode)
+				_, _ = w.Write([]byte(tt.body))
+			}))
+			defer srv.Close()
+
+			c := NewAdminClient(srv.URL, "")
+			info, err := c.RepoInfo(context.Background(), tt.did)
+
+			if (err != nil) != tt.wantErr {
+				t.Errorf("RepoInfo() error = %v, wantErr %v", err, tt.wantErr)
+			}
+
+			if !tt.wantErr {
+				expectedPath := "/info/" + tt.did
+				if gotPath != expectedPath {
+					t.Errorf("expected path %s, got %s", expectedPath, gotPath)
+				}
+				if info == nil {
+					t.Fatal("expected non-nil RepoInfoResponse")
+				}
+				if info.DID != tt.wantDID {
+					t.Errorf("DID: expected %s, got %s", tt.wantDID, info.DID)
+				}
+			}
+		})
+	}
+}
+
+// TestAdminClient_BasicAuth verifies auth header behavior.
+func TestAdminClient_BasicAuth(t *testing.T) {
+	tests := []struct {
+		name       string
+		password   string
+		wantAuth   bool
+		wantHeader string
+	}{
+		{
+			name:     "no auth when password is empty",
+			password: "",
+			wantAuth: false,
+		},
+		{
+			name:       "basic auth header when password is set",
+			password:   "secret",
+			wantAuth:   true,
+			wantHeader: "Basic " + base64.StdEncoding.EncodeToString([]byte("admin:secret")),
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			var gotAuthHeader string
+
+			srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+				gotAuthHeader = r.Header.Get("Authorization")
+				w.WriteHeader(http.StatusOK)
+				_, _ = w.Write([]byte(`{"status":"ok"}`))
+			}))
+			defer srv.Close()
+
+			c := NewAdminClient(srv.URL, tt.password)
+			_ = c.Health(context.Background())
+
+			if tt.wantAuth {
+				if gotAuthHeader == "" {
+					t.Error("expected Authorization header, got none")
+				}
+				if gotAuthHeader != tt.wantHeader {
+					t.Errorf("Authorization header: expected %q, got %q", tt.wantHeader, gotAuthHeader)
+				}
+			} else {
+				if gotAuthHeader != "" {
+					t.Errorf("expected no Authorization header, got %q", gotAuthHeader)
+				}
+			}
+		})
+	}
+}
+
+// TestAdminClient_ContentType verifies POST requests set Content-Type: application/json.
+func TestAdminClient_ContentType(t *testing.T) {
+	var gotContentType string
+
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotContentType = r.Header.Get("Content-Type")
+		w.WriteHeader(http.StatusOK)
+	}))
+	defer srv.Close()
+
+	c := NewAdminClient(srv.URL, "")
+	_ = c.AddRepos(context.Background(), []string{"did:plc:abc"})
+
+	if !strings.Contains(gotContentType, "application/json") {
+		t.Errorf("expected Content-Type application/json, got %q", gotContentType)
+	}
+}
diff --git a/internal/tap/consumer.go b/internal/tap/consumer.go
new file mode 100644
index 0000000..4ef3d77
--- /dev/null
+++ b/internal/tap/consumer.go
@@ -0,0 +1,320 @@
+package tap
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"sync"
+	"sync/atomic"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+const (
+	// tapChannelPath is the WebSocket endpoint path on the Tap server.
+	tapChannelPath = "/channel"
+
+	// defaultWriteTimeout is the timeout for WebSocket write operations.
+	defaultWriteTimeout = 10 * time.Second
+
+	// defaultReadTimeout is the timeout for WebSocket read operations.
+	defaultReadTimeout = 60 * time.Second
+
+	// minBackoff is the initial reconnection backoff duration.
+	minBackoff = time.Second
+
+	// maxBackoff is the maximum reconnection backoff duration.
+	maxBackoff = 2 * time.Minute
+
+	// maxMessageSize is the maximum WebSocket message size accepted from the Tap server.
+	// AT Protocol records can be up to 1MB; 4MB gives headroom while preventing OOM from
+	// malicious or buggy servers sending arbitrarily large messages.
+	maxMessageSize = 4 * 1024 * 1024 // 4 MB
+)
+
+// ConsumerConfig configures the Tap consumer.
+type ConsumerConfig struct {
+	// TapURL is the WebSocket base URL (e.g., "ws://localhost:2480").
+	TapURL string
+
+	// DisableAcks puts the consumer in fire-and-forget mode (no acks sent).
+	DisableAcks bool
+}
+
+// EventHandler processes Tap events. Return nil to ack, error to nack.
+type EventHandler interface {
+	HandleRecord(ctx context.Context, event *RecordEvent) error
+	HandleIdentity(ctx context.Context, event *IdentityEvent) error
+}
+
+// Stats tracks consumer statistics.
+type Stats struct {
+	EventsReceived int64
+	RecordsCreated int64
+	RecordsUpdated int64
+	RecordsDeleted int64
+	IdentityEvents int64
+	Errors         int64
+}
+
+// Consumer connects to Tap's WebSocket and dispatches events.
+type Consumer struct {
+	config  ConsumerConfig
+	handler EventHandler
+
+	// conn is the active WebSocket connection.
+	conn   *websocket.Conn
+	connMu sync.Mutex
+
+	// stopOnce ensures Stop is idempotent.
+	stopOnce sync.Once
+
+	// done is closed when Stop is called.
+	done chan struct{}
+
+	// stats are updated atomically.
+	eventsReceived int64
+	recordsCreated int64
+	recordsUpdated int64
+	recordsDeleted int64
+	identityEvents int64
+	errors         int64
+}
+
+// NewConsumer creates a new Tap consumer.
+func NewConsumer(config ConsumerConfig, handler EventHandler) *Consumer {
+	return &Consumer{
+		config:  config,
+		handler: handler,
+		done:    make(chan struct{}),
+	}
+}
+
+// Start connects to Tap and begins processing events.
+// Blocks until context is cancelled or Stop is called.
+// Automatically reconnects on connection loss with exponential backoff.
+func (c *Consumer) Start(ctx context.Context) error {
+	backoff := minBackoff
+
+	for {
+		// Check if we should stop before attempting connection.
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-c.done:
+			return nil
+		default:
+		}
+
+		err := c.runOnce(ctx)
+
+		// Reset backoff only after a successful connection (not failed dials).
+		if err == nil {
+			backoff = minBackoff
+		}
+
+		// Check if we should stop after connection ended.
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-c.done:
+			return nil
+		default:
+		}
+
+		// If context was cancelled, this is a graceful shutdown — do not log.
+		if ctx.Err() != nil {
+			return ctx.Err()
+		}
+
+		if err != nil {
+			slog.Warn("Tap connection lost, will reconnect",
+				"error", err,
+				"backoff", backoff,
+			)
+		} else {
+			slog.Warn("Tap connection closed unexpectedly, will reconnect",
+				"backoff", backoff,
+			)
+		}
+
+		// Wait before reconnecting.
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-c.done:
+			return nil
+		case <-time.After(backoff):
+		}
+
+		// Exponential backoff with cap.
+		backoff *= 2
+		if backoff > maxBackoff {
+			backoff = maxBackoff
+		}
+
+		slog.Info("Attempting to reconnect to Tap...")
+	}
+}
+
+// runOnce establishes one WebSocket connection and processes events until it closes.
+func (c *Consumer) runOnce(ctx context.Context) error {
+	channelURL := c.config.TapURL + tapChannelPath
+
+	slog.Info("Connecting to Tap", "url", channelURL)
+
+	conn, _, err := websocket.DefaultDialer.DialContext(ctx, channelURL, nil)
+	if err != nil {
+		return fmt.Errorf("failed to connect to Tap: %w", err)
+	}
+	conn.SetReadLimit(maxMessageSize)
+
+	c.connMu.Lock()
+	c.conn = conn
+	c.connMu.Unlock()
+
+	defer func() {
+		c.connMu.Lock()
+		c.conn = nil
+		c.connMu.Unlock()
+		conn.Close()
+	}()
+
+	slog.Info("Connected to Tap", "url", channelURL)
+
+	for {
+		// Check for stop signal before reading.
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-c.done:
+			return nil
+		default:
+		}
+
+		// Set read deadline.
+		if err := conn.SetReadDeadline(time.Now().Add(defaultReadTimeout)); err != nil {
+			return fmt.Errorf("failed to set read deadline: %w", err)
+		}
+
+		msgType, data, err := conn.ReadMessage()
+		if err != nil {
+			if websocket.IsCloseError(err, websocket.CloseNormalClosure, websocket.CloseGoingAway) {
+				return nil
+			}
+			return fmt.Errorf("read error: %w", err)
+		}
+
+		if msgType != websocket.TextMessage {
+			// Ignore non-text messages (e.g., ping/pong handled by gorilla automatically).
+			continue
+		}
+
+		atomic.AddInt64(&c.eventsReceived, 1)
+
+		event, err := ParseEvent(data)
+		if err != nil {
+			slog.Warn("Failed to parse Tap event", "error", err)
+			atomic.AddInt64(&c.errors, 1)
+			continue
+		}
+
+		if err := c.dispatch(ctx, conn, event); err != nil {
+			slog.Warn("Failed to handle Tap event",
+				"event_id", event.ID,
+				"type", event.Type,
+				"error", err,
+			)
+			atomic.AddInt64(&c.errors, 1)
+			// Do not ack on handler error.
+			continue
+		}
+	}
+}
+
+// dispatch routes an event to the appropriate handler and sends an ack on success.
+func (c *Consumer) dispatch(ctx context.Context, conn *websocket.Conn, event *Event) error {
+	var handlerErr error
+
+	switch {
+	case event.IsRecord():
+		handlerErr = c.handler.HandleRecord(ctx, event.Record)
+		if handlerErr == nil {
+			c.incrementRecordStat(event.Record.Action)
+		}
+
+	case event.IsIdentity():
+		handlerErr = c.handler.HandleIdentity(ctx, event.Identity)
+		if handlerErr == nil {
+			atomic.AddInt64(&c.identityEvents, 1)
+		}
+
+	default:
+		// Unknown event type — log and skip without acking.
+		slog.Warn("Unknown Tap event type", "type", event.Type, "id", event.ID)
+		return nil
+	}
+
+	if handlerErr != nil {
+		return handlerErr
+	}
+
+	// Send ack unless disabled.
+	if !c.config.DisableAcks {
+		ackMsg := fmt.Sprintf("%d", event.ID)
+		if err := c.writeText(conn, ackMsg); err != nil {
+			return fmt.Errorf("failed to send ack for event %d: %w", event.ID, err)
+		}
+	}
+
+	return nil
+}
+
+// writeText sends a text message on the WebSocket connection with a write deadline.
+func (c *Consumer) writeText(conn *websocket.Conn, msg string) error {
+	if err := conn.SetWriteDeadline(time.Now().Add(defaultWriteTimeout)); err != nil {
+		return fmt.Errorf("failed to set write deadline: %w", err)
+	}
+	return conn.WriteMessage(websocket.TextMessage, []byte(msg))
+}
+
+// incrementRecordStat increments the appropriate record stat counter.
+func (c *Consumer) incrementRecordStat(action ActionType) {
+	switch action {
+	case ActionCreate:
+		atomic.AddInt64(&c.recordsCreated, 1)
+	case ActionUpdate:
+		atomic.AddInt64(&c.recordsUpdated, 1)
+	case ActionDelete:
+		atomic.AddInt64(&c.recordsDeleted, 1)
+	}
+}
+
+// Stop gracefully shuts down the consumer.
+func (c *Consumer) Stop() {
+	c.stopOnce.Do(func() {
+		close(c.done)
+
+		c.connMu.Lock()
+		conn := c.conn
+		c.conn = nil
+		c.connMu.Unlock()
+
+		if conn != nil {
+			_ = conn.Close()
+		}
+	})
+}
+
+// Stats returns the current event counts.
+func (c *Consumer) Stats() Stats {
+	return Stats{
+		EventsReceived: atomic.LoadInt64(&c.eventsReceived),
+		RecordsCreated: atomic.LoadInt64(&c.recordsCreated),
+		RecordsUpdated: atomic.LoadInt64(&c.recordsUpdated),
+		RecordsDeleted: atomic.LoadInt64(&c.recordsDeleted),
+		IdentityEvents: atomic.LoadInt64(&c.identityEvents),
+		Errors:         atomic.LoadInt64(&c.errors),
+	}
+}
diff --git a/internal/tap/consumer_test.go b/internal/tap/consumer_test.go
new file mode 100644
index 0000000..6650a57
--- /dev/null
+++ b/internal/tap/consumer_test.go
@@ -0,0 +1,913 @@
+package tap
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+
+	"github.com/gorilla/websocket"
+)
+
+// upgrader is used by the mock WebSocket server.
+var upgrader = websocket.Upgrader{
+	CheckOrigin: func(r *http.Request) bool { return true },
+}
+
+// mockHandler is a test implementation of EventHandler.
+type mockHandler struct {
+	mu             sync.Mutex
+	recordEvents   []*RecordEvent
+	identityEvents []*IdentityEvent
+	recordErr      error
+	identityErr    error
+}
+
+func (m *mockHandler) HandleRecord(_ context.Context, event *RecordEvent) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.recordEvents = append(m.recordEvents, event)
+	return m.recordErr
+}
+
+func (m *mockHandler) HandleIdentity(_ context.Context, event *IdentityEvent) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	m.identityEvents = append(m.identityEvents, event)
+	return m.identityErr
+}
+
+func (m *mockHandler) RecordCount() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return len(m.recordEvents)
+}
+
+func (m *mockHandler) IdentityCount() int {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return len(m.identityEvents)
+}
+
+// newTestServer creates a mock WebSocket server that calls serverFn for each connection.
+// serverFn receives the WebSocket connection and can send messages and read acks.
+func newTestServer(t *testing.T, serverFn func(conn *websocket.Conn)) *httptest.Server {
+	t.Helper()
+	mux := http.NewServeMux()
+	mux.HandleFunc("/channel", func(w http.ResponseWriter, r *http.Request) {
+		conn, err := upgrader.Upgrade(w, r, nil)
+		if err != nil {
+			t.Logf("upgrade error: %v", err)
+			return
+		}
+		defer conn.Close()
+		serverFn(conn)
+	})
+	return httptest.NewServer(mux)
+}
+
+// wsURL converts an http:// test server URL to ws://.
+func wsURL(httpURL string) string {
+	return strings.Replace(httpURL, "http://", "ws://", 1)
+}
+
+// sendEvent sends a Tap event JSON to the WebSocket connection.
+func sendEvent(t *testing.T, conn *websocket.Conn, event Event) {
+	t.Helper()
+	data, err := json.Marshal(event)
+	if err != nil {
+		t.Fatalf("failed to marshal event: %v", err)
+	}
+	if err := conn.WriteMessage(websocket.TextMessage, data); err != nil {
+		t.Logf("write error (may be expected on close): %v", err)
+	}
+}
+
+// readAck reads one text message from the connection and returns it.
+func readAck(t *testing.T, conn *websocket.Conn) string {
+	t.Helper()
+	_ = conn.SetReadDeadline(time.Now().Add(2 * time.Second))
+	msgType, data, err := conn.ReadMessage()
+	if err != nil {
+		t.Fatalf("failed to read ack: %v", err)
+	}
+	if msgType != websocket.TextMessage {
+		t.Fatalf("expected text message for ack, got type %d", msgType)
+	}
+	return string(data)
+}
+
+// TestConsumer_ConnectsToChannel verifies the consumer connects to /channel.
+func TestConsumer_ConnectsToChannel(t *testing.T) {
+	connected := make(chan struct{})
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		close(connected)
+		// Keep connection open briefly then close.
+		time.Sleep(100 * time.Millisecond)
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	select {
+	case <-connected:
+		// Success
+	case <-time.After(2 * time.Second):
+		t.Fatal("consumer did not connect within timeout")
+	}
+
+	consumer.Stop()
+}
+
+// TestConsumer_ReceivesAndAcksRecordEvent verifies record events are dispatched and acked.
+func TestConsumer_ReceivesAndAcksRecordEvent(t *testing.T) {
+	ackReceived := make(chan string, 1)
+
+	recordEvent := Event{
+		ID:   12345,
+		Type: EventTypeRecord,
+		Record: &RecordEvent{
+			Live:       true,
+			Rev:        "abc123",
+			DID:        "did:plc:alice",
+			Collection: "app.bsky.feed.post",
+			RKey:       "rkey1",
+			Action:     ActionCreate,
+			CID:        "bafyreiabc",
+			Record:     json.RawMessage(`{"text":"hello"}`),
+		},
+	}
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		sendEvent(t, conn, recordEvent)
+		ack := readAck(t, conn)
+		ackReceived <- ack
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	select {
+	case ack := <-ackReceived:
+		if ack != "12345" {
+			t.Errorf("expected ack '12345', got %q", ack)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("did not receive ack within timeout")
+	}
+
+	consumer.Stop()
+
+	if handler.RecordCount() != 1 {
+		t.Errorf("expected 1 record event, got %d", handler.RecordCount())
+	}
+}
+
+// TestConsumer_ReceivesAndAcksIdentityEvent verifies identity events are dispatched and acked.
+func TestConsumer_ReceivesAndAcksIdentityEvent(t *testing.T) {
+	ackReceived := make(chan string, 1)
+
+	identityEvent := Event{
+		ID:   12346,
+		Type: EventTypeIdentity,
+		Identity: &IdentityEvent{
+			DID:      "did:plc:alice",
+			Handle:   "alice.bsky.social",
+			IsActive: true,
+			Status:   "active",
+		},
+	}
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		sendEvent(t, conn, identityEvent)
+		ack := readAck(t, conn)
+		ackReceived <- ack
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	select {
+	case ack := <-ackReceived:
+		if ack != "12346" {
+			t.Errorf("expected ack '12346', got %q", ack)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("did not receive ack within timeout")
+	}
+
+	consumer.Stop()
+
+	if handler.IdentityCount() != 1 {
+		t.Errorf("expected 1 identity event, got %d", handler.IdentityCount())
+	}
+}
+
+// TestConsumer_DisableAcks verifies no ack is sent when DisableAcks=true.
+func TestConsumer_DisableAcks(t *testing.T) {
+	eventHandled := make(chan struct{})
+	ackReceived := make(chan struct{})
+
+	recordEvent := Event{
+		ID:   99,
+		Type: EventTypeRecord,
+		Record: &RecordEvent{
+			Live:       true,
+			DID:        "did:plc:bob",
+			Collection: "app.bsky.feed.post",
+			RKey:       "rkey2",
+			Action:     ActionCreate,
+			Record:     json.RawMessage(`{"text":"hello"}`),
+		},
+	}
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		sendEvent(t, conn, recordEvent)
+		// Try to read an ack with a short timeout — should not arrive.
+		_ = conn.SetReadDeadline(time.Now().Add(300 * time.Millisecond))
+		_, _, err := conn.ReadMessage()
+		if err == nil {
+			close(ackReceived)
+		}
+		// Signal that we've processed the event check.
+		close(eventHandled)
+		// Keep connection open so consumer doesn't reconnect.
+		time.Sleep(500 * time.Millisecond)
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{
+		TapURL:      wsURL(srv.URL),
+		DisableAcks: true,
+	}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	select {
+	case <-eventHandled:
+	case <-time.After(2 * time.Second):
+		t.Fatal("server did not finish within timeout")
+	}
+
+	select {
+	case <-ackReceived:
+		t.Error("received unexpected ack when DisableAcks=true")
+	default:
+		// Good — no ack received.
+	}
+
+	consumer.Stop()
+}
+
+// TestConsumer_ReconnectsOnConnectionLoss verifies reconnection with backoff.
+func TestConsumer_ReconnectsOnConnectionLoss(t *testing.T) {
+	var connectionCount int32
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		count := atomic.AddInt32(&connectionCount, 1)
+		if count == 1 {
+			// First connection: close immediately to trigger reconnect.
+			conn.Close()
+			return
+		}
+		// Second connection: stay open briefly.
+		time.Sleep(200 * time.Millisecond)
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	// Use a very short initial backoff for testing by overriding via a custom consumer.
+	// We can't easily override minBackoff, so we just wait long enough for the default 1s backoff.
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	// Wait for at least 2 connections (initial + reconnect after 1s backoff).
+	deadline := time.Now().Add(4 * time.Second)
+	for time.Now().Before(deadline) {
+		if atomic.LoadInt32(&connectionCount) >= 2 {
+			break
+		}
+		time.Sleep(100 * time.Millisecond)
+	}
+
+	consumer.Stop()
+
+	if atomic.LoadInt32(&connectionCount) < 2 {
+		t.Errorf("expected at least 2 connections (reconnect), got %d", atomic.LoadInt32(&connectionCount))
+	}
+}
+
+// TestConsumer_StopGracefully verifies Stop closes the connection cleanly.
+func TestConsumer_StopGracefully(t *testing.T) {
+	serverDone := make(chan struct{})
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		defer close(serverDone)
+		// Read until connection closes.
+		for {
+			_, _, err := conn.ReadMessage()
+			if err != nil {
+				return
+			}
+		}
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	started := make(chan struct{})
+	go func() {
+		close(started)
+		_ = consumer.Start(ctx)
+	}()
+
+	<-started
+	// Give the consumer time to connect.
+	time.Sleep(100 * time.Millisecond)
+
+	consumer.Stop()
+
+	select {
+	case <-serverDone:
+		// Server saw the connection close — graceful shutdown confirmed.
+	case <-time.After(2 * time.Second):
+		t.Fatal("server did not see connection close after Stop()")
+	}
+}
+
+// TestConsumer_Stats verifies Stats() returns correct event counts.
+func TestConsumer_Stats(t *testing.T) {
+	allAcked := make(chan struct{})
+	var ackCount int32
+
+	events := []Event{
+		{
+			ID:   1,
+			Type: EventTypeRecord,
+			Record: &RecordEvent{
+				DID: "did:plc:a", Collection: "app.bsky.feed.post", RKey: "r1",
+				Action: ActionCreate, Record: json.RawMessage(`{"text":"hello"}`),
+			},
+		},
+		{
+			ID:   2,
+			Type: EventTypeRecord,
+			Record: &RecordEvent{
+				DID: "did:plc:a", Collection: "app.bsky.feed.post", RKey: "r1",
+				Action: ActionUpdate, Record: json.RawMessage(`{"text":"updated"}`),
+			},
+		},
+		{
+			ID:   3,
+			Type: EventTypeRecord,
+			Record: &RecordEvent{
+				DID: "did:plc:a", Collection: "app.bsky.feed.post", RKey: "r1",
+				Action: ActionDelete,
+			},
+		},
+		{
+			ID:       4,
+			Type:     EventTypeIdentity,
+			Identity: &IdentityEvent{DID: "did:plc:a", Handle: "alice.bsky.social", IsActive: true, Status: "active"},
+		},
+	}
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		for _, ev := range events {
+			sendEvent(t, conn, ev)
+		}
+		// Read all acks.
+		for i := 0; i < len(events); i++ {
+			_ = conn.SetReadDeadline(time.Now().Add(2 * time.Second))
+			_, _, err := conn.ReadMessage()
+			if err != nil {
+				return
+			}
+			if atomic.AddInt32(&ackCount, 1) == int32(len(events)) {
+				close(allAcked)
+			}
+		}
+		// Keep connection open.
+		time.Sleep(500 * time.Millisecond)
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	select {
+	case <-allAcked:
+	case <-time.After(4 * time.Second):
+		t.Fatal("did not receive all acks within timeout")
+	}
+
+	consumer.Stop()
+
+	stats := consumer.Stats()
+	if stats.EventsReceived != 4 {
+		t.Errorf("EventsReceived: want 4, got %d", stats.EventsReceived)
+	}
+	if stats.RecordsCreated != 1 {
+		t.Errorf("RecordsCreated: want 1, got %d", stats.RecordsCreated)
+	}
+	if stats.RecordsUpdated != 1 {
+		t.Errorf("RecordsUpdated: want 1, got %d", stats.RecordsUpdated)
+	}
+	if stats.RecordsDeleted != 1 {
+		t.Errorf("RecordsDeleted: want 1, got %d", stats.RecordsDeleted)
+	}
+	if stats.IdentityEvents != 1 {
+		t.Errorf("IdentityEvents: want 1, got %d", stats.IdentityEvents)
+	}
+	if stats.Errors != 0 {
+		t.Errorf("Errors: want 0, got %d", stats.Errors)
+	}
+}
+
+// TestConsumer_StopDuringDispatch verifies that calling Stop() concurrently with
+// active event dispatching does not cause a data race. gorilla/websocket does not
+// allow concurrent writers, so Stop() must not call WriteMessage while dispatch()
+// may be sending acks.
+func TestConsumer_StopDuringDispatch(t *testing.T) {
+	const numEvents = 200
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		// Send many events rapidly to keep dispatch() busy writing acks.
+		for i := 0; i < numEvents; i++ {
+			ev := Event{
+				ID:   int64(i + 1),
+				Type: EventTypeRecord,
+				Record: &RecordEvent{
+					DID:        "did:plc:race",
+					Collection: "app.bsky.feed.post",
+					RKey:       fmt.Sprintf("rkey%d", i),
+					Action:     ActionCreate,
+					Record:     json.RawMessage(`{"text":"hello"}`),
+				},
+			}
+			data, err := json.Marshal(ev)
+			if err != nil {
+				return
+			}
+			if err := conn.WriteMessage(websocket.TextMessage, data); err != nil {
+				// Connection may have been closed by Stop() — that is expected.
+				return
+			}
+		}
+		// Drain any acks that arrive before the connection closes.
+		for {
+			_ = conn.SetReadDeadline(time.Now().Add(500 * time.Millisecond))
+			_, _, err := conn.ReadMessage()
+			if err != nil {
+				return
+			}
+		}
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	// Let the consumer connect and start receiving events, then stop it
+	// concurrently while dispatch() is actively writing acks.
+	time.Sleep(10 * time.Millisecond)
+	consumer.Stop()
+}
+
+// TestConsumer_BackoffResetsAfterSuccess verifies that after a successful connection
+// the backoff is reset to minBackoff, so subsequent reconnections are fast.
+func TestConsumer_BackoffResetsAfterSuccess(t *testing.T) {
+	var connectionCount int32
+	// secondConnected is closed when the second connection is established.
+	secondConnected := make(chan struct{})
+	// thirdConnected is closed when the third connection is established.
+	thirdConnected := make(chan struct{})
+
+	recordEvent := Event{
+		ID:   1,
+		Type: EventTypeRecord,
+		Record: &RecordEvent{
+			DID:        "did:plc:backoff",
+			Collection: "app.bsky.feed.post",
+			RKey:       "rkey1",
+			Action:     ActionCreate,
+			Record:     json.RawMessage(`{"text":"hello"}`),
+		},
+	}
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		count := atomic.AddInt32(&connectionCount, 1)
+		switch count {
+		case 1:
+			// First connection: close immediately to trigger backoff escalation.
+			conn.Close()
+		case 2:
+			// Second connection: signal connected, send one event, then close cleanly.
+			close(secondConnected)
+			sendEvent(t, conn, recordEvent)
+			// Read the ack so dispatch completes successfully.
+			_ = conn.SetReadDeadline(time.Now().Add(2 * time.Second))
+			conn.ReadMessage() //nolint:errcheck
+			// Close with a normal closure so runOnce returns nil (success).
+			conn.WriteMessage(websocket.CloseMessage, //nolint:errcheck
+				websocket.FormatCloseMessage(websocket.CloseNormalClosure, ""))
+		case 3:
+			// Third connection: signal that we reconnected quickly.
+			close(thirdConnected)
+			// Keep open briefly.
+			time.Sleep(200 * time.Millisecond)
+		}
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	// Wait for the second connection (after the 1s backoff from the first failure).
+	select {
+	case <-secondConnected:
+	case <-time.After(5 * time.Second):
+		t.Fatal("second connection did not arrive within timeout")
+	}
+
+	// After the second connection closes cleanly, backoff should reset to minBackoff (1s).
+	// The third connection should arrive within ~1.5s, not 2s+ (which would indicate
+	// the backoff was not reset and stayed at 2s from the first failure).
+	start := time.Now()
+	select {
+	case <-thirdConnected:
+		elapsed := time.Since(start)
+		// Should reconnect within 1.5s (minBackoff=1s + some slack).
+		// If backoff was NOT reset it would wait 2s (doubled from 1s after first failure).
+		if elapsed > 1500*time.Millisecond {
+			t.Errorf("third connection took %v; expected <1.5s (backoff should have reset to minBackoff)", elapsed)
+		}
+	case <-time.After(4 * time.Second):
+		t.Fatal("third connection did not arrive within timeout")
+	}
+
+	consumer.Stop()
+}
+
+// TestConsumer_LargeMessageRejected verifies that a message exceeding maxMessageSize
+// causes a read error and triggers reconnection rather than OOM.
+func TestConsumer_LargeMessageRejected(t *testing.T) {
+	var connectionCount int32
+	secondConnected := make(chan struct{})
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		count := atomic.AddInt32(&connectionCount, 1)
+		switch count {
+		case 1:
+			// First connection: send a message larger than 4MB.
+			oversized := make([]byte, maxMessageSize+1)
+			for i := range oversized {
+				oversized[i] = 'x'
+			}
+			// The write may succeed on the server side; the client will reject it on read.
+			_ = conn.WriteMessage(websocket.TextMessage, oversized)
+			// Wait briefly for the client to close the connection.
+			_ = conn.SetReadDeadline(time.Now().Add(2 * time.Second))
+			conn.ReadMessage() //nolint:errcheck
+		case 2:
+			// Second connection: signal that the consumer reconnected successfully.
+			close(secondConnected)
+			// Keep open briefly.
+			time.Sleep(200 * time.Millisecond)
+		}
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	// The consumer should reject the oversized message and reconnect.
+	select {
+	case <-secondConnected:
+		// Consumer reconnected after rejecting the large message — no OOM, no crash.
+	case <-time.After(8 * time.Second):
+		t.Fatal("consumer did not reconnect after receiving oversized message")
+	}
+
+	consumer.Stop()
+
+	if atomic.LoadInt32(&connectionCount) < 2 {
+		t.Errorf("expected at least 2 connections, got %d", atomic.LoadInt32(&connectionCount))
+	}
+}
+
+// capturingHandler is a slog.Handler that records all log records.
+type capturingHandler struct {
+	mu      sync.Mutex
+	records []slog.Record
+}
+
+func (h *capturingHandler) Enabled(_ context.Context, _ slog.Level) bool { return true }
+
+func (h *capturingHandler) Handle(_ context.Context, r slog.Record) error {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	h.records = append(h.records, r)
+	return nil
+}
+
+func (h *capturingHandler) WithAttrs(attrs []slog.Attr) slog.Handler { return h }
+func (h *capturingHandler) WithGroup(name string) slog.Handler       { return h }
+
+func (h *capturingHandler) ErrorRecords() []slog.Record {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	var errs []slog.Record
+	for _, r := range h.records {
+		if r.Level >= slog.LevelError {
+			errs = append(errs, r)
+		}
+	}
+	return errs
+}
+
+// WarnRecordsContaining returns all Warn-level records whose message contains substr.
+func (h *capturingHandler) WarnRecordsContaining(substr string) []slog.Record {
+	h.mu.Lock()
+	defer h.mu.Unlock()
+	var matches []slog.Record
+	for _, r := range h.records {
+		if r.Level == slog.LevelWarn && strings.Contains(r.Message, substr) {
+			matches = append(matches, r)
+		}
+	}
+	return matches
+}
+
+// TestConsumer_ShutdownNoSpuriousLog verifies that cancelling the context during
+// shutdown does not produce any Error-level log messages.
+func TestConsumer_ShutdownNoSpuriousLog(t *testing.T) {
+	connected := make(chan struct{})
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		close(connected)
+		// Keep connection open until the client disconnects.
+		for {
+			_ = conn.SetReadDeadline(time.Now().Add(5 * time.Second))
+			_, _, err := conn.ReadMessage()
+			if err != nil {
+				return
+			}
+		}
+	})
+	defer srv.Close()
+
+	// Install a capturing slog handler for the duration of this test.
+	capturing := &capturingHandler{}
+	origLogger := slog.Default()
+	slog.SetDefault(slog.New(capturing))
+	defer slog.SetDefault(origLogger)
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithCancel(context.Background())
+
+	done := make(chan error, 1)
+	go func() {
+		done <- consumer.Start(ctx)
+	}()
+
+	// Wait for the consumer to connect before cancelling.
+	select {
+	case <-connected:
+	case <-time.After(2 * time.Second):
+		t.Fatal("consumer did not connect within timeout")
+	}
+
+	// Cancel the context to trigger graceful shutdown.
+	cancel()
+
+	select {
+	case err := <-done:
+		if err != nil && !errors.Is(err, context.Canceled) {
+			t.Errorf("Start() returned unexpected error: %v", err)
+		}
+	case <-time.After(3 * time.Second):
+		t.Fatal("consumer did not shut down within timeout")
+	}
+
+	// Verify no Error-level log messages were emitted during shutdown.
+	if errRecords := capturing.ErrorRecords(); len(errRecords) > 0 {
+		for _, r := range errRecords {
+			t.Errorf("unexpected Error-level log during shutdown: %s", r.Message)
+		}
+	}
+
+	// Verify no Warn-level "closed unexpectedly" messages were emitted during shutdown.
+	// These would indicate the else branch fired without checking ctx.Err() first.
+	if warnRecords := capturing.WarnRecordsContaining("unexpectedly"); len(warnRecords) > 0 {
+		for _, r := range warnRecords {
+			t.Errorf("unexpected Warn-level 'unexpectedly' log during shutdown: %s", r.Message)
+		}
+	}
+}
+
+// TestConsumer_BackoffEscalatesOnPersistentFailure verifies that when every connection
+// attempt fails (e.g., server unreachable), the backoff escalates rather than resetting
+// to minBackoff on each failure.
+func TestConsumer_BackoffEscalatesOnPersistentFailure(t *testing.T) {
+	// Port 1 is reserved and will refuse connections immediately on all platforms.
+	unreachableURL := "ws://127.0.0.1:1"
+
+	handler := &mockHandler{}
+	consumer := NewConsumer(ConsumerConfig{TapURL: unreachableURL}, handler)
+
+	// With minBackoff=1s and escalating backoff, in 4s we expect:
+	//   attempt 1 at t=0, wait 1s
+	//   attempt 2 at t=1s, wait 2s
+	//   attempt 3 at t=3s, wait 4s (capped later)
+	// So at most 3 attempts in 4s. If backoff were resetting to 1s every time,
+	// we would see ~4 attempts in 4s.
+	ctx, cancel := context.WithTimeout(context.Background(), 4*time.Second)
+	defer cancel()
+
+	var attemptCount int32
+	origDialer := websocket.DefaultDialer
+	_ = origDialer // ensure import used
+
+	// We count attempts by wrapping: use a real consumer but count via a channel.
+	// Since we can't easily intercept the dialer, we rely on the timing guarantee:
+	// if backoff escalates correctly, fewer than 4 attempts occur in 4s.
+	// We track this by counting how many times runOnce is called indirectly via
+	// the "Connecting to Tap" log message using a capturing handler.
+	capturing := &capturingHandler{}
+	origLogger := slog.Default()
+	slog.SetDefault(slog.New(capturing))
+	defer slog.SetDefault(origLogger)
+
+	done := make(chan error, 1)
+	go func() {
+		done <- consumer.Start(ctx)
+	}()
+
+	select {
+	case <-done:
+	case <-time.After(5 * time.Second):
+		t.Fatal("consumer did not stop within timeout")
+	}
+
+	// Count "Connecting to Tap" log messages to determine number of attempts.
+	capturing.mu.Lock()
+	for _, r := range capturing.records {
+		if r.Message == "Connecting to Tap" {
+			atomic.AddInt32(&attemptCount, 1)
+		}
+	}
+	capturing.mu.Unlock()
+
+	attempts := atomic.LoadInt32(&attemptCount)
+	// With proper escalating backoff: attempt 1 at t=0, wait 1s; attempt 2 at t=1s,
+	// wait 2s; attempt 3 at t=3s — context expires before attempt 4.
+	// So we expect at most 3 attempts. If backoff reset every time (bug), we'd see ~4.
+	if attempts >= 4 {
+		t.Errorf("expected fewer than 4 connection attempts (backoff should escalate), got %d", attempts)
+	}
+	if attempts == 0 {
+		t.Error("expected at least 1 connection attempt, got 0")
+	}
+}
+
+// TestConsumer_HandlerErrorDoesNotAck verifies that handler errors suppress acks.
+func TestConsumer_HandlerErrorDoesNotAck(t *testing.T) {
+	ackReceived := make(chan struct{})
+	eventSent := make(chan struct{})
+
+	recordEvent := Event{
+		ID:   777,
+		Type: EventTypeRecord,
+		Record: &RecordEvent{
+			DID: "did:plc:err", Collection: "app.bsky.feed.post", RKey: "r1",
+			Action: ActionCreate, Record: json.RawMessage(`{"text":"hello"}`),
+		},
+	}
+
+	srv := newTestServer(t, func(conn *websocket.Conn) {
+		sendEvent(t, conn, recordEvent)
+		close(eventSent)
+		// Try to read ack with short timeout.
+		_ = conn.SetReadDeadline(time.Now().Add(400 * time.Millisecond))
+		_, _, err := conn.ReadMessage()
+		if err == nil {
+			close(ackReceived)
+		}
+		// Keep connection open.
+		time.Sleep(500 * time.Millisecond)
+	})
+	defer srv.Close()
+
+	handler := &mockHandler{recordErr: fmt.Errorf("handler error")}
+	consumer := NewConsumer(ConsumerConfig{TapURL: wsURL(srv.URL)}, handler)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+
+	go func() {
+		_ = consumer.Start(ctx)
+	}()
+
+	select {
+	case <-eventSent:
+	case <-time.After(2 * time.Second):
+		t.Fatal("event was not sent within timeout")
+	}
+
+	// Wait a bit to ensure no ack arrives.
+	time.Sleep(500 * time.Millisecond)
+
+	select {
+	case <-ackReceived:
+		t.Error("received unexpected ack after handler error")
+	default:
+		// Good — no ack.
+	}
+
+	consumer.Stop()
+
+	stats := consumer.Stats()
+	if stats.Errors != 1 {
+		t.Errorf("Errors: want 1, got %d", stats.Errors)
+	}
+}
diff --git a/internal/tap/event.go b/internal/tap/event.go
new file mode 100644
index 0000000..91b6808
--- /dev/null
+++ b/internal/tap/event.go
@@ -0,0 +1,111 @@
+// Package tap provides a client for Bluesky's Tap sync utility.
+package tap
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// EventType is the top-level event type from Tap.
+type EventType string
+
+const (
+	EventTypeRecord   EventType = "record"
+	EventTypeIdentity EventType = "identity"
+)
+
+// ActionType is the record action type.
+type ActionType string
+
+const (
+	ActionCreate ActionType = "create"
+	ActionUpdate ActionType = "update"
+	ActionDelete ActionType = "delete"
+)
+
+// Event is the top-level Tap event envelope.
+type Event struct {
+	ID       int64          `json:"id"`
+	Type     EventType      `json:"type"`
+	Record   *RecordEvent   `json:"record,omitempty"`
+	Identity *IdentityEvent `json:"identity,omitempty"`
+}
+
+// RecordEvent is a record change event from Tap.
+type RecordEvent struct {
+	Live       bool            `json:"live"`
+	Rev        string          `json:"rev"`
+	DID        string          `json:"did"`
+	Collection string          `json:"collection"`
+	RKey       string          `json:"rkey"`
+	Action     ActionType      `json:"action"`
+	CID        string          `json:"cid,omitempty"`
+	Record     json.RawMessage `json:"record,omitempty"` // Only for create/update
+}
+
+// URI returns the AT-URI for this record event.
+func (r *RecordEvent) URI() string {
+	return fmt.Sprintf("at://%s/%s/%s", r.DID, r.Collection, r.RKey)
+}
+
+// IdentityEvent is an identity change event from Tap.
+type IdentityEvent struct {
+	DID      string `json:"did"`
+	Handle   string `json:"handle"`
+	IsActive bool   `json:"isActive"`
+	Status   string `json:"status"` // active, takendown, suspended, deactivated, deleted
+}
+
+// ParseEvent parses a Tap event from JSON bytes.
+func ParseEvent(data []byte) (*Event, error) {
+	var event Event
+	if err := json.Unmarshal(data, &event); err != nil {
+		return nil, fmt.Errorf("failed to parse tap event: %w", err)
+	}
+	if event.Type == "" {
+		return nil, fmt.Errorf("tap event missing type field")
+	}
+	// Validate record events.
+	if event.Type == EventTypeRecord {
+		if event.Record == nil {
+			return nil, fmt.Errorf("tap record event missing record payload")
+		}
+		if event.Record.DID == "" {
+			return nil, fmt.Errorf("tap record event missing did field")
+		}
+		if event.Record.Collection == "" {
+			return nil, fmt.Errorf("tap record event missing collection field")
+		}
+		if event.Record.RKey == "" {
+			return nil, fmt.Errorf("tap record event missing rkey field")
+		}
+		if event.Record.Action == "" {
+			return nil, fmt.Errorf("tap record event missing action field")
+		}
+		if event.Record.Action == ActionCreate || event.Record.Action == ActionUpdate {
+			if len(event.Record.Record) == 0 {
+				return nil, fmt.Errorf("tap record event action %q missing record body", event.Record.Action)
+			}
+		}
+	}
+	// Validate identity events.
+	if event.Type == EventTypeIdentity {
+		if event.Identity == nil {
+			return nil, fmt.Errorf("tap identity event missing identity payload")
+		}
+		if event.Identity.DID == "" {
+			return nil, fmt.Errorf("tap identity event missing did field")
+		}
+	}
+	return &event, nil
+}
+
+// IsRecord returns true if this is a record event.
+func (e *Event) IsRecord() bool {
+	return e.Type == EventTypeRecord && e.Record != nil
+}
+
+// IsIdentity returns true if this is an identity event.
+func (e *Event) IsIdentity() bool {
+	return e.Type == EventTypeIdentity && e.Identity != nil
+}
diff --git a/internal/tap/event_test.go b/internal/tap/event_test.go
new file mode 100644
index 0000000..1e50a50
--- /dev/null
+++ b/internal/tap/event_test.go
@@ -0,0 +1,492 @@
+package tap
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestParseEvent_RecordCreate(t *testing.T) {
+	data := []byte(`{
+		"id": 12345,
+		"type": "record",
+		"record": {
+			"live": true,
+			"rev": "3kgn2v3",
+			"did": "did:plc:abc",
+			"collection": "app.bsky.feed.post",
+			"rkey": "abc",
+			"action": "create",
+			"cid": "bafyrei123",
+			"record": {"text": "hello"}
+		}
+	}`)
+
+	event, err := ParseEvent(data)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if event.ID != 12345 {
+		t.Errorf("expected ID 12345, got %d", event.ID)
+	}
+	if event.Type != EventTypeRecord {
+		t.Errorf("expected type %q, got %q", EventTypeRecord, event.Type)
+	}
+	if event.Record == nil {
+		t.Fatal("expected record to be non-nil")
+	}
+	if !event.Record.Live {
+		t.Error("expected live to be true")
+	}
+	if event.Record.Rev != "3kgn2v3" {
+		t.Errorf("expected rev %q, got %q", "3kgn2v3", event.Record.Rev)
+	}
+	if event.Record.DID != "did:plc:abc" {
+		t.Errorf("expected DID %q, got %q", "did:plc:abc", event.Record.DID)
+	}
+	if event.Record.Collection != "app.bsky.feed.post" {
+		t.Errorf("expected collection %q, got %q", "app.bsky.feed.post", event.Record.Collection)
+	}
+	if event.Record.RKey != "abc" {
+		t.Errorf("expected rkey %q, got %q", "abc", event.Record.RKey)
+	}
+	if event.Record.Action != ActionCreate {
+		t.Errorf("expected action %q, got %q", ActionCreate, event.Record.Action)
+	}
+	if event.Record.CID != "bafyrei123" {
+		t.Errorf("expected cid %q, got %q", "bafyrei123", event.Record.CID)
+	}
+	if string(event.Record.Record) != `{"text": "hello"}` {
+		t.Errorf("unexpected record body: %s", event.Record.Record)
+	}
+}
+
+func TestParseEvent_RecordDelete(t *testing.T) {
+	data := []byte(`{
+		"id": 12346,
+		"type": "record",
+		"record": {
+			"live": false,
+			"rev": "3kgn2v4",
+			"did": "did:plc:abc",
+			"collection": "app.bsky.feed.post",
+			"rkey": "abc",
+			"action": "delete"
+		}
+	}`)
+
+	event, err := ParseEvent(data)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if event.Type != EventTypeRecord {
+		t.Errorf("expected type %q, got %q", EventTypeRecord, event.Type)
+	}
+	if event.Record == nil {
+		t.Fatal("expected record to be non-nil")
+	}
+	if event.Record.Action != ActionDelete {
+		t.Errorf("expected action %q, got %q", ActionDelete, event.Record.Action)
+	}
+	if event.Record.CID != "" {
+		t.Errorf("expected empty cid for delete, got %q", event.Record.CID)
+	}
+	if event.Record.Record != nil {
+		t.Errorf("expected nil record body for delete, got %s", event.Record.Record)
+	}
+}
+
+func TestParseEvent_Identity(t *testing.T) {
+	data := []byte(`{
+		"id": 12347,
+		"type": "identity",
+		"identity": {
+			"did": "did:plc:abc",
+			"handle": "alice.bsky.social",
+			"isActive": true,
+			"status": "active"
+		}
+	}`)
+
+	event, err := ParseEvent(data)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if event.ID != 12347 {
+		t.Errorf("expected ID 12347, got %d", event.ID)
+	}
+	if event.Type != EventTypeIdentity {
+		t.Errorf("expected type %q, got %q", EventTypeIdentity, event.Type)
+	}
+	if event.Identity == nil {
+		t.Fatal("expected identity to be non-nil")
+	}
+	if event.Identity.DID != "did:plc:abc" {
+		t.Errorf("expected DID %q, got %q", "did:plc:abc", event.Identity.DID)
+	}
+	if event.Identity.Handle != "alice.bsky.social" {
+		t.Errorf("expected handle %q, got %q", "alice.bsky.social", event.Identity.Handle)
+	}
+	if !event.Identity.IsActive {
+		t.Error("expected isActive to be true")
+	}
+	if event.Identity.Status != "active" {
+		t.Errorf("expected status %q, got %q", "active", event.Identity.Status)
+	}
+}
+
+func TestParseEvent_MissingType(t *testing.T) {
+	data := []byte(`{"id": 1, "record": {}}`)
+
+	_, err := ParseEvent(data)
+	if err == nil {
+		t.Fatal("expected error for missing type field, got nil")
+	}
+}
+
+func TestParseEvent_InvalidJSON(t *testing.T) {
+	data := []byte(`{invalid json`)
+
+	_, err := ParseEvent(data)
+	if err == nil {
+		t.Fatal("expected error for invalid JSON, got nil")
+	}
+}
+
+func TestRecordEvent_URI(t *testing.T) {
+	tests := []struct {
+		name       string
+		did        string
+		collection string
+		rkey       string
+		wantURI    string
+	}{
+		{
+			name:       "standard AT-URI",
+			did:        "did:plc:abc",
+			collection: "app.bsky.feed.post",
+			rkey:       "abc",
+			wantURI:    "at://did:plc:abc/app.bsky.feed.post/abc",
+		},
+		{
+			name:       "different collection",
+			did:        "did:plc:xyz",
+			collection: "app.bsky.actor.profile",
+			rkey:       "self",
+			wantURI:    "at://did:plc:xyz/app.bsky.actor.profile/self",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			r := &RecordEvent{
+				DID:        tt.did,
+				Collection: tt.collection,
+				RKey:       tt.rkey,
+			}
+			got := r.URI()
+			if got != tt.wantURI {
+				t.Errorf("URI() = %q, want %q", got, tt.wantURI)
+			}
+		})
+	}
+}
+
+func TestEvent_IsRecord(t *testing.T) {
+	tests := []struct {
+		name  string
+		event Event
+		want  bool
+	}{
+		{
+			name: "record event with record",
+			event: Event{
+				Type:   EventTypeRecord,
+				Record: &RecordEvent{},
+			},
+			want: true,
+		},
+		{
+			name: "record type but nil record",
+			event: Event{
+				Type:   EventTypeRecord,
+				Record: nil,
+			},
+			want: false,
+		},
+		{
+			name: "identity event",
+			event: Event{
+				Type:     EventTypeIdentity,
+				Identity: &IdentityEvent{},
+			},
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.event.IsRecord(); got != tt.want {
+				t.Errorf("IsRecord() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestEvent_IsIdentity(t *testing.T) {
+	tests := []struct {
+		name  string
+		event Event
+		want  bool
+	}{
+		{
+			name: "identity event with identity",
+			event: Event{
+				Type:     EventTypeIdentity,
+				Identity: &IdentityEvent{},
+			},
+			want: true,
+		},
+		{
+			name: "identity type but nil identity",
+			event: Event{
+				Type:     EventTypeIdentity,
+				Identity: nil,
+			},
+			want: false,
+		},
+		{
+			name: "record event",
+			event: Event{
+				Type:   EventTypeRecord,
+				Record: &RecordEvent{},
+			},
+			want: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := tt.event.IsIdentity(); got != tt.want {
+				t.Errorf("IsIdentity() = %v, want %v", got, tt.want)
+			}
+		})
+	}
+}
+
+func TestParseEvent_AcceptanceCriteria_RecordCreate(t *testing.T) {
+	// Exact format from acceptance criteria
+	data := []byte(`{"id": 12345, "type": "record", "record": {"live": true, "rev": "abc123", "did": "did:plc:abc", "collection": "app.bsky.feed.post", "rkey": "abc", "action": "create", "cid": "bafyrei...", "record": {"text": "hello"}}}`)
+
+	event, err := ParseEvent(data)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if event.ID != 12345 {
+		t.Errorf("expected ID 12345, got %d", event.ID)
+	}
+	if event.Type != EventTypeRecord {
+		t.Errorf("expected type %q, got %q", EventTypeRecord, event.Type)
+	}
+	if event.Record == nil {
+		t.Fatal("expected record to be non-nil")
+	}
+	if event.Record.DID != "did:plc:abc" {
+		t.Errorf("expected DID %q, got %q", "did:plc:abc", event.Record.DID)
+	}
+	if event.Record.Collection != "app.bsky.feed.post" {
+		t.Errorf("expected collection %q, got %q", "app.bsky.feed.post", event.Record.Collection)
+	}
+	if event.Record.Action != ActionCreate {
+		t.Errorf("expected action %q, got %q", ActionCreate, event.Record.Action)
+	}
+	// Verify record body is valid JSON
+	var body map[string]interface{}
+	if err := json.Unmarshal(event.Record.Record, &body); err != nil {
+		t.Errorf("record body is not valid JSON: %v", err)
+	}
+}
+
+func TestParseEvent_AcceptanceCriteria_Identity(t *testing.T) {
+	// Exact format from acceptance criteria
+	data := []byte(`{"id": 12346, "type": "identity", "identity": {"did": "did:plc:abc", "handle": "alice.bsky.social", "isActive": true, "status": "active"}}`)
+
+	event, err := ParseEvent(data)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if event.ID != 12346 {
+		t.Errorf("expected ID 12346, got %d", event.ID)
+	}
+	if event.Type != EventTypeIdentity {
+		t.Errorf("expected type %q, got %q", EventTypeIdentity, event.Type)
+	}
+	if event.Identity == nil {
+		t.Fatal("expected identity to be non-nil")
+	}
+	if event.Identity.DID != "did:plc:abc" {
+		t.Errorf("expected DID %q, got %q", "did:plc:abc", event.Identity.DID)
+	}
+	if event.Identity.Handle != "alice.bsky.social" {
+		t.Errorf("expected handle %q, got %q", "alice.bsky.social", event.Identity.Handle)
+	}
+	if !event.Identity.IsActive {
+		t.Error("expected isActive to be true")
+	}
+	if event.Identity.Status != "active" {
+		t.Errorf("expected status %q, got %q", "active", event.Identity.Status)
+	}
+}
+
+func TestRecordEvent_URI_AcceptanceCriteria(t *testing.T) {
+	r := &RecordEvent{
+		DID:        "did:plc:abc",
+		Collection: "app.bsky.feed.post",
+		RKey:       "abc",
+	}
+	got := r.URI()
+	want := "at://did:plc:abc/app.bsky.feed.post/abc"
+	if got != want {
+		t.Errorf("URI() = %q, want %q", got, want)
+	}
+}
+
+func TestParseEvent_RecordValidation(t *testing.T) {
+	validRecord := `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","rkey":"abc","action":"create","record":{"text":"hello"}}}`
+
+	tests := []struct {
+		name    string
+		data    string
+		wantErr bool
+	}{
+		{
+			name:    "valid record event",
+			data:    validRecord,
+			wantErr: false,
+		},
+		{
+			name:    "record with empty DID",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"","collection":"app.bsky.feed.post","rkey":"abc","action":"create","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+		{
+			name:    "record with missing DID",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","collection":"app.bsky.feed.post","rkey":"abc","action":"create","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+		{
+			name:    "record with empty Collection",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"","rkey":"abc","action":"create","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+		{
+			name:    "record with missing Collection",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","rkey":"abc","action":"create","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+		{
+			name:    "record with empty RKey",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","rkey":"","action":"create","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+		{
+			name:    "record with missing RKey",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","action":"create","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+		{
+			name:    "record with empty Action",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","rkey":"abc","action":"","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+		{
+			name:    "record with missing Action",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","rkey":"abc","record":{"text":"hello"}}}`,
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := ParseEvent([]byte(tt.data))
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ParseEvent() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestParseEvent_IdentityValidation(t *testing.T) {
+	tests := []struct {
+		name    string
+		data    string
+		wantErr bool
+	}{
+		{
+			name:    "valid identity event",
+			data:    `{"id":1,"type":"identity","identity":{"did":"did:plc:abc","handle":"alice.bsky.social","isActive":true,"status":"active"}}`,
+			wantErr: false,
+		},
+		{
+			name:    "identity with empty DID",
+			data:    `{"id":1,"type":"identity","identity":{"did":"","handle":"alice.bsky.social","isActive":true,"status":"active"}}`,
+			wantErr: true,
+		},
+		{
+			name:    "identity with missing DID",
+			data:    `{"id":1,"type":"identity","identity":{"handle":"alice.bsky.social","isActive":true,"status":"active"}}`,
+			wantErr: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := ParseEvent([]byte(tt.data))
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ParseEvent() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
+
+func TestParseEvent_NilPayloadRejection(t *testing.T) {
+	tests := []struct {
+		name    string
+		data    string
+		wantErr bool
+	}{
+		{
+			name:    "type=record with nil Record payload",
+			data:    `{"id":1,"type":"record"}`,
+			wantErr: true,
+		},
+		{
+			name:    "type=identity with nil Identity payload",
+			data:    `{"id":1,"type":"identity"}`,
+			wantErr: true,
+		},
+		{
+			name:    "type=record action=create with empty record body",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","rkey":"abc","action":"create"}}`,
+			wantErr: true,
+		},
+		{
+			name:    "type=record action=update with empty record body",
+			data:    `{"id":1,"type":"record","record":{"live":true,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","rkey":"abc","action":"update"}}`,
+			wantErr: true,
+		},
+		{
+			name:    "type=record action=delete with empty record body",
+			data:    `{"id":1,"type":"record","record":{"live":false,"rev":"r1","did":"did:plc:abc","collection":"app.bsky.feed.post","rkey":"abc","action":"delete"}}`,
+			wantErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := ParseEvent([]byte(tt.data))
+			if (err != nil) != tt.wantErr {
+				t.Errorf("ParseEvent() error = %v, wantErr %v", err, tt.wantErr)
+			}
+		})
+	}
+}
diff --git a/internal/tap/handler.go b/internal/tap/handler.go
new file mode 100644
index 0000000..7da7b62
--- /dev/null
+++ b/internal/tap/handler.go
@@ -0,0 +1,101 @@
+package tap
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+	"time"
+
+	"github.com/GainForest/hypergoat/internal/database/repositories"
+	"github.com/GainForest/hypergoat/internal/graphql/subscription"
+)
+
+// IndexHandler implements EventHandler and stores events in the database.
+type IndexHandler struct {
+	records  *repositories.RecordsRepository
+	actors   *repositories.ActorsRepository
+	activity *repositories.JetstreamActivityRepository // reuse existing activity repo
+	pubsub   *subscription.PubSub
+}
+
+// NewIndexHandler creates a new IndexHandler.
+func NewIndexHandler(
+	records *repositories.RecordsRepository,
+	actors *repositories.ActorsRepository,
+	activity *repositories.JetstreamActivityRepository,
+	pubsub *subscription.PubSub,
+) *IndexHandler {
+	return &IndexHandler{
+		records:  records,
+		actors:   actors,
+		activity: activity,
+		pubsub:   pubsub,
+	}
+}
+
+// HandleRecord processes a record event by storing or deleting the record and
+// publishing to GraphQL subscriptions.
+func (h *IndexHandler) HandleRecord(ctx context.Context, event *RecordEvent) error {
+	uri := event.URI()
+
+	switch event.Action {
+	case ActionCreate, ActionUpdate:
+		// Ensure actor exists (empty handle; identity events update it)
+		if err := h.actors.Upsert(ctx, event.DID, ""); err != nil {
+			slog.Debug("Failed to upsert actor", "did", event.DID, "error", err)
+		}
+
+		// Store record
+		_, err := h.records.Insert(ctx, uri, event.CID, event.DID, event.Collection, string(event.Record))
+		if err != nil {
+			return fmt.Errorf("failed to insert record: %w", err)
+		}
+
+		// Log activity (if activity repo available)
+		if h.activity != nil {
+			activityID, err := h.activity.LogActivity(ctx, time.Now(), string(event.Action), event.Collection, event.DID, event.RKey, string(event.Record))
+			if err != nil {
+				slog.Debug("Failed to log activity", "error", err)
+			} else {
+				if err := h.activity.UpdateStatus(ctx, activityID, "completed", nil); err != nil {
+					slog.Debug("Failed to update activity status", "error", err)
+				}
+			}
+		}
+
+		// Publish to GraphQL subscriptions
+		eventType := subscription.EventCreate
+		if event.Action == ActionUpdate {
+			eventType = subscription.EventUpdate
+		}
+		if h.pubsub != nil {
+			h.pubsub.PublishRecord(eventType, uri, event.CID, event.DID, event.Collection, event.Record)
+		}
+
+	case ActionDelete:
+		if err := h.records.Delete(ctx, uri); err != nil {
+			return fmt.Errorf("failed to delete record: %w", err)
+		}
+		if h.pubsub != nil {
+			h.pubsub.PublishRecord(subscription.EventDelete, uri, "", event.DID, event.Collection, nil)
+		}
+		if h.activity != nil {
+			activityID, err := h.activity.LogActivity(ctx, time.Now(), "delete", event.Collection, event.DID, event.RKey, "")
+			if err != nil {
+				slog.Debug("Failed to log delete activity", "error", err)
+			} else {
+				if err := h.activity.UpdateStatus(ctx, activityID, "completed", nil); err != nil {
+					slog.Debug("Failed to update activity status", "error", err)
+				}
+			}
+		}
+	}
+
+	slog.Debug("Handled record event", "action", event.Action, "uri", uri)
+	return nil
+}
+
+// HandleIdentity processes an identity event by updating the actor's handle.
+func (h *IndexHandler) HandleIdentity(ctx context.Context, event *IdentityEvent) error {
+	return h.actors.Upsert(ctx, event.DID, event.Handle)
+}
diff --git a/internal/tap/handler_test.go b/internal/tap/handler_test.go
new file mode 100644
index 0000000..d3ed834
--- /dev/null
+++ b/internal/tap/handler_test.go
@@ -0,0 +1,480 @@
+package tap_test
+
+import (
+	"context"
+	"encoding/json"
+	"testing"
+
+	"github.com/GainForest/hypergoat/internal/graphql/subscription"
+	"github.com/GainForest/hypergoat/internal/tap"
+	"github.com/GainForest/hypergoat/internal/testutil"
+)
+
+// setupHandler creates an IndexHandler backed by a real in-memory SQLite database.
+func setupHandler(t *testing.T) (*tap.IndexHandler, *testutil.TestDB, *subscription.PubSub) {
+	t.Helper()
+	db := testutil.SetupTestDB(t)
+	pubsub := subscription.NewPubSub()
+	handler := tap.NewIndexHandler(db.Records, db.Actors, db.Activity, pubsub)
+	return handler, db, pubsub
+}
+
+func TestIndexHandler_HandleRecord_Create(t *testing.T) {
+	handler, db, pubsub := setupHandler(t)
+	ctx := context.Background()
+
+	// Subscribe to capture published events
+	sub := pubsub.Subscribe("app.bsky.feed.post")
+	defer pubsub.Unsubscribe(sub)
+
+	event := &tap.RecordEvent{
+		Live:       true,
+		Rev:        "rev1",
+		DID:        "did:plc:alice",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post1",
+		Action:     tap.ActionCreate,
+		CID:        "bafyrei123",
+		Record:     json.RawMessage(`{"text":"hello"}`),
+	}
+
+	if err := handler.HandleRecord(ctx, event); err != nil {
+		t.Fatalf("HandleRecord returned error: %v", err)
+	}
+
+	// Verify record was inserted
+	uri := "at://did:plc:alice/app.bsky.feed.post/post1"
+	rec, err := db.Records.GetByURI(ctx, uri)
+	if err != nil {
+		t.Fatalf("record not found after create: %v", err)
+	}
+	if rec.CID != "bafyrei123" {
+		t.Errorf("expected CID %q, got %q", "bafyrei123", rec.CID)
+	}
+
+	// Verify actor was upserted
+	actor, err := db.Actors.GetByDID(ctx, "did:plc:alice")
+	if err != nil {
+		t.Fatalf("actor not found after create: %v", err)
+	}
+	if actor.DID != "did:plc:alice" {
+		t.Errorf("expected DID %q, got %q", "did:plc:alice", actor.DID)
+	}
+
+	// Verify pubsub event was published
+	select {
+	case pubEvent := <-sub.Events:
+		if pubEvent.Type != subscription.EventCreate {
+			t.Errorf("expected EventCreate, got %q", pubEvent.Type)
+		}
+		if pubEvent.URI != uri {
+			t.Errorf("expected URI %q, got %q", uri, pubEvent.URI)
+		}
+		if pubEvent.CID != "bafyrei123" {
+			t.Errorf("expected CID %q, got %q", "bafyrei123", pubEvent.CID)
+		}
+	default:
+		t.Error("expected pubsub event to be published for create")
+	}
+}
+
+func TestIndexHandler_HandleRecord_Update(t *testing.T) {
+	handler, db, pubsub := setupHandler(t)
+	ctx := context.Background()
+
+	// Subscribe to capture published events
+	sub := pubsub.Subscribe("app.bsky.feed.post")
+	defer pubsub.Unsubscribe(sub)
+
+	// First create the record
+	createEvent := &tap.RecordEvent{
+		DID:        "did:plc:alice",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post1",
+		Action:     tap.ActionCreate,
+		CID:        "bafyrei_original",
+		Record:     json.RawMessage(`{"text":"original"}`),
+	}
+	if err := handler.HandleRecord(ctx, createEvent); err != nil {
+		t.Fatalf("HandleRecord (create) returned error: %v", err)
+	}
+	// Drain the create event
+	<-sub.Events
+
+	// Now update the record
+	updateEvent := &tap.RecordEvent{
+		DID:        "did:plc:alice",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post1",
+		Action:     tap.ActionUpdate,
+		CID:        "bafyrei_updated",
+		Record:     json.RawMessage(`{"text":"updated"}`),
+	}
+	if err := handler.HandleRecord(ctx, updateEvent); err != nil {
+		t.Fatalf("HandleRecord (update) returned error: %v", err)
+	}
+
+	// Verify record was updated
+	uri := "at://did:plc:alice/app.bsky.feed.post/post1"
+	rec, err := db.Records.GetByURI(ctx, uri)
+	if err != nil {
+		t.Fatalf("record not found after update: %v", err)
+	}
+	if rec.CID != "bafyrei_updated" {
+		t.Errorf("expected updated CID %q, got %q", "bafyrei_updated", rec.CID)
+	}
+
+	// Verify pubsub event was published with EventUpdate
+	select {
+	case pubEvent := <-sub.Events:
+		if pubEvent.Type != subscription.EventUpdate {
+			t.Errorf("expected EventUpdate, got %q", pubEvent.Type)
+		}
+		if pubEvent.URI != uri {
+			t.Errorf("expected URI %q, got %q", uri, pubEvent.URI)
+		}
+	default:
+		t.Error("expected pubsub event to be published for update")
+	}
+}
+
+func TestIndexHandler_HandleRecord_Delete(t *testing.T) {
+	handler, db, pubsub := setupHandler(t)
+	ctx := context.Background()
+
+	// Subscribe to capture published events
+	sub := pubsub.Subscribe("app.bsky.feed.post")
+	defer pubsub.Unsubscribe(sub)
+
+	// First create the record
+	createEvent := &tap.RecordEvent{
+		DID:        "did:plc:alice",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post1",
+		Action:     tap.ActionCreate,
+		CID:        "bafyrei123",
+		Record:     json.RawMessage(`{"text":"hello"}`),
+	}
+	if err := handler.HandleRecord(ctx, createEvent); err != nil {
+		t.Fatalf("HandleRecord (create) returned error: %v", err)
+	}
+	// Drain the create event
+	<-sub.Events
+
+	// Now delete the record
+	deleteEvent := &tap.RecordEvent{
+		DID:        "did:plc:alice",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post1",
+		Action:     tap.ActionDelete,
+	}
+	if err := handler.HandleRecord(ctx, deleteEvent); err != nil {
+		t.Fatalf("HandleRecord (delete) returned error: %v", err)
+	}
+
+	// Verify record was deleted
+	uri := "at://did:plc:alice/app.bsky.feed.post/post1"
+	_, err := db.Records.GetByURI(ctx, uri)
+	if err == nil {
+		t.Error("expected record to be deleted, but it still exists")
+	}
+
+	// Verify pubsub event was published with EventDelete
+	select {
+	case pubEvent := <-sub.Events:
+		if pubEvent.Type != subscription.EventDelete {
+			t.Errorf("expected EventDelete, got %q", pubEvent.Type)
+		}
+		if pubEvent.URI != uri {
+			t.Errorf("expected URI %q, got %q", uri, pubEvent.URI)
+		}
+	default:
+		t.Error("expected pubsub event to be published for delete")
+	}
+}
+
+func TestIndexHandler_HandleRecord_Create_UpsertActor(t *testing.T) {
+	handler, db, _ := setupHandler(t)
+	ctx := context.Background()
+
+	event := &tap.RecordEvent{
+		DID:        "did:plc:bob",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post2",
+		Action:     tap.ActionCreate,
+		CID:        "bafyrei456",
+		Record:     json.RawMessage(`{"text":"hi"}`),
+	}
+
+	if err := handler.HandleRecord(ctx, event); err != nil {
+		t.Fatalf("HandleRecord returned error: %v", err)
+	}
+
+	// Verify actor was upserted
+	actor, err := db.Actors.GetByDID(ctx, "did:plc:bob")
+	if err != nil {
+		t.Fatalf("actor not found: %v", err)
+	}
+	if actor.DID != "did:plc:bob" {
+		t.Errorf("expected DID %q, got %q", "did:plc:bob", actor.DID)
+	}
+}
+
+func TestIndexHandler_HandleRecord_ActivityLogged(t *testing.T) {
+	handler, db, _ := setupHandler(t)
+	ctx := context.Background()
+
+	event := &tap.RecordEvent{
+		DID:        "did:plc:carol",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post3",
+		Action:     tap.ActionCreate,
+		CID:        "bafyrei789",
+		Record:     json.RawMessage(`{"text":"activity test"}`),
+	}
+
+	if err := handler.HandleRecord(ctx, event); err != nil {
+		t.Fatalf("HandleRecord returned error: %v", err)
+	}
+
+	// Verify activity was logged
+	count, err := db.Activity.GetCount(ctx)
+	if err != nil {
+		t.Fatalf("failed to get activity count: %v", err)
+	}
+	if count == 0 {
+		t.Error("expected activity to be logged, but count is 0")
+	}
+
+	// Verify activity status is "completed" (not "pending")
+	entries, err := db.Activity.GetRecentActivity(ctx, 1)
+	if err != nil {
+		t.Fatalf("failed to get recent activity: %v", err)
+	}
+	if len(entries) == 0 {
+		t.Fatal("expected at least one activity entry")
+	}
+	if entries[0].Status != "completed" {
+		t.Errorf("expected activity status %q, got %q", "completed", entries[0].Status)
+	}
+}
+
+func TestIndexHandler_HandleRecord_NilActivity(t *testing.T) {
+	// Handler with nil activity repo should not panic
+	db := testutil.SetupTestDB(t)
+	pubsub := subscription.NewPubSub()
+	handler := tap.NewIndexHandler(db.Records, db.Actors, nil, pubsub)
+	ctx := context.Background()
+
+	event := &tap.RecordEvent{
+		DID:        "did:plc:dave",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post4",
+		Action:     tap.ActionCreate,
+		CID:        "bafyreinil",
+		Record:     json.RawMessage(`{"text":"no activity"}`),
+	}
+
+	if err := handler.HandleRecord(ctx, event); err != nil {
+		t.Fatalf("HandleRecord with nil activity returned error: %v", err)
+	}
+}
+
+func TestIndexHandler_HandleRecord_NilPubSub(t *testing.T) {
+	// Handler with nil pubsub should not panic
+	db := testutil.SetupTestDB(t)
+	handler := tap.NewIndexHandler(db.Records, db.Actors, nil, nil)
+	ctx := context.Background()
+
+	// Test create event does not panic and stores the record
+	createEvent := &tap.RecordEvent{
+		DID:        "did:plc:grace",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post5",
+		Action:     tap.ActionCreate,
+		CID:        "bafyreinilpubsub",
+		Record:     json.RawMessage(`{"text":"no pubsub"}`),
+	}
+
+	if err := handler.HandleRecord(ctx, createEvent); err != nil {
+		t.Fatalf("HandleRecord (create) with nil pubsub returned error: %v", err)
+	}
+
+	// Verify record was still stored correctly
+	uri := "at://did:plc:grace/app.bsky.feed.post/post5"
+	rec, err := db.Records.GetByURI(ctx, uri)
+	if err != nil {
+		t.Fatalf("record not found after create with nil pubsub: %v", err)
+	}
+	if rec.CID != "bafyreinilpubsub" {
+		t.Errorf("expected CID %q, got %q", "bafyreinilpubsub", rec.CID)
+	}
+
+	// Test delete event does not panic
+	deleteEvent := &tap.RecordEvent{
+		DID:        "did:plc:grace",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post5",
+		Action:     tap.ActionDelete,
+	}
+
+	if err := handler.HandleRecord(ctx, deleteEvent); err != nil {
+		t.Fatalf("HandleRecord (delete) with nil pubsub returned error: %v", err)
+	}
+
+	// Verify record was deleted
+	_, err = db.Records.GetByURI(ctx, uri)
+	if err == nil {
+		t.Error("expected record to be deleted, but it still exists")
+	}
+}
+
+// TestIndexHandler_HandleRecord_DeleteNonExistent verifies that deleting a record
+// that does not exist is not an error (SQL DELETE of 0 rows is fine) and that
+// pubsub events are still published.
+func TestIndexHandler_HandleRecord_DeleteNonExistent(t *testing.T) {
+	handler, _, pubsub := setupHandler(t)
+	ctx := context.Background()
+
+	// Subscribe to capture published events
+	sub := pubsub.Subscribe("app.bsky.feed.post")
+	defer pubsub.Unsubscribe(sub)
+
+	// Delete a record that does not exist — should succeed (0 rows affected is fine)
+	deleteEvent := &tap.RecordEvent{
+		DID:        "did:plc:nonexistent",
+		Collection: "app.bsky.feed.post",
+		RKey:       "doesnotexist",
+		Action:     tap.ActionDelete,
+	}
+
+	if err := handler.HandleRecord(ctx, deleteEvent); err != nil {
+		t.Fatalf("HandleRecord (delete non-existent) returned unexpected error: %v", err)
+	}
+
+	// Verify pubsub event was still published (delete succeeded)
+	select {
+	case pubEvent := <-sub.Events:
+		if pubEvent.Type != subscription.EventDelete {
+			t.Errorf("expected EventDelete, got %q", pubEvent.Type)
+		}
+	default:
+		t.Error("expected pubsub event to be published for delete of non-existent record")
+	}
+}
+
+func TestIndexHandler_HandleRecord_DeleteActivityCompleted(t *testing.T) {
+	handler, db, _ := setupHandler(t)
+	ctx := context.Background()
+
+	// First create a record so there is something to delete.
+	createEvent := &tap.RecordEvent{
+		DID:        "did:plc:henry",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post-del-activity",
+		Action:     tap.ActionCreate,
+		CID:        "bafyreihenry",
+		Record:     json.RawMessage(`{"text":"to be deleted"}`),
+	}
+	if err := handler.HandleRecord(ctx, createEvent); err != nil {
+		t.Fatalf("HandleRecord (create) returned error: %v", err)
+	}
+
+	// Now delete the record.
+	deleteEvent := &tap.RecordEvent{
+		DID:        "did:plc:henry",
+		Collection: "app.bsky.feed.post",
+		RKey:       "post-del-activity",
+		Action:     tap.ActionDelete,
+	}
+	if err := handler.HandleRecord(ctx, deleteEvent); err != nil {
+		t.Fatalf("HandleRecord (delete) returned error: %v", err)
+	}
+
+	// GetRecentActivity returns entries ordered by timestamp DESC, so the delete
+	// entry should be first. Fetch enough entries to find the delete one.
+	entries, err := db.Activity.GetRecentActivity(ctx, 10)
+	if err != nil {
+		t.Fatalf("failed to get recent activity: %v", err)
+	}
+
+	found := false
+	for _, e := range entries {
+		if e.Operation == "delete" {
+			found = true
+			if e.Status != "completed" {
+				t.Errorf("expected delete activity status %q, got %q", "completed", e.Status)
+			}
+			break
+		}
+	}
+	if !found {
+		t.Error("expected to find an activity entry with operation=\"delete\"")
+	}
+}
+
+func TestIndexHandler_HandleIdentity(t *testing.T) {
+	handler, db, _ := setupHandler(t)
+	ctx := context.Background()
+
+	event := &tap.IdentityEvent{
+		DID:      "did:plc:eve",
+		Handle:   "eve.bsky.social",
+		IsActive: true,
+		Status:   "active",
+	}
+
+	if err := handler.HandleIdentity(ctx, event); err != nil {
+		t.Fatalf("HandleIdentity returned error: %v", err)
+	}
+
+	// Verify actor was upserted with handle
+	actor, err := db.Actors.GetByDID(ctx, "did:plc:eve")
+	if err != nil {
+		t.Fatalf("actor not found after HandleIdentity: %v", err)
+	}
+	if actor.DID != "did:plc:eve" {
+		t.Errorf("expected DID %q, got %q", "did:plc:eve", actor.DID)
+	}
+	if actor.Handle != "eve.bsky.social" {
+		t.Errorf("expected handle %q, got %q", "eve.bsky.social", actor.Handle)
+	}
+}
+
+func TestIndexHandler_HandleIdentity_UpdatesHandle(t *testing.T) {
+	handler, db, _ := setupHandler(t)
+	ctx := context.Background()
+
+	// First upsert with old handle
+	if err := db.Actors.Upsert(ctx, "did:plc:frank", "frank-old.bsky.social"); err != nil {
+		t.Fatalf("failed to upsert actor: %v", err)
+	}
+
+	// Now handle identity event with new handle
+	event := &tap.IdentityEvent{
+		DID:      "did:plc:frank",
+		Handle:   "frank-new.bsky.social",
+		IsActive: true,
+		Status:   "active",
+	}
+
+	if err := handler.HandleIdentity(ctx, event); err != nil {
+		t.Fatalf("HandleIdentity returned error: %v", err)
+	}
+
+	// Verify handle was updated
+	actor, err := db.Actors.GetByDID(ctx, "did:plc:frank")
+	if err != nil {
+		t.Fatalf("actor not found: %v", err)
+	}
+	if actor.Handle != "frank-new.bsky.social" {
+		t.Errorf("expected updated handle %q, got %q", "frank-new.bsky.social", actor.Handle)
+	}
+}
+
+func TestIndexHandler_ImplementsEventHandler(t *testing.T) {
+	// Compile-time check that IndexHandler implements EventHandler
+	db := testutil.SetupTestDB(t)
+	pubsub := subscription.NewPubSub()
+	var _ tap.EventHandler = tap.NewIndexHandler(db.Records, db.Actors, db.Activity, pubsub)
+}