--- name: pbip description: Guidance for Power BI Project (PBIP) structure, thick and thin reports, project renames, forks, and validation. Use for .pbip, .pbism, .platform, definition.pbir, PBIP vs PBIX, or cross-cutting project operations. ---

# PBIP Project Format

PBIP (Power BI Project) is the developer-mode file format for Power BI. It decomposes a `.pbix` binary into human-readable text files organized in folders, enabling source control, external editing, and multi-author collaboration.

## General, critical guidance

- **This skill covers project structure, not report editing.** Use `te` for the semantic model and `pbir` for every report mutation. Never hand-edit PBIR JSON. - **PBIX is a black box; PBIP is transparent.** PBIX is a single binary that cannot be diffed or edited externally. PBIP splits the same content into text files. Convert between them with File > Save As in PBI Desktop. - **Thick vs thin reports:** A thick report bundles `.Report/` + `.SemanticModel/` in the same project (`definition.pbir` uses `byPath`). A thin report has `.Report/` only, connecting to a remote model via `byConnection`. Thin reports are preferred for managed/shared BI. - **A project can contain multiple items.** Multiple `.Report/` and `.SemanticModel/` folders can coexist. The `.pbip` file is optional -- open `definition.pbir` directly. - **UTF-8 without BOM.** All files must be saved as UTF-8 without BOM. A BOM prefix causes parse errors in some tools. - **Git line endings:** PBI Desktop writes CRLF. Configure `core.autocrlf` or `* text=auto` in `.gitattributes` to normalize. - **260-char Windows path limit.** Use short root paths. Deep nesting of page/visual GUIDs can exceed this limit. - **Desktop reload is selective.** Use `pbir desktop refresh` for supported report/model changes; close and reopen Desktop for theme changes. - **Rename cascades are cross-cutting.** Rename model objects with `te mv --save`, then update each report with `pbir fields replace` or `replace-table` and validate both sides. - **SparklineData metadata** selectors embed Entity references in compact strings that do not follow the standard `SourceRef.Entity` JSON structure. Easy to miss. - **DAX query files exist in TWO locations:** `<Name>.SemanticModel/DAXQueries/` and `<Name>.Report/DAXQueries/`. Always check both during renames.

## Working with PBIX Files

Treat PBIX as an opaque Desktop artifact. Do not unzip it, patch its internals, reconstruct PBIR from its contents, or invoke an unapproved extraction engine. Microsoft licensing/EULA questions around third-party engine redistribution are unresolved for this project.

Use Power BI Desktop **File > Save As > Power BI Project (.pbip)**, then work on the resulting `.Report` folder with `pbir` and on the semantic model with `te`. If Desktop conversion is not available, stop and ask for a PBIP/PBIR source artifact rather than inventing a conversion path. ## PBIX vs PBIP

| Aspect | PBIX | PBIP | |--------|------|------| | Format | Single binary file | Folder of text files | | Source control | Not diff-friendly | Git-ready, human-readable diffs | | Collaboration | Single author at a time | Multiple authors, merge-friendly | | External editing | Not supported | VS Code, Tabular Editor, scripts | | Deployment | File > Publish | Git integration, Fabric APIs, fabric-cicd | | Data | Contains cached data | `cache.abf` is gitignored; metadata only in Git | | Convert | File > Save As > PBIP | File > Save As > PBIX |

## Project Structure

The `.Report/` folder is required in a PBIP. The `.SemanticModel/` folder is optional — a thin report has only `.Report/` and points at a remote semantic model via `definition.pbir` `byConnection`.

The `.pbi/` subfolders in both items (`localSettings.json`, `editorSettings.json`, `cache.abf`, etc.) are **all optional** — they are per-user/per-machine runtime state generated by Power BI Desktop. A freshly authored PBIP from an external tool may not have any of them, and the project still opens fine in Desktop.

``` <ProjectName>/ +-- <Name>.pbip # Entry point (references .Report folder) — optional +-- .gitignore # Recommended; excludes .pbi/localSettings.json and cache.abf +-- <Name>.SemanticModel/ # OPTIONAL — absent for thin reports | +-- .pbi/ # All contents OPTIONAL, per-user runtime state | | +-- localSettings.json # User-specific (gitignored) | | +-- editorSettings.json # Editor settings (committed) | | +-- cache.abf # Data cache (gitignored) | | +-- unappliedChanges.json # Pending Power Query changes | | +-- daxQueries.json # DAX query view tab settings | | +-- tmdlscripts.json # TMDL view script tab settings | +-- definition.pbism # SM entry point (required if .SemanticModel exists) | +-- definition/ # TMDL format (preferred) — see tmdl skill | +-- model.bim # TMSL format (legacy alt to definition/, mutually exclusive) | +-- diagramLayout.json # SM diagram (no external edit) | +-- DAXQueries/ # .dax files from DAX query view | +-- TMDLScripts/ # .tmdl files from TMDL view | +-- Copilot/ # Copilot tooling metadata | +-- .platform # Fabric identity (displayName, logicalId) +-- <Name>.Report/ # REQUIRED | +-- .pbi/ # OPTIONAL runtime state | | +-- localSettings.json # User-specific (gitignored) | +-- definition.pbir # Report entry point (required for PBIR format) | +-- definition/ # PBIR format — see pbir-format skill | | +-- report.json | | +-- version.json | | +-- pages/ | | | +-- pages.json | | | +-- <page-slug>/ # See "Page folder naming" below | | | | +-- page.json | | | | +-- visuals/... | +-- report.json # PBIR-Legacy format (legacy alt to definition/) | +-- mobileState.json # Mobile layout (no external edit) | +-- semanticModelDiagramLayout.json # Diagram positions (table renames) | +-- CustomVisuals/ # Private custom visual metadata | +-- StaticResources/ | | +-- SharedResources/ # Base themes, shared resources | | | +-- BaseThemes/<name>.json # Resolution path: <report>/StaticResources/SharedResources/<item.path> | | +-- RegisteredResources/ # Custom themes, images, .pbiviz files | +-- DAXQueries/ # .dax files from report DAX query view | +-- .platform # Fabric identity ```

