# Commands — the capstone starter pack, in order

This is the command-transparency source for the capstone. Run each command
individually, in this order, and read its output before moving on. The
instructor's runner (`run.sh`) executes the same sequence end-to-end and writes
a sanitized log; a command the runner executes but this file omits is a defect.

Placeholders: `<root>` is your registered domain, `<sub>` your `workers.dev`
subdomain, `<droplet-ip>` the Droplet's public address, `$ZONE_ID` the
Cloudflare zone ID. Never paste a token, a secret or an account ID into a file
that reaches the evidence bundle.

Two profiles:

- **Local profile** (sections A–H, J): everything runs on your laptop; the
  Worker runs under `wrangler dev --local` and the R2 binding is emulated. This
  is the fallback and the quick path; it proves the pipeline and the gate.
- **Cloud profile** (sections D, I, K): the same pipeline against a deployed
  Worker, a Droplet NAS and the real R2 buckets. The 72-hour window applies
  here. Every substitution is labelled in the evidence note.

## A. Pre-flight — prove the toolchain and read the rule

```bash
# The pack needs Python 3.14 or newer. It uses only the standard library, so
# there is nothing to pip install and no runtime download.
python3 --version

# The Worker tests need Node 22.12 or newer; current Wrangler refuses older
# releases.
node --version
npm --version

# Read the governance rule before running anything. Parts 1-6 are the S8 rule;
# `tag_schema` and `ingest` add the tag vocabulary and the gate's record shape.
# Change the model, vocabulary or controls here, then redeploy the Worker so the
# gate and the pipeline read the same file.
cat governance-rule.json
```

## B. Run the tests before trusting the pipeline

```bash
# 18 Python tests: the generator's determinism and schema, the canned
# pipeline, resume, the Worker-rejection stop, preflight, the monthly batch,
# the review sample, EXIF stripping, the sanitizer and the budget envelopes.
python3 -m unittest discover -s tests

# Install the Worker's pinned dev dependencies (Wrangler and Vitest). The lock
# file fixes the versions.
npm install

# 14 Worker tests: the S4 routes plus the ingest gate — auth, a compliant
# accept, a policy refusal, a schema refusal, a managed accept and batch
# atomicity. All must pass before a deployment is worth doing.
npm test
```

## C. Generate the 5,000-asset library

```bash
# Create 5,000 seeded 400 px PNGs, the catalogue in the spine's schema, the
# generator's labels and the 200-asset holdout. The same seed and count produce
# byte-identical files: this is the evidence's generator hash.
python3 generate_assets.py --count 5000 --seed 20261113 --out data/library

# Read the manifest. `catalogue_sha256` and `generator_sha256` are evidence
# item 1; `holdout` is 200 for a 5,000-asset run.
cat data/library/manifest.json

# Count the thumbnails and the catalogue records. Both must be 5,000.
find data/library/thumbs -name '*.png' | wc -l
python3 -c "import json; print(len(json.load(open('data/library/catalogue.json'))))"

# Assert that no generated image carries EXIF metadata before anything leaves
# the laptop. The generator writes clean PNGs; this is the preflight assertion
# the governance rule's part 2 requires.
python3 strip_exif.py --check data/library
```

The generator's labels are its own ground truth. The canned mode below reads
them, so it proves orchestration, not tagging quality; never present a canned
run as managed inference.

## D. Start the Worker and seed its bucket (local profile)

```bash
# Receive the generated catalogue and the tag output in the private bucket.
# Locally the R2 binding is emulated; the first object put creates the bucket.
npx wrangler r2 object put capstone-catalogue/catalogue.json \
  --file data/library/catalogue.json --local

# Seed an empty tag store. Re-running the pipeline overwrites entries by
# asset id, so a fresh run starts from a known state.
printf '{}\n' > data/run/empty-tags.json
npx wrangler r2 object put capstone-catalogue/tags.json \
  --file data/run/empty-tags.json --local

# Create the Worker secrets for the local run. `INGEST_TOKEN` authenticates the
# pipeline; `SIGNING_KEY` signs the private-original capability. `.dev.vars` is
# gitignored and chmod 600.
python3 -c "import secrets; print('INGEST_TOKEN=' + secrets.token_hex(24))" > .dev.vars
python3 -c "import secrets; print('SIGNING_KEY=' + secrets.token_hex(32))" >> .dev.vars
chmod 600 .dev.vars

# Start the Worker on port 8787. Leave it running for sections E and F.
npx wrangler dev --local --port 8787

# In a second terminal, prove the Worker reads the catalogue: 5,000 assets.
curl -sS http://127.0.0.1:8787/health
```

