Error Catalog

Overview

Remote error catalog (Cloudflare KV, edited via /errors/admin) that turns raw task failures into user-friendly messages, spotlight banners, and a dynamic help page — without shipping a new box version.

How it works

Matching runs client-side over the error cause chain, prioritizing the match closest to the root cause (matchOn OR substring logic — see docs/error-catalog-matching.md in ip-magicbox repo).

Key files

• src/protocol/refsErrors.ts — catalog load/cache/refresh, resolveError(), initErrorCatalog()
• src/components/TasksPanel/TaskView.tsx — inline user message, details toggle, help link
• src/components/TasksPanel/SpotlightBanner.tsx — consolidated account/config banner
• microservices/refs-domain/refs-worker.js — /errors/catalog, /errors/admin, /errors/help, /api-docs

Technical decisions

• Client-side matching keeps the box responsive when offline; DEFAULT_CATALOG covers boot without network.
• Catalog refresh re-resolves persisted failed tasks so message tweaks apply retroactively.
• REFS_BASE_URL built from env.refs_domain (same convention as other refs URLs).

Known issues

• Dev-only __mockError / __clearMockErrors helpers — disabled in production builds.

Next steps

• Expand catalog entries as new production error patterns are triaged