## Page folder naming

Power BI Desktop uses opaque 20-character hex slugs for new page, visual, bookmark, and filter folders by default (e.g. `847663d71e27e0840063`). Per Microsoft docs, these can be **renamed to friendly names** but the replacement must satisfy:

- **Regex:** `^[\w-]+$` — word characters (letters, digits, underscore) or hyphen only. - **No spaces, no dots, no other punctuation.** Names outside this set are **silently ignored** by Power BI Desktop and the page/visual vanishes from the loaded report. This is the hardest bug class to diagnose because there is no error dialog. - **Folder name and `name` field must match exactly (case-sensitive).** The folder may be bare (`<slug>/`) or suffixed (`<slug>.Page/`) — both forms are valid on disk. pbir-cli uses the `.Page` suffix in its CLI path syntax; current Desktop saves omit the suffix. - **`pages.json.pageOrder` entries must reference the slug**, not the display name. `activePageName` must be one of the entries in `pageOrder`. - **Restart Desktop after external rename.** PBI Desktop does not detect file changes while open.

Rename pages with `pbir pages rename`; it owns the cross-report reference updates. Do not rename a folder or patch the related JSON by hand.

## SharedResources path resolution

Items listed in `resourcePackages[]` are resolved relative to:

``` <Report>/StaticResources/<package_type>/<item.path> ```

For a `SharedResources` package with an item `{ "path": "BaseThemes/Fluent2-CY26SU03.json" }`, Power BI Desktop looks for:

``` <Report>/StaticResources/SharedResources/BaseThemes/Fluent2-CY26SU03.json ```

**Missing resource files are a common blocking error.** If `report.json` declares `themeCollection.baseTheme.type = "SharedResources"` and points at a resource that doesn't exist on disk, the report will not open. `validate_pbip.py` checks this explicitly.

## What to Read for Common Tasks

| Task | Read | |------|------| | Convert a PBIX source | **Working with PBIX Files** above -- use Desktop Save As; no extraction | | Understand entry point file structure | **`references/pbip-file-types.md`** -- `.pbip`, `.pbir`, `.pbism`, `.platform` JSON structure, version properties, byPath vs byConnection | | Rename a table, measure, or column | `te mv --save`, then `pbir fields replace` or `replace-table`; use the references only to understand validation coverage | | Fork / duplicate a PBIP project | **`references/pbip-file-types.md`** -- update `.pbip` path, `.pbir` byPath, `.platform` logicalId and displayName | | Work with Copilot tooling files | **`references/copilot-folder.md`** -- AI instructions, verified answers, schema, example prompts | | Edit TMDL model files | **`tmdl`** skill -- syntax, authoring, column properties, naming conventions | | Change a PBIR report | **`pbir-cli`** skill -- all report mutations; `pbir-format` is read-only schema context | | Verify no broken references after rename | Grep commands below |

## Forking a PBIP Project

1. **Copy the project folder** -- duplicate the entire root folder with a new name. 2. **Rename artifact folders** -- rename `.Report/` and `.SemanticModel/` subfolders to match the new project name. 3. **Rename and update `.pbip`** -- rename the `.pbip` file and update `artifacts[].report.path` to point to the renamed `.Report` folder. 4. **Update `.pbir`** -- if the report uses `byPath`, update the path to point to the renamed `.SemanticModel` folder. 5. **Update `.platform` files** -- set `displayName` to the new project name in each `.platform` file. Regenerate `logicalId` (new GUID) if deploying as a separate Fabric item.

## Verification

Two tools for validation, used together:

1. **`scripts/validate_pbip.py`** — project-level validator for cross-cutting concerns: `.pbip` root file, `.platform` identity, semantic model format (TMDL vs TMSL), `datasetReference` resolution, theme resource resolution on disk, **orphan page folders**, and the **silent-ignore page name regex rule** (page names outside `^[\w-]+$` are silently ignored by Power BI Desktop). Delegates deep `.Report` schema validation to `pbir validate` if it is on PATH.

```bash python3 scripts/validate_pbip.py <path-to-.pbip-or-project> # validate python3 scripts/validate_pbip.py <path> --fix # scaffold .gitignore python3 scripts/validate_pbip.py <path> --json # machine-readable python3 scripts/validate_pbip.py <path> --no-pbir-cli # skip delegation ```

Exit codes: `0` clean, `1` warnings only, `2` errors, `3` usage error.

2. **`pbir validate <Report.Report>`** (from the `pbir-cli` skill) — canonical JSON schema + PBIR structure validator for the `.Report` folder. Covers JSON syntax, schema compliance, required fields, and optional `--qa` / `--fields` / `--strict` checks.

3. **`pbip-validator`** agent — use for interactive, LLM-driven checking of orphaned references after renames, when you need reasoning over the whole project rather than a determi

