Detailed script usage

AtelierBID ships ten slash-command skills and 32 deterministic Node CLIs covering the complete Power BI build lifecycle. All capabilities described here are runnable now.

Phase A · Start a project & cross-cutting spine#

Phase B · Discovery & data acquisition#

Phase C · Model & data#

Phase D · Calculation#

Reachable from a session via /AtelierBID:author-dax (batch measure authoring from plain English, a spec file, or explicit DAX, with a per-measure scoreboard) and /AtelierBID:optimise-dax (ranked anti-pattern findings with confirmation-gated rewrites).

Phase E · Design & report#

Phase F · AI#

Reachable from a session via /AtelierBID:update-metadata, which audits the model then fills both display metadata (format strings, display folders, sort-by, hidden keys) and Q&A metadata (descriptions, synonyms, linguistic schema, verified answers). Writes are dry-run with a diff first.

Phase G · Documentation#

Reachable from a session via /AtelierBID:document-model — read-only, so it carries no confirmation gate and is safe to run repeatedly, including in CI.

The design phase ends with a deterministic pipeline that takes a composed report layout to a real PBIR report page without re-authoring. The bridge is a single shared mockup IR — a self-describing, deterministic JSON contract (schemaVersion 1.0, kind atelierbid/mockup-ir, additive-only). Both the human-facing previews and the PBIR converter read the same IR, so what a stakeholder approves is exactly what gets generated.

flowchart LR
    M["model.json / brief"] --> C["design-report.js --compose"]
    C --> IR["shared mockup IR<br/>(grid · KPI strip · visuals + rationale)"]
    IR --> MH["--emit-mockup → HTML mockup<br/>(IR embedded in a script block)"]
    IR --> PR["prototype-report.js --ir<br/>→ interactive Chart.js prototype"]
    PR --> EIR["--emit-ir → approved IR (byte-identical)"]
    EIR --> PBIR["design-report.js --from-ir --pbip<br/>→ structurally-valid PBIR page in the PBIP"]
    IR --> PBIR

1. Compose (design-report.js --compose) lays visuals out on a grid — a KPI strip, a visual hierarchy, and a per-visual visual-type choice (bar / line / map / table / donut / scatter, …) with a plain-English rationale derived from each visual's data shape.
2. Apply tokens (--apply-tokens, optional) resolves design-system tokens and background zones to concrete hex/font values.
3. Review as an HTML mockup (--emit-mockup) and/or an interactive prototype (prototype-report.js), both reading the embedded IR.
4. Convert (design-report.js --from-ir <ir.json> --pbip <project>) writes a structurally-valid PBIR report page into the PBIP.

Offline-first caveat: the interactive prototype loads Chart.js from a CDN — the single optional network dependency, needed only to view the prototype HTML. The PBIR generation path is fully offline.

All scripts below are deterministic, offline Node CLIs (the skills call them internally; they also run standalone). None use the clock, randomness, or the network.

Foundation CLIs (Phase A)#

• new-project.js — node scripts/new-project.js --name "<report name>" [--dry-run] [--force]. Sanitises the report name into a safe folder (refuses .. traversal — ADR-0007), writes a templated CLAUDE.md, seeds _00-Best-Practice/, folds in a validated PBIP container, and scaffolds _00-Artifacts/. --dry-run previews and writes nothing.
• scaffold-pbip.js / validate-pbip.js — emit an openable PBIP tree; validate structure with plain-English pass/fail. scaffold-pbip.js --merge --pbip <Name.pbip> --add-artefact measure|table --name <X> adds an artefact to an existing PBIP. The validator is an offline proxy for "opens in Desktop" (ADR-0004) and also validates TMDL (--tmdl, --model) and mockup IR (--ir).
• best-practice.js — scaffold / update / audit / sync a structured rule library (bp_*.md with stable BP-<AREA>-NNN ids) and emit BestPracticeRules.json in BPA shape.
• ground-schema.js — load (gate: refuses generation until a contract loads), off-schema refs surface as proposals (never fabrications), bootstrap from existing TMDL, --trace-out for traceability, re-ground on change.
• lifecycle.js / conformance-harness.js — mode (offline floor, --override tier1 per-invocation only — ADR-0008), create-artifact --bind ask, resolve-grounding, manual publish (reports execution: none); the harness flags drift against the canonical PBIR/TMDL shape.

Discovery & source-text authoring (Phase B)#

discover-requirements.js — capture a semantic model's requirements from a non-interactive answers file:

node scripts/discover-requirements.js --answers answers.json --out spec.json [--trace] [--check-gaps]

--trace stamps each item with a stable REQ-NNN id; --check-gaps warns about holes (e.g. missing grain) on stdout, exiting 0 — a gap is a warning, not a failure (ADR-0011).

author-sql.js — author review-only SQL for a Power BI context. Emit-only: writes text, never connects to or runs a database (ADR-0012).

node scripts/author-sql.js --table Sales --context directquery --out q.sql
#   --context : source | native | directquery | endpoint
#   --dialect : tsql (default) | ansi | postgres | databricks | snowflake
node scripts/author-sql.js --check-file query.sql --dialect tsql   # static parse, no emit

author-m.js — author review-only Power Query / M for a TMDL partition source. Emit-only: writes M text, never opens Power BI or evaluates M (ADR-0013).

node scripts/author-m.js --transforms "rename,filter,changeType,removeColumns" --out common.m --validate
node scripts/author-m.js --transforms "addIndexColumn" --check-folding --out fold.m
node scripts/author-m.js --native-sql "SELECT * FROM dbo.Sales" --ir-column OrderDate --out ir.m --validate

Model CLIs (Phase C)#

