# Today-Hero proposal tooling

Daily-build pipeline for the editorial Today-Hero card in Studio's store.
See `../../docs/today-pipeline.md` for the full design rationale.

## Quick start

```bash
# 1. Generate today's proposals (calls the local Ollama by default).
./propose.sh

# 2. Skim them — they sit under ~/.fai/today/proposals/<ISO-DATE>/
ls ~/.fai/today/proposals/

# 3. Accept one. The chosen file becomes ~/.fai/today/active.yaml,
#    which Studio reads at startup.
./accept.sh ~/.fai/today/proposals/2026-05-08/candidate-2.yaml

# 4. Restart Studio (or let the next launch pick it up).
```

## Schedule it

### macOS — launchd

```bash
# Drop a plist that runs propose.sh every morning at 07:30 local time.
# `launchctl load ~/Library/LaunchAgents/ai.flemming.chain.today.plist` to
# install. The plist must point at the absolute path of propose.sh.
```

A starter plist lives at `launchd/ai.flemming.chain.today.plist`.

### Linux — systemd timer

```bash
# Copy systemd/fai-today.{service,timer} into ~/.config/systemd/user/,
# then `systemctl --user enable --now fai-today.timer`.
```

### Anywhere — cron

```cron
30 7 * * * /Users/flemming/.../tools/today/propose.sh > /tmp/fai-today.log 2>&1
```

## Provider override

`propose.sh` defaults to Ollama at `http://127.0.0.1:11434` with the model
`gemma3:4b`. Override via env vars:

| Variable          | Default                          | Example                                         |
|-------------------|----------------------------------|-------------------------------------------------|
| `FAI_TODAY_API`   | `http://127.0.0.1:11434/api/generate` | `https://api.openai.com/v1/chat/completions` |
| `FAI_TODAY_MODEL` | `gemma3:4b`                      | `gpt-4o-mini`                                   |
| `FAI_TODAY_KEY`   | (unset)                          | `$OPENAI_API_KEY`                               |
| `FAI_TODAY_N`     | `3`                              | `1` (single shot)                               |

OpenAI-compatible endpoints will work as long as they speak `chat/completions`
or `generate`; the script auto-detects from the URL path.

## Trust model

- Reads only `git log`, `git diff`, and the bundled `seed.yaml` of
  installed Ch∆In monorepos. Never your audit log without explicit op-in.
- Calls only the System-AI you've already configured for Studio. The same
  privacy mode you set there applies here.
- Writes only into `~/.fai/today/`. Nothing in `~/.fai/data/` or
  `~/.fai/config.yaml` is touched.
- Studio loads `active.yaml` at startup; if the file is missing or fails
  schema validation, the compiled-in fallback story renders. KRITIS
  fresh installs see the fallback until and unless an operator accepts a
  proposal.