--- name: pbip description: Guidance for Power BI Project (PBIP) structure, thick and thin reports, project renames, forks, and validation. Use for .pbip, .pbism, .platform, definition.pbir, PBIP vs PBIX, or cross-cutting project operations. ---

# PBIP Project Format

PBIP (Power BI Project) is the developer-mode file format for Power BI. It decomposes a `.pbix` binary into human-readable text files organized in folders, enabling source control, external editing, and multi-author collaboration.

## General, critical guidance

- **This skill covers project structure, not report editing.** Use `te` for the semantic model and `pbir` for every report mutation. Never hand-edit PBIR JSON. - **PBIX is a black box; PBIP is transparent.** PBIX is a single binary that cannot be diffed or edited externally. PBIP splits the same content into text files. Convert between them with File > Save As in PBI Desktop. - **Thick vs thin reports:** A thick report bundles `.Report/` + `.SemanticModel/` in the same project (`definition.pbir` uses `byPath`). A thin report has `.Report/` only, connecting to a remote model via `byConnection`. Thin reports are preferred for managed/shared BI. - **A project can contain multiple items.** Multiple `.Report/` and `.SemanticModel/` folders can coexist. The `.pbip` file is optional -- open `definition.pbir` directly. - **UTF-8 without BOM.** All files must be saved as UTF-8 without BOM. A BOM prefix causes parse errors in some tools. - **Git line endings:** PBI Desktop writes CRLF. Configure `core.autocrlf` or `* text=auto` in `.gitattributes` to normalize. - **260-char Windows path limit.** Use short root paths. Deep nesting of page/visual GUIDs can exceed this limit. - **Desktop reload is selective.** Use `pbir desktop refresh` for supported report/model changes; close and reopen Desktop for theme changes. - **Rename cascades are cross-cutting.** Rename model objects with `te mv --save`, then update each report with `pbir fields replace` or `replace-table` and validate both sides. - **SparklineData metadata** selectors embed Entity references in compact strings that do not follow the standard `SourceRef.Entity` JSON structure. Easy to miss. - **DAX query files exist in TWO locations:** `<Name>.SemanticModel/DAXQueries/` and `<Name>.Report/DAXQueries/`. Always check both during renames.

## Working with PBIX Files

Treat PBIX as an opaque Desktop artifact. Do not unzip it, patch its internals, reconstruct PBIR from its contents, or invoke an unapproved extraction engine. Microsoft licensing/EULA questions around third-party engine redistribution are unresolved for this project.

Use Power BI Desktop **File > Save As > Power BI Project (.pbip)**, then work on the resulting `.Report` folder with `pbir` and on the semantic model with `te`. If Desktop conversion is not available, stop and ask for a PBIP/PBIR source artifact rather than inventing a conversion path. ## PBIX vs PBIP

| Aspect | PBIX | PBIP | |--------|------|------| | Format | Single binary file | Folder of text files | | Source control | Not diff-friendly | Git-ready, human-readable diffs | | Collaboration | Single author at a time | Multiple authors, merge-friendly | | External editing | Not supported | VS Code, Tabular Editor, scripts | | Deployment | File > Publish | Git integration, Fabric APIs, fabric-cicd | | Data | Contains cached data | `cache.abf` is gitignored; metadata only in Git | | Convert | File > Save As > PBIP | File > Save As > PBIX |

## Project Structure

The `.Report/` folder is required in a PBIP. The `.SemanticModel/` folder is optional — a thin report has only `.Report/` and points at a remote semantic model via `definition.pbir` `byConnection`.

The `.pbi/` subfolders in both items (`localSettings.json`, `editorSettings.json`, `cache.abf`, etc.) are **all optional** — they are per-user/per-machine runtime state generated by Power BI Desktop. A freshly authored PBIP from an external tool may not have any of them, and the project still opens fine in Desktop.

``` <ProjectName>/ +-- <Name>.pbip # Entry point (references .Report folder) — optional +-- .gitignore # Recommended; excludes .pbi/localSettings.json and cache.abf +-- <Name>.SemanticModel/ # OPTIONAL — absent for thin reports | +-- .pbi/ # All contents OPTIONAL, per-user runtime state | | +-- localSettings.json # User-specific (gitignored) | | +-- editorSettings.json # Editor settings (committed) | | +-- cache.abf # Data cache (gitignored) | | +-- unappliedChanges.json # Pending Power Query changes | | +-- daxQueries.json # DAX query view tab settings | | +-- tmdlscripts.json # TMDL view script tab settings | +-- definition.pbism # SM entry point (required if .SemanticModel exists) | +-- definition/ # TMDL format (preferred) — see tmdl skill | +-- model.bim # TMSL format (legacy alt to definition/, mutually exclusive) | +-- diagramLayout.json # SM diagram (no external edit) | +-- DAXQueries/ # .dax files from DAX query view | +-- TMDLScripts/ # .tmdl files from TMDL view | +-- Copilot/ # Copilot tooling metadata | +-- .platform # Fabric identity (displayName, logicalId) +-- <Name>.Report/ # REQUIRED | +-- .pbi/ # OPTIONAL runtime state | | +-- localSettings.json # User-specific (gitignored) | +-- definition.pbir # Report entry point (required for PBIR format) | +-- definition/ # PBIR format — see pbir-format skill | | +-- report.json | | +-- version.json | | +-- pages/ | | | +-- pages.json | | | +-- <page-slug>/ # See "Page folder naming" below | | | | +-- page.json | | | | +-- visuals/... | +-- report.json # PBIR-Legacy format (legacy alt to definition/) | +-- mobileState.json # Mobile layout (no external edit) | +-- semanticModelDiagramLayout.json # Diagram positions (table renames) | +-- CustomVisuals/ # Private custom visual metadata | +-- StaticResources/ | | +-- SharedResources/ # Base themes, shared resources | | | +-- BaseThemes/<name>.json # Resolution path: <report>/StaticResources/SharedResources/<item.path> | | +-- RegisteredResources/ # Custom themes, images, .pbiviz files | +-- DAXQueries/ # .dax files from report DAX query view | +-- .platform # Fabric identity ```

