From 5b7fa2d4ad36bf1cbc8ef2afb849c915566a16bb Mon Sep 17 00:00:00 2001
From: AIOSAI <aipass.system@gmail.com>
Date: Thu, 25 Jun 2026 07:10:49 -0700
Subject: [PATCH] docs(daemon): self-sufficient run --help
 (schema/types/example) + README scheduling section (FPLAN-0287)

---
 src/aipass/daemon/README.md                   | 42 +++++++++++++++++++
 src/aipass/daemon/apps/modules/run.py         | 32 ++++++++++++++
 .../daemon/apps/modules/timer_install.py      |  2 +-
 3 files changed, 75 insertions(+), 1 deletion(-)

diff --git a/src/aipass/daemon/README.md b/src/aipass/daemon/README.md
index a8059043..7d189162 100644
--- a/src/aipass/daemon/README.md
+++ b/src/aipass/daemon/README.md
@@ -120,6 +120,48 @@ drone @daemon <command> --help
 
 ---
 
+## Scheduling Jobs
+
+Each branch owns its schedule at `src/aipass/<branch>/.daemon/schedule.json`. The daemon discovers and fires — branches define their own jobs.
+
+### Job file schema
+
+```json
+{
+  "version": 1,
+  "branch": "@<branch>",
+  "jobs": [
+    {
+      "id": "my-job",
+      "enabled": true,
+      "schedule": { "type": "interval", "interval_minutes": 30 },
+      "wake": { "fresh": true, "model": "haiku" },
+      "prompt": "Do something, then STOP."
+    }
+  ]
+}
+```
+
+### Schedule types
+
+| Type | Fields | Due when |
+|------|--------|----------|
+| `interval` | `interval_minutes: N` | Elapsed >= N since last_run. Fires immediately if never run. |
+| `daily` | `time: "HH:MM"` | Within +/-15 min of target time, once per day. |
+| `hourly` | `time: "M"` (minute) | Within +/-15 min of target minute, once per hour. |
+| `once` | `due_date: "YYYY-MM-DD"` | Date <= today, then marks completed. |
+
+### Wake options
+
+- `fresh` (bool) — start a fresh Claude session (true) or resume (false)
+- `model` (string, optional) — `"haiku"` or `"sonnet"` recommended for light wakes
+
+### Staggering
+
+No native offset field. To stagger jobs, seed different `last_run` values in `daemon_json/daemon_runstate.json`.
+
+---
+
 ## Integration Points
 
 ### Depends On
diff --git a/src/aipass/daemon/apps/modules/run.py b/src/aipass/daemon/apps/modules/run.py
index fb606463..f6160891 100644
--- a/src/aipass/daemon/apps/modules/run.py
+++ b/src/aipass/daemon/apps/modules/run.py
@@ -69,6 +69,38 @@ def print_help():
     console.print("\n[yellow]DESCRIPTION:[/yellow]")
     console.print("  Sweeps src/aipass/*/.daemon/*.json for scheduled jobs,")
     console.print("  evaluates due-ness, and wakes each due branch via wake_branch().")
+    console.print("\n[bold cyan]SCHEDULING — How to author a job:[/bold cyan]")
+    console.print("  [bold]File:[/bold] src/aipass/<branch>/.daemon/schedule.json")
+    console.print()
+    console.print("  [bold]Schema:[/bold]")
+    console.print("    {")
+    console.print('      "version": 1,')
+    console.print('      "branch": "@<branch>",')
+    console.print('      "jobs": [')
+    console.print("        {")
+    console.print('          "id": "my-job",')
+    console.print('          "enabled": true,')
+    console.print('          "schedule": { "type": "interval", "interval_minutes": 30 },')
+    console.print('          "wake": { "fresh": true, "model": "haiku" },')
+    console.print('          "prompt": "Do something, then STOP."')
+    console.print("        }")
+    console.print("      ]")
+    console.print("    }")
+    console.print()
+    console.print("  [bold]Schedule types:[/bold]")
+    console.print("    [cyan]interval[/cyan]  interval_minutes: N")
+    console.print("              [dim]Fires when elapsed >= N since last_run. Fires immediately if never run.[/dim]")
+    console.print("    [cyan]daily[/cyan]     time: HH:MM")
+    console.print("              [dim]+/-15 min window, once per day.[/dim]")
+    console.print("    [cyan]hourly[/cyan]    time: M  [dim](minute of hour)[/dim]")
+    console.print("              [dim]+/-15 min window, once per hour.[/dim]")
+    console.print("    [cyan]once[/cyan]      due_date: YYYY-MM-DD")
+    console.print("              [dim]Fires when date <= today, then marks completed.[/dim]")
+    console.print()
+    console.print("  [bold]wake options:[/bold]  fresh (bool), model (haiku/sonnet — use light models)")
+    console.print()
+    console.print("  [bold]Staggering:[/bold] No native offset field. Seed different last_run values")
+    console.print("  in daemon_json/daemon_runstate.json to offset first-fire timing.")
     console.print()
 
 
diff --git a/src/aipass/daemon/apps/modules/timer_install.py b/src/aipass/daemon/apps/modules/timer_install.py
index fa4d8195..0b1041a4 100644
--- a/src/aipass/daemon/apps/modules/timer_install.py
+++ b/src/aipass/daemon/apps/modules/timer_install.py
@@ -55,7 +55,7 @@ def print_help():
     console.print("  drone @daemon install-timer --help")
     console.print("\n[yellow]DESCRIPTION:[/yellow]")
     console.print("  Copies daemon-tick.service and daemon-tick.timer to")
-    console.print(f"  {_UNIT_DIR}/")
+    console.print("  ~/.config/systemd/user/")
     console.print("  Then reloads systemd and enables+starts the timer.")
     console.print("  Idempotent — safe to run multiple times.")
     console.print()