feat(scripts): quickstart.sh + docs/quickstart.md — 15-min green-field spin-up (REQ-INB-40)

---ci---
project: inboxos
phase: 1
milestone: v1.4
status: execute
wave: 2
task: T1
---/ci---

docs/operations-runbook.md

@@ -84,6 +84,8 @@ The **reverse proxy** (Caddy in the commented-out `caddy` service in `docker/doc
 
 All workflows live in `.gitea/workflows/`. They are declarative, version-controlled in the same repo as the scripts they invoke, and have no separate runtime state to back up. This is the board decision recorded in [INB-8](/INB/issues/INB-8) — n8n was ruled out as unreliable.
 
+**Quickstart:** for a 15-minute green-field spin-up, see `docs/quickstart.md` and `scripts/quickstart.sh` (REQ-INB-40). The script runs the 8 steps below in sequence and prints the runbook §X.Y cross-ref on any failure.
+
 ### 3.1 Live pipeline — `live-pipeline.yml`
 
 | Aspect         | Value                                                                                       |

docs/quickstart.md

@@ -0,0 +1,24 @@
+# InboxOS Quickstart
+
+A 15-minute green-field operator spin-up.
+
+## Steps
+
+1. Run `scripts/quickstart.sh` from the inboxos repo root.
+2. The script will:
+   - Verify `docker` + `docker compose` are installed
+   - Pull the inboxos Docker images
+   - Generate `.env` from `.env.example` (edit with your secrets)
+   - Bring up the stack (`docker compose up -d`)
+   - Wait for NocoDB healthcheck
+   - Run `scripts/apply_schemas.py` to bootstrap the 4 module tables + `papra_index`
+   - Seed a 1-test `.mbox` and run `pipelines/historical_pipeline.py` to verify the extract path
+3. On success, login to NocoDB at http://localhost:8080.
+
+## Next
+
+For a 30-minute end-to-end walkthrough, see `docs/operator-tutorial.md` (REQ-INB-53).
+
+For the per-step details, see `docs/operations-runbook.md` §3 (Workflow operations).
+
+For failure recovery, see the runbook §5 + the ERROR-NN catalog (REQ-INB-46).

scripts/quickstart.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# scripts/quickstart.sh — 15-minute green-field operator spin-up.
+#
+# v1.4 REQ-INB-40.
+#
+# Steps:
+#   1. Verify docker + docker compose are installed
+#   2. Pull the inboxos images
+#   3. Generate a .env from .env.example (with operator-supplied secrets)
+#   4. Bring up the stack (docker compose up -d)
+#   5. Wait for NocoDB healthcheck
+#   6. Run apply_schemas.py to bootstrap the 4 module tables + papra_index
+#   7. Seed a 1-test .mbox and run historical_pipeline.py
+#   8. Print success line
+#
+# On any failure, print the failed step + runbook §X.Y cross-ref.
+#
+set -euo pipefail
+
+readonly STEPS=(
+  "1. Verify docker + docker compose"
+  "2. Pull inboxos images"
+  "3. Generate .env from .env.example"
+  "4. Bring up the stack"
+  "5. Wait for NocoDB healthcheck"
+  "6. Run apply_schemas.py"
+  "7. Seed 1-test .mbox + run historical pipeline"
+  "8. Print success line"
+)
+
+ok() { printf "  ✅ %s\n" "$1"; }
+err() { printf "  ❌ %s\n" "$1" >&2; printf "  See: docs/operations-runbook.md §%s\n" "$2" >&2; exit 1; }
+
+# 1. docker + docker compose
+if ! command -v docker >/dev/null 2>&1; then
+  err "docker not found" "2.1 (Service inventory)"
+fi
+if ! docker compose version >/dev/null 2>&1; then
+  err "docker compose not found" "2.1 (Service inventory)"
+fi
+ok "${STEPS[0]}"
+
+# 2. Pull images
+if ! docker compose -f docker/docker-compose.yml pull 2>/dev/null; then
+  err "docker compose pull failed" "5.5 (Ollama / NocoDB image pull)"
+fi
+ok "${STEPS[1]}"
+
+# 3. Generate .env if missing
+if [[ ! -f .env ]]; then
+  if [[ -f .env.example ]]; then
+    cp .env.example .env
+    printf "  ⚠️  .env created from .env.example — edit it with your secrets before production use.\n"
+  else
+    err ".env.example not found" "6.1 (Secret inventory)"
+  fi
+fi
+ok "${STEPS[2]}"
+
+# 4. Bring up the stack
+docker compose -f docker/docker-compose.yml up -d
+ok "${STEPS[3]}"
+
+# 5. Wait for NocoDB
+for i in {1..30}; do
+  if docker compose -f docker/docker-compose.yml exec -T nocodb curl -sf http://localhost:8080/api/v1/health >/dev/null 2>&1; then
+    break
+  fi
+  sleep 2
+done
+ok "${STEPS[4]}"
+
+# 6. Run apply_schemas.py
+if ! python3 scripts/apply_schemas.py 2>/dev/null; then
+  err "apply_schemas.py failed" "5.3 (Schema bootstrap)"
+fi
+ok "${STEPS[5]}"
+
+# 7. Seed 1-test .mbox and run historical pipeline
+if [[ ! -f tests/fixtures/single.mbox ]]; then
+  mkdir -p tests/fixtures
+  cat > tests/fixtures/single.mbox <<'EOF'
+From: test@example.com
+To: operator@inboxos.local
+Subject: Quickstart test
+Date: Mon, 01 Jan 2024 00:00:00 +0000
+Message-ID: <quickstart-test@local>
+
+Quickstart test body.
+EOF
+fi
+if ! python3 pipelines/historical_pipeline.py --mbox tests/fixtures/single.mbox 2>/dev/null; then
+  err "historical_pipeline.py failed" "5.5 (Pipeline extract)"
+fi
+ok "${STEPS[6]}"
+
+# 8. Print success
+ok "${STEPS[7]}"
+printf "\n✅ Quickstart complete — operator can now login to http://localhost:8080 (NocoDB).\n"
+printf "Next: read docs/operator-tutorial.md for the full 30-min walkthrough.\n"