## Page folder naming

Power BI Desktop uses opaque 20-character hex slugs for new page, visual, bookmark, and filter folders by default (e.g. `847663d71e27e0840063`). Per Microsoft docs, these can be **renamed to friendly names** but the replacement must satisfy:

- **Regex:** `^[\w-]+$` — word characters (letters, digits, underscore) or hyphen only. - **No spaces, no dots, no other punctuation.** Names outside this set are **silently ignored** by Power BI Desktop and the page/visual vanishes from the loaded report. This is the hardest bug class to diagnose because there is no error dialog. - **Folder name and `name` field must match exactly (case-sensitive).** The folder may be bare (`<slug>/`) or suffixed (`<slug>.Page/`) — both forms are valid on disk. pbir-cli uses the `.Page` suffix in its CLI path syntax; current Desktop saves omit the suffix. - **`pages.json.pageOrder` entries must reference the slug**, not the display name. `activePageName` must be one of the entries in `pageOrder`. - **Restart Desktop after external rename.** PBI Desktop does not detect file changes while open.

Rename pages with `pbir pages rename`; it owns the cross-report reference updates. Do not rename a folder or patch the related JSON by hand.

## SharedResources path resolution

Items listed in `resourcePackages[]` are resolved relative to:

``` <Report>/StaticResources/<package_type>/<item.path> ```

For a `SharedResources` package with an item `{ "path": "BaseThemes/Fluent2-CY26SU03.json" }`, Power BI Desktop looks for:

``` <Report>/StaticResources/SharedResources/BaseThemes/Fluent2-CY26SU03.json ```

**Missing resource files are a common blocking error.** If `report.json` declares `themeCollection.baseTheme.type = "SharedResources"` and points at a resource that doesn't exist on disk, the report will not open. `validate_pbip.py` checks this explicitly.

## What to Read for Common Tasks

| Task | Read | |------|------| | Convert a PBIX source | **Working with PBIX Files** above -- use Desktop Save As; no extraction | | Understand entry point file structure | **`references/pbip-file-types.md`** -- `.pbip`, `.pbir`, `.pbism`, `.platform` JSON structure, version properties, byPath vs byConnection | | Rename a table, measure, or column | `te mv --save`, then `pbir fields replace` or `replace-table`; use the references only to understand validation coverage | | Fork / duplicate a PBIP project | **`references/pbip-file-types.md`** -- update `.pbip` path, `.pbir` byPath, `.platform` logicalId and displayName | | Work with Copilot tooling files | **`references/copilot-folder.md`** -- AI instructions, verified answers, schema, example prompts | | Edit TMDL model files | **`tmdl`** skill -- syntax, authoring, column properties, naming conventions | | Change a PBIR report | **`pbir-cli`** skill -- all report mutations; `pbir-format` is read-only schema context | | Verify no broken references after rename | Grep commands below |

## Forking a PBIP Project

1. **Copy the project folder** -- duplicate the entire root folder with a new name. 2. **Rename artifact folders** -- rename `.Report/` and `.SemanticModel/` subfolders to match the new project name. 3. **Rename and update `.pbip`** -- rename the `.pbip` file and update `artifacts[].report.path` to point to the renamed `.Report` folder. 4. **Update `.pbir`** -- if the report uses `byPath`, update the path to point to the renamed `.SemanticModel` folder. 5. **Update `.platform` files** -- set `displayName` to the new project name in each `.platform` file. Regenerate `logicalId` (new GUID) if deploying as a separate Fabric item.

## Verification

Two tools for validation, used together:

1. **`scripts/validate_pbip.py`** — project-level validator for cross-cutting concerns: `.pbip` root file, `.platform` identity, semantic model format (TMDL vs TMSL), `datasetReference` resolution, theme resource resolution on disk, **orphan page folders**, and the **silent-ignore page name regex rule** (page names outside `^[\w-]+$` are silently ignored by Power BI Desktop). Delegates deep `.Report` schema validation to `pbir validate` if it is on PATH.

```bash python3 scripts/validate_pbip.py <path-to-.pbip-or-project> # validate python3 scripts/validate_pbip.py <path> --fix # scaffold .gitignore python3 scripts/validate_pbip.py <path> --json # machine-readable python3 scripts/validate_pbip.py <path> --no-pbir-cli # skip delegation ```

Exit codes: `0` clean, `1` warnings only, `2` errors, `3` usage error.

2. **`pbir validate <Report.Report>`** (from the `pbir-cli` skill) — canonical JSON schema + PBIR structure validator for the `.Report` folder. Covers JSON syntax, schema compliance, required fields, and optional `--qa` / `--fields` / `--strict` checks.

3. **`pbip-validator`** agent — use for interactive, LLM-driven checking of orphaned references after renames, when you need reasoning over the whole project rather than a determi

