aias 0.1.0

data/docs/guides/scheduling-prompts.md

@@ -0,0 +1,319 @@
+# Scheduling Prompts
+
+## The `schedule:` Key
+
+Add a single `schedule:` key to any AIA prompt's YAML frontmatter to make it a scheduled job:
+
+```yaml
+---
+description: Morning briefing
+schedule: "0 8 * * *"
+---
+Summarize what happened overnight.
+```
+
+The value is a plain string — either a standard cron expression or a natural language phrase that fugit understands. That is all `aias` needs. At install time `aias` calls `Fugit.parse_cronish` to resolve the value to a canonical cron expression, which is what gets written to the crontab.
+
+## Enabling and Disabling
+
+| Action | How |
+|---|---|
+| Enable scheduling | Add `schedule:` to the frontmatter |
+| Disable scheduling | Remove the `schedule:` line, then run `aias update` |
+| Change the schedule | Edit the `schedule:` value, then run `aias update` or `aias add PATH` |
+
+Removing the `schedule:` line from a prompt that is already installed in the crontab does **not** automatically remove the cron entry. You must run `aias update` (full sync) or `aias remove PROMPT_ID` to remove it.
+
+---
+
+## Schedule Formats
+
+### Standard Cron Expressions
+
+Five-field cron syntax:
+
+```
+┌─ minute     (0–59)
+│  ┌─ hour    (0–23)
+│  │  ┌─ day  (1–31)
+│  │  │  ┌─ month  (1–12 or jan–dec)
+│  │  │  │  └─ weekday (0–7, 0=Sun, 7=Sun, or sun–sat)
+│  │  │  │  │
+*  *  *  *  *
+```
+
+```yaml
+schedule: "0 8 * * *"        # 8:00 AM every day
+schedule: "30 6 * * 1-5"     # 6:30 AM Monday–Friday
+schedule: "0 */4 * * *"      # every 4 hours (at 0, 4, 8, 12, 16, 20)
+schedule: "0 9 1,15 * *"     # 9 AM on the 1st and 15th of each month
+schedule: "0 0 * * 0"        # midnight every Sunday
+```
+
+### `@` Shorthand Keywords
+
+```yaml
+schedule: "@hourly"          # 0 * * * *
+schedule: "@daily"           # 0 0 * * *
+schedule: "@weekly"          # 0 0 * * 0
+schedule: "@monthly"         # 0 0 1 * *
+schedule: "@yearly"          # 0 0 1 1 *
+schedule: "@midnight"        # 0 0 * * *
+```
+
+---
+
+## Natural Language Scheduling (fugit)
+
+`aias` uses the [fugit](https://github.com/floraison/fugit) gem (version 1.12.1) to parse natural language schedule strings. fugit converts them to cron expressions via `Fugit.parse_cronish`.
+
+**Important:** fugit 1.12.1 generates explicit time lists rather than the `*/N` step notation. For example, `every 6 hours` produces `0 0,6,12,18 * * *`, not `0 */6 * * *`. Both are equivalent in meaning, but the explicit form is what you will see in the crontab.
+
+### Frequency Intervals
+
+```yaml
+schedule: "every minute"       # 0,1,2,...,59 * * * *  (every minute)
+schedule: "every 5 minutes"    # 0,5,10,15,20,25,30,35,40,45,50,55 * * * *
+schedule: "every 10 minutes"   # 0,10,20,30,40,50 * * * *
+schedule: "every 30 minutes"   # 0,30 * * * *
+schedule: "every hour"         # 0 * * * *
+schedule: "every 2 hours"      # 0 0,2,4,6,8,10,12,14,16,18,20,22 * * *
+schedule: "every 4 hours"      # 0 0,4,8,12,16,20 * * *
+schedule: "every 6 hours"      # 0 0,6,12,18 * * *
+schedule: "every 12 hours"     # 0 0,12 * * *
+schedule: "every day"          # 0 0 * * *
+schedule: "every week"         # 0 0 * * 0
+schedule: "every month"        # 0 0 1 * *
+schedule: "every year"         # 0 0 1 1 *
+```
+
+Supported abbreviations:
+
+| Abbreviation | Meaning |
+|---|---|
+| `s`, `sec`, `secs`, `second`, `seconds` | seconds |
+| `m`, `min`, `mins`, `minute`, `minutes` | minutes |
+| `h`, `hou`, `hour`, `hours` | hours |
+| `d`, `day`, `days` | days |
+| `M`, `month`, `months` | months (capital `M`) |
+
+Note: `M` (capital) means months; `m` (lowercase) means minutes. Case matters here.
+
+### Days of the Week
+
+Day names are case-insensitive. Three-letter abbreviations work.
+
+```yaml
+schedule: "every monday"                        # 0 0 * * 1
+schedule: "every tuesday"                       # 0 0 * * 2
+schedule: "every friday"                        # 0 0 * * 5
+schedule: "every weekday"                       # 0 0 * * 1,2,3,4,5
+schedule: "every weekend"                       # 0 0 * * 6,0
+schedule: "every monday and wednesday"          # 0 0 * * 1,3
+schedule: "every tuesday and monday at 5pm"     # 0 17 * * 1,2
+schedule: "every friday and saturday at 11pm"   # 0 23 * * 5,6
+schedule: "every Mon to Fri at 9am"             # 0 9 * * 1,2,3,4,5
+schedule: "every monday through friday at 9am"  # 0 9 * * 1,2,3,4,5
+schedule: "every Mon,Tue,Wed,Thu,Fri at 9am"    # 0 9 * * 1,2,3,4,5
+schedule: "every Mon, Tue, and Wed at 18:15"    # 15 18 * * 1,2,3
+schedule: "from Monday to Friday at 9am"        # 0 9 * * 1,2,3,4,5
+```
+
+### Times of Day
+
+```yaml
+# Named times
+schedule: "every day at noon"           # 0 12 * * *
+schedule: "every day at midnight"       # 0 0 * * *
+schedule: "every day at five"           # 0 5 * * *
+
+# 24-hour clock
+schedule: "every day at 8:30"           # 30 8 * * *
+schedule: "every day at 16:00"          # 0 16 * * *
+schedule: "every day at 18:22"          # 22 18 * * *
+
+# AM/PM
+schedule: "every day at 8am"            # 0 8 * * *
+schedule: "every day at 5pm"            # 0 17 * * *
+schedule: "every day at 8:30am"         # 30 8 * * *
+schedule: "every day at 8:30 pm"        # 30 20 * * *
+
+# Combined day + time
+schedule: "every weekday at 9am"        # 0 9 * * 1,2,3,4,5
+schedule: "every monday at 9am"         # 0 9 * * 1
+
+# Multiple times — same minutes merge into one cron entry
+schedule: "every day at 8am and 5pm"       # 0 8,17 * * *
+schedule: "every day at 8:00 and 17:00"    # 0 8,17 * * *
+```
+
+**Limitation:** When two times have *different* minutes (e.g. `8:15 and 17:45`), only the first time is used. Use two separate prompt files with individual `schedule:` lines if you need two runs at different minutes.
+
+### 12 AM/PM Edge Cases
+
+Noon and midnight have special handling:
+
+```yaml
+schedule: "every day at 12pm"           # 0 12 * * *  (noon)
+schedule: "every day at 12am"           # 0 0 * * *   (midnight)
+schedule: "every day at 12 noon"        # 0 12 * * *
+schedule: "every day at 12 midnight"    # 0 0 * * *
+schedule: "every day at 12:30pm"        # 30 12 * * *
+schedule: "every day at 12:30am"        # 30 0 * * *
+```
+
+### Day of Month
+
+Ordinal words (`1st`, `2nd`, `3rd`, etc.) and the word `last` are supported:
+
+```yaml
+schedule: "every 1st of the month at midnight"         # 0 0 1 * *
+schedule: "every 15th of the month at noon"            # 0 12 15 * *
+schedule: "every month on the 1st at 9am"              # 0 9 1 * *
+schedule: "every month on the 1st and 15th at noon"    # 0 12 1,15 * *
+schedule: "every month on the 1st and last at noon"    # 0 12 1,L * *
+schedule: "every month on days 1,15 at 10:00"          # 0 10 1,15 * *
+```
+
+### Time Windows (Range Within a Day)
+
+Run a job on every hour (or minute) within a time range:
+
+```yaml
+schedule: "every weekday 9am to 5pm on the hour"    # 0 9,10,11,12,13,14,15,16,17 * * 1,2,3,4,5
+schedule: "every hour, from 8am to 5pm"             # 0 8,9,10,11,12,13,14,15,16,17 * * *
+schedule: "every minute from 8am to 5pm"            # * 8,9,10,11,12,13,14,15,16 * * *
+```
+
+### Timezone
+
+Append `in TIMEZONE`, `on TIMEZONE`, or a bare timezone name:
+
+```yaml
+schedule: "every day at 9am in America/New_York"       # 0 9 * * * America/New_York
+schedule: "every day at 5pm on America/Chicago"        # 0 17 * * * America/Chicago
+schedule: "every day at midnight America/Los_Angeles"  # 0 0 * * * America/Los_Angeles
+schedule: "every day at 6pm UTC"                       # 0 18 * * * UTC
+schedule: "every day at 9am in Etc/GMT+5"              # 0 9 * * * Etc/GMT+5
+```
+
+Supported formats: IANA city names (`America/New_York`, `Asia/Tokyo`, etc.), `UTC`, `Z`, and offset codes (`Etc/GMT+5`).
+
+If no timezone is given, the job runs in the system timezone of the machine where cron is running.
+
+---
+
+## Limitations
+
+**`every 2 weeks` is not supported.** fugit does not parse multi-week intervals. Use a cron expression instead:
+
+```yaml
+schedule: "0 9 * * 1"    # every Monday — effectively every week
+schedule: "0 9 1,15 * *" # approximate bi-weekly (1st and 15th of month)
+```
+
+**Maximum 256 characters.** Natural language strings longer than 256 characters are rejected.
+
+**Two times with different minutes only fires at the first time.** `"every day at 8:15 and 17:45"` resolves to `15 8 * * *` — the 17:45 is silently dropped. Split into two prompts if you need both.
+
+**`every 2 days` produces a long explicit list.** `"every 2 days"` resolves to `0 0 1,3,5,7,9,11,13,15,17,19,21,23,25,27,29,31 * *`. This is correct but verbose. A simpler alternative is the raw cron `"0 0 */2 * *"`.
+
+---
+
+## Checking Your Schedule
+
+Before installing, preview exactly what cron expression your `schedule:` string resolves to:
+
+```bash
+aias dry-run
+```
+
+The output shows the literal cron line that will be written, so you can verify the expression is correct before committing it to the crontab.
+
+You can also test a fugit parse directly in a Ruby one-liner:
+
+```bash
+ruby -rfugit -e 'puts Fugit.parse_cronish("every weekday at 9am").to_cron_s'
+# => 0 9 * * 1,2,3,4,5
+```
+
+---
+
+## Parameters in Scheduled Prompts
+
+If your prompt uses `parameters:`, **every parameter must have a default value**. Cron runs unattended — there is no interactive session to prompt for input.
+
+**This will fail validation:**
+
+```yaml
+---
+schedule: "0 8 * * *"
+parameters:
+  topic:              # no default — invalid for scheduled prompts
+---
+Write about <%= topic %>.
+```
+
+**This is valid:**
+
+```yaml
+---
+schedule: "0 8 * * *"
+parameters:
+  topic: "Ruby news"  # default provided — safe to run unattended
+---
+Write about <%= topic %>.
+```
+
+`aias` rejects prompts with missing parameter defaults and warns during `update` or `add`. The prompt is excluded from the crontab.
+
+---
+
+## Nested Prompts
+
+Prompts in subdirectories work exactly the same. The full subpath (minus `.md`) becomes the prompt ID:
+
+```
+$AIA_PROMPTS_DIR/
+  reports/
+    weekly_digest.md     → prompt ID: reports/weekly_digest
+  daily_digest.md        → prompt ID: daily_digest
+```
+
+The log file mirrors the directory structure:
+
+```
+~/.config/aia/schedule/logs/reports/weekly_digest.log
+```
+
+---
+
+## Quick Reference
+
+| Natural language | Resolved cron |
+|---|---|
+| `every minute` | `0,1,...,59 * * * *` |
+| `every 5 minutes` | `0,5,10,...,55 * * * *` |
+| `every 10 minutes` | `0,10,20,30,40,50 * * * *` |
+| `every 30 minutes` | `0,30 * * * *` |
+| `every hour` | `0 * * * *` |
+| `every 6 hours` | `0 0,6,12,18 * * *` |
+| `every 12 hours` | `0 0,12 * * *` |
+| `every day` | `0 0 * * *` |
+| `every day at 8am` | `0 8 * * *` |
+| `every day at noon` | `0 12 * * *` |
+| `every day at midnight` | `0 0 * * *` |
+| `every day at 8:30` | `30 8 * * *` |
+| `every weekday` | `0 0 * * 1,2,3,4,5` |
+| `every weekday at 9am` | `0 9 * * 1,2,3,4,5` |
+| `every monday` | `0 0 * * 1` |
+| `every monday at 9am` | `0 9 * * 1` |
+| `every monday through friday at 9am` | `0 9 * * 1,2,3,4,5` |
+| `every friday and saturday at 11pm` | `0 23 * * 5,6` |
+| `every 1st of the month at midnight` | `0 0 1 * *` |
+| `every 15th of the month at noon` | `0 12 15 * *` |
+| `every month on the 1st and 15th at noon` | `0 12 1,15 * *` |
+| `@daily` | `0 0 * * *` |
+| `@weekly` | `0 0 * * 0` |
+| `@monthly` | `0 0 1 * *` |
+| `@hourly` | `0 * * * *` |

data/docs/guides/understanding-cron.md

@@ -0,0 +1,134 @@
+# Understanding Cron and Crontab
+
+`aias` schedules AIA prompts using your operating system's built-in job scheduler: **cron**. This page explains what cron is, how it works, and how `aias` fits into it — so you know what is happening when you run `aias update`.
+
+---
+
+## What Is Cron?
+
+**Cron** is a time-based job scheduler built into every Unix-like operating system (macOS, Linux). It runs in the background at all times, waking up once per minute to check whether any scheduled job is due to run. When one is, cron launches it as a separate process and goes back to sleep.
+
+Cron requires no ongoing configuration once a job is installed. Your Mac does not need to be awake — if the machine is asleep at the scheduled time, cron skips that run and waits for the next one. If you need guaranteed execution even after a missed run, look into `launchd` (macOS) or `systemd` timers (Linux) — but for most prompt scheduling purposes, cron is sufficient.
+
+---
+
+## What Is a Crontab?
+
+**Crontab** (cron table) is the file that lists your scheduled jobs. Each user on the system has their own private crontab. Jobs in your crontab run as you, with your user permissions — they cannot see another user's files or processes.
+
+To view your current crontab:
+
+```bash
+crontab -l
+```
+
+If you have no scheduled jobs yet, this prints nothing (or "no crontab for \<user\>").
+
+A crontab entry looks like this:
+
+```
+0 8 * * * /bin/bash -c 'source ~/.config/aia/schedule/env.sh && aia daily_digest > ~/.config/aia/schedule/logs/daily_digest.log 2>&1'
+```
+
+The five fields before the command are the **schedule expression**.
+
+---
+
+## Reading a Cron Expression
+
+A cron expression is five space-separated fields:
+
+```
+┌─── minute       (0–59)
+│  ┌── hour        (0–23)
+│  │  ┌─ day of month  (1–31)
+│  │  │  ┌ month       (1–12)
+│  │  │  │  ┌ day of week  (0–7, 0 and 7 = Sunday)
+│  │  │  │  │
+*  *  *  *  *   command
+```
+
+An asterisk (`*`) means "every". Common examples:
+
+| Expression | Meaning |
+|---|---|
+| `0 8 * * *` | Every day at 8:00 AM |
+| `0 9 * * 1-5` | Every weekday (Mon–Fri) at 9:00 AM |
+| `30 6 * * 1` | Every Monday at 6:30 AM |
+| `0 */6 * * *` | Every 6 hours |
+| `0 0 1 * *` | The 1st of every month at midnight |
+
+`aias` also accepts natural language — `"every weekday at 9am"` — and converts it to a cron expression automatically using the [fugit](https://github.com/floraison/fugit) gem. Use `aias dry-run` to see the resolved expression before installing.
+
+---
+
+## How aias Manages Your Crontab
+
+`aias` never overwrites your entire crontab. It owns a single marked block, delimited by comments:
+
+```
+# BEGIN aias
+0 8 * * * /bin/bash -c 'source ~/.config/aia/schedule/env.sh && aia daily_digest > ...'
+0 9 * * 1-5 /bin/bash -c 'source ~/.config/aia/schedule/env.sh && aia standup > ...'
+# END aias
+```
+
+Any jobs you have added outside this block — whether written by hand or installed by another tool — are left completely untouched. `aias update` replaces only the content between the markers.
+
+---
+
+## Why Cron Has No Environment
+
+When cron launches a job it starts a new, bare-minimum process. Your shell profile (`~/.zshrc`, `~/.bash_profile`) is **not** sourced. Your `PATH` is reduced to `/usr/bin:/bin`. Your API keys, Ruby version manager shims, and `AIA_*` variables are gone.
+
+This is the single biggest source of cron job failures. A command that works perfectly in your terminal fails silently under cron because `aia` is not on the stripped PATH.
+
+`aias install` solves this once. It captures the critical parts of your live environment — `PATH`, `LANG`, `LC_ALL`, `AIA_*` variables, and `*_API_KEY` keys — and writes them to `~/.config/aia/schedule/env.sh`. Every `aias`-managed cron entry sources that file before running:
+
+```bash
+source ~/.config/aia/schedule/env.sh && aia prompt_id > log 2>&1
+```
+
+See [Cron Environment](cron-environment.md) for the full details on what is captured and how to keep it current.
+
+---
+
+## Crontab Commands You Should Know
+
+| Command | What it does |
+|---|---|
+| `crontab -l` | Print your current crontab to the terminal |
+| `crontab -e` | Open your crontab in `$EDITOR` for manual editing |
+| `EDITOR=nano crontab -e` | Open with a specific editor |
+| `crontab -r` | **Delete your entire crontab** — use with care |
+
+> **Warning:** `crontab -r` removes *everything*, including any non-aias jobs. To remove only the `aias`-managed entries, use `aias clear`.
+
+---
+
+## Checking Whether a Job Ran
+
+Cron itself provides no built-in log viewer. `aias` directs each job's output to a per-prompt log file:
+
+```
+~/.config/aia/schedule/logs/<prompt_id>.log
+```
+
+```bash
+# View the log for a specific job
+cat ~/.config/aia/schedule/logs/daily_digest.log
+
+# Show when a job last ran
+aias last
+
+# Show when a job is next scheduled to run
+aias next
+```
+
+If a job is failing, the log is the first place to look. Common causes and fixes are covered in [Cron Environment — Troubleshooting](cron-environment.md#troubleshooting).
+
+---
+
+## macOS Notes
+
+On macOS, cron is managed by `launchd` and runs continuously in the background — you do not need to start or enable it. However, macOS may show a **Full Disk Access** prompt the first time a cron job runs, because cron does not automatically inherit the permissions granted to your terminal. If a job fails with a permission error, open **System Settings → Privacy & Security → Full Disk Access** and add `/usr/sbin/cron`.

data/docs/guides/validation.md

@@ -0,0 +1,114 @@
+# Validation
+
+Before writing anything to the crontab, `aias` validates every scheduled prompt. This prevents broken cron entries from silently failing at runtime.
+
+## Validation Rules
+
+### 1. Schedule Syntax
+
+The `schedule:` value must be parseable as either a cron expression or a whenever DSL string.
+
+`aias` validates this by evaluating a minimal whenever DSL fragment:
+
+```ruby
+every '0 8 * * *' do
+  command 'true'
+end
+```
+
+**Valid examples:**
+
+```yaml
+schedule: "0 8 * * *"
+schedule: "@daily"
+schedule: "every 1.day at 8:00am"
+schedule: "every :monday at 9:00am"
+schedule: "every 6.hours"
+```
+
+**Invalid examples (fail with an error):**
+
+```yaml
+schedule: "every banana"     # not valid whenever DSL
+schedule: "0 8 *"            # too few cron fields
+schedule: ""                 # empty
+```
+
+### 2. Parameter Completeness
+
+All `parameters:` keys must have non-nil, non-empty default values. Cron jobs run unattended — there is no interactive session to supply missing values.
+
+```yaml
+# VALID — all parameters have defaults
+parameters:
+  topic: "Ruby news"
+  format: "bullet points"
+
+# INVALID — missing default
+parameters:
+  topic:           # nil value — rejected
+  format: ""       # empty string — rejected
+```
+
+### 3. AIA Binary
+
+The `aia` binary must be locatable. Two checks are performed in order; if either succeeds, the prompt passes:
+
+1. **Login-shell `which`** — spawns a login shell and runs `which aia`. This is the normal path when the shell profile initialises the version manager (rbenv, rvm, asdf, etc.).
+
+2. **Fallback directory scan** — if the login-shell check fails (common when `rbenv init` is not in the bash login profile), `aias` scans these directories for an executable named `aia`:
+
+   | Directory | Manager |
+   |---|---|
+   | `~/.rbenv/shims` | rbenv |
+   | `~/.rbenv/bin` | rbenv |
+   | `~/.rvm/bin` | rvm |
+   | `~/.asdf/shims` | asdf |
+   | `/usr/local/bin` | Homebrew / manual |
+   | `/usr/bin` | system |
+   | `/opt/homebrew/bin` | Homebrew (Apple Silicon) |
+
+   Only an **executable** file satisfies the check — a non-executable file at the path is ignored.
+
+If `aia` is not found by either method, **all** prompts fail this check — no jobs are installed.
+
+The check result is cached per `Validator` instance (shell spawn is expensive).
+
+### 4. Prompts Directory
+
+`$AIA_PROMPTS_DIR` must be set, exist, and be readable. This check happens before scanning, not per-prompt. If it fails, `aias` exits immediately with an error.
+
+## Validation Flow
+
+```
+For each prompt file with schedule: in frontmatter:
+  1. Check schedule syntax        → error if invalid
+  2. Check parameter defaults     → error per missing default
+  3. Check aia binary             → error if not found (cached)
+
+  If all checks pass  → prompt is included in install
+  If any check fails  → prompt is skipped, warning to stderr
+```
+
+The crontab write happens only after all valid prompts have been collected. A mix of valid and invalid prompts is handled gracefully — valid ones are installed, invalid ones are skipped.
+
+## Seeing Validation Results
+
+Use `aias check` to see validation results without modifying the crontab:
+
+```bash
+aias check
+```
+
+```
+INVALID (would be skipped by update):
+  bad_prompt: Schedule 'every banana': undefined method 'banana' for Integer
+
+  bad_params: Parameter 'topic' has no default value (required for unattended cron execution)
+```
+
+Use `aias dry-run` to see what the valid prompts would generate:
+
+```bash
+aias dry-run
+```

data/docs/index.md

@@ -0,0 +1,100 @@
+# aias
+
+<table>
+<tr>
+<td width="40%" align="center" valign="top">
+<img src="assets/images/logo.jpg" alt="aias"><br>
+<em>"Schedule. Batch. Execute."</em>
+</td>
+<td width="60%" valign="top">
+<h2>Key Features</h2>
+<ul>
+<li>Natural Language Scheduling</li>
+<li>Zero Configuration</li>
+<li>Reliable Cron Environment</li>
+<li>MCP Server Support</li>
+<li>Per-Prompt Overrides</li>
+<li>Schedule-Specific Config</li>
+<li>Single-Prompt Control</li>
+<li>Full Sync on Update</li>
+<li>Safe Validation</li>
+<li>Rich Inspection Commands</li>
+</ul>
+</td>
+</tr>
+</table>
+
+`aias` turns any AIA prompt into a recurring batch job by reading a `schedule:` key directly from its YAML frontmatter. It scans your prompts directory, validates each scheduled prompt, and installs the results into your crontab.
+
+---
+
+## Commands
+
+```
+$ aias help
+Commands:
+  aias add PATH              # Add (or replace) a single scheduled prompt in the crontab
+  aias check                 # Diff view: scheduled prompts vs what is installed
+  aias clear                 # Remove all aias-managed crontab entries
+  aias dry-run               # Show what `update` would write without touching the crontab
+  aias help [COMMAND]        # Describe available commands or one specific command
+  aias install [PATTERN...]  # Capture PATH, API keys, and env vars into ~/.config/aia/schedule/env.sh
+  aias last [N]              # Show last-run time for installed jobs (default 5)
+  aias list                  # List all installed aias cron jobs
+  aias next [N]              # Show next scheduled run time for installed jobs (default 5)
+  aias remove PROMPT_ID      # Remove a single scheduled prompt from the crontab
+  aias show PROMPT_ID        # Show the installed crontab entry for a single prompt
+  aias uninstall             # Remove managed env block from ~/.config/aia/schedule/env.sh
+  aias update                # Scan prompts, regenerate all crontab entries, and install
+  aias version               # Print the aias version
+
+Options:
+  -p, [--prompts-dir=PROMPTS_DIR]  # Prompts directory (overrides AIA_PROMPTS__DIR / AIA_PROMPTS_DIR env vars)
+```
+
+---
+
+## How It Works
+
+```
+Prompt file with schedule: in YAML frontmatter
+         │
+         ▼
+aias update scans prompts directory for schedule: keys
+         │
+         ▼
+Each prompt is validated: schedule syntax, parameter defaults, aia binary
+         │
+         ▼
+A cron entry is written for each valid prompt
+         │
+         ▼
+OS cron daemon runs each job on schedule:
+  source env.sh && aia [--prompts-dir DIR] prompt_id > log 2>&1
+```
+
+---
+
+## Core Design Principles
+
+**Self-describing prompts.** A prompt that wants to run on a schedule says so in its own frontmatter. No external config file maps prompts to schedules.
+
+**Full sync on every `update`.** The entire managed crontab block is replaced on each run. Deleted or de-scheduled prompts are automatically removed — there are no orphaned entries to clean up manually.
+
+**OS cron reliability.** No long-running daemon. The system cron daemon handles job execution, reboots, and missed runs. Each `aia` invocation is a fresh, clean process.
+
+**Explicit environment capture.** `aias install` snapshots your live PATH, API keys, and AIA variables into `~/.config/aia/schedule/env.sh`. Every cron entry sources that file, giving `aia` the same environment it has in your interactive shell — without relying on a login shell that may rebuild PATH unexpectedly.
+
+---
+
+## At a Glance
+
+```bash
+# Add schedule: to a prompt's frontmatter, then:
+aias update     # install all scheduled prompts into crontab
+aias check      # diff: prompts with schedule: vs what is installed
+aias list       # show all installed jobs
+aias dry-run    # preview what update would write
+```
+
+See the [Quick Start](getting-started/quick-start.md) to get running in under five minutes.