> 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/ai-os-dream.md).

# AI OS Dream Runbook

AI OS Dream is the host runtime job that evaluates Dream activation gates, ensures fresh browser-safe host/local material, and writes private Dream output for local operator review. Dream is enabled in starter scheduler metadata, but the Dream activation gate remains explicit and only passes when the operator invokes it from the local dashboard, the CLI, or an activated scheduler process.

Dream is AI OS host behavior. Trend Finder remains a separate extension and does not own Dream cadence, state, prescriptions, provider setup, or private outputs.

## Current Status

| Area                 | Current behavior                                                                             |
| -------------------- | -------------------------------------------------------------------------------------------- |
| Scheduler job        | `dream` is an available AI OS scheduler job                                                  |
| Default cadence      | Daily 07:00 local candidate                                                                  |
| Enablement           | Enabled by default in starter metadata; activation remains explicit                          |
| Manual run           | Home/Settings button or activated CLI scheduler run                                          |
| Status command       | `bun run scheduler:dream:status`                                                             |
| Material dependency  | Dream uses recent generated data, or refreshes host/local material through `agent-aggregate` |
| Browser projection   | Safe live-data Dream cards after aggregate refresh                                           |
| Output               | Private AI OS Dream output, continuity state, and scheduler state                            |
| Legacy compatibility | Read fallback for legacy `~/.claude-os/dreams` outputs                                       |

## Before You Run Dream

Dream is designed for local operator use and should stay private. Before using it with real data:

* Keep `.env.local`, account-auth files, generated data, scheduler state, scheduler logs, and Dream outputs out of git.
* Run Dream from the repository root.
* Configure AI runtime values through script-only env names such as `AI_OS_AI_RUNTIME_*`, `AI_OS_OPENAI_ACCOUNT_AUTH_PATH`, and `OPENAI_API_KEY`.
* Do not create `VITE_` aliases for runtime secrets or auth paths.
* Treat the setup wizard Dream toggles as browser-safe setup preferences, not provider credentials.
* Use `data/ai-os.scheduler.json` only for local scheduler timer intent and reviewed cadence/time choices; keep secrets and activation env in `.env.local`.

## Commands

Inspect Dream status:

```bash
bun run scheduler:dream:status
```

Run Dream through the AI OS scheduler when activation is already present in the scheduler process:

```bash
bun run scheduler:dream:run
```

Run a one-shot enabled CLI review without changing persistent env:

```bash
AI_OS_DREAM_ENABLED=true bun run scheduler:dream:run
```

Inspect JSON status for local automation:

```bash
bun run scripts/scheduler-status.ts --job dream --json
```

Refresh the full compatibility aggregate directly without scheduler state:

```bash
bun run aggregate
```

The direct aggregate command remains useful for immediate full generated-data refreshes. Dream uses the scheduler path because it needs activation gates, locks, runtime state, continuity, material freshness checks, and private output validation.

## Freshness Behavior

Dream depends on fresh, browser-safe generated data. The Dream scheduler handler first evaluates the current local live-data material. If the material is fresh enough, Dream proceeds without refreshing aggregate data. If the material is stale, missing, fallback, or empty, Dream refreshes host/local material through the scoped `agent-aggregate` handler and then evaluates Dream material readiness, provider readiness, locks, cooldowns, and output validation.

The normal Dream path does not run Trend Finder collectors. Trend Finder can still be refreshed separately with `bun run scheduler:trend-finder:run`, and the full `bun run aggregate` compatibility command remains available when an operator intentionally wants the complete writer.

If generated data remains unavailable, stale, degraded, or blocked after the agent aggregate refresh, Dream can skip, degrade, or fall back depending on the safe state produced by the handler. Dream does not read raw browser transcripts or private source directories through the browser UI.

## Enablement

Dream is enabled by default in the scheduler registry metadata. The Home and Settings Dream Review buttons still start the scheduler job with explicit one-shot activation. For CLI use, either set the activation env in the scheduler process or prefix the command:

```bash
AI_OS_DREAM_ENABLED=true bun run scheduler:dream:run
```

Without explicit activation, `bun run scheduler:dream:run` is expected to report a skipped Dream run rather than write private Dream output.

`data/ai-os.scheduler.json` can record local timer intent and a strict `HH:MM` Dream time, but it does not activate the Dream runtime by itself and does not prove that an OS timer is installed. Keep the actual activation boundary in the scheduler process through `AI_OS_DREAM_ENABLED=true`.

To schedule Dream on macOS or Windows, use `bun run install-dream`; full telemetry setup may call the same installer. To schedule Dream on Linux, create a local user timer yourself and point it at the Dream scheduler command with explicit activation. Status commands report last-run state; they do not prove future timer delivery.

Example systemd user service:

```ini
[Unit]
Description=AI OS Dream scheduler

[Service]
Type=oneshot
WorkingDirectory=/path/to/ai-os
ExecStart=/usr/bin/env bun run scheduler:dream:run
Environment=AI_OS_DREAM_ENABLED=true
Environment=AI_OS_SCHEDULER_TRIGGER_SOURCE=systemd
```

Example timer:

```ini
[Unit]
Description=Run AI OS Dream daily

[Timer]
OnCalendar=*-*-* 07:00:00
Persistent=true

[Install]
WantedBy=timers.target
```