--- name: pbip description: Guidance for Power BI Project (PBIP) structure, thick and thin reports, project renames, forks, and validation. Use for .pbip, .pbism, .platform, definition.pbir, PBIP vs PBIX, or cross-cutting project operations. ---

# PBIP Project Format

PBIP (Power BI Project) is the developer-mode file format for Power BI. It decomposes a `.pbix` binary into human-readable text files organized in folders, enabling source control, external editing, and multi-author collaboration.

## General, critical guidance

- **This skill covers project structure, not report editing.** Use `te` for the semantic model and `pbir` for every report mutation. Never hand-edit PBIR JSON. - **PBIX is a black box; PBIP is transparent.** PBIX is a single binary that cannot be diffed or edited externally. PBIP splits the same content into text files. Convert between them with File > Save As in PBI Desktop. - **Thick vs thin reports:** A thick report bundles `.Report/` + `.SemanticModel/` in the same project (`definition.pbir` uses `byPath`). A thin report has `.Report/` only, connecting to a remote model via `byConnection`. Thin reports are preferred for managed/shared BI. - **A project can contain multiple items.** Multiple `.Report/` and `.SemanticModel/` folders can coexist. The `.pbip` file is optional -- open `definition.pbir` directly. - **UTF-8 without BOM.** All files must be saved as UTF-8 without BOM. A BOM prefix causes parse errors in some tools. - **Git line endings:** PBI Desktop writes CRLF. Configure `core.autocrlf` or `* text=auto` in `.gitattributes` to normalize. - **260-char Windows path limit.** Use short root paths. Deep nesting of page/visual GUIDs can exceed this limit. - **Desktop reload is selective.** Use `pbir desktop refresh` for supported report/model changes; close and reopen Desktop for theme changes. - **Rename cascades are cross-cutting.** Rename model objects with `te mv --save`, then update each report with `pbir fields replace` or `replace-table` and validate both sides. - **SparklineData metadata** selectors embed Entity references in compact strings that do not follow the standard `SourceRef.Entity` JSON structure. Easy to miss. - **DAX query files exist in TWO locations:** `<Name>.SemanticModel/DAXQueries/` and `<Name>.Report/DAXQueries/`. Always check both during renames.

## Working with PBIX Files

Treat PBIX as an opaque Desktop artifact. Do not unzip it, patch its internals, reconstruct PBIR from its contents, or invoke an unapproved extraction engine. Microsoft licensing/EULA questions around third-party engine redistribution are unresolved for this project.

Use Power BI Desktop **File > Save As > Power BI Project (.pbip)**, then work on the resulting `.Report` folder with `pbir` and on the semantic model with `te`. If Desktop conversion is not available, stop and ask for a PBIP/PBIR source artifact rather than inventing a conversion path. ## PBIX vs PBIP

| Aspect | PBIX | PBIP | |--------|------|------| | Format | Single binary file | Folder of text files | | Source control | Not diff-friendly | Git-ready, human-readable diffs | | Collaboration | Single author at a time | Multiple authors, merge-friendly | | External editing | Not supported | VS Code, Tabular Editor, scripts | | Deployment | File > Publish | Git integration, Fabric APIs, fabric-cicd | | Data | Contains cached data | `cache.abf` is gitignored; metadata only in Git | | Convert | File > Save As > PBIP | File > Save As > PBIX |

## Project Structure

The `.Report/` folder is required in a PBIP. The `.SemanticModel/` folder is optional — a thin report has only `.Report/` and points at a remote semantic model via `definition.pbir` `byConnection`.

The `.pbi/` subfolders in both items (`localSettings.json`, `editorSettings.json`, `cache.abf`, etc.) are **all optional** — they are per-user/per-machine runtime state generated by Power BI Desktop. A freshly authored PBIP from an external tool may not have any of them, and the project still opens fine in Desktop.

``` <ProjectName>/ +-- <Name>.pbip # Entry point (references .Report folder) — optional +-- .gitignore # Recommended; excludes .pbi/localSettings.json and cache.abf +-- <Name>.SemanticModel/ # OPTIONAL — absent for thin reports | +-- .pbi/ # All contents OPTIONAL, per-user runtime state | | +-- localSettings.json # User-specific (gitignored) | | +-- editorSettings.json # Editor settings (committed) | | +-- cache.abf # Data cache (gitignored) | | +-- unappliedChanges.json # Pending Power Query changes | | +-- daxQueries.json # DAX query view tab settings | | +-- tmdlscripts.json # TMDL view script tab settings | +-- definition.pbism # SM entry point (required if .SemanticModel exists) | +-- definition/ # TMDL format (preferred) — see tmdl skill | +-- model.bim # TMSL format (legacy alt to definition/, mutually exclusive) | +-- diagramLayout.json # SM diagram (no external edit) | +-- DAXQueries/ # .dax files from DAX query view | +-- TMDLScripts/ # .tmdl files from TMDL view | +-- Copilot/ # Copilot tooling metadata | +-- .platform # Fabric identity (displayName, logicalId) +-- <Name>.Report/ # REQUIRED | +-- .pbi/ # OPTIONAL runtime state | | +-- localSettings.json # User-specific (gitignored) | +-- definition.pbir # Report entry point (required for PBIR format) | +-- definition/ # PBIR format — see pbir-format skill | | +-- report.json | | +-- version.json | | +-- pages/ | | | +-- pages.json | | | +-- <page-slug>/ # See "Page folder naming" below | | | | +-- page.json | | | | +-- visuals/... | +-- report.json # PBIR-Legacy format (legacy alt to definition/) | +-- mobileState.json # Mobile layout (no external edit) | +-- semanticModelDiagramLayout.json # Diagram positions (table renames) | +-- CustomVisuals/ # Private custom visual metadata | +-- StaticResources/ | | +-- SharedResources/ # Base themes, shared resources | | | +-- BaseThemes/<name>.json # Resolution path: <report>/StaticResources/SharedResources/<item.path> | | +-- RegisteredResources/ # Custom themes, images, .pbiviz files | +-- DAXQueries/ # .dax files from report DAX query view | +-- .platform # Fabric identity ```

