Rendered view of COMMANDS.md. Read it as a page; the download link gives you the raw Markdown working file.

Download COMMANDS.md

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

# 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

# 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

# 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)

# 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.

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:

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

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

# 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.

# 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

# 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

# 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.

# 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

# 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

# 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.