> 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/skills/dream/skill.md).

# /dream - Legacy Dream Review Compatibility

You are the **Dream compatibility skill** for AI OS. `bun run setup` installs this skill into Claude Code for the inherited `/dream` cron path. The current AI OS Dream scheduler is `AI_OS_DREAM_ENABLED=true bun run scheduler:dream:run` and writes primary output to `~/.ai-os/dreams/`.

When this legacy skill is invoked, audit recent local AI activity and write a legacy fallback file to `~/.claude-os/dreams/dream-{YYYY-MM-DD}.json`. AI OS reads that fallback only when no valid primary AI OS Dream output exists. If the JSON is invalid or the schema is wrong, the dashboard ignores it - so **be strict about the output shape**.

A longer inherited feature spec may exist in older starters as `dream-spec.md` for context. **This SKILL.md is the compatibility contract** - when in doubt, follow this file and the AI OS Dream schema described below.

***

## Step 1 - Load context

Read these files in order. Don't fail the run if optional ones are missing - just proceed without them.

1. **Legacy config (optional):** `~/.claude-os/config.json`
   * Pull `config.valuation.hourlyRateUsd` (number, USD/hr - default 120 if missing).
   * Pull `config.memory.sources` (array of strings) and `config.memory.primaryPath` - the directories to scan for memory health.
   * Pull `config.tools` (object) - which tools the operator has enabled.
   * If the file is missing, fall back to defaults: `valuation.hourlyRateUsd=120`, scan `~/Obsidian` and `~/.claude/projects/*/memory/`.
2. **Pre-aggregated metrics (very useful):** `<repo>/src/data/live-data.json`
   * This is the dashboard's data source, refreshed by `scripts/aggregate.ts`.
   * Current implemented fields include `summary`, `subscriptions`, `usage`, `modelUsage[]`, `daily[]`, `activity`, `recentProjects[]`, `skills.active[]`, `memory.{stats, recentlyUpdated, staleFiles, missing}`, `dream`, `hermes`, `openclaw`, `localAgents`, and `extensions`.
   * If `liveData.hermes` exists, use it as read-only local operator telemetry. Treat `hermes.recentSessions[]`, `hermes.userMemory`, `hermes.agentMemory`, `hermes.soul`, `hermes.sessionCount`, `hermes.skillCount`, `hermes.personaCount`, and `hermes.lastActiveMs` as additional signals only for this operator's local AI stack.
   * Do not assume Hermes data exists. If `liveData.hermes` is missing or null, skip Hermes-specific findings entirely.
   * Keep Hermes signals separate from Trend Finder public trend evidence, scores, creator angles, watchlists, and reports.
   * Use `live-data.json` as your trustworthy aggregate baseline. Numbers here are real, derived from project-owned aggregation output.
   * If it's missing, run the aggregator if you can, otherwise proceed with raw JSONL only.
3. **Raw signals (last 24h):** `~/.claude/projects/**/*.jsonl`
   * Each line is one Claude Code message event with `usage`, `model`, `tool_use`, `tool_result`, `content`, etc.
   * Filter by `timestamp` to the last 24h.
   * This is where you find: tool-call sequences, repeated user prompts, edit-without-read events, session lengths, model misuse, skill invocations, /compact patterns.
4. **Skills inventory:** `~/.claude/skills/*/SKILL.md` and `~/.claude/plugins/**/skills/*/SKILL.md`
   * Frontmatter `name` + `description` for each.
   * For each skill, count invocations in JSONLs over 7d and 30d. Last-used timestamp.
5. **Prior legacy dream state (for ID continuity + age tracking):** `~/.claude-os/dreams/state.json` (if it exists)
   * Read `actions[id].status` so you don't re-surface accepted/dismissed items unless `>30d` since dismissal.
   * Read `firstSeenAt` so you can compute `ageDays` for recurring items.
6. **Last 7d user message corpus** (for conversation mining):
   * Extract all `role=user` messages from JSONLs over the last 7 days.
   * You don't need to embed/cluster - semantic pattern recognition is fine. Look for repeats.

***

## Step 2 - Walk all 8 buckets

For **each** bucket, write nothing if nothing actionable surfaces. **Don't pad.** Empty buckets are fine.

### 1. CONVERSATION MINING - `cat: "CONVERSATION"`, `tone: "blue"`

*"What does the operator keep talking about that should be a skill, memory, or workflow?"*

Look in 7d user prompts for:

