tableau-to-sigma

Tableau → Sigma Conversion

⛔ STEP 0 — MANDATORY environment bootstrap (before any other step)

On the first run on a machine, run the ONE bootstrap command — idempotent, non-interactive, no admin, never echoes credentials:

• macOS / Linux / Git Bash: bash scripts/bootstrap.sh --workdir <WORK>
• Windows PowerShell: powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1 -WorkDir <WORK>

It resolves a supported runtime profile from runtime-capabilities.json, installs only that profile's missing dependencies (user-scoped, never admin), persists credentials with the matching setup script, ends in a doctor run (doctor.json), and writes the bootstrap sentinel (bootstrap.json). Both orchestrators REFUSE to start without sentinel + doctor-green. NEVER hand-install a runtime or edit PATH yourself — if bootstrap reports no admin-free route, surface its message to the user and stop. Dry run: --check / -Check. Details: refs/environment.md.

⛔ STEP 1 — THE ONE PATH (a single entry point; do not improvise one)

After the bootstrap, always run the orchestrator — it chains every phase in one process and self-gates:

# Use the entrypoint selected in doctor.json:
ruby scripts/migrate-tableau.rb --workbook "<name>" --connection <id>
# or, when selectedProfile=python:
python3 scripts/migrate-tableau.py --workbook "<name>" --connection <id> …

• Pass the Tableau /#/views/… share URL straight to --workbook (quote it). The orchestrator resolves the workbook LUID from the URL's contentUrl slug in process. Display names diverge from slugs, so never hand-roll name:eq: filters or page the workbook list — that field-cost a 500-workbook scan. Give it the URL.
• Flag cheatsheet — use the EXACT flags for the selected entrypoint: migrate-tableau.rb --out DIR (the workdir flag is --out, not --workdir); migrate-tableau.py --out DIR uses the same workdir flag; validate-spec.rb <spec.json> --type dm|workbook (spec is a positional arg, no --spec); put-layout.rb --workbook ID (not --workbook-id), reading SIGMA_API_TOKEN from the env.
• Do NOT hand-drive the per-phase scripts or hand-author DM/workbook JSON UNLESS an orchestrator STOP explicitly routes you there (e.g. "CONVERTER STOP", the exit-4 handoff). The script map is not a menu — à-la-carte scripts are the #1 way runs go inconsistent.
• "Done" is not something you decide — it is a file on disk. The migration is complete only when the selected runtime's completion gate (verify-complete.rb or verify-complete.py) exits 0 / prints ✅ DONE. A clean PASS 1 (exit 12) is NOT done — it means "run --finalize". Never report success or write a completion summary before. Completion also requires complete accounting: every formula in formula-audit.json and every object in source-object-census.json has one terminal disposition in MIGRATION_REPORT.md / migration-result.json.
• This is a PRODUCTION migration, not a demo. The bar is EXACT parity against the same warehouse, always. At a wall: follow the printed STOP/handoff, or surface the blocker plainly and stop — NEVER a third "lighter/simplified" path; only the user may descope. Verbatim rule: refs/operating-contract.md §Never negotiate fidelity down.
• An orchestrator STOP is an instruction to YOU (the agent), not a handoff to a human — keep going. A routing exit authorizes you to do the next step yourself and re-enter the gated spine; the only finish line is verify-complete.rb exit 0. Verbatim rule: refs/gates.md.
• At the exit-4 handoff, PATCH the auto-built <WORK>/wb-spec.json — do NOT rewrite it (a from-scratch rewrite drifts controlIds and fails control-lint wholesale — the #1 way this handoff spirals; prefer --master-col for master-level calcs). Full handoff discipline: refs/gates.md §Exit-4.
• Credentials: the orchestrator stops at step 0 telling you to run the selected runtime's scripts/setup.rb or scripts/setup.py once — do that rather than working around auth (refs/environment.md §Credentials).