# Scheduler Mail Skill Contract

Portable Scheduler project and Session identity ownership is defined in
[`../id_management.md`](../id_management.md).

This document defines the product contract for scheduler jobs that create
Oysterun Mail reports.

## Canonical Flow

Scheduler jobs must generate a durable HTML report file first, then send that
file through the Oysterun Mail product command.

```bash
$OYSTERUN_CLI_BIN mail send \
  --title "Daily report" \
  --html-file data/latest_report.html
```

Use `$OYSTERUN_CLI_BIN` when Host injects it into a live session or scheduler
run. Bare `oysterun` can resolve to an older globally installed package and
must not be used when the injected binary is available.

## Mail Body Contract

Mail writes are HTML-only.

Required payload shape:

```json
{
  "body_format": "html",
  "body_html": "<html or fragment>"
}
```

The deliverable must be a file path ending in `.html`.

Rejected inputs:

- markdown bodies
- `body_format=markdown`
- `body_format=auto`
- `--text`
- `--body`
- stdin body content
- `OYSTERUN_CLI_TEXT`
- non-`.html` files
- direct Host `/mail/*` calls from agents

The Mail database may keep legacy columns such as `body_markdown`, but new
product writes must not use them.

## Scheduler Guidance

Scheduler prompts and scripts should:

1. produce the report file, for example `data/latest_report.html`;
2. verify the file exists and is non-empty;
3. call the Mail product command with `--html-file`;
4. avoid printing capability tokens, auth headers, raw profiles, or secrets;
5. use scheduler run logs and Mail item creation as product evidence.

For GitHub Tracker, the expected command is:

```bash
uv run tasks/repo_crawler_rich.py --days 1
```

The script publishes one report deliverable and updates its Website landing
page:

```text
.oysterun/site/reports/latest_report.html
.oysterun/site/index.html
```

It sends the report file, not a second generated body, through Oysterun Mail.
The CLI, Host route, and Mail store preserve that HTML source exactly rather
than trimming it. This permits a byte-for-byte comparison between the Website
report and `mail_items.body_html` for the same scheduler run.

## Skill Sources

The Mail and Scheduler product skills must carry the same contract in all
mirrors:

```text
skills/oysterun-mail
skills/Oysterun/modules/oysterun-mail
skills/oysterun-scheduler
skills/Oysterun/modules/oysterun-scheduler
host-service/assets/product-skills/oysterun-mail
host-service/assets/product-skills/Oysterun/modules/oysterun-mail
host-service/assets/product-skills/oysterun-scheduler
host-service/assets/product-skills/Oysterun/modules/oysterun-scheduler
```

After changing skill sources, run:

```bash
node tool_scripts/sync_product_skills_to_codex.mjs
node tool_scripts/check_product_skill_mirrors.mjs
```