Chapter 2 of 8

Getting started — AtelierBID

Prerequisites, install, and a first run of both a script and a skill.

AtelierBID is a Claude Code plugin. You install it into Claude Code, then invoke its skills in a session. There is no server to run and no account to create.

Prerequisites#

Claude Code (CLI, desktop, or IDE extension).
Node.js on your PATH — the deterministic scripts run via node. The plugin's scripts are dependency-free (Node stdlib only), so no npm install is required.
No API key, no env vars, no credentials. The whole point is zero-config, in-session operation.
Internet is needed only to view a prototype's output HTML (it loads Chart.js from a CDN). Generating artefacts — including the IR → PBIR conversion — needs no network.

Windows PATH gotcha: on Git Bash and the default PowerShell session, C:\Program Files\nodejs is often missing from PATH, surfacing as exit 127 / "command not found" or "npm is not recognized". Put Node on PATH before running — Bash: export PATH="/c/Program Files/nodejs:$PATH"; PowerShell: $env:PATH = 'C:\Program Files\nodejs;' + $env:PATH.

Install#

This repo ships as a standalone marketplace. Add the marketplace, then install the plugin:

claude plugin marketplace add https://github.com/DATA-AI-XYZ/Atelier
claude plugin install AtelierBID@AtelierBID-Marketplace

Reload Claude Code so the skills register.

First run — a deterministic script (no AI step, no network)#

The quickest proof it works is the theme builder:

node scripts/build-theme.js --brand "#2A6FDB,#E8743B" --out ./out/theme --colors 10

This writes a schema-valid theme.json plus a rationale.md to ./out/theme/. It exits non-zero and prints validation errors on stderr if the produced theme is not template-valid. Import the theme in Power BI via View → Themes → Browse for themes.

First run — a skill (inside a Claude Code session)#

From inside a Claude Code session, invoke any of the six AtelierBID skills:

/AtelierBID:build-theme           # accessible, schema-valid theme.json
/AtelierBID:design-report         # composed report layout → mockup IR → PBIR
/AtelierBID:model-star-schema     # plain English → star-schema TMDL
/AtelierBID:prototype-report      # interactive Chart.js prototype from the shared IR
/AtelierBID:generate-background   # zoned, on-brand canvas backdrop
/AtelierBID:powerbi-design-system # reference-doctrine skill — auto-loads design system context, creates nothing
/AtelierBID:author-dax            # batch DAX measure authoring with a per-measure scoreboard
/AtelierBID:optimise-dax          # ranked anti-patterns, confirmation-gated rewrites
/AtelierBID:document-model        # read-only data dictionary from the TMDL
/AtelierBID:update-metadata       # display + Q&A metadata, dry-run before any write

Each skill run creates a checkpoint folder under output/<run-id>/. Each pipeline step writes a checkpoint there, so an interrupted run resumes from where it stopped. The output/ folder is gitignored.

A guided tour of the shipped CLIs#

All of these are deterministic, offline Node CLIs. None use the clock, randomness, or the network. The skills call them internally; they also run standalone.

# Phase A — start a project + the grounding spine
node scripts/new-project.js --name "Q3 Sales 2026" --dry-run        # scaffold a sanitised project tree (preview)
node scripts/scaffold-pbip.js --name "Q3Sales" --out ./projects     # emit an openable PBIP container
node scripts/validate-pbip.js --project ./projects/Q3Sales          # plain-English structural pass/fail
node scripts/best-practice.js scaffold                              # seed _00-Best-Practice/ + BestPracticeRules.json
node scripts/ground-schema.js load --use-sample                     # load the schema-grounding contract (gate)
node scripts/lifecycle.js mode                                      # report the offline/Tier-1 lifecycle mode

# Phase B — discovery + review-only SQL & Power Query/M authoring (emit-only, never executed)
node scripts/discover-requirements.js --answers a.json --out spec.json --check-gaps
node scripts/author-sql.js --table Sales --context directquery --out q.sql
node scripts/author-m.js --transforms "rename,filter,changeType" --out q.m --validate

