Operational Copy Codes

This repo uses code-driven operational copy at service boundaries. Backend and web BFF layers return stable status, detail, and error codes, and the web app renders English through its translation seam.

Purpose

• Keep user-facing operational copy out of backend route handlers and service payloads.
• Make future translation work additive instead of requiring contract redesign.
• Prevent raw internal/provider/backend exception text from leaking into product UI.
• Keep closed-set status and error behavior explicit, testable, and searchable.

Contract Shape

Errors cross boundaries as structured codes:

{
  error: {
    code: string
    params?: Record<string, string | number | boolean>
  }
}

Normal successful payloads can also carry machine-readable status or detail fields when the UI needs to choose copy for success, progress, or recovery states.

Current operational-copy rendering seam:

• Web translation: apps/web/app/utils/operationalCopy.ts
• Web error readers: apps/web/app/utils/httpErrors.ts
• Shared auth-layer translation: packages/nuxt-auth-layer/app/utils/authHttpErrors.ts
• Shared Nuxt auth-layer BFF proxy normalization: packages/nuxt-auth-layer/server/utils/proxyErrorResponse.ts

Domain Catalog

The current code set is large enough that a flat manual list becomes noisy. Treat the catalog as grouped by domain:

• auth: access request, completion, sign-in policy, and sign-in gating flows
• connectors: connection, sync, disconnect, recovery, auth-health, and service-trigger failures
• chat: chats, chat spaces, response templates, skills, sharing, HITL, focus, and message operations
• library: library CRUD, item operations, and validation failures
• uploads: upload sessions, file upload/download, and connector-file access failures
• common: cross-domain codes such as unauthorized, forbidden, and generic request failures

Use the source catalogs as the canonical list. Avoid hand-maintaining a second exhaustive table unless it is generated from those catalogs.

How To Add Or Change Codes

1. Add or reuse a stable machine-readable code in the shared contract or API/web-facing handler.
2. Return that code from API or web BFF boundaries instead of backend-authored English.
3. Add or update the English rendering in apps/web/app/utils/operationalCopy.ts, or in packages/nuxt-auth-layer/app/utils/authHttpErrors.ts for shared auth-layer UI.
4. Update tests so they assert codes at the boundary and translated copy in UI-facing assertions.
5. Keep true content data and proper names out of this system unless the app owns the wording.

Quick Lookup

• Search the current web translation catalog: rg "^ '" apps/web/app/utils/operationalCopy.ts
• Search shared operational error schema usage: rg "operationalErrorResponseSchema|error: \\{ code" packages apps
• Search for legacy raw error strings that still need cleanup: rg "statusMessage: '|body: \\{ error: '|sendProxyErrorResponse\\(.*'[A-Z]" apps/web apps/api apps/auth

Which Files Matter

File	What it helps you answer
apps/web/app/utils/operationalCopy.ts	Current English operational-copy catalog grouped by domain
apps/web/app/utils/httpErrors.ts	How web readers resolve display-safe messages from code-bearing errors
packages/nuxt-auth-layer/app/utils/authHttpErrors.ts	How shared auth UI resolves display-safe auth messages from code-bearing errors
packages/nuxt-auth-layer/server/utils/proxyErrorResponse.ts	How shared Nuxt auth-layer and web proxy routes normalize upstream failures into structured error codes
packages/contracts/src/common/errors.ts	Shared operational error envelope contract
packages/contracts/src/auth/accessRequests.ts	Access-request detail codes and auth contract shape
packages/contracts/src/connectors/contracts.ts	Connector status, recovery, progress, and machine-readable contract fields
apps/auth/src/index.ts	Auth-side request-access, completion, and sign-in-policy code emission
apps/api/src/chats/chatRouteHandlers.ts	Chat/skills/response-template/chat-space operational error code mapping
apps/api/src/connectors/connectorRouteHandlers.ts	Connector runtime and internal-service operational error responses

Helpful External Docs

• Nuxt
• h3
• Zod