sf-decomposer 6.13.0 → 6.15.0

package/CHANGELOG.md

@@ -5,6 +5,26 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [6.15.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.14.0...v6.15.0) (2026-04-30)
+
+
+### Features
+
+* support multi-rule multiLevel overrides ([#419](https://github.com/mcarvin8/sf-decomposer/issues/419)) ([5b36f74](https://github.com/mcarvin8/sf-decomposer/commit/5b36f745ab998509b2b7a86a1a6d0a65ebc91a45))
+
+
+### Bug Fixes
+
+* **bot:** round-trip bots with nested botSteps multi-level rule ([#421](https://github.com/mcarvin8/sf-decomposer/issues/421)) ([38e8f9e](https://github.com/mcarvin8/sf-decomposer/commit/38e8f9e944b6ba85d724c479c28f9f3de1e9361a))
+
+## [6.14.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.13.0...v6.14.0) (2026-04-30)
+
+
+### Features
+
+* add multiLevel override and round-trip verify command ([#418](https://github.com/mcarvin8/sf-decomposer/issues/418)) ([5f06265](https://github.com/mcarvin8/sf-decomposer/commit/5f06265333e9a0523154d0c745e83e0571938f98))
+* **decompose:** expose splitTags as an override field ([#416](https://github.com/mcarvin8/sf-decomposer/issues/416)) ([eedf0f2](https://github.com/mcarvin8/sf-decomposer/commit/eedf0f23d248fdd028a097435aa9493449269954))
+
 ## [6.13.0](https://github.com/mcarvin8/sf-decomposer/compare/v6.12.0...v6.13.0) (2026-04-30)
 
 

package/HANDBOOK.md

@@ -0,0 +1,286 @@
+# Admin Handbook — Decomposing Tricky Salesforce Metadata
+
+This handbook collects ready-to-paste `.sfdecomposer.config.json` recipes for the metadata types where Salesforce's native source format either doesn't decompose at all or decomposes too coarsely to diff well in version control. Every recipe in this guide:
+
+- decomposes the original file into per-piece units that survive `git diff` cleanly,
+- recomposes back to a **byte-identical** XML deployable to any org,
+- is verified by `sf decomposer verify` before you commit it.
+
+If you want the underlying option grammar instead of recipes, see the [main README](./README.md#per-type--per-component-overrides).
+
+## Contents
+
+- [Choosing a strategy](#choosing-a-strategy)
+- [Bots (Agentforce and Einstein)](#bots-agentforce-and-einstein)
+- [Flexipages (Lightning App / Record / Home pages)](#flexipages-lightning-app--record--home-pages)
+- [Layouts (page layouts)](#layouts-page-layouts)
+- [Other deeply-nested types](#other-deeply-nested-types)
+- [The verification workflow](#the-verification-workflow)
+- [Common pitfalls](#common-pitfalls)
+
+## Choosing a strategy
+
+Three knobs cover almost every case:
+
+| Symptom of the source XML                                                                     | Reach for                                                                                          |
+| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| One repeating section at the top level (e.g. `<labels>` of a custom-labels file).             | `strategy: unique-id` (default).                                                                   |
+| Lots of small repeatable tags, you want one file per tag-name, not per-instance.              | `strategy: grouped-by-tag`.                                                                        |
+| `grouped-by-tag`, but a few specific tags (e.g. `objectPermissions`) need finer-grained diff. | Add `splitTags`.                                                                                   |
+| A deeply-nested repeatable block lives _inside_ another repeatable block (the bot pattern).   | Add `multiLevel`. If there are several such nested blocks, pass them as an array — see Bots below. |
+
+Hard rules the plugin always enforces (so you don't have to):
+
+- `labels` and `loyaltyProgramSetup` are always treated as `unique-id` regardless of any override.
+- `loyaltyProgramSetup` automatically gets `multiLevel: programProcesses:programProcesses:parameterName,ruleName` when run under `unique-id` — you can replace it but you don't have to set it.
+
+Everything else in this handbook is opt-in.
+
+## Bots (Agentforce and Einstein)
+
+**Why this is hard.** Agentforce and Einstein bots both ship as `.bot-meta.xml`, but their internals diverge:
+
+- The bot **header** (`Bot.bot-meta.xml`) is small — a few leaves, a few `botUserList` entries.
+- The bot **versions** (`vN.botVersion-meta.xml`) are the painful ones. A single `BotVersion` typically contains:
+  - `botDialogGroups` (logical groupings),
+  - `botDialogs` (the dialogs themselves), and inside each dialog,
+  - `botSteps` (often nested 2–3 levels deep — message, collect, transfer, condition, ...),
+  - `mlIntents`, `conversationVariables`, `botStepConditions`, ...
+
+A flat `unique-id` decomposition of a `BotVersion` produces one giant per-dialog file with hundreds of nested steps inside. That's only marginally easier to review than the original.
+
+**Recipe — two-rule multi-level decomposition.**
+
+```json
+{
+  "metadataSuffixes": "bot",
+  "strategy": "unique-id",
+  "decomposedFormat": "xml",
+  "overrides": [
+    {
+      "metadataTypes": ["bot"],
+      "multiLevel": ["botDialogs:botDialogs:developerName", "botSteps:botSteps:type"]
+    }
+  ]
+}
+```
+
+What this produces on disk for `Sample_Chat_Bot/v1.botVersion-meta.xml` (an Einstein chat bot from the plugin's own fixtures):
+
+```
+bots/
+└── Sample_Chat_Bot/
+    ├── Sample_Chat_Bot.bot-meta.xml                 ← bot header (untouched)
+    ├── v1/
+    │   ├── nlpProviders/
+    │   │   └── EinsteinAi.nlpProviders-meta.xml
+    │   ├── botDialogs/                              ← outer rule lands here
+    │   │   ├── Welcome/                             ← one directory per dialog (named by developerName)
+    │   │   │   ├── Welcome.xml                      ← dialog leaf properties
+    │   │   │   └── botSteps/                        ← inner rule lands here
+    │   │   │       ├── 853b6432/                    ← step with nested content -> own subdir
+    │   │   │       │   ├── 853b6432.xml             ← step leaf properties
+    │   │   │       │   └── botNavigation/           ← nested step content broken out
+    │   │   │       │       └── Redirect.botNavigation-meta.xml
+    │   │   │       └── dc35b789/
+    │   │   │           ├── dc35b789.xml
+    │   │   │           └── botMessages/
+    │   │   │               └── dc35b789.botMessages-meta.xml
+    │   │   ├── End_Chat/
+    │   │   │   ├── End_Chat.xml
+    │   │   │   └── botSteps/
+    │   │   │       ├── 9d031e75.botSteps-meta.xml   ← step with no nested content -> single leaf file
+    │   │   │       └── a7afda99/                    ← step with nested content -> subdir
+    │   │   │           └── ...
+    │   │   └── ...
+    │   ├── .multi_level.json                        ← required for recompose; do not hand-edit
+    │   └── v1.botVersion-meta.xml                   ← leaf-only outer wrapper
+    └── ...
+```
+
+A few things worth knowing before you commit this:
+
+- **Dialog folders are named by developerName**, the way the recipe asks for. So `Welcome`, `End_Chat`, etc. are stable and review-friendly across deploys.
+- **Step folders/files are content-hashed.** The inner rule's `:type` segment tells the disassembler what to look for, but each step's nested content is what determines the on-disk name (`853b6432`, `dc35b789`, ...). The hashes are stable across runs as long as the step content doesn't change, so they diff cleanly. Don't try to "rename them to something nicer" — they'll regenerate on the next decompose.
+- **Each step is one of two shapes**: a leaf `<hash>.botSteps-meta.xml` file when the step has no nested content (e.g. a `Wait` step), or a `<hash>/` directory containing `<hash>.xml` plus subdirectories for the nested content (e.g. a `Message` step with `<botMessages>`, a `Navigation` step with `<botNavigation>`, an Agentforce `Action` step with `<botFlowInvocation>`). Both shapes recompose back to identical `<botSteps>` XML.
+- **The two rules do different things.** The outer `botDialogs` rule is what gives you per-dialog folders — that's the headline win for review-ability. The inner `botSteps` rule additionally splits each step's nested content out of the per-dialog file into per-step subdirectories. For small Einstein bots with shallow steps you can drop the inner rule and still get the dialog-level split; for heavier Agentforce bots the inner rule is the difference between a 50-line per-step subtree and a 500-line per-dialog file.
+
+**When to use a single rule instead.** If your bots have shallow steps (most Einstein chat bots, or pre-Agentforce bots), `multiLevel: ["botDialogs:botDialogs:developerName"]` alone is enough. Each dialog gets its own folder and steps live as flat `*.botSteps-meta.xml` files inside. Recompose is byte-identical either way; the choice is purely about how granular you want the per-step diff to be.
+
+> **Per-bot precision.** Scope the override to a single component when one bot in your repo has a different shape than the rest. The plugin's own bot fixture suite uses this pattern:
+>
+> ```json
+> {
+>   "components": ["bot:Sample_Chat_Bot", "bot:Internal_Copilot_Sample"],
+>   "multiLevel": ["botDialogs:botDialogs:developerName", "botSteps:botSteps:type"]
+> }
+> ```
+
+> **Agentforce vs Einstein.** Both share the `bot` suffix, so a single override entry covers both bot families. The structural difference (Agentforce uses richer `botFlowInvocation` and `genAi*` blocks where Einstein uses `botNavigation` and `mlIntents`) is invisible to this recipe — `multiLevel` rules only target the repeating sections that exist on each side. The plugin ships an `Internal_Copilot_Sample` fixture that exercises the Agentforce-style shape and an Einstein-style `Sample_Chat_Bot` fixture; both round-trip with the same recipe.
+
+> **Sibling order inside `botSteps`.** Recompose orders `<botSteps>` siblings alphabetically by their on-disk filename, not by their original document position. For bot deploys this is a no-op (Salesforce doesn't rely on step order at the XML level), but a freshly-recomposed file may show step entries shuffled compared to the source you originally pulled. The committed fixtures in this repo are baked from the recompose output for that reason — `sf decomposer verify` will treat the baked output as the source of truth.
+
+## Flexipages (Lightning App / Record / Home pages)
+
+**Why this is hard.** A non-trivial flexipage looks like:
+
+```xml
+<FlexiPage>
+  <flexiPageRegions>
+    <itemInstances>
+      <componentInstance>
+        <componentInstanceProperties>...</componentInstanceProperties>
+        <componentName>...</componentName>
+      </componentInstance>
+    </itemInstances>
+    <itemInstances>...</itemInstances>
+    ...
+  </flexiPageRegions>
+  <flexiPageRegions>...</flexiPageRegions>
+</FlexiPage>
+```
+
+Two repeating layers (`flexiPageRegions → itemInstances`) and component identity is buried inside `componentInstance` — the surrounding wrappers don't have a stable name, so a naive `unique-id` pass produces hash-named files that churn whenever a component is reordered.
+
+**Recipe — flexiPageRegions out, then itemInstances per region.**
+
+```json
+{
+  "overrides": [
+    {
+      "metadataTypes": ["flexipage"],
+      "strategy": "unique-id",
+      "multiLevel": ["flexiPageRegions:flexiPageRegions:name", "itemInstances:itemInstances:componentName,facetId"]
+    }
+  ]
+}
+```
+
+What you'll see on disk:
+
+```
+flexipages/
+└── Account_Record_Page/
+    ├── flexiPageRegions/
+    │   ├── header.flexiPageRegions-meta.xml
+    │   ├── main.flexiPageRegions-meta.xml
+    │   └── main/
+    │       └── itemInstances/
+    │           ├── force_highlightsPanel.itemInstances-meta.xml
+    │           ├── runtime_sales_activities__activitiesComponent.itemInstances-meta.xml
+    │           └── ...
+    └── Account_Record_Page.flexipage-meta.xml
+```
+
+**When to adjust.**
+
+- Flexipages where regions are addressed by `regionId` instead of `name` — swap the first rule to `flexiPageRegions:flexiPageRegions:regionId,name`.
+- If the same `componentName` appears multiple times in one region (common for blank `force:emptySpace`), include `facetId` (already in the recipe) and, if needed, a stable property: `itemInstances:itemInstances:componentName,facetId,componentInstanceProperties.value`.
+
+## Layouts (page layouts)
+
+**Why this is hard.** Layouts have three nested repeatables:
+
+```xml
+<Layout>
+  <layoutSections>
+    <layoutColumns>
+      <layoutItems>
+        <field>...</field>
+      </layoutItems>
+    </layoutColumns>
+  </layoutSections>
+</Layout>
+```
+
+For a fat object (Account, Opportunity), this often runs to thousands of lines. Reviewing a "moved one field from column 1 to column 2" change in the raw XML is painful.
+
+**Recipe — section out, item per field.**
+
+```json
+{
+  "overrides": [
+    {
+      "metadataTypes": ["layout"],
+      "strategy": "unique-id",
+      "multiLevel": ["layoutSections:layoutSections:label", "layoutItems:layoutItems:field,customLink,emptySpace"]
+    }
+  ]
+}
+```
+
+What you'll see on disk:
+
+```
+layouts/
+└── Account-Account_Layout/
+    ├── layoutSections/
+    │   ├── Account_Information.layoutSections-meta.xml
+    │   ├── Address_Information.layoutSections-meta.xml
+    │   └── Account_Information/
+    │       └── layoutItems/
+    │           ├── Name.layoutItems-meta.xml
+    │           ├── Type.layoutItems-meta.xml
+    │           └── ...
+    └── Account-Account_Layout.layout-meta.xml
+```
+
+**Caveats.**
+
+- Empty-space layout items (`<emptySpace>true</emptySpace>` with no `field`) all collapse to the same key. The recipe above falls through to `customLink` and then `emptySpace`, but if you have many empty-space spacers per section you'll get hash-named tiebreakers. That's fine for diffs (they only churn when the layout changes), just be aware.
+- Sections with duplicate labels are unusual but legal (e.g. two "Custom Links" sections). If you hit collisions, add a stable secondary like `style`: `layoutSections:layoutSections:label,style`.
+
+## Other deeply-nested types
+
+These follow the same pattern; pick the rules that match your repo's data. None of these are decomposed natively by Salesforce.
+
+| Metadata type                              | Suggested override                                                                                 |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `flow`                                     | `multiLevel: ["actionCalls:actionCalls:name", "decisions:decisions:name", "rules:rules:name"]`     |
+| `globalValueSet`                           | `multiLevel: ["customValue:customValue:fullName"]` — handy when value sets have hundreds of picks. |
+| `marketingappextension`                    | `multiLevel: ["activityDefinitions:activityDefinitions:apiName"]`                                  |
+| `cmsDeliveryChannel` (and other CMS types) | `strategy: grouped-by-tag` plus `splitTags` for any wide repeatable tag.                           |
+| `dashboard`                                | `multiLevel: ["components:components:title"]` — one file per dashboard widget.                     |
+
+If a metadata type has a single deeply-nested repeatable block, a one-rule `multiLevel` is enough. Reach for the array form only when you have **two or more** distinct nested sections you want addressable on disk.
+
+## The verification workflow
+
+Always verify a new override before committing it:
+
+```bash
+# 1. Stash any uncommitted source first.
+git stash --include-untracked
+
+# 2. Decompose with the new override.
+sf decomposer decompose -t bot --config
+
+# 3. Recompose back from the decomposed tree.
+sf decomposer recompose -t bot
+
+# 4. Check the round-trip didn't drift.
+sf decomposer verify -t bot --config
+```
+
+`sf decomposer verify` is non-destructive: it decomposes into a temp dir, recomposes from the temp dir, and compares the result to your committed source. If anything drifts (content, missing file, sibling reorder) it tells you exactly which paths broke. Treat any drift as a blocker — fix the override (or fall back to the previous one) before committing.
+
+## Common pitfalls
+
+**1. "I added two `multiLevel` rules but only one survived."**
+You probably ran two `decompose` invocations back-to-back, one rule each. Don't. The disassembler rewrites `.multi_level.json` on every run, so each call replaces the prior one. Pass every rule for a given component in **one** override entry, in array form.
+
+**2. "My `multiLevel` rule is correct but recompose produces a smaller file."**
+Almost always a unique-id collision. Two array items resolved to the same filename and one overwrote the other on disk. Add a tiebreaker to `unique_id_elements` (e.g. `developerName,id`) and re-decompose with `prePurge: true`.
+
+**3. "Component-scope override fields look ignored."**
+Component-scope wins over type-scope, but only for fields **the component override explicitly sets**. Fields it leaves out fall through to the type-scope value, then to the run-wide default. If you set `decomposedFormat: "yaml"` on a type and `strategy: "grouped-by-tag"` on the component, the component still gets `decomposedFormat: "yaml"` from the type override.
+
+**4. "Reassembly removed my decomposed directory even though I didn't pass `postPurge`."**
+That's by design for `multiLevel` types only. Multi-level recompose has to clean up inner-level directories so the next level can merge their reassembled XML. If you want the decomposed tree preserved for inspection, copy it before running `recompose`.
+
+**5. "Decompose succeeded but my decomposed files all have hash names."**
+Your `unique_id_elements` (or the rule's third part) didn't resolve to a non-empty value on those items. Check the source XML for the elements you listed — names are case-sensitive and live at the immediate child level of each repeating item. The plugin only walks one level deep when picking a UID.
+
+---
+
+When in doubt: write the override, run `verify`, read the diff. Every recipe in this handbook was derived that way.

package/README.md

@@ -17,7 +17,8 @@ A Salesforce CLI plugin that **decomposes** large metadata XML files into smalle
 - [Commands](#commands)
   - [sf decomposer decompose](#sf-decomposer-decompose)
   - [sf decomposer recompose](#sf-decomposer-recompose)
-  - [Manifest-scoped runs](#manifest-scoped-runs)
+  - [sf decomposer verify](#sf-decomposer-verify)
+- [Manifest-scoped runs](#manifest-scoped-runs)
 - [Decompose Strategies](#decompose-strategies)
   - [Custom Labels](#custom-labels-decomposition)
   - [Permission Sets (grouped-by-tag)](#additional-permission-set-decomposition)
@@ -27,6 +28,8 @@ A Salesforce CLI plugin that **decomposes** large metadata XML files into smalle
 - [Troubleshooting](#troubleshooting)
 - [Hooks](#hooks)
 - [Per-Type & Per-Component Overrides](#per-type--per-component-overrides)
+  - [splitTags grammar](#splittags-grammar)
+  - [multiLevel grammar](#multilevel-grammar)
 - [Ignore Files](#ignore-files)
   - [.forceignore](#forceignore)
   - [.sfdecomposerignore](#sfdecomposerignore)
@@ -113,10 +116,11 @@ Salesforce’s built-in decomposition is limited. sf-decomposer gives admins and
 
 ## Commands
 
-| Command                   | Description                                                     |
-| ------------------------- | --------------------------------------------------------------- |
-| `sf decomposer decompose` | Decompose metadata in package directories into smaller files.   |
-| `sf decomposer recompose` | Recompose decomposed files back into deployment-ready metadata. |
+| Command                   | Description                                                                         |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `sf decomposer decompose` | Decompose metadata in package directories into smaller files.                       |
+| `sf decomposer recompose` | Recompose decomposed files back into deployment-ready metadata.                     |
+| `sf decomposer verify`    | Round-trip check: decompose + recompose in a temp directory and diff the originals. |
 
 ### sf decomposer decompose
 
@@ -193,9 +197,49 @@ sf decomposer recompose -x "manifest/package.xml"
 sf project deploy start -x "manifest/package.xml"
 ```
 
-### Manifest-scoped runs
+### sf decomposer verify
 
-The `-x` / `--manifest` flag accepts any standard Salesforce `package.xml` and limits the work to just the components it lists. This is especially useful for CI/CD pipelines that deploy a subset of metadata per change.
+Non-destructive round-trip check: copies your package directories into a temp directory under your OS's `tmpdir()`, runs decompose then recompose there, and diffs the rebuilt parents against the originals using **structural XML equality** (sibling and attribute order are ignored). Exits non-zero on any drift; your working tree is never modified.
+
+```
+USAGE
+  $ sf decomposer verify [-m <value>] [-x <value>] [-f <value>] [-i <value>] [-s <value>] [-p -c --json]
+
+FLAGS
+  -m, --metadata-type=<value>             Metadata suffix to verify (e.g. flow, labels). Repeatable. Optional when --manifest is provided.
+  -x, --manifest=<value>                  Path to a package.xml manifest. When provided, only the components listed in the manifest are verified.
+  -f, --format=<value>                    Output format used for the round-trip decompose: xml | yaml | json | json5 [default: xml]
+  -i, --ignore-package-directory=<value>  Package directory to skip. Repeatable.
+  -s, --strategy=<value>                  unique-id | grouped-by-tag [default: unique-id]
+  -p, --decompose-nested-permissions      With grouped-by-tag, further decompose permission set and muting permission set object/field permissions.
+  -c, --config                            Load per-type and per-component overrides from .sfdecomposer.config.json in the repo root, the same as `decompose --config`. [default: false]
+
+GLOBAL FLAGS
+  --json  Output as JSON.
+```
+
+> At least one of `--metadata-type` or `--manifest` is required. When both are supplied, the run is scoped to the intersection of the two.
+
+**Examples**
+
+```bash
+# Verify two metadata types round-trip cleanly with defaults
+sf decomposer verify -m "permissionset" -m "profile"
+
+# Verify a different strategy + nested-perms split before committing the change
+sf decomposer verify -m "permissionset" -s "grouped-by-tag" -p
+
+# CI gate: verify just the components in a deploy manifest, using the repo-root config
+sf decomposer verify -x "manifest/package.xml" --config
+```
+
+Files where the **only** delta is sibling or attribute ordering are surfaced separately as informational notices ("Note: N file(s) round-tripped semantically but with sibling/attribute reordering") rather than as drift. This is safe — Salesforce treats metadata as order-agnostic and `config-disassembler` does not preserve original sibling order — but it tells you up front that committing the post-recompose output will produce a diff in git even though the metadata is functionally identical.
+
+---
+
+## Manifest-scoped runs
+
+The `-x` / `--manifest` flag is supported by every `sf decomposer` command (`decompose`, `recompose`, `verify`) and accepts any standard Salesforce `package.xml`, limiting the work to just the components it lists. This is especially useful for CI/CD pipelines that deploy a subset of metadata per change.
 
 How it works:
 
@@ -407,15 +451,17 @@ By default, a single decompose run uses one format and one strategy across every
 
 ### What can be overridden
 
-| Field                        | Notes                                                                                                                                                                                                          |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `metadataTypes`              | Optional (required if `components` is omitted). Array of metadata suffixes (same vocabulary as `--metadata-type` / `metadataSuffixes`). Each suffix may appear in at most one override.                        |
-| `components`                 | Optional (required if `metadataTypes` is omitted). Array of `<metadataSuffix>:<fullName>` keys (e.g. `permissionset:HR_Admin`, `report:MyFolder/MyReport`). Each component may appear in at most one override. |
-| `decomposedFormat`           | `xml` \| `json` \| `json5` \| `yaml`.                                                                                                                                                                          |
-| `strategy`                   | `unique-id` \| `grouped-by-tag`. Hard rules still win — `labels` and `loyaltyProgramSetup` are always treated as `unique-id`.                                                                                  |
-| `decomposeNestedPermissions` | Only applies to `permissionset` / `mutingpermissionset` with `grouped-by-tag`.                                                                                                                                 |
-| `prePurge`                   | Per-scope prePurge (decompose). Component-scope `prePurge` only purges the named component's decomposed directory.                                                                                             |
-| `postPurge`                  | Per-scope postPurge (decompose: remove originals after decomposing).                                                                                                                                           |
+| Field                        | Notes                                                                                                                                                                                                                                                        |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `metadataTypes`              | Optional (required if `components` is omitted). Array of metadata suffixes (same vocabulary as `--metadata-type` / `metadataSuffixes`). Each suffix may appear in at most one override.                                                                      |
+| `components`                 | Optional (required if `metadataTypes` is omitted). Array of `<metadataSuffix>:<fullName>` keys (e.g. `permissionset:HR_Admin`, `report:MyFolder/MyReport`). Each component may appear in at most one override.                                               |
+| `decomposedFormat`           | `xml` \| `json` \| `json5` \| `yaml`.                                                                                                                                                                                                                        |
+| `strategy`                   | `unique-id` \| `grouped-by-tag`. Hard rules still win — `labels` and `loyaltyProgramSetup` are always treated as `unique-id`.                                                                                                                                |
+| `decomposeNestedPermissions` | Only applies to `permissionset` / `mutingpermissionset` with `grouped-by-tag`. Sets a known-good `splitTags` default; ignored if `splitTags` is also set in the same scope.                                                                                  |
+| `splitTags`                  | Custom `splitTags` spec for `grouped-by-tag` strategy. See [splitTags grammar](#splittags-grammar). Ignored when the resolved strategy is not `grouped-by-tag`.                                                                                              |
+| `multiLevel`                 | One or more `multiLevel` specs for nested-array decomposition. Pass a string, a `string[]`, or a `;`-separated string. See [multiLevel grammar](#multilevel-grammar). When set, replaces the hardcoded `loyaltyProgramSetup` default for the targeted scope. |
+| `prePurge`                   | Per-scope prePurge (decompose). Component-scope `prePurge` only purges the named component's decomposed directory.                                                                                                                                           |
+| `postPurge`                  | Per-scope postPurge (decompose: remove originals after decomposing).                                                                                                                                                                                         |
 
 Run-scope options (`metadataSuffixes`, `manifest`, `ignorePackageDirectories`) are **not** valid inside an override; the plugin will throw if they are present.
 
@@ -439,6 +485,95 @@ For each component, each option is resolved independently in this order (highest
 3. The run-wide value (CLI flag, hook config top-level field, or built-in default).
 4. Hard plugin rules (e.g. `labels` and `loyaltyProgramSetup` forced to `unique-id`) override all of the above.
 
+### splitTags grammar
+
+`splitTags` lets you control how `grouped-by-tag` writes nested arrays for any metadata type. The plugin already applies a known-good default for permission sets when `decomposeNestedPermissions: true` is set; setting `splitTags` directly takes precedence and works for any metadata type.
+
+**Spec:** Comma-separated rules. Each rule has 3 or 4 colon-separated parts:
+
+- `<tag>:<mode>:<field>` — read array items from the top-level `<tag>`.
+- `<tag>:<path>:<mode>:<field>` — read array items from the nested `<path>` (defaults to `<tag>`).
+
+`<mode>` is one of:
+
+- **`split`** — write one file per array item, named after the value of `<field>` on each item.
+- **`group`** — group array items by the value of `<field>`, writing one file per group.
+
+Each `<tag>` may appear at most once in a spec. The plugin validates the grammar at config-load time. Deeper checks (e.g. unknown tag names for the metadata type) are surfaced by the underlying disassembler crate at runtime.
+
+#### splitTags cookbook
+
+```json
+"overrides": [
+  {
+    "metadataTypes": ["permissionset", "mutingpermissionset"],
+    "strategy": "grouped-by-tag",
+    "splitTags": "objectPermissions:split:object,fieldPermissions:group:field"
+  },
+  {
+    "metadataTypes": ["profile"],
+    "strategy": "grouped-by-tag",
+    "splitTags": "objectPermissions:split:object,fieldPermissions:group:field,layoutAssignments:group:layout"
+  },
+  {
+    "metadataTypes": ["flow"],
+    "strategy": "grouped-by-tag",
+    "splitTags": "actionCalls:split:name,decisions:split:name,assignments:split:name"
+  },
+  {
+    "metadataTypes": ["workflow"],
+    "strategy": "grouped-by-tag",
+    "splitTags": "rules:split:fullName,alerts:split:fullName,fieldUpdates:split:fullName,tasks:split:fullName"
+  }
+]
+```
+
+> **Caveat:** When using `mode: split`, the chosen `<field>` must produce a unique value for every array item — otherwise two items would map to the same filename. If two items share a field value, prefer `mode: group` instead, which is designed for that case.
+
+### multiLevel grammar
+
+`multiLevel` enables a second decomposition pass on inner-level files for metadata types whose XML has deeply nested repeatable blocks (e.g. `loyaltyProgramSetup`'s `programProcesses → parameters → ...`, or a Bot's `botVersion → botDialogs → botSteps`). The plugin already applies a known-good default for `loyaltyProgramSetup` when running the `unique-id` strategy; setting `multiLevel` directly takes precedence and works for any metadata type.
+
+**Spec:** Each rule has exactly 3 colon-separated parts (the third part is itself a comma-separated list):
+
+```
+<file_pattern>:<root_to_strip>:<unique_id_elements>
+```
+
+- **`<file_pattern>`** — basename pattern that selects which inner-level files get the second decomposition pass (e.g. `programProcesses`).
+- **`<root_to_strip>`** — XML root tag to strip from each matched file before splitting.
+- **`<unique_id_elements>`** — comma-separated list of element names used to derive a stable filename for each inner-level item (e.g. `parameterName,ruleName`). The first element that resolves to a non-empty value wins.
+
+A scope may target several nested sections by passing **multiple rules**. Three input shapes are supported:
+
+- a single rule string (legacy, unchanged behaviour);
+- a JSON `string[]` of rules (preferred — clearest intent, easiest to diff);
+- a single `;`-separated string of rules (compact form, also accepted).
+
+Within one scope, the `(file_pattern, root_to_strip)` pair must be unique across rules. The plugin validates the grammar at config-load time; deeper checks (whether a file pattern matches anything, whether the unique-id elements actually appear on the inner XML) are surfaced by the underlying disassembler crate at runtime.
+
+```json
+"overrides": [
+  {
+    "metadataTypes": ["loyaltyProgramSetup"],
+    "multiLevel": "programProcesses:programProcesses:parameterName,ruleName"
+  },
+  {
+    "components": ["bot:Assessment_Bot"],
+    "multiLevel": [
+      "botDialogs:botDialogs:developerName",
+      "botSteps:botSteps:type"
+    ]
+  }
+]
+```
+
+> **Why one call:** Pass every rule for a given component in a single override. Sequential single-rule decompositions rewrite the on-disk `.multi_level.json` and only the last rule survives — so multi-rule scenarios must travel together.
+
+> **Tip:** Use [`sf decomposer verify`](#sf-decomposer-verify) to non-destructively confirm a new override config still round-trips before committing it.
+
+> **Tip:** See the [admin handbook](https://github.com/mcarvin8/sf-decomposer/blob/main/HANDBOOK.md) for end-to-end recipes for Bots, Flexipages, Layouts, and other deeply-nested metadata.
+
 ### Opting in from the CLI
 
 CLI users can opt into overrides on `decompose` with the boolean `--config` (`-c`) flag. When set, the plugin reads `.sfdecomposer.config.json` from the repo root (the nearest ancestor directory that contains `sfdx-project.json`):

package/lib/commands/decomposer/verify.d.ts

@@ -0,0 +1,17 @@
+import { SfCommand } from '@salesforce/sf-plugins-core';
+import { VerifyResult } from '../../helpers/types.js';
+export default class DecomposerVerify extends SfCommand<VerifyResult> {
+    static readonly summary: string;
+    static readonly description: string;
+    static readonly examples: string[];
+    static readonly flags: {
+        'metadata-type': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        manifest: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        format: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'ignore-package-directory': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        strategy: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'decompose-nested-permissions': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        config: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<VerifyResult>;
+}

package/lib/commands/decomposer/verify.js

@@ -0,0 +1,83 @@
+'use strict';
+import { SfCommand, Flags } from '@salesforce/sf-plugins-core';
+import { Messages } from '@salesforce/core';
+import { DECOMPOSED_FILE_TYPES, DECOMPOSED_STRATEGIES } from '../../helpers/constants.js';
+import { verifyMetadataTypes } from '../../core/verifyMetadataTypes.js';
+import { loadOverridesFromConfig, resolveDefaultConfigPath } from '../../helpers/configOverrides.js';
+Messages.importMessagesDirectoryFromMetaUrl(import.meta.url);
+const messages = Messages.loadMessages('sf-decomposer', 'decomposer.verify');
+export default class DecomposerVerify extends SfCommand {
+    static summary = messages.getMessage('summary');
+    static description = messages.getMessage('description');
+    static examples = messages.getMessages('examples');
+    static flags = {
+        'metadata-type': Flags.string({
+            summary: messages.getMessage('flags.metadata-type.summary'),
+            char: 'm',
+            multiple: true,
+            required: false,
+        }),
+        manifest: Flags.file({
+            summary: messages.getMessage('flags.manifest.summary'),
+            char: 'x',
+            required: false,
+            exists: true,
+        }),
+        format: Flags.string({
+            summary: messages.getMessage('flags.format.summary'),
+            char: 'f',
+            required: true,
+            multiple: false,
+            default: 'xml',
+            options: DECOMPOSED_FILE_TYPES,
+        }),
+        'ignore-package-directory': Flags.directory({
+            summary: messages.getMessage('flags.ignore-package-directory.summary'),
+            char: 'i',
+            required: false,
+            multiple: true,
+        }),
+        strategy: Flags.string({
+            summary: messages.getMessage('flags.strategy.summary'),
+            char: 's',
+            required: true,
+            multiple: false,
+            default: 'unique-id',
+            options: DECOMPOSED_STRATEGIES,
+        }),
+        'decompose-nested-permissions': Flags.boolean({
+            summary: messages.getMessage('flags.decompose-nested-permissions.summary'),
+            char: 'p',
+            required: false,
+            default: false,
+        }),
+        config: Flags.boolean({
+            summary: messages.getMessage('flags.config.summary'),
+            char: 'c',
+            required: false,
+            default: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(DecomposerVerify);
+        if (!flags['metadata-type'] && !flags['manifest']) {
+            throw messages.createError('error.missingMetadataOrManifest');
+        }
+        const overrides = flags['config'] ? await loadOverridesFromConfig(await resolveDefaultConfigPath()) : undefined;
+        const result = await verifyMetadataTypes({
+            metadataTypes: flags['metadata-type'],
+            format: flags['format'],
+            ignoreDirs: flags['ignore-package-directory'],
+            strategy: flags['strategy'],
+            decomposeNestedPerms: flags['decompose-nested-permissions'],
+            manifest: flags['manifest'],
+            overrides,
+            log: this.log.bind(this),
+        });
+        if (result.drift.length > 0) {
+            throw messages.createError('error.driftDetected', [String(result.drift.length)]);
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=verify.js.map

package/lib/commands/decomposer/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../src/commands/decomposer/verify.ts"],"names":[],"mappings":"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"}