• model-star-schema.js — --describe "<text>" --out <dir> [--validate] [--preview] [--report-json]. Heuristic plain-English → TMDL. --validate runs an offline structural TMDL parse; --preview writes DDL + a Mermaid ER diagram.
• model-relationships.js — infers safe relationships by shared-key naming, with star-safe many→one defaults, bidirectional opt-in (warned), offline cycle/ambiguity detection, and role-playing-dimension handling.
• model-settings.js — emits deliberate, uniform table/column settings (summarisation, hidden keys, sort-by, uniform column grouping with a built-in catalogue fallback).
• model-partition.js — deterministic row-threshold recommendation (1M+ rows + a date-like grain), emitting the date range as an IR-template partition.
• model-incremental-refresh.js — emits refreshPolicy + RangeStart/RangeEnd params and a foldable filter.
• optimise-model.js — read-only static scan over TMDL with numeric severity ranking; only safe, result-preserving fixes are written (ADR-0021).

Calculation CLIs (Phase D)#

• author-dax.js — emits idiomatic measures and calculation groups in TMDL, hosted in a dedicated _Measures table (ADR-0006).
• dax-time-intelligence.js — binds to a marked date table, emitting a contiguous calculated CALENDAR() date table with fiscal-year / ISO-week semantics.
• optimise-dax.js — applies a closed set of equivalence-preserving rewrites; write-back is gated behind --apply, dry-run by default (ADR-0025).
• dax-query.js — emits review-only EVALUATE queries with human metadata in comment lines, offline structural validation, and two-block equivalence pairs.

Design CLIs (Phase E)#

• design-system.js — CLI over the authoritative token file data/design-system.json:

``bash node scripts/design-system.js --validate --schema data/design-system.json node scripts/design-system.js --resolve --feature theme --set accent=#FF8800 ``

• build-theme.js — deterministic, schema-valid theme.json:

``bash node scripts/build-theme.js --brand "#2A6FDB,#E8743B" --out ./theme --colors 10 --rag "#2D6CDF,#0D9488,#D63031" ``

Data colours are nudged apart for ΔE ≥ 15 separation from the reserved RAG status roles.

• check-palette.js — flags data colours perceptually too close to the RAG roles:

``bash node scripts/check-palette.js --in theme.json --min-delta-e 15 ``

• validate-theme-schema.js — validate a theme.json against the Power BI template schema:

``bash node scripts/validate-theme-schema.js --in theme.json ``

• reconcile-dummy-data.js — cross-check dummy data vs schema; rescale breakdown totals to KPIs:

``bash node scripts/reconcile-dummy-data.js --data dummy.json --schema model.json ``

• generate-background.js — page-size-exact, grid-aligned, token-driven background:

``bash node scripts/generate-background.js --page-size 1280x720 --grid 16 --out bg.json node scripts/generate-background.js --page-size 1280x720 --out bg.json --pbip /path/to/project --explain ``

• design-report.js — compose a report page, emit the mockup IR/HTML, apply tokens, and convert an approved IR into PBIR:

``bash node scripts/design-report.js --compose --out page.json --model model.json --theme design-system.json node scripts/design-report.js --compose --emit-mockup mockup.html --apply-tokens node scripts/design-report.js --from-ir approved-ir.json --pbip /path/to/project ``

• prototype-report.js — render one self-contained interactive HTML prototype from the shared IR:

``bash node scripts/prototype-report.js --out ./prototype --sample node scripts/prototype-report.js --ir composed-ir.json --out ./prototype --emit-ir approved-ir.json ``

The prototype HTML loads Chart.js from a CDN — viewing it needs internet; generating it does not.

AI-readiness CLI (Phase F)#

ai-readiness.js — turns a bare TMDL model into a Copilot/Q&A-ready one. A "model" is a directory of *.tmdl table files. Every sub-command exits 0 on a successful pass — gaps are reported in the artefact content, not via a non-zero exit.

node scripts/ai-readiness.js audit --model ./model --out audit.json
node scripts/ai-readiness.js enrich --model ./model --out ./enriched
node scripts/ai-readiness.js linguistic --model ./model --out linguistic-schema.json
node scripts/ai-readiness.js hygiene --model ./model --out ./hygiene
node scripts/ai-readiness.js verified-answers --model ./model --out verified-answers.json

Fabric data-agent CLI (Phase F)#

fabric-agent.js — emits the complete provisioning kit for a Microsoft Fabric data agent over an AI-ready model. No clock / RNG / network.

node scripts/fabric-agent.js --emit-config --out ./agent
node scripts/fabric-agent.js --emit-runbook --out ./agent
node scripts/fabric-agent.js --model ./enriched --out ./agent     # config + runbook, grounded

Documentation CLI (Phase G)#

document-model.js — generates a regenerable data-dictionary markdown from the TMDL, with gaps flagged:

node scripts/document-model.js --model ./model --out data-dictionary.md

Shared design libraries (scripts/lib/)#

• mockupIr.js — the shared mockup-IR contract.
• composeLayout.js — deterministic grid composition: KPI strip + visual hierarchy.
• chooseVisualType.js — data-shape → visual-type selection with rationale.
• irToPbir.js — converts the mockup IR into a structurally-valid PBIR page.
• applyTokens.js — resolves design-system tokens to concrete values.
• colorMath.js — CIE76 ΔE, HSL/RGB conversions.
• themeBuilder.js — builds and template-validates theme.json.
• designSystem.js — single loader/validator/resolver for data/design-system.json.

See also#

• Overview — the package at a glance.
• Commands — the canonical skill table and script inventory.
• Architecture — how it's structured and how data flows.
• Decisions — the architectural decisions on record.