## Page folder naming

Power BI Desktop uses opaque 20-character hex slugs for new page, visual, bookmark, and filter folders by default (e.g. `847663d71e27e0840063`). Per Microsoft docs, these can be **renamed to friendly names** but the replacement must satisfy:

- **Regex:** `^[\w-]+$` — word characters (letters, digits, underscore) or hyphen only. - **No spaces, no dots, no other punctuation.** Names outside this set are **silently ignored** by Power BI Desktop and the page/visual vanishes from the loaded report. This is the hardest bug class to diagnose because there is no error dialog. - **Folder name and `name` field must match exactly (case-sensitive).** The folder may be bare (`<slug>/`) or suffixed (`<slug>.Page/`) — both forms are valid on disk. pbir-cli uses the `.Page` suffix in its CLI path syntax; current Desktop saves omit the suffix. - **`pages.json.pageOrder` entries must reference the slug**, not the display name. `activePageName` must be one of the entries in `pageOrder`. - **Restart Desktop after external rename.** PBI Desktop does not detect file changes while open.

Rename pages with `pbir pages rename`; it owns the cross-report reference updates. Do not rename a folder or patch the related JSON by hand.

## SharedResources path resolution

Items listed in `resourcePackages[]` are resolved relative to:

``` <Report>/StaticResources/<package_type>/<item.path> ```

For a `SharedResources` package with an item `{ "path": "BaseThemes/Fluent2-CY26SU03.json" }`, Power BI Desktop looks for:

``` <Report>/StaticResources/SharedResources/BaseThemes/Fluent2-CY26SU03.json ```

**Missing resource files are a common blocking error.** If `report.json` declares `themeCollection.baseTheme.type = "SharedResources"` and points at a resource that doesn't exist on disk, the report will not open. `validate_pbip.py` checks this explicitly.

## What to Read for Common Tasks

| Task | Read | |------|------| | Convert a PBIX source | **Working with PBIX Files** above -- use Desktop Save As; no extraction | | Understand entry point file structure | **`references/pbip-file-types.md`** -- `.pbip`, `.pbir`, `.pbism`, `.platform` JSON structure, version properties, byPath vs byConnection | | Rename a table, measure, or column | `te mv --save`, then `pbir fields replace` or `replace-table`; use the references only to understand validation coverage | | Fork / duplicate a PBIP project | **`references/pbip-file-types.md`** -- update `.pbip` path, `.pbir` byPath, `.platform` logicalId and displayName | | Work with Copilot tooling files | **`references/copilot-folder.md`** -- AI instructions, verified answers, schema, example prompts | | Edit TMDL model files | **`tmdl`** skill -- syntax, authoring, column properties, naming conventions | | Change a PBIR report | **`pbir-cli`** skill -- all report mutations; `pbir-format` is read-only schema context | | Verify no broken references after rename | Grep commands below |

## Forking a PBIP Project

1. **Copy the project folder** -- duplicate the entire root folder with a new name. 2. **Rename artifact folders** -- rename `.Report/` and `.SemanticModel/` subfolders to match the new project name. 3. **Rename and update `.pbip`** -- rename the `.pbip` file and update `artifacts[].report.path` to point to the renamed `.Report` folder. 4. **Update `.pbir`** -- if the report uses `byPath`, update the path to point to the renamed `.SemanticModel` folder. 5. **Update `.platform` files** -- set `displayName` to the new project name in each `.platform` file. Regenerate `logicalId` (new GUID) if deploying as a separate Fabric item.

## Verification

Two tools for validation, used together:

1. **`scripts/validate_pbip.py`** — project-level validator for cross-cutting concerns: `.pbip` root file, `.platform` identity, semantic model format (TMDL vs TMSL), `datasetReference` resolution, theme resource resolution on disk, **orphan page folders**, and the **silent-ignore page name regex rule** (page names outside `^[\w-]+$` are silently ignored by Power BI Desktop). Delegates deep `.Report` schema validation to `pbir validate` if it is on PATH.

```bash python3 scripts/validate_pbip.py <path-to-.pbip-or-project> # validate python3 scripts/validate_pbip.py <path> --fix # scaffold .gitignore python3 scripts/validate_pbip.py <path> --json # machine-readable python3 scripts/validate_pbip.py <path> --no-pbir-cli # skip delegation ```

Exit codes: `0` clean, `1` warnings only, `2` errors, `3` usage error.

2. **`pbir validate <Report.Report>`** (from the `pbir-cli` skill) — canonical JSON schema + PBIR structure validator for the `.Report` folder. Covers JSON syntax, schema compliance, required fields, and optional `--qa` / `--fields` / `--strict` checks.

3. **`pbip-validator`** agent — use for interactive, LLM-driven checking of orphaned references after renames, when you need reasoning over the whole project rather than a determi

