# Capstone starter pack — AI tagging on R2, the NAS and OpenRouter

The starter pack for the capstone: design and prototype the next phase of the
campus media unit's catalogue. Add AI tagging to **5,000 assets**, with a
governance rule, inside a fixed monthly budget, using:

- **Cloudflare R2** for the canonical catalogue and tags (private) and the
  thumbnails (public, behind `media.<root>`);
- the **Nextcloud/RAID NAS** as the local origin and backup for the 5,000
  originals;
- the **S4 Worker**, extended with a tag-ingest route, as the catalogue API and
  the write gate;
- **OpenRouter** as the governed managed-inference path.

You choose the tagging method — managed inference, the fine-tuned Qwen3.5-4B, or
the S10 classifier — and justify it in the proposal. Every implementation
includes one refused and one accepted governed OpenRouter request, and every
record passes the Worker's gate.

This pack is a starting point, not the answer: replace the canned offline stub
with your method, extend the rule's vocabulary, and build your own evidence.

## Architecture — what each piece does

```
        originals + backup                    canonical catalogue + tags
   ┌──────────────────────────┐          ┌──────────────────────────────┐
   │  Nextcloud on RAID1 NAS  │          │  private R2: capstone-       │
   │  /srv/nas/nextcloud      │          │  catalogue (Worker binding)  │
   └────────────┬─────────────┘          └──────────────┬───────────────┘
                │ rclone backup                          │ validated writes
                ▼                                        │
   ┌──────────────────────────┐          ┌──────────────┴───────────────┐
   │  private R2 backup       │          │  Worker: /health, /assets,   │
   │  capstone-nas-backup     │          │  /asset/:id, /ingest/tags    │
   └──────────────────────────┘          └──────────────┬───────────────┘
                                                        │ reads tags
   ┌──────────────────────────┐          ┌──────────────┴───────────────┐
   │  tag.py (laptop/Droplet) │─────────▶│  OpenRouter, ZDR + deny      │
   │  preflight → batch 100   │  governed │  data_collection, no         │
   │  → validate → post       │  request  │  fallbacks                   │
   └──────────────────────────┘          └──────────────────────────────┘
```

| Piece | Holds | Visibility |
|---|---|---|
| `capstone-catalogue` (R2) | `catalogue.json`, `tags.json`, private files | Worker binding only |
| `capstone-media-public` (R2) | `thumbs/*.png` | public, R2 custom domain `media.<root>` |
| NAS `/srv/nas` | the 5,000 originals, Nextcloud data | private network, `nas.<root>` |
| Worker `capstone-catalogue` | API + ingest gate | `workers.dev` or a custom domain |
| `tag.py` | the pipeline and its checkpoints | your laptop or the Droplet |

Two R2 buckets, because an R2 custom domain exposes **every key** in the bucket
it is attached to. Public thumbnails and the private catalogue cannot share one.

## What to run, in what order

[`COMMANDS.md`](COMMANDS.md) is the authoritative sequence: every command, in
order, with an explanation. The short version for the local profile:

```bash
python3 -m unittest discover -s tests
npm install && npm test
python3 generate_assets.py --count 5000 --seed 20261113 --out data/library
python3 strip_exif.py --check data/library
bash run.sh                       # the full local reference run
```

`run.sh` is the verified reference: it starts the Worker locally, seeds the
emulated R2 bucket, tags through the gate, proves the gate refuses a bad
record, reconciles the budget, verifies the evidence and writes a sanitized
log. The learner still types each command from `COMMANDS.md` and observes it.

## Files

| File | Purpose |
|---|---|
| `governance-rule.json` | The S8 six-part rule plus `tag_schema` and `ingest`; the single source the Worker and pipeline both read |
| `generate_assets.py` | Seeded 5,000-asset generator: catalogue, 400 px PNGs, labels, 200-asset holdout, hashes |
| `tag.py` | Preflight, batches of 100, checkpoint/resume, local validation, Worker post, failure log, monthly batch, review sample |
| `reconcile.py` | Reconciles actuals against the $80 spine and the $5/$10 envelopes |
| `reconcile.ipynb` | The same reconciliation as a notebook |
| `budget.csv` | The monthly spine and the capstone's actual lines, with a basis and note per line |
| `strip_exif.py` | Checks or strips EXIF before an image leaves the laptop |
| `scripts/sanitize_log.py` | Removes tokens, account IDs, emails and keys from a log |
| `src/index.js` | The S4 Worker extended with `POST /ingest/tags` and rule validation |
| `test/worker.test.js` | 14 Worker tests, including the gate's refusals |
| `tests/test_capstone.py` | 18 Python tests for the generator, pipeline, budget, EXIF and sanitizer |
| `compose.yaml`, `Caddyfile`, `.env.example` | The S5 Nextcloud/MariaDB/Redis/Caddy NAS stack |
| `compose.local.yaml` | The laptop fallback stack on port 8080 |
| `up.sh`, `down.sh` | Open and close the bounded 72-hour window; write the teardown log |
| `run.sh` | The verified reference runner |
| `verify.sh` | The machine proof over the evidence bundle |
| `COMMANDS.md` | Every command with an explanation |

