# InboxOS — Operator Tutorial (30-minute walkthrough)

A guided tour for the new operator. Read top-to-bottom; each chapter takes ~5-10 minutes.

## Chapter 1: Setup (5 min)

Goal: get a working InboxOS instance on your laptop.

1. Clone the repo: `git clone https://git.cloudinit.dev/jc-capital/inboxos.git && cd inboxos`
2. Run `scripts/quickstart.sh` (REQ-INB-40). The script pulls Docker images, generates `.env`, brings up the stack, and runs a 1-message smoke test.
3. Login to NocoDB at http://localhost:8080.
4. See the 4 module tables in the left-nav: `finance`, `crm`, `intel`, `promotions`.

Next: see `docs/operations-runbook.md §3.1` (Live pipeline) for the production setup.

## Chapter 2: First run (5 min)

Goal: process a real .mbox file end-to-end.

1. Get a sample .mbox (or use `tests/fixtures/single.mbox` from the repo).
2. Run `python pipelines/historical_pipeline.py --mbox /path/to/file.mbox`.
3. Watch the JSONL events stream to stderr.
4. In NocoDB, look for the row in the appropriate module table.
5. Check the 4 curated views (REQ-INB-41) in the left-nav.

Next: see `docs/extraction-contract.md` for the prompt contract.

## Chapter 3: Day-to-day (10 min)

Goal: monitor the live pipeline and use the operator tools.

1. The live pipeline runs on `cron */5 * * * *` via `.gitea/workflows/live-pipeline.yml`. Check Gitea Actions for the last run.
2. Run `scripts/dashboard.py` (REQ-INB-50) for an at-a-glance terminal view.
3. To find a specific email, use `scripts/find_email.py --mid <Message-ID>` (REQ-INB-43) or `--sender`.
4. To inspect a recent run in detail, use `scripts/explain_run.py` (REQ-INB-42) or `scripts/explain_run.py --json | jq`.
5. To see monthly costs, run `scripts/cost_report.py --month 2026-06` (REQ-INB-54).

Next: see `docs/operations-runbook.md §4` (Observability).

## Chapter 4: Incident response (5 min)

Goal: recover from a stuck or failed run.

1. If something is broken, start at the ERROR-NN catalog (REQ-INB-46) at `docs/operations-runbook.md §5`.
2. The 10 ERROR-NN codes map 1:1 to the §5.X subsections.
3. To replay failed/skipped MIDs, use `scripts/replay.py --status errored --confirm` (REQ-INB-45).
4. To reclassify a MID into a different module, use `scripts/reclassify.py --mid <MID> --new-module crm --confirm` (REQ-INB-44).
5. If the smoke test fails on a fresh install, the runbook §5 has the recovery procedure per failure mode.

Next: see `docs/operations-runbook.md §5.7` (Backup and restore).

## Chapter 5: Hardening (5 min)

Goal: understand the v1.4 product-grade security posture.

1. Container hardening (REQ-INB-55): all 6 services run with `read_only: true` (or `tmpfs: [/tmp]` for write-required services), `cap_drop: [ALL]`, and `security_opt: no-new-privileges`. See `docker/docker-compose.yml`.
2. PII-scrub (REQ-INB-57): SSN, credit-card, IBAN, and phone numbers are masked before the email body is sent to Ollama. The audit trail is in `_artifacts/pii_scrub.jsonl`.
3. Secret redaction (REQ-INB-56): all 9 secret env vars are auto-masked in CI logs via `::add-mask::`.
4. DPIA (REQ-INB-58): see `docs/security/dpia.md` for the GDPR Art. 35 data protection impact assessment.
5. Threat model (REQ-INB-59): see `docs/security/threat-model.md` for the STRIDE-per-component decomposition.

Next: see `docs/security/dpia.md` and `docs/security/threat-model.md`.