--- name: pbip description: Guidance for Power BI Project (PBIP) structure, thick and thin reports, project renames, forks, and validation. Use for .pbip, .pbism, .platform, definition.pbir, PBIP vs PBIX, or cross-cutting project operations. ---

# PBIP Project Format

PBIP (Power BI Project) is the developer-mode file format for Power BI. It decomposes a `.pbix` binary into human-readable text files organized in folders, enabling source control, external editing, and multi-author collaboration.

## General, critical guidance

- **This skill covers project structure, not report editing.** Use `te` for the semantic model and `pbir` for every report mutation. Never hand-edit PBIR JSON. - **PBIX is a black box; PBIP is transparent.** PBIX is a single binary that cannot be diffed or edited externally. PBIP splits the same content into text files. Convert between them with File > Save As in PBI Desktop. - **Thick vs thin reports:** A thick report bundles `.Report/` + `.SemanticModel/` in the same project (`definition.pbir` uses `byPath`). A thin report has `.Report/` only, connecting to a remote model via `byConnection`. Thin reports are preferred for managed/shared BI. - **A project can contain multiple items.** Multiple `.Report/` and `.SemanticModel/` folders can coexist. The `.pbip` file is optional -- open `definition.pbir` directly. - **UTF-8 without BOM.** All files must be saved as UTF-8 without BOM. A BOM prefix causes parse errors in some tools. - **Git line endings:** PBI Desktop writes CRLF. Configure `core.autocrlf` or `* text=auto` in `.gitattributes` to normalize. - **260-char Windows path limit.** Use short root paths. Deep nesting of page/visual GUIDs can exceed this limit. - **Desktop reload is selective.** Use `pbir desktop refresh` for supported report/model changes; close and reopen Desktop for theme changes. - **Rename cascades are cross-cutting.** Rename model objects with `te mv --save`, then update each report with `pbir fields replace` or `replace-table` and validate both sides. - **SparklineData metadata** selectors embed Entity references in compact strings that do not follow the standard `SourceRef.Entity` JSON structure. Easy to miss. - **DAX query files exist in TWO locations:** `<Name>.SemanticModel/DAXQueries/` and `<Name>.Report/DAXQueries/`. Always check both during renames.

## Working with PBIX Files

Treat PBIX as an opaque Desktop artifact. Do not unzip it, patch its internals, reconstruct PBIR from its contents, or invoke an unapproved extraction engine. Microsoft licensing/EULA questions around third-party engine redistribution are unresolved for this project.

Use Power BI Desktop **File > Save As > Power BI Project (.pbip)**, then work on the resulting `.Report` folder with `pbir` and on the semantic model with `te`. If Desktop conversion is not available, stop and ask for a PBIP/PBIR source artifact rather than inventing a conversion path. ## PBIX vs PBIP

| Aspect | PBIX | PBIP | |--------|------|------| | Format | Single binary file | Folder of text files | | Source control | Not diff-friendly | Git-ready, human-readable diffs | | Collaboration | Single author at a time | Multiple authors, merge-friendly | | External editing | Not supported | VS Code, Tabular Editor, scripts | | Deployment | File > Publish | Git integration, Fabric APIs, fabric-cicd | | Data | Contains cached data | `cache.abf` is gitignored; metadata only in Git | | Convert | File > Save As > PBIP | File > Save As > PBIX |

## Project Structure

The `.Report/` folder is required in a PBIP. The `.SemanticModel/` folder is optional — a thin report has only `.Report/` and points at a remote semantic model via `definition.pbir` `byConnection`.

The `.pbi/` subfolders in both items (`localSettings.json`, `editorSettings.json`, `cache.abf`, etc.) are **all optional** — they are per-user/per-machine runtime state generated by Power BI Desktop. A freshly authored PBIP from an external tool may not have any of them, and the project still opens fine in Desktop.

``` <ProjectName>/ +-- <Name>.pbip # Entry point (references .Report folder) — optional +-- .gitignore # Recommended; excludes .pbi/localSettings.json and cache.abf +-- <Name>.SemanticModel/ # OPTIONAL — absent for thin reports | +-- .pbi/ # All contents OPTIONAL, per-user runtime state | | +-- localSettings.json # User-specific (gitignored) | | +-- editorSettings.json # Editor settings (committed) | | +-- cache.abf # Data cache (gitignored) | | +-- unappliedChanges.json # Pending Power Query changes | | +-- daxQueries.json # DAX query view tab settings | | +-- tmdlscripts.json # TMDL view script tab settings | +-- definition.pbism # SM entry point (required if .SemanticModel exists) | +-- definition/ # TMDL format (preferred) — see tmdl skill | +-- model.bim # TMSL format (legacy alt to definition/, mutually exclusive) | +-- diagramLayout.json # SM diagram (no external edit) | +-- DAXQueries/ # .dax files from DAX query view | +-- TMDLScripts/ # .tmdl files from TMDL view | +-- Copilot/ # Copilot tooling metadata | +-- .platform # Fabric identity (displayName, logicalId) +-- <Name>.Report/ # REQUIRED | +-- .pbi/ # OPTIONAL runtime state | | +-- localSettings.json # User-specific (gitignored) | +-- definition.pbir # Report entry point (required for PBIR format) | +-- definition/ # PBIR format — see pbir-format skill | | +-- report.json | | +-- version.json | | +-- pages/ | | | +-- pages.json | | | +-- <page-slug>/ # See "Page folder naming" below | | | | +-- page.json | | | | +-- visuals/... | +-- report.json # PBIR-Legacy format (legacy alt to definition/) | +-- mobileState.json # Mobile layout (no external edit) | +-- semanticModelDiagramLayout.json # Diagram positions (table renames) | +-- CustomVisuals/ # Private custom visual metadata | +-- StaticResources/ | | +-- SharedResources/ # Base themes, shared resources | | | +-- BaseThemes/<name>.json # Resolution path: <report>/StaticResources/SharedResources/<item.path> | | +-- RegisteredResources/ # Custom themes, images, .pbiviz files | +-- DAXQueries/ # .dax files from report DAX query view | +-- .platform # Fabric identity ```