Cloud profile instead of `wrangler dev`: create the two buckets, upload the
catalogue, deploy, set the secrets and (optionally) attach the custom domain.

```bash
npx wrangler r2 bucket create capstone-media-public
npx wrangler r2 bucket create capstone-catalogue
npx wrangler r2 object put capstone-catalogue/catalogue.json \
  --file data/library/catalogue.json --remote
npx wrangler deploy
npx wrangler secret put INGEST_TOKEN
npx wrangler secret put SIGNING_KEY
curl -sS https://capstone-catalogue.<sub>.workers.dev/health
```

The public thumbnails go to `capstone-media-public` under `thumbs/`. Uploading
5,000 files one at a time with Wrangler is slow; use the `rclone` remote from S5
and sync the directory:

```bash
rclone sync data/library/thumbs r2:capstone-media-public/thumbs
```

## E. Run the tagging pipeline through the gate (canned, offline)

```bash
# Tag all 5,000 in checkpointed batches of 100. Every record is validated
# locally against the same rule, then posted to the Worker's ingest route; the
# Worker validates again and writes accepted records to tags.json.
INGEST_TOKEN="$(grep '^INGEST_TOKEN=' .dev.vars | cut -d= -f2)" \
python3 tag.py --mode canned \
  --catalogue data/library/catalogue.json \
  --labels data/library/labels/generated.json \
  --out data/run --worker-url http://127.0.0.1:8787

# Read the report: 5,000 tagged, coverage 1.0, failures 0, gate worker.
cat data/run/report.json

# Query the tags through the Worker. One asset, then every asset with a tag.
curl -sS http://127.0.0.1:8787/asset/asset-0001
curl -sS 'http://127.0.0.1:8787/assets?tag=mug'

# Prove the gate refuses a non-compliant record. The expected status is 422,
# and the bad record is not written.
curl -sS -o data/run/gate-refusal.json -w '%{http_code}\n' \
  -X POST http://127.0.0.1:8787/ingest/tags \
  -H "authorization: Bearer $(grep '^INGEST_TOKEN=' .dev.vars | cut -d= -f2)" \
  -H 'content-type: application/json' \
  -d '{"records":[{"asset_id":"asset-0001","tags":["not-in-the-vocabulary"],"caption":"x","method":"canned","policy":{"egress":false},"model":null,"endpoint":null,"tagged_at":"2026-11-13T00:00:00Z"}]}'
```

A crash or a stopped run resumes from `data/run/checkpoint.json`: re-run the
same command and it tags only the missing assets. Every failure is appended to
`data/run/failures.jsonl`; it is never invented or silently dropped.

## F. The governed managed path (live, one pair first)

The design requires one refused request and one accepted policy-compliant
request, both recorded, before any full managed run. The snapshots in `data/`
are the dated fallback; refresh them if the date is stale.

```bash
# Refresh the endpoint snapshots. The ZDR list names the endpoints that meet
# zero-retention terms; the model list names every endpoint, including the
# first-party one the refusal pins.
curl -sS https://openrouter.ai/api/v1/endpoints/zdr -o data/endpoints-zdr.json
curl -sS https://openrouter.ai/api/v1/models/google/gemini-4-hydrogen/endpoints \
  -o data/endpoints-gemini.json

# Make the pair: a pinned non-ZDR endpoint refuses (4xx), then the same model
# with zdr/data_collection/allow_fallbacks enforced succeeds (200). The pair is
# written to data/run/govern-pair.json.
python3 tag.py --mode openrouter --model google/gemini-4-hydrogen \
  --snapshot data/endpoints-zdr.json --model-snapshot data/endpoints-gemini.json \
  --govern-pair --out data/run

# Read the pair. A success on the refused call, or a failure on the governed
# call, stops the run: the rule is not being enforced.
cat data/run/govern-pair.json

# Then the managed run, all 5,000 through the same gate. This spends real
# credit: the 40-item projection and the $5 line decide whether it fits.
OPENROUTER_API_KEY=... python3 tag.py --mode openrouter \
  --model google/gemini-4-hydrogen --snapshot data/endpoints-zdr.json \
  --out data/run --worker-url http://127.0.0.1:8787
```

Swap `--model` and the snapshot for the model your rule names. The pipeline
refuses to start if the ZDR list has no live endpoint for that model.

## G. The measured monthly batch and the budget

```bash
# The pipeline writes data/run/monthly-batch.json: the measured cost of the
# first 40 items projected to the 40-per-month run-rate, against $5.
cat data/run/monthly-batch.json

# Reconcile every line against the $80 spine. The compute and storage lines are
# window costs, not a month's droplet; the notes say so. `--check` exits non-zero
# if inference > $5, the total > $80 or the backfill > $10.
python3 reconcile.py --budget budget.csv --run data/run --check

# Read the result, including the delta explanation.
cat data/run/budget-reconciliation.json
```

