diff --git a/CLAUDE.md b/CLAUDE.md
index 3d1522d2..c30605b9 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -319,7 +319,7 @@ Check `agentex/docker-compose.yml` for default values.
 ### Database Migrations
 
 Always create migrations when changing models:
-1. Modify SQLAlchemy models in `database/models/`
+1. Modify the SQLAlchemy models in `src/adapters/orm.py`
 2. Run `make migration NAME="description"` from `agentex/`
 3. Review generated migration in `database/migrations/versions/`
 4. Apply with `make apply-migrations`
@@ -380,7 +380,7 @@ Use the escape hatch for "this needs a maintenance window with traffic shifted a
 
 ##### Anti-pattern → linter rule reference
 
-The migration linter at `agentex/scripts/lint_migrations.py` enforces these rules at PR time via `.github/workflows/migration-lint.yml`. It only checks files changed vs the PR base, so existing migrations are not retro-flagged. The mapping below is what the linter catches:
+The migration linter at `agentex/scripts/ci_tools/migration_lint.py` enforces these rules at PR time via `.github/workflows/migration-lint.yml`. It only checks files changed vs the PR base, so existing migrations are not retro-flagged. The mapping below is what the linter catches:
 
 | Anti-pattern | Linter rule |
 |---|---|
@@ -393,7 +393,7 @@ The migration linter at `agentex/scripts/lint_migrations.py` enforces these rule
 Run the linter locally before pushing:
 
 ```bash
-agentex/scripts/lint_migrations.py --base-ref origin/main
+python3 agentex/scripts/ci_tools/migration_lint.py --base origin/main
 ```
 
 ##### Other rules
@@ -443,7 +443,7 @@ sudo systemctl stop redis-server
 
 ### Adding Database Tables
 
-1. Create SQLAlchemy model in `database/models/`
+1. Add the SQLAlchemy model to `src/adapters/orm.py`
 2. Generate migration: `make migration NAME="add_table_name"`
 3. Review and edit migration file if needed
 4. Apply migration: `make apply-migrations`
diff --git a/agentex-ui/README.md b/agentex-ui/README.md
index 9eb53860..f441c772 100644
--- a/agentex-ui/README.md
+++ b/agentex-ui/README.md
@@ -42,7 +42,7 @@ A modern web interface for building, testing, and monitoring intelligent agents.
 
 ### Developer Experience
 
-- **Real-time Updates** - Live task and message updates via WebSocket subscriptions
+- **Real-time Updates** - Live task and message updates streamed over HTTP (`GET /tasks/{id}/stream`, server-sent events)
 - **Optimistic UI** - Instant feedback with automatic cache updates
 - **Error Handling** - User-friendly error messages with toast notifications
 - **Dark Mode** - WCAG-compliant dark mode with proper contrast ratios
@@ -53,7 +53,7 @@ A modern web interface for building, testing, and monitoring intelligent agents.
 - **Styling**: Tailwind CSS v4, shadcn/ui components
 - **State Management**: React Query for server state
 - **Data Fetching**: Agentex SDK (`agentex`) for API client + RPC helpers
-- **Real-time**: WebSocket subscriptions for live updates
+- **Real-time**: streaming HTTP subscriptions (server-sent events) for live updates
 
 ## Prerequisites
 
@@ -177,7 +177,7 @@ For Docker-related commands, see the Docker section in `build.ps1 help`.
 - `hooks/use-agents.ts` - Fetches all agents via React Query
 - `hooks/use-tasks.ts` - Task list with infinite scroll pagination
 - `hooks/use-task-messages.ts` - Message fetching and sending with message streaming for sync agents
-- `hooks/use-task-subscription.ts` - Real-time task updates via WebSocket for async agents
+- `hooks/use-task-subscription.ts` - Real-time task updates via the HTTP event stream for async agents
 - `hooks/use-spans.ts` - Execution trace data
 
 **Components:**