## Page folder naming

Power BI Desktop uses opaque 20-character hex slugs for new page, visual, bookmark, and filter folders by default (e.g. `847663d71e27e0840063`). Per Microsoft docs, these can be **renamed to friendly names** but the replacement must satisfy:

- **Regex:** `^[\w-]+$` — word characters (letters, digits, underscore) or hyphen only. - **No spaces, no dots, no other punctuation.** Names outside this set are **silently ignored** by Power BI Desktop and the page/visual vanishes from the loaded report. This is the hardest bug class to diagnose because there is no error dialog. - **Folder name and `name` field must match exactly (case-sensitive).** The folder may be bare (`<slug>/`) or suffixed (`<slug>.Page/`) — both forms are valid on disk. pbir-cli uses the `.Page` suffix in its CLI path syntax; current Desktop saves omit the suffix. - **`pages.json.pageOrder` entries must reference the slug**, not the display name. `activePageName` must be one of the entries in `pageOrder`. - **Restart Desktop after external rename.** PBI Desktop does not detect file changes while open.

Rename pages with `pbir pages rename`; it owns the cross-report reference updates. Do not rename a folder or patch the related JSON by hand.

## SharedResources path resolution

Items listed in `resourcePackages[]` are resolved relative to:

``` <Report>/StaticResources/<package_type>/<item.path> ```

For a `SharedResources` package with an item `{ "path": "BaseThemes/Fluent2-CY26SU03.json" }`, Power BI Desktop looks for:

``` <Report>/StaticResources/SharedResources/BaseThemes/Fluent2-CY26SU03.json ```

**Missing resource files are a common blocking error.** If `report.json` declares `themeCollection.baseTheme.type = "SharedResources"` and points at a resource that doesn't exist on disk, the report will not open. `validate_pbip.py` checks this explicitly.

## What to Read for Common Tasks

| Task | Read | |------|------| | Convert a PBIX source | **Working with PBIX Files** above -- use Desktop Save As; no extraction | | Understand entry point file structure | **`references/pbip-file-types.md`** -- `.pbip`, `.pbir`, `.pbism`, `.platform` JSON structure, version properties, byPath vs byConnection | | Rename a table, measure, or column | `te mv --save`, then `pbir fields replace` or `replace-table`; use the references only to understand validation coverage | | Fork / duplicate a PBIP project | **`references/pbip-file-types.md`** -- update `.pbip` path, `.pbir` byPath, `.platform` logicalId and displayName | | Work with Copilot tooling files | **`references/copilot-folder.md`** -- AI instructions, verified answers, schema, example prompts | | Edit TMDL model files | **`tmdl`** skill -- syntax, authoring, column properties, naming conventions | | Change a PBIR report | **`pbir-cli`** skill -- all report mutations; `pbir-format` is read-only schema context | | Verify no broken references after rename | Grep commands below |

## Forking a PBIP Project

1. **Copy the project folder** -- duplicate the entire root folder with a new name. 2. **Rename artifact folders** -- rename `.Report/` and `.SemanticModel/` subfolders to match the new project name. 3. **Rename and update `.pbip`** -- rename the `.pbip` file and update `artifacts[].report.path` to point to the renamed `.Report` folder. 4. **Update `.pbir`** -- if the report uses `byPath`, update the path to point to the renamed `.SemanticModel` folder. 5. **Update `.platform` files** -- set `displayName` to the new project name in each `.platform` file. Regenerate `logicalId` (new GUID) if deploying as a separate Fabric item.

## Verification

Two tools for validation, used together:

1. **`scripts/validate_pbip.py`** — project-level validator for cross-cutting concerns: `.pbip` root file, `.platform` identity, semantic model format (TMDL vs TMSL), `datasetReference` resolution, theme resource resolution on disk, **orphan page folders**, and the **silent-ignore page name regex rule** (page names outside `^[\w-]+$` are silently ignored by Power BI Desktop). Delegates deep `.Report` schema validation to `pbir validate` if it is on PATH.

```bash python3 scripts/validate_pbip.py <path-to-.pbip-or-project> # validate python3 scripts/validate_pbip.py <path> --fix # scaffold .gitignore python3 scripts/validate_pbip.py <path> --json # machine-readable python3 scripts/validate_pbip.py <path> --no-pbir-cli # skip delegation ```

Exit codes: `0` clean, `1` warnings only, `2` errors, `3` usage error.

2. **`pbir validate <Report.Report>`** (from the `pbir-cli` skill) — canonical JSON schema + PBIR structure validator for the `.Report` folder. Covers JSON syntax, schema compliance, required fields, and optional `--qa` / `--fields` / `--strict` checks.

3. **`pbip-validator`** agent — use for interactive, LLM-driven checking of orphaned references after renames, when you need reasoning over the whole project rather than a determi