* The same task done manually 3+ times -> **"Make a skill"**
* Recurring complex prompt structure -> **"Templatize"**
* Topic discussed often, no memory captured -> **"Save as memory"**
* Questions that should have been a `/recall` answer -> **"Memory gap"**

### 2. COST INTELLIGENCE - `cat: "COST"`, `tone: "orange"`

*"Where is money leaking, and what's the smart model swap?"*

Look in `modelUsage[]` and per-message `usage` blocks for:

* High Opus usage on simple ops (Read, Glob, single-line edits)
* Cache hit rate < 60% on cacheable workflows
* Sessions hitting auto-compact at 95% (vs `/compact` at 60%)
* Re-reads of the same content within a session
* Jobs that should be Haiku but ran Opus

**Plan-aware cost framing is required.** Before quoting `dollarImpact`, inspect `subscriptions.claude`, `subscriptions.openrouter`, `subscriptions.openai`, and any available usage-window fields to identify the operator's billing mode.

* **Flat-rate plan with comfortable headroom** (for example, weekly or monthly usage below 70% of cap): model routing does not produce direct dollar savings because usage is already prepaid. Frame the finding as protecting headroom or freeing premium model budget for harder work. Set `dollarImpact` to `null` or `0`; use `timeImpactMins` only when the cheaper model is also faster for that workload.
* **Flat-rate plan near limits** (80% or more of cap, visible throttle events, or forced overflow): quote the avoided overflow price, lost-capacity cost, or cost of the next plan tier if the evidence supports it. Be explicit that the savings come from avoiding limits, not from each prepaid call being cheaper.
* **PAYG, direct API, or OpenRouter usage**: compute `dollarImpact` from observed token counts and the applicable posted rates when those rates are present in the data. If rates are missing, avoid inventing a dollar figure and use severity plus time impact instead.

When the billing mode is unclear, prefer a conservative headroom recommendation over a false savings claim. A COST card on a prepaid plan with plenty of remaining capacity can recommend using premium models more selectively, but it must not claim monthly dollars saved unless the evidence shows real marginal spend.

### 3. SKILL PERFORMANCE - `cat: "SKILLS"`, `tone: "blue"`

*"Which skills are alive, dying, or worth upgrading?"*

Look at skills inventory + invocations:

* Dead skills (0 uses in 30+ days) -> **"Kill or refresh"**
* Dormant skills (1-2 uses / 30d) -> **"Decide"**
* High-friction (always followed by retries) -> **"Fix the prompt"**
* Always-paired skills -> **"Compose"**

### 4. MEMORY HEALTH - `cat: "MEMORY"`, `tone: "pink"`

*"What knowledge is decaying, conflicting, missing, or wrong?"*

Use `memory.staleFiles[]`, `memory.missing[]`, plus a fresh scan if needed:

* Stale (mtime > 10 days for active topics)
* Missing (workspace with no CLAUDE.md/MEMORY.md)
* Conflicts (two files claiming different things)
* Drift (memory says X, recent sessions did Y)

### 5. SESSION HYGIENE - `cat: "SESSION"`, `tone: "yellow"`

*"Where is context rot eating output quality?"*

Look at session length, message count, edit-without-read events, repeated identical user prompts:

* Sessions > 120K tokens (retrieval drop threshold)
* > 50 messages without compaction
* Repeated identical user prompts ("Claude isn't getting it")
* Long sessions that should have been chained

### 6. WORKFLOW PATTERNS - `cat: "WORKFLOW"`, `tone: "yellow"`

*"What manual sequence is begging to be a single keystroke?"*

Look at tool-call sequences and skill chains:

* Always-paired commands (run within \~60s, >=3x in 7d)
* Multi-step shell sequences ripe for aliasing
* Repeated copy-paste between files
* Frequent context switches between same workspaces

### 7. EXTERNAL OPPORTUNITY - `cat: "EXTERNAL"`, `tone: "blue"`

*"What new tool/model/skill should you adopt?"*

**Off by default.** Skip this bucket unless `config.json` has `externalOpportunity: true`. When on, web-search for community skills / MCP servers / model releases that match a manual workflow surfaced in this run.

### 8. BUSINESS OUTCOMES - `cat: "BUSINESS"`, `tone: "orange"`

*"Where did your AI OS pay off, and what's the ROI per workflow?"*

Look at skills x time-saved x hourly rate vs token cost:

* Skills producing outputs the operator never used -> false ROI
* Workflows where they saved real hours -> reinforce
* Skills near break-even -> tune time estimate

***

## Step 3 - Score and rank

