reflectt-node 0.1.0

package/public/docs.md

@@ -0,0 +1,1062 @@
+# reflectt-node API Reference
+
+Base URL: `http://localhost:4445`
+
+## Quickstarts
+
+- [Tasks API Quickstart](../docs/TASKS_API_QUICKSTART.md) — create → doing → validating → done with current status contract and curl examples.
+- [Known Issues](../docs/KNOWN_ISSUES.md) — verified runtime/docs drift with repro, workaround, and owner.
+- [Reviewer Handoff Bundle Template](../docs/REVIEWER_HANDOFF_BUNDLE_TEMPLATE.md) — reviewer-ready QA bundle format.
+- [Task Creation Template](../docs/TASK_CREATION_TEMPLATE.md) — high-signal task spec + anti-patterns.
+- [Reviewer-Ready Tasks Guide](../docs/REVIEWER_READY_TASKS_GUIDE.md) — short operational guide to reduce QA churn.
+- [Dashboard Task Field Reference](../docs/DASHBOARD_TASK_FIELD_REFERENCE.md) — task-card field mapping, null semantics, and UI edge cases.
+- [Task Comments API Quickstart](../docs/TASK_COMMENTS_API_QUICKSTART.md) — POST/GET task comments with QA checklist.
+- [Release Endpoints Guide](../docs/RELEASE_ENDPOINTS_GUIDE.md) — /release/status, /release/notes, /release/deploy workflow.
+- [Review Queue SOP](../docs/REVIEW_QUEUE_SOP.md) — validating queue workflow, SLA, and PASS/FAIL discipline.
+- [Task-Close Gate Playbook](../docs/TASK_CLOSE_GATE_PLAYBOOK.md) — required close metadata with pass/fail examples.
+- [Backlog Claim Troubleshooting](../docs/BACKLOG_CLAIM_TROUBLESHOOTING.md) — claim flow, metadata requirements, and common errors.
+- [Health Endpoints Operator Cheat Sheet](../docs/HEALTH_ENDPOINTS_OPERATOR_CHEAT_SHEET.md) — compact endpoint-by-endpoint triage reference.
+- [Health Endpoints Map](../docs/HEALTH_ENDPOINTS_MAP.md) — endpoint selector for /health, /health/team, /health/agents, and debug paths.
+- [Watchdog Behavior Explainer](../docs/WATCHDOG_BEHAVIOR_EXPLAINER.md) — idle/cadence/mention rescue behavior with cooldown + debug flow.
+- [OpenClaw 2026.2.13 Memory Search Rollout Note](../docs/OPENCLAW_2026_2_13_MEMORY_SEARCH_ROLLOUT_NOTE.md) — what changed, impact, caveats, and safe usage pattern.
+- [Research Intake Handbook](../docs/RESEARCH_INTAKE_HANDBOOK.md) — requests/findings flow and handoff protocol.
+- [Dashboard Panel Reference](../docs/DASHBOARD_PANEL_REFERENCE.md) — panel-to-endpoint mapping and refresh behavior.
+- [API Docs Quality Checklist](../docs/API_DOCS_QUALITY_CHECKLIST.md) — pre-merge checks for endpoint-doc consistency.
+- [Weekly Ship Log Template](../docs/WEEKLY_SHIP_LOG_TEMPLATE.md) — compact weekly status template.
+- [Incident Writeup Template](../docs/INCIDENT_WRITEUP_TEMPLATE.md) — timeline/root-cause/fix/prevention structure.
+- [Contributor Onboarding Script](../docs/CONTRIBUTOR_ONBOARDING_SCRIPT.md) — first-day workflow from clone to validated task.
+
+---
+
+## UI Pages
+
+### `GET /ui-kit`
+
+Living design system reference page. Shows all Reflectt design tokens rendered as interactive specimens: color swatches, typography scale, spacing, radii, shadows, buttons, links, badges, inputs, panels, and tables.
+
+Returns `text/html`. No parameters.
+
+```bash
+# Open in browser
+open http://localhost:4445/ui-kit
+```
+
+---
+
+## Error Envelope (all endpoints)
+
+All API errors normalize to:
+
+```json
+{
+  "success": false,
+  "error": "human-readable message",
+  "code": "BAD_REQUEST|NOT_FOUND|CONFLICT|...",
+  "status": 400,
+  "hint": "optional fix guidance"
+}
+```
+
+For 4xx errors, `hint` is included by default to speed up client-side troubleshooting.
+
+## Rate limiting (`429` / `Retry-After`)
+
+Core `reflectt-node` routes do not currently apply built-in per-route throttling in-process.
+
+Operationally:
+- If you see `429 Too Many Requests`, it is typically from an upstream gateway/proxy layer.
+- If `Retry-After` is present, follow that value before retrying.
+- Retry strategy recommendation: exponential backoff + jitter for idempotent reads.
+
+## Preflight
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/preflight` | Run BYOH preflight checks (auth, network, runtime). Returns JSON with per-check pass/fail, remediation guidance, and overall readiness status. Query: `cloudUrl`, `port`, `skipNetwork` |
+| GET | `/preflight/text` | Run preflight checks and return a plain-text formatted report for CLI/terminal display. Same query params as GET. |
+| POST | `/preflight` | Run preflight checks with custom config. Body: `{ cloudUrl?, port?, skipNetwork?, joinToken?, apiKey?, userId? }`. When `userId` is provided, emits `host_preflight_passed` or `host_preflight_failed` activation funnel events for onboarding drop-off tracking. |
+
+## Hosts (registry)
+
+Remote hosts (multi-host installs) phone-home via a lightweight heartbeat so the dashboard can show which machines are online.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/hosts/heartbeat` | Upsert a host heartbeat. Body: `{ hostId (string, required), hostname?, os?, arch?, ip?, version?, agents? (string[]), metadata? (object) }`. Returns `{ success, host }`.
+| GET | `/hosts` | List all known hosts. Query: `status=online|stale|offline` (optional). Returns `{ hosts, count }`.
+| GET | `/hosts/:hostId` | Fetch one host by ID. Returns `{ host }` or `{ success:false, error:"Host not found" }`.
+| DELETE | `/hosts/:hostId` | Remove a host from the registry. Returns `{ success, hostId }`.
+| GET | `/hosts/keepalive` | Keepalive status for all managed hosts — last ping times, intervals, health. |
+| POST | `/hosts/keepalive/ping` | Manually trigger a keepalive ping to all or a specific host. Body: `{ hostId? }`. Returns `{ success, results }`. |
+
+## Health
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health/errors` | Request error metrics: total errors, total requests, error rate, and last 20 errors for debugging. Returns `{ total_errors, total_requests, error_rate, recent[], timestamp }`. |
+| GET | `/health/keepalive` | Self-keepalive status for CF/serverless: warm boot detection, ping state, cold start count, environment info. |
+| GET | `/health/ping` | Ultra-lightweight keepalive — no DB access. Returns `{ status, uptime_seconds, ts }`. Use for cron triggers, load balancers, uptime monitors. |
+| GET | `/health/watchdog` | Richer keepalive with cold_start flag, task/chat stats, boot_info, and remediation hints. For monitoring dashboards. See `docs/KEEPALIVE.md`. |
+| GET | `/health` | System health — task counts, chat stats, inbox stats. Includes `cold_start` flag (true if uptime < 60s). Query: `include_test=1` to include test-harness tasks in stats (excluded by default). |
+| GET | `/team/health` | Team config linter status for `~/.reflectt/TEAM.md`, `TEAM-ROLES.yaml`, `TEAM-STANDARDS.md` (issues, role coverage, last check timestamp) |
+| GET | `/health/team` | Team health metrics with compliance + `staleDoing` snapshot. Per-agent rows include `activeTaskTitle` and `activeTaskPrLink` when an agent has a doing task with PR evidence. Flagged agents also include `actionable_reason` (last comment age, last transition, last mention age, suggested action). |
+| GET | `/health/agents` | Per-agent health summary (`last_seen`, `active_task`, `heartbeat_age_ms`, `last_shipped_at`, `stale_reason`, state) |
+| GET | `/health/compliance` | Compliance check results |
+| GET | `/health/backlog` | Backlog readiness health by lane (ready counts, floor compliance, breach status, blocked/todo/doing/validating rollups). Query: `include_test=1` to include test-harness tasks. |
+| GET | `/health/system` | System + loop/timer health (quiet-hours suppression, sweeper status, watchdog tick timestamps, uptime/memory) |
+| GET | `/health/build` | Build/runtime identity (version, git SHA, branch, build timestamp, PID, uptime) |
+| GET | `/health/deploy` | Deploy attestation payload for dashboards (`version`, `gitSha`, `branch`, `buildTimestamp`, `startedAt`, `pid`) |
+| GET | `/health/team/summary` | Compact team health summary |
+| GET | `/health/team/history` | Historical team health data |
+| GET | `/health/workflow` | Unified per-agent workflow state: doing-task age, last shipped timestamp, blocker flag, artifact path, and linked PR state. Query: `include_test=1` to include test-harness tasks. |
+| GET | `/health/reflection-pipeline` | Reflection→Insight→Promotion health signal. Returns recent reflection/insight/promotion counts, status (`healthy`\|`at_risk`\|`broken`), and alert timestamps. Triggers alert when reflections flow but insights remain zero past threshold. |
+| GET | `/health/backlog` | Backlog readiness snapshot by lane/agent with ready-floor breach detection and stale-validating summary. Query: `include_test=1` to include test-harness tasks. |
+| GET | `/health/alert-preflight` | Alert-preflight guard metrics: total checked, canary-flagged, suppressed, false-positive rate, mode (canary/enforce/off). |
+| GET | `/health/mention-ack` | Mention-ack lifecycle metrics (pending, timeout, latency counters) |
+| GET | `/health/mention-ack/recent` | Recent mention-ack entries for debugging. Query: `limit` (max 100) |
+| GET | `/health/mention-ack/:agent` | Pending mention-ack entries for one agent |
+| POST | `/health/mention-ack/check-timeouts` | Run timeout sweep and return timed-out mention entries |
+| GET | `/health/idle-nudge/debug` | Idle-nudge watchdog debug state |
+| GET | `/admin/task-comment-rejects` | Reject ledger for phantom task-comment IDs. Query: `limit` (max 200), `reason` (task_not_found\|invalid_task_refs), `author`, `since` (timestamp). Each row includes provenance (integration, sender_id, original_message_id). |
+| POST | `/health/idle-nudge/tick` | Trigger idle-nudge evaluation |
+| POST | `/health/cadence-watchdog/tick` | Trigger cadence watchdog |
+| POST | `/health/mention-rescue/tick` | Trigger mention-rescue fallback |
+| POST | `/health/working-contract/tick` | Evaluate working-contract enforcement: auto-requeue stale doing tasks (90m warning → 15m grace → auto todo) and fire alerts. |
+| GET | `/health/working-contract/gate/:agent` | Dry-run claim gate check for an agent. Returns `{ allowed, reason }` — whether the agent can claim a new task given current WIP and contract status. |
+
+### Quick system-loop check
+
+Verify watchdogs are actually running (and whether they’re suppressed by quiet hours):
+
+```bash
+curl -s http://127.0.0.1:4445/health/system | jq
+```
+
+## Hosts (multi-host registry)
+
+Remote hosts (Pis/robots/other machines) can phone-home to a central reflectt-node.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/hosts/heartbeat` | Upsert a host heartbeat. Body: `{ hostId, hostname?, os?, arch?, ip?, version?, agents? (string[]), metadata? (object) }`. Returns `{ success, host }`. |
+| GET | `/hosts` | List hosts. Query: `status` (optional). Returns `{ hosts, count }`. |
+| GET | `/hosts/:hostId` | Fetch one host by id. Returns `{ host }` or `{ success:false, error }`. |
+| DELETE | `/hosts/:hostId` | Remove a host from registry. Returns `{ success, hostId }`. |
+
+### Team Pulse
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health/team/pulse` | Current team pulse snapshot: per-agent activity summary, team velocity, and health signals |
+| GET | `/health/team/pulse/config` | Read team pulse broadcast configuration |
+| GET | `/health/team/pulse/history` | Historical pulse snapshots. Query: `limit`, `since` |
+| PATCH | `/health/team/pulse/config` | Update pulse config. Fields: `intervalMs`, `channel`, `enabled` |
+| POST | `/health/team/pulse` | Trigger immediate team pulse broadcast |
+| GET | `/health/team/doctor` | Run team doctor diagnostics: checks node, database, agents, gateway, model auth, chat activity. Returns overall status + fix instructions |
+| POST | `/team/starter` | Scaffold a starter team with default agents (builder + ops). Idempotent: skips existing agent directories |
+
+### Quiet hours behavior (watchdogs)
+
+Watchdog endpoints currently execute whenever called (manual or scheduled). Quiet-hours suppression is not enforced by these endpoints at the API layer yet.
+
+If your deployment needs quiet-hours behavior today, enforce it in scheduler/gateway policy (for example: only trigger watchdog ticks during allowed windows).
+
+## Tasks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/tasks` | List tasks. Query: `status`, `assignee`, `agent`, `priority`, `limit`, `offset`, `q` (text search), `updatedSince`, `include_test=1|true` (include test-harness tasks; default excluded). Returns `{ tasks, total, offset, limit, hasMore }`. |
+| GET | `/tasks/:id` | Get task by ID. Also accepts unambiguous ID prefixes. Ambiguous prefix returns `400` with full-ID suggestions. |
+| GET | `/tasks/:id/artifacts` | Resolve all artifact references from task metadata. Returns accessibility status (file existence, URL validation), heartbeat status (last comment age, staleness). Heartbeat threshold: 30m for doing tasks. Query: `include=preview` (first 2000 chars) or `include=content` (full file, up to 400KB). Falls back to shared workspace (`~/.openclaw/workspace-shared`) when file is not in repo root. |
+| GET | `/tasks/:id/history` | Status changelog for task lifecycle transitions. Returns `history[]` entries shaped as `{ status, changedBy, changedAt, metadata }` for each status transition. |
+| GET | `/tasks/:id/comments` | List task discussion comments. Query: `includeSuppressed=true|1` to include suppressed (audit) comments. Returns `{ comments, count, includeSuppressed }` where each comment is `{ id, taskId, author, content, timestamp, category?, suppressed, suppressedReason?, suppressedRule? }`. |
+| POST | `/tasks/:id/comments` | Add task comment. Body: `{ "author": "agent", "content": "text", "category"?: "restart|rollback_trigger|promote_due_verdict" }`. If task has `metadata.comms_policy.rule = silent_until_restart_or_promote_due`, missing/non-whitelisted categories are stored but suppressed from default feeds. Returns `{ success, comment }` (same fields as GET comments). |
+| GET | `/tasks/:id/pr-review` | PR review quality panel data. Returns diff scope, CI checks, done criteria alignment. Requires PR URL in task metadata (`pr_url`, `qa_bundle.pr_link`, or in `artifacts`). |
+| POST | `/tasks/:id/outcome` | Capture 48h checkpoint verdict for completed tasks. Body: `verdict` (`PASS`\|`NO-CHANGE`\|`REGRESSION`), optional `author`, `notes` |
+| POST | `/tasks/:id/review-bundle` | Auto-build reviewer packet by resolving PR URL + CI + artifact evidence from task metadata. Returns normalized `verdict` (`pass`/`fail`) and reasons. Optional body: `author`, `strict` (default `true`, requires CI=`success`). |
+| POST | `/tasks/:id/review` | Reviewer decision endpoint. Body: `{ "reviewer": "agent", "decision": "approve|reject", "comment": "..." }`. Only the assigned reviewer may submit. Approve auto-transitions validating→done. |
+| GET | `/reviews/pending` | Pending reviews for a reviewer. Query: `reviewer` (required), `compact` (optional). Returns tasks in validating awaiting review (excludes already-approved). Each item: id, title, assignee, priority, age_minutes, review_state, pr_url, artifact_path. Sorted oldest-first. |
+| POST | `/tasks` | Create task. Required: `title`, `createdBy`, `assignee`, `reviewer`, `done_criteria` (string[]), `eta`. Optional: `description`, `priority` (P0-P3), `status`, `tags`, `metadata`. **Reflection-origin invariant:** `metadata.source_reflection` or `metadata.source_insight` required (or `metadata.reflection_exempt=true` with `reflection_exempt_reason`). Status contract: `validating` also requires `metadata.artifact_path` under `process/`. |
+| PATCH | `/tasks/:id` | Update task (partial). Any task field, plus optional `actor` for history attribution. Status contract: `doing` requires reviewer + `metadata.eta`; `validating` requires `metadata.artifact_path` under `process/` (workspace-agnostic). |
+| DELETE | `/tasks/:id` | Delete task |
+| GET | `/tasks/next` | Pull-based assignment. Query: `agent`, `compact` |
+| GET | `/tasks/active` | Get active (doing) task for agent. Query: `agent`, `compact`. Returns null if no doing tasks. |
+| GET | `/heartbeat/:agent` | Single compact heartbeat payload (~200 tokens). Returns active task, next task, slim inbox, queue counts, and suggested action. Replaces 3 separate API calls. |
+| GET | `/bootstrap/heartbeat/:agent` | Generate optimal HEARTBEAT.md content for agent. References best endpoints. Includes version stamp and content hash for change detection. |
+| POST | `/bootstrap/team` | Returns TEAM-ROLES.yaml schema, constraints, well-formed examples, and save endpoint. The calling agent composes the team itself. Body: `{ useCase?, maxAgents? }`. Returns `{ schema, constraints, examples[], saveEndpoint, nextSteps[] }`. |
+| GET | `/manage/status` | Remote management: unified status (version + health + uptime). Auth: `x-manage-token` header or `Authorization: Bearer`. |
+| GET | `/manage/config` | Remote management: config introspection with secrets redacted. Auth required. |
+| GET | `/manage/logs` | Remote management: bounded log tail. Query: `level`, `since`, `limit`, `format=text`. Auth required. |
+| POST | `/manage/restart` | Remote management: graceful restart (Docker/systemd/CLI). Auth required. |
+| GET | `/manage/disk` | Remote management: data directory sizes. Auth required. |
+| GET | `/capabilities` | Agent-facing endpoint discovery. Lists all endpoints grouped by purpose, compact support flags, and usage recommendations. |
+| GET | `/version` | Current version + latest available from GitHub releases. Includes `update_available` boolean. Caches GitHub check for 15 minutes. |
+| GET | `/me/:agent` | Agent "My Now" cockpit payload: assigned tasks, pending reviews, blockers, failing-check signals, since-last-seen changelog, and next action. Supports `compact`. |
+| GET | `/tasks/intake-schema` | Task intake schema discovery — returns required/optional fields and per-type templates |
+| GET | `/tasks/templates/:type` | Get task creation template for a specific type (e.g. `feature`, `bug`, `chore`) |
+| GET | `/tasks/search` | Keyword search across task `title` + `description` (case-insensitive). Query: `q`, optional `limit`, `include_test=1|true` (include test-harness tasks; default excluded). |
+| GET | `/tasks/analytics` | Task completion analytics and velocity |
+| GET | `/tasks/instrumentation/lifecycle` | Reviewer/done-criteria gates + status-contract violations (`doing` missing ETA, `validating` missing artifact path) |
+| POST | `/tasks/batch-create` | Batch create up to 20 tasks. Body: `{ "tasks": [...], "createdBy": "agent", "deduplicate": true, "dryRun": false }`. Each task follows the same schema as `POST /tasks`. Returns per-task results (created/duplicate/error) with summary counts. Deduplication checks exact title match + fuzzy word overlap (Jaccard >0.6) against active tasks. |
+| GET | `/tasks/heartbeat-status` | All doing tasks with stale comment activity (>30m). Returns `{ threshold, doingTaskCount, staleCount, staleTasks[] }`. Use for monitoring status heartbeat discipline compliance. |
+| GET | `/tasks/board-health` | Board-level health metrics for backlog replenishment. Returns per-agent breakdown (doing, validating, todo, active counts), `needsWork`/`lowWatermark` flags, and `replenishNeeded` trigger (fires when 2+ agents idle or <3 backlog tasks). Query: `include_test=1` to include test-harness tasks. |
+| GET | `/agents/roles` | Agent role registry with live WIP status. Returns all agents with `name`, `displayName`, `role`, `affinityTags`, `protectedDomains`, `wipCap`, `wipCount`, `overCap`. |
+| POST | `/config/identity` | Set an agent's display name. Body: `{ "agent": "agent-1", "displayName": "Juniper" }`. Persists to TEAM-ROLES.yaml, hot-reloads. Dashboard and mentions use display name. |
+| GET | `/resolve/mention/:mention` | Resolve a mention string (name, displayName, or alias) to canonical agent ID. Returns `{ agent, displayName, role }`. |
+| POST | `/tasks/suggest-assignee` | Suggest best assignee for a task. Body: `{ "title": "...", "tags": [...], "done_criteria": [...] }`. Returns `suggested` agent name, `scores` array with affinity/WIP/throughput breakdown, and `protectedMatch` if a protected domain applies. |
+| GET | `/team/manifest` | Serve TEAM.md from `~/.reflectt/` (falls back to defaults). Returns `manifest` object with `raw_markdown`, parsed `sections` array, `version` (SHA-256 hash), `updated_at`, `path`, and `source`. |
+
+### Lane-state transition metadata (required on guarded transitions)
+
+`PATCH /tasks/:id` enforces transition metadata for lane-locked transitions:
+
+- `doing -> blocked` requires:
+  - `metadata.transition.type = "pause"`
+  - `metadata.transition.reason`
+- `blocked -> doing` requires:
+  - `metadata.transition.type = "resume"`
+  - `metadata.transition.reason`
+- `doing -> doing` with assignee change (handoff) requires:
+  - `metadata.transition.type = "handoff"`
+  - `metadata.transition.reason`
+  - `metadata.transition.handoff_to` (must match new `assignee`)
+
+If missing/invalid, API returns `400` with `Lane-state lock: ...` validation errors.
+
+### Done-gate: PR merge verification
+
+When closing a code-lane task (`product`/`frontend`/`backend`/`infra` lane or `code` tag), the API verifies:
+
+1. **`artifacts` required** — at least one proof link (`gate: artifacts`)
+2. **PR URL required** — at least one GitHub PR URL in artifacts (`gate: pr_link`)
+3. **PR must be merged** — linked PRs are checked via GitHub API; open PRs block closure (`gate: pr_not_merged`)
+4. **Reviewer sign-off** — assigned reviewer must approve (`gate: reviewer_signoff`)
+
+Bypass: set `metadata.pr_waiver=true` + `metadata.pr_waiver_reason` to skip PR gates (hotfixes).
+Graceful degradation: if GitHub API is unavailable, the merge check is skipped (does not block).
+
+## GitHub approvals (per-agent identity routing)
+
+Reflectt needs to occasionally **approve** GitHub PRs. GitHub blocks self-approval (you cannot approve your own PR), so we support per-actor tokens.
+
+### Token configuration
+Store fine-grained PATs in the Secret Vault:
+
+- `github.pat.<actor>` (recommended, scope=`agent`)
+  - Example: `github.pat.harmony`, `github.pat.pixel`, `github.pat.kai`
+- Optional fallback shared reviewer identity:
+  - `github.pat.reviewer` (scope=`host`)
+
+Env var fallback is also supported:
+- `GH_TOKEN_<ACTOR>` / `GITHUB_TOKEN_<ACTOR>`
+- legacy: `GH_TOKEN` / `GITHUB_TOKEN`
+
+### Endpoints
+
+**Security:** These endpoints are **disabled by default**. Enable with:
+- `REFLECTT_ENABLE_GITHUB_APPROVAL_API=true`
+
+They are **localhost-only** and can be additionally protected by token:
+- set `REFLECTT_GITHUB_APPROVAL_TOKEN=<token>`
+- send `x-reflectt-admin-token: <token>` (or `Authorization: Bearer <token>`)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/github/whoami/:actor` | Validate which GitHub user a given actor token maps to (never returns the token). |
+| POST | `/github/pr/approve` | Approve a PR as a given actor. Body: `{ pr_url, actor, reason? }` |
+
+## Recurring Tasks
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/tasks/recurring` | List recurring task definitions |
+| POST | `/tasks/recurring` | Create recurring task definition |
+| PATCH | `/tasks/recurring/:id` | Update recurring task definition (supports `enabled` toggle and schedule updates) |
+| DELETE | `/tasks/recurring/:id` | Delete recurring task definition |
+| POST | `/tasks/recurring/materialize` | Materialize due recurring tasks; skips creation when previous instance is still open. Query: `force=true` to override skip guard |
+
+## Backlog (Self-Serve)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/tasks/backlog` | Unassigned todo tasks ranked by priority then age. Returns `{ tasks, count }` |
+| POST | `/tasks/:id/claim` | Self-assign a task → moves to "doing". Body: `{ "agent": "name" }`. Rejects if already assigned |
+
+## Release / Deploy
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/release/status` | Compare startup code snapshot vs current repo state. Returns `stale` + reasons for code/server mismatch detection. |
+| GET | `/release/notes` | Generate deploy changelog from completed tasks. Query: `since` (epoch ms), `limit`. Returns markdown + structured task list. |
+| GET | `/release/diff` | Compare live SHA vs previous deploy SHA. Returns changed files, inferred endpoint changes, changed tests, commits, and PR links. Query: `from`, `to`, `commitLimit`. |
+| POST | `/release/deploy` | Mark deploy timestamp + tracked commit SHA. Body (optional): `{ "deployedBy": "agent", "note": "text" }` |
+
+## Chat
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/chat/ws` | WebSocket — real-time chat |
+| GET | `/ws/stats` | WebSocket heartbeat stats (connections, ping/pong health, cleanup stats) |
+| POST | `/chat/messages` | Post message. Body: `from` (required), `content` (required), `channel`, `replyTo` |
+| GET | `/chat/messages` | Message history. Query: `channel`, `limit`, `before`, `after`, `compact` (slim: from/content/ts/ch only) |
+| GET | `/chat/context/:agent` | Compact, deduplicated chat context for agent injection. Prioritizes mentions, deduplicates system alerts, slim format. Query: `limit` (default 30), `channel`, `since` (epoch ms, default 4h). |
+| PATCH | `/chat/messages/:id` | Edit message (author-only). Body: `from`, `content` |
+| DELETE | `/chat/messages/:id` | Delete message (author-only). Body: `from` |
+| POST | `/chat/messages/:id/react` | React to message. Body: `emoji`, `agent`, `remove` |
+| GET | `/chat/messages/:id/reactions` | Get reactions |
+| GET | `/chat/channels` | List channels (includes `general`, `decisions`, `shipping`, `reviews`, `blockers`) |
+| GET | `/chat/search` | Search messages. Query: `q`, `channel`, `from`, `limit` |
+| GET | `/chat/messages/:id/thread` | Get thread replies |
+| GET | `/chat/rooms` | List rooms |
+| POST | `/chat/rooms` | Create room |
+
+## Context (Budgeted Injection)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/context/inject/:agent` | Budgeted context injection for an agent. Returns per-layer items + `context_budget` attribution (token estimates, top contributors) and memo reuse metadata. Query: `limit` (default 60, max 200), `channel` (optional; if omitted defaults to `general` → team scope), `since` (epoch ms, default 4h), `task_id` (optional), `peer` (optional), `scope_id` (explicit **session scope** override), `team_scope_id` (explicit **team_shared scope** override; default `team:default`). Default session scope routing (when `scope_id` not provided): `general/ops → team:default`, `task-* / task-comments → task:<taskId>`, `dm:* → user:<peer>`. |
+| GET | `/context/budgets` | Current configured context budgets (per-layer caps + optional total) and autosummary flag. |
+| GET | `/context/memo` | Read a persisted memo. Query: `scope_id` (required), `layer` (`session_local`\|`agent_persistent`\|`team_shared`). |
+| POST | `/context/memo` | Create/overwrite a persisted memo (useful for bootstrapping `team_shared`). Body: `{ scope_id, layer, content, source_window? }`. |
+
+### Noise Budget (control-plane rate limiting)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/chat/noise-budget` | Current budget snapshot: per-channel ratios, window stats, enforcement state |
+| GET | `/chat/suppression/stats` | Chat dedup suppression stats: total suppressed, by category (system/agent), active hash count, since timestamp. |
+| POST | `/chat/suppression/prune` | Prune expired entries from the suppression ledger. Returns `{ pruned }`. |
+| GET | `/chat/noise-budget/canary` | Canary rollback evaluation: ratio vs target, SLA miss delta, P95 response delta |
+| GET | `/chat/noise-budget/suppression-log` | Audit trail of suppressed/digested messages |
+| GET | `/chat/noise-budget/config` | Read current noise budget configuration |
+| PATCH | `/chat/noise-budget/config` | Update config. Fields: `budgetPercent`, `dedupWindowMs`, `digestIntervalMs`, `channelBudgets` |
+| POST | `/chat/noise-budget/activate` | Exit canary (log-only) mode and enable enforcement |
+| POST | `/chat/noise-budget/flush-digest` | Force immediate digest flush |
+
+Bypass: escalation, blocker, and critical-priority messages always pass through budget enforcement.
+Budget enforcement requires minimum 10 messages in the rolling window before activating.
+
+### Alert Integrity Guard (false-positive prevention)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/chat/alert-integrity` | Current alert integrity stats: total checked, blocked false-positives, pass-through count |
+| GET | `/chat/alert-integrity/audit` | Audit log of preflight decisions. Query: `limit`, `since` |
+| GET | `/chat/alert-integrity/config` | Read alert integrity guard configuration |
+| GET | `/chat/alert-integrity/rollback` | Rollback evaluation: false-positive rate, missed true-positives, preflight latency p95 |
+| PATCH | `/chat/alert-integrity/config` | Update config. Fields: `enabled`, `canaryMode`, `maxPreflightMs`, `reconcileFields` |
+| POST | `/chat/alert-integrity/activate` | Exit canary (log-only) mode and enable enforcement |
+
+Preflight checks reconcile live task state (status, assignee, reviewer, recent comment timestamp, queue state hash) before publishing SLA/requeue/stale alerts. Idempotent alert key: `task_id + alert_type + state_hash`.
+
+### Chat edit/delete contract
+
+- `PATCH /chat/messages/:id` and `DELETE /chat/messages/:id` are author-only.
+- Request body must include `from` matching the original message author.
+- Non-author attempts return an error envelope (`403`), and unknown message IDs return `404`.
+
+## Inbox
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/inbox/:agent` | Get inbox. Query: `limit`, `since` (epoch ms), `channel`, `compact` (strips id/reactions/replyCount) |
+| POST | `/inbox/:agent/ack` | Acknowledge messages. Body: `{ "upTo": epochMs }` |
+| POST | `/inbox/:agent/subscribe` | Replace channel subscriptions. Body: `{ "channels": ["reviews", "blockers"] }` |
+| GET | `/inbox/:agent/subscriptions` | List subscriptions |
+| GET | `/inbox/:agent/unread` | Unread count |
+| GET | `/inbox/:agent/mentions` | Get @mentions |
+
+## Presence
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/presence` | All agents' presence |
+| GET | `/presence/:agent` | Single agent presence |
+| POST | `/presence/:agent` | Update presence. Body: `{ "status": "working|idle|blocked|reviewing|offline" }` |
+| GET | `/presence/:agent/focus` | Get agent focus state (active, level, expiry) |
+| POST | `/presence/:agent/focus` | Toggle focus mode. Body: `{ "active": true, "level": "soft|deep", "durationMin": 60, "reason": "shipping PR" }`. Soft: suppresses system nudges, allows direct mentions. Deep: suppresses everything except blocker/review pings. |
+
+## Memory
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/memory/:agent` | Get all memory files |
+| POST | `/memory/:agent` | Save memory. Body: `{ "content": "..." }` |
+| GET | `/memory/:agent/search` | Search memory. Query: `q` |
+
+## Semantic Search
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/search/semantic` | Semantic search across indexed tasks and chat messages. Query: `q` (required), `limit`, `type` (`task`\|`chat`\|`reflection`\|`insight`\|`shared_file`) |
+| GET | `/search/semantic/status` | Vector index status — availability and counts by source type (tasks, chat, reflections, insights, shared_files) |
+| POST | `/search/semantic/reindex` | Bulk reindex all existing tasks, reflections, and insights for semantic search |
+| GET | `/knowledge/search` | Unified knowledge search across all indexed content (tasks, chat, reflections, insights, shared files). Query: `q` (required), `limit`, `type` (optional filter). Returns results with source_type, snippet, similarity score, and deep link. |
+| GET | `/knowledge/stats` | Knowledge index health — availability and counts per source type |
+| POST | `/knowledge/reindex-shared` | Scan and index shared workspace files (process/, specs/, artifacts/, handoffs/, references/) for knowledge search |
+| POST | `/knowledge/docs` | Create a knowledge document. Body: `{ title, content, category, author, tags?, related_task_ids?, related_insight_ids? }`. Categories: decision, runbook, architecture, lesson, how-to. Auto-indexed for search. |
+| GET | `/knowledge/docs` | List documents. Query: `tag`, `category`, `author`, `search` (text), `limit`. |
+| GET | `/knowledge/docs/:id` | Get single document. |
+| PATCH | `/knowledge/docs/:id` | Update document (re-indexes in vector store). |
+| DELETE | `/knowledge/docs/:id` | Delete document + vector entry. |
+| POST | `/contacts` | Create a contact. Body: `name` (required); optional: `org`, `emails[]`, `handles{}` (discord/github/twitter), `tags[]`, `notes`, `source`, `owner`, `last_contact` (epoch ms), `related_task_ids[]`. Auto-indexed for knowledge search. |
+| GET | `/contacts` | List contacts. Query: `name`, `org`, `tag`, `owner`, `q` (text search across name/org/notes/emails), `limit`, `offset`. |
+| GET | `/contacts/:id` | Get a single contact by ID. |
+| PATCH | `/contacts/:id` | Update a contact. Body: any field from create. Re-indexes on update. |
+| DELETE | `/contacts/:id` | Delete a contact. Removes from vector index. |
+
+## Experiments
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/experiments` | Create experiment |
+| GET | `/experiments/active` | List active experiments |
+
+## Research
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/research/requests` | List research requests. Query: `status`, `owner`, `category`, `limit` |
+| POST | `/research/requests` | Create research request. Body: `title`, `question`, `requestedBy`; optional: `owner`, `category`, `priority`, `taskId`, `dueAt`, `slaHours` |
+| GET | `/research/findings` | List findings. Query: `requestId`, `author`, `limit` |
+| POST | `/research/findings` | Add finding linked to request. Body: `requestId`, `title`, `summary`, `author`; optional `artifactUrl`, `confidence`, `highlights[]` |
+| POST | `/research/handoff` | Structured research→execution handoff that auto-creates a task. Required: `requestId`, `findingIds[]`, `title`, `summary`, `assignee`, `reviewer`, `eta`. Returns linked task + source metadata. |
+
+## Content
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/content/published` | Record published content |
+| GET | `/content/published` | List published content |
+| GET | `/content/published/:id` | Get content piece |
+| PATCH | `/content/published/:id/performance` | Update performance metrics |
+| GET | `/content/calendar` | Calendar entries |
+| POST | `/content/calendar` | Create calendar entry |
+| GET | `/content/calendar/:id` | Get calendar entry |
+| DELETE | `/content/calendar/:id` | Delete calendar entry |
+| GET | `/content/stats` | Publishing statistics |
+| GET | `/content/performance` | Overall performance metrics |
+
+## Events (SSE)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/events/subscribe` | SSE stream for real-time updates. Query: `agent`, `topics` (comma-separated), `types` (exact event type filter, comma-separated) |
+| GET | `/events` | SSE alias of `/events/subscribe` (used by reflectt-channel plugin) |
+| GET | `/events/types` | List valid event types for SSE `?types=` filtering |
+| GET | `/events/status` | Event system status |
+| GET | `/events/config` | Get event config |
+| POST | `/events/config` | Update event config (`batchWindowMs`) |
+
+## Analytics
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/agents/activity` | All agents activity summary |
+| GET | `/agents/:agent/activity` | Single agent activity |
+| GET | `/activity` | Global activity feed |
+| GET | `/analytics/foragents` | forAgents.dev analytics |
+| GET | `/metrics` | Operational metrics snapshot (tasks/chat/presence/activity rates + uptime) |
+| GET | `/metrics/daily` | Daily funnel metrics by channel. Query: `timezone` (IANA tz, default `America/Vancouver`) |
+| GET | `/metrics/summary` | Aggregated metrics |
+| GET | `/logs` | Server logs. Query: `limit`, `level` |
+
+## MCP
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/sse` | MCP SSE transport |
+| POST | `/mcp/messages` | MCP message handler |
+
+## Database
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/db/status` | SQLite database status (engine, WAL mode, schema version, table row counts including `sync_ledger`) |
+
+## Cloud
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/cloud/status` | Cloud connection state (registered, heartbeat age, sync status). Only active when `REFLECTT_HOST_TOKEN` is set. |
+| POST | `/cloud/reload` | Hot-reload cloud config from `~/.reflectt/config.json` without server restart. Updates env vars and restarts heartbeat/sync loops. Used by CLI after `host connect` enrollment. |
+| GET | `/provisioning/status` | Host provisioning state: phase, enrollment, config/secrets pull status, webhook routes. Dashboard-safe (no credentials). |
+| POST | `/provisioning/provision` | Full provisioning flow: enroll with cloud (join token or API key), pull config + secrets, configure webhooks. Body: `{ cloudUrl, hostName, joinToken?, apiKey?, capabilities? }`. |
+| POST | `/provisioning/refresh` | Re-pull config + secrets + webhooks from cloud. Requires existing enrollment. |
+| POST | `/provisioning/reset` | Reset provisioning state for re-enrollment. Clears hostId, credential, and all provisioning data. |
+| GET | `/provisioning/webhooks` | List configured webhook routes for this host. |
+| POST | `/provisioning/webhooks` | Add a webhook route. Body: `{ provider, path?, events?, active? }`. |
+| DELETE | `/provisioning/webhooks/:id` | Remove a webhook route by ID. |
+| POST | `/webhooks/incoming/:provider` | Receive incoming webhooks from external providers (GitHub, Stripe, etc.). Auto-routes through delivery engine to configured targets. Returns 202 Accepted. |
+| POST | `/webhooks/deliver` | Enqueue a webhook for durable delivery. Body: `{ provider, eventType, payload, targetUrl, idempotencyKey?, metadata? }`. Returns event with idempotency key. |
+| GET | `/webhooks/events` | List webhook events. Query: `status`, `provider`, `limit`, `offset`. |
+| GET | `/webhooks/events/:id` | Get a webhook event by ID. |
+| POST | `/webhooks/events/:id/replay` | Replay a webhook: re-enqueue with new idempotency key. Original preserved in audit trail. |
+| GET | `/webhooks/dlq` | Dead letter queue: list permanently failed webhook deliveries. Query: `limit`. |
+| GET | `/webhooks/stats` | Webhook delivery statistics: counts by status, config, oldest pending. |
+| PATCH | `/webhooks/config` | Update webhook delivery config (maxAttempts, backoff, retention, timeout, concurrency). |
+| GET | `/webhooks/idempotency/:key` | Lookup webhook event by idempotency key. |
+## Host Registry
+
+Multi-host management: remote hosts register via heartbeat and are tracked by status (online/stale/offline based on `last_seen_at`).
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/hosts/heartbeat` | Register or update a host. Body: `{ hostId, name?, version?, capabilities?, meta? }`. Requires `Authorization: Bearer <HEARTBEAT_SECRET>` header. Returns upserted host record. |
+| GET | `/hosts` | List all registered hosts. Each includes computed `status` (online: <5min, stale: 5-15min, offline: >15min). Query: `status` filter. |
+| GET | `/hosts/:hostId` | Get a single host by ID with computed status. |
+| DELETE | `/hosts/:hostId` | Remove a host from the registry. |
+
+| GET | `/portability/export` | One-click export: team config, server config (redacted), encrypted secrets, webhook routes, provisioning state. |
+| GET | `/portability/export/download` | Download export bundle as JSON file attachment. |
+| POST | `/portability/import` | Import from export bundle. Body: `{ bundle, overwrite?, skipSecrets?, skipConfig? }`. Rehydrates ~/.reflectt/ on a new host. |
+| GET | `/portability/manifest` | Preview what would be exported (file list, counts, no content). |
+| GET | `/notifications/preferences` | List all agents' notification preferences. |
+| GET | `/notifications/preferences/:agent` | Get notification preferences for a specific agent. |
+| PATCH | `/notifications/preferences/:agent` | Update notification preferences (partial). Body: `{ enabled?, deliveryMethod?, priorityThreshold?, quietHours?, eventFilters?, channelSubscriptions? }`. |
+| DELETE | `/notifications/preferences/:agent` | Reset preferences to defaults. |
+| POST | `/notifications/preferences/:agent/mute` | Mute notifications. Body: `{ durationMs? }` or `{ until? }`. Default: 1 hour. |
+| POST | `/notifications/preferences/:agent/unmute` | Unmute notifications. |
+| POST | `/notifications/route` | Check if notification should be delivered.
+| GET | `/connectivity/status` | Cloud connectivity state: mode (connected/degraded/offline), failure counts, queue depth, transition history. |
+| PATCH | `/connectivity/thresholds` | Update connectivity thresholds (degradedAfterFailures, offlineAfterMs, recoveryAfterSuccesses). |
+| POST | `/connectivity/simulate-failure` | Simulate cloud failure for outage drill. Body: `{ reason?, count? }`. |
+| POST | `/connectivity/simulate-success` | Simulate cloud success for recovery testing. Body: `{ count? }`. |
+| POST | `/connectivity/reset` | Reset connectivity state to connected. |
+| GET | `/board-health/status` | Board health worker status: config, running state, tick count, recent actions, rollbackable actions. |
+| GET | `/board-health/audit-log` | Audit log of all automated board actions. Query: `?limit=N&since=timestamp&kind=auto-block-stale\|suggest-close\|digest-emitted`. |
+| POST | `/board-health/tick` | Manually trigger board health tick. Query: `?dryRun=true` for preview. |
+| POST | `/board-health/rollback/:actionId` | Rollback an automated action within the rollback window. Body: `{ by? }`. |
+| PATCH | `/board-health/config` | Update worker config at runtime. Fields: enabled, intervalMs, staleDoingThresholdMin, suggestCloseThresholdMin, rollbackWindowMs, digestIntervalMs, digestChannel, quietHoursStart, quietHoursEnd, dryRun, maxActionsPerTick. |
+| POST | `/board-health/prune` | Prune old audit log entries. Query: `?maxAgeDays=7`. |
+| GET | `/feed/:agent` | Since-last-seen change feed. Query: `?since=timestamp&limit=100&kinds=task_status_changed,mention&includeGlobal=true`. Returns unified timeline of task changes, comments, mentions, PRs, deploys relevant to agent. |
+| GET | `/policy` | Get unified policy config (quiet hours, idle nudge, cadence watchdog, board health, escalation thresholds). |
+| PATCH | `/policy` | Update policy config at runtime (deep-merged, persisted to ~/.reflectt/policy.json). Propagates to running workers. |
+| POST | `/policy/reset` | Reset policy to defaults + env overrides. |
+| GET | `/routing/stats` | Message routing stats: total routed, by channel/category/severity, general vs ops count. |
+| GET | `/approval-queue` | Pending tasks with confidence scores and agent suggestions. Returns `{ items[], total, highConfidenceCount, needsReviewCount }`. |
+| POST | `/approval-queue/:taskId/approve` | Approve a task. Body: `{ assignedAgent?, priorityOverride?, note?, reviewedBy }`. |
+| POST | `/approval-queue/:taskId/reject` | Reject a task. Body: `{ reason?, reviewedBy }`. |
+| POST | `/approval-queue/batch-approve` | Batch approve high-confidence tasks. Body: `{ taskIds[], reviewedBy }`. |
+| GET | `/routing-policy` | Current agent affinity maps from TEAM-ROLES.yaml. Returns `{ agents[], version, source }`. |
+| PUT | `/routing-policy` | Update agent affinity maps. Body: `{ agents[{ agentId, affinityTags[], weight, ... }], updatedBy }`. Writes to `~/.reflectt/TEAM-ROLES.yaml`. |
+| POST | `/feedback` | Submit user feedback. Body: `{ category: "bug"\|"feature"\|"general", message (10-1000 chars), email?, url?, siteToken, severity?, reporterType?, reporterAgent? }`. Rate limited 5/min/IP. |
+| GET | `/feedback` | List feedback. Query: `status=new\|triaged\|archived\|all`, `category`, `severity`, `reporterType`, `sort=date\|votes\|severity`, `order`, `limit`, `offset`. |
+| GET | `/feedback/:id` | Get single feedback record. |
+| PATCH | `/feedback/:id` | Triage/update feedback metadata. Body: `{ status?, notes?, assignedTo? }`. |
+| POST | `/feedback/:id/vote` | Upvote feedback. |
+| GET | `/triage` | List untriaged feedback queue sorted by severity/date with suggested priorities. |
+| POST | `/feedback/:id/triage` | Convert feedback into a task. Body: `{ triageAgent, priority?, assignee?, lane?, title? }`. |
+| GET | `/widget/feedback.js` | Embeddable feedback widget (Shadow DOM, self-contained). Embed: `<script src="/widget/feedback.js" data-token="..." data-theme="auto">`. |
+| GET | `/routing/log` | Recent routing decisions. Query: `?limit=50&since=timestamp&category=watchdog-alert&severity=warning`. |
+| POST | `/routing/resolve` | Dry-run route resolution. Body: `{ from, content, severity?, category?, taskId?, mentions? }`. Returns where message would go. |
+| POST | `/routing/overrides` | Create a routing override. Body: `CreateOverrideInput` with target, target_type, override config, TTL. Returns created override. |
+| GET | `/routing/overrides` | List routing overrides. Query: `?target=agent&target_type=agent|role&status=active|expired&limit=N`. |
+| GET | `/routing/overrides/:id` | Get a specific routing override by ID. |
+| GET | `/routing/overrides/active/:target` | Find the currently active override for a target. Query: `?target_type=agent|role`. |
+| POST | `/routing/overrides/tick` | Advance override lifecycle — expires stale overrides, applies TTL rules. |
+| POST | `/tasks/:id/precheck` | Precheck task transition. Body: `{ targetStatus }`. Returns required fields, auto-defaults, and a PATCH template. |
+| GET | `/health/watchdog/suppression` | Watchdog de-noise config: show all suppression rules, thresholds, and what activity types prevent re-firing. | Body: `{ agent, type, priority?, channel?, message? }`. Returns routing decision + reason. |
+| GET | `/runtime/truth` | Canonical environment snapshot for operators: repo/branch/SHA, runtime host+port+PID+uptime, deploy drift, cloud registration/heartbeat, and `REFLECTT_HOME` path. |
+
+## Reflections
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/reflections` | Create a structured reflection. Body: `{ pain, impact, evidence[] (array, min 1), went_well, suspected_why, proposed_fix, confidence (0-10), role_type, author }`. Optional: `severity` (low\|medium\|high\|critical), `task_id`, `tags[]`, `team_id`, `metadata {}`. Returns 400 with field-level errors on validation failure. |
+| GET | `/reflections` | List reflections. Query: `author`, `role_type`, `severity`, `task_id`, `team_id`, `since`, `before`, `limit` (max 200), `offset`. |
+| GET | `/reflections/:id` | Get single reflection by ID. |
+| GET | `/reflections/stats` | Aggregate stats: total count, by role_type, by severity, average confidence. |
+| GET | `/reflections/sla` | Reflection SLA status per agent: last reflection time, overdue hours, tasks done since last reflection. |
+| POST | `/reflections/nudge/tick` | Manually trigger reflection nudge cycle (post-task + idle checks). |
+| GET | `/reflections/tracking/:agent` | Debug endpoint: reflection tracking state for an agent. Returns tracking row, latest actual reflection, staleness flag, gate status (`gate_would_block`), and whether reconciliation is available. |
+| GET | `/reflections/schema` | Machine-readable field reference (required/optional fields, enums, ranges). |
+
+## Insights (Clustering Engine)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/insights/ingest` | Ingest a reflection into clustering. Body: `{ reflection_id }`. Cluster key auto-derived from reflection tags/content. Promotion gate: 2 independent reflections (distinct authors) OR severity high/critical. 24h cooldown after promotion. |
+| GET | `/insights` | List insights. Supports `compact=true` (slim: id/title/score/priority/status/task_id/independent_count). Query: `status` (candidate\|promoted\|pending_triage\|task_created\|cooldown\|closed), `priority` (P0-P3), `workflow_stage`, `failure_family`, `impacted_unit`, `limit`, `offset`. Sorted by score desc. |
+| GET | `/insights/bridge/stats` | Insight→Task bridge stats: auto-created count, triaged count, duplicates skipped, errors. |
+| GET | `/insights/bridge/config` | Current bridge config including ownership guardrail settings. |
+| PATCH | `/insights/bridge/config` | Update bridge config. Body: partial config object (e.g. `{ ownershipGuardrail: { enabled: false } }`). |
+| GET | `/insights/:id/assignment-preview` | Dry-run ownership guardrail for an insight. Returns `{ decision: { assignee, reviewer, reason, guardrailApplied, soleAuthorFallback, candidatesConsidered, insightAuthors } }`. Query: `team_id`. |
+| GET | `/insights/triage` | List insights in `pending_triage` status (medium/low severity awaiting review). Query: `limit`. |
+| POST | `/insights/:id/triage` | Triage a pending insight. Body: `{ action: "approve"\|"dismiss", assignee? (required for approve), reviewer?, rationale?, priority?, triaged_by? }`. Approve creates a linked task; dismiss closes the insight. Records audit decision with reviewer + rationale. |
+| GET | `/insights/triage/audit` | Triage decision audit trail (all insights). Returns timestamped decisions with reviewer, rationale, action, outcome. Query: `limit`. |
+| GET | `/insights/:id/triage/audit` | Triage audit trail for a specific insight. Returns full lifecycle: entry → decision → outcome. |
+| GET | `/insights/:id` | Get single insight by ID. |
+| PATCH | `/insights/:id` | **Admin-only** insight mutation (hygiene tooling). **Disabled by default.** Enable with `REFLECTT_ENABLE_INSIGHT_MUTATION_API=true`. Localhost-only. Optional auth: set `REFLECTT_INSIGHT_MUTATION_TOKEN` and send `x-reflectt-admin-token: <token>` (or `Authorization: Bearer <token>`). Body: `{ actor, reason, status?, cluster_key?, metadata?: { notes?, cluster_key_override? } }`. Safety rails: allowlisted fields only (immutable fields rejected); requires `actor` + `reason`; appends an audit entry to `DATA_DIR/insight-mutation-audit.jsonl` (override path via `REFLECTT_INSIGHT_MUTATION_AUDIT_FILE`). |
+| GET | `/insights/stats` | Aggregate stats: by status, priority, failure family. |
+| POST | `/insights/tick-cooldowns` | Advance cooldown state machine: promoted past deadline → cooldown, expired cooldown → archived. |
+| POST | `/insights/:id/promote` | Promote insight to board task. Body: `{ contract: { owner, reviewer, eta, acceptance_check, artifact_proof_requirement, next_checkpoint_eta }, promoted_by }`. Optional: `title`, `description`, `priority`, `team_id`. Returns task_id + audit entry. |
+| GET | `/insights/:id/audit` | Promotion audit trail for an insight. |
+| GET | `/insights/promotions` | List all promotion audit entries. Query: `limit`. |
+| GET | `/insights/recurring/candidates` | List recurring task candidates from insights with persistent patterns. Auto-suggests owner/lane per failure family. Template-first (no auto task spam). |
+| GET | `/insights/top` | Top pain clusters by frequency within a time window. Query: `window` (e.g. `7d`, `24h`, `2w`; default `7d`), `limit` (1-50, default 10). Returns `{ clusters: [{ cluster_key, count, avg_score, last_seen_at, linked_task_ids }], window, since, limit }`. |
+| GET | `/loop/summary` | Supports `compact=true` (strips evidence_refs, slim linked_task). Top signals from the reflection→insight→task loop. Returns insights ranked by score, each with linked task details and evidence status. Query: `limit` (1-100, default 20), `min_score` (minimum score threshold, default 0), `exclude_addressed=1` (skip insights in cooldown/closed status or whose linked task is done/validating). Response: `{ success, entries[], total, filters }`. Each entry: `insight_id`, `title`, `score`, `priority`, `status`, `workflow_stage`, `failure_family`, `impacted_unit`, `independent_count`, `authors[]`, `evidence_count`, `evidence_refs[]`, `linked_task { id, title, status, assignee }`, `addressed`, `created_at`, `updated_at`. |
+
+### Example: `/insights/top`
+
+```bash
+curl "http://localhost:4445/insights/top?window=7d&limit=10"
+```
+
+```json
+{
+  "clusters": [
+    {
+      "cluster_key": "runtime::crash::api-server",
+      "count": 5,
+      "avg_score": 7.6,
+      "last_seen_at": 1771987260456,
+      "linked_task_ids": ["task-abc123", "task-def456"]
+    }
+  ],
+  "window": "7d",
+  "since": 1771382460456,
+  "limit": 10
+}
+```
+
+## Scoring Engine Configuration
+
+The insight scoring engine uses the following parameters (defined in `src/insights.ts`):
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `PROMOTION_THRESHOLD` | `2` | Minimum independent reflections (distinct authors) required for automatic promotion. Severity high/critical bypasses this gate. |
+| `COOLDOWN_MS` | `86400000` (24h) | Cooldown period after promotion before the insight can be re-promoted. |
+| `HYSTERESIS_BUFFER` | `0.3` | Score buffer zone around priority thresholds to prevent flapping. A score must exceed `threshold + buffer` to upgrade priority, or drop below `threshold - buffer` to downgrade. If within the buffer zone, previous priority is retained. |
+| `SCORING_ENGINE_VERSION` | `1.1.0` | Semver tag included in all scoring output for audit lineage. |
+
+### Priority thresholds (with hysteresis)
+
+| Priority | Score threshold | Upgrade requires | Downgrade requires |
+|----------|----------------|------------------|--------------------|
+| P0 | ≥ 9 | score ≥ 9.3 | score < 8.7 |
+| P1 | ≥ 7 | score ≥ 7.3 | score < 6.7 |
+| P2 | ≥ 4 | score ≥ 4.3 | score < 3.7 |
+| P3 | < 4 | — | — |
+
+### Audit fields in scoring output
+
+Every scored insight includes these audit fields:
+
+- **`dedupe_cluster_id`** — Cluster key for deduplication across reflections
+- **`promotion_band`** — Current priority band (P0–P3) after hysteresis
+- **`decision_trace`** — Top contributing factors to the score (severity, author count, recency, etc.)
+- **`version`** — Scoring engine version for reproducibility
+- **`hysteresis_applied`** — Whether the buffer zone retained a previous priority
+
+## Lineage Timeline (Debug/Audit)
+
+Traces the full reflection → insight → task chain for debugging and audit. Each insight forms a chain; anomalies (missing links, stale promotions) are flagged automatically.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/lineage` | List lineage entries (insight-centric chains). Each entry includes linked reflection, insight, task, promotion audit, timeline events, and anomaly flags. Query: `status` (insight status filter), `team_id`, `role_type`, `author`, `has_anomaly` (true\|false), `limit` (default 50, max 200), `offset`. Sorted by most recently updated. |
+| GET | `/lineage/:id` | Get lineage chain by insight ID, reflection ID, or task ID. Resolves any ID type to its full chain. Returns 404 if no chain found. |
+| GET | `/lineage/stats` | Lineage statistics: total chains, chains with tasks, chains with anomalies, anomaly type breakdown. |
+
+**Anomaly types:** `missing_insight` (reflection not clustered), `missing_task` (task_id points to deleted task), `orphaned_insight` (insight with no reflections), `stale_promotion` (promoted >48h with no task), `missing_reflection` (reflection ID in insight but not in DB).
+
+**Timeline events:** `reflection_created`, `insight_created`, `insight_promoted`, `task_created` — each with timestamp and actor.
+
+## Intake Pipeline
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/intake` | Process a single reflection through the full intake pipeline (validate → create reflection → cluster into insight → auto-promote if gate met). Body: `{ reflection: { pain, impact, evidence[], went_well, suspected_why, proposed_fix, confidence, role_type, author }, auto_promote?: boolean, promotion_contract?: { owner, reviewer, eta, acceptance_checks[], artifact_proof_requirement, next_checkpoint_eta } }`. Returns pipeline result with reflection, insight, and optional promotion outcome. |
+| POST | `/intake/batch` | Batch process multiple reflections through the intake pipeline. Body: `{ items: [{ reflection: {...}, auto_promote?: boolean, promotion_contract?: {...} }, ...] }`. Returns per-item results with summary counts (processed, promoted, errors). |
+| GET | `/intake/stats` | Pipeline statistics: total processed, auto-promoted count, error count, last run timestamp. |
+| POST | `/intake/maintenance` | Run pipeline maintenance: tick cooldowns, clean stale state, advance insight state machine. Returns maintenance summary. |
+
+## Continuity Loop
+
+Autonomous work-continuity system. Monitors agent queue floors and auto-replenishes by promoting qualified insights into tasks. Falls back to reflection nudges when no promotable insights exist.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/continuity/stats` | Loop statistics: cycles run, insights promoted, reflection nudges fired, no-candidate cycles, last run timestamp. |
+| GET | `/continuity/audit` | Persistent audit trail of all continuity actions. Query: `agent`, `limit`, `since` (epoch ms). Returns timestamped actions with kind, detail, linked insight/task IDs. |
+| POST | `/continuity/tick` | Manually trigger one continuity cycle. Returns actions taken, agents checked, and replenishment count. Normally runs automatically via board health worker. |
+
+### Shipped Heartbeat
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/shipped-heartbeat/stats` | Shipped-artifact heartbeat stats: messages sent, errors, last heartbeat timestamp. |
+
+## Files
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/files` | Upload a file (multipart/form-data). Fields: `file` (required), `uploadedBy`, `tags` (JSON array). Returns `{ success, file }`. 50MB limit. |
+| GET | `/files/:id` | Download file bytes with correct Content-Type. Images served inline, others as attachment. |
+| GET | `/files/:id/meta` | File metadata only (no bytes). Returns `{ success, file }`. |
+| GET | `/files` | List files. Query: `uploadedBy`, `tag`, `limit` (default 50), `offset`. Returns `{ files[], total }`. |
+| DELETE | `/files/:id` | Delete file (disk + metadata). Returns `{ success }`. |
+
+## Team
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/team/manifest` | Team charter manifest from `~/.reflectt/TEAM.md`. Returns parsed sections, version hash, update timestamp, and raw markdown. Returns `404` if TEAM.md is missing with creation hint. |
+| POST | `/pause` | Pause an agent or team. Body: `{ target: "team"|"agent-name", durationMinutes?, reason?, pausedBy? }`. Auto-resumes when duration expires. |
+| DELETE | `/pause` | Resume (unpause) an agent or team. Query: `target=team|agent-name`. |
+| GET | `/pause/status` | Current pause status. Query: `agent` (optional). Returns paused flag, remaining time, reason. |
+| POST | `/polls` | Create a poll. Body: `{ question, options[], createdBy, expiresInMinutes?, anonymous? }`. Returns `{ poll }`. |
+| GET | `/polls` | List polls. Query: `status=active|closed|all`, `limit`. Returns `{ polls[], count }`. |
+| GET | `/polls/:id` | Get poll with results. Returns `{ poll }` with vote counts and voter lists. |
+| POST | `/polls/:id/vote` | Cast a vote. Body: `{ voter, choice }` (choice is 0-indexed). Allows changing vote. |
+| POST | `/polls/:id/close` | Close a poll manually. |
+| GET | `/team/roles` | TEAM-ROLES routing matrix — agent skills, affinity scores, WIP caps |
+| GET | `/policy/intensity` | Current intensity preset + limits (wipLimit, maxPullsPerHour, batchIntervalMs). |
+| PUT | `/policy/intensity` | Set intensity preset. Body: `{ preset: "low"|"normal"|"high", updatedBy? }`. Returns new state. |
+
+## Other
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/` | Root redirect — redirects to `/dashboard`. |
+| GET | `/dashboard` | HTML dashboard UI |
+| GET | `/docs` | This API reference |
+| GET | `/ui-kit` | Living design system reference page — colors, typography, spacing, buttons, links, badges, inputs, panels, tables with token names. |
+| GET | `/artifacts/view` | In-browser artifact viewer (safe). Query: `path` (repo-relative). Guardrails: repo-root only, extension allowlist (`.md .txt .json .log .yml .yaml`), max 400KB. If `path` contains an embedded `http(s)://...`, redirects to that URL. |
+| GET | `/shared/list` | List files in shared workspace directory. Query: `path` (default `process/`), `limit` (default 200, max 500). Security: prefix allowlist (`process/`), traversal protection, extension filter. |
+| GET | `/shared/read` | Read file from shared workspace. Query: `path` (required), `include=preview` (truncated), `maxChars` (default 2000). Security: same as `/shared/list` + size cap (400KB). |
+| GET | `/shared/view` | HTML viewer for shared workspace artifacts. Query: `path` (required). Dark-themed in-browser view. |
+| GET | `/openclaw/status` | OpenClaw connection status |
+| GET | `/secrets` | List all secrets (metadata only — no plaintext values) |
+| POST | `/secrets` | Create/update a secret (encrypts locally, stores ciphertext) |
+| GET | `/secrets/export` | Export all secrets as encrypted bundle for portability |
+| GET | `/secrets/audit` | Secret access audit log |
+| GET | `/secrets/:name` | Decrypt and return a secret value (audit logged) |
+| DELETE | `/secrets/:name` | Revoke/delete a secret |
+| POST | `/secrets/:name/rotate` | Rotate a secret's encryption key |
+| GET | `/analytics/models` | Model performance analytics — tasks per model, avg cycle time, review pass rate |
+| GET | `/analytics/agents` | Per-agent analytics — model used, performance stats |
+
+---
+
+*Manually curated from source routes. Base: http://localhost:4445*
+| GET | `/telemetry` | Full telemetry snapshot (config + metrics) |
+| GET | `/telemetry/config` | Telemetry configuration (safe — no secrets) |
+| POST | `/api/telemetry/ingest` | Cloud telemetry ingest endpoint (receives snapshots from hosts) |
+| POST | `/canvas/render` | Push content to a canvas slot (Screen Contract v0 validated) |
+| GET | `/canvas/slots` | Current active (non-stale) slots |
+| GET | `/canvas/slots/all` | All slots including stale (debug) |
+| GET | `/canvas/history` | Recent render history (?slot=&limit=) |
+| GET | `/canvas/rejections` | Recent contract validation rejections |
+| GET | `/canvas/stream` | SSE stream of canvas render events |
+| GET | `/execution-health` | Execution sweeper status: validating queue violations, SLA breaches, escalation tracking. |
+| POST | `/pr-event` | PR state webhook. Body: `{ taskId, prState: "merged"|"closed", prUrl? }`. Auto-updates task artifacts on merge, auto-blocks on close. |
+| GET | `/pr-automerge/status` | PR auto-merge attempt log: recent merge/close attempts with summary counts (attempted, success, failed, skipped, auto-close, close-gate-fail). |
+| GET | `/drift-report` | Task/PR drift report: tasks with merged PRs still in validating, orphan PRs, state mismatches. |
+| POST | `/activation/event` | Record activation funnel event. Body: `{ type, userId, metadata? }`. Events: signup_completed, host_preflight_passed, host_preflight_failed, workspace_ready, first_task_started, first_task_completed, first_team_message_sent, day2_return_action. |
+| GET | `/activation/funnel` | Get funnel state. Query: `?userId=...` for single user, no params for aggregate summary. |
+| GET | `/activation/dashboard` | Full onboarding telemetry dashboard: conversion funnel, failure distribution, weekly trends. Query: `?weeks=12`. |
+| GET | `/activation/funnel/conversions` | Step-by-step conversion rates with per-step reach count, conversion rate, and median step timing. |
+| GET | `/activation/funnel/failures` | Failure-reason distribution per step. Shows where users drop off and why (from event metadata). |
+| GET | `/activation/funnel/weekly` | Weekly trend snapshots for planning. Query: `?weeks=12`. Exportable JSON with per-week step counts, new users, completion rate. |
+| GET | `/audit/reviews` | Audit ledger for review-field mutations: actor trace, before/after diffs, timestamps. |
+| GET | `/audit/mutation-alerts` | Suspicious mutation alert status and history. |
+| GET | `/escalations` | List active escalations. |
+| GET | `/escalations/:id` | Get escalation details by ID. |
+| GET | `/feedback/:feedbackId/escalation` | Get escalation linked to feedback item. |
+| GET | `/feedback/:id/sla` | SLA status for a feedback/support item. |
+| GET | `/support/tiers` | Support tier SLA policy definitions. |
+| POST | `/escalations` | Create a new escalation. |
+| POST | `/escalations/:id/ack` | Acknowledge an escalation. |
+| POST | `/escalations/:id/resolve` | Resolve an escalation. |
+| POST | `/escalations/tick` | Trigger escalation timer tick (cron/manual). |
+| POST | `/feedback/:id/respond` | Respond to a feedback/support item. |
+
+## Reflection Automation
+
+Team-wide nudging and SLA tracking for reflection cadence.
+
+### Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/reflections/sla` | Reflection SLA status for all tracked agents. |
+| POST | `/reflections/nudge/tick` | Tick nudge engine: fire pending post-task and idle nudges. |
+
+### How It Works
+
+1. **Post-task nudges**: When a task moves to `done` or `blocked`, the assignee is queued for a reflection nudge (configurable delay, default 5min).
+2. **Idle nudges**: Agents who haven't submitted a reflection within their cadence interval (default: 8h for humans, 2h for agents) receive a reminder.
+3. **Never-reflected agents**: New agents are auto-seeded into tracking on first discovery. Once seeded long enough (≥ cadence interval), they receive their first nudge. Controlled by `nudgeNeverReflected` (default: true).
+4. **SLA breach**: Agents overdue beyond 1.5× their cadence interval are marked as `overdue`.
+5. **Cooldowns**: Nudges are throttled per-agent (default: 60min between nudges).
+6. **Tracking resets**: Submitting a reflection via `POST /reflections` resets the agent's tasks-done counter and last-reflection timestamp.
+7. **Agent filtering**: Test/system agents (names matching `test-*`, `proof-*`, `lane-*`, `unassigned`, `system`, `bot`) are auto-excluded from SLA reporting and nudges. Additional exclusions via `excludeAgents` config.
+8. **SLA agent discovery**: Agents are discovered from both active tasks (doing/todo/validating) AND the tracking table (agents who have reflected before). This ensures agents who go idle aren't silently dropped from SLA tracking.
+
+### SLA Statuses
+
+- `healthy`: Reflected within cadence interval
+- `due`: Past cadence interval but within breach threshold
+- `overdue`: Beyond breach threshold (1.5× cadence)
+
+### Configuration
+
+Set via `reflectionNudge` in policy config:
+
+```json
+{
+  "reflectionNudge": {
+    "enabled": true,
+    "postTaskDelayMin": 5,
+    "idleReflectionHours": 8,
+    "cooldownMin": 60,
+    "agents": [],
+    "channel": "general",
+    "roleCadenceHours": { "link": 4, "sage": 8 },
+    "excludeAgents": [],
+    "nudgeNeverReflected": true
+  }
+}
+```
+
+## Usage Tracking + Cost Guardrails
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/usage/report` | Record model usage event. Body: `{ agent, model, provider?, input_tokens, output_tokens, estimated_cost_usd?, category?, task_id?, team_id? }`. Auto-estimates cost if not provided. |
+| POST | `/usage/report/batch` | Record batch of usage events. Body: `{ events: [...] }`. |
+| GET | `/usage/summary` | Aggregated usage totals. Query: `since`, `until`, `agent`, `team_id`. |
+| GET | `/usage/by-agent` | Per-agent cost breakdown. Query: `since`, `until`. |
+| GET | `/usage/by-model` | Per-model cost breakdown. Query: `since`, `until`. |
+| GET | `/usage/by-task` | Per-task cost attribution. Query: `since`, `until`, `limit`. |
+| GET | `/usage/estimate` | Dry-run cost estimate (no storage). Query: `model`, `input_tokens`, `output_tokens`. |
+| GET | `/usage/caps` | List active spend caps with current utilization status. |
+| POST | `/usage/caps` | Create spend cap. Body: `{ scope: "global"\|"agent"\|"team", scope_id?, period: "daily"\|"weekly"\|"monthly", limit_usd, action: "warn"\|"throttle"\|"block" }`. |
+| DELETE | `/usage/caps/:id` | Delete a spend cap. |
+| GET | `/usage/routing-suggestions` | Smart routing savings suggestions (which low-stakes categories could use cheaper models). Query: `since`. |
+
+### Model Pricing (built-in estimates, per 1M tokens)
+| Model | Input | Output |
+|-------|-------|--------|
+| claude-opus-4-6 | $15.00 | $75.00 |
+| claude-sonnet-4-6 | $3.00 | $15.00 |
+| gpt-5.3 / gpt-5.3-codex | $2.00 | $8.00 |
+| gpt-4o-mini | $0.15 | $0.60 |
+
+### Spend Cap Events
+- `usage:cap_warning` — emitted when spend reaches 80% of cap limit
+- `usage:cap_breached` — emitted when spend exceeds cap limit
+
+## Insight Reconciliation (Orphan Detection)
+
+Ensures promoted insights always have task linkage. Detects and fixes orphaned insights.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/insights/orphans` | List promoted/task_created insights with no `task_id`. Returns `orphans[]` with id, title, status, score, priority, authors. |
+| POST | `/insights/reconcile` | Scan orphaned insights and create tasks for each. Query: `dry_run=true` for preview. Returns scanned/created/skipped counts + details per insight. |
+
+## Alert-Integrity Guard (P0-2)
+
+Preflight reconciliation for system alerts — verifies live state before publishing to prevent stale/false-positive alerts.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/chat/alert-integrity` | Current guard snapshot: canary mode, total checked/rejected/passed, false-positive rate, rejection breakdown. |
+| GET | `/chat/alert-integrity/audit` | Rejection audit log. Query: `limit` (default 50), `since` (timestamp). Returns rejected alerts with reason + state diff. |
+| GET | `/chat/alert-integrity/config` | Read current guard config (enabled, canaryMode, reconcile checks, staleness thresholds). |
+| PATCH | `/chat/alert-integrity/config` | Update guard config. Body: partial config object. |
+| POST | `/chat/alert-integrity/activate` | Exit canary mode — start rejecting stale alerts (instead of log-only). |
+| GET | `/chat/alert-integrity/rollback` | Rollback evaluation metrics: false-positive rate, critical misses, whether rollback trigger is tripped. |
+
+## Routing Approvals
+
+Explicit routing approval queue. Tasks enter ONLY when marked with `metadata.routing_approval=true` by the routing system. This is NOT derived from "all todo tasks."
+
+**Routing approvals** (assignment suggestions) are distinct from **reviewer approvals** (code review sign-off).
+
+### Metadata Contract
+
+- `metadata.routing_approval: boolean` — marks task as needing routing review
+- `metadata.routing_suggestion: { suggestedAssignee, confidence, reason, alternatives? }` — the routing system's suggestion
+- `metadata.routing_decision: { approvedBy/rejectedBy, decision, assignee?, note? }` — auditable decision record
+- `metadata.routing_rejected: boolean` — suppression flag (prevents reappearance after rejection)
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/routing/approvals` | List all tasks with `routing_approval=true`. Returns suggestion details + confidence. |
+| POST | `/routing/approvals/:taskId/decide` | Approve or reject a routing suggestion. Body: `{ decision: 'approve'\|'reject', actor, assignee?, note? }`. Approve sets assignee + clears queue. Reject suppresses reappearance. |
+| POST | `/routing/approvals/suggest` | Submit a routing suggestion for a task. Body: `{ taskId, suggestedAssignee, confidence, reason, alternatives? }`. Sets `routing_approval=true`. |
+
+## Artifact Resolver (path normalization + GitHub fallback)
+
+Artifact paths are normalized on PATCH to `validating` to prevent workspace-dependent paths from blocking reviewer access.
+
+### Path Normalization
+- Absolute paths with known workspace prefixes (e.g., `/Users/.../workspace-link/process/...`) are stripped to repo-relative (`process/...`)
+- Relative workspace prefixes (`workspace-shared/`, `shared/`) are stripped
+- Unknown absolute paths (e.g., `/etc/passwd`) are rejected
+- Paths with `..` or null bytes are rejected
+- Normalization metadata stamped: `metadata.artifact_normalization.{ normalized, warnings, rejected, normalizedAt }`
+
+### GitHub Blob Fallback
+- When `/tasks/:id/artifacts` can't find a local file but PR URL + commit SHA are available
+- Builds `https://github.com/{owner/repo}/blob/{sha}/{path}` as fallback
+- Returns `source: 'github-fallback'` + `rawUrl` for direct download
+- Only applies to `process/` prefixed paths
+
+### Artifact Path Guidance (for submitters)
+- Always use repo-relative paths: `process/task-{id}-qa-bundle.md`
+- Never use absolute paths or workspace-prefixed paths
+- The normalizer will auto-fix common workspace prefixes but rejection is possible for unknown patterns
+
+## Calendar
+
+Shared time-awareness system for agents and humans. Supports availability blocks and (coming soon) full calendar events with iCal compatibility.
+
+### Block Types
+- `busy` — occupied but interruptible for normal+ urgency
+- `focus` — deep work, only interruptible for high urgency
+- `available` — explicitly free
+- `ooo` — out of office, only interruptible for high urgency
+
+### Recurring Blocks
+Recurring blocks use day-of-week scheduling with minutes-from-midnight for start/end times. Days: `sun,mon,tue,wed,thu,fri,sat`. Timezone-aware evaluation.
+
+### Ping Gating Rules
+| Urgency | Free | Busy | Focus | OOO |
+|---------|------|------|-------|-----|
+| high    | ✅   | ✅   | ✅    | ✅  |
+| normal  | ✅   | ✅   | ❌    | ❌  |
+| low     | ✅   | ❌   | ❌    | ❌  |
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/calendar/blocks` | Create a calendar block. Body: `{ agent, type, title, start, end, recurring?, timezone? }`. For one-off: start/end are epoch ms. For recurring: start/end are minutes from midnight (0-1439), recurring is comma-separated days. |
+| GET | `/calendar/blocks` | List blocks. Query: `agent`, `type`, `from` (epoch ms), `to` (epoch ms). |
+| GET | `/calendar/blocks/:id` | Get a single block by ID. |
+| PATCH | `/calendar/blocks/:id` | Update a block. Body: partial block fields. |
+| DELETE | `/calendar/blocks/:id` | Delete a block. |
+| GET | `/calendar/busy` | Check if agent is busy. Query: `agent` (required). Returns busy/free status + current block details. |
+| GET | `/calendar/availability` | Team-wide availability snapshot. Returns all agents with calendar blocks and their current status. |
+| GET | `/calendar/should-ping` | Ping gating check. Query: `agent` (required), `urgency` (low/normal/high, default: normal). Returns should_ping boolean + reason + delay_until. |
+
+## Calendar Events
+
+Full calendar event system with iCal-compatible fields, attendees, RSVP, recurrence (RRULE), and reminders.
+
+### Event Fields (iCal-aligned)
+- `summary` — event title (SUMMARY)
+- `description` — event description (DESCRIPTION)
+- `dtstart`, `dtend` — epoch ms start/end (DTSTART, DTEND)
+- `timezone` — IANA timezone (VTIMEZONE)
+- `rrule` — RFC 5545 recurrence rule (e.g., `FREQ=WEEKLY;BYDAY=MO,WE,FR`)
+- `organizer` — creator (agent or human name)
+- `attendees[]` — participants with RSVP status (`accepted`, `declined`, `tentative`, `needs-action`)
+- `location` — text or URL
+- `categories[]` — tags
+- `reminders[]` — `{ minutes_before, method: 'chat'|'inbox' }`
+- `status` — `confirmed`, `tentative`, `cancelled`
+- `uid` — RFC 5545 UID for iCal interop
+
+### Supported RRULE frequencies
+`DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY` with `INTERVAL`, `BYDAY`, `BYMONTHDAY`, `BYMONTH`, `COUNT`, `UNTIL`.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/calendar/events` | Create event. Body: `{ summary, dtstart, dtend, organizer, description?, timezone?, rrule?, attendees?, location?, categories?, reminders?, status? }` |
+| GET | `/calendar/events` | List events. Query: `organizer`, `attendee`, `status`, `from`, `to` (epoch ms), `categories` (comma-separated), `limit`. |
+| GET | `/calendar/events/:id` | Get single event. |
+| PATCH | `/calendar/events/:id` | Update event fields. |
+| DELETE | `/calendar/events/:id` | Delete event + associated fired reminders. |
+| POST | `/calendar/events/:id/rsvp` | RSVP to event. Body: `{ name, status }`. Adds attendee if not present. |
+| GET | `/calendar/events/:id/occurrences` | Get occurrence timestamps for recurring events. Query: `from`, `to` (epoch ms, default: next 30 days). |
+| GET | `/calendar/reminders/pending` | List reminders that should fire now (for reminder engine polling). |
+| GET | `/calendar/events/current` | Check if agent is in an event right now. Query: `agent` (required). |
+| GET | `/calendar/events/next` | Get agent's next upcoming event. Query: `agent` (required). |
+
+## Calendar Reminder Engine
+
+Polls for pending reminders every 30 seconds and delivers them via chat messages. Reminders are deduplicated across restarts via SQLite.
+
+Reminder delivery: fires to `#calendar-reminders` channel AND `#general` with @mentions for recipients.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/calendar/reminders/stats` | Reminder engine stats: running, poll_interval_ms, last_poll_at, total_polls, total_delivered. |
+| GET | `/calendar/next-free` | When is agent next free? Query: `agent` (required). Returns free_now boolean + free_at timestamp. Checks both blocks and events. |
+
+## Calendar iCal Import/Export (RFC 5545)
+
+Standard iCalendar format support. Events can be imported from email invites, Google Calendar, Outlook, etc.
+
+### Export
+Exports produce RFC 5545 compliant `.ics` files with VEVENT, ATTENDEE (with PARTSTAT), VALARM (reminders), RRULE, CATEGORIES, and proper text escaping/line folding.
+
+### Import
+Import parses VEVENT components and creates/updates events. If a VEVENT has a UID matching an existing event, it's updated instead of duplicated. VALARM maps to reminders, ATTENDEE maps to attendees with PARTSTAT.
+
+### Round-trip
+Export → import preserves: summary, description, organizer, attendees, location, categories, reminders, RRULE, status.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/calendar/export.ics` | Export events as .ics file. Query: `organizer`, `attendee`, `from`, `to`. Returns `text/calendar` with Content-Disposition. |
+| GET | `/calendar/events/:id/export.ics` | Export single event as .ics file. |
+| POST | `/calendar/import` | Import events from .ics content. Body: `{ ics: string, organizer?: string }` or raw .ics string. Returns created/updated events. UID-based dedup on re-import. |
+
+## Remote Node Management
+
+Auth-gated endpoints for managing a reflectt-node instance remotely. Provide `REFLECTT_MANAGE_TOKEN` env var; authenticate via `x-manage-token` header or `Authorization: Bearer <token>`. Loopback (localhost) access is always allowed.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/manage/status` | Unified status: version, build info, health stats, uptime |
+| GET | `/manage/config` | Config introspection with secrets redacted (server config, auth token status, team files) |
+| GET | `/manage/logs` | Bounded log tail. Query: `level` (error/warn/info), `since` (epoch ms), `limit` (max 200), `format=text` for plain text |
+| POST | `/manage/restart` | Graceful restart. Works with Docker, systemd, and reflectt CLI (PID file). Returns 501 if unsupported. |
+| GET | `/manage/disk` | Data directory sizes for capacity monitoring |
+
+### Example: Check Remote Node Status
+
+```bash
+curl -s http://your-node:4445/manage/status \
+  -H 'x-manage-token: YOUR_TOKEN' | jq .
+```
+
+### Example: Tail Error Logs (Plain Text)
+
+```bash
+curl -s 'http://your-node:4445/manage/logs?level=error&limit=20&format=text' \
+  -H 'x-manage-token: YOUR_TOKEN'
+```
+
+### Example: Inspect Config (Secrets Redacted)
+
+```bash
+curl -s http://your-node:4445/manage/config \
+  -H 'x-manage-token: YOUR_TOKEN' | jq .
+```
+
+## Bootstrap: Team Composition
+
+`POST /bootstrap/team` recommends a team based on your use case. Returns agents, ready-to-create task payloads, HEARTBEAT.md snippets, and a TEAM-ROLES.yaml you can save directly.
+
+### Example: Support Team
+
+```bash
+curl -s -X POST http://127.0.0.1:4445/bootstrap/team \
+  -H 'Content-Type: application/json' \
+  -d '{"useCase": "managed node support team", "constraints": {"maxAgents": 3}}' | jq .
+```
+
+### Example: Content Launch
+
+```bash
+curl -s -X POST http://127.0.0.1:4445/bootstrap/team \
+  -H 'Content-Type: application/json' \
+  -d '{"useCase": "content and growth launch"}' | jq .
+```