# /schedule -- Manage recurring scheduled tasks

Manage Dave's scheduled tasks: list, create, enable, disable, and remove recurring jobs that run via OS-native scheduling facilities.

## Behaviour

### First use / no backend configured

If `.dave/config.json` does not have a `scheduler.backend` key, run detection first:

```bash
node core/tools/scheduler/detect.mjs
```

Present the available backends to the user with the recommendation noted. Ask which backend to use. Store the choice in `.dave/config.json`:

```json
{
  "scheduler": {
    "backend": "<chosen>",
    "detectedAt": "<ISO timestamp>",
    "available": ["<list>"]
  }
}
```

### List schedules

Show all installed Dave schedules for the configured backend:

```bash
node core/tools/scheduler/list.mjs <backend>
```

Also list any schedule JSON files in `schedules/` that are not yet installed (enabled but no matching backend entry).

### Create a new schedule

1. Ask the user for: id, name, cron expression, command, and description
2. Write the schedule JSON to `schedules/<id>.json`
3. Run install:

```bash
node core/tools/scheduler/install.mjs schedules/<id>.json <backend>
```

4. Confirm installation

### Enable / disable a schedule

To disable: set `enabled: false` in the schedule JSON and run remove.mjs for the backend.

To enable: set `enabled: true` and run install.mjs.

### Remove a schedule

```bash
node core/tools/scheduler/remove.mjs <id> <backend> --delete-file
```

### Run a schedule now (manual trigger)

Execute the command from the schedule JSON directly:

```bash
cd <workingDirectory> && <command>
```

## Schedule format

See `core/tools/desk/schema/schedule.json` for the full JSON schema. Quick reference:

| Field | Required | Example |
|---|---|---|
| `id` | Yes | `distillation-sweep` |
| `name` | No | `Daily Distillation Sweep` |
| `schedule` | Yes | `0 3 * * *` (cron syntax) |
| `command` | Yes | `bash core/tools/distill/run.sh` |
| `workingDirectory` | No | `${DAVE_ROOT}` |
| `enabled` | No | `true` |
| `description` | No | `Run distillation daily at 3am` |

## Common schedules

| Task | Suggested cron | Command |
|---|---|---|
| Distillation sweep | `0 3 * * *` | `bash core/tools/distill/run.sh` |
| Knowledge reindex | `0 */6 * * *` | `node core/knowledge/retrieval/index-builder.mjs` |
| Health check | `*/30 * * * *` | `node core/tools/scheduler/detect.mjs` |

## Backend reference

| Backend | OS | How it works |
|---|---|---|
| launchd | macOS | Plist in `~/Library/LaunchAgents/com.dave.{id}.plist` |
| cron | macOS/Linux | Crontab entries tagged with `# dave-{id}` |
| systemd | Linux | User timer + service in `~/.config/systemd/user/dave-{id}.{timer,service}` |
| schtasks | Windows | Windows Task Scheduler entries named `dave-{id}` |