# Phase C — model engine (emit-only TMDL)
node scripts/model-star-schema.js --describe "Sales by Date, Product, Region with Revenue, OrderCount" \
  --out ./tables --validate --preview
node scripts/model-relationships.js --tables ./tables --out relationships.tmdl
node scripts/model-incremental-refresh.js --table Sales --date-column OrderDate --out refresh.tmdl
node scripts/optimise-model.js --model ./tables                     # ranked anti-pattern report

# Phase D — calculation engine (DAX as TMDL / query text)
node scripts/author-dax.js --measure "Total Revenue" --out measures.tmdl
node scripts/dax-time-intelligence.js --date-table Date --out ti.tmdl
node scripts/dax-query.js --measure "Total Revenue" --out test.dax  # EVALUATE validation query

# Phase E — design pipeline (tokens → theme → background → mockup IR → PBIR)
node scripts/design-system.js --validate --schema data/design-system.json
node scripts/check-palette.js "#2D6CDF,#0D9488,#F0B429"             # flag colours within ΔE 15 of RAG roles
node scripts/generate-background.js --page-size 1280x720 --grid 16 --out bg.json
node scripts/design-report.js --compose --emit-mockup mockup.html --apply-tokens
node scripts/prototype-report.js --out ./prototype --sample
node scripts/design-report.js --from-ir approved-ir.json --pbip ./projects/Q3Sales

# Phase F — model AI-readiness (model = a directory of *.tmdl)
node scripts/ai-readiness.js audit --model ./tables --out audit.json          # flag Q&A gaps
node scripts/ai-readiness.js enrich --model ./tables --out ./enriched         # descriptions + synonyms
node scripts/ai-readiness.js linguistic --model ./tables --out linguistic.json
node scripts/ai-readiness.js hygiene --model ./tables --out ./hygiene         # hide keys + disambiguate
node scripts/ai-readiness.js verified-answers --model ./tables --out va.json

# Phase F — Fabric data agent (offline; --model = a .json model or a *.tmdl dir)
node scripts/fabric-agent.js --model ./enriched --out ./agent                 # emits config + runbook
#   → agent-config.json (grounding + scope + guardrails) and provisioning-runbook.md
node scripts/validate-pbip.js --model ./enriched                              # enriched TMDL still valid

# Phase G — documentation
node scripts/document-model.js --model ./enriched --out data-dictionary.md

author-sql.js and author-m.js are emit-only — they write reviewable text and never connect to a database or evaluate M. The model and calculation CLIs likewise emit TMDL and validate it structurally offline. See Features for the full flag reference on every script.

The mockup → PBIR flow, end to end#

The design phase's headline capability converts an approved layout into a real report page without re-authoring (full detail in Features):

# 1. Compose a page and emit a reviewable HTML mockup with the IR embedded
node scripts/design-report.js --compose --emit-mockup mockup.html --apply-tokens

# 2. (Optional) Render an interactive prototype from the same IR for sign-off, and hand the IR back
node scripts/prototype-report.js --ir composed-ir.json --out ./prototype --emit-ir approved-ir.json

# 3. Convert the approved IR into a structurally-valid PBIR page inside a PBIP
node scripts/design-report.js --from-ir approved-ir.json --pbip ./projects/Q3Sales

# 4. Validate the IR and the PBIP offline
node scripts/validate-pbip.js --ir approved-ir.json
node scripts/validate-pbip.js --project ./projects/Q3Sales

Troubleshooting#

exit 127 / "command not found" / "npm not recognized" — Node is not on the shell's PATH. See the Windows PATH gotcha above.
A prototype HTML opens blank / charts missing — the page loads Chart.js from a CDN; you need internet to view it. The file itself is a complete, standalone preview artefact, and the PBIR generation path does not need the network.