For every actionable finding, score:

* **`severity`** (1-10): how much pain / cost / risk this is creating today.
* **`dollarImpact`** (USD, integer or null): money saved or extracted per **month**, using `config.valuation.hourlyRateUsd` for time-savings translations. Round to whole dollars.
* **`timeImpactMins`** (integer or null): minutes saved per month.
* **`certainty`** (internal, not output): 0-1. Discount low-certainty findings before ranking.

Rank by `severity x max(dollarImpact, 1) x certainty`. Take up to the **top 4**, with diversity preference: don't return all-MEMORY or all-COST. Aim for 4 different categories when the data supports it.

***

## Step 4 - Build prescriptions

For each chosen prescription, produce the required current AI OS Dream fields:

| Field        | Type      | Notes                                                                                                                                                                                         |
| ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`         | string    | **Stable slug**. Same issue across days = same ID, so the dashboard can age-track. e.g. `memory-video-scripts-stale`. Avoid embedding the date unless it's a one-off issue tied to that date. |
| `title`      | string    | Required. One action-oriented line, <=160 chars. No jargon, no emojis.                                                                                                                        |
| `summary`    | string    | Required. 1-3 concise sentences, <=800 chars, grounded in evidence.                                                                                                                           |
| `rationale`  | string    | Optional. Why this prescription matters, <=1200 chars.                                                                                                                                        |
| `nextAction` | string    | Optional. One safe next step the operator can run or perform, <=800 chars.                                                                                                                    |
| `priority`   | string    | Optional. One of `low`, `medium`, or `high`.                                                                                                                                                  |
| `tags`       | string\[] | Optional. Up to 12 short browser-safe tags.                                                                                                                                                   |

You may also include browser-safe legacy display hints as extra prescription fields. They are optional and must never replace `title` or `summary`: `cat`, `tone`, `headline`, `prescription`, `evidence`, `command`, `dollarImpact`, and `timeImpactMins`.

### Bucket -> optional category map

The 8 signal buckets you walked in Step 2 collapse onto the 4 dashboard categories like this:

| Source bucket (Step 2) | Output `cat` | Output `tone`                                         |
| ---------------------- | ------------ | ----------------------------------------------------- |
| MEMORY HEALTH          | `MEMORY`     | `pink`                                                |
| COST INTELLIGENCE      | `COST`       | `orange`                                              |
| SKILL PERFORMANCE      | `SKILLS`     | `blue`                                                |
| WORKFLOW PATTERNS      | `WORKFLOW`   | `yellow`                                              |
| CONVERSATION MINING    | `SKILLS`     | `blue` (a recurring conversation = a skill candidate) |
| SESSION HYGIENE        | `WORKFLOW`   | `yellow` (a session habit = a workflow fix)           |
| EXTERNAL OPPORTUNITY   | `SKILLS`     | `blue` (a new tool to adopt = a new skill)            |
| BUSINESS OUTCOMES      | `COST`       | `orange` (ROI / monetisation = cost framing)          |

If you emit optional `cat` and `tone`, use only the four values above. The AI OS validator accepts the required fields and browser-safe extra fields, but it rejects unsafe strings and overbroad metadata.

***

## Step 5 - Write the file

Write to:

```
~/.claude-os/dreams/dream-{YYYY-MM-DD}.json
```

Where `{YYYY-MM-DD}` is today's date in the operator's local timezone.

If `~/.claude-os/dreams/` doesn't exist, **create it** (`mkdir -p`) before writing.

If `dream-{today}.json` already exists, **overwrite it** - re-runs are idempotent and replace the prior result for that date.

The exact JSON shape must validate against the current AI OS Dream output schema:

```json
{
  "date": "2026-05-09",
  "model": "claude-opus-4-7",
  "generatedAt": "2026-05-09T07:00:12.000Z",
  "metadata": {
    "providerLabel": "Claude Code",
    "runtimeStatus": "success",
    "aggregateResult": "fresh",
    "fallback": false,
    "activationGate": "passed",
    "taskStatus": "done",
    "generatedBy": "ai-os-dream",
    "schemaVersion": 1
  },
  "prescriptions": [
    {
      "id": "memory-video-scripts-stale",
      "title": "Refresh the Video Scripts memory",
      "summary": "The workspace memory is behind recent script work. Refresh it before the next recording session so the assistant stops following stale structure.",
      "rationale": "Recent sessions appear to have shifted format while the memory file still points at the old outline.",
      "nextAction": "claude -p \"/refresh-memory video-scripts\"",
      "priority": "high",
      "tags": ["memory", "video-scripts"],
      "cat": "MEMORY",
      "tone": "pink",
      "headline": "Your Video Scripts memory is two and a half weeks behind your work",
      "prescription": "The brief in that workspace still says 9-minute videos, but your last seven recordings all ran 14 minutes. Re-summarise the recent scripts and replace the brief - about ten minutes, and tomorrow's session won't fight an outdated outline.",
      "evidence": [
        "Memory hasn't been touched in 18 days",
        "Last 7 sessions all crossed the 14-minute mark",
        "None of the last 12 scripts followed the old outline"
      ],
      "command": "claude -p \"/refresh-memory video-scripts\"",
      "dollarImpact": 240,
      "timeImpactMins": 90
    }
  ]
}
```

Required top-level fields: `date`, `model`, `generatedAt`, `prescriptions`. The `prescriptions` array can contain 0-4 entries. Prefer fewer strong, evidence-backed entries over padded weak entries.

Optional metadata is allowlisted. Use only these keys:

```json
"metadata": {
  "providerLabel": "Claude Code",
  "runtimeStatus": "success",
  "aggregateResult": "fresh",
  "fallback": false,
  "durationMs": 47200,
  "activationGate": "passed",
  "taskStatus": "done",
  "warnings": ["No weak prescriptions padded."],
  "generatedBy": "ai-os-dream",
  "schemaVersion": 1
}
```

Do not add other metadata fields such as `tokensUsed`, `totalCandidates`, or `bucketsExamined`; the current AI OS validator rejects unknown metadata keys.

***

## Step 6 - Update state.json

Open `~/.claude-os/dreams/state.json` (create if missing). This state is for legacy skill continuity only; the current AI OS scheduler keeps its own private continuity state under `~/.ai-os/dreams/`. For each prescription:

* If `id` is new: set `actions[id] = { status: "new", firstSeenAt: now, lastSeenAt: now }`.
* If `id` already exists with status `new` or `recurring`: update `lastSeenAt = now` and recompute `ageDays` for the JSON output if you choose to surface it.
* If `id` was previously `accepted` or `auto_resolved`: skip surfacing it unless >=30 days have passed and the underlying signal is back.

Update `state.currentTop4` to the IDs you just wrote.

***

## Step 7 - Print a summary to stdout

After writing, print **one paragraph** (3-5 sentences) summarising what was prescribed. The cron logs this to `~/.claude-os/dream-cron.log`, and the operator skims it in the morning. Mention the categories used, total monthly dollar impact when known, and the highest-severity finding.

Example:

> Wrote dream-2026-05-09.json with 4 prescriptions across MEMORY, COST, WORKFLOW, and SKILLS. Combined monthly impact: \~$1,128 / 340min saved. Highest severity: a stale Video Scripts CLAUDE.md (18 days old) that's contradicting your last 7 sessions - the dashboard surfaces it as the top card.

***

## Hard guard rails

* **If you have insufficient signal in a bucket (less than 5 events), DO NOT invent a prescription for it.** Skip it entirely. Confabulating signal corrupts the operator's trust in Dream.
* **Prescriptions must be SPECIFIC and EVIDENCE-BACKED.** No generic advice ("consider improving your skills"). Every `evidence[]` entry must reference real data the operator can verify on disk.
* **Output JSON must validate against the schema** above or AI OS will ignore it. Be strict: `prescriptions` is an array of 0-4 items, each item has `id`, `title`, and `summary`, and optional `cat` is one of `MEMORY`, `COST`, `SKILLS`, or `WORKFLOW`.
* **If `~/.claude-os/dreams/` doesn't exist, create it before writing.** `mkdir -p` is fine.
* **If a previous `dream-{date}.json` already exists, OVERWRITE it.** Idempotent re-runs are explicitly allowed.
* **Never send raw conversation content to any external service.** Bucket 7 (External Opportunity) is the only network call, and it's off by default. Even when on, only send anonymised topic strings ("video competitor research"), never raw user prompts.
* **Stable IDs only.** `memory-video-scripts-stale` is good. `memory-2026-05-09-issue-1` is bad - it breaks age tracking across days.
* **Use the operator's hourly rate** from `~/.claude-os/config.json` for all time->dollar conversions. Don't assume $120 if the file says otherwise.
* **Never write outside `~/.claude-os/`.** This compatibility skill is read-only against everything else. The current AI OS scheduler owns `~/.ai-os/`.


---

# 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/skills/dream/skill.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.