> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/runbooks/incident-response.md).

# Incident Response

## Severity Levels

| Level | Description                            | Response Time        |
| ----- | -------------------------------------- | -------------------- |
| P0    | App cannot start or build              | Immediate            |
| P1    | Core dashboard or report output broken | Same day             |
| P2    | Non-core route, script, or doc problem | Next working session |
| P3    | Cosmetic or copy issue                 | Backlog              |

## Common Incidents

### Dev Server Does Not Start

**Symptoms:** `bun run dev` exits or reports port `5189` is unavailable.

**Resolution:**

1. Stop the process using port `5189`.
2. Run `bun run dev` again.
3. If the error persists, inspect `vite.config.ts` for dev server settings.

### Fallback Data Missing

**Symptoms:** `/__live-data` returns an error and the dashboard fails to render data.

**Resolution:**

1. Check that `src/data/live-data.example.json` exists.
2. Run `bun run seed:data`.
3. Restart `bun run dev`.

### Aggregator Fails

**Symptoms:** `bun run aggregate` or refresh from the UI fails.

**Resolution:**

1. Run `bun run aggregate` directly to see terminal output.
2. Inspect `logs/aggregate.latest.jsonl` for collector lifecycle, runtime readiness, sanitized provider errors, validation issues, and fallback reasons.
3. Confirm optional API keys are valid only if the failing source needs them.
4. Delete `src/data/live-data.json` and run `bun run seed:data` to return to fallback data.

### Scheduler Status Is Blocked Or Stale

**Symptoms:** `bun run scheduler:status` reports `blocked`, `stale-lock`, or `unreadable-state` for the aggregate job.

**Resolution:**

1. Confirm no local aggregate timer or manual `bun run scheduler:run` process is still running.
2. Run `bun run scheduler:status` to capture the safe status labels.
3. Run `bun run scheduler:run` once to allow normal stale-lock recovery.
4. If state is still unreadable, stop any local timer, then remove only the private AI OS scheduler state, lock, and log files from the local scheduler root.

Do not paste scheduler state files, scheduler logs, auth JSON, `.env.local`, or raw aggregate logs into issues.

### Dream Review Skips Or Fails

**Symptoms:** The Home or Settings Dream Review button reports skipped or failed, or `bun run scheduler:dream:status` reports `skipped`, `failed`, `timeout`, or `unreadable-state`.

**Resolution:**

1. Run `bun run scheduler:dream:status` and use the safe status labels first.
2. For CLI runs, verify activation is explicit with `AI_OS_DREAM_ENABLED=true bun run scheduler:dream:run` unless the scheduler process already has that env.
3. Check aggregate readiness with `bun run scheduler:status` or `bun run aggregate`.
4. Check provider readiness using script-only env names such as `AI_OS_AI_RUNTIME_*`, `AI_OS_OPENAI_ACCOUNT_AUTH_PATH`, and `OPENAI_API_KEY`.
5. If a local timer is enabled, disable it before deleting private Dream or scheduler state.

Do not share Dream output files, continuity state, runtime state, provider responses, prompts, transcripts, account-auth JSON, or scheduler logs.

### Trend Finder Backtest Or Backhistory Replay Fails

**Symptoms:** `bun run trend-finder:backtest` or `bun run trend-finder:replay-backhistory` exits non-zero.

**Resolution:**

1. Run the command with `--help` and confirm the flags match the script.
2. For `trend-finder:backtest`, use only reviewed historical sources such as `producthunt-ai-launches`.
3. For `trend-finder:replay-backhistory`, confirm the private `.cache/extensions/trend-finder/backhistory/` input files exist without opening or sharing their contents.
4. Keep output under `.cache/extensions/trend-finder/backtests/`.
5. Use `--publish-aggregate` only when a bounded browser summary is intentionally needed.

### Build Fails

**Symptoms:** `bun run build` exits non-zero.

**Resolution:**

1. Run `bun run lint`.
2. Fix TypeScript, lint, or formatting errors reported by the build.
3. Run `bun run build` again.

### Secret Scan Blocks Commit

**Symptoms:** `.githooks/pre-commit` blocks a commit with an API key warning.

**Resolution:**

1. Remove the real key from staged files.
2. Use `.env.local` for local values.
3. Use short placeholders such as `<key>` in docs.
4. Stage the cleaned files and commit again.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/runbooks/incident-response.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.