Use your actual checkout path. Do not commit generated unit files with local machine paths or account names.

## Status States

`bun run scheduler:dream:status` prints stable labels that are safe to share when the command was run without credentialed private output.

| State              | Meaning                                                               | Usual response                                |
| ------------------ | --------------------------------------------------------------------- | --------------------------------------------- |
| `first-run`        | No private Dream scheduler state exists yet                           | Run the Dream scheduler command               |
| `success`          | Latest Dream scheduler run completed cleanly                          | No action required                            |
| `warning-only`     | Run completed with sanitized warning summaries                        | Inspect private logs locally if repeated      |
| `degraded`         | Run completed with reduced input, mock provider, or fallback coverage | Check aggregate and provider readiness        |
| `failed`           | Handler failed before clean completion                                | Check local script-only config and rerun      |
| `timeout`          | Run exceeded the 45 minute timeout                                    | Check aggregate duration and provider latency |
| `blocked`          | Existing lock or active run prevented execution                       | Wait or rerun to allow stale-lock recovery    |
| `skipped`          | Activation gates or scheduler policy skipped execution                | Check explicit enablement and readiness       |
| `stale-lock`       | Run completed after stale lock recovery                               | Watch for repeated recovery                   |
| `unreadable-state` | Latest state could not be parsed safely                               | Rerun to replace private state                |

Status output intentionally omits raw warning bodies, prompts, transcripts, provider responses, auth JSON, command bodies, local usernames, emails, and private path contents.

## Private Files

Dream may create or refresh these local-only artifact classes:

| Path class                              | Purpose                                         |
| --------------------------------------- | ----------------------------------------------- |
| `src/data/live-data.json`               | Generated aggregate input used by the dashboard |
| AI OS scheduler run state               | Latest Dream status metadata                    |
| AI OS scheduler lock                    | Non-overlap guard for Dream runs                |
| AI OS scheduler log                     | Private scheduler diagnostics                   |
| `~/.ai-os/dreams/dream-YYYY-MM-DD.json` | Private Dream output                            |
| `~/.ai-os/dreams/continuity-state.json` | Private Dream prescription continuity           |
| `~/.ai-os/dreams/runtime-state.json`    | Private Dream lifecycle state                   |

The status command exposes labels for these files, not local path values or file contents.

## Legacy Compatibility

AI OS Dream writes to the AI OS private Dream root. Legacy `~/.claude-os/dreams` output is retained as a read fallback so older local Dream artifacts can still be loaded when no primary AI OS output exists.

The inherited `/dream` skill remains a compatibility asset. The `install-dream` and `uninstall-dream` commands now manage the OS-level AI OS Dream schedule: macOS through launchd, Windows through Task Scheduler, and Linux through printed manual cron guidance. OS task registration is not proof that the latest Dream job succeeded; use `bun run scheduler:dream:status` for the safe last-run state.

## Provider Behavior

Dream uses the AI OS host runtime provider boundary. Host env names take precedence, then compatibility names are used when host names are unset:

```
AI_OS_AI_RUNTIME_PROVIDER -> FINDTREND_AI_RUNTIME_PROVIDER
AI_OS_AI_RUNTIME_ENABLED -> FINDTREND_AI_RUNTIME_ENABLED
AI_OS_AI_RUNTIME_MODEL -> FINDTREND_AI_RUNTIME_MODEL
AI_OS_AI_RUNTIME_REASONING_EFFORT -> FINDTREND_AI_RUNTIME_REASONING_EFFORT
AI_OS_AI_RUNTIME_BASE_URL -> FINDTREND_AI_RUNTIME_BASE_URL
AI_OS_OPENAI_ACCOUNT_AUTH_PATH -> FINDTREND_OPENAI_ACCOUNT_AUTH_PATH -> FINDTREND_AI_RUNTIME_AUTH_PATH
```

Supported readiness states include disabled, mock, missing-auth, invalid-auth, Codex-account, and OpenAI API placeholder readiness. Disabled, mock, missing-auth, and invalid-auth states produce explicit Dream status and fallback behavior instead of printing secrets or crashing.

## Prescriptions And Continuity

Dream output may include up to four current prescriptions. Continuity state is kept privately so repeated runs can suppress duplicates and prune stale prescriptions. Browser setup copy can describe the prescription count, but it must not expose private Dream output or provider payloads.

## Cleanup

To reset generated local aggregate data:

```bash
rm -f src/data/live-data.json
```

To reset direct aggregate logs:

```bash
rm -f logs/aggregate.latest.jsonl
rm -f logs/aggregate-*.jsonl
```

If you enabled a local timer, disable it before deleting scheduler state:

```bash
systemctl --user disable --now ai-os-dream.timer
```

Then remove private AI OS scheduler state, Dream lock, scheduler log, Dream output, continuity state, and runtime state from your local machine. Do not commit those files.

## Deferrals

This runbook does not add:

* a general Dream control panel beyond the manual local run button
* browser writes to private Dream state or output files
* a remote scheduler API
* a gateway or daemon
* remote execution
* automatic production timer installation
* Trend Finder source expansion
* removal of inherited compatibility env names or legacy Dream assets

Any expanded browser control surface, remote scheduler service, or compatibility rename needs a separate threat model, spec, and tests.


---

# 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/ai-os-dream.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.