dreaming

# Dreaming

Creative, exploratory thinking during quiet hours. Not task-oriented work — freeform associative exploration that gets captured for later review.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `WORKSPACE` | No | Skill's parent directory (`scripts/..`) | Root directory where `data/` and `memory/` live. Optional — defaults to the skill's parent directory, which is correct for standard workspace layouts. |

## Directories Written

The skill writes to these directories (relative to `WORKSPACE`):

- **`data/dream-state.json`** — Tracks nightly dream count and last dream date
- **`data/dream-config.json`** — Optional custom topic configuration (user-created)
- **`memory/dreams/YYYY-MM-DD.md`** — Dream output files (written by the agent, not the script)

## Setup

### 1. Configure quiet hours and topics

Edit `skills/dreaming/scripts/should-dream.sh` to customize:

- **QUIET_START / QUIET_END** — when dreaming can happen (default: 11 PM - 7 AM)
- **TOPICS array** — categories of exploration (see defaults for examples)

### 2. Create state and output directories

```bash
mkdir -p data memory/dreams
```

### 3. Add to HEARTBEAT.md

Add this section to your heartbeat routine (during quiet hours):

```markdown
## Dream Mode (Quiet Hours Only)

Check if it's time to dream:

\`\`\`bash
DREAM_TOPIC=$(./skills/dreaming/scripts/should-dream.sh 2>/dev/null) && echo "DREAM:$DREAM_TOPIC" || echo "NO_DREAM"
\`\`\`

**If DREAM_TOPIC is set:**

1. Parse the topic (format: `category:prompt`)
2. Write a thoughtful exploration to `memory/dreams/YYYY-MM-DD.md`
3. Keep it genuine — not filler. If the well is dry, skip it.
4. Append to the file if multiple dreams that night
```

## How It Works

The `skills/dreaming/scripts/should-dream.sh` script acts as a gate:

1. Checks if current time is within quiet hours
2. Checks if we've already hit the nightly dream limit
3. Rolls dice based on configured probab...