# Artifact Policy

Use this reference before generating previews, reports, send logs, backups, or temporary files.

## Directory Layout

- `runs/YYYYMMDD/<run_id>/`: JSON previews, HTML previews, retry manifests, send logs, and run reports.
- `backups/YYYYMMDD/`: Excel backups created immediately before writing a workbook.
- `logs/`: durable operational ledgers, such as Facebook account daily limits.
- `archives/`: compressed old logs/backups after retention cleanup.
- `.tmp/`: short-lived development or repair scripts; safe to clear after the task ends.
- `dashboards/latest/`: optional stable copy of the latest generated customer dashboard for quick local viewing.

Do not write previews, retry manifests, send logs, or scraper JSON outputs to the project root unless the user explicitly provides an absolute path there.

## Backup Rules

- Create an Excel backup only before a write-enabled operation changes the official workbook.
- Do not create backups for preview, dry-run, HTML rendering, search-only JSON generation, or SMTP send-only operations.
- For the same logical task, pass the same `run_id` and create only one backup per workbook/purpose.
- Keep the official workbook in the project root; put backups under `backups/YYYYMMDD/`.

## Preview and Log Rules

- JSON preview is the main audit artifact.
- HTML preview should reference image files by path by default; avoid repeating base64 image data for every email.
- Use embedded/base64 assets only when the user explicitly asks for a standalone offline HTML file.
- Send logs must be JSONL and must never include SMTP authorization codes.
- Dashboard HTML/JSON files follow preview/report rules: write them under `runs/YYYYMMDD/<run_id>/` by default, and only copy to `dashboards/latest/` when a stable local viewing entry is requested.

## Retention Defaults

- Keep the latest 10 Excel backups per official workbook; keep same-day backups.
- Keep JSON/HTML previews and send logs for 30 days, then move or archive them.
- Keep Facebook account ledger logs for 30 days unless the user asks for a longer audit trail.
- Clear `.tmp` after the task unless a file is still actively needed.

## Cleanup Safety

- Always support dry-run cleanup first.
- Never delete the official workbook, skill package, assets, templates, development MD, or recent backups.
- Prefer moving legacy root artifacts into `runs/legacy_YYYYMM/` or `backups/legacy_YYYYMM/` before deletion when they may be audit-relevant.