## The ten-item evidence bundle

1. The generated manifest: seed, count, generator hash, catalogue hash.
2. The tag output (`tags.jsonl`, `report.json`): schema validity, coverage, and
   every failed asset in `failures.jsonl`.
3. Worker proof: `/health`, `/asset/:id` with tags, `/assets?tag=<tag>`, the
   refused record and the accepted governed write.
4. Governance: the rule file, the dated endpoint snapshot, the refused and
   accepted OpenRouter requests, and the 10% sample-review sheet.
5. NAS proof: RAID1 status, originals in Nextcloud, the `rclone` backup and the
   restore checksum.
6. One measured 40-item monthly batch and its run-rate projection.
7. Cost actuals: OpenRouter usage, the DigitalOcean balance and bill, R2 usage,
   reconciled against $5 and $80; no-auto-top-up proof.
8. The budget sheet: forecast versus actuals, with every delta explained.
9. The sanitized command log, `COMMANDS.md` and your runner.
10. The teardown log and the final balance, with the no-resources-running check.

## Budget

| Line | Monthly spine | Capstone actual | Why |
|---|---:|---:|---|
| Storage | $25 | ≈ $0.20 | 20 GiB of block storage for 72 hours; R2 stays in the free tier |
| Compute and CDN | $25 | ≈ $2.36 | one `s-2vcpu-4gb` Droplet for 72 hours; Workers and CDN are free |
| Egress | $15 | $0.00 | R2 egress is free |
| Inference | $5 | measured | the 40-item monthly batch projected to 40/month |
| Buffer | $10 | $10.00 | held, not spent |
| **Total** | **$80** | **≈ $12.56 + inference** | the bounded window, not a month of Droplet |

The $12.56 is the envelope, including the $10 the buffer holds back; cash spend
is about $2.56 plus the measured inference line. `budget-reconciliation.json`
reports both `actual_total_usd` and `spent_usd` so the distinction is explicit.

The one-off backfill is capped at the **$10** OpenRouter credit carried from S8,
separately from the monthly line. `python3 reconcile.py --check` exits non-zero
if inference exceeds $5, the total exceeds $80, or the backfill exceeds $10.

## Governance

`governance-rule.json` is the S8 rule extended for the capstone:

- **Part 1:** synthetic/public/internal data only; real personal or sensitive
  media never leaves the laptop.
- **Part 2:** names, emails, phones, student IDs, GPS, device and timestamp
  metadata are removed before any request (`strip_exif.py` checks images).
- **Part 3:** the endpoint must satisfy the rule — `zdr: true`,
  `data_collection: "deny"`, `allow_fallbacks: false` — and the pipeline refuses
  to start if the dated snapshot has no qualifying endpoint.
- **Part 4–5:** no in-region route on the student plan; nothing retained.
- **Part 6:** a 10% sample is reviewed; exceptions are approved in writing.

The Worker's ingest route validates every record against `tag_schema` and
`ingest` and writes nothing if any record fails. The refused and accepted pair
in `data/run/govern-pair.json` is the evidence, not an assertion.

## The 72-hour window

Cloud resources run in a bounded window: `up.sh` opens it (and refuses a second
window while one is live), `down.sh` closes it, and both write timestamps to
`data/run/teardown.log`. The window is why the compute and storage lines are
window costs, not a month's Droplet. Deleting the Droplet does not delete its
volumes; deleting an R2 bucket does not remove a DNS record. `COMMANDS.md`
section K lists both checks.

## Fallback chain

Every fallback keeps the evidence shape and earns full points when labelled:
`workers.dev` + `r2.dev`; the instructor demo bucket + `wrangler dev --local`;
`compose.local.yaml` for the NAS; a free-tier or instructor OpenRouter key; the
classifier on MPS/CPU. A fallback that changes the evidence shape is a defect.

## Safety

Synthetic media only. No real people, client footage, brands or personal data.
Never commit `.env`, `.dev.vars` or a token; `chmod 600` both. Sanitize the log
before publishing it. The generated labels are the generator's ground truth and
must not be read by a managed pipeline; the canned stub reads them and is
labelled `canned` in the report.
