inboxos-v1/docs/operator-tutorial.md

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.