aias 0.1.0

data/docs/cli/install.md

@@ -0,0 +1,198 @@
+# aias install
+
+Capture your current shell environment into `~/.config/aia/schedule/env.sh` so scheduled jobs can find `aia`, authenticate with LLM APIs, and reach any MCP servers your prompts depend on.
+
+```bash
+aias install [PATTERN...]
+```
+
+Run this once after installing `aias`, and again any time your environment changes.
+
+---
+
+## What It Does
+
+1. Reads a set of environment variables from the current shell process (see [Default Variables](#default-variables) below)
+2. Writes them as `export KEY="value"` lines into `~/.config/aia/schedule/env.sh`, wrapped in `# BEGIN aias-env` / `# END aias-env` markers
+3. Creates `~/.config/aia/schedule/` if it does not exist
+4. Copies `~/.config/aia/aia.yml` to `~/.config/aia/schedule/aia.yml` if that file does not yet exist (first run only)
+5. Sets file permissions on `env.sh` to `0600` (owner read/write only)
+
+The generated `env.sh` is sourced at the start of every cron entry `aias` installs:
+
+```bash
+source ~/.config/aia/schedule/env.sh && aia --config ... prompt_id > log 2>&1
+```
+
+---
+
+## Default Variables
+
+The following groups are captured automatically on every `aias install`, with no pattern argument required.
+
+### `PATH`
+
+```bash
+export PATH="/Users/you/.rbenv/shims:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin"
+```
+
+**Why it is needed:** Cron's default `PATH` is `/usr/bin:/bin` — nothing else. The `aia` binary lives in a gem bin directory under a Ruby version manager shim path. MCP server binaries (Node packages, Homebrew-installed tools) live in `/opt/homebrew/bin` or similar locations. Without the full `PATH`, every scheduled job would fail immediately with `command not found`.
+
+`PATH` is captured from your live shell at install time, when rbenv, asdf, or your version manager is already activated. This is why `aias install` must be run from an interactive terminal, not from a cron job itself.
+
+### `*_API_KEY` (all variables ending in `_API_KEY`)
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+export OPENAI_API_KEY="sk-..."
+export GEMINI_API_KEY="..."
+export OPENROUTER_API_KEY="..."
+```
+
+**Why they are needed:** Cron does not inherit your interactive shell's exports. Any variable you set in `.bashrc`, `.zshrc`, or in a terminal session is not available to cron unless it is explicitly written to a file that cron sources. Without the API key for the LLM provider your prompt uses, AIA cannot authenticate and every scheduled prompt run will return an authentication error.
+
+The pattern `*_API_KEY` is broad by design — it captures keys for all LLM providers at once (Anthropic, OpenAI, Google, Together, OpenRouter, and any others you have set), so you do not need to list them individually.
+
+### `AIA_*` (all variables starting with `AIA_`)
+
+```bash
+export AIA_PROMPTS__DIR="/Users/you/.prompts"
+export AIA_MODEL="claude-haiku-4-5"
+export AIA_FLAGS__VERBOSE="false"
+```
+
+**Why they are needed:** AIA's runtime behaviour is controlled through `AIA_*` environment variables. The most important is `AIA_PROMPTS__DIR`, which tells AIA where to find prompt files. Without it, AIA cannot resolve a prompt ID like `daily_digest` to an actual file, and the job fails with a "file not found" error.
+
+Other `AIA_*` variables set defaults that you may have tuned in your interactive shell — model selection, output format flags, backend adapter settings. Capturing the entire `AIA_*` group ensures the scheduled environment matches your interactive environment as closely as possible.
+
+### `LANG` and `LC_ALL`
+
+```bash
+export LANG="en_US.UTF-8"
+export LC_ALL="en_US.UTF-8"
+```
+
+**Why they are needed:** When neither `LANG` nor `LC_ALL` is set, Ruby defaults to `US-ASCII` encoding. AIA prompt files, LLM responses, and log output routinely contain UTF-8 characters (curly quotes, em dashes, emoji, non-English text). Without a UTF-8 locale, Ruby raises `Encoding::UndefinedConversionError` and the job fails mid-run with a cryptic encoding error. Setting these variables ensures Ruby uses UTF-8 for all string operations.
+
+---
+
+## Capturing Additional Variables with Patterns
+
+Pass one or more glob patterns as arguments to capture variables beyond the defaults:
+
+```bash
+aias install 'PATTERN'
+aias install 'PATTERN_1' 'PATTERN_2'
+aias install 'PATTERN_1 PATTERN_2'   # space-separated in a single argument
+```
+
+Patterns are matched case-insensitively. The default groups (`PATH`, `*_API_KEY`, `AIA_*`, `LANG`, `LC_ALL`) are always included — patterns only add to them.
+
+### MCP Server Variables
+
+If your scheduled prompts use MCP servers, those servers often need their own credentials or configuration variables. Cron will not have these unless you explicitly capture them.
+
+**GitHub MCP server**
+
+The GitHub MCP server (`github-mcp-server`) requires a personal access token to authenticate with the GitHub API:
+
+```bash
+aias install 'GITHUB_*'
+```
+
+This captures variables like `GITHUB_TOKEN`, `GITHUB_PERSONAL_ACCESS_TOKEN`, and `GITHUB_API_KEY` — whichever your GitHub MCP server configuration expects. Without the token, any scheduled prompt that calls GitHub tools (reading issues, listing repositories, searching code) will receive an authentication error from the GitHub API.
+
+**Homebrew MCP server**
+
+The Homebrew MCP server (`brew mcp-server`) may read Homebrew-specific configuration variables:
+
+```bash
+aias install 'HOMEBREW_*'
+```
+
+This captures `HOMEBREW_PREFIX`, `HOMEBREW_CELLAR`, `HOMEBREW_REPOSITORY`, and any `HOMEBREW_*` variables you have set. Without them, the brew MCP server may fail to locate its own installation or behave differently than it does in your interactive shell.
+
+**Combining patterns**
+
+Install all at once in a single command:
+
+```bash
+aias install 'GITHUB_*' 'HOMEBREW_*'
+```
+
+Or add them to an existing `env.sh` incrementally — each `aias install` rewrites only the managed block, so running it multiple times with different patterns is safe. The last run wins for any variable that appears in more than one pattern.
+
+**Other MCP servers**
+
+The same principle applies to any MCP server that reads credentials or configuration from the environment. Check the documentation for each MCP server you use to identify its required environment variables, then add the appropriate pattern to your `aias install` command.
+
+| MCP server | Variables to capture | Pattern |
+|---|---|---|
+| github-mcp-server | `GITHUB_TOKEN`, `GITHUB_PERSONAL_ACCESS_TOKEN` | `'GITHUB_*'` |
+| brew mcp-server | `HOMEBREW_PREFIX`, `HOMEBREW_CELLAR`, etc. | `'HOMEBREW_*'` |
+| OpenRouter | `OPEN_ROUTER_API_KEY` | captured by default (`*_API_KEY`) |
+| crimson | Check crimson's documentation | `'CRIMSON_*'` |
+| Custom MCP server | Depends on implementation | `'YOUR_SERVER_*'` |
+
+---
+
+## Example Output
+
+```
+aias: installed AGENTQL_API_KEY, AIA_FLAGS__VERBOSE, AIA_MODEL, AIA_PROMPTS__DIR,
+  ANTHROPIC_API_KEY, GEMINI_API_KEY, GITHUB_TOKEN, HOMEBREW_PREFIX,
+  LANG, LC_ALL, OPENAI_API_KEY, PATH into ~/.config/aia/schedule/env.sh
+```
+
+---
+
+## The Schedule Config
+
+On the first run, if `~/.config/aia/aia.yml` exists and `~/.config/aia/schedule/aia.yml` does not, `aias install` copies your interactive AIA config to the schedule directory as a starting point:
+
+```
+aias: copied ~/.config/aia/aia.yml → ~/.config/aia/schedule/aia.yml
+
+Review ~/.config/aia/schedule/aia.yml — these settings apply to all scheduled prompts.
+Prompt frontmatter overrides any setting in that file.
+```
+
+**Important:** edit `schedule/aia.yml` after this copy. Your interactive config almost certainly has settings that are wrong for unattended cron jobs — MCP servers you do not want loaded for every scheduled run, verbose output flags, or editor-specific settings. The schedule config should be a minimal, conservative baseline. See [Configuration Layering](../guides/configuration-layering.md) for guidance.
+
+If `schedule/aia.yml` already exists, `aias install` leaves it untouched.
+
+---
+
+## Updating env.sh
+
+Re-run `aias install` (with any patterns you need) whenever:
+
+- You rotate or add an API key
+- You install a new MCP server binary
+- You change your Ruby version or version manager configuration
+- You add or change an `AIA_*` variable in your shell profile
+- You set up a new MCP server that needs its own credentials
+
+The managed block in `env.sh` is replaced atomically on each run. Content you have written outside the markers is preserved.
+
+---
+
+## Viewing the Captured Environment
+
+```bash
+cat ~/.config/aia/schedule/env.sh
+```
+
+---
+
+## Options
+
+`aias install` accepts no named options — only the optional glob pattern arguments described above.
+
+---
+
+## See Also
+
+- [`aias uninstall`](uninstall.md) — remove the managed env block from `env.sh`
+- [Cron Environment](../guides/cron-environment.md) — how `env.sh` solves the cron PATH problem
+- [Configuration Layering](../guides/configuration-layering.md) — how `env.sh`, the schedule config, and prompt frontmatter combine at runtime

data/docs/cli/last.md

@@ -0,0 +1,49 @@
+# aias last
+
+Show the last-run time for installed jobs.
+
+```bash
+aias last [N]
+```
+
+The command is also accessible as `aias last_run` (the Ruby method name).
+
+## Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `N` | `5` | Maximum number of jobs to show |
+
+## Output
+
+```
+daily_digest
+  schedule : every day at 8am (0 8 * * *)
+  last run : 2026-03-23 08:00:01 -0500
+  log      : /Users/you/.aia/schedule/logs/daily_digest.log
+
+reports/weekly
+  schedule : every Monday at 9am (0 9 * * 1)
+  last run : never run
+  log      : /Users/you/.aia/schedule/logs/reports/weekly.log
+
+(Pass N as argument to show N entries. Last-run time is derived from the log file modification timestamp.)
+```
+
+When no jobs are installed:
+
+```
+aias: no installed jobs
+```
+
+## Notes
+
+**Last run time** is derived from the log file's modification timestamp. If the log file does not exist, `never run` is shown.
+
+Use [`aias next`](next.md) to see when each job is next scheduled to run.
+
+## See Also
+
+- [`aias next [N]`](next.md) — next scheduled run time for installed jobs
+- [`aias list`](list.md) — tabular view of installed jobs
+- [`aias show PROMPT_ID`](show.md) — details for a single job

data/docs/cli/list.md

@@ -0,0 +1,40 @@
+# aias list
+
+Print all currently installed aias cron jobs.
+
+```bash
+aias list
+```
+
+## Output
+
+```
+PROMPT ID                       SCHEDULE                                  LOG
+----------------------------------------------------------------------------------------------------
+daily_digest                    every day at 8am (0 8 * * *)              /Users/you/.aia/schedule/logs/daily_digest.log
+reports/weekly                  every Monday at 9am (0 9 * * 1)           /Users/you/.aia/schedule/logs/reports/weekly.log
+```
+
+When no jobs are installed:
+
+```
+aias: no installed jobs
+```
+
+## Columns
+
+| Column | Description |
+|---|---|
+| `PROMPT ID` | Full subpath relative to `$AIA_PROMPTS_DIR`, without the `.md` extension |
+| `SCHEDULE` | Human-readable description with raw cron expression in parentheses, e.g. `every day at 8am (0 8 * * *)` |
+| `LOG` | Absolute path to the log file for this job |
+
+## Notes
+
+`list` reads directly from the crontab — it shows what is actually installed, not what the current prompt files declare. Use [`aias check`](check.md) to see whether the installed jobs match the current prompt files.
+
+## See Also
+
+- [`aias check`](check.md) — diff between prompts and installed jobs
+- [`aias show PROMPT_ID`](show.md) — details for a single job
+- [`aias next`](next.md) — schedule and last-run information

data/docs/cli/next.md

@@ -0,0 +1,49 @@
+# aias next
+
+Show the next scheduled run time for installed jobs.
+
+```bash
+aias next [N]
+```
+
+The command is also accessible as `aias upcoming` (the Ruby method name, since `next` is a reserved keyword).
+
+## Arguments
+
+| Argument | Default | Description |
+|---|---|---|
+| `N` | `5` | Maximum number of jobs to show |
+
+## Output
+
+```
+daily_digest
+  schedule : every day at 8am (0 8 * * *)
+  next run : 2026-03-24 08:00:00 -0500
+  log      : /Users/you/.aia/schedule/logs/daily_digest.log
+
+reports/weekly
+  schedule : every Monday at 9am (0 9 * * 1)
+  next run : 2026-03-30 09:00:00 -0500
+  log      : /Users/you/.aia/schedule/logs/reports/weekly.log
+
+(Pass N as argument to show N entries.)
+```
+
+When no jobs are installed:
+
+```
+aias: no installed jobs
+```
+
+## Notes
+
+**Next run time** is computed from the installed cron expression using the `fugit` gem.
+
+Use [`aias last`](last.md) to see when each job last ran.
+
+## See Also
+
+- [`aias last [N]`](last.md) — last-run time for installed jobs
+- [`aias list`](list.md) — tabular view of installed jobs
+- [`aias show PROMPT_ID`](show.md) — details for a single job

data/docs/cli/remove.md

@@ -0,0 +1,87 @@
+# aias remove
+
+Remove a single scheduled prompt's cron job from the crontab.
+
+```bash
+aias remove PROMPT_ID
+```
+
+Aliases: `aias rm PROMPT_ID`, `aias delete PROMPT_ID`
+
+---
+
+## What It Does
+
+Finds the cron entry for `PROMPT_ID` inside the `aias`-managed crontab block and removes it. All other installed jobs — both `aias`-managed and user-managed — are left untouched.
+
+Exits with an error if `PROMPT_ID` is not currently installed.
+
+## When to Use `remove` vs `clear` vs `update`
+
+| Goal | Command |
+|---|---|
+| Remove one specific job | `aias remove PROMPT_ID` |
+| Remove all aias-managed jobs | `aias clear` |
+| Remove jobs for prompts that no longer have `schedule:` | `aias update` (full sync) |
+
+`remove` is the right command when you want to unschedule a single prompt and leave everything else alone. It does not require the prompt file to exist — you can use it to clean up an orphaned entry after the file has already been deleted.
+
+## Example Output
+
+**Success:**
+
+```
+aias: removed daily_digest
+```
+
+**Not installed:**
+
+```
+aias [error] 'daily_digest' is not currently installed
+```
+
+## Finding the Prompt ID
+
+Use `aias list` to see the exact ID strings for all installed jobs:
+
+```bash
+aias list
+# PROMPT ID                       SCHEDULE              LOG
+# ------------------------------  --------------------  ---
+# daily_digest                    every day at 8am      ...
+# reports/weekly                  every monday at 9am   ...
+```
+
+Then remove by that ID:
+
+```bash
+aias remove daily_digest
+aias remove reports/weekly
+```
+
+## Removing an Orphaned Entry
+
+If you deleted a prompt file without first running `aias remove` or `aias update`, the crontab entry persists as an orphan. Use `aias check` to see it, then `aias remove` to clean it up:
+
+```bash
+aias check
+# ORPHANED (installed but no longer scheduled):
+#   - reports/weekly
+
+aias remove reports/weekly
+# aias: removed reports/weekly
+```
+
+## Exit Codes
+
+| Code | Condition |
+|---|---|
+| `0` | Job removed successfully |
+| `1` | Prompt ID not installed, or crontab write error |
+
+## See Also
+
+- [`aias add PATH`](add.md) — add a single job (the inverse operation)
+- [`aias list`](list.md) — see installed prompt IDs
+- [`aias check`](check.md) — identify orphaned entries
+- [`aias clear`](clear.md) — remove all aias-managed entries at once

data/docs/cli/show.md

@@ -0,0 +1,54 @@
+# aias show
+
+Show the installed crontab entry for a single prompt.
+
+```bash
+aias show PROMPT_ID
+```
+
+## Arguments
+
+| Argument | Description |
+|---|---|
+| `PROMPT_ID` | The prompt ID as it appears in `aias list` (full subpath, no `.md` extension) |
+
+## Output
+
+```bash
+aias show daily_digest
+```
+
+```
+prompt_id : daily_digest
+schedule  : every day at 8am (0 8 * * *)
+log       : /Users/you/.aia/schedule/logs/daily_digest.log
+```
+
+For a nested prompt:
+
+```bash
+aias show reports/weekly
+```
+
+```
+prompt_id : reports/weekly
+schedule  : every Monday at 9am (0 9 * * 1)
+log       : /Users/you/.aia/schedule/logs/reports/weekly.log
+```
+
+## Error
+
+When the prompt ID is not found in the crontab, `show` prints a message and exits 1:
+
+```
+aias: 'nonexistent' is not currently installed
+```
+
+## Notes
+
+`show` reads from the installed crontab, not from the prompt files. A prompt must have been installed via `aias update` before it appears.
+
+## See Also
+
+- [`aias list`](list.md) — all installed jobs
+- [`aias check`](check.md) — compare installed vs scheduled

data/docs/cli/uninstall.md

@@ -0,0 +1,29 @@
+# aias uninstall
+
+Remove the `aias`-managed environment block from `~/.config/aia/schedule/env.sh`.
+
+```bash
+aias uninstall
+```
+
+Aliases: `aias unins`
+
+---
+
+## What It Does
+
+Strips the `# BEGIN aias-env` / `# END aias-env` block from `env.sh`. If the file becomes empty after removal it is deleted. Content you have written outside the markers is preserved.
+
+The schedule configuration (`~/.config/aia/schedule/aia.yml`) and installed cron jobs are not touched. To remove the cron jobs themselves use [`aias clear`](clear.md).
+
+## Example Output
+
+```
+aias: env vars removed from ~/.config/aia/schedule/env.sh
+      ~/.config/aia/schedule/ is unchanged
+```
+
+## See Also
+
+- [`aias install`](install.md) — capture or refresh the environment block
+- [`aias clear`](clear.md) — remove all aias-managed crontab entries

data/docs/cli/update.md

@@ -0,0 +1,75 @@
+# aias update
+
+Full sync: scan all prompts, validate, and install every scheduled prompt as a cron job.
+
+```bash
+aias update
+```
+
+## What It Does
+
+1. Scans `$AIA_PROMPTS_DIR` recursively for files containing `schedule:` in their frontmatter
+2. Parses the YAML frontmatter of each candidate file via `PM::Metadata`
+3. Validates each scheduled prompt (schedule syntax, parameter defaults, `aia` binary)
+4. Builds a `whenever` DSL string for each valid prompt
+5. Combines all DSL strings and calls `whenever` to replace the entire `aias`-managed crontab block
+
+## Output
+
+```
+aias: installed 3 job(s)
+```
+
+When some prompts are invalid:
+
+```
+aias: installed 2 job(s), skipped 1 invalid
+```
+
+Invalid prompts are printed to stderr:
+
+```
+aias [skip] bad_prompt: Schedule 'every banana': ...
+```
+
+When no valid prompts are found:
+
+```
+aias: no valid scheduled prompts found — crontab not changed
+```
+
+## Full Sync Semantics
+
+Every `update` replaces the **entire** `aias`-managed crontab block. This means:
+
+- Prompts that had their `schedule:` line removed are automatically uninstalled
+- Schedule changes take effect on the next `update`
+- No manual cleanup of orphaned entries is ever required
+
+Non-aias crontab entries are never touched.
+
+## Error Handling
+
+| Condition | Behaviour |
+|---|---|
+| `AIA_PROMPTS_DIR` not set or missing | Exits 1 with an error message |
+| Crontab write fails | Exits 1 with an error message |
+| Invalid schedule syntax | Skips the prompt, warns to stderr |
+| Missing parameter defaults | Skips the prompt, warns to stderr |
+| `aia` binary not found | Skips all prompts, warns to stderr |
+
+## Options
+
+| Option | Alias | Description |
+|---|---|---|
+| `--prompts-dir PATH` | `-p` | Use PATH instead of `AIA_PROMPTS__DIR` / `AIA_PROMPTS_DIR` |
+
+```bash
+aias --prompts-dir ~/work/prompts update
+```
+
+## See Also
+
+- [`aias dry-run`](dry-run.md) — preview without writing
+- [`aias check`](check.md) — see what would change
+- [Scheduling Prompts](../guides/scheduling-prompts.md) — schedule format reference

data/docs/getting-started/installation.md

@@ -0,0 +1,69 @@
+# Installation
+
+## Requirements
+
+| Requirement | Notes |
+|---|---|
+| Ruby | >= 3.2.0 |
+| `aia` gem | Must be installed and reachable via `which aia` in your login shell |
+| `AIA_PROMPTS_DIR` | Environment variable pointing to your AIA prompts directory |
+
+## Install the Gem
+
+```bash
+gem install aias
+```
+
+Or add it to your project's `Gemfile`:
+
+```ruby
+gem "aias"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Verify Prerequisites
+
+`aias update` will validate that `aia` is reachable and that `AIA_PROMPTS_DIR` is set. You can check manually first:
+
+```bash
+# Confirm aia is in your login shell PATH
+bash -l -c "which aia"
+
+# Confirm AIA_PROMPTS_DIR is set and points to a real directory
+echo $AIA_PROMPTS_DIR
+ls "$AIA_PROMPTS_DIR"
+```
+
+If `aia` is not found, install it:
+
+```bash
+gem install aia
+```
+
+## Set AIA_PROMPTS_DIR
+
+Add to your shell profile (`.bashrc`, `.zshrc`, etc.):
+
+```bash
+export AIA_PROMPTS_DIR="$HOME/.prompts"
+```
+
+Reload your shell or source the file:
+
+```bash
+source ~/.zshrc   # or ~/.bashrc
+```
+
+## Verify the Installation
+
+```bash
+aias --version
+aias help
+```
+
+`aias help` lists all available commands with descriptions.