## H. Review the 10% sample

```bash
# The pipeline writes one review row for every ten tagged assets (500 rows for
# 5,000). Open it and mark each row: keep or fix. The schema and coverage
# checks cover the other 90%; this sample is the quality check.
head -20 data/run/review-sample.csv
```

## I. The NAS, the 72-hour window, backup and restore (cloud profile)

The NAS is the S5 four-service Compose stack: Caddy, Nextcloud 35, MariaDB and
Redis on a two-volume mdadm RAID1 at `/srv/nas`. Build the array and the stack
with the S5 lab's commands (RAID1, mount, Compose, the proxied `nas.<root>`
record); the capstone adds the window, the originals and the backup.

```bash
# Open the window and start the stack. The script refuses a second window while
# one is live; the deadline is written to data/run/window.json.
PROFILE=remote bash up.sh

# Read the window and the services.
cat data/run/window.json
docker compose -f compose.yaml ps

# Copy the 5,000 originals into Nextcloud. Use the Nextcloud web UI or rclone
# with the NAS remote; the library on the laptop is the source.
rclone copy data/library rclone:nextcloud/capstone-library

# Back the NAS up to a private R2 bucket. The bucket is private: it is the
# backup, never a public hostname.
rclone sync /srv/nas/nextcloud r2:capstone-nas-backup

# Restore drill: copy one file back, compare hashes, and record both.
rclone copy r2:capstone-nas-backup/<one-file> /tmp/restore-check
sha256sum /tmp/restore-check/<one-file> /srv/nas/nextcloud/<one-file>

# Close the window and stop the stack. The teardown is logged.
PROFILE=remote bash down.sh
cat data/run/teardown.log
```

For the laptop fallback, `PROFILE=local bash up.sh` starts
`compose.local.yaml` on port 8080 with bind mounts under `data/nas`; label it
as the local NAS substitute in the evidence.

## J. Verify the evidence

```bash
# The machine proof: catalogue and thumbnail counts, hashes, tag coverage and
# schema validity, the Worker gate, the monthly batch, the budget envelopes,
# the review sample, the teardown log and the secret scan. Exits non-zero on
# the first mismatch.
bash verify.sh data/run

# Sanitize the raw log before it travels with the evidence: tokens, account
# IDs, emails and private keys are removed. Check the result.
python3 scripts/sanitize_log.py data/run/run.log
python3 scripts/sanitize_log.py --check data/run/run.sanitized.log
```

## K. Teardown — close every resource and prove it

```bash
# Remove the Worker and its secrets, then the objects and both buckets.
npx wrangler delete --name capstone-catalogue
npx wrangler r2 object delete capstone-catalogue/catalogue.json --remote
npx wrangler r2 object delete capstone-catalogue/tags.json --remote
npx wrangler r2 bucket delete capstone-catalogue
npx wrangler r2 bucket delete capstone-media-public

# Remove the custom domain and the DNS records through the Cloudflare panel or
# `doctl`/API; a deleted bucket does not remove a DNS record you added.
# Cloudflare → DNS → delete the media/nas records.

# Terminate the Droplet and every volume. A deleted Droplet does not delete its
# volumes.
doctl compute droplet list
doctl compute droplet delete <droplet-id>
doctl compute volume list
doctl compute volume delete <volume-id>

# Confirm the balances and that nothing is left running.
doctl compute droplet list --format ID,Name,Status
doctl balance get
```

Append each deletion to `data/run/teardown.log` with the UTC timestamp. The
evidence item is the log plus the final balance, not an assertion.

## L. Fallback chain — same evidence shape, full points

| Missing | Substitute | What the note must say |
|---|---|---|
| No active zone | `workers.dev` plus the `r2.dev` public bucket URL | the custom-domain step is substituted |
| No R2 subscription | the instructor demo bucket for the live proof, `wrangler dev --local` for the run | which bucket served the proof |
| No Droplet | `compose.local.yaml` on the laptop | the NAS is a local substitute; the RAID claim is not made |
| No OpenRouter card | a free-tier call pair or the instructor key | which key ran the pair; the $0.00 cost line |
| No GPU | the classifier on MPS or CPU | the device and the slower run time |
| Managed API blocked | 500 assets tagged plus a costed plan for 5,000 | it is a fallback, not a full run |

A fallback that changes the evidence shape is a defect. Label every
substitution in the 150–250-word note and in the evidence bundle's index.
