Troubleshooting

The app does not start

Confirm Bun 1.3.14 is active, run bun install, and start with bun run dev. The dev server uses a fixed port. Stop the conflicting process if port 5189 is already in use instead of documenting a silently selected fallback.

A surface shows fallback or empty data

Fallback data is expected before local aggregation. Run bun run scheduler:agents:run for host and agent data, or the scoped extension job for Trend Finder. Check the matching status command for a visible error or a not-yet-run state.

An agent cannot execute

Read the agent page’s readiness and recovery message. Confirm the local tool, selected model, and required provider are available. A public-demo readiness card is illustrative and cannot execute.

Voice does not start

Voice needs the reviewed local broker path and an available provider configuration. Start from the Intelligence portal so the UI can report whether the broker was already running, started successfully, or needs recovery.

OpenAI account runtime is not ready

bun run auth:openai -- status
bun run codex:smoke -- --model gpt-5.6-sol --json

Use reauth when the stored grant is rejected. If authentication succeeds but the model is rejected, choose a model available to that account. A successful smoke still does not prove that Dream or Trend Finder completed; run the consumer and inspect its own status.

Knowledge Graph cannot ingest

The reviewed seed graph should render without Graphify. Ingest is a separate local write and requires the optional dependency plus local readiness.

bash scripts/setup-graphify-brain.sh
bun run graph:policy:check

If removal succeeds, remember that it deletes graph artifacts, not the source project.

AI Rogue has no audio

Interact with the Play surface once so the browser can unlock Web Audio. Check mute, music volume, and effect volume in Settings. If Web Audio is unavailable or an asset cannot decode, gameplay intentionally continues in silence.

Documentation validation fails

Run the narrow gates from the repository root:

bun run docs:scan
bun run docs:check
bun run docs:build

The output names the affected public file and failed boundary. Do not bypass a privacy, frontmatter, symlink, link, or build failure to publish.

The public site has a missing route

Use search or Start Here. Maintainers should add a reviewed static redirect only for a useful legacy route; do not add a catch-all fallback that turns missing assets into HTML responses.