---

title: Operations and diagnostics description: Diagnose AIRI at the correct boundary, protect local data, and distinguish source-derived procedures from deployment evidence.

Operations and diagnostics

A working page, a working provider request, and a working native integration are different acceptance results. Diagnose the failed boundary before changing another subsystem.

This page contains source-derived operating guidance. It is not a service inventory or a claim that every upstream capability runs on the showcase host.

Recorded integration context

The integration owner reports Node v22.23.1 with Corepack pnpm 11.24.0 as the showcase deployment/runtime choice. The host did not switch Node versions.

The repository records different Node guidance. See setup for that distinction and provenance for the evidence labels.

Provider credentials, model inference, microphone behavior, native devices, and external bots were not exercised during wiki authoring. Deployment and browser acceptance remain separate evidence.

Diagnose the first failed boundary

flowchart TD
    Failure[Unexpected behavior] --> Shell{Does the application load?}
    Shell -->|No| Assets[Inspect build assets and browser errors]
    Shell -->|Yes| Scope{Showcase or full runtime?}
    Scope -->|Showcase| Guide[No character session implied]
    Scope -->|Full runtime| Text{Does a text request work?}
    Text -->|No| Provider[Inspect provider, model, endpoint, and credentials]
    Text -->|Yes| Feature[Isolate hearing, speech, display, or external service]
    Feature --> Evidence[Observe the actual failed operation]

Symptom	First inspection	Source owner
Provider appears selected but chat fails	Endpoint, selected model, credentials, and the real request error	Consciousness and provider stores
Chat works but no voice plays	Speech provider, model, voice, and device output	Speech store and audio pipelines
No transcription	Microphone permission, available input, provider capability, and transcription model	Hearing store
Imported model does not appear	Selected asset, renderer error, graphics support, and required files	Display-model store and renderer package
Native speech is absent	Application surface, OS, and native availability	Apple Speech provider
Integration settings exist but nothing connects	Separate process, credentials, destination, and server-channel connection	Selected integration

The Hearing source distinguishes permission, device, input, and provider failures. Those categories are more useful than treating every failure as an inference error.

A source configured flag is a configuration predicate. It is not a substitute for a request or device check.

Protect state before recovery

The provider configuration store uses localStorage. The display-model store uses localforage for imported assets. Provider configuration also has remote operations.

Do not assume that browser storage is encrypted, backed up, or identical to account-side state. Keep original assets and recovery information outside the browser.

Storage clearing can remove user data

Preserve required configuration and original assets before clearing site data. A cache-recovery action can also remove locally stored state.

The web Vite configuration documents an existing service worker as a possible cause of stale development behavior. A previous production or preview registration can survive later development sessions.

Before destructive recovery, inspect the actual origin, loaded assets, and service-worker registration. The showcase and a separate upstream development origin do not share one universal browser state.

Keep service checks separate

The local backend Compose file defines readiness checks for API, Auth, PostgreSQL, and Redis. A container start does not establish service readiness.

The backend guide gives the API ownership of shared migrations. It does not give that responsibility to Auth. The local edge rejects the API’s internal routes.

The server channel is a separate runtime. Its connection result does not establish hosted account, billing, or database readiness. See services-and-integrations.

Maintain the source guide

1. Record the new upstream revision before changing a source-based claim.
2. Read changed manifests and the owning implementation.
3. Update affected pages and their immutable source links together.
4. Preserve the distinction between source support and runtime evidence.
5. Record the exact surface and operation for each acceptance result.

The root build:web command is a source build procedure. A successful build alone does not prove keyboard behavior, mobile layout, audio, or provider access.

Source context

• packages/stage-ui/src/stores/modules/hearing.ts, lines 61–86: transcription failure categories.
• packages/stage-ui/src/stores/providers/config.ts, lines 45–98: local persistence and remote operations.
• packages/stage-ui/src/stores/display-models.ts, lines 69–87 and 154–164: local asset persistence.
• apps/stage-web/vite.config.ts, lines 173–189: service-worker development caveat.
• server/docker-compose.yaml: service readiness checks.
• server/README.md, lines 56–65: internal routes, migration ownership, and readiness.

Navigation: index · setup · workflows · provenance