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.

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.