diff --git a/packages/bitbadgesjs-sdk/scripts/gen-skill-docs.ts b/packages/bitbadgesjs-sdk/scripts/gen-skill-docs.ts
new file mode 100644
index 0000000000..6f1a3d9dac
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/scripts/gen-skill-docs.ts
@@ -0,0 +1,112 @@
+#!/usr/bin/env tsx
+/**
+ * Generate docs pages from builder skill instructions.
+ *
+ * Source of truth: src/builder/resources/skillInstructions.ts
+ * Output: ../bitbadges-docs/x-tokenization/examples/skills/
+ *
+ * Ported from the old bitbadges-builder-mcp/scripts/gen-skill-docs.ts
+ * when the MCP server was folded into the SDK. The only real change is
+ * the import path — SKILL_INSTRUCTIONS now lives under the SDK's builder
+ * subpath. Output shape + docs destination are unchanged so the existing
+ * SUMMARY.md entries and any review diffs stay stable.
+ *
+ * Usage: npx tsx scripts/gen-skill-docs.ts
+ *        (optional) DOCS_OUTPUT_DIR=/path/to/override npx tsx scripts/gen-skill-docs.ts
+ */
+
+import { SKILL_INSTRUCTIONS } from '../src/builder/resources/skillInstructions.js';
+import { writeFileSync, mkdirSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+
+// Resolve __dirname in a way that works both when tsx runs this file as
+// ESM (import.meta.url present) and when it transpiles to CJS (falls
+// back to __dirname if already defined). The docs output path is
+// resolved relative to this script's location so running from any cwd
+// produces the same result.
+const here =
+  typeof __dirname !== 'undefined'
+    ? __dirname
+    : dirname(fileURLToPath(import.meta.url));
+
+const DOCS_DIR =
+  process.env.DOCS_OUTPUT_DIR ||
+  join(here, '../../../../bitbadges-docs/x-tokenization/examples/skills');
+
+mkdirSync(DOCS_DIR, { recursive: true });
+
+const categoryLabels: Record<string, string> = {
+  'token-type': 'Token Types',
+  standard: 'Standards',
+  approval: 'Approval Patterns',
+  feature: 'Features',
+  advanced: 'Advanced',
+};
+
+// Group skills by category for the README
+const byCategory = new Map<string, typeof SKILL_INSTRUCTIONS>();
+for (const skill of SKILL_INSTRUCTIONS) {
+  const list = byCategory.get(skill.category) || [];
+  list.push(skill);
+  byCategory.set(skill.category, list);
+}
+
+// Generate individual skill pages
+for (const skill of SKILL_INSTRUCTIONS) {
+  const filename = `${skill.id}.md`;
+  const refs = skill.referenceCollectionIds?.length
+    ? `\n\n## Reference Collections\n\n${skill.referenceCollectionIds
+        .map((id) => `- [Collection ${id}](https://bitbadges.io/collections/${id})`)
+        .join('\n')}`
+    : '';
+
+  const content = `# ${skill.name}
+
+> ${skill.description}
+
+**Category:** ${categoryLabels[skill.category] || skill.category}
+
+## Summary
+
+${skill.summary}
+
+## Instructions
+
+${skill.instructions}${refs}
+`;
+
+  writeFileSync(join(DOCS_DIR, filename), content);
+}
+
+// Generate README index
+const categoryOrder = ['token-type', 'standard', 'approval', 'feature', 'advanced'];
+let readme = `# 🤖 Builder Skills
+
+These pages document every guided build skill available in the BitBadges Builder (shipped as part of [bitbadgesjs-sdk](https://github.com/BitBadges/bitbadgesjs)). Each skill provides step-by-step instructions for building a specific type of token or configuring a specific feature.
+
+> **Tip:** If you're using the BitBadges builder in Claude, Cursor, or another AI tool via the MCP server (\`npx bitbadgesjs-sdk-mcp\`) or the \`bitbadges-cli builder\` command surface, these instructions are loaded automatically when you select a skill. These pages are provided as a human-readable reference.
+
+`;
+
+for (const cat of categoryOrder) {
+  const skills = byCategory.get(cat);
+  if (!skills?.length) continue;
+  readme += `## ${categoryLabels[cat] || cat}\n\n`;
+  for (const skill of skills) {
+    readme += `- [${skill.name}](${skill.id}.md) — ${skill.description}\n`;
+  }
+  readme += '\n';
+}
+
+writeFileSync(join(DOCS_DIR, 'README.md'), readme);
+
+// Print SUMMARY.md lines for easy copy-paste
+console.log('\n=== Add these lines to SUMMARY.md as a top-level section ===\n');
+console.log('## 🤖 Builder Skills\n');
+console.log('* [Overview](x-tokenization/examples/skills/README.md)');
+for (const skill of SKILL_INSTRUCTIONS) {
+  console.log(`  * [${skill.name}](x-tokenization/examples/skills/${skill.id}.md)`);
+}
+
+console.log(`\n✅ Generated ${SKILL_INSTRUCTIONS.length} skill pages + README in ${DOCS_DIR}`);
diff --git a/packages/bitbadgesjs-sdk/src/builder/index.ts b/packages/bitbadgesjs-sdk/src/builder/index.ts
index 7a5c29bfce..02a0aef4e4 100644
--- a/packages/bitbadgesjs-sdk/src/builder/index.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/index.ts
@@ -1,11 +1,15 @@
 #!/usr/bin/env node
 
 /**
- * BitBadges Builder MCP Server
+ * BitBadges Builder — Model Context Protocol (MCP) stdio server bin.
  *
- * Enable natural language collection creation via MCP.
+ * Entry point when users run `bitbadges-builder` or point Claude Desktop at
+ * this package as an MCP server. The actual tool/resource handlers live in
+ * `./tools/registry.ts` and `./resources/registry.ts` — this file is just
+ * the stdio transport + lifecycle wrapper. For in-process use, import the
+ * registry directly or call `bitbadges-cli builder …`.
  *
- * Example usage:
+ * Example natural-language usage (via an MCP client):
  * > "Create a 1:1 backed USDC stablecoin with 100 USDC/day spend limit"
  *
  * Supported collection types:
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/examplesDocs.ts b/packages/bitbadgesjs-sdk/src/builder/resources/examplesDocs.ts
index a5a9bd2f03..1441cdc162 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/examplesDocs.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/examplesDocs.ts
@@ -130,7 +130,26 @@ Create a collection of 100 unique NFTs with a public mint approval.
           "cosmosCoinBackedPath": null
         },
         "aliasPathsToAdd": [],
-        "cosmosCoinWrapperPathsToAdd": []
+        "cosmosCoinWrapperPathsToAdd": [],
+        "_meta": {
+          "metadataPlaceholders": {
+            "ipfs://METADATA_COLLECTION": {
+              "name": "My NFT Collection",
+              "description": "A collection of 100 unique NFTs.",
+              "image": "ipfs://QmCollectionImage..."
+            },
+            "ipfs://METADATA_TOKEN_{id}": {
+              "name": "My NFT Collection Token",
+              "description": "A unique NFT from the My NFT Collection.",
+              "image": "ipfs://QmTokenImage..."
+            },
+            "ipfs://METADATA_APPROVAL_mint": {
+              "name": "Public Mint",
+              "description": "Allows anyone to mint one NFT for 5 BADGE.",
+              "image": ""
+            }
+          }
+        }
       }
     }
   ],
@@ -138,23 +157,6 @@ Create a collection of 100 unique NFTs with a public mint approval.
   "fee": {
     "amount": [{ "denom": "ubadge", "amount": "5000" }],
     "gas": "500000"
-  },
-  "metadataPlaceholders": {
-    "ipfs://METADATA_COLLECTION": {
-      "name": "My NFT Collection",
-      "description": "A collection of 100 unique NFTs.",
-      "image": "ipfs://QmCollectionImage..."
-    },
-    "ipfs://METADATA_TOKEN_{id}": {
-      "name": "My NFT Collection Token",
-      "description": "A unique NFT from the My NFT Collection.",
-      "image": "ipfs://QmTokenImage..."
-    },
-    "ipfs://METADATA_APPROVAL_mint": {
-      "name": "Public Mint",
-      "description": "Allows anyone to mint one NFT for 5 BADGE.",
-      "image": ""
-    }
   }
 }
 \`\`\``,
@@ -253,7 +255,31 @@ Create a fungible token with unlimited supply.
           "cosmosCoinBackedPath": null
         },
         "aliasPathsToAdd": [],
-        "cosmosCoinWrapperPathsToAdd": []
+        "cosmosCoinWrapperPathsToAdd": [],
+        "_meta": {
+          "metadataPlaceholders": {
+            "ipfs://METADATA_COLLECTION": {
+              "name": "My Token",
+              "description": "A fungible token with unlimited supply.",
+              "image": "ipfs://QmTokenImage..."
+            },
+            "ipfs://METADATA_TOKEN": {
+              "name": "MY",
+              "description": "The MY token unit.",
+              "image": "ipfs://QmTokenImage..."
+            },
+            "ipfs://METADATA_APPROVAL_mint": {
+              "name": "Public Mint",
+              "description": "Allows anyone to mint tokens freely.",
+              "image": ""
+            },
+            "ipfs://METADATA_APPROVAL_transfer": {
+              "name": "Free Transfer",
+              "description": "Allows free transfer between users.",
+              "image": ""
+            }
+          }
+        }
       }
     }
   ],
@@ -261,28 +287,6 @@ Create a fungible token with unlimited supply.
   "fee": {
     "amount": [{ "denom": "ubadge", "amount": "5000" }],
     "gas": "500000"
-  },
-  "metadataPlaceholders": {
-    "ipfs://METADATA_COLLECTION": {
-      "name": "My Token",
-      "description": "A fungible token with unlimited supply.",
-      "image": "ipfs://QmTokenImage..."
-    },
-    "ipfs://METADATA_TOKEN": {
-      "name": "MY",
-      "description": "The MY token unit.",
-      "image": "ipfs://QmTokenImage..."
-    },
-    "ipfs://METADATA_APPROVAL_mint": {
-      "name": "Public Mint",
-      "description": "Allows anyone to mint tokens freely.",
-      "image": ""
-    },
-    "ipfs://METADATA_APPROVAL_transfer": {
-      "name": "Free Transfer",
-      "description": "Allows free transfer between users.",
-      "image": ""
-    }
   }
 }
 \`\`\``,
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/frontendDocs.ts b/packages/bitbadgesjs-sdk/src/builder/resources/frontendDocs.ts
index 76d980ca5f..2079eea00a 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/frontendDocs.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/frontendDocs.ts
@@ -28,7 +28,7 @@ const FRONTEND_DOCS_CONTENT = {
 
 ### Address Handling
 - Always validate addresses before use (0x or bb1 format)
-- Use \`convert_address\` MCP tool or SDK's \`ethToCosmos\`/\`cosmosToEth\` for format conversion
+- Use the \`convert_address\` builder tool or SDK's \`ethToCosmos\`/\`cosmosToEth\` for format conversion
 - Display resolved names when available
 
 ### Amount Display
@@ -37,7 +37,7 @@ const FRONTEND_DOCS_CONTENT = {
 - Show both the human-readable amount and denomination
 
 ### Transaction Flow
-- Build transaction JSON (via MCP tools or manually)
+- Build transaction JSON (via builder tools or manually)
 - Present to user for review before signing
 - User signs with their wallet (MetaMask for EVM, Keplr for Cosmos)
 - Broadcast the signed transaction
@@ -46,7 +46,7 @@ const FRONTEND_DOCS_CONTENT = {
   collectionPatterns: `## Working with Collections
 
 ### Fetching Collection Data
-Use the BitBadges API (via SDK or MCP \`query_collection\` tool):
+Use the BitBadges API (via SDK or the builder's \`query_collection\` tool):
 \`\`\`typescript
 import { BitBadgesAPI } from 'bitbadgesjs-sdk';
 
@@ -79,7 +79,7 @@ const protocolData = JSON.parse(collection.customData || '{}');
   transactionPatterns: `## Transaction Patterns
 
 ### Building and Submitting
-1. Build transaction JSON using MCP tools or construct manually
+1. Build transaction JSON using builder tools or construct manually
 2. Validate with \`validate_transaction\` tool
 3. Present to user for review
 4. User signs with their wallet
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/masterPrompt.ts b/packages/bitbadgesjs-sdk/src/builder/resources/masterPrompt.ts
index a615cea8fe..dc02d33667 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/masterPrompt.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/masterPrompt.ts
@@ -89,13 +89,13 @@ When the user wants to:
 - Update existing collection → Use MsgUniversalUpdateCollection with actual collection ID
 - Create subscription → Use MsgUniversalUpdateCollection with "Subscriptions" standard
 
-## Build → Audit → Deploy Flow (MANDATORY)
+## Build → Review → Deploy Flow (MANDATORY)
 
 After EVERY collection build, follow this pipeline:
 1. **Build** → Use per-field tools in parallel: set_standards, set_valid_token_ids, set_invariants, add_approval, set_permissions, set_default_balances, set_collection_metadata, set_token_metadata, add_alias_path, set_mint_escrow_coins
-2. **Audit** → audit_collection, validate_transaction
-3. **Fix** → Address findings, re-audit if needed
-4. **Present** → Show audit results to user with plain-language explanations
+2. **Review** → review_collection, validate_transaction
+3. **Fix** → Address findings, re-review if needed
+4. **Present** → Show review results to user with plain-language explanations
 5. **Deploy** → get_transaction to retrieve the final transaction, return for user review and submission
 
 **IMPORTANT: JSON Output Format** — When returning the final transaction JSON, do NOT just print it inline in the terminal. Terminal output often introduces formatting artifacts (line wrapping, ANSI codes, truncation) that break JSON parsing. Instead:
@@ -136,7 +136,7 @@ The complete transaction is a JSON object with this EXACT structure:
 
 {
   "messages": [
-    { "typeUrl": "/tokenization.MsgUniversalUpdateCollection", "value": {...} }
+    { "typeUrl": "/tokenization.MsgCreateCollection", "value": {...} }
   ],
   "memo": "Optional memo text",
   "fee": {
@@ -149,7 +149,7 @@ The complete transaction is a JSON object with this EXACT structure:
 1. All numbers as strings: "1" not 1, "0" not 0
 2. UintRange format: { "start": "1", "end": "18446744073709551615" }
 3. Max uint64: "18446744073709551615" (use for "forever" time ranges)
-4. collectionId: "0": Creates new collection OR references just-created collection`,
+4. New vs edit: use MsgCreateCollection to create a new collection, MsgUpdateCollection (with real collectionId) to edit one.`,
 
   messageTypes: `## Message Types
 
@@ -157,13 +157,15 @@ The complete transaction is a JSON object with this EXACT structure:
 
 | typeUrl | Purpose |
 |---------|---------|
-| /tokenization.MsgUniversalUpdateCollection | Create/update collections |
+| /tokenization.MsgCreateCollection | Create a new collection. Keeps \`defaultBalances\` and \`invariants\`; no \`collectionId\` and no \`updateXxxTimeline\` flags. |
+| /tokenization.MsgUpdateCollection | Edit an existing collection. Requires non-zero \`collectionId\` + \`updateXxxTimeline\` flags. Never set \`defaultBalances\` or \`invariants\` here. |
 | /tokenization.MsgCreateAddressLists | Create reusable address lists |
 | /tokenization.MsgUpdateUserApprovals | Update user-level approvals |
+| /tokenization.MsgTransferTokens | Mint or transfer tokens (commonly paired after Create for initial distribution) |
 
 ### Message Selection
-- **New collection**: MsgUniversalUpdateCollection with collectionId: "0"
-- **Update collection**: MsgUniversalUpdateCollection with actual ID`,
+- **New collection**: MsgCreateCollection (optionally followed by MsgTransferTokens for initial mint)
+- **Edit existing**: MsgUpdateCollection with the real \`collectionId\` and the \`updateXxxTimeline\` flags for the fields you intend to change.`,
 
   msgUniversalUpdateCollection: `## MsgUniversalUpdateCollection - Complete Structure
 
@@ -922,56 +924,76 @@ Before outputting JSON, verify:
 
   metadataPlaceholders: `## Metadata Placeholders System
 
-The metadataPlaceholders system allows you to generate metadata for collection, token, or approval metadata that will be automatically uploaded to IPFS.
+The metadataPlaceholders system allows you to generate metadata for collection, token, approval, and alias-path metadata that will be automatically uploaded to IPFS.
+
+The sidecar lives **inside the message**, at \`messages[i].value._meta.metadataPlaceholders\`. It is NOT a top-level sibling of \`messages\`. Every placeholder URI referenced by this message's body gets a matching entry in this map — no wrapper-level copy, no parallel shape.
 
 ### Format
 
 \`\`\`json
 {
-  "messages": [...],
-  "metadataPlaceholders": {
-    "ipfs://METADATA_COLLECTION": {
-      "name": "My Collection Name",
-      "description": "A description of the collection.",
-      "image": "https://example.com/image.png"
-    },
-    "ipfs://METADATA_TOKEN_1": {
-      "name": "Token Name",
-      "description": "Token description.",
-      "image": "https://example.com/token.png"
-    },
-    "ipfs://METADATA_APPROVAL_public-mint": {
-      "name": "Public Mint Approval",
-      "description": "Allows anyone to mint one token by paying 5 BADGE.",
-      "image": ""
-    },
-    "ipfs://METADATA_ALIAS_PATH": {
-      "name": "vATOM",
-      "description": "Wrapped ATOM token for liquidity pools.",
-      "image": "https://example.com/vatom.png"
+  "messages": [
+    {
+      "typeUrl": "/tokenization.MsgUniversalUpdateCollection",
+      "value": {
+        "collectionMetadata": { "uri": "ipfs://METADATA_COLLECTION", "customData": "" },
+        "tokenMetadata": [
+          { "uri": "ipfs://METADATA_TOKEN_1", "customData": "", "tokenIds": [{ "start": "1", "end": "1" }] }
+        ],
+        "collectionApprovals": [
+          { "approvalId": "public-mint", "uri": "ipfs://METADATA_APPROVAL_public-mint", "...": "..." }
+        ],
+        "aliasPathsToAdd": [
+          { "denom": "uvatom", "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom", "customData": "" }, "...": "..." }
+        ],
+        "_meta": {
+          "metadataPlaceholders": {
+            "ipfs://METADATA_COLLECTION": {
+              "name": "My Collection Name",
+              "description": "A description of the collection.",
+              "image": "https://example.com/image.png"
+            },
+            "ipfs://METADATA_TOKEN_1": {
+              "name": "Token Name",
+              "description": "Token description.",
+              "image": "https://example.com/token.png"
+            },
+            "ipfs://METADATA_APPROVAL_public-mint": {
+              "name": "Public Mint Approval",
+              "description": "Allows anyone to mint one token by paying 5 BADGE.",
+              "image": ""
+            },
+            "ipfs://METADATA_ALIAS_uvatom": {
+              "name": "vATOM",
+              "description": "Wrapped ATOM token for liquidity pools.",
+              "image": "https://example.com/vatom.png"
+            }
+          }
+        }
+      }
     }
-  }
+  ]
 }
 \`\`\`
 
 ### How It Works
 
-1. In your messages, use placeholder URIs like \`ipfs://METADATA_COLLECTION\`, \`ipfs://METADATA_TOKEN_1\`, etc.
-2. In the \`metadataPlaceholders\` object, provide the actual metadata for each placeholder URI
-3. The system will automatically replace the placeholder URIs with the provided metadata and upload to IPFS
+1. In your message body, use placeholder URIs like \`ipfs://METADATA_COLLECTION\`, \`ipfs://METADATA_TOKEN_1\`, etc.
+2. In the same message's \`value._meta.metadataPlaceholders\` object, provide the actual metadata for each placeholder URI.
+3. The system will automatically replace the placeholder URIs with the provided metadata and upload to IPFS.
 4. This works for:
    - Collection metadata (collectionMetadata.uri)
    - Token metadata (tokenMetadata[].uri)
    - Approval metadata (collectionApprovals[].uri)
-   - Alias path metadata (aliasPathsToAdd[].metadata.uri)
+   - Alias path metadata (aliasPathsToAdd[].metadata.uri and denomUnits[].metadata.uri)
 
 ### Important Notes
 
-- Approval metadata should have \`image: ""\` (empty string) as approvals don't have images
-- Collection and token metadata require \`name\`, \`description\`, and \`image\`
-- You can use any placeholder URI format (e.g., \`ipfs://METADATA_APPROVAL_public-mint\`)
-- The placeholder URI in the message must exactly match the key in \`metadataPlaceholders\`
-- Always include proper descriptions ending with periods`,
+- The sidecar lives at \`messages[0].value._meta.metadataPlaceholders\` — per-message, NOT at the tx wrapper level.
+- Approval metadata MUST have \`image: ""\` (empty string) — approvals don't have images.
+- Collection, token, and alias-path metadata require \`name\`, \`description\`, and \`image\`.
+- The placeholder URI in the message body must exactly match the key in \`_meta.metadataPlaceholders\`.
+- Always include proper descriptions ending with periods.`,
 
   evmQueryChallenges: `## EVM Query Challenges (v25+)
 
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/recipes.ts b/packages/bitbadgesjs-sdk/src/builder/resources/recipes.ts
index 9a71e7e906..49ff74d282 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/recipes.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/recipes.ts
@@ -76,7 +76,7 @@ const api = new BitBadgesAPI({ apiUrl: 'https://api.bitbadges.io', apiKey: proce
 const balance = await api.getBalanceByAddress(collectionId, 'bb1address...');
 console.log(balance.balances); // Balance[]
 
-// Or via MCP: query_balance({ collectionId: "123", address: "bb1..." })`
+// Or via the builder: query_balance({ collectionId: "123", address: "bb1..." })`
   },
   {
     id: 'transfer-tokens',
@@ -110,7 +110,7 @@ const transferMsg = {
     name: 'Verify Token Ownership (Gate Access)',
     description: 'Check if an address owns specific tokens — use for gating',
     tags: ['verify', 'gate', 'access', 'ownership', 'check'],
-    code: `// Via MCP tool: verify_ownership
+    code: `// Via builder tool: verify_ownership
 // Supports AND/OR/NOT logic for complex ownership checks
 //
 // verify_ownership({
@@ -135,7 +135,7 @@ const hasToken = balance.balances.some(b =>
     tags: ['smart-token', 'ibc', 'usdc', 'wrapped', 'stablecoin', 'backing'],
     code: `// Smart Token Key Points:
 //
-// 1. Use generate_backing_address MCP tool to get the deterministic backing address
+// 1. Use generate_backing_address builder tool to get the deterministic backing address
 //    for an IBC denom (e.g., USDC → bb1backingaddr...)
 //
 // 2. Two approvals required (backing + unbacking). Transferable is common but optional:
@@ -218,7 +218,7 @@ const bb1Address = ethToCosmos('0x1234...');
 // BitBadges -> ETH
 const ethAddress = cosmosToEth('bb1...');
 
-// Or via MCP: convert_address({ address: "0x1234..." })
+// Or via the builder: convert_address({ address: "0x1234..." })
 
 // IMPORTANT: This is byte-level conversion (same key, different encoding)
 // This is NOT public key derivation — both addresses share the same key pair`
@@ -265,9 +265,9 @@ const withdrawMsg = {
 
 // Server-side verification:
 // 1. Client presents their address
-// 2. Server verifies ownership via MCP or API
+// 2. Server verifies ownership via the builder or API
 
-// Via MCP:
+// Via the builder:
 // verify_ownership({
 //   address: "bb1clientaddress...",
 //   requirements: {
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/registry.ts b/packages/bitbadgesjs-sdk/src/builder/resources/registry.ts
index b6a241b1cc..2bd3a20686 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/registry.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/registry.ts
@@ -2,7 +2,7 @@
  * Central resource registry.
  *
  * Mirrors the tool registry (src/tools/registry.ts). Single source of truth
- * for every MCP resource so the stdio server and library consumers
+ * for every builder resource so the stdio server and library consumers
  * (bitbadges-cli, bitbadgeschaind) see the same surface.
  *
  * A resource is a static-ish document addressed by URI. Unlike tools, reads
@@ -47,7 +47,7 @@ export interface ResourceEntry {
 }
 
 // Inline ResourceInfo for the skills resource — it was defined ad-hoc inside
-// server.ts before. Keeping the same metadata the MCP server used to expose.
+// server.ts before. Keeping the same metadata the stdio server used to expose.
 const skillsAllInfo: ResourceInfo = {
   uri: 'bitbadges://skills/all',
   name: 'Skill Instructions',
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts b/packages/bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts
index 822a993215..94e758da71 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/skillInstructions.ts
@@ -36,8 +36,8 @@ export const SKILL_INSTRUCTIONS: SkillInstruction[] = [
 - Unbacking fromListId uses "!Mint:backingAddress" syntax (excludes both Mint and backing address — meaning only regular holders can unback)
 - Backing address is deterministic — use generate_backing_address tool
 - Optional: Add "AI Agent Vault" to standards for AI Prompt tab (display-only)
-- Alias path: symbol = base unit (e.g. "uvatom"), denomUnits = display units with decimals > 0 only, each denomUnit MUST have metadata with an image
-- All alias path and denomUnit metadata MUST include an \`image\` field (token logo URL)`,
+- Alias path: symbol = base unit (e.g. "uvatom"), denomUnits = display units with decimals > 0 only, each denomUnit MUST have PathMetadata with a placeholder uri
+- PathMetadata ONLY has \`{ uri, customData }\` — do NOT include image/name/description fields. Set metadata.uri to a placeholder like \`"ipfs://METADATA_ALIAS_<denom>"\` and register the image/name/description in the metadataPlaceholders sidecar keyed by that URI`,
     instructions: `## Smart Token Configuration
 
 ### Mental Model: Three Phases
@@ -195,9 +195,9 @@ MUST configure at least one alias path. Structure:
       "decimals": "6",
       "symbol": "vATOM",
       "isDefaultDisplay": true,
-      "metadata": { "uri": "ipfs://...", "customData": "" }
+      "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom_UNIT", "customData": "" }
     }],
-    "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" }
+    "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom", "customData": "" }
   }]
 }
 \`\`\`
@@ -205,10 +205,9 @@ MUST configure at least one alias path. Structure:
 Rules:
 - symbol = base unit symbol (e.g., "uvatom")
 - denomUnits = display units with decimals > 0 ONLY (base decimals 0 is implicit)
-- Each denomUnit MUST have metadata with an image field (often the same image as the base alias path)
-- The alias path itself MUST have metadata with an image field — this is the token logo shown in the UI
+- Each denomUnit and the path itself MUST have PathMetadata of the form \`{ uri, customData }\`. Use a placeholder URI like \`"ipfs://METADATA_ALIAS_<denom>"\` / \`"ipfs://METADATA_ALIAS_<denom>_UNIT"\`.
 - isDefaultDisplay: true for the primary display unit
-- **CRITICAL**: All metadata objects (alias path, denomUnits, cosmosCoinWrapperPaths) MUST include an \`image\` field with a valid URL. Missing images will be auto-fixed to a default but you should always provide a descriptive image.
+- **CRITICAL**: PathMetadata has EXACTLY two fields — \`uri\` and \`customData\`. Never add \`image\`, \`name\`, or \`description\` here. Register the name, description, and image for each placeholder URI in the \`metadataPlaceholders\` sidecar returned alongside the transaction — the metadata auto-apply flow uploads the off-chain JSON and substitutes the placeholder URIs with real IPFS URIs after deploy.
 
 ### Cosmos Coin Wrapper (Optional)
 
@@ -222,8 +221,8 @@ For wrapping native Cosmos SDK coins, use \`allowSpecialWrapping: true\` and \`c
       "sideA": { "amount": "1" },
       "sideB": [{ "amount": "1", "tokenIds": [{ "start": "1", "end": "1" }], "ownershipTimes": [{ "start": "1", "end": "18446744073709551615" }] }]
     },
-    "denomUnits": [{ "decimals": "6", "symbol": "ATOM", "isDefaultDisplay": true, "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" } }],
-    "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" },
+    "denomUnits": [{ "decimals": "6", "symbol": "ATOM", "isDefaultDisplay": true, "metadata": { "uri": "ipfs://METADATA_WRAPPER_uatom_UNIT", "customData": "" } }],
+    "metadata": { "uri": "ipfs://METADATA_WRAPPER_uatom", "customData": "" },
     "allowOverrideWithAnyValidToken": false
   }]
 }
@@ -284,8 +283,8 @@ Require ownership of a 2FA token to withdraw. Add mustOwnTokens to the unbacking
 
 ### Metadata Guidance
 
-- Collection metadata, token metadata, alias path metadata, and denomUnit metadata should all have descriptive names/descriptions and images
-- Do NOT use lazy placeholder names like "Backing Approval" — write real user-facing descriptions explaining what each approval does
+- Collection, token, alias path, and denomUnit metadata proto fields are ALL shaped as \`{ uri, customData }\`. Use placeholder URIs (\`ipfs://METADATA_COLLECTION\`, \`ipfs://METADATA_TOKEN_<id>\`, \`ipfs://METADATA_ALIAS_<denom>\`, etc.) and register the real names, descriptions, and images in the \`metadataPlaceholders\` sidecar keyed by those URIs. The auto-apply flow uploads the off-chain JSON and substitutes the placeholder URIs with real uploaded URIs after deploy.
+- Do NOT use lazy placeholder names like "Backing Approval" — write real user-facing descriptions inside the metadataPlaceholders entries explaining what each approval / collection / token does.
 
 ### Key Rules Summary
 
@@ -585,9 +584,9 @@ When enabling liquidity pools for a collection, follow these requirements:
          "decimals": "6",
          "symbol": "vATOM",
          "isDefaultDisplay": true,
-         "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" }
+         "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom_UNIT", "customData": "" }
        }],
-       "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" }
+       "metadata": { "uri": "ipfs://METADATA_ALIAS_uvatom", "customData": "" }
      }]
    }
    \`\`\`
@@ -596,7 +595,7 @@ When enabling liquidity pools for a collection, follow these requirements:
 
 - disablePoolCreation MUST be false (not true)
 - MUST configure at least one alias path (required for liquidity pools)
-- All alias path and denomUnit metadata MUST include an \`image\` field with a valid URL (token logo)
+- PathMetadata (on every aliasPath and denomUnit) is ONLY \`{ uri, customData }\`. Put the token logo in the off-chain JSON at the placeholder URI and register a matching entry in \`metadataPlaceholders\` — never put \`image\` on the proto.
 - Merkle challenges are NOT compatible with liquidity pools
 - This enables decentralized exchange (DEX) trading interfaces`
   },
@@ -1188,7 +1187,7 @@ When creating a Custom-2FA collection, follow these requirements:
 - Manager can add (mint) and remove (burn) addresses
 - No peer-to-peer transfers
 - Requires TWO approvals: manager-add (minting) + manager-remove (burn to bb1qqq...s7gvmv)
-- After building, proceed with audit_collection + validate_transaction as normal`,
+- After building, proceed with review_collection + validate_transaction as normal`,
     instructions: `## Address List Token Type
 
 Use per-field tools to create this collection. It requires:
@@ -1201,7 +1200,7 @@ Use per-field tools to create this collection. It requires:
 
 This creates a token collection where list membership = owning x1 of token ID 1. The manager can add (mint) and remove (burn) addresses. No peer-to-peer transfers.
 
-After building, proceed with audit_collection and validate_transaction as normal.`
+After building, proceed with review_collection and validate_transaction as normal.`
   },
   {
     id: 'bb-402',
@@ -1829,7 +1828,7 @@ MUST include an alias path so tokens display nicely:
   },
   "symbol": "<SYMBOL>",
   "denomUnits": [],
-  "metadata": { "uri": "", "customData": "", "image": "https://example.com/token-logo.png" }
+  "metadata": { "uri": "ipfs://METADATA_ALIAS_u<symbol_lowercase>", "customData": "" }
 }]
 \`\`\`
 
@@ -2245,6 +2244,7 @@ Without this, the escrow has no funds and claims will fail.
 - Binary prediction market: "Will X happen by Y?" Users deposit USDC to mint paired YES+NO tokens. Trade YES↔NO on a liquidity pool. Verifier settles by voting. Winner redeems 1:1.
 - Token ID 1 = YES, Token ID 2 = NO (via alias paths with 6 decimals)
 - mintEscrowAddress holds all deposited USDC
+- invariants: \\\`noForcefulPostMintTransfers: true\\\` — locks non-mint approvals (redeem, settlement, transferable) from using \\\`overridesFromOutgoingApprovals\\\` or \\\`overridesToIncomingApprovals\\\`. Non-mint approvals rely on \\\`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\\\` for outgoing-side auth and on the burn destination for incoming-side auth
 - All permissions frozen after creation
 - 7 approvals: paired mint, freely transferable, pre-settlement redeem, yes-wins, no-wins, push-yes, push-no
 - Alias paths for YES (token 1) and NO (token 2) with 6 decimals
@@ -2842,6 +2842,7 @@ For bounties that require the verifier or submitter to hold a token from THIS co
 - maxScalingMultiplier: MAX_UINT for unrestricted scaling
 - Deposit coinTransfer.to = "Mint" (auto-resolves to escrow)
 - requireToEqualsInitiatedBy: true on deposit-refund (contributor receives their own refund token)
+- invariants: \\\`noForcefulPostMintTransfers: true\\\` — the refund approval (non-mint) MUST NOT set \\\`overridesFromOutgoingApprovals\\\` or \\\`overridesToIncomingApprovals\\\` (both must be false or omitted). It relies on \\\`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\\\` for the outgoing side and on the burn destination for the incoming side. The deposit-refund / deposit-progress / success approvals ARE Mint-side and keep \\\`overridesFromOutgoingApprovals: true\\\` as the chain requires, with \\\`overridesToIncomingApprovals: false\\\`
 - All permissions frozen after creation
 - DON'T use votingChallenges — goal tracking is via mustOwnTokens, not voting
 - DON'T forget allowAmountScaling on ALL 4 approvals
@@ -3070,10 +3071,14 @@ On-chain crowdfunding with automatic goal tracking. Contributors deposit coins a
 - initiatedByListId on mint-to-winner = seller address (only seller can accept)
 - maxNumTransfers = 1 on all approvals (one-shot)
 - overridesToIncomingApprovals: false on mint-to-winner (bidder's incoming approval handles payment)
+- Burn approval has NO override flags — relies on defaultBalances autoApproveSelfInitiatedOutgoingTransfers + burn destination
+- noForcefulPostMintTransfers: true in invariants (permanently locks out forceful transfers post-mint)
+- After settlement, the mint-to-winner approval is auto-deleted via afterOneUse — protocol validators treat a missing mint-to-winner as a valid post-settlement state, not an error
 - All permissions frozen after creation
 - DON'T use coinTransfers on collection approvals — payment happens via intent matching
 - DON'T set initiatedByListId to "All" on mint-to-winner — must be seller
 - DON'T set transferTimes to forever — must be bounded to accept window
+- DON'T put override flags on the burn approval — auction has noForcefulPostMintTransfers: true, so non-mint override flags would be invariant violations
 - DO use autoDeletionOptions.afterOneUse: true on mint-to-winner`,
     instructions: `## Auction Configuration
 
@@ -3086,7 +3091,8 @@ A single-item auction where the seller creates a collection, bidders place inten
 - Token ID 1 = The auctioned item
 - Standard: "Auction"
 - validTokenIds: [{ start: "1", end: "1" }]
-- invariants: { noCustomOwnershipTimes: true }
+- invariants: \\\`{ noCustomOwnershipTimes: true, maxSupplyPerId: "0", noForcefulPostMintTransfers: true, disablePoolCreation: true }\\\`
+- \\\`noForcefulPostMintTransfers: true\\\` locks the collection so no non-mint approval can ever use \\\`overridesFromOutgoingApprovals\\\` or \\\`overridesToIncomingApprovals\\\` — the burn approval below relies on \\\`defaultBalances\\\` auto-approve flags instead
 - All permissions frozen after creation
 
 ### Bidding Mechanism
@@ -3134,17 +3140,12 @@ Bids must have transferTimes that stay valid through the END of the accept windo
   "toListId": "<BURN_ADDRESS>",
   "initiatedByListId": "All",
   "tokenIds": [{ "start": "1", "end": "1" }],
-  "transferTimes": [{ "start": "1", "end": "18446744073709551615" }],
-  "approvalCriteria": {
-    "overridesFromOutgoingApprovals": true,
-    "overridesToIncomingApprovals": true,
-    "coinTransfers": [],
-    "maxNumTransfers": { "overallMaxNumTransfers": "1" },
-    "autoDeletionOptions": { "afterOneUse": true, "afterOverallMaxNumTransfers": true }
-  }
+  "transferTimes": [{ "start": "1", "end": "18446744073709551615" }]
 }
 \\\`\\\`\\\`
 
+> **No \\\`approvalCriteria\\\` overrides:** because the invariants lock \\\`noForcefulPostMintTransfers: true\\\`, the burn approval MUST NOT set \\\`overridesFromOutgoingApprovals\\\` or \\\`overridesToIncomingApprovals\\\`. It relies on \\\`defaultBalances.autoApproveSelfInitiatedOutgoingTransfers: true\\\` for the outgoing side and on the burn destination for the incoming side.
+
 ### Auction Flow
 
 1. **Create**: Seller creates auction collection with 2 approvals. No token is minted yet.
@@ -3156,7 +3157,7 @@ Bids must have transferTimes that stay valid through the END of the accept windo
 
 1. \\\`set_valid_token_ids\\\` — set [{ start: "1", end: "1" }]
 2. \\\`set_standards\\\` — set ["Auction"]
-3. \\\`set_invariants\\\` — set { noCustomOwnershipTimes: true }
+3. \\\`set_invariants\\\` — set \\\`{ noCustomOwnershipTimes: true, maxSupplyPerId: "0", noForcefulPostMintTransfers: true, disablePoolCreation: true }\\\`
 4. \\\`add_approval\\\` x2 — mint-to-winner, burn
 5. \\\`set_collection_metadata\\\` — auction title, description, image
 6. \\\`set_token_metadata\\\` — token 1 metadata (the item being auctioned)
@@ -3170,6 +3171,8 @@ Bids must have transferTimes that stay valid through the END of the accept windo
 - DON'T set initiatedByListId to "All" on mint-to-winner — only the seller can accept bids
 - DON'T set transferTimes to forever — MUST be bounded to accept window (bidDeadline → bidDeadline + acceptWindow)
 - DON'T set overridesToIncomingApprovals to true on mint-to-winner — must be false so the bidder's incoming approval (payment intent) is checked
+- DON'T add override flags to the burn approval — the invariant \\\`noForcefulPostMintTransfers: true\\\` rejects \\\`overridesFromOutgoingApprovals\\\` or \\\`overridesToIncomingApprovals\\\` on any non-mint approval
+- DON'T worry if the mint-to-winner approval is absent after settlement — \\\`autoDeletionOptions.afterOneUse: true\\\` removes it after the first successful mint, and the protocol validator accepts that as a valid post-settlement state
 - DON'T create a separate mint-to-seller approval — the token should not exist until the seller accepts a bid
 - DON'T forget autoDeletionOptions on mint-to-winner — without afterOneUse: true, the seller could mint to multiple bidders
 - DON'T forget that bids must have transferTimes valid through the END of the accept window, not just the bid deadline`
@@ -3186,7 +3189,7 @@ Bids must have transferTimes that stay valid through the END of the accept windo
 - Each purchase approval: fromListId="Mint", toListId="All" (or burn address if burn-on-purchase), 1 coinTransfer paying the store address
 - Payment goes directly to store address (NOT to escrow) — overrideFromWithApproverAddress: false
 - Each product has independent price, supply limit (maxNumTransfers), and burn-on-purchase toggle
-- predeterminedBalances.startBalances: 1x of that product's token ID
+- predeterminedBalances.incrementedBalances.startBalances: 1x of that product's token ID
 - Optional burn approval: !Mint → burn address, no coinTransfers
 - invariants: { noCustomOwnershipTimes: true }
 - All permissions frozen after creation
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/tokenRegistry.ts b/packages/bitbadgesjs-sdk/src/builder/resources/tokenRegistry.ts
index ff3a79b415..3802c43ad9 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/tokenRegistry.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/tokenRegistry.ts
@@ -64,7 +64,7 @@ export function formatTokenRegistryForDisplay(): string {
   output += '| Symbol | IBC Denom | Decimals | Backing Address |\n';
   output += '|--------|-----------|----------|------------------|\n';
   for (const token of content.tokens) {
-    output += `| ${token.symbol} | ${token.ibcDenom.slice(0, 20)}... | ${token.decimals} | ${token.backingAddress.slice(0, 15)}... |\n`;
+    output += `| ${token.symbol} | ${token.ibcDenom} | ${token.decimals} | ${token.backingAddress} |\n`;
   }
 
   output += '\n## Native Coins\n\n';
diff --git a/packages/bitbadgesjs-sdk/src/builder/resources/workflows.ts b/packages/bitbadgesjs-sdk/src/builder/resources/workflows.ts
index 05f8b23657..1191758b0b 100644
--- a/packages/bitbadgesjs-sdk/src/builder/resources/workflows.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/resources/workflows.ts
@@ -13,7 +13,7 @@ export const workflowsResourceInfo = {
 const WORKFLOWS_CONTENT = {
   overview: `# BitBadges Workflow Chains
 
-Multi-step tool sequences for common operations. Each workflow lists the exact MCP tools to call in order.`,
+Multi-step tool sequences for common operations. Each workflow lists the exact builder tools to call in order.`,
 
   bb402Acquire: `## BB-402: Acquire Tokens to Gain Access
 
@@ -213,8 +213,8 @@ Step 1: Build the collection
   → Use per-field tools: set_standards, set_valid_token_ids, set_invariants, add_approval, set_permissions, set_default_balances, set_collection_metadata, set_token_metadata, add_alias_path, set_mint_escrow_coins
   → Use get_transaction to retrieve the built transaction
 
-Step 2: Audit
-  → audit_collection(collection: result.transaction, context: "nft art collection")
+Step 2: Review
+  → review_collection(collection: result.transaction, context: "nft art collection")
   → Review all CRITICAL findings — these MUST be fixed
   → Review all WARNING findings — decide if they're intentional
 
@@ -223,8 +223,8 @@ Step 3: Fix critical issues
   → Common fixes: add overridesFromOutgoingApprovals, add supply limits,
     lock permissions, set autoApproveAllIncomingTransfers
 
-Step 4: Re-audit
-  → audit_collection(collection: fixedTransaction)
+Step 4: Re-review
+  → review_collection(collection: fixedTransaction)
   → Verify no more CRITICAL findings
 
 Step 5: Deploy
@@ -232,10 +232,10 @@ Step 5: Deploy
   → Return transaction JSON for user to sign with their wallet and broadcast
 \`\`\`
 
-Can also audit existing on-chain collections:
+Can also review existing on-chain collections:
 \`\`\`
 Step 1: → query_collection(collectionId)
-Step 2: → audit_collection(collection: queryResult, context: "description")
+Step 2: → review_collection(collection: queryResult, context: "description")
 Step 3: → Present findings to user
 \`\`\``
 };
diff --git a/packages/bitbadgesjs-sdk/src/builder/sdk/apiClient.ts b/packages/bitbadgesjs-sdk/src/builder/sdk/apiClient.ts
index 4eb59111f1..101f737073 100644
--- a/packages/bitbadgesjs-sdk/src/builder/sdk/apiClient.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/sdk/apiClient.ts
@@ -16,10 +16,28 @@ export interface ApiResponse<T> {
 }
 
 /**
- * Get the API key from environment variable
+ * Get the API key. Resolution order:
+ *   1. `BITBADGES_API_KEY` environment variable (highest priority — overrides
+ *      everything so CI / one-off shells can swap keys without touching disk).
+ *   2. `~/.bitbadges/config.json` `apiKey` field, populated via
+ *      `bitbadges-cli config set apiKey <key>`. Persistent default for
+ *      day-to-day use.
+ *
+ * Imported lazily so this module stays usable in environments where the
+ * filesystem helper isn't available (e.g. browser bundles via the SDK).
  */
 export function getApiKey(): string | undefined {
-  return process.env.BITBADGES_API_KEY;
+  const envKey = process.env.BITBADGES_API_KEY;
+  if (envKey) return envKey;
+  try {
+    // Lazy require to avoid pulling fs/os into non-Node consumers of the SDK.
+    // The CLI config helper is the source of truth for the on-disk format.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { getConfigApiKey } = require('../../cli/utils/config.js');
+    return getConfigApiKey();
+  } catch {
+    return undefined;
+  }
 }
 
 /**
@@ -179,27 +197,36 @@ export async function getBalanceForToken(
 // Simulation APIs
 // ============================================
 
+/**
+ * Agent-JSON single-tx simulate request. Sent to the indexer's
+ * `/api/v0/simulate` Path 2. The indexer proto-encodes server-side
+ * via `encodeMsgsFromJson` and forwards to the LCD simulate endpoint.
+ *
+ * Previously this type wrapped a single tx in a `{txs: [...]}` "batch"
+ * envelope. The batch wrapper was never actually used as a batch
+ * (always exactly 1 element) and has been removed.
+ */
 export interface SimulateRequest {
-  txs: Array<{
-    context: {
-      address: string;
-      chain: string;
-    };
-    messages: unknown[];
-    memo?: string;
-    fee?: {
-      amount: Array<{ denom: string; amount: string }>;
-      gas: string;
-    };
-  }>;
+  messages: unknown[];
+  memo?: string;
+  fee?: {
+    amount: Array<{ denom: string; amount: string }>;
+    gas: string;
+  };
+  /** bb1… address of the tx signer. Optional if every message already
+   * has the same `value.creator`. */
+  creatorAddress?: string;
 }
 
+/**
+ * Raw LCD simulate response — what the indexer forwards back from
+ * `/cosmos/tx/v1beta1/simulate`. Consumers typically read
+ * `gas_info.gas_used` + `result.events`.
+ */
 export interface SimulateResponse {
-  results: Array<{
-    gasUsed?: string;
-    events?: unknown[];
-    error?: string;
-  }>;
+  gas_info?: { gas_used?: string; gas_wanted?: string };
+  result?: { events?: unknown[] };
+  error?: string;
 }
 
 export async function simulateTx(
diff --git a/packages/bitbadgesjs-sdk/src/builder/server.ts b/packages/bitbadgesjs-sdk/src/builder/server.ts
index f390526d57..60674ba8ae 100644
--- a/packages/bitbadgesjs-sdk/src/builder/server.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/server.ts
@@ -1,9 +1,12 @@
 /**
- * BitBadges Builder MCP Server Configuration
+ * BitBadges Builder — Model Context Protocol (MCP) stdio transport.
  *
- * Tool handlers live in `src/tools/registry.ts` — this file is just the MCP
- * protocol shim. ListTools and CallTool both read from the same registry, so
- * the CLI and any other library consumers see exactly the same tool surface.
+ * Wraps the builder tool/resource registry in the MCP protocol so Claude
+ * Desktop and other MCP clients can reach it over stdio. Tool handlers
+ * themselves live in `src/builder/tools/registry.ts` and are used unchanged
+ * by the in-process CLI path (`bitbadges-cli builder`) and by library
+ * consumers (indexer, chain binary delegation, etc.) — the MCP server is
+ * just one presentation layer among several.
  */
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
@@ -18,12 +21,12 @@ import { toolRegistry, listTools, callTool } from './tools/registry.js';
 import { listResources, readResource } from './resources/registry.js';
 
 /**
- * Create and configure the MCP server.
+ * Create and configure the BitBadges Builder MCP stdio server.
  */
 export function createServer(): Server {
   const server = new Server(
     {
-      name: 'bitbadges-builder-mcp',
+      name: 'bitbadges-builder',
       version: '1.0.0'
     },
     {
@@ -40,7 +43,8 @@ export function createServer(): Server {
   }));
 
   // CallTool — dispatch through the registry. The registry never throws, so
-  // we just wrap its output in the MCP content-block shape.
+  // we just wrap its output in the MCP content-block shape expected by the
+  // wire protocol.
   server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     const { text, isError } = await callTool(name, args);
diff --git a/packages/bitbadgesjs-sdk/src/builder/session/fileStore.ts b/packages/bitbadgesjs-sdk/src/builder/session/fileStore.ts
new file mode 100644
index 0000000000..da70467b95
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/builder/session/fileStore.ts
@@ -0,0 +1,93 @@
+/**
+ * File-backed session persistence.
+ *
+ * The in-memory session store (`sessionState.ts`) is ephemeral — it lives for
+ * the lifetime of one process. CLI consumers run many one-shot processes, one
+ * per tool call, and need session state to survive across them. These helpers
+ * bridge the two: snapshot the in-memory session to `~/.bitbadges/sessions/<id>.json`
+ * after each call, restore it from disk before the next.
+ *
+ * All functions default to `DEFAULT_SESSIONS_DIR` but accept an override so
+ * agents can isolate sessions per workspace, tests can point at a tmpdir, and
+ * no caller has to hardcode the path.
+ *
+ * These helpers never throw for "no session found" — missing files are a
+ * normal condition (first call on a fresh id). They do throw on corrupt JSON
+ * and I/O failures, since those are real problems a caller should see.
+ */
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { exportSession, importSession } from './sessionState.js';
+
+/** Default on-disk location for persisted session snapshots. */
+export const DEFAULT_SESSIONS_DIR = path.join(os.homedir(), '.bitbadges', 'sessions');
+
+/** Resolve the JSON file path for a session id under the given directory. */
+export function sessionFilePath(id: string, dir: string = DEFAULT_SESSIONS_DIR): string {
+  return path.join(dir, `${id}.json`);
+}
+
+/**
+ * Load a persisted session snapshot from disk into the in-memory store.
+ *
+ * If no file exists at the expected path, this is a no-op — the caller will
+ * fall through to `getOrCreateSession` which initializes a blank template on
+ * first mutation. Throws on corrupt JSON or read failures so the caller can
+ * surface the error.
+ */
+export function loadSessionFromDisk(id: string, dir: string = DEFAULT_SESSIONS_DIR): void {
+  const file = sessionFilePath(id, dir);
+  if (!fs.existsSync(file)) return;
+  let snapshot: any;
+  try {
+    snapshot = JSON.parse(fs.readFileSync(file, 'utf-8'));
+  } catch (err) {
+    throw new Error(`Failed to load session "${id}" from ${file}: ${(err as Error).message}`);
+  }
+  importSession(id, snapshot);
+}
+
+/**
+ * Snapshot the in-memory session for the given id and write it to disk.
+ *
+ * No-op if the session doesn't exist in memory — a tool call that never
+ * touched session state shouldn't create an empty file on disk. Creates the
+ * target directory if it doesn't exist yet.
+ */
+export function saveSessionToDisk(id: string, dir: string = DEFAULT_SESSIONS_DIR): void {
+  const snapshot = exportSession(id);
+  if (snapshot === null) return;
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(sessionFilePath(id, dir), JSON.stringify(snapshot, null, 2));
+}
+
+/** List persisted session ids under the given directory. Empty array if dir doesn't exist. */
+export function listSessionFilesOnDisk(dir: string = DEFAULT_SESSIONS_DIR): string[] {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((file) => file.endsWith('.json'))
+    .map((file) => file.replace(/\.json$/, ''));
+}
+
+/**
+ * Read the raw JSON body of a persisted session snapshot, or null if not
+ * present. Returns the string as-is so callers can either pretty-print or
+ * re-parse.
+ */
+export function readSessionFileRaw(id: string, dir: string = DEFAULT_SESSIONS_DIR): string | null {
+  const file = sessionFilePath(id, dir);
+  if (!fs.existsSync(file)) return null;
+  return fs.readFileSync(file, 'utf-8');
+}
+
+/** Delete the persisted session file for the given id. No-op if absent. */
+export function resetSessionFile(id: string, dir: string = DEFAULT_SESSIONS_DIR): void {
+  const file = sessionFilePath(id, dir);
+  if (fs.existsSync(file)) {
+    fs.unlinkSync(file);
+  }
+}
diff --git a/packages/bitbadgesjs-sdk/src/builder/session/index.ts b/packages/bitbadgesjs-sdk/src/builder/session/index.ts
index 2ae81d7ea1..24c65a1017 100644
--- a/packages/bitbadgesjs-sdk/src/builder/session/index.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/session/index.ts
@@ -1 +1,2 @@
 export * from './sessionState.js';
+export * from './fileStore.js';
diff --git a/packages/bitbadgesjs-sdk/src/builder/session/sessionState.ts b/packages/bitbadgesjs-sdk/src/builder/session/sessionState.ts
index 969bbd4c19..0ff34c562e 100644
--- a/packages/bitbadgesjs-sdk/src/builder/session/sessionState.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/session/sessionState.ts
@@ -1,9 +1,9 @@
 /**
- * In-memory session state for the MCP builder v2.
+ * In-memory session state for the builder v2.
  *
  * Uses a Map keyed by sessionId for per-request isolation.
  * Each session holds a blank MsgUniversalUpdateCollection template that per-field tools mutate.
- * Auto-creates on first mutation. State is ephemeral — scoped to the MCP process lifetime.
+ * Auto-creates on first mutation. State is ephemeral — scoped to the process lifetime.
  *
  * Design principles:
  * - Set tools replace the entire field
@@ -33,15 +33,31 @@ export interface SessionTransaction {
     typeUrl: string;
     value: Record<string, any>;
   }>;
-  metadataPlaceholders: Record<string, { name: string; description: string; image: string }>;
   /** Approval IDs that existed when the session was initialized (for update flows) */
   originalApprovalIds?: Set<string>;
 }
 
+/**
+ * Get or create the per-msg metadataPlaceholders sidecar on the first
+ * message's value. Canonical location: `session.messages[0].value._meta.metadataPlaceholders`.
+ * There is no session-level top-level sidecar — the sidecar belongs to
+ * the msg whose body references the placeholder URIs.
+ */
+export function getMsgPlaceholders(session: SessionTransaction): Record<string, { name: string; description: string; image: string }> {
+  const value = session.messages[0].value;
+  if (!value._meta || typeof value._meta !== 'object') {
+    value._meta = {};
+  }
+  if (!value._meta.metadataPlaceholders || typeof value._meta.metadataPlaceholders !== 'object') {
+    value._meta.metadataPlaceholders = {};
+  }
+  return value._meta.metadataPlaceholders;
+}
+
 // Per-session state keyed by sessionId
 const sessions = new Map<string, SessionTransaction>();
 
-// Default sessionId when none is provided (MCP-direct / single-user mode)
+// Default sessionId when none is provided (builder-direct / single-user mode)
 const DEFAULT_SESSION_ID = '__default__';
 
 function resolveSessionId(sessionId?: string): string {
@@ -100,8 +116,7 @@ export function getOrCreateSession(sessionId?: string, creatorAddress?: string):
           aliasPathsToAdd: [],
           cosmosCoinWrapperPathsToAdd: []
         }
-      }],
-      metadataPlaceholders: {}
+      }]
     };
     sessions.set(sid, session);
   }
@@ -141,7 +156,6 @@ export function exportSession(sessionId?: string): any | null {
   if (!session) return null;
   return {
     messages: session.messages,
-    metadataPlaceholders: session.metadataPlaceholders,
     originalApprovalIds: session.originalApprovalIds ? Array.from(session.originalApprovalIds) : undefined
   };
 }
@@ -159,7 +173,6 @@ export function importSession(sessionId: string | undefined, snapshot: any): voi
   }
   const restored: SessionTransaction = {
     messages: snapshot.messages,
-    metadataPlaceholders: snapshot.metadataPlaceholders || {},
     originalApprovalIds: Array.isArray(snapshot.originalApprovalIds)
       ? new Set<string>(snapshot.originalApprovalIds)
       : undefined
@@ -248,7 +261,7 @@ export function setCollectionMetadata(sessionId: string | undefined, name: strin
   const uri = 'ipfs://METADATA_COLLECTION';
   value.collectionMetadata = { uri, customData: '' };
   value.updateCollectionMetadata = true;
-  s.metadataPlaceholders[uri] = { name, description, image: sanitizeImage(image) };
+  getMsgPlaceholders(s)[uri] = { name, description, image: sanitizeImage(image) };
 }
 
 export function setTokenMetadata(
@@ -277,7 +290,7 @@ export function setTokenMetadata(
     value.tokenMetadata = [...(value.tokenMetadata || []), entry];
   }
   value.updateTokenMetadata = true;
-  s.metadataPlaceholders[uriKey] = { name, description, image: sanitizeImage(image) };
+  getMsgPlaceholders(s)[uriKey] = { name, description, image: sanitizeImage(image) };
 }
 
 // ============================================================
@@ -306,9 +319,10 @@ export function addApproval(sessionId: string | undefined, approval: Record<stri
   approvals[idx].uri = approvals[idx].uri || uri;
   approvals[idx].customData = approvals[idx].customData || '';
   approvals[idx].version = approvals[idx].version || '0';
-  if (!s.metadataPlaceholders[uri]) {
+  const placeholders = getMsgPlaceholders(s);
+  if (!placeholders[uri]) {
     const approvalTitle = (approvalId as string).replace(/-/g, ' ').replace(/\b\w/g, (c: string) => c.toUpperCase());
-    s.metadataPlaceholders[uri] = { name: approvalTitle, description: '', image: '' };
+    placeholders[uri] = { name: approvalTitle, description: '', image: '' };
   }
 }
 
@@ -327,7 +341,7 @@ export function removeApproval(sessionId: string | undefined, approvalId: string
 export function setApprovalMetadata(sessionId: string | undefined, approvalId: string, name: string, description: string, image: string = ''): void {
   const s = getOrCreateSession(sessionId);
   const uri = `ipfs://METADATA_APPROVAL_${approvalId}`;
-  s.metadataPlaceholders[uri] = { name, description, image };
+  getMsgPlaceholders(s)[uri] = { name, description, image };
 
   const value = s.messages[0].value;
   const approvals: any[] = value.collectionApprovals || [];
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/builders/auditCollection.ts b/packages/bitbadgesjs-sdk/src/builder/tools/builders/auditCollection.ts
deleted file mode 100644
index caba0a440c..0000000000
--- a/packages/bitbadgesjs-sdk/src/builder/tools/builders/auditCollection.ts
+++ /dev/null
@@ -1,32 +0,0 @@
-/**
- * Tool: audit_collection
- * Audits a MsgUniversalUpdateCollection for security risks, design flaws, and common gotchas.
- * Returns categorized findings with severity levels.
- *
- * Logic delegated to bitbadgesjs-sdk's auditCollection().
- */
-
-import { auditCollection, type AuditResult } from '../../../core/audit.js';
-
-export const auditCollectionTool = {
-  name: 'audit_collection',
-  description: 'Audit a collection transaction or on-chain collection for security risks, design flaws, and common gotchas. Pass either a MsgUniversalUpdateCollection message or a raw collection object. Returns categorized findings with severity levels (critical/warning/info).',
-  inputSchema: {
-    type: 'object' as const,
-    properties: {
-      collection: {
-        type: 'object',
-        description: 'The collection to audit. Can be: (1) A MsgUniversalUpdateCollection message object with typeUrl and value, (2) The value field directly, or (3) A raw collection object from query_collection.'
-      },
-      context: {
-        type: 'string',
-        description: 'Optional context about the intended use case (e.g., "NFT art collection", "stablecoin vault", "subscription token"). Helps tailor findings.'
-      }
-    },
-    required: ['collection']
-  }
-};
-
-export function handleAuditCollection(input: { collection: Record<string, unknown>; context?: string }): AuditResult {
-  return auditCollection(input);
-}
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/builders/buildClaim.ts b/packages/bitbadgesjs-sdk/src/builder/tools/builders/buildClaim.ts
index 512b7ff611..6f958cd0ba 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/builders/buildClaim.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/builders/buildClaim.ts
@@ -209,14 +209,17 @@ export function handleBuildClaim(input: BuildClaimInput): BuildClaimResult {
     claims: [claim]
   };
 
-  // Build helpful nextSteps
+  // Build helpful nextSteps. The submit URL respects BITBADGES_API_URL so
+  // agents pointed at testnet / local indexers see the correct endpoint
+  // in the rendered instructions instead of a hardcoded mainnet URL.
+  const apiUrl = process.env.BITBADGES_API_URL || 'https://api.bitbadges.io';
   const nextStepsParts: string[] = [];
 
   nextStepsParts.push(
     '## How to submit this claim\n' +
       'Send a POST request to the BitBadges API:\n' +
       '```\n' +
-      'POST https://api.bitbadges.io/api/v0/claims\n' +
+      `POST ${apiUrl}/api/v0/claims\n` +
       'Authorization: Bearer <YOUR_API_KEY>\n' +
       'Content-Type: application/json\n' +
       'Body: <the apiPayload object from this response>\n' +
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/builders/explainCollection.ts b/packages/bitbadgesjs-sdk/src/builder/tools/builders/explainCollection.ts
index a8f6255168..c7958b58c7 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/builders/explainCollection.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/builders/explainCollection.ts
@@ -5,7 +5,7 @@
  * No API key required — purely local analysis.
  *
  * Uses interpretCollection() from bitbadgesjs-sdk as the core explanation engine,
- * with MCP-specific input normalization and developer/auditor extras on top.
+ * with builder-specific input normalization and developer/auditor extras on top.
  */
 
 import { interpretCollection } from '../../../core/interpret.js';
@@ -57,7 +57,7 @@ interface ApprovalData {
 }
 
 /**
- * Unwraps the raw MCP input into a flat collection-like object.
+ * Unwraps the raw tool input into a flat collection-like object.
  * Handles build results, MsgUniversalUpdateCollection, on-chain query results, etc.
  */
 function normalizeInput(input: Record<string, unknown>): Record<string, unknown> {
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/builders/index.ts b/packages/bitbadgesjs-sdk/src/builder/tools/builders/index.ts
index 6a96c3dfe0..8cd1c849f0 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/builders/index.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/builders/index.ts
@@ -2,7 +2,6 @@
  * High-level builders index
  */
 
-export * from './auditCollection.js';
-export * from './verifyStandards.js';
 export * from './explainCollection.js';
 export * from './buildClaim.js';
+export * from './reviewCollection.js';
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/builders/reviewCollection.ts b/packages/bitbadgesjs-sdk/src/builder/tools/builders/reviewCollection.ts
new file mode 100644
index 0000000000..b8139442e3
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/builders/reviewCollection.ts
@@ -0,0 +1,39 @@
+/**
+ * Tool: review_collection
+ * Unified deterministic review — combines audit + standards + UX checks
+ * into a single ReviewResult. This is the only review entry point
+ * exposed by the builder tool surface.
+ *
+ * Logic delegated to bitbadgesjs-sdk's reviewCollection().
+ */
+
+import { reviewCollection, type ReviewResult, type ReviewContext } from '../../../core/review.js';
+
+export const reviewCollectionTool = {
+  name: 'review_collection',
+  description:
+    'Run the unified deterministic review on a collection transaction or on-chain collection. Returns audit + standards + UX findings merged into one ReviewResult with a single verdict. Every finding has a stable `code`, `severity`, `source`, `category`, plus three required localized strings: `title`, `detail`, `recommendation` (each shaped { en, ... }). Accepts an optional context (onChainCollection, skipSources, hideAgentOnly).',
+  inputSchema: {
+    type: 'object' as const,
+    properties: {
+      collection: {
+        type: 'object',
+        description:
+          'The collection to review. Accepts a MsgUniversalUpdateCollection message, its value field, a transaction { messages: [...] }, or a raw on-chain collection object.'
+      },
+      context: {
+        type: 'object',
+        description:
+          'Optional review context. Fields: onChainCollection (object, prior on-chain state used by diff checks and update-only suppressions), skipSources (array of "audit" | "standards" | "ux" to skip whole families), hideAgentOnly (boolean, drops findings tagged agentOnly — human consumers set this).'
+      }
+    },
+    required: ['collection']
+  }
+};
+
+export function handleReviewCollection(input: {
+  collection: Record<string, unknown>;
+  context?: ReviewContext;
+}): ReviewResult {
+  return reviewCollection(input.collection, input.context);
+}
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/builders/verifyStandards.ts b/packages/bitbadgesjs-sdk/src/builder/tools/builders/verifyStandards.ts
deleted file mode 100644
index bbf64aa84b..0000000000
--- a/packages/bitbadgesjs-sdk/src/builder/tools/builders/verifyStandards.ts
+++ /dev/null
@@ -1,16 +0,0 @@
-/**
- * Deterministic skill/standard verification.
- *
- * Logic delegated to bitbadgesjs-sdk's verifyStandardsCompliance() and
- * formatVerificationResult().
- *
- * This file re-exports those functions so the rest of the MCP codebase
- * (server.ts, builders/index.ts) can continue importing from this path.
- */
-
-export {
-  verifyStandardsCompliance,
-  formatVerificationResult,
-  type VerificationResult,
-  type StandardViolation
-} from '../../../core/verify-standards.js';
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/queries/simulateTransaction.ts b/packages/bitbadgesjs-sdk/src/builder/tools/queries/simulateTransaction.ts
index 2539ddef1c..78e832cb04 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/queries/simulateTransaction.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/queries/simulateTransaction.ts
@@ -64,6 +64,89 @@ function bigintToString(obj: unknown): unknown {
   return obj;
 }
 
+/**
+ * Reusable simulate helper used by both the MCP tool wrapper above and the
+ * CLI's `builder simulate` / templates auto-simulate paths. Sends the
+ * agent-JSON single-tx shape (`{messages, memo, fee, creatorAddress}`)
+ * to the indexer's `/api/v0/simulate` endpoint and normalizes the raw
+ * LCD response into a `SimulateTransactionResult` so all callers render
+ * identically through the terminal helpers.
+ */
+export async function simulateMessages(params: {
+  messages: unknown[];
+  memo?: string;
+  fee?: {
+    amount: Array<{ denom: string; amount: string }>;
+    gas: string;
+  };
+  creatorAddress?: string;
+  /** Override the resolved API key (e.g. CLI `--network local` flow). */
+  apiKey?: string;
+  /** Override the resolved API base URL (e.g. CLI `--url http://...`). */
+  apiUrl?: string;
+}): Promise<SimulateTransactionResult> {
+  try {
+    if (!params.messages || !Array.isArray(params.messages) || params.messages.length === 0) {
+      return { success: false, error: 'Invalid transaction: empty or missing messages array' };
+    }
+
+    const response = await simulateTx(
+      {
+        messages: params.messages,
+        memo: params.memo || '',
+        fee: params.fee || { amount: [{ denom: 'ubadge', amount: '5000' }], gas: '500000' },
+        creatorAddress: params.creatorAddress
+      },
+      // Pass per-call override config through to apiRequest so the
+      // CLI's --network/--url flags can hit a local indexer without
+      // requiring environment variables.
+      params.apiKey || params.apiUrl ? { apiKey: params.apiKey, apiUrl: params.apiUrl } : undefined
+    );
+
+    if (!response.success) {
+      return { success: false, error: response.error };
+    }
+
+    // Path 2 response is the raw LCD simulate shape:
+    //   { gas_info: { gas_used, gas_wanted }, result: { events: [...] } }
+    // On a chain-level rejection the indexer surfaces the message as
+    // response.data.error (via BitBadgesError passthrough) or as an
+    // error field on data itself.
+    const data: any = response.data;
+    const chainError = data?.error || data?.message;
+    if (chainError && !data?.gas_info && !data?.result) {
+      return { success: true, valid: false, simulationError: chainError };
+    }
+
+    const gasUsed: string | undefined = data?.gas_info?.gas_used;
+    const events = ((data?.result?.events || []) as SimulationEvent[]);
+    let parsedEvents: unknown = undefined;
+    let netChanges: unknown = undefined;
+    try {
+      const parsed: ParsedSimulationEvents = parseSimulationEvents(events, []);
+      const net: NetBalanceChanges = calculateNetChanges(parsed);
+      parsedEvents = bigintToString(parsed);
+      netChanges = bigintToString(net);
+    } catch {
+      // If parsing fails, still return raw events — don't break the caller
+    }
+
+    return {
+      success: true,
+      valid: true,
+      gasUsed,
+      events,
+      parsedEvents,
+      netChanges
+    };
+  } catch (error) {
+    return {
+      success: false,
+      error: 'Failed to simulate transaction: ' + (error instanceof Error ? error.message : String(error))
+    };
+  }
+}
+
 export async function handleSimulateTransaction(input: SimulateTransactionInput): Promise<SimulateTransactionResult> {
   try {
     // Normalize: accept either a pre-parsed object or a JSON string
@@ -90,71 +173,11 @@ export async function handleSimulateTransaction(input: SimulateTransactionInput)
       };
     }
 
-    // Validate basic structure
-    if (!tx.messages || !Array.isArray(tx.messages)) {
-      return {
-        success: false,
-        error: 'Invalid transaction: Missing "messages" array'
-      };
-    }
-
-    // Create simulation request
-    const response = await simulateTx({
-      txs: [{
-        context: {
-          address: 'bb1simulation',
-          chain: 'eth'
-        },
-        messages: tx.messages,
-        memo: tx.memo || '',
-        fee: tx.fee || {
-          amount: [{ denom: 'ubadge', amount: '5000' }],
-          gas: '500000'
-        }
-      }]
+    return simulateMessages({
+      messages: tx.messages,
+      memo: tx.memo,
+      fee: tx.fee
     });
-
-    if (!response.success) {
-      return {
-        success: false,
-        error: response.error
-      };
-    }
-
-    const result = response.data?.results?.[0];
-
-    if (result?.error) {
-      return {
-        success: true,
-        valid: false,
-        simulationError: result.error
-      };
-    }
-
-    // Parse events into structured output
-    const events = (result?.events || []) as SimulationEvent[];
-    let parsedEvents: unknown = undefined;
-    let netChanges: unknown = undefined;
-
-    try {
-      const parsed: ParsedSimulationEvents = parseSimulationEvents(events, []);
-      const net: NetBalanceChanges = calculateNetChanges(parsed);
-
-      // Convert bigint to string for JSON serialization
-      parsedEvents = bigintToString(parsed);
-      netChanges = bigintToString(net);
-    } catch {
-      // If parsing fails, still return raw events — don't break the tool
-    }
-
-    return {
-      success: true,
-      valid: true,
-      gasUsed: result?.gasUsed,
-      events: result?.events,
-      parsedEvents,
-      netChanges
-    };
   } catch (error) {
     return {
       success: false,
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/registry.spec.ts b/packages/bitbadgesjs-sdk/src/builder/tools/registry.spec.ts
new file mode 100644
index 0000000000..8a953c000d
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/registry.spec.ts
@@ -0,0 +1,111 @@
+/**
+ * Tests for the centralized tool dispatch in `callTool` — specifically the
+ * pre-flight argument validator and the Zod-error formatter that round 4
+ * added to catch LLM-agent footguns:
+ *
+ *   - missing required field → handler crashes with "Cannot read properties
+ *     of undefined" instead of "Missing required field 'X'"
+ *   - typo'd arg key → handler silently treats as missing, agent thinks
+ *     the call succeeded but state never got set
+ *   - Zod errors → raw JSON dump that's hard for both humans and LLMs to
+ *     parse
+ *
+ * The validator is generic — it walks the tool's JSON Schema `inputSchema`
+ * and uses `required` + `additionalProperties: false`. Tests below exercise
+ * a representative sample of real registered tools rather than mocks, so
+ * any wiring drift surfaces here.
+ */
+
+import { callTool, toolRegistry } from './registry.js';
+
+describe('callTool — pre-flight arg validation', () => {
+  describe('missing required field', () => {
+    it('generate_unique_id with no prefix → friendly error, not "undefined_xxx"', async () => {
+      const res = await callTool('generate_unique_id', {});
+      expect(res.isError).toBe(true);
+      expect(res.text).toMatch(/Missing required field/);
+      expect(res.text).toMatch(/prefix/);
+      expect(res.result).toBeNull();
+    });
+
+    it('generate_unique_id with empty-string prefix → rejected (not "undefined_xxx")', async () => {
+      const res = await callTool('generate_unique_id', { prefix: '' });
+      expect(res.isError).toBe(true);
+      expect(res.text).toMatch(/Missing required field/);
+    });
+
+    it('query_balance with no args → friendly error listing both required fields', async () => {
+      const res = await callTool('query_balance', {});
+      expect(res.isError).toBe(true);
+      expect(res.text).toMatch(/Missing required fields?/);
+      expect(res.text).toMatch(/collectionId/);
+      expect(res.text).toMatch(/address/);
+    });
+
+    it('query_balance with one of two required → flags the missing one in the "Missing:" line', async () => {
+      const res = await callTool('query_balance', { collectionId: '42' });
+      expect(res.isError).toBe(true);
+      // The error message has two parts: "Missing required field: address."
+      // and "Expected: collectionId, address" (full required list). Check
+      // that `address` shows up in the missing list.
+      expect(res.text).toMatch(/Missing required field: address/);
+    });
+
+    it('set_valid_token_ids with sessionId only → flags missing tokenIds', async () => {
+      const res = await callTool('set_valid_token_ids', { sessionId: 'spec-test' });
+      expect(res.isError).toBe(true);
+      expect(res.text).toMatch(/tokenIds/);
+    });
+
+    it('set_valid_token_ids with truly-wrong key → catches via missing-required path', async () => {
+      // LLM agents typo arg names; the validator should refuse the call
+      // before the handler crashes / silently succeeds.
+      const res = await callTool('set_valid_token_ids', {
+        sessionId: 'spec-test',
+        badgeIds: [{ start: '1', end: '10' }] // wrong key
+      });
+      expect(res.isError).toBe(true);
+      expect(res.text).toMatch(/tokenIds/);
+    });
+  });
+
+  describe('unknown tool', () => {
+    it('returns isError without crashing', async () => {
+      const res = await callTool('totally_fake_tool_xxx', { foo: 'bar' });
+      expect(res.isError).toBe(true);
+      expect(res.text).toMatch(/Unknown tool/);
+      expect(res.result).toBeNull();
+    });
+  });
+
+  describe('happy path', () => {
+    it('get_current_timestamp with no args → succeeds (no required fields)', async () => {
+      const res = await callTool('get_current_timestamp', {});
+      expect(res.isError).toBeFalsy();
+      expect(res.result).not.toBeNull();
+    });
+
+    it('generate_unique_id with valid prefix → succeeds', async () => {
+      const res = await callTool('generate_unique_id', { prefix: 'spec-test' });
+      expect(res.isError).toBeFalsy();
+      expect((res.result as any).success).toBe(true);
+      expect((res.result as any).ids[0]).toMatch(/^spec-test_[a-f0-9]+$/);
+    });
+  });
+
+  describe('coverage sanity', () => {
+    it('all 51+ registered tools have an inputSchema', () => {
+      // If a tool slips into the registry without an inputSchema, the
+      // validator silently passes through and the handler is unguarded.
+      // Catch the regression here.
+      const missing: string[] = [];
+      for (const [name, entry] of Object.entries(toolRegistry)) {
+        const schema = (entry as any).tool?.inputSchema;
+        if (!schema || typeof schema !== 'object') {
+          missing.push(name);
+        }
+      }
+      expect(missing).toEqual([]);
+    });
+  });
+});
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/registry.ts b/packages/bitbadgesjs-sdk/src/builder/tools/registry.ts
index 853be3e894..d2bd780313 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/registry.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/registry.ts
@@ -1,15 +1,15 @@
 /**
  * Central tool registry.
  *
- * Single source of truth for every MCP tool. Used by:
- *  - src/server.ts (MCP stdio server — wraps entries into ListTools/CallTool handlers)
+ * Single source of truth for every builder tool. Used by:
+ *  - src/server.ts (Model Context Protocol (MCP) stdio transport — wraps entries into ListTools/CallTool handlers)
  *  - external consumers (e.g. bitbadges-cli) that import this module and invoke
- *    tools as plain functions, without the MCP protocol.
+ *    tools as plain functions, bypassing the MCP stdio transport.
  *
  * Each entry has a `tool` schema (for discovery) and a `run` function that takes
  * raw args and returns a structured result. An optional `formatText` controls how
- * the result is serialized for the MCP text content block; by default we JSON
- * stringify. The registry itself is protocol-agnostic — it never returns MCP
+ * the result is serialized for the text content block returned over MCP; by default we JSON
+ * stringify. The registry itself is protocol-agnostic — it never returns transport-shaped
  * content blocks directly.
  */
 
@@ -44,13 +44,12 @@ import {
   // Dynamic store
   buildDynamicStoreTool, handleBuildDynamicStore,
   queryDynamicStoreTool, handleQueryDynamicStore,
-  // Audit / explain
-  auditCollectionTool, handleAuditCollection,
+  // Explain
   explainCollectionTool, handleExplainCollection,
+  // Unified review
+  reviewCollectionTool, handleReviewCollection,
   // Claim builder
   buildClaimTool, handleBuildClaim,
-  // Standards compliance
-  verifyStandardsCompliance, formatVerificationResult,
   // Session-based per-field tools (v2)
   setStandardsTool, handleSetStandards,
   setValidTokenIdsTool, handleSetValidTokenIds,
@@ -86,7 +85,7 @@ export { exportSession, importSession } from '../session/sessionState.js';
 
 // Re-export the resource registry so consumers get tools + resources from one
 // import. Resources are static documents (token registry, recipes, skill docs,
-// error patterns, etc.) — the other half of the MCP surface.
+// error patterns, etc.) — the other half of the builder surface.
 export {
   resourceRegistry,
   listResources,
@@ -96,7 +95,7 @@ export {
   type ReadResourceResult
 } from '../resources/registry.js';
 
-/** MCP tool schema shape — kept loose to avoid coupling to a specific SDK version. */
+/** Builder tool schema shape — kept loose to avoid coupling to a specific SDK version. */
 export interface ToolSchema {
   name: string;
   description: string;
@@ -113,7 +112,7 @@ export interface ToolEntry {
   /** Invoke the tool. Receives raw args and returns a structured result. */
   run: (args: any) => Promise<any> | any;
   /**
-   * Optional custom text serializer for MCP content blocks.
+   * Optional custom text serializer for MCP content blocks when used through the stdio transport.
    * Defaults to `JSON.stringify(result, null, 2)`.
    */
   formatText?: (result: any) => string;
@@ -142,21 +141,8 @@ const getSkillInstructionsTool: ToolSchema = {
   }
 };
 
-const verifyStandardsTool: ToolSchema = {
-  name: 'verify_standards',
-  description:
-    'Verify that a collection transaction complies with BitBadges protocol standards (subscription, credit token, smart token, etc.). Returns violations with severity levels. Complements audit_collection which covers security — this covers standards compliance.',
-  inputSchema: {
-    type: 'object',
-    properties: {
-      transaction: { type: 'object', description: 'The transaction object to verify (MsgUniversalUpdateCollection or similar)' },
-      transactionJson: { type: 'string', description: 'The transaction as a JSON string (alternative to transaction object)' }
-    }
-  }
-};
-
 /**
- * The tool registry. Keys are MCP tool names.
+ * The tool registry. Keys are builder tool names.
  */
 export const toolRegistry: Record<string, ToolEntry> = {
   // Utilities
@@ -208,8 +194,10 @@ export const toolRegistry: Record<string, ToolEntry> = {
   build_dynamic_store: entry(buildDynamicStoreTool, handleBuildDynamicStore),
   query_dynamic_store: entry(queryDynamicStoreTool, async (args: any) => await handleQueryDynamicStore(args)),
 
-  // Audit / explain / claim
-  audit_collection: entry(auditCollectionTool, handleAuditCollection),
+  // Unified review (preferred)
+  review_collection: entry(reviewCollectionTool, handleReviewCollection),
+
+  // Explain / claim
   explain_collection: entry(
     explainCollectionTool,
     handleExplainCollection,
@@ -217,21 +205,6 @@ export const toolRegistry: Record<string, ToolEntry> = {
   ),
   build_claim: entry(buildClaimTool, handleBuildClaim),
 
-  // Standards compliance (custom arg handling + formatter)
-  verify_standards: {
-    tool: verifyStandardsTool,
-    run: (args: any) => {
-      let tx = args;
-      if (typeof args?.transactionJson === 'string') {
-        tx = JSON.parse(args.transactionJson);
-      } else if (args?.transaction) {
-        tx = args.transaction;
-      }
-      return verifyStandardsCompliance(tx);
-    },
-    formatText: (result: any) => formatVerificationResult(result)
-  },
-
   // Session-based per-field tools (v2)
   set_standards: entry(setStandardsTool, handleSetStandards),
   set_valid_token_ids: entry(setValidTokenIdsTool, handleSetValidTokenIds),
@@ -272,6 +245,80 @@ export interface CallToolResult {
   isError?: boolean;
 }
 
+/**
+ * Pre-flight check against `tool.inputSchema` (JSON-Schema-shaped). Catches
+ * the two LLM-agent footguns that handlers were silently tolerating:
+ *
+ *   1. **Missing required field** — handler reads `args.foo.toString()` and
+ *      crashes with "Cannot read properties of undefined". An LLM agent
+ *      gets a stack trace instead of "missing required field 'foo'".
+ *
+ *   2. **Wrong arg key** — agent passes `tokenIds` instead of
+ *      `validTokenIds`. Without `additionalProperties: false`, the handler
+ *      silently treats the field as missing and proceeds; state never
+ *      gets set; the agent thinks the call succeeded.
+ *
+ * We check JSON Schema `required` always, and optionally `additionalProperties`
+ * when the tool's schema declares it `false`. Tools that DON'T set
+ * `additionalProperties: false` retain their existing tolerant behavior
+ * (some legitimately accept arbitrary kwargs).
+ */
+function preflightArgs(tool: any, args: any): { ok: true } | { ok: false; error: string } {
+  const schema = tool?.inputSchema;
+  if (!schema || typeof schema !== 'object') return { ok: true };
+  const argsObj = args && typeof args === 'object' && !Array.isArray(args) ? args : {};
+
+  // Required fields
+  if (Array.isArray(schema.required) && schema.required.length > 0) {
+    const missing: string[] = [];
+    for (const key of schema.required) {
+      if (argsObj[key] === undefined || argsObj[key] === null || argsObj[key] === '') {
+        missing.push(key);
+      }
+    }
+    if (missing.length > 0) {
+      const expected = Array.isArray(schema.required) ? schema.required.join(', ') : '';
+      return {
+        ok: false,
+        error: `Missing required field${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}.${expected ? ` Expected: ${expected}` : ''}`
+      };
+    }
+  }
+
+  // Unknown fields (only when explicitly closed)
+  if (schema.additionalProperties === false && schema.properties && typeof schema.properties === 'object') {
+    const allowed = new Set(Object.keys(schema.properties));
+    const unknown = Object.keys(argsObj).filter((k) => !allowed.has(k));
+    if (unknown.length > 0) {
+      const allowedList = [...allowed].join(', ');
+      return {
+        ok: false,
+        error: `Unknown field${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}. Allowed: ${allowedList}.`
+      };
+    }
+  }
+  return { ok: true };
+}
+
+/**
+ * Format a thrown error for tool consumers. Recognizes Zod issues and
+ * renders them as `path: message` lines instead of a giant JSON dump.
+ * Falls back to plain `error.message` for anything else.
+ */
+function formatToolError(err: unknown): string {
+  if (!err || typeof err !== 'object') return String(err);
+  const e = err as any;
+  // Zod errors have `issues: ZodIssue[]` with `path` + `message` per entry.
+  if (Array.isArray(e.issues) && e.issues.length > 0 && e.issues[0]?.message) {
+    const lines = e.issues.map((i: any) => {
+      const path = Array.isArray(i.path) && i.path.length > 0 ? i.path.join('.') : '(root)';
+      return `${path}: ${i.message}`;
+    });
+    return `Invalid input — ${e.issues.length} issue${e.issues.length > 1 ? 's' : ''}:\n  ${lines.join('\n  ')}`;
+  }
+  return e.message ? String(e.message) : String(err);
+}
+
 /**
  * Invoke a tool by name. Never throws — errors are captured into the result.
  */
@@ -280,13 +327,21 @@ export async function callTool(name: string, args: any): Promise<CallToolResult>
   if (!tool) {
     return { text: `Unknown tool: ${name}`, result: null, isError: true };
   }
+  // Centralized pre-flight: catches missing-required and unknown-field
+  // mistakes BEFORE the handler runs. Without this, handlers dereferencing
+  // a missing field would crash with "Cannot read properties of undefined"
+  // and agents would get a stack trace instead of a structured error.
+  const pre = preflightArgs(tool.tool, args);
+  if (!pre.ok) {
+    return { text: `Error: ${pre.error}`, result: null, isError: true };
+  }
   try {
     const result = await tool.run(args);
     const text = tool.formatText ? tool.formatText(result) : JSON.stringify(result, null, 2);
     return { text, result };
   } catch (error) {
     return {
-      text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+      text: `Error: ${formatToolError(error)}`,
       result: null,
       isError: true
     };
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/session/addAliasPath.ts b/packages/bitbadgesjs-sdk/src/builder/tools/session/addAliasPath.ts
index 636106a86f..6c75ac642b 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/session/addAliasPath.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/session/addAliasPath.ts
@@ -1,9 +1,21 @@
 import { z } from 'zod';
-import { addAliasPath as addAliasPathToSession, getOrCreateSession } from '../../session/sessionState.js';
+import { addAliasPath as addAliasPathToSession, getOrCreateSession, getMsgPlaceholders } from '../../session/sessionState.js';
 
 export const addAliasPathSchema = z.object({
   sessionId: z.string().optional().describe("Session ID for per-request isolation."),
   creatorAddress: z.string().optional(),
+  // Off-chain metadata for the path-level placeholder URI. These are stored
+  // in the session's metadataPlaceholders sidecar (NOT on the proto) and
+  // referenced by metadata.uri. The metadata auto-apply flow uploads the
+  // sidecar entries as off-chain JSON and substitutes the placeholder URIs.
+  pathName: z.string().optional().describe('Display name for this alias path (off-chain metadata). Stored in metadataPlaceholders sidecar.'),
+  pathDescription: z.string().optional().describe('1-2 sentence description for this alias path (off-chain metadata).'),
+  pathImage: z.string().optional().describe('Image URL or IMAGE_N placeholder for this alias path (off-chain metadata).'),
+  // Optional per-denomUnit display content. Indexed by unit position. Same
+  // routing — sidecar only, not the proto.
+  denomUnitName: z.string().optional().describe('Display name for the default denom unit (off-chain).'),
+  denomUnitDescription: z.string().optional().describe('Description for the default denom unit (off-chain).'),
+  denomUnitImage: z.string().optional().describe('Image URL or IMAGE_N placeholder for the default denom unit (off-chain).'),
   aliasPath: z.object({
     denom: z.string().describe('Base denom symbol (e.g., "uvatom", "uwusdc"). Must only contain a-zA-Z, _, {, }, -. NEVER use raw IBC denom (ibc/...).'),
     symbol: z.string().describe('Same as denom for the base unit.'),
@@ -15,16 +27,18 @@ export const addAliasPathSchema = z.object({
       decimals: z.string().describe('Decimal places as string. Must match IBC denom decimals (e.g., "6" for ATOM/USDC).'),
       symbol: z.string().describe('Display symbol (e.g., "vATOM", "wUSDC"). Do NOT reuse reserved symbols.'),
       isDefaultDisplay: z.boolean().optional(),
+      // PathMetadata only has { uri, customData }. Do NOT add an image
+      // field here — images live inside the off-chain JSON at metadata.uri
+      // and are handled by the metadata auto-apply flow.
       metadata: z.object({
         uri: z.string().optional().default(''),
-        customData: z.string().optional().default(''),
-        image: z.string().describe('Token logo URL. REQUIRED.')
+        customData: z.string().optional().default('')
       }).optional()
     })).describe('Display units with decimals > 0 ONLY. Base decimals (0) is implicit.'),
+    // PathMetadata only has { uri, customData }. See note on denomUnits.
     metadata: z.object({
       uri: z.string().optional().default(''),
-      customData: z.string().optional().default(''),
-      image: z.string().describe('Token logo URL. REQUIRED for alias paths.')
+      customData: z.string().optional().default('')
     }).optional()
   })
 });
@@ -33,12 +47,18 @@ export type AddAliasPathInput = z.infer<typeof addAliasPathSchema>;
 
 export const addAliasPathTool = {
   name: 'add_alias_path',
-  description: 'Add an alias path for ICS20-backed tokens or liquidity pools. Required for smart tokens. Decimals must match the IBC denom decimals. All metadata MUST include an image field.',
+  description: 'Add an alias path for ICS20-backed tokens or liquidity pools. Required for smart tokens. Decimals must match the IBC denom decimals. PathMetadata on-chain only has { uri, customData }; pass pathName / pathDescription / pathImage (and denomUnitName / Description / Image) as TOP-LEVEL params and they will be routed into the off-chain metadataPlaceholders sidecar keyed by an auto-generated placeholder URI.',
   inputSchema: {
     type: 'object' as const,
     properties: {
       sessionId: { type: 'string', description: 'Session ID.' },
       creatorAddress: { type: 'string' },
+      pathName: { type: 'string', description: 'Display name for the alias path. Stored off-chain in metadataPlaceholders.' },
+      pathDescription: { type: 'string', description: '1-2 sentence description for the alias path. Off-chain.' },
+      pathImage: { type: 'string', description: 'Image URL or IMAGE_N placeholder for the alias path. Off-chain.' },
+      denomUnitName: { type: 'string', description: 'Display name for the default denom unit. Off-chain.' },
+      denomUnitDescription: { type: 'string', description: 'Description for the default denom unit. Off-chain.' },
+      denomUnitImage: { type: 'string', description: 'Image URL or IMAGE_N placeholder for the default denom unit. Off-chain.' },
       aliasPath: {
         type: 'object',
         description: 'Alias path configuration for ICS20-backed tokens.',
@@ -82,10 +102,10 @@ export const addAliasPathTool = {
                 isDefaultDisplay: { type: 'boolean', description: 'Whether this is the default display unit.' },
                 metadata: {
                   type: 'object',
+                  description: 'PathMetadata — ONLY { uri, customData }. No image/name/description at this level.',
                   properties: {
-                    uri: { type: 'string' },
-                    customData: { type: 'string' },
-                    image: { type: 'string', description: 'Token logo URL. REQUIRED.' }
+                    uri: { type: 'string', description: 'Placeholder URI like "ipfs://METADATA_ALIAS_<denom>_UNIT_<idx>". The metadata auto-apply flow substitutes real URIs after the off-chain JSON (with image/name/description) is uploaded.' },
+                    customData: { type: 'string' }
                   }
                 }
               },
@@ -94,11 +114,10 @@ export const addAliasPathTool = {
           },
           metadata: {
             type: 'object',
-            description: 'Path-level metadata.',
+            description: 'Path-level PathMetadata — ONLY { uri, customData }. The image/name/description live inside the off-chain JSON at metadata.uri, not on this proto.',
             properties: {
-              uri: { type: 'string' },
-              customData: { type: 'string' },
-              image: { type: 'string', description: 'Token logo URL. REQUIRED for alias paths.' }
+              uri: { type: 'string', description: 'Placeholder URI like "ipfs://METADATA_ALIAS_<denom>". Substituted by the metadata auto-apply flow.' },
+              customData: { type: 'string' }
             }
           }
         },
@@ -125,20 +144,87 @@ export function handleAddAliasPath(input: AddAliasPathInput) {
     return { success: false, error: `Symbol "${symbol}" contains invalid characters. Only a-zA-Z, _, {, }, - are allowed.` };
   }
 
-  // Propagate path-level image to denomUnits that are missing metadata/image
-  const pathImage = input.aliasPath.metadata?.image || '';
+  // PathMetadata only has { uri, customData }. An `image` field at this
+  // level is invalid proto. Strip any inbound `image` field and ensure
+  // every PathMetadata has a placeholder uri the metadata auto-apply flow
+  // can substitute. We then route any image/name/description the caller
+  // passed (either via the new top-level params or, defensively, via the
+  // legacy nested-on-metadata shape) into the session's metadataPlaceholders
+  // sidecar. Nothing about the image goes onto the on-chain proto.
+  let legacyPathImage: string | undefined;
+  let legacyPathName: string | undefined;
+  let legacyPathDescription: string | undefined;
+  if (input.aliasPath.metadata) {
+    const { image, name, description, ...cleanPathMetadata } = input.aliasPath.metadata as any;
+    legacyPathImage = typeof image === 'string' ? image : undefined;
+    legacyPathName = typeof name === 'string' ? name : undefined;
+    legacyPathDescription = typeof description === 'string' ? description : undefined;
+    input.aliasPath.metadata = {
+      uri: cleanPathMetadata.uri || `ipfs://METADATA_ALIAS_${denom}`,
+      customData: cleanPathMetadata.customData || ''
+    };
+  } else {
+    input.aliasPath.metadata = { uri: `ipfs://METADATA_ALIAS_${denom}`, customData: '' };
+  }
+  const pathUri = input.aliasPath.metadata!.uri as string;
+
+  // Track the default denom unit URI so we can attach off-chain metadata to
+  // the right placeholder.
+  let defaultUnitUri: string | undefined;
+  let legacyUnitImage: string | undefined;
+  let legacyUnitName: string | undefined;
+  let legacyUnitDescription: string | undefined;
   if (input.aliasPath.denomUnits && Array.isArray(input.aliasPath.denomUnits)) {
-    input.aliasPath.denomUnits = input.aliasPath.denomUnits.map((unit: any) => {
-      if (!unit.metadata) {
-        unit.metadata = { uri: '', customData: '', image: pathImage };
-      } else if (!unit.metadata.image) {
-        unit.metadata.image = pathImage;
+    input.aliasPath.denomUnits = input.aliasPath.denomUnits.map((unit: any, idx: number) => {
+      if (!unit.metadata || typeof unit.metadata !== 'object') {
+        unit.metadata = { uri: `ipfs://METADATA_ALIAS_${denom}_UNIT_${idx}`, customData: '' };
+      } else {
+        const { image, name, description, ...cleanUnitMetadata } = unit.metadata as any;
+        if (unit.isDefaultDisplay || idx === 0) {
+          if (typeof image === 'string') legacyUnitImage = image;
+          if (typeof name === 'string') legacyUnitName = name;
+          if (typeof description === 'string') legacyUnitDescription = description;
+        }
+        unit.metadata = {
+          uri: cleanUnitMetadata.uri || `ipfs://METADATA_ALIAS_${denom}_UNIT_${idx}`,
+          customData: cleanUnitMetadata.customData || ''
+        };
+      }
+      if ((unit.isDefaultDisplay || idx === 0) && !defaultUnitUri) {
+        defaultUnitUri = unit.metadata.uri;
       }
       return unit;
     });
   }
 
-  getOrCreateSession(input.sessionId, input.creatorAddress);
+  // Persist the alias path itself into session state.
+  const session = getOrCreateSession(input.sessionId, input.creatorAddress);
   addAliasPathToSession(input.sessionId, input.aliasPath);
+  const placeholders = getMsgPlaceholders(session);
+
+  // Route off-chain metadata into the per-msg metadataPlaceholders sidecar
+  // at `messages[0].value._meta.metadataPlaceholders`. Top-level params
+  // win over legacy nested-on-metadata fields if both are set.
+  const pathName = input.pathName ?? legacyPathName;
+  const pathDescription = input.pathDescription ?? legacyPathDescription;
+  const pathImage = input.pathImage ?? legacyPathImage;
+  if (pathName || pathDescription || pathImage) {
+    placeholders[pathUri] = {
+      name: pathName || placeholders[pathUri]?.name || `${denom} alias path`,
+      description: pathDescription || placeholders[pathUri]?.description || '',
+      image: pathImage || placeholders[pathUri]?.image || ''
+    };
+  }
+  const unitName = input.denomUnitName ?? legacyUnitName;
+  const unitDescription = input.denomUnitDescription ?? legacyUnitDescription;
+  const unitImage = input.denomUnitImage ?? legacyUnitImage;
+  if (defaultUnitUri && (unitName || unitDescription || unitImage)) {
+    placeholders[defaultUnitUri] = {
+      name: unitName || placeholders[defaultUnitUri]?.name || `${denom} default unit`,
+      description: unitDescription || placeholders[defaultUnitUri]?.description || '',
+      image: unitImage || placeholders[defaultUnitUri]?.image || ''
+    };
+  }
+
   return { success: true, denom: input.aliasPath.denom };
 }
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/session/addCosmosWrapperPath.ts b/packages/bitbadgesjs-sdk/src/builder/tools/session/addCosmosWrapperPath.ts
index 40a7cda84d..1ef1311282 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/session/addCosmosWrapperPath.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/session/addCosmosWrapperPath.ts
@@ -19,13 +19,23 @@
  */
 
 import { z } from 'zod';
-import { addCosmosWrapperPath as addCosmosWrapperPathToSession, getOrCreateSession } from '../../session/sessionState.js';
+import { addCosmosWrapperPath as addCosmosWrapperPathToSession, getOrCreateSession, getMsgPlaceholders } from '../../session/sessionState.js';
 
 const VALID_CHARS = /^[a-zA-Z_{}-]+$/;
 
 export const addCosmosWrapperPathSchema = z.object({
   sessionId: z.string().optional().describe("Session ID for per-request isolation."),
   creatorAddress: z.string().optional(),
+  // Off-chain metadata for the path-level placeholder URI. Stored in the
+  // session's metadataPlaceholders sidecar and referenced by metadata.uri.
+  // The metadata auto-apply flow uploads the sidecar entries as off-chain
+  // JSON and substitutes the placeholder URIs.
+  pathName: z.string().optional().describe('Display name for this wrapper path (off-chain metadata).'),
+  pathDescription: z.string().optional().describe('1-2 sentence description for this wrapper path (off-chain metadata).'),
+  pathImage: z.string().optional().describe('Image URL or IMAGE_N placeholder for this wrapper path (off-chain metadata).'),
+  denomUnitName: z.string().optional().describe('Display name for the default denom unit (off-chain).'),
+  denomUnitDescription: z.string().optional().describe('Description for the default denom unit (off-chain).'),
+  denomUnitImage: z.string().optional().describe('Image URL or IMAGE_N placeholder for the default denom unit (off-chain).'),
   wrapperPath: z.object({
     denom: z.string().describe('Custom denom for the wrapped ICS20 coin (e.g., "utoken", "uwrapped"). Must only contain a-zA-Z, _, {, }, -. This creates a NEW denom — do NOT use an existing IBC denom.'),
     symbol: z.string().describe('Symbol for the base unit. Usually same as denom.'),
@@ -39,17 +49,19 @@ export const addCosmosWrapperPathSchema = z.object({
       decimals: z.string().describe('Display decimals for this unit (e.g., "6"). Min 1, max 18.'),
       symbol: z.string().describe('Display symbol (e.g., "TOKEN"). Must only contain a-zA-Z, _, {, }, -.'),
       isDefaultDisplay: z.boolean().optional().describe('Whether this is the default display unit.'),
+      // PathMetadata only has { uri, customData }. Image/name/description
+      // live inside the off-chain JSON at metadata.uri and are handled by
+      // the metadata auto-apply flow.
       metadata: z.object({
         uri: z.string().optional().default(''),
-        customData: z.string().optional().default(''),
-        image: z.string().describe('Token logo URL. REQUIRED.')
+        customData: z.string().optional().default('')
       }).optional()
     })).describe('Denomination units for display. At least one with isDefaultDisplay: true required.'),
     allowOverrideWithAnyValidToken: z.boolean().optional().default(false).describe('If true, users can choose any valid token ID to wrap. If false (default), must match exact tokenIds in conversion.'),
+    // PathMetadata only has { uri, customData }. See note on denomUnits.
     metadata: z.object({
       uri: z.string().optional().default(''),
-      customData: z.string().optional().default(''),
-      image: z.string().optional().describe('Token logo URL. Recommended for display.')
+      customData: z.string().optional().default('')
     }).optional()
   })
 });
@@ -58,12 +70,18 @@ export type AddCosmosWrapperPathInput = z.infer<typeof addCosmosWrapperPathSchem
 
 export const addCosmosWrapperPathTool = {
   name: 'add_cosmos_wrapper_path',
-  description: 'Add a Cosmos coin wrapper path for wrapping BitBadges tokens to a NEW ICS20 denomination. This mints/burns a custom ICS20 coin — NOT wrapping to an existing coin like USDC. ADVANCED: most use cases should use smart tokens (backed by existing coins), liquidity pools, or coinTransfers instead. Approvals for the wrapper address need allowSpecialWrapping: true and mustPrioritize: true.',
+  description: 'Add a Cosmos coin wrapper path for wrapping BitBadges tokens to a NEW ICS20 denomination. This mints/burns a custom ICS20 coin — NOT wrapping to an existing coin like USDC. ADVANCED: most use cases should use smart tokens (backed by existing coins), liquidity pools, or coinTransfers instead. Approvals for the wrapper address need allowSpecialWrapping: true and mustPrioritize: true. PathMetadata on-chain only has { uri, customData }; pass pathName / pathDescription / pathImage (and denomUnitName / Description / Image) as TOP-LEVEL params and they will be routed into the off-chain metadataPlaceholders sidecar.',
   inputSchema: {
     type: 'object' as const,
     properties: {
       sessionId: { type: 'string', description: 'Session ID.' },
       creatorAddress: { type: 'string' },
+      pathName: { type: 'string', description: 'Display name for the wrapper path. Stored off-chain in metadataPlaceholders.' },
+      pathDescription: { type: 'string', description: '1-2 sentence description for the wrapper path. Off-chain.' },
+      pathImage: { type: 'string', description: 'Image URL or IMAGE_N placeholder for the wrapper path. Off-chain.' },
+      denomUnitName: { type: 'string', description: 'Display name for the default denom unit. Off-chain.' },
+      denomUnitDescription: { type: 'string', description: 'Description for the default denom unit. Off-chain.' },
+      denomUnitImage: { type: 'string', description: 'Image URL or IMAGE_N placeholder for the default denom unit. Off-chain.' },
       wrapperPath: {
         type: 'object',
         description: 'Wrapper path config. Denom creates a NEW ICS20 coin. Wrapper address is auto-generated from denom.',
@@ -107,10 +125,10 @@ export const addCosmosWrapperPathTool = {
                 isDefaultDisplay: { type: 'boolean', description: 'Whether this is the default display unit.' },
                 metadata: {
                   type: 'object',
+                  description: 'PathMetadata — ONLY { uri, customData }. No image/name/description at this level.',
                   properties: {
-                    uri: { type: 'string' },
-                    customData: { type: 'string' },
-                    image: { type: 'string', description: 'Token logo URL. REQUIRED.' }
+                    uri: { type: 'string', description: 'Placeholder URI like "ipfs://METADATA_WRAPPER_<denom>_UNIT_<idx>". Substituted by the metadata auto-apply flow.' },
+                    customData: { type: 'string' }
                   }
                 }
               },
@@ -120,11 +138,10 @@ export const addCosmosWrapperPathTool = {
           allowOverrideWithAnyValidToken: { type: 'boolean', description: 'If true, users can choose any valid token ID to wrap. Default false.' },
           metadata: {
             type: 'object',
-            description: 'Path-level metadata.',
+            description: 'Path-level PathMetadata — ONLY { uri, customData }. Image/name/description live inside the off-chain JSON at metadata.uri.',
             properties: {
-              uri: { type: 'string' },
-              customData: { type: 'string' },
-              image: { type: 'string', description: 'Token logo URL. Recommended for display.' }
+              uri: { type: 'string', description: 'Placeholder URI like "ipfs://METADATA_WRAPPER_<denom>". Substituted by the metadata auto-apply flow.' },
+              customData: { type: 'string' }
             }
           }
         },
@@ -150,21 +167,80 @@ export function handleAddCosmosWrapperPath(input: AddCosmosWrapperPathInput) {
     return { success: false, error: `Symbol "${symbol}" contains invalid characters. Only a-zA-Z, _, {, }, - are allowed.` };
   }
 
-  // Propagate path-level image to denomUnits that are missing metadata/image
-  const pathImage = input.wrapperPath.metadata?.image || '';
+  // PathMetadata only has { uri, customData }. Strip any inbound `image`
+  // (or other invalid fields) and ensure every PathMetadata has a
+  // placeholder uri the metadata auto-apply flow can substitute. Then
+  // route off-chain metadata into the session's metadataPlaceholders
+  // sidecar — NEVER onto the proto.
+  let legacyPathImage: string | undefined;
+  let legacyPathName: string | undefined;
+  let legacyPathDescription: string | undefined;
+  if (input.wrapperPath.metadata) {
+    const { image, name, description, ...cleanPathMetadata } = input.wrapperPath.metadata as any;
+    legacyPathImage = typeof image === 'string' ? image : undefined;
+    legacyPathName = typeof name === 'string' ? name : undefined;
+    legacyPathDescription = typeof description === 'string' ? description : undefined;
+    input.wrapperPath.metadata = {
+      uri: cleanPathMetadata.uri || `ipfs://METADATA_WRAPPER_${denom}`,
+      customData: cleanPathMetadata.customData || ''
+    };
+  } else {
+    input.wrapperPath.metadata = { uri: `ipfs://METADATA_WRAPPER_${denom}`, customData: '' };
+  }
+  const pathUri = input.wrapperPath.metadata!.uri as string;
+
+  let defaultUnitUri: string | undefined;
+  let legacyUnitImage: string | undefined;
+  let legacyUnitName: string | undefined;
+  let legacyUnitDescription: string | undefined;
   if (input.wrapperPath.denomUnits && Array.isArray(input.wrapperPath.denomUnits)) {
-    input.wrapperPath.denomUnits = input.wrapperPath.denomUnits.map((unit: any) => {
-      if (!unit.metadata) {
-        unit.metadata = { uri: '', customData: '', image: pathImage };
-      } else if (!unit.metadata.image) {
-        unit.metadata.image = pathImage;
+    input.wrapperPath.denomUnits = input.wrapperPath.denomUnits.map((unit: any, idx: number) => {
+      if (!unit.metadata || typeof unit.metadata !== 'object') {
+        unit.metadata = { uri: `ipfs://METADATA_WRAPPER_${denom}_UNIT_${idx}`, customData: '' };
+      } else {
+        const { image, name, description, ...cleanUnitMetadata } = unit.metadata as any;
+        if (unit.isDefaultDisplay || idx === 0) {
+          if (typeof image === 'string') legacyUnitImage = image;
+          if (typeof name === 'string') legacyUnitName = name;
+          if (typeof description === 'string') legacyUnitDescription = description;
+        }
+        unit.metadata = {
+          uri: cleanUnitMetadata.uri || `ipfs://METADATA_WRAPPER_${denom}_UNIT_${idx}`,
+          customData: cleanUnitMetadata.customData || ''
+        };
+      }
+      if ((unit.isDefaultDisplay || idx === 0) && !defaultUnitUri) {
+        defaultUnitUri = unit.metadata.uri;
       }
       return unit;
     });
   }
 
-  getOrCreateSession(input.sessionId, input.creatorAddress);
+  const session = getOrCreateSession(input.sessionId, input.creatorAddress);
   addCosmosWrapperPathToSession(input.sessionId, input.wrapperPath);
+  const placeholders = getMsgPlaceholders(session);
+
+  const pathName = input.pathName ?? legacyPathName;
+  const pathDescription = input.pathDescription ?? legacyPathDescription;
+  const pathImage = input.pathImage ?? legacyPathImage;
+  if (pathName || pathDescription || pathImage) {
+    placeholders[pathUri] = {
+      name: pathName || placeholders[pathUri]?.name || `${denom} wrapper path`,
+      description: pathDescription || placeholders[pathUri]?.description || '',
+      image: pathImage || placeholders[pathUri]?.image || ''
+    };
+  }
+  const unitName = input.denomUnitName ?? legacyUnitName;
+  const unitDescription = input.denomUnitDescription ?? legacyUnitDescription;
+  const unitImage = input.denomUnitImage ?? legacyUnitImage;
+  if (defaultUnitUri && (unitName || unitDescription || unitImage)) {
+    placeholders[defaultUnitUri] = {
+      name: unitName || placeholders[defaultUnitUri]?.name || `${denom} default unit`,
+      description: unitDescription || placeholders[defaultUnitUri]?.description || '',
+      image: unitImage || placeholders[defaultUnitUri]?.image || ''
+    };
+  }
+
   return {
     success: true,
     denom: input.wrapperPath.denom,
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/session/getTransaction.ts b/packages/bitbadgesjs-sdk/src/builder/tools/session/getTransaction.ts
index 2824e201a5..4f9a720ba9 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/session/getTransaction.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/session/getTransaction.ts
@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { getTransaction as getTransactionFromSession, getOrCreateSession, ensureStringNumbers } from '../../session/sessionState.js';
+import { normalizeTxMessages } from '../../../cli/utils/normalizeMsg.js';
 
 export const getTransactionSchema = z.object({
   sessionId: z.string().optional().describe("Session ID for per-request isolation."),
@@ -50,5 +51,9 @@ export function handleGetTransaction(input: GetTransactionInput) {
   const sanitized = ensureStringNumbers(transaction);
   // Replace any unreplaced IMAGE_N placeholders with default logo
   const cleaned = replaceUnresolvedImagePlaceholders(sanitized);
-  return { success: true, transaction: cleaned };
+  // Narrow Universal → MsgCreateCollection / MsgUpdateCollection at this
+  // agent-facing boundary. Session storage stays on Universal (superset)
+  // so internal mutators don't have to branch on message type.
+  const normalized = normalizeTxMessages(cleaned);
+  return { success: true, transaction: normalized };
 }
diff --git a/packages/bitbadgesjs-sdk/src/builder/tools/utilities/fetchDocs.ts b/packages/bitbadgesjs-sdk/src/builder/tools/utilities/fetchDocs.ts
index 9d88be3af3..e39fc77bcc 100644
--- a/packages/bitbadgesjs-sdk/src/builder/tools/utilities/fetchDocs.ts
+++ b/packages/bitbadgesjs-sdk/src/builder/tools/utilities/fetchDocs.ts
@@ -91,8 +91,10 @@ const TOPIC_URL_MAP: Record<string, string> = {
   'ai agents': 'https://docs.bitbadges.io/for-developers/ai-agents',
   'ai': 'https://docs.bitbadges.io/for-developers/ai-agents',
   'bots': 'https://docs.bitbadges.io/for-developers/ai-agents',
-  'mcp': 'https://docs.bitbadges.io/for-developers/ai-agents/mcp-builder-tools',
-  'mcp tools': 'https://docs.bitbadges.io/for-developers/ai-agents/mcp-builder-tools',
+  'builder': 'https://docs.bitbadges.io/for-developers/ai-agents/builder-tools',
+  'builder tools': 'https://docs.bitbadges.io/for-developers/ai-agents/builder-tools',
+  'mcp': 'https://docs.bitbadges.io/for-developers/ai-agents/builder-tools',
+  'mcp tools': 'https://docs.bitbadges.io/for-developers/ai-agents/builder-tools',
   'bot examples': 'https://docs.bitbadges.io/for-developers/ai-agents/bot-examples',
   'websocket': 'https://docs.bitbadges.io/for-developers/ai-agents/websocket-events',
   'websocket events': 'https://docs.bitbadges.io/for-developers/ai-agents/websocket-events',
@@ -143,6 +145,49 @@ function findTopicUrl(topic: string): string | null {
   return null;
 }
 
+/**
+ * Strip a block-level HTML tag (and its contents) from a string.
+ *
+ * Uses a tempered-greedy token so nested `<` characters inside the block are
+ * consumed, and a flexible closing tag pattern that matches `</tag >` with
+ * trailing whitespace. Runs in a loop until the output is stable so partial
+ * bypasses like `<scr<script>ipt>...</script>` — where a single pass would
+ * leave `<script>...` exposed after removing the inner match — are fully
+ * eliminated.
+ */
+function stripTagBlock(html: string, tag: string): string {
+  const re = new RegExp(
+    `<${tag}\\b[^<]*(?:(?!<\\/${tag}\\s*>)<[^<]*)*<\\/${tag}\\s*>`,
+    'gi'
+  );
+  let current = html;
+  while (true) {
+    const next = current.replace(re, '');
+    if (next === current) return next;
+    current = next;
+  }
+}
+
+/**
+ * Decode the handful of HTML entities we care about in a single pass.
+ *
+ * Doing sequential `.replace()` calls is unsafe because an earlier decode can
+ * produce an entity-looking substring that a later decode then re-interprets
+ * (e.g. `&amp;lt;` → `&lt;` → `<`). A single regex with a lookup table means
+ * each source character position is decoded at most once.
+ */
+const ENTITY_MAP: Record<string, string> = {
+  nbsp: ' ',
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'"
+};
+function decodeHtmlEntities(input: string): string {
+  return input.replace(/&(nbsp|amp|lt|gt|quot|apos);/g, (_match, name: string) => ENTITY_MAP[name] ?? '');
+}
+
 /**
  * Fetch and extract content from a documentation page
  */
@@ -150,7 +195,7 @@ async function fetchDocContent(url: string): Promise<string> {
   try {
     const response = await fetch(url, {
       headers: {
-        'User-Agent': 'BitBadges-Builder-MCP/1.0',
+        'User-Agent': 'BitBadges-Builder/1.0',
         'Accept': 'text/html,application/xhtml+xml'
       }
     });
@@ -161,23 +206,19 @@ async function fetchDocContent(url: string): Promise<string> {
 
     const html = await response.text();
 
-    // Extract main content (simple extraction, GitBook-based)
-    // Remove script and style tags
-    let content = html.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, '');
-    content = content.replace(/<style[^>]*>[\s\S]*?<\/style>/gi, '');
+    // Remove script / style blocks (loop-stable, permissive closing tag).
+    let content = stripTagBlock(html, 'script');
+    content = stripTagBlock(content, 'style');
 
-    // Remove HTML tags but keep text
+    // Remove remaining HTML tags but keep text
     content = content.replace(/<[^>]+>/g, ' ');
 
     // Clean up whitespace
     content = content.replace(/\s+/g, ' ').trim();
 
-    // Decode HTML entities
-    content = content.replace(/&nbsp;/g, ' ');
-    content = content.replace(/&amp;/g, '&');
-    content = content.replace(/&lt;/g, '<');
-    content = content.replace(/&gt;/g, '>');
-    content = content.replace(/&quot;/g, '"');
+    // Decode the small set of HTML entities we care about, in one pass so
+    // `&amp;lt;` does not double-unescape into `<`.
+    content = decodeHtmlEntities(content);
 
     // Truncate to reasonable length
     if (content.length > 10000) {
@@ -202,7 +243,7 @@ async function fetchLlmsFullText(topic: string): Promise<string | null> {
   // Fetch and cache
   if (!llmsFullTextCache) {
     const response = await fetch('https://docs.bitbadges.io/llms-full.txt', {
-      headers: { 'User-Agent': 'BitBadges-Builder-MCP/1.0' }
+      headers: { 'User-Agent': 'BitBadges-Builder/1.0' }
     });
     if (!response.ok) return null;
     llmsFullTextCache = await response.text();
diff --git a/packages/bitbadgesjs-sdk/src/cli/commands/builder.ts b/packages/bitbadgesjs-sdk/src/cli/commands/builder.ts
index 199e0c3435..45a28dcd18 100644
--- a/packages/bitbadgesjs-sdk/src/cli/commands/builder.ts
+++ b/packages/bitbadgesjs-sdk/src/cli/commands/builder.ts
@@ -1,52 +1,55 @@
 /**
- * `mcp` command group — reach every bitbadges-builder-mcp tool from the CLI.
+ * `builder` command group — reach every BitBadges Builder tool from the CLI.
  *
- * The MCP tool registry is imported as a plain library (see
- * bitbadges-builder-mcp/src/tools/registry.ts). There is no subprocess, no
- * stdio MCP protocol — we just call the handlers directly.
+ * The builder tool registry is imported as a plain library (see
+ * src/builder/tools/registry.ts). Handlers are invoked directly — no
+ * subprocess and no MCP protocol on this path. The same registry is also
+ * exposed over stdio by src/builder/index.ts (see src/builder/server.ts) for
+ * Claude Desktop and other MCP clients, but that's a separate transport.
  *
- * Session state is persisted per-invocation under ~/.bitbadges/sessions/<id>.json
- * so agents can compose a collection across many `mcp call` invocations.
+ * Session state is persisted per-invocation via the file-backed store in
+ * src/builder/session/fileStore.ts so agents can compose a collection across
+ * many `builder call` invocations. This file contains no session persistence
+ * logic — it's CLI wiring over library helpers.
  */
 
 import { Command } from 'commander';
 import fs from 'fs';
-import os from 'os';
-import path from 'path';
 
 import {
   toolRegistry,
   listTools,
   callTool,
-  exportSession,
-  importSession,
   resourceRegistry,
   listResources,
   readResource
 } from '../../builder/tools/registry.js';
+import {
+  loadSessionFromDisk,
+  saveSessionToDisk,
+  listSessionFilesOnDisk,
+  readSessionFileRaw,
+  resetSessionFile,
+  sessionFilePath,
+  DEFAULT_SESSIONS_DIR
+} from '../../builder/session/fileStore.js';
+import { templatesCommand } from './templates.js';
+import { addNetworkOptions } from '../utils/io.js';
 
-const SESSIONS_DIR = path.join(os.homedir(), '.bitbadges', 'sessions');
-
-function sessionFilePath(id: string): string {
-  return path.join(SESSIONS_DIR, `${id}.json`);
-}
-
-function loadSession(id: string): void {
-  const file = sessionFilePath(id);
-  if (!fs.existsSync(file)) return;
-  try {
-    const snapshot = JSON.parse(fs.readFileSync(file, 'utf-8'));
-    importSession(id, snapshot);
-  } catch (err) {
-    throw new Error(`Failed to load session "${id}" from ${file}: ${(err as Error).message}`);
-  }
-}
-
-function saveSession(id: string): void {
-  const snapshot = exportSession(id);
-  if (snapshot === null) return;
-  fs.mkdirSync(SESSIONS_DIR, { recursive: true });
-  fs.writeFileSync(sessionFilePath(id), JSON.stringify(snapshot, null, 2));
+/**
+ * Normalize loose CLI input into a transaction body with a `messages` array.
+ *
+ * Accepts any of: a full `{messages: [...]}` tx body (returned as-is), a bare
+ * `{typeUrl, value}` Msg (wrapped into a single-message tx body), or anything
+ * else (passed through untouched so `reviewCollection`'s own tolerant
+ * `extractCollectionValue` can handle raw collection objects and numeric ID
+ * fetch results).
+ */
+function ensureTxWrapper(input: any): any {
+  if (!input || typeof input !== 'object') return input;
+  if (Array.isArray(input.messages)) return input;
+  if (typeof input.typeUrl === 'string' && input.value) return { messages: [input] };
+  return input;
 }
 
 function parseArgs(argsJson: string | undefined, argsFile: string | undefined): any {
@@ -69,7 +72,7 @@ function parseArgs(argsJson: string | undefined, argsFile: string | undefined):
 
 /**
  * If the tool's args mention a session id (via the conventional `sessionId`
- * field that the MCP v2 session tools use), return it. Otherwise fall back to
+ * field that the builder v2 session tools use), return it. Otherwise fall back to
  * the explicit --session flag. This keeps the default session isolated per
  * CLI user without forcing them to repeat the id on every call.
  */
@@ -79,15 +82,35 @@ function resolveSessionId(parsedArgs: any, sessionFlag: string | undefined): str
   return undefined;
 }
 
-export const builderCommand = new Command('builder').description(
-  'Invoke BitBadges Builder tools directly (no MCP protocol / no subprocess).'
-);
+export const builderCommand = new Command('builder')
+  .description(
+    'BitBadges Builder — deterministic templates, fine-grained tools, docs resources, and session state for composing token transactions.'
+  )
+  // Print usage on `builder typo-not-a-real-command` instead of a bare
+  // commander error. Helps users discover the right subcommand name.
+  .showHelpAfterError('(see `bitbadges-cli builder --help` for the full subcommand list)');
+
+// ── builder templates ──────────────────────────────────────────────────────
+//
+// Deterministic flag-based template generators (vault, nft, subscription,
+// bounty, …). Imported from ./templates.ts so the large template surface
+// lives in its own file.
+
+builderCommand.addCommand(templatesCommand);
 
-// ── mcp list ─────────────────────────────────────────────────────────────────
+// ── builder tools ──────────────────────────────────────────────────────────
+//
+// Fine-grained tool registry — the in-process twin of the BitBadges Builder
+// MCP stdio server. Every tool available to Claude Desktop via the builder
+// bin is reachable here as a plain function call.
 
-builderCommand
+const toolsCommand = builderCommand
+  .command('tools')
+  .description('Fine-grained builder tool registry (session builders, queries, reviews, utilities).');
+
+toolsCommand
   .command('list')
-  .description('List every MCP tool with its schema as JSON.')
+  .description('List every builder tool with its schema as JSON.')
   .option('--names', 'Print only tool names, one per line')
   .action((opts: { names?: boolean }) => {
     if (opts.names) {
@@ -99,18 +122,16 @@ builderCommand
     process.stdout.write(JSON.stringify(listTools(), null, 2) + '\n');
   });
 
-// ── mcp call <tool> ──────────────────────────────────────────────────────────
-
-builderCommand
+toolsCommand
   .command('call <tool>')
-  .description('Call an MCP tool by name. Args come from --args (JSON) or --args-file.')
+  .description('Call a builder tool by name. Args come from --args (JSON) or --args-file.')
   .option('--args <json>', 'Tool arguments as a JSON string')
   .option('--args-file <path>', 'Tool arguments read from a JSON file')
   .option(
     '--session <id>',
     'Session id for stateful tools. Stored under ~/.bitbadges/sessions/<id>.json. Defaults to the id inside --args.sessionId, or the builtin default session.'
   )
-  .option('--raw', 'Print the structured result instead of the MCP text block')
+  .option('--raw', 'Print the structured result instead of the formatted text block')
   .action(async (toolName: string, opts: { args?: string; argsFile?: string; session?: string; raw?: boolean }) => {
     if (!toolRegistry[toolName]) {
       const available = Object.keys(toolRegistry).sort().join(', ');
@@ -133,7 +154,7 @@ builderCommand
     // Load session from disk into the in-memory Map before dispatch.
     if (sessionId) {
       try {
-        loadSession(sessionId);
+        loadSessionFromDisk(sessionId);
       } catch (err) {
         process.stderr.write(`${(err as Error).message}\n`);
         process.exitCode = 1;
@@ -150,7 +171,7 @@ builderCommand
     // Persist session state back to disk so the next invocation sees it.
     if (sessionId) {
       try {
-        saveSession(sessionId);
+        saveSessionToDisk(sessionId);
       } catch (err) {
         process.stderr.write(`Warning: failed to save session "${sessionId}": ${(err as Error).message}\n`);
       }
@@ -167,23 +188,1094 @@ builderCommand
     }
   });
 
-// ── mcp session ──────────────────────────────────────────────────────────────
+// ── builder review <input> ───────────────────────────────────────────────────
+//
+// Top-level alias for `sdk review`. Runs reviewCollection() over a
+// transaction, collection, or on-chain collection ID and prints the grouped
+// findings. The review phase is the natural companion to the build phase,
+// so it lives under the same umbrella.
+
+addNetworkOptions(
+  builderCommand
+    .command('review <input>')
+    .description(
+      'Review a built transaction or collection for issues. Input: JSON file, inline JSON, numeric collection ID, or - for stdin.'
+    )
+    .option('--json', 'Output the full ReviewResult as JSON')
+    .option('--strict', 'Exit 1 on warnings (critical always exits 2)')
+    .option('--output-file <path>', 'Write output to file instead of stdout')
+)
+  .action(
+    async (
+      input: string,
+      opts: {
+        json?: boolean;
+        strict?: boolean;
+        network?: 'mainnet' | 'local' | 'testnet';
+        testnet?: boolean;
+        local?: boolean;
+        url?: string;
+        outputFile?: string;
+      }
+    ) => {
+      const { readJsonInput, output, getApiUrl, getApiKeyForNetwork } = await import('../utils/io.js');
+      let data: unknown;
+      // Defensive input handling — both the numeric-id fetch and JSON
+      // parse used to throw uncaught Node errors on bad input. Wrap
+      // both so we get a friendly one-liner instead of a stack dump.
+      if (/^\d+$/.test(input)) {
+        const baseUrl = getApiUrl(opts);
+        const apiKey = getApiKeyForNetwork(opts) || '';
+        try {
+          const response = await fetch(`${baseUrl}/api/v0/collection/${input}`, {
+            headers: { 'x-api-key': apiKey }
+          });
+          if (!response.ok) {
+            process.stderr.write(
+              `Could not fetch collection ${input} from ${baseUrl} — HTTP ${response.status}.\n` +
+                `Hint: --network local may not have a wired collection-by-id endpoint.\n` +
+                `Try passing the collection JSON directly instead of a numeric id.\n`
+            );
+            process.exit(2);
+          }
+          data = await response.json();
+        } catch (err: any) {
+          process.stderr.write(
+            `Could not reach ${baseUrl}/api/v0/collection/${input}: ${err?.message || err}\n`
+          );
+          process.exit(2);
+        }
+      } else {
+        try {
+          data = readJsonInput(input);
+        } catch (err: any) {
+          process.stderr.write(
+            `Failed to parse input JSON: ${err?.message || err}\n` +
+              `Accepts: file path, @file.json, inline JSON, numeric collection id, or - for stdin.\n`
+          );
+          process.exit(2);
+        }
+      }
+
+      const { reviewCollection } = await import('../../core/review.js');
+      let result;
+      try {
+        result = reviewCollection(ensureTxWrapper(data));
+      } catch (err: any) {
+        process.stderr.write(
+          `Could not review input: ${err?.message || err}\n` +
+            `\`builder review\` expects a transaction (with messages[]), a single Msg ({typeUrl,value}), ` +
+            `or a complete on-chain collection document.\n`
+        );
+        process.exit(2);
+      }
+
+      if (opts.json) {
+        output(result, { ...opts, human: false });
+      } else {
+        const { renderReview } = await import('../utils/terminal.js');
+        // When writing to a file, target the "plain" rendering path by
+        // lying about the stream's TTY-ness — createWriteStream isn't a
+        // TTY, so makeColor() inside renderReview naturally drops ANSI.
+        const text = renderReview(result, { stream: process.stdout });
+        if (opts.outputFile) {
+          const fsMod = await import('fs');
+          // Strip any ANSI that snuck in (defensive — renderReview already
+          // disables colour when stdout isn't a TTY).
+          const plain = text.replace(/\x1b\[[0-9;]*m/g, '');
+          fsMod.writeFileSync(opts.outputFile, plain + '\n', 'utf-8');
+          process.stderr.write(`Written to ${opts.outputFile}\n`);
+        } else {
+          console.log(text);
+        }
+      }
+
+      if (result.summary.critical > 0) process.exit(2);
+      if (opts.strict && result.summary.warning > 0) process.exit(1);
+    }
+  );
+
+// ── builder verify <input> ───────────────────────────────────────────────────
+//
+// Aggregate command — runs validate + review + metadata-coverage scan on
+// any saved tx file (or stdin) and renders all three sections with the
+// same terminal renderer the templates auto-review uses. Exit non-zero
+// if anything failed.
+//
+// Saves agents 3+ separate calls per build. Also gives humans a one-stop
+// diligence command for tx files they didn't build through templates.
+
+addNetworkOptions(
+  builderCommand
+    .command('verify <input>')
+    .description(
+      'Aggregate validate + review + metadata coverage check. Input: JSON file, inline JSON, or - for stdin.'
+    )
+    .option('--json', 'Output a structured aggregate JSON instead of rendered sections')
+    .option('--strict', 'Exit 1 on warnings (criticals always exit 2)')
+    .option('--no-validate', 'Skip the structural validation section')
+    .option('--no-review', 'Skip the design review section')
+    .option('--no-metadata', 'Skip the metadata coverage section')
+    .option('--output-file <path>', 'Write the rendered sections to a file instead of stdout')
+)
+  .action(
+    async (
+      input: string,
+      opts: {
+        json?: boolean;
+        strict?: boolean;
+        validate?: boolean;
+        review?: boolean;
+        metadata?: boolean;
+        outputFile?: string;
+      }
+    ) => {
+      const { readJsonInput, output } = await import('../utils/io.js');
+      const {
+        renderValidate,
+        renderReview,
+        renderMetadataPlaceholders,
+        collectMetadataPlaceholders
+      } = await import('../utils/terminal.js');
+
+      // Defensive parse — `readJsonInput` throws on missing files and bad
+      // JSON; without a try/catch the whole command dumps a Node stack.
+      let raw: any;
+      try {
+        raw = readJsonInput(input);
+      } catch (err: any) {
+        process.stderr.write(
+          `Failed to parse input JSON: ${err?.message || err}\n` +
+            `Accepts: file path, @file.json, inline JSON, or - for stdin.\n`
+        );
+        process.exit(2);
+      }
+      const wrapped = ensureTxWrapper(raw);
+
+      // Locate the first collection message (Create / Update / Universal)
+      // so the metadata scan + review pass operate on collection state,
+      // not whatever happens to be at index 0. This makes verify
+      // msg-type-agnostic: a tx like `[MsgTransferTokens, MsgCreateCollection]`
+      // (transfer first, e.g. via add_transfer + post-fact create) still
+      // correctly identifies the collection for review purposes. Falls
+      // back to messages[0] only when there's no collection msg at all,
+      // in which case the metadata + review sections will be skipped
+      // anyway (gated on `firstIsCollection` below).
+      const { isCollectionMsg } = await import('../utils/normalizeMsg.js');
+      const firstMsg = Array.isArray(wrapped?.messages) && wrapped.messages.length > 0
+        ? wrapped.messages.find((m: any) => isCollectionMsg(m)) ?? wrapped.messages[0]
+        : wrapped;
+
+      // `review` and the metadata placeholder scan are collection-CRUD
+      // specific — they walk collectionApprovals, standards, etc. that
+      // only exist on MsgCreateCollection / MsgUpdateCollection / legacy
+      // MsgUniversalUpdateCollection. For user-level approval msgs,
+      // transfers, dynamic stores, and every other tokenization msg type,
+      // validate + simulate are the useful signal and review should stay
+      // silent (empty findings would be misleading).
+      const firstIsCollection = isCollectionMsg(firstMsg);
+
+      let validation: any = null;
+      if (opts.validate !== false) {
+        const { validateTransaction } = await import('../../core/validate.js');
+        validation = validateTransaction(wrapped);
+      }
+
+      let review: any = null;
+      if (opts.review !== false && firstIsCollection) {
+        const { reviewCollection } = await import('../../core/review.js');
+        review = reviewCollection(wrapped);
+      }
+
+      let placeholders: ReturnType<typeof collectMetadataPlaceholders> = [];
+      if (opts.metadata !== false && firstIsCollection) {
+        placeholders = collectMetadataPlaceholders(firstMsg);
+      }
+
+      // JSON output mode — single structured payload for tool consumers.
+      if (opts.json) {
+        output(
+          {
+            validate: validation,
+            review,
+            metadata: {
+              placeholders,
+              filled: firstMsg?.value?._meta?.metadataPlaceholders || {}
+            }
+          },
+          { ...opts, human: false }
+        );
+      } else {
+        const lines: string[] = [];
+        if (validation) {
+          lines.push(renderValidate(validation, { stream: process.stdout }));
+          lines.push('');
+        }
+        if (review) {
+          lines.push(renderReview(review, { stream: process.stdout }));
+          lines.push('');
+        }
+        if (placeholders.length > 0) {
+          lines.push(
+            renderMetadataPlaceholders(placeholders, firstMsg?.value?._meta?.metadataPlaceholders, {
+              stream: process.stdout
+            })
+          );
+        }
+        const text = lines.join('\n');
+
+        if (opts.outputFile) {
+          const fsMod = await import('fs');
+          // Strip ANSI when writing to a file (defensive — the helpers
+          // already disable colour when stdout isn't a TTY).
+          const plain = text.replace(/\x1b\[[0-9;]*m/g, '');
+          fsMod.writeFileSync(opts.outputFile, plain + '\n', 'utf-8');
+          process.stderr.write(`Written to ${opts.outputFile}\n`);
+        } else {
+          console.log(text);
+        }
+      }
+
+      // Exit codes: 2 if anything is critically broken, 1 if --strict and
+      // there are warnings, 0 otherwise.
+      const hasValidationErrors = validation && validation.issues?.some((i: any) => i.severity === 'error');
+      const hasCritical = review && review.summary?.critical > 0;
+      if (hasValidationErrors || hasCritical) {
+        process.exit(2);
+      }
+      const hasValidationWarnings = validation && validation.issues?.some((i: any) => i.severity === 'warning');
+      const hasReviewWarnings = review && review.summary?.warning > 0;
+      if (opts.strict && (hasValidationWarnings || hasReviewWarnings)) {
+        process.exit(1);
+      }
+    }
+  );
+
+// ── builder doctor ───────────────────────────────────────────────────────────
+//
+// One-shot environment + session health check. Six independent probes:
+//
+//   1. Node version (must be ≥ 18)
+//   2. SDK package + version (loaded from bitbadgesjs-sdk's own package.json)
+//   3. CLI config file at ~/.bitbadges/config.json
+//   4. API key reachable (pings /api/v0/simulate with a no-op request)
+//   5. MCP stdio bin presence + smoke launch
+//   6. Persisted sessions parse
+//
+// Each probe reports PASS / FAIL / WARN / SKIP via the same color sigils
+// the rest of the renderer family uses. Exit non-zero only if any probe
+// is a hard FAIL — warnings and skips are informational.
+
+interface DoctorCheck {
+  name: string;
+  status: 'pass' | 'fail' | 'warn' | 'skip';
+  detail?: string;
+}
+
+addNetworkOptions(
+  builderCommand
+    .command('doctor')
+    .description('Environment + session health check. Verifies Node/SDK/config/API key/MCP bin/session integrity. Pass --with-preview to also probe the indexer\'s shareable-preview upload + fetch roundtrip.')
+    .option('--json', 'Output the full DoctorReport as JSON')
+    .option(
+      '--with-preview',
+      'Add a preview-roundtrip probe: builds a minimal tx, POSTs it to /api/v0/builder/preview, GETs it back by code, and asserts the round trip is byte-equivalent. Catches indexer / Redis / preview-route regressions.'
+    )
+).action(async (opts: { json?: boolean; withPreview?: boolean; network?: 'mainnet' | 'local' | 'testnet'; testnet?: boolean; local?: boolean; url?: string }) => {
+    const checks: DoctorCheck[] = [];
+
+    // 1. Node version
+    const nodeVersion = process.versions.node;
+    const nodeMajor = parseInt(nodeVersion.split('.')[0], 10);
+    if (nodeMajor >= 18) {
+      checks.push({ name: 'Node version', status: 'pass', detail: `v${nodeVersion}` });
+    } else {
+      checks.push({
+        name: 'Node version',
+        status: 'fail',
+        detail: `v${nodeVersion} — bitbadgesjs-sdk requires Node 18+`
+      });
+    }
+
+    // 2. SDK version (best-effort lookup via process.argv[1] → walk up
+    // for nearest bitbadgesjs-sdk/package.json). Compatible with both the
+    // CJS and ESM dist builds since neither __dirname nor import.meta.url
+    // would reliably resolve the same way across the two.
+    try {
+      const pathMod = await import('path');
+      const fsMod = await import('fs');
+      // Start from the bin entry script when available, else process.cwd()
+      const startFrom = pathMod.dirname(process.argv[1] || process.cwd());
+      let dir = startFrom;
+      let pkgPath: string | null = null;
+      for (let i = 0; i < 8; i++) {
+        const candidate = pathMod.join(dir, 'package.json');
+        if (fsMod.existsSync(candidate)) {
+          try {
+            const pkg = JSON.parse(fsMod.readFileSync(candidate, 'utf-8'));
+            if (pkg.name === 'bitbadgesjs-sdk') {
+              pkgPath = candidate;
+              break;
+            }
+          } catch {
+            // Not JSON or unreadable — keep walking
+          }
+        }
+        const parent = pathMod.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+      if (pkgPath) {
+        const pkg = JSON.parse(fsMod.readFileSync(pkgPath, 'utf-8'));
+        checks.push({ name: 'SDK package', status: 'pass', detail: `bitbadgesjs-sdk@${pkg.version}` });
+      } else {
+        checks.push({
+          name: 'SDK package',
+          status: 'warn',
+          detail: 'Could not locate bitbadgesjs-sdk package.json from CLI entry'
+        });
+      }
+    } catch (err) {
+      checks.push({ name: 'SDK package', status: 'warn', detail: (err as Error).message });
+    }
+
+    // 3. Config file
+    try {
+      const fsMod = await import('fs');
+      const pathMod = await import('path');
+      const osMod = await import('os');
+      const configPath = pathMod.join(osMod.homedir(), '.bitbadges', 'config.json');
+      if (fsMod.existsSync(configPath)) {
+        try {
+          JSON.parse(fsMod.readFileSync(configPath, 'utf-8'));
+          checks.push({ name: 'Config file', status: 'pass', detail: configPath });
+        } catch {
+          checks.push({ name: 'Config file', status: 'fail', detail: `${configPath} exists but is not valid JSON` });
+        }
+      } else {
+        checks.push({ name: 'Config file', status: 'skip', detail: 'no ~/.bitbadges/config.json (env vars also OK)' });
+      }
+    } catch (err) {
+      checks.push({ name: 'Config file', status: 'fail', detail: (err as Error).message });
+    }
+
+    // 4. API key reachable. Probe the network the user selected via
+    // --network/--local/--testnet (or mainnet by default), so `doctor`
+    // tells you whether THIS network is reachable instead of always
+    // hitting prod.
+    try {
+      const { getApiUrl, getApiKeyForNetwork, resolveNetwork } = await import('../utils/io.js');
+      const key = getApiKeyForNetwork(opts);
+      const network = resolveNetwork(opts);
+      if (!key) {
+        checks.push({
+          name: `API key (${network})`,
+          status: 'skip',
+          detail: `no key set (BITBADGES_API_KEY or config.apiKey${network !== 'mainnet' ? `/apiKey${network[0].toUpperCase() + network.slice(1)}` : ''})`
+        });
+      } else {
+        const url = `${getApiUrl(opts)}/api/v0/simulate`;
+        try {
+          const response = await fetch(url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'x-api-key': key },
+            body: JSON.stringify({ txs: [] })
+          });
+          // Any 2xx/4xx is "reachable" — only network failures are FAIL.
+          // 4xx with a clear message is expected for an empty txs array.
+          if (response.status >= 200 && response.status < 500) {
+            checks.push({
+              name: `API key (${network})`,
+              status: 'pass',
+              detail: `${url} responded with HTTP ${response.status}`
+            });
+          } else {
+            checks.push({ name: `API key (${network})`, status: 'warn', detail: `HTTP ${response.status} from ${url}` });
+          }
+        } catch (err) {
+          checks.push({
+            name: `API key (${network})`,
+            status: 'warn',
+            detail: `network error pinging ${url}: ${(err as Error).message}`
+          });
+        }
+      }
+    } catch (err) {
+      checks.push({ name: 'API key', status: 'fail', detail: (err as Error).message });
+    }
+
+    // 5. MCP stdio bin — try the same package-walk approach to find the
+    // SDK root, then check for dist/cjs/builder/index.js inside it.
+    try {
+      const fsMod = await import('fs');
+      const pathMod = await import('path');
+      const startFrom = pathMod.dirname(process.argv[1] || process.cwd());
+      let dir = startFrom;
+      let pkgRoot: string | null = null;
+      for (let i = 0; i < 8; i++) {
+        const candidate = pathMod.join(dir, 'package.json');
+        if (fsMod.existsSync(candidate)) {
+          try {
+            const pkg = JSON.parse(fsMod.readFileSync(candidate, 'utf-8'));
+            if (pkg.name === 'bitbadgesjs-sdk') {
+              pkgRoot = dir;
+              break;
+            }
+          } catch {
+            // continue
+          }
+        }
+        const parent = pathMod.dirname(dir);
+        if (parent === dir) break;
+        dir = parent;
+      }
+      if (!pkgRoot) {
+        checks.push({
+          name: 'MCP stdio bin',
+          status: 'warn',
+          detail: 'Could not locate SDK root from CLI entry'
+        });
+      } else {
+        const binCandidates = [
+          pathMod.join(pkgRoot, 'dist', 'cjs', 'builder', 'index.js'),
+          pathMod.join(pkgRoot, 'dist', 'esm', 'builder', 'index.js')
+        ];
+        const found = binCandidates.find((p) => fsMod.existsSync(p));
+        if (found) {
+          checks.push({ name: 'MCP stdio bin', status: 'pass', detail: found });
+        } else {
+          checks.push({
+            name: 'MCP stdio bin',
+            status: 'warn',
+            detail: 'dist/cjs/builder/index.js not found — run `npm run build` in bitbadgesjs-sdk'
+          });
+        }
+      }
+    } catch (err) {
+      checks.push({ name: 'MCP stdio bin', status: 'fail', detail: (err as Error).message });
+    }
+
+    // 6. Persisted sessions
+    try {
+      const { listSessionFilesOnDisk, readSessionFileRaw } = await import('../../builder/session/fileStore.js');
+      const ids = listSessionFilesOnDisk();
+      let parseable = 0;
+      let corrupt = 0;
+      for (const id of ids) {
+        const raw = readSessionFileRaw(id);
+        if (!raw) continue;
+        try {
+          JSON.parse(raw);
+          parseable++;
+        } catch {
+          corrupt++;
+        }
+      }
+      if (corrupt > 0) {
+        checks.push({
+          name: 'Sessions',
+          status: 'warn',
+          detail: `${parseable} parseable, ${corrupt} corrupt — run \`bitbadges-cli builder session reset <id>\` on broken ones`
+        });
+      } else {
+        checks.push({ name: 'Sessions', status: 'pass', detail: `${parseable} session(s) on disk` });
+      }
+    } catch (err) {
+      checks.push({ name: 'Sessions', status: 'fail', detail: (err as Error).message });
+    }
+
+    // 7. Optional preview-roundtrip probe (--with-preview).
+    //
+    // Builds a minimal MsgCreateCollection wrapper, POSTs it to
+    // /api/v0/builder/preview, GETs it back by code, and asserts the
+    // round trip preserves the typeUrl + sidecar shape. Catches
+    // regressions in the preview route, Redis storage, JSON parsing,
+    // and the SDK's preview command path itself in one shot. Skipped
+    // by default to keep `doctor` zero-side-effect; opt-in via
+    // --with-preview when you want a deeper local-network probe.
+    if (opts.withPreview) {
+      try {
+        const { getApiUrl: gAU, resolveNetwork: rN } = await import('../utils/io.js');
+        const network = rN(opts);
+        const baseUrl = gAU(opts);
+        const probeTx = {
+          transaction: {
+            messages: [
+              {
+                typeUrl: '/tokenization.MsgCreateCollection',
+                value: {
+                  creator: 'bb1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqpdguex7',
+                  validTokenIds: [],
+                  standards: [],
+                  collectionApprovals: [],
+                  tokenMetadata: [],
+                  aliasPathsToAdd: [],
+                  cosmosCoinWrapperPathsToAdd: [],
+                  mintEscrowCoinsToTransfer: [],
+                  // Canonical location for the placeholder sidecar —
+                  // per-msg, under value._meta. The old top-level
+                  // `metadataPlaceholders` sibling of `transaction` has
+                  // been removed.
+                  _meta: {
+                    metadataPlaceholders: {
+                      'ipfs://METADATA_DOCTOR_PROBE': { name: 'doctor probe', description: '', image: '' }
+                    }
+                  }
+                }
+              }
+            ]
+          }
+        };
+        const postRes = await fetch(`${baseUrl}/api/v0/builder/preview`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(probeTx)
+        });
+        if (!postRes.ok) {
+          checks.push({
+            name: `Preview roundtrip (${network})`,
+            status: 'fail',
+            detail: `POST /api/v0/builder/preview returned HTTP ${postRes.status}`
+          });
+        } else {
+          const { code } = (await postRes.json()) as { code: string };
+          const getRes = await fetch(`${baseUrl}/api/v0/builder/preview?code=${encodeURIComponent(code)}`);
+          if (!getRes.ok) {
+            checks.push({
+              name: `Preview roundtrip (${network})`,
+              status: 'fail',
+              detail: `GET /api/v0/builder/preview returned HTTP ${getRes.status} for the code we just uploaded (${code})`
+            });
+          } else {
+            const fetched = (await getRes.json()) as any;
+            const echoedTypeUrl = fetched?.transaction?.messages?.[0]?.typeUrl;
+            const sidecarKey =
+              fetched?.transaction?.messages?.[0]?.value?._meta?.metadataPlaceholders?.[
+                'ipfs://METADATA_DOCTOR_PROBE'
+              ]?.name;
+            if (echoedTypeUrl !== '/tokenization.MsgCreateCollection' || sidecarKey !== 'doctor probe') {
+              checks.push({
+                name: `Preview roundtrip (${network})`,
+                status: 'fail',
+                detail: `Round trip mutated the payload — got typeUrl=${echoedTypeUrl}, sidecarName=${sidecarKey}`
+              });
+            } else {
+              checks.push({
+                name: `Preview roundtrip (${network})`,
+                status: 'pass',
+                detail: `${baseUrl}/api/v0/builder/preview · uploaded ${code} · fetched and verified`
+              });
+            }
+          }
+        }
+      } catch (err: any) {
+        checks.push({
+          name: 'Preview roundtrip',
+          status: 'fail',
+          detail: `network error: ${err?.message || err}`
+        });
+      }
+    }
+
+    // Render
+    if (opts.json) {
+      const { output: outputFn } = await import('../utils/io.js');
+      outputFn(checks, { ...opts, human: false });
+    } else {
+      const { makeColor, rule } = await import('../utils/terminal.js');
+      const { c } = makeColor(process.stdout);
+      const width = Math.min(80, (process.stdout as any).columns || 80);
+      const lines: string[] = [];
+      lines.push(c('gray', rule('━', width, 'Doctor')));
+      lines.push('');
+      const sigil = { pass: '✓', fail: '■', warn: '▲', skip: '·' } as const;
+      const colorFor = { pass: 'green', fail: 'red', warn: 'yellow', skip: 'gray' } as const;
+      const labelFor = { pass: 'PASS', fail: 'FAIL', warn: 'WARN', skip: 'SKIP' } as const;
+      for (const ch of checks) {
+        const badge = `${sigil[ch.status]} ${labelFor[ch.status]}`;
+        lines.push(`  ${c(colorFor[ch.status], c('bold', badge))}  ${c('bold', ch.name)}`);
+        if (ch.detail) {
+          lines.push(`        ${c('dim', ch.detail)}`);
+        }
+      }
+      lines.push('');
+      const counts = checks.reduce(
+        (acc, ch) => ({ ...acc, [ch.status]: (acc[ch.status] || 0) + 1 }),
+        {} as Record<string, number>
+      );
+      lines.push(c('gray', rule('━', width)));
+      lines.push(
+        `  ${c('bold', 'Summary')}  ${counts.pass || 0} pass · ${
+          counts.fail
+            ? c('red', `${counts.fail} fail`)
+            : c('gray', '0 fail')
+        } · ${counts.warn ? c('yellow', `${counts.warn} warn`) : c('gray', '0 warn')} · ${
+          counts.skip || 0
+        } skip`
+      );
+      lines.push(c('gray', rule('━', width)));
+      console.log(lines.join('\n'));
+    }
+
+    if (checks.some((ch) => ch.status === 'fail')) process.exit(2);
+  });
+
+// ── builder preview <input> ──────────────────────────────────────────────────
+//
+// Upload a built tx to the indexer and print a shareable bitbadges.io preview
+// URL. Lets agents/humans hand off a tx to a non-CLI reviewer for visual
+// inspection without giving them edit/submit rights. The endpoint is open
+// (no API key required); the unguessable code in the URL is the secret.
+// Lives 1 hour in the indexer's Redis cache.
+
+addNetworkOptions(
+  builderCommand
+    .command('preview <input>')
+    .description(
+      'Upload a tx to the indexer and print a shareable bitbadges.io preview URL. Input: JSON file, inline JSON, or - for stdin.'
+    )
+    .option(
+      '--frontend-url <url>',
+      'Override the bitbadges.io frontend base for the printed preview URL',
+      'https://bitbadges.io'
+    )
+    .option('--json', 'Output the structured upload result as JSON instead of just the URL')
+).action(
+    async (
+      input: string,
+      opts: { network?: 'mainnet' | 'local' | 'testnet'; testnet?: boolean; local?: boolean; url?: string; frontendUrl?: string; json?: boolean }
+    ) => {
+      const { readJsonInput, getApiUrl } = await import('../utils/io.js');
+
+      // Read + normalize. Templates emit a single Msg; verify/simulate
+      // wrap into {messages: [...]}. Preview accepts either shape.
+      const raw = readJsonInput(input);
+      const wrapped = ensureTxWrapper(raw);
+
+      // The placeholder sidecar lives inside `msg.value._meta` per the
+      // single-source-of-truth contract — we just need to normalize the
+      // msg type (Universal → Create/Update) and the `_meta` field rides
+      // along inside the value. No lift-to-top-level, no strip.
+      const { normalizeToCreateOrUpdate: _normalize } = await import('../utils/normalizeMsg.js');
+      const cleanedMessages = (wrapped.messages || []).map((m: any) => _normalize(m));
+
+      const payload = {
+        transaction: {
+          messages: cleanedMessages,
+          ...(wrapped.memo ? { memo: wrapped.memo } : {}),
+          ...(wrapped.fee ? { fee: wrapped.fee } : {})
+        }
+      };
+
+      // Direct fetch — apiRequest() requires an API key, but the preview
+      // endpoint is intentionally open.
+      const apiUrl = getApiUrl(opts);
+      const url = `${apiUrl}/api/v0/builder/preview`;
+      let response: Response;
+      try {
+        response = await fetch(url, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(payload)
+        });
+      } catch (err) {
+        process.stderr.write(`Preview upload failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exit(2);
+      }
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        process.stderr.write(`Preview upload failed: HTTP ${response.status} ${text}\n`);
+        process.exit(2);
+      }
+
+      const result = (await response.json()) as {
+        success: boolean;
+        code: string;
+        expiresAt: number;
+        expiresIn: string;
+      };
+
+      const frontendBase = opts.frontendUrl || 'https://bitbadges.io';
+      const previewUrl = `${frontendBase.replace(/\/$/, '')}/builder/preview?code=${encodeURIComponent(result.code)}`;
+
+      if (opts.json) {
+        process.stdout.write(
+          JSON.stringify(
+            {
+              code: result.code,
+              url: previewUrl,
+              expiresAt: result.expiresAt,
+              expiresIn: result.expiresIn
+            },
+            null,
+            2
+          ) + '\n'
+        );
+      } else {
+        // URL on stdout so it's pipe-friendly. TTL reminder on stderr.
+        process.stdout.write(previewUrl + '\n');
+        process.stderr.write(`Expires in ${result.expiresIn}.\n`);
+      }
+    }
+  );
+
+// ── builder simulate <input> ─────────────────────────────────────────────────
+//
+// Standalone simulator. Posts the tx to the BitBadges API's /api/v0/simulate
+// endpoint via simulateMessages(), parses events through
+// parseSimulationEvents → calculateNetChanges, and renders the same
+// Auto-Simulate section the templates use when invoked with --simulate.
+// Requires BITBADGES_API_KEY (or `bitbadges-cli config set apiKey`).
+
+addNetworkOptions(
+  builderCommand
+    .command('simulate <input>')
+    .description(
+      'Dry-run a built tx against the BitBadges API simulate endpoint. Returns gas + per-address net balance changes. Input: JSON file, inline JSON, or - for stdin.'
+    )
+    .option('--json', 'Output the structured SimulateResult as JSON instead of a rendered section')
+    .option('--creator <address>', 'Override the simulation context address (default: bb1simulation)')
+    .option('--events', 'Dump the full raw chain events array in the rendered output (default: just the count)')
+).action(async (
+    input: string,
+    opts: {
+      json?: boolean;
+      creator?: string;
+      events?: boolean;
+      network?: 'mainnet' | 'local' | 'testnet';
+      testnet?: boolean;
+      local?: boolean;
+      url?: string;
+    }
+  ) => {
+    const { readJsonInput, output, getApiUrl, getApiKeyForNetwork } = await import('../utils/io.js');
+    const { simulateMessages } = await import('../../builder/tools/queries/simulateTransaction.js');
+    const { renderSimulate } = await import('../utils/terminal.js');
+    const { prefetchSimulateCollections } = await import('../utils/simulateSymbols.js');
+
+    // Network-aware API key + URL resolution. The simulate endpoint is
+    // gated on an API key on mainnet/testnet but most local indexers
+    // accept any (or no) key — we still pass it through if present so
+    // local routes that DO check it (premium gates) keep working.
+    const apiKey = getApiKeyForNetwork(opts);
+    if (!apiKey) {
+      process.stderr.write(
+        renderSimulate(
+          {
+            success: false,
+            error: 'No API key. Set BITBADGES_API_KEY, run `bitbadges-cli config set apiKey <key>`, or pass --network local against a key-less local indexer.'
+          },
+          { stream: process.stderr }
+        ) + '\n'
+      );
+      process.exit(2);
+    }
+
+    const raw = readJsonInput(input);
+    const wrapped = ensureTxWrapper(raw);
+    const messages = Array.isArray(wrapped?.messages) ? wrapped.messages : [];
+    if (messages.length === 0) {
+      process.stderr.write(
+        renderSimulate(
+          { success: false, error: 'No messages found in input. Expected `{messages: [...]}` or a single Msg.' },
+          { stream: process.stderr }
+        ) + '\n'
+      );
+      process.exit(2);
+    }
+
+    // Refuse to simulate user-level approval messages. They describe a
+    // state mutation on an existing collection's user-approval list, not
+    // a self-contained tx — set/append/delete semantics vary at runtime
+    // and dry-running against a fresh account isn't meaningful. Use
+    // `validate` + `review` instead.
+    const APPROVAL_RE =
+      /\.(MsgUpdateUserApprovals|MsgSetIncomingApproval|MsgSetOutgoingApproval|MsgDeleteIncomingApproval|MsgDeleteOutgoingApproval|MsgPurgeApprovals)$/;
+    const firstApprovalMsg = messages.find((m: any) => typeof m?.typeUrl === 'string' && APPROVAL_RE.test(m.typeUrl));
+    if (firstApprovalMsg) {
+      process.stderr.write(
+        renderSimulate(
+          {
+            success: false,
+            error:
+              `Cannot simulate user-level approval message (${firstApprovalMsg.typeUrl}). ` +
+              'Use `builder validate` and `builder review` to check it, or include it inside an ' +
+              'alternative approval message that wraps a full collection transaction.'
+          },
+          { stream: process.stderr }
+        ) + '\n'
+      );
+      process.exit(2);
+    }
+
+    const result = await simulateMessages({
+      messages,
+      memo: wrapped.memo,
+      fee: wrapped.fee,
+      creatorAddress: opts.creator,
+      apiKey,
+      apiUrl: getApiUrl(opts)
+    });
+
+    if (opts.json) {
+      output(result, { ...opts, human: false });
+    } else {
+      // Pre-fetch alias metadata for every collection referenced by
+      // the result so renderSimulate can suffix balance lines with
+      // their alias / wrapper-path symbol. Best-effort: a fetch
+      // failure just degrades to today's un-suffixed rendering.
+      const collectionCache = await prefetchSimulateCollections(result, {
+        apiKey,
+        apiUrl: getApiUrl(opts)
+      });
+      console.log(
+        renderSimulate(result, {
+          stream: process.stdout,
+          events: opts.events ? 'full' : 'count',
+          collectionCache
+        })
+      );
+    }
+
+    if (!result.success || result.valid === false) process.exit(2);
+  });
+
+// ── builder explain <input> ──────────────────────────────────────────────────
+//
+// Human-readable explanation of a transaction body or a collection. Auto-
+// detects which shape was passed: a MsgUniversalUpdateCollection tx body
+// goes through interpretTransaction(); a raw collection goes through
+// interpretCollection(). Numeric input is treated as a collection id and
+// fetched from the API.
+
+addNetworkOptions(
+  builderCommand
+    .command('explain <input>')
+    .description(
+      'Explain a transaction or collection in plain English. Input: JSON file, inline JSON, numeric collection ID, or - for stdin.'
+    )
+    .option('--output-file <path>', 'Write output to file instead of stdout')
+).action(
+    async (input: string, opts: { network?: 'mainnet' | 'local' | 'testnet'; testnet?: boolean; local?: boolean; url?: string; outputFile?: string }) => {
+      const { readJsonInput, getApiUrl, getApiKeyForNetwork } = await import('../utils/io.js');
+      let data: any;
+      let fetchedCollection = false;
+
+      // Numeric input: try to fetch a collection by id from the indexer.
+      // Wrap in try/catch so a 404 / network failure produces a friendly
+      // error instead of a raw stack trace.
+      if (/^\d+$/.test(input)) {
+        const baseUrl = getApiUrl(opts);
+        const apiKey = getApiKeyForNetwork(opts) || '';
+        try {
+          const response = await fetch(`${baseUrl}/api/v0/collection/${input}`, {
+            headers: { 'x-api-key': apiKey }
+          });
+          if (!response.ok) {
+            process.stderr.write(
+              `Could not fetch collection ${input} from ${baseUrl} — HTTP ${response.status}.\n` +
+                `Hint: the indexer's collection-by-id endpoint may not be wired on --network local.\n` +
+                `Try passing the collection JSON directly (file or inline) instead of a numeric id.\n`
+            );
+            process.exit(2);
+          }
+          data = await response.json();
+          fetchedCollection = true;
+        } catch (err: any) {
+          process.stderr.write(
+            `Could not reach ${baseUrl}/api/v0/collection/${input}: ${err?.message || err}.\n` +
+              `Check that the network is reachable, or pass the collection JSON directly.\n`
+          );
+          process.exit(2);
+        }
+      } else {
+        try {
+          data = readJsonInput(input);
+        } catch (err: any) {
+          process.stderr.write(
+            `Failed to parse input JSON: ${err?.message || err}.\n` +
+              `Accepts: file path, @file.json, inline JSON, numeric collection id, or - for stdin.\n`
+          );
+          process.exit(2);
+        }
+      }
+
+      // Auto-detect shape. Accepts three input shapes and unwraps each
+      // down to the collection `value` that `interpretTransaction` expects:
+      //
+      //   1. Single Msg  — `{ typeUrl, value: {...} }`                   → .value
+      //   2. Tx wrapper  — `{ messages: [{ typeUrl, value }, ...] }`     → first collection msg's value
+      //   3. Raw collection — no typeUrl, no messages, no value          → interpretCollection
+      //
+      // API-fetched collections always take the raw-collection path.
+      // Both interpret paths are wrapped in try/catch — they expect
+      // proto-shaped objects with required fields, and missing fields
+      // (e.g. minimal `{collectionId:"1"}` ad-hoc inputs) used to crash
+      // with `Cannot read properties of undefined (reading 'uri')`.
+      let text: string;
+      const { isCollectionMsg } = await import('../utils/normalizeMsg.js');
+      const hasMessages = Array.isArray(data?.messages);
+      const firstCollectionMsg = hasMessages ? data.messages.find((m: any) => isCollectionMsg(m)) : null;
+
+      try {
+        if (
+          fetchedCollection ||
+          (data && typeof data === 'object' && !data.typeUrl && !hasMessages && !data.value)
+        ) {
+          const { interpretCollection } = await import('../../core/interpret.js');
+          text = interpretCollection(data);
+        } else {
+          const txBody = firstCollectionMsg?.value ?? data.value ?? data;
+          const { interpretTransaction } = await import('../../core/interpret-transaction.js');
+          text = interpretTransaction(txBody);
+        }
+      } catch (err: any) {
+        process.stderr.write(
+          `Could not interpret input: ${err?.message || err}.\n` +
+            `Hint: \`builder explain\` expects either a full transaction (with messages[]),\n` +
+            `a single Msg ({typeUrl, value}), a complete on-chain collection document\n` +
+            `(returned by query_collection), or a numeric collection id. Minimal ad-hoc\n` +
+            `JSON like {collectionId:"1"} is not a valid input — it lacks the fields the\n` +
+            `interpreter needs (collectionMetadata.uri, validTokenIds, etc).\n`
+        );
+        process.exit(2);
+      }
+
+      if (opts.outputFile) {
+        const fsMod = await import('fs');
+        fsMod.writeFileSync(opts.outputFile, text + '\n', 'utf-8');
+        process.stderr.write(`Written to ${opts.outputFile}\n`);
+      } else {
+        console.log(text);
+      }
+    }
+  );
+
+// ── builder validate <input> ─────────────────────────────────────────────────
+//
+// Pure static validation of a transaction body — no API calls, no review
+// framework. Runs the low-level validateTransaction() from core/validate.ts
+// and prints each issue with its path and level. Useful as a fast "is this
+// JSON even shaped right" check before running the fuller review.
+
+// validate is OFFLINE — no API calls. We still accept (and ignore) the
+// network flags via addNetworkOptions so users can pipe the same command
+// through any wrapper script without "unknown option '--local'" errors.
+addNetworkOptions(
+  builderCommand
+    .command('validate <input>')
+    .description(
+      'Run static validation over a transaction JSON (structure, uint ranges, approval criteria, …). Offline — no API calls. Input: JSON file, inline JSON, or - for stdin. Exits 1 on validation failure, 2 on parse failure.'
+    )
+)
+  .option('--json', 'Output the full ValidationResult as JSON')
+  .option('--output-file <path>', 'Write output to file instead of stdout')
+  .action(async (input: string, opts: { json?: boolean; outputFile?: string }) => {
+    const { readJsonInput, output } = await import('../utils/io.js');
+    let data: any;
+    try {
+      data = ensureTxWrapper(readJsonInput(input));
+    } catch (err: any) {
+      // Catch the readJsonInput parse error so we don't dump a raw Node
+      // stack on bad JSON. Output as a clean validation result so JSON
+      // mode stays consumable by tools.
+      const friendly = err?.message || String(err);
+      if (opts.json) {
+        const { output: outFn } = await import('../utils/io.js');
+        outFn(
+          { valid: false, issues: [{ severity: 'error', path: '(input)', message: friendly }] },
+          { ...opts, human: false }
+        );
+      } else {
+        process.stderr.write(`✗ Could not parse input: ${friendly}\n`);
+      }
+      process.exit(2);
+    }
+
+    // Empty messages array isn't a structural error per se but it's almost
+    // never what the user wanted. Surface as a warning so quiet-on-empty
+    // tx files don't slip through.
+    if (Array.isArray(data?.messages) && data.messages.length === 0) {
+      const result = {
+        valid: true,
+        issues: [
+          {
+            severity: 'warning' as const,
+            path: 'messages',
+            message: 'Transaction has an empty messages array. Did you forget to add any messages?'
+          }
+        ]
+      };
+      if (opts.json) {
+        output(result, { ...opts, human: false });
+      } else {
+        process.stderr.write('▲ WARNING  messages: Transaction has an empty messages array.\n');
+      }
+      process.exitCode = 1;
+      return;
+    }
+
+    const { validateTransaction } = await import('../../core/validate.js');
+    const result = validateTransaction(data);
+
+    if (opts.json) {
+      output(result, { ...opts, human: false });
+    } else {
+      const { makeColor, rule } = await import('../utils/terminal.js');
+      const { c } = makeColor(process.stdout);
+      const width = Math.min(80, (process.stdout as any).columns || 80);
+      const lines: string[] = [];
+      lines.push(c('gray', rule('━', width, 'Validate')));
+      if (result.issues.length === 0) {
+        lines.push('');
+        lines.push(`  ${c('green', '✓')} ${c('bold', 'Clean')} — no structural issues`);
+        lines.push('');
+      } else {
+        lines.push('');
+        for (const issue of result.issues) {
+          const levelColor = issue.severity === 'error' ? 'red' : 'yellow';
+          const badge = issue.severity === 'error' ? '■ ERROR  ' : '▲ WARNING';
+          lines.push(`  ${c(levelColor, c('bold', badge))}  ${c('dim', issue.path || '(root)')}`);
+          lines.push(`      ${issue.message}`);
+          lines.push('');
+        }
+      }
+      lines.push(c('gray', rule('━', width)));
+      const errCount = result.issues.filter((i) => i.severity === 'error').length;
+      const warnCount = result.issues.filter((i) => i.severity === 'warning').length;
+      lines.push(
+        `  ${c('bold', 'Summary')}  ${errCount > 0 ? c('red', `${errCount} error`) : c('gray', `${errCount} error`)}  ·  ${
+          warnCount > 0 ? c('yellow', `${warnCount} warning`) : c('gray', `${warnCount} warning`)
+        }`
+      );
+      lines.push(c('gray', rule('━', width)));
+      const text = lines.join('\n');
+      if (opts.outputFile) {
+        const fsMod = await import('fs');
+        const plain = text.replace(/\x1b\[[0-9;]*m/g, '');
+        fsMod.writeFileSync(opts.outputFile, plain + '\n', 'utf-8');
+        process.stderr.write(`Written to ${opts.outputFile}\n`);
+      } else {
+        console.log(text);
+      }
+    }
+
+    if (!result.valid) process.exitCode = 1;
+  });
+
+// ── builder session ──────────────────────────────────────────────────────────────
 
 const sessionCommand = builderCommand
   .command('session')
-  .description('Inspect, dump, or reset persisted MCP builder sessions.');
+  .description('Inspect, dump, or reset persisted builder sessions.');
 
 sessionCommand
   .command('list')
-  .description('List persisted session ids.')
+  .description('List persisted session ids under ~/.bitbadges/sessions/.')
   .action(() => {
-    if (!fs.existsSync(SESSIONS_DIR)) {
-      return;
-    }
-    for (const file of fs.readdirSync(SESSIONS_DIR)) {
-      if (file.endsWith('.json')) {
-        process.stdout.write(file.replace(/\.json$/, '') + '\n');
-      }
+    for (const id of listSessionFilesOnDisk()) {
+      process.stdout.write(id + '\n');
     }
   });
 
@@ -191,30 +1283,27 @@ sessionCommand
   .command('show <id>')
   .description('Print a session snapshot as JSON.')
   .action((id: string) => {
-    const file = sessionFilePath(id);
-    if (!fs.existsSync(file)) {
-      process.stderr.write(`No session file at ${file}\n`);
+    const raw = readSessionFileRaw(id);
+    if (raw === null) {
+      process.stderr.write(`No session file at ${sessionFilePath(id)}\n`);
       process.exitCode = 1;
       return;
     }
-    process.stdout.write(fs.readFileSync(file, 'utf-8'));
+    process.stdout.write(raw);
   });
 
 sessionCommand
   .command('reset <id>')
   .description('Delete a persisted session file.')
   .action((id: string) => {
-    const file = sessionFilePath(id);
-    if (fs.existsSync(file)) {
-      fs.unlinkSync(file);
-    }
+    resetSessionFile(id);
   });
 
-// ── mcp resources ────────────────────────────────────────────────────────────
+// ── builder resources ────────────────────────────────────────────────────────────
 
 const resourcesCommand = builderCommand
   .command('resources')
-  .description('Read static MCP resources (token registry, recipes, skills, docs, error patterns, ...).');
+  .description('Read static builder resources (token registry, recipes, skills, docs, error patterns, ...).');
 
 resourcesCommand
   .command('list')
diff --git a/packages/bitbadgesjs-sdk/src/cli/commands/sdk.ts b/packages/bitbadgesjs-sdk/src/cli/commands/sdk.ts
index 74181cb2d0..bafad1c3aa 100644
--- a/packages/bitbadgesjs-sdk/src/cli/commands/sdk.ts
+++ b/packages/bitbadgesjs-sdk/src/cli/commands/sdk.ts
@@ -9,16 +9,17 @@ export const sdkCommand = new Command('sdk').description('SDK analysis and utili
 
 sdkCommand
   .command('review <input>')
-  .description('Review a transaction or collection JSON for issues. Input: JSON file, inline JSON, collection ID, or - for stdin')
-  .option('--human', 'Output human-readable text instead of JSON')
+  .description('Review a transaction or collection for issues via reviewCollection(). Input: JSON file, inline JSON, collection ID, or - for stdin')
+  .option('--json', 'Output the full ReviewResult as JSON')
+  .option('--human', 'Force human-readable text output (default)')
+  .option('--strict', 'Exit 1 on warnings (critical always exits 2)')
   .option('--testnet', 'Use testnet API URL')
   .option('--local', 'Use local API URL (http://localhost:3001)')
   .option('--url <url>', 'Custom API base URL')
   .option('--output-file <path>', 'Write output to file instead of stdout')
-  .action(async (input: string, opts: { human?: boolean; testnet?: boolean; local?: boolean; url?: string; outputFile?: string }) => {
+  .action(async (input: string, opts: { json?: boolean; human?: boolean; strict?: boolean; testnet?: boolean; local?: boolean; url?: string; outputFile?: string }) => {
     let data;
     if (/^\d+$/.test(input)) {
-      // Numeric ID — fetch collection from API
       const baseUrl = getApiUrl(opts);
       const response = await fetch(`${baseUrl}/api/v0/collection/${input}`, {
         headers: { 'x-api-key': process.env.BITBADGES_API_KEY || '' }
@@ -28,62 +29,40 @@ sdkCommand
     } else {
       data = readJsonInput(input);
     }
-    const isTransaction = !!data.messages || !!data.msgs;
-
-    if (isTransaction) {
-      // Try enriched simulate via indexer first
-      const apiKey = process.env.BITBADGES_API_KEY;
-      const apiUrl = getApiUrl(opts);
-
-      if (apiKey) {
-        try {
-          const axios = (await import('axios')).default;
-          const response = await axios.post(`${apiUrl}/api/v0/simulate`, data, {
-            headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' }
-          });
-          output(response.data, opts);
-          return;
-        } catch {
-          // Fall through to local analysis
-        }
-      }
 
-      // Local fallback
-      const { validateTransaction } = await import('../../core/validate.js');
-      const { auditCollection } = await import('../../core/audit.js');
-      const { verifyStandardsCompliance } = await import('../../core/verify-standards.js');
-
-      const validation = validateTransaction(data);
-      const standards = verifyStandardsCompliance(data);
-
-      // Try to extract collection from the first message for audit
-      const msg = data.messages?.[0] || data.msgs?.[0];
-      const value = msg?.value || msg;
-      let audit = null;
-      if (value) {
-        try {
-          audit = auditCollection({ collection: value });
-        } catch {
-          // Collection audit not applicable for this message type
-        }
-      }
+    const { reviewCollection } = await import('../../core/review.js');
+    const result = reviewCollection(data);
 
-      output({ validation, standards, audit }, opts);
+    if (opts.json) {
+      output(result, { ...opts, human: false });
     } else {
-      // Collection review
-      const { auditCollection } = await import('../../core/audit.js');
-      const { verifyStandardsCompliance } = await import('../../core/verify-standards.js');
-
-      const audit = auditCollection({ collection: data });
-      let standards = null;
-      try {
-        standards = verifyStandardsCompliance(data);
-      } catch {
-        // Standards check may not apply to raw collections
+      // Human format — grouped by severity
+      const lines: string[] = [];
+      const byLevel: Record<string, typeof result.findings> = { critical: [], warning: [], info: [] };
+      for (const f of result.findings) byLevel[f.severity].push(f);
+      for (const level of ['critical', 'warning', 'info'] as const) {
+        for (const f of byLevel[level]) {
+          lines.push(`[${level.toUpperCase()}] ${f.code} — ${f.title.en}`);
+          if (f.detail.en) lines.push(`  ${f.detail.en}`);
+          if (f.recommendation.en) lines.push(`  -> ${f.recommendation.en}`);
+        }
+      }
+      lines.push('');
+      lines.push(
+        `Summary: ${result.summary.critical} critical, ${result.summary.warning} warning, ${result.summary.info} info — verdict: ${result.summary.verdict}`
+      );
+      const text = lines.join('\n');
+      if (opts.outputFile) {
+        const fs = await import('fs');
+        fs.writeFileSync(opts.outputFile, text + '\n', 'utf-8');
+        process.stderr.write(`Written to ${opts.outputFile}\n`);
+      } else {
+        console.log(text);
       }
-
-      output({ audit, standards }, opts);
     }
+
+    if (result.summary.critical > 0) process.exit(2);
+    if (opts.strict && result.summary.warning > 0) process.exit(1);
   });
 
 // ── sdk interpret-tx <input> ───────────────────────────────────────────────────
@@ -393,8 +372,8 @@ Section Navigation (use slugs from the tree view, separated by /):
   sdk docs messages                     All message type docs
   sdk docs messages/msg-transfer-tokens A specific message
   sdk docs examples                     Code examples and snippets
-  sdk docs mcp-builder-skills           All builder skills (same as "sdk skills")
-  sdk docs mcp-builder-skills/smart-token  A specific skill
+  sdk docs builder-skills               All builder skills (same as "sdk skills")
+  sdk docs builder-skills/smart-token   A specific skill
 
 Partial matching: "sdk docs approvals" finds the first section containing "approvals".
 
@@ -448,15 +427,17 @@ Cache: ~/.bitbadges/docs-cache.json | Refresh: sdk docs --refresh`)
     console.log(out.trim() || `No content found for "${section}".`);
   });
 
-// ── sdk skills (alias for sdk docs mcp-builder-skills) ──────────────────────
+// ── sdk skills (alias for sdk docs builder-skills) ──────────────────────
 
 sdkCommand
   .command('skills [skillId]')
-  .description('Shorthand for "sdk docs mcp-builder-skills" — list or show MCP Builder skills')
-  .addHelpText('after', '\nEquivalent to: sdk docs mcp-builder-skills / sdk docs mcp-builder-skills/<id>')
+  .description('Shorthand for "sdk docs builder-skills" — list or show BitBadges Builder skills')
+  .addHelpText('after', '\nEquivalent to: sdk docs builder-skills / sdk docs builder-skills/<id>')
   .action(async (skillId: string | undefined) => {
-    // Delegate to the docs command logic
-    const section = skillId ? `mcp-builder-skills/${skillId}` : 'mcp-builder-skills';
+    // Delegate to the docs command logic. The slug must exist in the loaded
+    // docs tree — coordinated with bitbadges-docs where this section is
+    // published.
+    const section = skillId ? `builder-skills/${skillId}` : 'builder-skills';
     sdkCommand.commands.find((c) => c.name() === 'docs')!.parseAsync(['node', 'docs', section]);
   });
 
diff --git a/packages/bitbadgesjs-sdk/src/cli/commands/build.ts b/packages/bitbadgesjs-sdk/src/cli/commands/templates.ts
similarity index 51%
rename from packages/bitbadgesjs-sdk/src/cli/commands/build.ts
rename to packages/bitbadgesjs-sdk/src/cli/commands/templates.ts
index 1c5c11ee37..0086645d72 100644
--- a/packages/bitbadgesjs-sdk/src/cli/commands/build.ts
+++ b/packages/bitbadgesjs-sdk/src/cli/commands/templates.ts
@@ -1,61 +1,353 @@
 import { Command } from 'commander';
 import { output, readJsonInput } from '../utils/io.js';
+import {
+  renderReview,
+  renderValidate,
+  renderMetadataPlaceholders,
+  collectMetadataPlaceholders,
+  renderSimulate
+} from '../utils/terminal.js';
+import { isCollectionMsg, normalizeToCreateOrUpdate } from '../utils/normalizeMsg.js';
+import { addNetworkOptions } from '../utils/io.js';
 
-export const buildCommand = new Command('build').description('Template builders — generate MsgUniversalUpdateCollection or user approval JSON');
+export const templatesCommand = new Command('templates').description('Deterministic transaction templates — flag-based generators for vaults, NFTs, subscriptions, bounties, and more.');
 
 // ── Output helper ────────────────────────────────────────────────────────────
 
 
-async function emit(data: any, opts: { condensed?: boolean; outputFile?: string; dryRun?: boolean; explain?: boolean; creator?: string; manager?: string }) {
-  // Apply --creator / --manager overrides to collection msgs
-  if (data.typeUrl?.includes('MsgUniversalUpdateCollection') && data.value) {
+async function emit(
+  data: any,
+  opts: {
+    condensed?: boolean;
+    outputFile?: string;
+    jsonOnly?: boolean;
+    explain?: boolean;
+    creator?: string;
+    manager?: string;
+    name?: string;
+    description?: string;
+    image?: string;
+    simulate?: boolean;
+    events?: boolean;
+    // Network selection — passed through addNetworkOptions on the
+    // shared sharedOpts() helper. Only consulted when --simulate is on.
+    network?: 'mainnet' | 'local' | 'testnet';
+    testnet?: boolean;
+    local?: boolean;
+    url?: string;
+  }
+) {
+  // User-level approval templates produce
+  // `/tokenization.MsgUpdateUserApprovals` and similar — they're not
+  // collection CRUD msgs but they still need the creator / manager
+  // backfill from CLI flags. Detect once and use the flag in two
+  // places below: (a) post-build creator override, (b) gating the
+  // auto-simulate path (we skip simulate for approval-style msgs
+  // because their semantics are state-change-on-existing-collection
+  // with set/append/delete variability — not a single tx the user
+  // wants to dry-run on a fresh chain).
+  const isUserApprovalTx =
+    typeof data?.typeUrl === 'string' &&
+    /\.(MsgUpdateUserApprovals|MsgSetIncomingApproval|MsgSetOutgoingApproval|MsgDeleteIncomingApproval|MsgDeleteOutgoingApproval|MsgPurgeApprovals)$/.test(
+      data.typeUrl
+    );
+
+  // Apply --creator / --manager overrides to collection msgs. Builders emit
+  // MsgUniversalUpdateCollection internally (superset) — the normalization
+  // into MsgCreateCollection / MsgUpdateCollection happens once, at the very
+  // end of emit(), right before we write the JSON out.
+  const isCollectionTx = isCollectionMsg(data);
+  if ((isCollectionTx || isUserApprovalTx) && data.value) {
     if (opts.creator) data.value.creator = opts.creator;
+  }
+  if (isCollectionTx && data.value) {
     if (opts.manager) data.value.manager = opts.manager;
+
+    // Defensive backfill — last-mile safety net for templates that
+    // generate approvals without knowing the creator address.
+    //
+    // (1) `initiatedByListId === ''` → fill in with creator. The chain
+    //     rejects empty list IDs with "initiated by list id is
+    //     uninitialized". Any builder that genuinely wants a permissionless
+    //     list must explicitly set `'All'` — empty string is never valid.
+    //
+    // (2) `coinTransfers[].to === ''` → fill in with creator, BUT only
+    //     when `overrideToWithInitiator !== true`. The override flag tells
+    //     the chain to substitute `to` with the initiator at runtime
+    //     (correct for quest rewards, bounty payouts to claimants, etc.).
+    //     The empty `to` without the override means "refund the creator"
+    //     — typical for deny/expire branches in bounty/crowdfund/etc. where
+    //     the builder couldn't know the creator at build time.
+    const creatorForFallback = data.value.creator;
+    if (Array.isArray(data.value.collectionApprovals) && creatorForFallback) {
+      for (const approval of data.value.collectionApprovals) {
+        if (!approval || typeof approval !== 'object') continue;
+        if (approval.initiatedByListId === '') {
+          approval.initiatedByListId = creatorForFallback;
+        }
+        const cts = approval.approvalCriteria?.coinTransfers;
+        if (Array.isArray(cts)) {
+          for (const ct of cts) {
+            if (ct && ct.to === '' && ct.overrideToWithInitiator !== true) {
+              ct.to = creatorForFallback;
+            }
+          }
+        }
+      }
+    }
   }
 
-  // --dry-run: run verifyStandardsCompliance and print violations
-  if (opts.dryRun && data.typeUrl?.includes('MsgUniversalUpdateCollection')) {
-    const { verifyStandardsCompliance } = await import('../../core/verify-standards.js');
-    const result = verifyStandardsCompliance({ messages: [data] });
-    if (result.valid) {
-      process.stderr.write(`✓ Passes all standard checks (${result.standardsChecked.length} checks run)\n`);
-    } else {
-      process.stderr.write(`✗ ${result.violations.length} violation(s) found:\n`);
-      for (const v of result.violations) {
-        process.stderr.write(`  [${v.standard}] ${v.field}: ${v.message}\n`);
-        if (v.fix) process.stderr.write(`    Fix: ${v.fix}\n`);
+  // Pre-fill the metadataPlaceholders sidecar from the user's --name /
+  // --description / --image flags. Walk every placeholder URI in the tx
+  // and supply the user's content for any URI the template didn't already
+  // populate. Approval URIs derive a name from the approvalId so the
+  // user's "My Vault" doesn't accidentally label every approval as
+  // "My Vault" — they keep their own descriptive default.
+  if (isCollectionTx && (opts.name || opts.description || opts.image)) {
+    const meta = (data.value._meta = data.value._meta || {});
+    const sidecar: Record<string, { name: string; description: string; image: string }> = (meta.metadataPlaceholders =
+      meta.metadataPlaceholders || {});
+    const fallbackName = opts.name || 'Untitled';
+    const fallbackDescription = opts.description || '';
+    const fallbackImage = opts.image || 'ipfs://QmNTpizCkY5tcMpPMf1kkn7Y5YxFQo3oT54A9oKP5ijP9E';
+    const found = collectMetadataPlaceholders(data);
+    for (const p of found) {
+      if (sidecar[p.uri]) continue; // already filled by the template
+      // Approval / alias / wrapper / denom-unit URIs should keep a
+      // descriptive default rooted in their own identifier rather than
+      // the user's collection name.
+      if (p.uri.startsWith('ipfs://METADATA_APPROVAL_')) {
+        const approvalId = p.uri.replace('ipfs://METADATA_APPROVAL_', '');
+        sidecar[p.uri] = {
+          name: approvalId.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()),
+          description: '',
+          image: '' // approval images MUST be empty per the standards
+        };
+        continue;
       }
+      if (p.uri.startsWith('ipfs://METADATA_ALIAS_') || p.uri.startsWith('ipfs://METADATA_WRAPPER_')) {
+        sidecar[p.uri] = {
+          name: `${fallbackName} ${p.uri.startsWith('ipfs://METADATA_ALIAS_') ? 'alias path' : 'wrapper path'}`,
+          description: fallbackDescription,
+          image: fallbackImage
+        };
+        continue;
+      }
+      // Collection / token / anything else gets the user's flag values.
+      sidecar[p.uri] = {
+        name: fallbackName,
+        description: fallbackDescription,
+        image: fallbackImage
+      };
     }
   }
 
-  // --explain: run interpretTransaction and print human-readable summary
-  if (opts.explain && data.typeUrl?.includes('MsgUniversalUpdateCollection')) {
+  // Emit the JSON payload FIRST. Scroll order on an interactive terminal
+  // naturally puts the most recently-written bytes at the bottom, so the
+  // review summary appearing *after* the JSON means the user's final
+  // eyeline lands on the review verdict — the most actionable bit.
+  //
+  // Stdout flushes synchronously for pipes/files and line-buffered for
+  // TTYs, so writing JSON before the stderr review keeps the visible
+  // order stable across both cases.
+  //
+  // We deliberately keep `value._meta.metadataPlaceholders` on the emitted
+  // JSON so that re-reading the file via `bitbadges-cli builder verify` (or
+  // any other downstream tool that walks the same sidecar) preserves the
+  // PROVIDED state. Chain proto serialization drops unknown fields on
+  // `value`, so the `_meta` annotation never reaches the wire — it's
+  // purely a CLI / off-chain pipeline annotation scoped to this specific
+  // msg. Narrow Universal → MsgCreateCollection / MsgUpdateCollection
+  // right at the write boundary. Agents and humans see the proto's real
+  // per-intent message type; only legacy internal tooling sees the
+  // Universal superset. The `value._meta.metadataPlaceholders` sidecar is
+  // preserved — it rides on the same msg.value and the chain strips
+  // unknown fields on serialization.
+  const outData = isCollectionTx ? normalizeToCreateOrUpdate(data) : data;
+  output(outData, { condensed: opts.condensed, outputFile: opts.outputFile });
+
+  // --explain: run interpretTransaction and print human-readable summary.
+  // Printed to stderr so it doesn't pollute the JSON pipe; shown above the
+  // auto-review so the narrative ("what this tx does") precedes the
+  // critique ("what might be wrong with it").
+  if (opts.explain && isCollectionTx) {
     const { interpretTransaction } = await import('../../core/interpret-transaction.js');
     const explanation = interpretTransaction(data.value);
     process.stderr.write('\n── Explanation ──\n' + explanation + '\n');
   }
 
-  // Strip _meta before output — it's informational, not part of the msg
-  const { _meta, ...cleanData } = data;
-  output(cleanData, { condensed: opts.condensed, outputFile: opts.outputFile });
+  // Auto-review every produced collection tx. Runs both the design-level
+  // `reviewCollection()` checks (audit, standards, UX) and the low-level
+  // structural `validateTransaction()` checks so templates can't silently
+  // produce JSON that the chain would reject. Findings go to stderr so
+  // stdout stays pure JSON for sign/broadcast pipelines; --json-only
+  // suppresses both for callers that want zero stderr noise.
+  //
+  // Auto-validate runs for BOTH collection and user-approval templates
+  // (both produce structurally validatable txs). Auto-review and
+  // metadata + simulate are gated below — review only fires for
+  // collection txs (collection-specific rules), and simulate is
+  // refused for approval-style msgs entirely.
+  if (!opts.jsonOnly && (isCollectionTx || isUserApprovalTx)) {
+    // Static validation FIRST — if the JSON is structurally broken, the
+    // design review below is much less meaningful.
+    try {
+      const { validateTransaction } = await import('../../core/validate.js');
+      const wrapped = { messages: [data] };
+      const vResult = validateTransaction(wrapped);
+      process.stderr.write('\n' + renderValidate(vResult, { stream: process.stderr, title: 'Auto-Validate' }) + '\n');
+    } catch (err) {
+      process.stderr.write(`Validation skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+  }
+
+  if (!opts.jsonOnly && isCollectionTx) {
+    try {
+      const { reviewCollection } = await import('../../core/review.js');
+      // reviewCollection wants either a raw collection or a tx body with
+      // messages[]. Templates emit a single Msg, so wrap it.
+      const result = reviewCollection({ messages: [data] });
+      process.stderr.write('\n' + renderReview(result, { stream: process.stderr, title: 'Auto-Review' }) + '\n');
+    } catch (err) {
+      process.stderr.write(`Review skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+
+    // Metadata To Upload — every placeholder URI on the tx that the
+    // metadata auto-apply flow will later substitute. The user (or a
+    // downstream tool) needs to produce JSON for each of these URIs and
+    // upload it somewhere the chain can resolve before broadcast.
+    try {
+      const placeholders = collectMetadataPlaceholders(data);
+      if (placeholders.length > 0) {
+        process.stderr.write(
+          '\n' +
+            renderMetadataPlaceholders(placeholders, data.value?._meta?.metadataPlaceholders, {
+              stream: process.stderr
+            }) +
+            '\n'
+        );
+      }
+    } catch (err) {
+      process.stderr.write(`Metadata placeholder scan skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+    }
+
+    // Auto-Simulate — opt-in via --simulate. Posts to the BitBadges API's
+    // /api/v0/simulate endpoint via simulateMessages(). Returns gasUsed +
+    // parsed events + per-address net balance changes. Skips gracefully
+    // if no API key is configured rather than hard-failing.
+    //
+    // Honors --network/--local/--testnet/--url so a `templates vault
+    // --simulate --network local` flow lands on the local indexer
+    // automatically.
+    if (opts.simulate) {
+      try {
+        const { getApiUrl, getApiKeyForNetwork } = await import('../utils/io.js');
+        // getApiKeyForNetwork() already does env-var > config fallback,
+        // so we don't need a separate getApiKey() call.
+        const apiKey = getApiKeyForNetwork(opts);
+        if (!apiKey) {
+          process.stderr.write(
+            '\n' +
+              renderSimulate(
+                {
+                  success: false,
+                  error:
+                    'Auto-Simulate skipped — no API key. Set BITBADGES_API_KEY or run `bitbadges-cli config set apiKey <key>`.'
+                },
+                { stream: process.stderr, title: 'Auto-Simulate' }
+              ) +
+              '\n'
+          );
+        } else {
+          const { simulateMessages } = await import('../../builder/tools/queries/simulateTransaction.js');
+          const { prefetchSimulateCollections } = await import('../utils/simulateSymbols.js');
+          const result = await simulateMessages({
+            messages: [data],
+            creatorAddress: opts.creator,
+            apiKey,
+            apiUrl: getApiUrl(opts)
+          });
+          const collectionCache = await prefetchSimulateCollections(result, {
+            apiKey,
+            apiUrl: getApiUrl(opts)
+          });
+          process.stderr.write(
+            '\n' +
+              renderSimulate(result, {
+                stream: process.stderr,
+                title: 'Auto-Simulate',
+                events: opts.events ? 'full' : 'count',
+                collectionCache
+              }) +
+              '\n'
+          );
+        }
+      } catch (err) {
+        process.stderr.write(`Simulation skipped: ${err instanceof Error ? err.message : String(err)}\n`);
+      }
+    }
+  }
+
+  // Approval-template auto-simulate skip — sits OUTSIDE the
+  // collection-only block so it fires even when isCollectionTx is
+  // false. Approval msgs already get the Auto-Validate run above; we
+  // print the skip note once so the user understands why no gas is
+  // shown.
+  if (!opts.jsonOnly && opts.simulate && isUserApprovalTx) {
+    process.stderr.write(
+      '\nAuto-Simulate skipped — wrap user-level approvals inside an alternative approval message to simulate end-to-end. Auto-Validate ran above.\n'
+    );
+  }
+}
+
+// renderValidate, renderMetadataPlaceholders, and collectMetadataPlaceholders
+// live in src/cli/utils/terminal.ts so the standalone `builder verify`
+// command and the templates auto-review path share one implementation.
+
+/**
+ * Add a shared option only if the per-template command hasn't already
+ * declared it. Avoids commander "duplicate flag" errors for templates
+ * (vault, subscription, bounty, …) that already define their own --name
+ * / --description / --image flags. Those template-level flags double as
+ * the metadataPlaceholders content because emit() reads opts.name etc.
+ * directly — no extra plumbing needed.
+ */
+function addOptionIfMissing(cmd: Command, flags: string, description: string): Command {
+  const longFlag = flags.match(/--[a-z][a-z0-9-]*/)?.[0];
+  if (longFlag && (cmd as any)._findOption?.(longFlag)) return cmd;
+  return cmd.option(flags, description);
 }
 
-const sharedOpts = (cmd: Command) =>
+const sharedOpts = (cmd: Command) => {
   cmd
     .option('--condensed', 'Output compact JSON (no whitespace)')
     .option('--output-file <path>', 'Write output to file')
     .option('--json <input>', 'Pass all params as JSON (file, inline, or - for stdin). Overrides individual flags.')
-    .option('--dry-run', 'Validate output against standard checks (violations to stderr)')
-    .option('--explain', 'Print human-readable explanation of the output (to stderr)')
+    .option('--json-only', 'Skip the automatic review — emit pure JSON to stdout with no stderr commentary')
+    .option('--explain', 'Print a human-readable explanation of the output to stderr (in addition to the auto-review)')
     .option('--creator <address>', 'Creator/sender address (bb1... or 0x...)')
-    .option('--manager <address>', 'Collection manager address (bb1...)');
+    .option('--manager <address>', 'Collection manager address (bb1...)')
+    .option('--simulate', 'Also simulate the tx against the BitBadges API and render gas + net changes (requires BITBADGES_API_KEY)')
+    .option('--events', 'When --simulate is set, dump the full raw chain events array (default: just the count)');
+  // Network selection — only the --simulate path actually hits the
+  // API, but we add the flags universally so `templates vault
+  // --simulate --network local` works without parser surprises.
+  addNetworkOptions(cmd);
+  // Metadata flags — only added when the template doesn't already declare
+  // them. Templates that DO declare them keep their own description string;
+  // emit() reads opts.name / description / image regardless.
+  addOptionIfMissing(cmd, '--name <name>', 'Display name written into unfilled metadataPlaceholders entries (collection / tokens / alias paths)');
+  addOptionIfMissing(cmd, '--description <text>', 'Description written into unfilled metadataPlaceholders entries');
+  addOptionIfMissing(cmd, '--image <url>', 'Image URL written into unfilled metadataPlaceholders entries');
+  return cmd;
+};
 
 // ============================================================
 // Collection builders
 // ============================================================
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('vault')
     .description('Create an IBC-backed vault token')
     .requiredOption('--backing-coin <symbol>', 'Backing coin symbol (USDC, BADGE, ATOM, OSMO)')
@@ -77,7 +369,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('subscription')
     .description('Create a recurring subscription collection')
     .requiredOption('--interval <duration>', 'Interval: daily, monthly, annually, or shorthand (30d)')
@@ -103,7 +395,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('bounty')
     .description('Create a bounty escrow collection')
     .requiredOption('--amount <n>', 'Bounty amount (display units)')
@@ -119,7 +411,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('crowdfund')
     .description('Create a crowdfunding collection')
     .requiredOption('--goal <n>', 'Funding goal (display units)')
@@ -130,11 +422,11 @@ sharedOpts(
 ).action(async (opts) => {
   const { buildCrowdfund } = await import('../../core/builders/crowdfund.js');
   if (opts.json) { emit(buildCrowdfund(readJsonInput(opts.json)), opts); return; }
-  emit(buildCrowdfund({ goal: Number(opts.goal), denom: opts.denom, crowdfunder: opts.crowdfunder, deadline: opts.deadline, name: opts.name }), opts);
+  emit(buildCrowdfund({ goal: Number(opts.goal), denom: opts.denom, crowdfunder: opts.crowdfunder, deadline: opts.deadline, name: opts.name, creator: opts.creator }), opts);
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('auction')
     .description('Create an auction collection')
     .option('--bid-deadline <duration>', 'Bidding window', '7d')
@@ -142,14 +434,15 @@ sharedOpts(
     .option('--name <name>', 'Item name', 'Auction')
     .option('--description <text>', 'Item description')
     .option('--image <url>', 'Item image URL')
+    .option('--seller <address>', 'Seller address — only this address can accept the winning bid (defaults to --creator)')
 ).action(async (opts) => {
   const { buildAuction } = await import('../../core/builders/auction.js');
   if (opts.json) { emit(buildAuction(readJsonInput(opts.json)), opts); return; }
-  emit(buildAuction({ bidDeadline: opts.bidDeadline, acceptWindow: opts.acceptWindow, name: opts.name, description: opts.description, image: opts.image }), opts);
+  emit(buildAuction({ bidDeadline: opts.bidDeadline, acceptWindow: opts.acceptWindow, name: opts.name, description: opts.description, image: opts.image, seller: opts.seller, creator: opts.creator }), opts);
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('product-catalog')
     .description('Create a product catalog collection')
     .requiredOption('--products <json>', 'Product array JSON: [{"name","price","denom","maxSupply?","burn?"}]')
@@ -163,11 +456,11 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('prediction-market')
     .description('Create a binary prediction market (YES/NO)')
     .requiredOption('--verifier <address>', 'Market resolver address (bb1...)')
-    .option('--denom <symbol>', 'Payment coin (default: USDC)', 'USDC')
+    .option('--denom <symbol>', 'Payment coin', 'USDC')
     .option('--name <name>', 'Market question', 'Prediction Market')
     .option('--description <text>', 'Market details')
     .option('--image <url>', 'Market image URL')
@@ -178,7 +471,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('smart-account')
     .description('Create an IBC-backed smart account')
     .requiredOption('--backing-coin <symbol>', 'Backing coin (USDC, BADGE, ATOM, OSMO)')
@@ -193,7 +486,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('credit-token')
     .description('Create a credit/prepaid token')
     .requiredOption('--payment-denom <symbol>', 'Payment coin (USDC, BADGE)')
@@ -208,7 +501,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('custom-2fa')
     .description('Create a custom 2FA token')
     .requiredOption('--name <name>', 'Token name')
@@ -223,7 +516,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('quests')
     .description('Create a quest/reward collection')
     .requiredOption('--reward <n>', 'Reward per claim (display units)')
@@ -237,7 +530,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('address-list')
     .description('Create an on-chain address list')
     .requiredOption('--name <name>', 'List name')
@@ -246,7 +539,7 @@ sharedOpts(
 ).action(async (opts) => {
   const { buildAddressList } = await import('../../core/builders/address-list.js');
   if (opts.json) { emit(buildAddressList(readJsonInput(opts.json)), opts); return; }
-  emit(buildAddressList({ name: opts.name, image: opts.image, description: opts.description, manager: opts.manager }), opts);
+  emit(buildAddressList({ name: opts.name, image: opts.image, description: opts.description, manager: opts.manager, creator: opts.creator }), opts);
 });
 
 // ============================================================
@@ -254,7 +547,7 @@ sharedOpts(
 // ============================================================
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('intent')
     .description('Create an OTC swap intent (user outgoing approval)')
     .requiredOption('--address <address>', 'Creator address (bb1...)')
@@ -271,7 +564,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('recurring-payment')
     .description('Create a recurring payment approval (user incoming)')
     .requiredOption('--collection-id <id>', 'Subscription collection ID')
@@ -287,7 +580,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('listing')
     .description('Create a marketplace listing (user outgoing approval)')
     .requiredOption('--address <address>', 'Seller address (bb1...)')
@@ -304,7 +597,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('bid')
     .description('Create a marketplace bid (user incoming approval)')
     .requiredOption('--address <address>', 'Bidder address (bb1...)')
@@ -320,7 +613,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('pm-sell-intent')
     .description('Create a prediction market sell intent (user outgoing approval)')
     .requiredOption('--address <address>', 'Seller address (bb1...)')
@@ -337,7 +630,7 @@ sharedOpts(
 });
 
 sharedOpts(
-  buildCommand
+  templatesCommand
     .command('pm-buy-intent')
     .description('Create a prediction market buy intent (user incoming approval)')
     .requiredOption('--address <address>', 'Buyer address (bb1...)')
diff --git a/packages/bitbadgesjs-sdk/src/cli/index.ts b/packages/bitbadgesjs-sdk/src/cli/index.ts
index 19350a52d1..874692b498 100644
--- a/packages/bitbadgesjs-sdk/src/cli/index.ts
+++ b/packages/bitbadgesjs-sdk/src/cli/index.ts
@@ -3,7 +3,6 @@ import { Command } from 'commander';
 import { sdkCommand } from './commands/sdk.js';
 import { createApiCommand } from './commands/api.js';
 import { configCommand } from './commands/config.js';
-import { buildCommand } from './commands/build.js';
 import { builderCommand } from './commands/builder.js';
 
 const program = new Command();
@@ -19,7 +18,6 @@ program.option('--help-json', 'Output all commands as structured JSON (for LLMs)
 program.addCommand(sdkCommand);
 program.addCommand(createApiCommand());
 program.addCommand(configCommand);
-program.addCommand(buildCommand);
 program.addCommand(builderCommand);
 
 // ── completion command ───────────────────────────────────────────────────────
diff --git a/packages/bitbadgesjs-sdk/src/cli/utils/io.ts b/packages/bitbadgesjs-sdk/src/cli/utils/io.ts
index 226cce041a..745fb8a899 100644
--- a/packages/bitbadgesjs-sdk/src/cli/utils/io.ts
+++ b/packages/bitbadgesjs-sdk/src/cli/utils/io.ts
@@ -1,5 +1,6 @@
 import * as fs from 'fs';
-import { getConfigBaseUrl } from './config.js';
+import type { Command } from 'commander';
+import { getConfigBaseUrl, getConfigApiKey } from './config.js';
 
 /**
  * Read JSON input from multiple sources:
@@ -82,24 +83,68 @@ function formatHuman(obj: any, indent = 0): string {
   return String(obj);
 }
 
+/**
+ * Network shorthand for `--network mainnet|local|testnet`. Maps to the
+ * equivalent legacy boolean flag so existing flow inside `getApiUrl()`
+ * keeps working without branching.
+ */
+export type NetworkName = 'mainnet' | 'local' | 'testnet';
+
+export interface NetworkOptions {
+  /** Long-form network selector — `mainnet` | `local` | `testnet`. */
+  network?: NetworkName;
+  /** Legacy boolean shorthand. Equivalent to `--network testnet`. */
+  testnet?: boolean;
+  /** Legacy boolean shorthand. Equivalent to `--network local`. */
+  local?: boolean;
+  /** Custom API base URL — overrides every other selector. */
+  url?: string;
+}
+
+/**
+ * Resolve a network name from a mix of long-form and legacy flags.
+ * `--url` always wins; otherwise `--network` > `--local` > `--testnet`
+ * > env > config > mainnet default.
+ */
+export function resolveNetwork(options: NetworkOptions): NetworkName {
+  if (options.network) return options.network;
+  if (options.local) return 'local';
+  if (options.testnet) return 'testnet';
+  return 'mainnet';
+}
+
 /**
  * Resolve the API URL from CLI flags and environment variables.
  *
- * Priority: --url > --local > --testnet > BITBADGES_API_URL env > default production URL.
+ * Priority order (top wins):
+ *   1. `--url <url>` — explicit CLI override, applies regardless of network.
+ *   2. `BITBADGES_API_URL` env var — applies regardless of network.
+ *      Setting this lets you point the CLI at a private proxy / staging
+ *      indexer without having to invent a new `--network` value.
+ *   3. `--network local` → `http://localhost:3001`
+ *   4. `--network testnet` → `https://api.testnet.bitbadges.io`
+ *   5. Config file (`~/.bitbadges/config.json` `url` field).
+ *   6. Default production URL `https://api.bitbadges.io`.
+ *
+ * Note: the env var was previously only consulted for the mainnet branch,
+ * which silently ignored `BITBADGES_API_URL=http://my-proxy` when the
+ * caller passed `--network local`. The env var is now honored at all
+ * networks so a single shell-level export reaches every command.
  */
-export function getApiUrl(options: { testnet?: boolean; local?: boolean; url?: string }): string {
+export function getApiUrl(options: NetworkOptions): string {
   if (options.url) {
     return options.url;
   }
-  if (options.local) {
+  if (process.env.BITBADGES_API_URL) {
+    return process.env.BITBADGES_API_URL;
+  }
+  const network = resolveNetwork(options);
+  if (network === 'local') {
     return 'http://localhost:3001';
   }
-  if (options.testnet) {
+  if (network === 'testnet') {
     return 'https://api.testnet.bitbadges.io';
   }
-  if (process.env.BITBADGES_API_URL) {
-    return process.env.BITBADGES_API_URL;
-  }
   const configUrl = getConfigBaseUrl();
   if (configUrl) {
     // Config base URL includes /api/v0 suffix; strip it for getApiUrl callers
@@ -107,3 +152,33 @@ export function getApiUrl(options: { testnet?: boolean; local?: boolean; url?: s
   }
   return 'https://api.bitbadges.io';
 }
+
+/**
+ * Resolve the API key for a given network. Priority: env var (BITBADGES_API_KEY)
+ * > network-scoped config key (apiKeyTestnet / apiKeyLocal) > default
+ * config apiKey. Mirrors `getApiUrl()`'s priority so a single
+ * `--network local` flag picks up both the local URL AND any local apiKey
+ * the user has stashed via `bitbadges-cli config set apiKeyLocal <key>`.
+ */
+export function getApiKeyForNetwork(options: NetworkOptions): string | undefined {
+  const envKey = process.env.BITBADGES_API_KEY;
+  if (envKey) return envKey;
+  return getConfigApiKey(resolveNetwork(options));
+}
+
+/**
+ * Add the four network-selection options to a Command in one call.
+ * Use this on every CLI command that makes an external API call so the
+ * flag surface stays consistent: `--network`, `--testnet`, `--local`,
+ * and `--url` all do the same job, with `--url` as the manual override.
+ */
+export function addNetworkOptions(cmd: Command): Command {
+  return cmd
+    .option(
+      '--network <name>',
+      'Network: mainnet | testnet | local. Picks the matching API base URL and config apiKey.'
+    )
+    .option('--testnet', 'Shortcut for --network testnet')
+    .option('--local', 'Shortcut for --network local (http://localhost:3001)')
+    .option('--url <url>', 'Custom API base URL (overrides --network)');
+}
diff --git a/packages/bitbadgesjs-sdk/src/cli/utils/normalizeMsg.spec.ts b/packages/bitbadgesjs-sdk/src/cli/utils/normalizeMsg.spec.ts
new file mode 100644
index 0000000000..83bfb1784f
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/cli/utils/normalizeMsg.spec.ts
@@ -0,0 +1,281 @@
+/**
+ * Tests for the Universal → Create/Update narrowing helpers.
+ *
+ * Rules under test (locked against `proto/tokenization/tx.proto`):
+ *   - Create: no `collectionId`, no `updateXxxTimeline` flags, keeps
+ *     `defaultBalances` + `invariants`.
+ *   - Update: requires non-zero `collectionId` + flags, must not set
+ *     `defaultBalances` or `invariants`.
+ *   - Universal: superset — passes through unchanged when it's already
+ *     wearing the Universal typeUrl.
+ */
+
+import {
+  isCollectionMsg,
+  normalizeToCreateOrUpdate,
+  coerceToUniversal,
+  normalizeTxMessages
+} from './normalizeMsg.js';
+
+const UNIVERSAL = '/tokenization.MsgUniversalUpdateCollection';
+const CREATE = '/tokenization.MsgCreateCollection';
+const UPDATE = '/tokenization.MsgUpdateCollection';
+const TRANSFER = '/tokenization.MsgTransferTokens';
+
+const UPDATE_FLAGS = [
+  'updateValidTokenIds',
+  'updateCollectionPermissions',
+  'updateManager',
+  'updateCollectionMetadata',
+  'updateTokenMetadata',
+  'updateCustomData',
+  'updateCollectionApprovals',
+  'updateStandards',
+  'updateIsArchived'
+];
+
+describe('isCollectionMsg', () => {
+  it('returns true for all three collection msg typeUrls', () => {
+    expect(isCollectionMsg({ typeUrl: UNIVERSAL })).toBe(true);
+    expect(isCollectionMsg({ typeUrl: CREATE })).toBe(true);
+    expect(isCollectionMsg({ typeUrl: UPDATE })).toBe(true);
+  });
+
+  it('returns false for non-collection msgs', () => {
+    expect(isCollectionMsg({ typeUrl: TRANSFER })).toBe(false);
+    expect(isCollectionMsg({ typeUrl: '/cosmos.bank.v1beta1.MsgSend' })).toBe(false);
+  });
+
+  it('returns false for malformed input', () => {
+    expect(isCollectionMsg(null)).toBe(false);
+    expect(isCollectionMsg(undefined)).toBe(false);
+    expect(isCollectionMsg({})).toBe(false);
+    expect(isCollectionMsg({ typeUrl: null })).toBe(false);
+    expect(isCollectionMsg({ typeUrl: 42 })).toBe(false);
+  });
+
+  it('matches non-slash-prefixed typeUrls that end with the collection suffix', () => {
+    // Amino / @type style sometimes drops the leading slash.
+    expect(isCollectionMsg({ typeUrl: 'tokenization.MsgCreateCollection' })).toBe(true);
+    expect(isCollectionMsg({ typeUrl: 'tokenization.MsgUpdateCollection' })).toBe(true);
+  });
+
+  it('REJECTS foreign-module typeUrls that share the suffix (security regression)', () => {
+    // Caught in round 4 sweep. Without the namespace check, ANY module
+    // with a MsgCreateCollection / MsgUpdateCollection / MsgUniversalUpdateCollection
+    // would silently get rewritten as a tokenization message.
+    expect(isCollectionMsg({ typeUrl: '/myext.MsgCreateCollection' })).toBe(false);
+    expect(isCollectionMsg({ typeUrl: '/somethingelse.MsgUpdateCollection' })).toBe(false);
+    expect(isCollectionMsg({ typeUrl: '/totally.fake.MsgUniversalUpdateCollection' })).toBe(false);
+  });
+
+  it('trims whitespace before matching (stdin-pipe regression)', () => {
+    // Caught in round 4 sweep. JSON files with trailing newlines or
+    // stdin pipes leave whitespace on string fields; without trimming
+    // the whole coercion path was silently bypassed.
+    expect(isCollectionMsg({ typeUrl: ' /tokenization.MsgCreateCollection ' })).toBe(true);
+    expect(isCollectionMsg({ typeUrl: '/tokenization.MsgCreateCollection\n' })).toBe(true);
+    expect(isCollectionMsg({ typeUrl: '\t/tokenization.MsgUpdateCollection' })).toBe(true);
+  });
+});
+
+describe('normalizeToCreateOrUpdate', () => {
+  const baseUniversalValue = () => ({
+    creator: 'bb1abc',
+    collectionId: '0',
+    defaultBalances: { autoApproveAllIncomingTransfers: true },
+    invariants: { maxSupplyPerId: '1' },
+    updateValidTokenIds: true,
+    validTokenIds: [{ start: '1', end: '1' }],
+    updateCollectionPermissions: true,
+    collectionPermissions: {},
+    updateManager: true,
+    manager: 'bb1abc',
+    updateCollectionMetadata: true,
+    collectionMetadata: { uri: 'ipfs://METADATA_COLLECTION', customData: '' },
+    updateTokenMetadata: true,
+    tokenMetadata: [],
+    updateCustomData: false,
+    customData: '',
+    updateCollectionApprovals: true,
+    collectionApprovals: [],
+    updateStandards: true,
+    standards: [],
+    updateIsArchived: false,
+    isArchived: false
+  });
+
+  it('collectionId=="0" narrows to MsgCreateCollection and strips flags + collectionId', () => {
+    const msg = { typeUrl: UNIVERSAL, value: baseUniversalValue() };
+    const out = normalizeToCreateOrUpdate(msg);
+
+    expect(out.typeUrl).toBe(CREATE);
+    expect(out.value.collectionId).toBeUndefined();
+    for (const flag of UPDATE_FLAGS) {
+      expect(out.value).not.toHaveProperty(flag);
+    }
+    // Keeps defaultBalances + invariants (create-only fields).
+    expect(out.value.defaultBalances).toEqual({ autoApproveAllIncomingTransfers: true });
+    expect(out.value.invariants).toEqual({ maxSupplyPerId: '1' });
+    // Preserves the rest.
+    expect(out.value.creator).toBe('bb1abc');
+    expect(out.value.collectionMetadata.uri).toBe('ipfs://METADATA_COLLECTION');
+  });
+
+  it('missing collectionId is treated as a new collection (Create)', () => {
+    const value = baseUniversalValue();
+    delete (value as any).collectionId;
+    const out = normalizeToCreateOrUpdate({ typeUrl: UNIVERSAL, value });
+    expect(out.typeUrl).toBe(CREATE);
+  });
+
+  it('non-zero collectionId narrows to MsgUpdateCollection and strips defaultBalances + invariants', () => {
+    const value = { ...baseUniversalValue(), collectionId: '42' };
+    const out = normalizeToCreateOrUpdate({ typeUrl: UNIVERSAL, value });
+
+    expect(out.typeUrl).toBe(UPDATE);
+    expect(out.value.collectionId).toBe('42');
+    // Update must not carry these.
+    expect(out.value.defaultBalances).toBeUndefined();
+    expect(out.value.invariants).toBeUndefined();
+    // Flags preserved so the chain knows what to mutate.
+    expect(out.value.updateValidTokenIds).toBe(true);
+    expect(out.value.updateCollectionMetadata).toBe(true);
+  });
+
+  it('does not mutate the input object', () => {
+    const msg = { typeUrl: UNIVERSAL, value: baseUniversalValue() };
+    const snapshot = JSON.stringify(msg);
+    normalizeToCreateOrUpdate(msg);
+    expect(JSON.stringify(msg)).toBe(snapshot);
+  });
+
+  it('passes Create and Update msgs through unchanged', () => {
+    const create = { typeUrl: CREATE, value: { creator: 'bb1abc' } };
+    const update = { typeUrl: UPDATE, value: { creator: 'bb1abc', collectionId: '5' } };
+    expect(normalizeToCreateOrUpdate(create)).toEqual(create);
+    expect(normalizeToCreateOrUpdate(update)).toEqual(update);
+  });
+
+  it('leaves non-collection msgs untouched', () => {
+    const transfer = { typeUrl: TRANSFER, value: { creator: 'bb1abc', transfers: [] } };
+    expect(normalizeToCreateOrUpdate(transfer)).toEqual(transfer);
+  });
+
+  it('handles null / undefined / non-object gracefully', () => {
+    expect(normalizeToCreateOrUpdate(null)).toBe(null);
+    expect(normalizeToCreateOrUpdate(undefined)).toBe(undefined);
+    expect(normalizeToCreateOrUpdate('string' as any)).toBe('string');
+  });
+
+  it('treats empty-string and whitespace collectionId as new (Create)', () => {
+    // Round 4 regression: '' and '  0  ' used to fall into the Update
+    // branch, producing a useless `collectionId: ''` that the chain
+    // would reject with a confusing error.
+    const base = {
+      typeUrl: UNIVERSAL,
+      value: { creator: 'bb1abc', collectionId: '', defaultBalances: { x: 1 } }
+    };
+    expect(normalizeToCreateOrUpdate(base).typeUrl).toBe(CREATE);
+
+    const ws = {
+      typeUrl: UNIVERSAL,
+      value: { creator: 'bb1abc', collectionId: '   0   ', defaultBalances: { x: 1 } }
+    };
+    expect(normalizeToCreateOrUpdate(ws).typeUrl).toBe(CREATE);
+  });
+
+  it('coerces numeric collectionId to string and routes correctly', () => {
+    // Round 4 regression: number 0 was treated as Update, number 5 was
+    // emitted as a number (downstream proto encoders expect strings).
+    const newColl = { typeUrl: UNIVERSAL, value: { creator: 'bb1abc', collectionId: 0, defaultBalances: { x: 1 } } };
+    expect(normalizeToCreateOrUpdate(newColl).typeUrl).toBe(CREATE);
+
+    const existing = { typeUrl: UNIVERSAL, value: { creator: 'bb1abc', collectionId: 5 } };
+    const out = normalizeToCreateOrUpdate(existing);
+    expect(out.typeUrl).toBe(UPDATE);
+    expect(out.value.collectionId).toBe('5');
+    expect(typeof out.value.collectionId).toBe('string');
+  });
+
+  it('REJECTS foreign-module Universal typeUrls (security regression)', () => {
+    const foreign = {
+      typeUrl: '/myext.MsgUniversalUpdateCollection',
+      value: { creator: 'bb1abc', collectionId: '0' }
+    };
+    // Should pass through unchanged (not normalize foreign messages).
+    expect(normalizeToCreateOrUpdate(foreign).typeUrl).toBe('/myext.MsgUniversalUpdateCollection');
+  });
+});
+
+describe('coerceToUniversal', () => {
+  it('Create → Universal fills in collectionId="0" and sets every update flag to true', () => {
+    const create = {
+      typeUrl: CREATE,
+      value: { creator: 'bb1abc', defaultBalances: { autoApproveAllIncomingTransfers: true } }
+    };
+    const out = coerceToUniversal(create);
+    expect(out.typeUrl).toBe(UNIVERSAL);
+    expect(out.value.collectionId).toBe('0');
+    for (const flag of UPDATE_FLAGS) {
+      expect(out.value[flag]).toBe(true);
+    }
+    expect(out.value.defaultBalances).toEqual({ autoApproveAllIncomingTransfers: true });
+  });
+
+  it('Update → Universal rewrites typeUrl but preserves fields', () => {
+    const update = {
+      typeUrl: UPDATE,
+      value: {
+        creator: 'bb1abc',
+        collectionId: '42',
+        updateManager: true,
+        manager: 'bb1new'
+      }
+    };
+    const out = coerceToUniversal(update);
+    expect(out.typeUrl).toBe(UNIVERSAL);
+    expect(out.value.collectionId).toBe('42');
+    expect(out.value.manager).toBe('bb1new');
+  });
+
+  it('Universal → Universal is a no-op', () => {
+    const msg = { typeUrl: UNIVERSAL, value: { creator: 'bb1abc', collectionId: '0' } };
+    expect(coerceToUniversal(msg).typeUrl).toBe(UNIVERSAL);
+  });
+
+  it('leaves non-collection msgs alone', () => {
+    const transfer = { typeUrl: TRANSFER, value: {} };
+    expect(coerceToUniversal(transfer)).toEqual(transfer);
+  });
+});
+
+describe('normalizeTxMessages', () => {
+  it('normalizes every collection msg in a tx body, leaves transfers alone', () => {
+    const tx = {
+      messages: [
+        { typeUrl: UNIVERSAL, value: { creator: 'bb1abc', collectionId: '0', defaultBalances: {} } },
+        { typeUrl: TRANSFER, value: { creator: 'bb1abc', transfers: [] } }
+      ]
+    };
+    const out = normalizeTxMessages(tx);
+    expect(out.messages[0].typeUrl).toBe(CREATE);
+    expect(out.messages[1].typeUrl).toBe(TRANSFER);
+  });
+
+  it('handles [Create, Transfer, Transfer] auto-mint shape — Create untouched, transfers untouched', () => {
+    const tx = {
+      messages: [
+        { typeUrl: CREATE, value: { creator: 'bb1abc' } },
+        { typeUrl: TRANSFER, value: { creator: 'bb1abc', transfers: [] } },
+        { typeUrl: TRANSFER, value: { creator: 'bb1abc', transfers: [] } }
+      ]
+    };
+    const out = normalizeTxMessages(tx);
+    expect(out.messages.map((m: any) => m.typeUrl)).toEqual([CREATE, TRANSFER, TRANSFER]);
+  });
+
+  it('returns tx unchanged if messages array is missing', () => {
+    expect(normalizeTxMessages({} as any)).toEqual({});
+  });
+});
diff --git a/packages/bitbadgesjs-sdk/src/cli/utils/normalizeMsg.ts b/packages/bitbadgesjs-sdk/src/cli/utils/normalizeMsg.ts
new file mode 100644
index 0000000000..006244589c
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/cli/utils/normalizeMsg.ts
@@ -0,0 +1,152 @@
+/**
+ * Collection-msg normalization helpers.
+ *
+ * Internal tooling (templates, validate, audit, interpret, builder sessions)
+ * historically speaks a single superset message type:
+ * `/tokenization.MsgUniversalUpdateCollection`. The chain accepts that form
+ * for legacy reasons but exposes two narrower types in its proto:
+ *
+ *   - `MsgCreateCollection` for new collections — no `collectionId`, no
+ *     `updateXxxTimeline` flags, keeps `defaultBalances` + `invariants`.
+ *   - `MsgUpdateCollection`  for edits — keeps `collectionId` + flags,
+ *     rejects `defaultBalances` + `invariants` (the latter is genesis-only
+ *     per the proto comment, even though the proto field still appears).
+ *
+ * We keep Universal as the in-memory representation everywhere internal (it's
+ * a superset, so every piece of logic naturally covers both cases) and
+ * normalize at the narrow set of agent/user-facing output boundaries:
+ * CLI template stdout, `builder preview` upload, `getTransaction` MCP tool,
+ * indexer session export. Input boundaries accept all three shapes via
+ * `isCollectionMsg` / `coerceToUniversal`.
+ */
+
+export const TYPE_URL_UNIVERSAL = '/tokenization.MsgUniversalUpdateCollection';
+export const TYPE_URL_CREATE = '/tokenization.MsgCreateCollection';
+export const TYPE_URL_UPDATE = '/tokenization.MsgUpdateCollection';
+
+const COLLECTION_TYPE_URLS = new Set([TYPE_URL_UNIVERSAL, TYPE_URL_CREATE, TYPE_URL_UPDATE]);
+
+const UPDATE_FLAGS = [
+  'updateValidTokenIds',
+  'updateCollectionPermissions',
+  'updateManager',
+  'updateCollectionMetadata',
+  'updateTokenMetadata',
+  'updateCustomData',
+  'updateCollectionApprovals',
+  'updateStandards',
+  'updateIsArchived'
+] as const;
+
+/** True if `msg.typeUrl` is any of the three collection create/update msgs.
+ *  Trims whitespace before matching (stdin-piped JSON often has trailing
+ *  newlines) and only accepts typeUrls in the `tokenization` module
+ *  namespace — both proto-style (`/tokenization.MsgX`) and Amino-style
+ *  (`tokenization.MsgX`) — to avoid silently rewriting foreign-module
+ *  messages that happen to end with the same suffix (e.g.
+ *  `/myext.MsgCreateCollection`). */
+export function isCollectionMsg(msg: any): boolean {
+  if (!msg || typeof msg !== 'object') return false;
+  const raw = typeof msg.typeUrl === 'string' ? msg.typeUrl.trim() : '';
+  if (COLLECTION_TYPE_URLS.has(raw)) return true;
+  // Namespace-scoped suffix check. `endsWith('.MsgCreateCollection')`
+  // alone would match any module's MsgCreateCollection; require the
+  // tokenization prefix (with or without leading slash) so we don't
+  // accidentally rewrite cross-module messages into the wrong type.
+  const inTokenizationNs =
+    raw.startsWith('/tokenization.') || raw.startsWith('tokenization.');
+  if (!inTokenizationNs) return false;
+  return (
+    raw.endsWith('.MsgCreateCollection') ||
+    raw.endsWith('.MsgUpdateCollection') ||
+    raw.endsWith('.MsgUniversalUpdateCollection')
+  );
+}
+
+/**
+ * Given a collection msg in any of the three shapes, return a plain Universal
+ * superset shape so internal logic (validate, audit, interpret, review,
+ * frontend auto-apply) doesn't need to branch on typeUrl. Create → fills in
+ * `collectionId = "0"` and sets every `updateXxxTimeline` flag to true
+ * (matches the handler adapter pattern in the indexer). Update → just
+ * rewrites the typeUrl; collectionId + flags are already there. Universal →
+ * returned as-is.
+ */
+export function coerceToUniversal(msg: any): any {
+  if (!isCollectionMsg(msg)) return msg;
+  const t = msg.typeUrl as string;
+  const value = { ...(msg.value || {}) };
+
+  if (t.endsWith('.MsgCreateCollection')) {
+    if (!('collectionId' in value)) value.collectionId = '0';
+    for (const f of UPDATE_FLAGS) value[f] = true;
+  }
+
+  return { ...msg, typeUrl: TYPE_URL_UNIVERSAL, value };
+}
+
+/**
+ * Narrow a Universal-shaped msg into either MsgCreateCollection (new
+ * collection — `collectionId` absent or `"0"`) or MsgUpdateCollection. If
+ * the input is already Create or Update, returned unchanged.
+ *
+ * Field-strip rules (locked against `proto/tokenization/tx.proto`):
+ *   - Create: drops `collectionId` and every `updateXxxTimeline` flag.
+ *     Keeps `defaultBalances` and `invariants` (both create-only).
+ *   - Update: drops `defaultBalances` and `invariants`. Keeps
+ *     `collectionId` + flags so the chain knows what to mutate.
+ */
+export function normalizeToCreateOrUpdate(msg: any): any {
+  if (!msg || typeof msg !== 'object') return msg;
+  // Same trim + namespace-scope as isCollectionMsg, so foreign modules
+  // that happen to end with .MsgUniversalUpdateCollection don't get
+  // rewritten into the tokenization namespace. Accept both proto-style
+  // (`/tokenization.X`) and Amino-style (`tokenization.X`).
+  const t = typeof msg.typeUrl === 'string' ? msg.typeUrl.trim() : '';
+  const inTokenizationNs = t.startsWith('/tokenization.') || t.startsWith('tokenization.');
+  if (!inTokenizationNs || !t.endsWith('.MsgUniversalUpdateCollection')) return msg;
+
+  const value = { ...(msg.value || {}) };
+  // Coerce + trim collectionId so the "is new collection" decision is
+  // robust against:
+  //   - undefined / null               → new
+  //   - '' / '0' / '   0  ' (whitespace) → new
+  //   - 0 (number)                       → new
+  //   - 5 (number)                       → existing (coerce to '5' string
+  //                                       so downstream proto encoders that
+  //                                       expect strings don't barf)
+  const rawId = value.collectionId;
+  let isNew: boolean;
+  if (rawId === undefined || rawId === null) {
+    isNew = true;
+  } else if (typeof rawId === 'string') {
+    const trimmed = rawId.trim();
+    isNew = trimmed === '' || trimmed === '0';
+    if (!isNew) value.collectionId = trimmed;
+  } else if (typeof rawId === 'number') {
+    isNew = rawId === 0;
+    if (!isNew) value.collectionId = String(rawId);
+  } else {
+    // Unknown type — best-effort: don't normalize, leave caller to handle.
+    return msg;
+  }
+
+  if (isNew) {
+    delete value.collectionId;
+    for (const f of UPDATE_FLAGS) delete value[f];
+    return { ...msg, typeUrl: TYPE_URL_CREATE, value };
+  }
+
+  delete value.defaultBalances;
+  delete value.invariants;
+  for (const f of UPDATE_FLAGS) {
+    if (value[f] === undefined) value[f] = true;
+  }
+  return { ...msg, typeUrl: TYPE_URL_UPDATE, value };
+}
+
+/** Apply `normalizeToCreateOrUpdate` to every collection msg in a tx body. */
+export function normalizeTxMessages<T extends { messages?: any[] }>(tx: T): T {
+  if (!tx || !Array.isArray(tx.messages)) return tx;
+  return { ...tx, messages: tx.messages.map((m) => normalizeToCreateOrUpdate(m)) };
+}
diff --git a/packages/bitbadgesjs-sdk/src/cli/utils/simulateSymbols.ts b/packages/bitbadgesjs-sdk/src/cli/utils/simulateSymbols.ts
new file mode 100644
index 0000000000..3d2bf98587
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/cli/utils/simulateSymbols.ts
@@ -0,0 +1,265 @@
+/**
+ * Symbol + alias resolution helpers for the simulate renderer.
+ *
+ * Two jobs:
+ *  1. Map a Cosmos coin denom (`ubadge`, `ibc/…`) → human symbol via
+ *     the SDK `MAINNET_COINS_REGISTRY`. Used to suffix net-change and
+ *     transfer lines with `(BADGE)` / `(ATOM)` / etc.
+ *  2. Given a balance array for a collection, detect whether it
+ *     cleanly maps to one of the collection's `aliasPaths` or
+ *     `cosmosCoinWrapperPaths` — i.e. represents exactly N units of
+ *     that alias's `conversion.sideB` recipe for some positive integer
+ *     N. If so, return the alias symbol.
+ *
+ * Both stages are best-effort: a failed lookup or a non-matching
+ * balance shape just returns null and the renderer prints the raw
+ * denom / raw JSON with no suffix — same behavior as before the
+ * feature existed.
+ *
+ * Only mainnet symbols are registered today; the single
+ * `MAINNET_COINS_REGISTRY` is the source of truth even on testnet/
+ * local because local dev forks mainnet denoms. If a distinct
+ * testnet registry is added later, branch here.
+ */
+
+import { getCoinDetails } from '../../builder/sdk/coinRegistry.js';
+import { getCollections } from '../../builder/sdk/apiClient.js';
+
+export interface CoinSymbolInfo {
+  symbol: string;
+  /** Decimals for the display unit. 0 if unknown / native micro-unit. */
+  decimals: number;
+}
+
+export interface AliasSymbolInfo {
+  symbol: string;
+  /**
+   * Signed count of alias base units encoded by the balance array.
+   * Negative if the underlying balance amounts were negative (e.g. the
+   * Mint side of a net-change). Format with `decimals` to get the
+   * human-readable display amount.
+   */
+  amount: bigint;
+  /** Decimals for the alias's default-display denomUnit. 0 if none set. */
+  decimals: number;
+}
+
+export interface SimulateRenderCollection {
+  aliasPaths?: SimulatePath[];
+  cosmosCoinWrapperPaths?: SimulatePath[];
+}
+
+interface SimulatePath {
+  symbol?: string;
+  denomUnits?: Array<{ symbol?: string; isDefaultDisplay?: boolean; decimals?: string | number }>;
+  conversion?: {
+    sideB?: Array<{
+      amount: string | number | bigint;
+      tokenIds: Array<{ start: string | number | bigint; end: string | number | bigint }>;
+      ownershipTimes: Array<{ start: string | number | bigint; end: string | number | bigint }>;
+    }>;
+  };
+}
+
+/** Loose balance shape — amounts may be strings (post bigintToString) or bigints. */
+interface LooseBalance {
+  amount: string | number | bigint;
+  tokenIds: Array<{ start: string | number | bigint; end: string | number | bigint }>;
+  ownershipTimes: Array<{ start: string | number | bigint; end: string | number | bigint }>;
+}
+
+/**
+ * Look up the human symbol + decimals for a Cosmos coin denom.
+ * Returns null if the denom isn't in the registry. Never throws.
+ */
+export function resolveCoinSymbol(denom: string): CoinSymbolInfo | null {
+  if (!denom) return null;
+  const details = getCoinDetails(denom);
+  if (details?.symbol && details.symbol !== 'UNKNOWN') {
+    const dec = parseInt(details.decimals, 10);
+    return {
+      symbol: details.symbol,
+      decimals: Number.isFinite(dec) && dec > 0 ? dec : 0
+    };
+  }
+  return null;
+}
+
+/**
+ * Format a raw integer amount into a human decimal string. Preserves
+ * every non-zero fractional digit — no rounding — and strips trailing
+ * zeros. `decimals <= 0` falls back to the integer representation.
+ */
+export function formatHumanAmount(raw: bigint, decimals: number): string {
+  if (decimals <= 0) return raw.toString();
+  const negative = raw < 0n;
+  const abs = negative ? -raw : raw;
+  const s = abs.toString();
+  const padded = s.padStart(decimals + 1, '0');
+  const intPart = padded.slice(0, padded.length - decimals);
+  const fracPartRaw = padded.slice(padded.length - decimals);
+  const fracPart = fracPartRaw.replace(/0+$/, '');
+  const out = fracPart ? `${intPart}.${fracPart}` : intPart;
+  return negative ? '-' + out : out;
+}
+
+function toBigIntOrNull(v: unknown): bigint | null {
+  try {
+    if (typeof v === 'bigint') return v;
+    if (typeof v === 'number') return BigInt(v);
+    if (typeof v === 'string' && v.length > 0) return BigInt(v);
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+function rangesEqual(
+  a: Array<{ start: unknown; end: unknown }> | undefined,
+  b: Array<{ start: unknown; end: unknown }> | undefined
+): boolean {
+  if (!a || !b || a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i++) {
+    const as = toBigIntOrNull(a[i].start);
+    const ae = toBigIntOrNull(a[i].end);
+    const bs = toBigIntOrNull(b[i].start);
+    const be = toBigIntOrNull(b[i].end);
+    if (as === null || ae === null || bs === null || be === null) return false;
+    if (as !== bs || ae !== be) return false;
+  }
+  return true;
+}
+
+function pathSymbol(path: SimulatePath): string | null {
+  if (path.symbol) return path.symbol;
+  const display = path.denomUnits?.find((u) => u.isDefaultDisplay)?.symbol;
+  if (display) return display;
+  return path.denomUnits?.[0]?.symbol || null;
+}
+
+function pathDecimals(path: SimulatePath): number {
+  const units = path.denomUnits || [];
+  const display = units.find((u) => u.isDefaultDisplay) || units[0];
+  if (!display?.decimals) return 0;
+  const n = typeof display.decimals === 'number' ? display.decimals : parseInt(display.decimals, 10);
+  return Number.isFinite(n) && n > 0 ? n : 0;
+}
+
+/**
+ * Check whether `balances` cleanly encodes N units of `path.conversion.sideB`
+ * for some integer N. "Cleanly" means:
+ *   - balances.length === sideB.length
+ *   - each balance's tokenIds + ownershipTimes ranges equal the
+ *     corresponding sideB entry exactly
+ *   - every (balance.amount / sideB.amount) ratio is the same integer
+ *     with no remainder, and all entries share the same sign
+ *
+ * Returns the signed ratio N — negative if the balance amounts were
+ * negative (e.g. the Mint side of a net-change).
+ */
+function matchesPath(balances: LooseBalance[], path: SimulatePath): bigint | null {
+  const sideB = path.conversion?.sideB;
+  if (!sideB || sideB.length === 0) return null;
+  if (balances.length !== sideB.length) return null;
+
+  let ratio: bigint | null = null;
+  for (let i = 0; i < sideB.length; i++) {
+    const b = balances[i];
+    const s = sideB[i];
+    if (!rangesEqual(b.tokenIds, s.tokenIds)) return null;
+    if (!rangesEqual(b.ownershipTimes, s.ownershipTimes)) return null;
+
+    const bAmt = toBigIntOrNull(b.amount);
+    const sAmt = toBigIntOrNull(s.amount);
+    if (bAmt === null || sAmt === null || sAmt === 0n) return null;
+
+    // sideB amounts are always positive by construction; preserve sign
+    // from the balance so negative net-change lines render as negative.
+    const negative = bAmt < 0n;
+    const absB = negative ? -bAmt : bAmt;
+    if (absB % sAmt !== 0n) return null;
+    const absRatio = absB / sAmt;
+    if (absRatio === 0n) return null;
+    const thisRatio = negative ? -absRatio : absRatio;
+    if (ratio === null) ratio = thisRatio;
+    else if (ratio !== thisRatio) return null;
+  }
+  return ratio;
+}
+
+/**
+ * Given a balance array and a pre-fetched collection, return the
+ * alias or wrapper-path symbol + signed base-unit amount + decimals
+ * if the balances cleanly map to one. Returns null on any mismatch
+ * (ranges don't align, amounts aren't evenly divisible, etc.) —
+ * callers then render the raw JSON without a suffix.
+ */
+export function detectBalanceAliasSymbol(
+  balances: unknown,
+  collection: SimulateRenderCollection | undefined
+): AliasSymbolInfo | null {
+  if (!collection) return null;
+  if (!Array.isArray(balances) || balances.length === 0) return null;
+  const looseBalances = balances as LooseBalance[];
+
+  const paths: SimulatePath[] = [
+    ...(collection.aliasPaths || []),
+    ...(collection.cosmosCoinWrapperPaths || [])
+  ];
+  for (const path of paths) {
+    const ratio = matchesPath(looseBalances, path);
+    if (ratio === null) continue;
+    const sym = pathSymbol(path);
+    if (!sym) continue;
+    return { symbol: sym, amount: ratio, decimals: pathDecimals(path) };
+  }
+  return null;
+}
+
+/**
+ * Pre-fetch every collection referenced by a simulate result so the
+ * synchronous `renderSimulate()` can do alias lookups without doing
+ * I/O. Errors are swallowed — a missing collection fetch just
+ * degrades the rendered output to "no alias suffix", identical to
+ * pre-feature behavior.
+ */
+export async function prefetchSimulateCollections(
+  result: { netChanges?: any; parsedEvents?: any } | undefined,
+  opts: { apiKey?: string; apiUrl?: string }
+): Promise<Map<string, SimulateRenderCollection>> {
+  const cache = new Map<string, SimulateRenderCollection>();
+  if (!result) return cache;
+
+  const ids = new Set<string>();
+  const badgeChanges = result.netChanges?.badgeChanges || {};
+  for (const addrEntry of Object.values(badgeChanges)) {
+    for (const collectionId of Object.keys(addrEntry as Record<string, unknown>)) {
+      if (collectionId) ids.add(String(collectionId));
+    }
+  }
+  const badgeXfers = result.parsedEvents?.badgeTransferEvents;
+  if (Array.isArray(badgeXfers)) {
+    for (const t of badgeXfers) {
+      if (t?.collectionId != null) ids.add(String(t.collectionId));
+    }
+  }
+  if (ids.size === 0) return cache;
+
+  try {
+    const response = await getCollections(
+      {
+        collectionsToFetch: Array.from(ids).map((collectionId) => ({ collectionId }))
+      },
+      { apiKey: opts.apiKey, apiUrl: opts.apiUrl }
+    );
+    if (response.success && response.data?.collections) {
+      for (const col of response.data.collections) {
+        const id = String((col as any).collectionId);
+        cache.set(id, col as SimulateRenderCollection);
+      }
+    }
+  } catch {
+    // best-effort — leave cache partial or empty
+  }
+  return cache;
+}
diff --git a/packages/bitbadgesjs-sdk/src/cli/utils/terminal.ts b/packages/bitbadgesjs-sdk/src/cli/utils/terminal.ts
new file mode 100644
index 0000000000..61854904dd
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/cli/utils/terminal.ts
@@ -0,0 +1,728 @@
+/**
+ * Tiny terminal-output helpers for CLI commands.
+ *
+ * Responsibilities:
+ *  - TTY detection (only colorize when the stream is actually a terminal)
+ *  - Narrow ANSI colour + style primitives (bold, red, yellow, cyan, green,
+ *    dim) — no external dep so we stay compatible with the SDK's existing
+ *    commonjs / esm dual build
+ *  - A single `renderReview()` function that both `emit()` (templates
+ *    auto-review) and `builder review` call, so output formatting stays in
+ *    lockstep across the `build → review` flow
+ *
+ * We deliberately check the *target* stream each time rather than caching,
+ * because the caller may pass different streams (review to stderr, JSON to
+ * stdout) and redirections can differ per stream. `NO_COLOR` env var
+ * (https://no-color.org) force-disables colour.
+ */
+
+import {
+  resolveCoinSymbol,
+  detectBalanceAliasSymbol,
+  formatHumanAmount,
+  type SimulateRenderCollection
+} from './simulateSymbols.js';
+
+/**
+ * Build the `(…)` suffix for an ICS20 coin line. `rawAmount` is the
+ * signed stringified integer as it appears in the simulate result
+ * (e.g. `"-5000"` or `"+5000"`). Returns an empty string if the
+ * denom isn't in the registry so the render stays a no-op.
+ */
+function coinSuffix(rawAmount: unknown, denom: string, c: (code: any, s: string) => string): string {
+  const info = resolveCoinSymbol(denom);
+  if (!info) return '';
+  let inner = info.symbol;
+  if (info.decimals > 0) {
+    // rawAmount may carry a leading '+' that BigInt() doesn't accept;
+    // strip it first. Any parse failure → plain symbol (no amount).
+    const cleaned = String(rawAmount).replace(/^\+/, '');
+    try {
+      const bi = BigInt(cleaned);
+      inner = `${formatHumanAmount(bi, info.decimals)} ${info.symbol}`;
+    } catch {
+      /* keep inner = symbol */
+    }
+  }
+  return ' ' + c('dim', `(${inner})`);
+}
+
+export type ColorFn = (s: string) => string;
+
+const OPEN: Record<string, string> = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  gray: '\x1b[90m'
+};
+
+/**
+ * Build a colorizer for the given NodeJS.WritableStream. Returns a function
+ * that passes through plain text when colour is disabled.
+ */
+export function makeColor(stream: NodeJS.WriteStream): { c: (code: keyof typeof OPEN, s: string) => string; enabled: boolean } {
+  const enabled =
+    !process.env.NO_COLOR &&
+    process.env.TERM !== 'dumb' &&
+    !!(stream as any).isTTY;
+  return {
+    enabled,
+    c: (code, s) => (enabled ? `${OPEN[code] ?? ''}${s}${OPEN.reset}` : s)
+  };
+}
+
+/**
+ * Colorize the `"amount":"<n>"` field inside a BalanceArray JSON string
+ * in-place — red for negative values, green for positive. Leaves the
+ * rest of the JSON untouched so the structure stays machine-readable.
+ * The regex is deliberately conservative: it only matches a string-
+ * quoted integer value right after the literal key `"amount":`.
+ */
+export function colorizeAmountsInJson(
+  json: string,
+  c: (code: 'red' | 'green', s: string) => string
+): string {
+  return json.replace(/"amount":"(-?\d+)"/g, (_match, amt: string) => {
+    const colored = amt.startsWith('-') ? c('red', amt) : c('green', '+' + amt);
+    return `"amount":"${colored}"`;
+  });
+}
+
+/** Build a horizontal rule filled with `ch` up to `width`, with an optional label. */
+export function rule(ch: string, width: number, label?: string): string {
+  if (!label) return ch.repeat(width);
+  const pre = `${ch}${ch}${ch} ${label} `;
+  const rem = Math.max(3, width - pre.length);
+  return `${pre}${ch.repeat(rem)}`;
+}
+
+
+/**
+ * Render a ReviewResult as terminal-friendly text.
+ *
+ * Parameters are intentionally minimal — the caller decides where to write
+ * (stdout vs stderr, file vs stream) and whether to add a boundary separator
+ * after the review section.
+ *
+ * @returns the formatted string (no trailing newline)
+ */
+export function renderReview(
+  result: {
+    findings: Array<{
+      code: string;
+      severity: 'critical' | 'warning' | 'info';
+      title: { en: string };
+      detail: { en: string };
+      recommendation: { en: string };
+    }>;
+    summary: { critical: number; warning: number; info: number; verdict: string };
+  },
+  opts: { stream: NodeJS.WriteStream; title?: string }
+): string {
+  const { c, enabled } = makeColor(opts.stream);
+  const width = Math.min(80, (opts.stream as any).columns || 80);
+  const title = opts.title || 'Review';
+
+  const lines: string[] = [];
+  lines.push(c('gray', rule('━', width, title)));
+
+  if (result.findings.length === 0) {
+    lines.push('');
+    lines.push(`  ${c('green', '✓')} ${c('bold', 'Clean')} — no findings`);
+    lines.push('');
+  } else {
+    const byLevel: Record<'critical' | 'warning' | 'info', typeof result.findings> = {
+      critical: [],
+      warning: [],
+      info: []
+    };
+    for (const f of result.findings) byLevel[f.severity].push(f);
+
+    const sigil = { critical: '■', warning: '▲', info: '●' } as const;
+    const colorFor = { critical: 'red', warning: 'yellow', info: 'cyan' } as const;
+    const labelFor = { critical: 'CRITICAL', warning: 'WARNING ', info: 'INFO    ' } as const;
+
+    let first = true;
+    for (const level of ['critical', 'warning', 'info'] as const) {
+      for (const f of byLevel[level]) {
+        if (!first) lines.push('');
+        first = false;
+        const badge = `${sigil[level]} ${labelFor[level]}`;
+        lines.push(`  ${c(colorFor[level], c('bold', badge))}  ${c('dim', f.code)}`);
+        for (const textLine of wrap(f.title.en, width - 6)) {
+          lines.push(`      ${c('bold', textLine)}`);
+        }
+        if (f.detail.en) {
+          for (const textLine of wrap(f.detail.en, width - 6)) {
+            lines.push(`      ${textLine}`);
+          }
+        }
+        if (f.recommendation.en) {
+          for (const textLine of wrap(f.recommendation.en, width - 8)) {
+            lines.push(`      ${c('gray', '→')} ${textLine}`);
+          }
+        }
+      }
+    }
+  }
+
+  lines.push('');
+  lines.push(c('gray', rule('━', width)));
+
+  const { critical, warning, info, verdict } = result.summary;
+  const verdictColor: keyof typeof OPEN =
+    verdict === 'pass' ? 'green' : verdict === 'warn' ? 'yellow' : 'red';
+  const summaryParts = [
+    critical > 0 ? c('red', `${critical} critical`) : c('gray', `${critical} critical`),
+    warning > 0 ? c('yellow', `${warning} warning`) : c('gray', `${warning} warning`),
+    info > 0 ? c('cyan', `${info} info`) : c('gray', `${info} info`),
+    `verdict: ${c(verdictColor, c('bold', verdict))}`
+  ];
+  lines.push(`  ${c('bold', 'Summary')}  ${summaryParts.join('  ·  ')}`);
+  lines.push(c('gray', rule('━', width)));
+
+  // Silence unused var warning in strict mode.
+  void enabled;
+
+  return lines.join('\n');
+}
+
+/**
+ * Render a boundary rule announcing that stdout is about to take over with
+ * JSON. Used by the auto-review path so the user sees a clear transition
+ * between the stderr review section and the stdout transaction payload.
+ */
+export function renderJsonBoundary(stream: NodeJS.WriteStream): string {
+  const { c } = makeColor(stream);
+  const width = Math.min(80, (stream as any).columns || 80);
+  return c('gray', rule('━', width, 'Transaction JSON (stdout)'));
+}
+
+/** Wrap plain text to a column width, preserving word boundaries. */
+export function wrap(text: string, width: number): string[] {
+  if (width <= 10) return [text];
+  const words = text.split(/\s+/);
+  const out: string[] = [];
+  let line = '';
+  for (const w of words) {
+    if (!line.length) {
+      line = w;
+      continue;
+    }
+    if (line.length + 1 + w.length > width) {
+      out.push(line);
+      line = w;
+    } else {
+      line += ' ' + w;
+    }
+  }
+  if (line.length) out.push(line);
+  return out;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Validate / Metadata renderers — shared between templates auto-review and
+// the standalone `builder verify` command so output formatting stays in
+// lockstep across the build → verify flow.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ValidationIssueLike {
+  severity: 'error' | 'warning';
+  path?: string;
+  message: string;
+}
+
+export interface ValidationResultLike {
+  valid: boolean;
+  issues: ValidationIssueLike[];
+}
+
+/**
+ * Render a ValidationResult for stderr/stdout. Title defaults to "Validate"
+ * but `emit()` in templates passes "Auto-Validate" to distinguish.
+ */
+export function renderValidate(
+  result: ValidationResultLike,
+  opts?: { stream?: NodeJS.WriteStream; title?: string }
+): string {
+  const stream = opts?.stream || process.stderr;
+  const { c } = makeColor(stream);
+  const width = Math.min(80, (stream as any).columns || 80);
+  const errors = result.issues.filter((i) => i.severity === 'error');
+  const warnings = result.issues.filter((i) => i.severity === 'warning');
+
+  const lines: string[] = [];
+  lines.push(c('gray', rule('━', width, opts?.title || 'Validate')));
+
+  if (result.issues.length === 0) {
+    lines.push('');
+    lines.push(`  ${c('green', '✓')} ${c('bold', 'Clean')} — no structural issues`);
+  } else {
+    lines.push('');
+    for (const issue of result.issues) {
+      const lc = issue.severity === 'error' ? 'red' : 'yellow';
+      const badge = issue.severity === 'error' ? '■ ERROR  ' : '▲ WARNING';
+      lines.push(`  ${c(lc, c('bold', badge))}  ${c('dim', issue.path || '(root)')}`);
+      for (const t of wrap(issue.message, width - 6)) {
+        lines.push(`      ${t}`);
+      }
+    }
+    lines.push('');
+    lines.push(
+      `  ${c('bold', 'Summary')}  ${
+        errors.length > 0 ? c('red', `${errors.length} error`) : c('gray', '0 error')
+      }  ·  ${warnings.length > 0 ? c('yellow', `${warnings.length} warning`) : c('gray', '0 warning')}`
+    );
+  }
+  lines.push(c('gray', rule('━', width)));
+  return lines.join('\n');
+}
+
+export interface MetadataPlaceholderEntry {
+  uri: string;
+  kind: string;
+  location: string;
+  fields: string[];
+}
+
+/**
+ * Walk a transaction body (or full tx with `messages: [...]`) and collect
+ * every `ipfs://METADATA_*` placeholder URI, tagged with what it is and
+ * where it lives. Used by both the templates auto-review and the
+ * standalone `builder verify` command.
+ *
+ * Accepts either a single Msg (`{typeUrl, value: {...}}`), the unwrapped
+ * `value`, or a tx body with `messages[]` — pulls out the first
+ * collection message it finds (MsgCreateCollection, MsgUpdateCollection,
+ * or legacy MsgUniversalUpdateCollection).
+ */
+export function collectMetadataPlaceholders(input: any): MetadataPlaceholderEntry[] {
+  const out: MetadataPlaceholderEntry[] = [];
+  const seen = new Set<string>();
+
+  // Locate the collection value.
+  let value: any = null;
+  if (Array.isArray(input?.messages)) {
+    const isCollection = (t: unknown) =>
+      typeof t === 'string' &&
+      (t.endsWith('.MsgCreateCollection') ||
+        t.endsWith('.MsgUpdateCollection') ||
+        t.endsWith('.MsgUniversalUpdateCollection'));
+    const msg = input.messages.find((m: any) => isCollection(m?.typeUrl)) || input.messages[0];
+    value = msg?.value || msg;
+  } else if (input?.value) {
+    value = input.value;
+  } else {
+    value = input;
+  }
+  if (!value || typeof value !== 'object') return out;
+
+  const isPlaceholder = (uri: unknown): uri is string =>
+    typeof uri === 'string' && /^ipfs:\/\/METADATA_[A-Z]/.test(uri);
+
+  const push = (uri: string, kind: string, location: string, fields: string[]) => {
+    if (seen.has(uri)) return;
+    seen.add(uri);
+    out.push({ uri, kind, location, fields });
+  };
+
+  // Collection metadata
+  if (isPlaceholder(value?.collectionMetadata?.uri)) {
+    push(value.collectionMetadata.uri, 'Collection', 'collectionMetadata.uri', ['name', 'description', 'image']);
+  }
+
+  // Per-token metadata
+  if (Array.isArray(value.tokenMetadata)) {
+    for (let i = 0; i < value.tokenMetadata.length; i++) {
+      const tm = value.tokenMetadata[i];
+      if (isPlaceholder(tm?.uri)) {
+        const ids = Array.isArray(tm.tokenIds) && tm.tokenIds.length > 0
+          ? tm.tokenIds.map((r: any) => `${r.start}-${r.end}`).join(', ')
+          : 'all';
+        push(tm.uri, `Token (ids: ${ids})`, `tokenMetadata[${i}].uri`, ['name', 'description', 'image']);
+      }
+    }
+  }
+
+  // Approval metadata
+  if (Array.isArray(value.collectionApprovals)) {
+    for (let i = 0; i < value.collectionApprovals.length; i++) {
+      const a = value.collectionApprovals[i];
+      if (isPlaceholder(a?.uri)) {
+        push(a.uri, `Approval "${a.approvalId || i}"`, `collectionApprovals[${i}].uri`, [
+          'name',
+          'description',
+          'image (must be "")'
+        ]);
+      }
+    }
+  }
+
+  // Alias path metadata (path level + each denomUnit)
+  if (Array.isArray(value.aliasPathsToAdd)) {
+    for (let i = 0; i < value.aliasPathsToAdd.length; i++) {
+      const ap = value.aliasPathsToAdd[i];
+      if (isPlaceholder(ap?.metadata?.uri)) {
+        push(ap.metadata.uri, `Alias path "${ap.denom || i}"`, `aliasPathsToAdd[${i}].metadata.uri`, [
+          'name',
+          'description',
+          'image'
+        ]);
+      }
+      if (Array.isArray(ap?.denomUnits)) {
+        for (let j = 0; j < ap.denomUnits.length; j++) {
+          const du = ap.denomUnits[j];
+          if (isPlaceholder(du?.metadata?.uri)) {
+            push(
+              du.metadata.uri,
+              `Denom unit "${du.symbol || j}" of ${ap.denom || i}`,
+              `aliasPathsToAdd[${i}].denomUnits[${j}].metadata.uri`,
+              ['name', 'description', 'image']
+            );
+          }
+        }
+      }
+    }
+  }
+
+  // Cosmos wrapper path metadata
+  if (Array.isArray(value.cosmosCoinWrapperPathsToAdd)) {
+    for (let i = 0; i < value.cosmosCoinWrapperPathsToAdd.length; i++) {
+      const wp = value.cosmosCoinWrapperPathsToAdd[i];
+      if (isPlaceholder(wp?.metadata?.uri)) {
+        push(wp.metadata.uri, `Wrapper path "${wp.denom || i}"`, `cosmosCoinWrapperPathsToAdd[${i}].metadata.uri`, [
+          'name',
+          'description',
+          'image'
+        ]);
+      }
+      if (Array.isArray(wp?.denomUnits)) {
+        for (let j = 0; j < wp.denomUnits.length; j++) {
+          const du = wp.denomUnits[j];
+          if (isPlaceholder(du?.metadata?.uri)) {
+            push(
+              du.metadata.uri,
+              `Wrapper denom unit "${du.symbol || j}" of ${wp.denom || i}`,
+              `cosmosCoinWrapperPathsToAdd[${i}].denomUnits[${j}].metadata.uri`,
+              ['name', 'description', 'image']
+            );
+          }
+        }
+      }
+    }
+  }
+
+  return out;
+}
+
+export interface PlaceholderSidecar {
+  [uri: string]: { name?: string; description?: string; image?: string };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Simulate renderer — shared between templates --simulate auto-section and
+// the standalone `builder simulate` command.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface SimulateResultLike {
+  success: boolean;
+  valid?: boolean;
+  gasUsed?: string;
+  parsedEvents?: any;
+  netChanges?: any;
+  /** Raw Cosmos SDK simulation events. Contains approvalChange entries the
+   *  parsedEvents stream doesn't capture — high-value for agents reviewing
+   *  which approvals will exist on the collection after the tx executes. */
+  events?: any[];
+  simulationError?: string;
+  error?: string;
+}
+
+/**
+ * Render a simulation result. Three states:
+ *   - hard error (no API key, network failure, etc.) → red error block
+ *   - valid: false (chain rejected the tx) → red CHAIN-REJECTED block + reason
+ *   - valid: true → green check + gasUsed + per-address net change diff
+ *
+ * @param opts.events When `'full'` (or true), pretty-prints the entire raw
+ *   chain events array under a "Raw events" section. Default `'count'`
+ *   only shows the total event count (much shorter — the full dump is
+ *   typically 2000+ lines for a Create+Mint).
+ */
+export function renderSimulate(
+  result: SimulateResultLike,
+  opts?: {
+    stream?: NodeJS.WriteStream;
+    title?: string;
+    events?: 'count' | 'full' | boolean;
+    /**
+     * Optional pre-fetched collection metadata keyed by collectionId.
+     * Populated by `prefetchSimulateCollections` in the CLI call sites —
+     * used to suffix balance lines with their alias/wrapper symbol when
+     * the balance shape cleanly maps to a path on the collection. When
+     * omitted, balance lines render exactly as before.
+     */
+    collectionCache?: Map<string, SimulateRenderCollection>;
+  }
+): string {
+  const stream = opts?.stream || process.stderr;
+  const { c } = makeColor(stream);
+  const eventMode: 'count' | 'full' =
+    opts?.events === true || opts?.events === 'full' ? 'full' : 'count';
+  const width = Math.min(80, (stream as any).columns || 80);
+  const title = opts?.title || 'Simulate';
+
+  const lines: string[] = [];
+  lines.push(c('gray', rule('━', width, title)));
+  lines.push('');
+
+  if (!result.success) {
+    lines.push(`  ${c('red', '■')} ${c('bold', c('red', 'ERROR    '))}  ${result.error || 'Unknown simulation failure'}`);
+    lines.push('');
+    lines.push(c('gray', rule('━', width)));
+    return lines.join('\n');
+  }
+
+  if (result.valid === false) {
+    lines.push(`  ${c('red', '■')} ${c('bold', c('red', 'REJECTED '))}  ${c('dim', 'chain rejected the tx during simulation')}`);
+    if (result.simulationError) {
+      for (const t of wrap(result.simulationError, width - 6)) {
+        lines.push(`      ${t}`);
+      }
+    }
+    lines.push('');
+    lines.push(c('gray', rule('━', width)));
+    return lines.join('\n');
+  }
+
+  // Valid path — show gas + net changes
+  lines.push(
+    `  ${c('green', '✓')} ${c('bold', c('green', 'VALID    '))}  ${c('dim', 'gas used:')} ${c('bold', result.gasUsed || 'unknown')}`
+  );
+
+  // Net changes summary — coin + badge per address
+  const net: any = result.netChanges || {};
+  const coinChanges: Record<string, Record<string, string>> = net.coinChanges || {};
+  const badgeChanges: Record<string, Record<string, any>> = net.badgeChanges || {};
+  const allAddresses = new Set<string>([...Object.keys(coinChanges), ...Object.keys(badgeChanges)]);
+
+  // Known chain-module addresses — surface them with a human label so a
+  // reader doesn't have to grep the addr set. Covers the Cosmos fee
+  // collector (both bb1 and cosmos prefixes) and our two string-keyed
+  // synthetic buckets populated by calculateNetChanges().
+  const WELL_KNOWN_ADDR_LABELS: Record<string, string> = {
+    bb17xpfvakm2amg962yls6f84z3kell8c5lnytnhv: 'Fee Collector',
+    cosmos17xpfvakm2amg962yls6f84z3kell8c5lserqta: 'Fee Collector',
+    'Network Fee': 'Network Fee',
+    'Protocol Fee': 'Protocol Fee',
+    'IBC Transfer': 'IBC Transfer'
+  };
+
+  if (allAddresses.size > 0) {
+    lines.push('');
+    lines.push(`  ${c('bold', 'Net changes')}`);
+    for (const addr of Array.from(allAddresses).sort()) {
+      const label = WELL_KNOWN_ADDR_LABELS[addr];
+      const display = label ? `${label} (${addr})` : addr;
+      lines.push(`    ${c('dim', display)}`);
+      const coins = coinChanges[addr] || {};
+      for (const [denom, amount] of Object.entries(coins)) {
+        const sign = String(amount).startsWith('-') ? c('red', String(amount)) : c('green', '+' + amount);
+        const suffix = coinSuffix(amount, denom, c);
+        lines.push(`      ${c('dim', '·')} ${sign} ${denom}${suffix}`);
+      }
+      const tokens = badgeChanges[addr] || {};
+      for (const [collectionId, balance] of Object.entries(tokens)) {
+        // Full BalanceArray JSON — agents consume it directly, no
+        // truncation. Colorize the `"amount":"<n>"` field in-place so
+        // a reader can spot the sign at a glance without losing the
+        // raw JSON structure. Injected color escapes don't get wiped
+        // by an outer dim wrapper because we emit the JSON un-dimmed.
+        const json = JSON.stringify(balance);
+        const colorized = colorizeAmountsInJson(json, c);
+        const col = opts?.collectionCache?.get(String(collectionId));
+        const alias = detectBalanceAliasSymbol(balance, col);
+        let suffix = '';
+        if (alias) {
+          const human = formatHumanAmount(alias.amount, alias.decimals);
+          suffix = ' ' + c('dim', `(${human} ${alias.symbol})`);
+        }
+        lines.push(
+          `      ${c('dim', '·')} collection ${collectionId}: ${colorized}${suffix}`
+        );
+      }
+    }
+  } else {
+    lines.push('');
+    lines.push(`  ${c('dim', 'No net balance changes detected.')}`);
+  }
+
+  // ── Approval changes ────────────────────────────────────────────────
+  // The chain emits one `approvalChange` event per approval mutation
+  // (created / updated / deleted). Most useful piece of an agent-facing
+  // simulate output — it tells them exactly which approvals will exist
+  // on the collection after the tx executes, BEFORE they broadcast.
+  // Walked from raw events instead of parsedEvents because
+  // parseSimulationEvents doesn't handle this event type.
+  const events: any[] = Array.isArray(result.events) ? result.events : [];
+  const approvalEvents = events.filter((e) => e?.type === 'approvalChange');
+  if (approvalEvents.length > 0) {
+    lines.push('');
+    lines.push(`  ${c('bold', 'Approval changes')} ${c('dim', `(${approvalEvents.length})`)}`);
+    for (const ev of approvalEvents) {
+      const attrs: Record<string, string> = {};
+      for (const a of ev.attributes || []) attrs[a.key] = a.value;
+      const action = attrs.action || 'changed';
+      const id = attrs.approvalId || '?';
+      const level = attrs.approvalLevel || '?';
+      const collId = attrs.collectionId || '?';
+      const approver = attrs.approverAddress ? ` by ${attrs.approverAddress}` : '';
+      const actionColor: 'green' | 'yellow' | 'red' =
+        action === 'created' ? 'green' : action === 'deleted' ? 'red' : 'yellow';
+      lines.push(
+        `    ${c(actionColor, '●')} ${c('bold', action)} ${c('dim', `[${level}]`)} ${id} ${c('dim', `on collection ${collId}${approver}`)}`
+      );
+    }
+  }
+
+  // ── Parsed transfer events ──────────────────────────────────────────
+  // Individual coin / badge / IBC transfers extracted from raw events.
+  // These complement the per-address Net changes summary by showing
+  // each leg of a multi-hop transfer, so agents can spot unexpected
+  // intermediate hops (e.g. a fee splitter routing through a third
+  // address).
+  const parsed: any = result.parsedEvents || {};
+  const coinXfers: any[] = Array.isArray(parsed.coinTransferEvents) ? parsed.coinTransferEvents : [];
+  const badgeXfers: any[] = Array.isArray(parsed.badgeTransferEvents) ? parsed.badgeTransferEvents : [];
+  const ibcXfers: any[] = Array.isArray(parsed.ibcTransferEvents) ? parsed.ibcTransferEvents : [];
+  const totalXfers = coinXfers.length + badgeXfers.length + ibcXfers.length;
+  if (totalXfers > 0) {
+    lines.push('');
+    lines.push(`  ${c('bold', 'Transfers')} ${c('dim', `(${totalXfers})`)}`);
+    for (const t of coinXfers) {
+      const from = t.from || '';
+      const to = t.to || '';
+      const amtStr = String(t.amount);
+      const amt = amtStr.startsWith('-') ? c('red', amtStr) : c('green', '+' + amtStr);
+      const symSuffix = coinSuffix(amtStr, t.denom, c);
+      lines.push(`    ${c('dim', '→')} ICS20 ${c('bold', amt)} ${t.denom}${symSuffix} ${c('dim', `${from} → ${to}`)}`);
+    }
+    for (const t of badgeXfers) {
+      const from = t.from || '';
+      const to = t.to || '';
+      // Token transfer events carry a `balances` array, NOT a flat
+      // `amount`. Render the raw balances JSON so agents get the full
+      // (amount, tokenIds, ownershipTimes) tuple without lossy
+      // reformatting. Amounts inside the JSON are in-place colorized.
+      const json = Array.isArray(t.balances) ? JSON.stringify(t.balances) : '[]';
+      const colorized = colorizeAmountsInJson(json, c);
+      const col = opts?.collectionCache?.get(String(t.collectionId));
+      const alias = detectBalanceAliasSymbol(t.balances, col);
+      let aliasSuffix = '';
+      if (alias) {
+        const human = formatHumanAmount(alias.amount, alias.decimals);
+        aliasSuffix = ' ' + c('dim', `(${human} ${alias.symbol})`);
+      }
+      lines.push(
+        `    ${c('dim', '→')} token collection ${t.collectionId} ${colorized}${aliasSuffix} ${c('dim', `${from} → ${to}`)}`
+      );
+    }
+    for (const t of ibcXfers) {
+      const amtStr = String(t.amount);
+      const amt = amtStr.startsWith('-') ? c('red', amtStr) : c('green', '+' + amtStr);
+      const symSuffix = coinSuffix(amtStr, t.denom, c);
+      lines.push(`    ${c('dim', '→')} ibc ${c('bold', amt)} ${t.denom}${symSuffix} via ${t.sourceChannel || '?'}`);
+    }
+  }
+
+  // ── Raw events ──────────────────────────────────────────────────────
+  // By default we just print the count (helps sanity-check that the
+  // chain actually executed something — a successful tx with 0 events
+  // almost always means a no-op). With `--events` (eventMode='full'),
+  // pretty-print the entire array. Useful for debugging chain hooks,
+  // approval matchers, IBC flows, etc.
+  if (events.length > 0) {
+    if (eventMode === 'full') {
+      lines.push('');
+      lines.push(`  ${c('bold', 'Raw events')} ${c('dim', `(${events.length})`)}`);
+      // Pretty-print as JSON, indented 4 spaces so it lines up with
+      // the rest of the section. Strip terminal-color ANSI from inside
+      // the JSON if any.
+      const json = JSON.stringify(events, null, 2);
+      for (const line of json.split('\n')) {
+        lines.push(`    ${line}`);
+      }
+    } else {
+      lines.push('');
+      lines.push(`  ${c('dim', `${events.length} chain events emitted total — re-run with --events to dump the full array`)}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(c('gray', rule('━', width)));
+  return lines.join('\n');
+}
+
+/**
+ * Render the Metadata To Upload section. `filled` is a sidecar map (usually
+ * `data.value?._meta?.metadataPlaceholders`) keyed by placeholder URI — entries
+ * present in the map are rendered as PROVIDED, others as NEEDED.
+ */
+export function renderMetadataPlaceholders(
+  placeholders: MetadataPlaceholderEntry[],
+  filled?: PlaceholderSidecar,
+  opts?: { stream?: NodeJS.WriteStream; title?: string }
+): string {
+  const stream = opts?.stream || process.stderr;
+  const { c } = makeColor(stream);
+  const width = Math.min(80, (stream as any).columns || 80);
+
+  const lines: string[] = [];
+  lines.push(c('gray', rule('━', width, opts?.title || 'Metadata To Upload')));
+  lines.push('');
+
+  const totalMissing = placeholders.filter((p) => !filled || !filled[p.uri]).length;
+  const totalProvided = placeholders.length - totalMissing;
+
+  for (const p of placeholders) {
+    const supplied = filled?.[p.uri];
+    const badge = supplied
+      ? `${c('green', '✓')} ${c('bold', c('green', 'PROVIDED '))}`
+      : `${c('yellow', '●')} ${c('bold', c('yellow', 'NEEDED   '))}`;
+    lines.push(`  ${badge}  ${c('dim', p.uri)}`);
+    lines.push(`      ${c('bold', p.kind)} — referenced by ${c('dim', p.location)}`);
+    if (supplied) {
+      const supplyBits: string[] = [];
+      if (supplied.name) supplyBits.push(`name: "${supplied.name}"`);
+      if (supplied.description) supplyBits.push(`description: "${supplied.description}"`);
+      if (supplied.image) supplyBits.push(`image: ${supplied.image}`);
+      if (supplyBits.length) lines.push(`      ${c('gray', '→')} ${supplyBits.join('  ')}`);
+    } else {
+      lines.push(`      ${c('gray', '→')} fields: ${p.fields.join(', ')}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(c('gray', rule('━', width)));
+  const summaryParts = [
+    totalMissing > 0 ? c('yellow', `${totalMissing} needed`) : c('gray', `${totalMissing} needed`),
+    totalProvided > 0 ? c('green', `${totalProvided} provided`) : c('gray', `${totalProvided} provided`)
+  ];
+  lines.push(`  ${c('bold', 'Summary')}  ${summaryParts.join('  ·  ')}`);
+  lines.push(
+    c(
+      'dim',
+      '  Upload each Needed entry as off-chain JSON (name, description, image) and\n' +
+        '  substitute the placeholder URI with the real upload URI before broadcast.'
+    )
+  );
+  lines.push(c('gray', rule('━', width)));
+  return lines.join('\n');
+}
diff --git a/packages/bitbadgesjs-sdk/src/core/auctions.ts b/packages/bitbadgesjs-sdk/src/core/auctions.ts
index c78cfc567b..d9c8c909fa 100644
--- a/packages/bitbadgesjs-sdk/src/core/auctions.ts
+++ b/packages/bitbadgesjs-sdk/src/core/auctions.ts
@@ -20,17 +20,21 @@ export const validateAuctionCollection = (collection: Readonly<iCollectionDoc<bi
     errors.push('validTokenIds must be exactly [{start: 1, end: 1}]');
   }
 
-  // 3. 1-2 approvals (mint-to-winner + optional burn)
+  // 3. 0-2 approvals (mint-to-winner + optional burn). The mint-to-winner
+  // approval uses autoDeletionOptions.afterOneUse, so once the auction
+  // settles it is removed from the collection — a valid post-settlement
+  // state with 0-1 remaining approvals.
   const approvals = collection.collectionApprovals;
-  if (approvals.length === 0 || approvals.length > 2) {
-    errors.push(`Expected 1-2 approvals, found ${approvals.length}`);
+  if (approvals.length > 2) {
+    errors.push(`Expected 0-2 approvals, found ${approvals.length}`);
   }
 
-  // 4. Find mint-to-winner approval
+  // 4. Find mint-to-winner approval. Absence is a valid post-settlement
+  // state (auto-deleted after one use) — skip mint-specific checks rather
+  // than flag a structural error.
   const mintApproval = approvals.find((a) => a.fromListId === 'Mint');
   if (!mintApproval) {
-    errors.push('Missing mint-to-winner approval (fromListId: "Mint")');
-    return { valid: false, errors, warnings };
+    return { valid: errors.length === 0, errors, warnings };
   }
 
   const ac = mintApproval.approvalCriteria;
diff --git a/packages/bitbadgesjs-sdk/src/core/audit.ts b/packages/bitbadgesjs-sdk/src/core/audit.ts
index 59edbe4b3a..ac88430450 100644
--- a/packages/bitbadgesjs-sdk/src/core/audit.ts
+++ b/packages/bitbadgesjs-sdk/src/core/audit.ts
@@ -6,7 +6,9 @@
  * with severity levels so callers can programmatically inspect results.
  */
 
-const MAX_UINT64 = '18446744073709551615';
+import { normalizeForReview } from './review-normalize.js';
+
+const MAX_UINT64 = 18446744073709551615n;
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -22,6 +24,13 @@ export interface AuditFinding {
   title: string;
   detail: string;
   recommendation: string;
+  /**
+   * Hidden from human consumers (frontend sidebar) when true. Used for
+   * findings that just restate permission state ("canUpdateX is NEUTRAL")
+   * — redundant for humans who can already see the permissions tab, but
+   * useful for CLI / indexer / MCP agents who need a flat summary.
+   */
+  agentOnly?: boolean;
 }
 
 /** The complete result returned by {@link auditCollection}. */
@@ -39,8 +48,8 @@ export interface AuditResult {
 // ---------------------------------------------------------------------------
 
 interface UintRange {
-  start: string;
-  end: string;
+  start: bigint;
+  end: bigint;
 }
 
 interface PermissionEntry {
@@ -94,7 +103,10 @@ interface CollectionValue {
 
 function isForever(ranges: UintRange[] | undefined): boolean {
   if (!ranges || ranges.length === 0) return false;
-  return ranges.some((r) => r.start === '1' && r.end === MAX_UINT64);
+  // Tolerate both string and bigint shapes. The SDK builders emit
+  // strings; the frontend collection store uses bigints. Normalizing
+  // via String() catches both uniformly.
+  return ranges.some((r) => r.start === 1n && r.end === MAX_UINT64);
 }
 
 function isForbidden(entries: PermissionEntry[] | undefined): boolean {
@@ -173,7 +185,10 @@ function extractCollection(input: Record<string, unknown>): CollectionValue {
  */
 export function auditCollection(input: { collection: Record<string, unknown>; context?: string }): AuditResult {
   try {
-    const col = extractCollection(input.collection);
+    // normalizeForReview unwraps tx/msg wrappers, mirrors aliasPaths
+    // field names, and converts all numeric fields to bigints via the
+    // Msg class's registered .convert(BigIntify). Idempotent.
+    const col = normalizeForReview(input.collection) as CollectionValue;
     const findings: AuditFinding[] = [];
     const context = (input.context || '').toLowerCase();
 
@@ -185,7 +200,8 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
     // 1. MANAGER & CENTRALIZATION ANALYSIS
     // ========================================
 
-    // 1a. Manager exists
+    // 1a. Manager exists. Tagged agentOnly because the frontend permissions
+    // tab already shows the manager state — this finding just restates it.
     if (col.manager) {
       const managerState = permissionState(perms.canUpdateManager);
       if (managerState === 'NEUTRAL') {
@@ -194,7 +210,8 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
           category: 'centralization',
           title: 'Manager change permission is NEUTRAL',
           detail: `Manager is ${col.manager}. The canUpdateManager permission is neutral, meaning the manager could lock or transfer manager control at any time.`,
-          recommendation: 'Set canUpdateManager to FORBIDDEN to prevent manager address changes, or to PERMITTED if intentional.'
+          recommendation: 'Set canUpdateManager to FORBIDDEN to prevent manager address changes, or to PERMITTED if intentional.',
+          agentOnly: true
         });
       } else if (managerState === 'PERMITTED') {
         findings.push({
@@ -202,7 +219,8 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
           category: 'centralization',
           title: 'Manager can be changed permanently',
           detail: 'canUpdateManager is PERMITTED. The current manager can transfer control to any address at any time.',
-          recommendation: 'This is valid for multi-sig rotation or planned ownership transfer. Otherwise, set to FORBIDDEN.'
+          recommendation: 'This is valid for multi-sig rotation or planned ownership transfer. Otherwise, set to FORBIDDEN.',
+          agentOnly: true
         });
       }
     }
@@ -231,7 +249,9 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
         category: 'centralization',
         title: `${neutralPerms.length} permission(s) are NEUTRAL (undecided)`,
         detail: `Neutral permissions: ${neutralPerms.join(', ')}. These can be changed to forbidden or permitted at any time by the manager.`,
-        recommendation: 'Consider locking permissions you are confident about. Neutral permissions signal uncertainty to users.'
+        recommendation: 'Consider locking permissions you are confident about. Neutral permissions signal uncertainty to users.',
+        // Redundant for humans who see the permissions tab. Agent-only.
+        agentOnly: true
       });
     }
 
@@ -239,7 +259,7 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
     // 2. SUPPLY CONTROL & INFLATION
     // ========================================
 
-    // 2a. canUpdateValidTokenIds
+    // 2a. canUpdateValidTokenIds — agentOnly, see permissions tab note above.
     const validTokenIdState = permissionState(perms.canUpdateValidTokenIds);
     if (validTokenIdState !== 'FORBIDDEN') {
       findings.push({
@@ -247,19 +267,24 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
         category: 'supply',
         title: 'Token ID creation is not locked',
         detail: `canUpdateValidTokenIds is ${validTokenIdState}. The manager can add new token IDs, which creates new supply.`,
-        recommendation: 'Set canUpdateValidTokenIds to FORBIDDEN if supply should be fixed. Even with locked mint approvals, new token IDs = new supply ranges.'
+        recommendation: 'Set canUpdateValidTokenIds to FORBIDDEN if supply should be fixed. Even with locked token-creation approvals, new token IDs create new supply ranges.',
+        agentOnly: true
       });
     }
 
-    // 2b. maxSupplyPerId invariant
-    const maxSupply = invariants.maxSupplyPerId as string | undefined;
-    if (!maxSupply || maxSupply === '0') {
+    // 2b. maxSupplyPerId invariant — only meaningful for NFT collections.
+    // Fungible / credit / address-list / vault collections legitimately
+    // have maxSupplyPerId == 0, so gating on the NFTs standard prevents
+    // false positives for every non-NFT collection.
+    const colStandards: string[] = (col.standards as string[]) || [];
+    const maxSupply = invariants.maxSupplyPerId as bigint | undefined;
+    if (colStandards.includes('NFTs') && (maxSupply === undefined || maxSupply === 0n)) {
       findings.push({
         severity: 'info',
         category: 'supply',
         title: 'No per-token-ID supply cap (maxSupplyPerId = 0)',
         detail: 'maxSupplyPerId is 0 or unset, meaning unlimited tokens can exist per token ID. For NFTs, this should be "1".',
-        recommendation: 'Set maxSupplyPerId to "1" for NFTs, or an appropriate cap for fungible tokens.'
+        recommendation: 'Set maxSupplyPerId to "1" for NFTs.'
       });
     }
 
@@ -267,37 +292,87 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
     // 3. APPROVAL ANALYSIS
     // ========================================
 
-    // 3a. canUpdateCollectionApprovals
+    // 3a. canUpdateCollectionApprovals — analyzed across three flows:
+    //     - mint approvals          (fromListId === 'Mint')       → supply risk if mutable
+    //     - backing mint approvals  (allowBackedMinting === true) → supply risk if mutable
+    //       (smart tokens don't use fromListId 'Mint'; the backing
+    //       address acts as the functional mint source, so mutable
+    //       backing approvals are the same class of unlimited-supply
+    //       risk as a mutable Mint approval)
+    //     - post-mint transfer approvals (everything else)        → transferability risk
+    //
+    // For each flow we ask: is the relevant subset of approvals
+    // mutable? An approval is "mutable" when canUpdateCollectionApprovals
+    // is PERMITTED, or it's NEUTRAL without a scoped forbidden lock
+    // covering that subset.
     const approvalPermState = permissionState(perms.canUpdateCollectionApprovals);
-
-    // Check if it's scoped or blanket
     const approvalPerms = perms.canUpdateCollectionApprovals || [];
     const hasScopedMintLock = approvalPerms.some(
       (p) => (p.fromListId === 'Mint' || p.fromListId === 'All') && isForever(p.permanentlyForbiddenTimes)
     );
+    // Blanket lock: every one of the 8 CollectionApprovalPermission
+    // scope fields is set to its wildcard value AND
+    // permanentlyForbiddenTimes covers forever. Partial locks (e.g.
+    // "Mint scope forbidden forever") don't count — they only freeze
+    // a subset of the approval space. A blanket lock means no approval
+    // can ever be added / removed / modified post-creation, so
+    // transferability is permanently fixed.
+    const hasBlanketLock = approvalPerms.some((p: any) => {
+      if (p.fromListId !== 'All') return false;
+      if (p.toListId !== 'All') return false;
+      if (p.initiatedByListId !== 'All') return false;
+      if (!isForever(p.transferTimes)) return false;
+      if (!isForever(p.tokenIds)) return false;
+      if (p.approvalId !== 'All') return false;
+      if (p.amountTrackerId !== 'All') return false;
+      if (p.challengeTrackerId !== 'All') return false;
+      return isForever(p.permanentlyForbiddenTimes);
+    });
 
-    if (approvalPermState === 'PERMITTED' || (approvalPermState === 'NEUTRAL' && !hasScopedMintLock)) {
-      // Check if there are mint approvals - if so, this is a supply risk
-      const hasMintApproval = approvals.some((a) => a.fromListId === 'Mint');
-      if (hasMintApproval) {
-        findings.push({
-          severity: 'critical',
-          category: 'supply',
-          title: 'Mint approvals can be modified - UNLIMITED SUPPLY RISK',
-          detail: `canUpdateCollectionApprovals is ${approvalPermState} and the collection has mint approvals. The manager can add new mint approvals, change mint limits, or remove restrictions at any time. This effectively means unlimited supply.`,
-          recommendation:
-            'Lock canUpdateCollectionApprovals for mint-related approvals (fromListId: "Mint"). Use scoped approval permissions to lock mint while allowing transfer approval updates if needed.'
-        });
-      }
+    const mintMutable =
+      approvalPermState === 'PERMITTED' || (approvalPermState === 'NEUTRAL' && !hasScopedMintLock);
+    const transferMutable =
+      approvalPermState === 'PERMITTED' || (approvalPermState === 'NEUTRAL' && !hasBlanketLock);
+
+    const hasMintApproval = approvals.some((a) => a.fromListId === 'Mint');
+    const hasBackingApproval2 = approvals.some((a) => {
+      const crit = a.approvalCriteria as Record<string, unknown> | undefined;
+      return !!crit?.allowBackedMinting;
+    });
+    const hasNonMintApproval = approvals.some(
+      (a) => a.fromListId !== 'Mint' && !(a.approvalCriteria as Record<string, unknown>)?.allowBackedMinting
+    );
+
+    if (mintMutable && hasMintApproval) {
+      findings.push({
+        severity: 'critical',
+        category: 'supply',
+        title: 'Mint approvals can be modified — UNLIMITED SUPPLY RISK',
+        detail: `canUpdateCollectionApprovals is ${approvalPermState} and the collection has token-creation (Mint) approvals. The manager can add new creation approvals, change creation limits, or remove restrictions at any time. This effectively means unlimited supply.`,
+        recommendation:
+          'Lock canUpdateCollectionApprovals for mint-related approvals (fromListId: "Mint"). Use scoped approval permissions to lock mint while allowing transfer approval updates if needed.'
+      });
     }
 
-    if (approvalPermState !== 'FORBIDDEN' && !hasScopedMintLock) {
+    if (mintMutable && hasBackingApproval2) {
       findings.push({
-        severity: 'warning',
+        severity: 'critical',
+        category: 'supply',
+        title: 'Backing approvals can be modified — UNLIMITED SUPPLY RISK',
+        detail: `canUpdateCollectionApprovals is ${approvalPermState} and the collection uses IBC backing to create tokens (allowBackedMinting = true). The manager can modify the 1:1 backing conversion, add new backing paths, or change limits at any time, which effectively means unlimited supply risk even though this is not a traditional "Mint" approval.`,
+        recommendation:
+          'Lock canUpdateCollectionApprovals for the backing address scope. Use scoped approval permissions to fix the backing configuration at creation and block future modifications.'
+      });
+    }
+
+    if (transferMutable && hasNonMintApproval) {
+      findings.push({
+        severity: 'critical',
         category: 'transferability',
-        title: 'Transfer rules can be modified',
-        detail: `canUpdateCollectionApprovals is ${approvalPermState}. The manager can add, remove, or modify transfer approvals. This includes adding forceful transfer approvals.`,
-        recommendation: 'If transfer rules should be fixed, set canUpdateCollectionApprovals to FORBIDDEN. For compliance tokens, this may need to stay PERMITTED.'
+        title: 'Post-mint transfer approvals can be modified',
+        detail: `canUpdateCollectionApprovals is ${approvalPermState} and the collection has post-mint transfer approvals. The manager can add, remove, or modify transfer rules at any time. Holders cannot rely on the current transfer rules being stable.`,
+        recommendation:
+          'Permanently lock canUpdateCollectionApprovals if transfer rules should be fixed. For compliance tokens that need ongoing manager control, this may need to stay neutral or permitted — in that case, document the trust assumption.'
       });
     }
 
@@ -311,16 +386,8 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
 
       // --- Mint approval checks ---
       if (fromId === 'Mint') {
-        // Must have overridesFromOutgoingApprovals
-        if (!criteria.overridesFromOutgoingApprovals) {
-          findings.push({
-            severity: 'critical',
-            category: 'approval-bug',
-            title: `Mint approval "${approvalId}" missing overridesFromOutgoingApprovals`,
-            detail: 'Approvals with fromListId: "Mint" MUST have overridesFromOutgoingApprovals: true. Without this, the Mint address cannot send tokens and minting will fail.',
-            recommendation: 'Add overridesFromOutgoingApprovals: true to approvalCriteria.'
-          });
-        }
+        // "Mint approval missing overridesFromOutgoingApprovals" moved to
+        // review-ux/approvals.ts (review.ux.mint_approval_missing_override).
 
         // Check for unlimited mint (no amount limits and no transfer limits)
         const amounts = criteria.approvalAmounts as Record<string, unknown> | undefined;
@@ -329,12 +396,12 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
 
         const hasAmountLimit =
           amounts &&
-          ((amounts.overallApprovalAmount && amounts.overallApprovalAmount !== '0') ||
-            (amounts.perInitiatedByAddressApprovalAmount && amounts.perInitiatedByAddressApprovalAmount !== '0'));
+          ((amounts.overallApprovalAmount && amounts.overallApprovalAmount !== 0n) ||
+            (amounts.perInitiatedByAddressApprovalAmount && amounts.perInitiatedByAddressApprovalAmount !== 0n));
         const hasTransferLimit =
           transfers &&
-          ((transfers.overallMaxNumTransfers && transfers.overallMaxNumTransfers !== '0') ||
-            (transfers.perInitiatedByAddressMaxNumTransfers && transfers.perInitiatedByAddressMaxNumTransfers !== '0'));
+          ((transfers.overallMaxNumTransfers && transfers.overallMaxNumTransfers !== 0n) ||
+            (transfers.perInitiatedByAddressMaxNumTransfers && transfers.perInitiatedByAddressMaxNumTransfers !== 0n));
         const hasPredetermined =
           predetermined &&
           ((predetermined.incrementedBalances && Object.keys(predetermined.incrementedBalances as object).length > 0) ||
@@ -344,23 +411,17 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
           findings.push({
             severity: 'critical',
             category: 'supply',
-            title: `Mint approval "${approvalId}" has NO supply limits`,
-            detail: 'This mint approval has no overallApprovalAmount, no maxNumTransfers, and no predeterminedBalances. Anyone matching the approval can mint unlimited tokens.',
+            title: `Mint approval "${approvalId}" has no supply limits`,
+            detail: 'This token-creation approval has no overallApprovalAmount, no maxNumTransfers, and no predeterminedBalances. Anyone matching the approval can create unlimited new tokens.',
             recommendation:
-              'Add approvalAmounts.overallApprovalAmount to cap total supply, or maxNumTransfers.overallMaxNumTransfers to cap mint count, or use predeterminedBalances for sequential allocation.'
+              'Add approvalAmounts.overallApprovalAmount to cap total supply, or maxNumTransfers.overallMaxNumTransfers to cap the creation count, or use predeterminedBalances for sequential allocation.'
           });
         }
 
-        // Public mint check
-        if (initiatedBy === 'All' && toId === 'All') {
-          findings.push({
-            severity: 'info',
-            category: 'approval-design',
-            title: `Mint approval "${approvalId}" is PUBLIC`,
-            detail: 'Anyone can mint tokens. initiatedByListId and toListId are both "All".',
-            recommendation: 'This is correct for public mints. For restricted mints, use a specific address or dynamic store challenge.'
-          });
-        }
+        // "Public mint" info finding removed — approvals are commonly
+        // gated via claim plugins, merkle challenges, dynamic stores, or
+        // out-of-band allowlists, and flagging All+All as noteworthy
+        // produced noise on every template that uses public mints.
       }
 
       // --- Backing address checks ---
@@ -472,53 +533,44 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
         });
       }
 
-      // All -> specific address with no initiator restriction (forceful revocation)
-      if (fromId === 'All' && initiatedBy === 'All' && !criteria.requireToEqualsInitiatedBy) {
-        findings.push({
-          severity: 'critical',
-          category: 'transferability',
-          title: `Approval "${approvalId}" allows FORCEFUL transfers from anyone`,
-          detail: 'fromListId: "All" + initiatedByListId: "All" means ANYONE can initiate a transfer FROM any address. This allows forceful seizure/revocation of tokens.',
-          recommendation:
-            'Add requireToEqualsInitiatedBy: true, or restrict initiatedByListId to the token owner, or restrict fromListId to "!Mint" for voluntary transfers only.'
-        });
-      }
+      // "Approval allows FORCEFUL transfers" moved to review-ux/approvals.ts
+      // (review.ux.forceful_transfers_allowed + review.ux.forceful_override_mismatch).
 
-      // Specific from -> specific to with All initiator
-      if (
-        fromId !== 'Mint' &&
-        fromId !== '!Mint' &&
-        fromId !== 'All' &&
-        !fromId.startsWith('!') &&
-        toId !== 'All' &&
-        initiatedBy === 'All'
-      ) {
-        if (fromId !== toId) {
-          findings.push({
-            severity: 'info',
-            category: 'approval-design',
-            title: `Approval "${approvalId}" is a directed transfer channel`,
-            detail: `Allows transfers from ${fromId} to ${toId}, initiated by anyone.`,
-            recommendation: 'Verify this directed channel is intentional.'
-          });
-        }
-      }
+      // "Directed transfer channel" info finding removed — self-explanatory
+      // from the approval definition itself and produced noise on every
+      // smart-token backing/unbacking pair.
     }
 
     // 3c. Check for backing approval completeness (smart tokens need BOTH)
     const standards = col.standards || [];
     const isSmartToken = standards.some((s) => s.toLowerCase().includes('smart token'));
 
+    // Use the canonical backing address from cosmosCoinBackedPath to
+    // identify backing / unbacking approvals structurally. An approval is:
+    //   - backing   (deposit)    when allowBackedMinting && fromListId == backingAddr
+    //   - unbacking (withdrawal) when allowBackedMinting && toListId   == backingAddr
+    // This is more reliable than guessing based on '!' prefixes on the
+    // opposite list, which misses valid shapes like `fromListId: 'AllWithoutMint'`.
+    const backingAddr = (invariants.cosmosCoinBackedPath as any)?.address as string | undefined;
+    const addrMatches = (listId: string | undefined, addr: string | undefined): boolean => {
+      if (!listId || !addr) return false;
+      if (listId === addr) return true;
+      // compound/negated lists containing the backing address also count
+      return listId.includes(addr);
+    };
+
     const hasBackingApproval = approvals.some((a) => {
       const crit = a.approvalCriteria as Record<string, unknown> | undefined;
-      if (crit?.allowBackedMinting && a.fromListId && !a.fromListId.startsWith('!')) return true;
+      if (crit?.allowBackedMinting && addrMatches(a.fromListId, backingAddr)) return true;
       if (a.approvalId && /backing/i.test(a.approvalId) && !/unbacking/i.test(a.approvalId)) return true;
+      if (a.approvalId && /vault-deposit/i.test(a.approvalId)) return true;
       return false;
     });
     const hasUnbackingApproval = approvals.some((a) => {
       const crit = a.approvalCriteria as Record<string, unknown> | undefined;
-      if (crit?.allowBackedMinting && a.toListId && a.fromListId && (a.fromListId.startsWith('!') || a.fromListId === 'All')) return true;
+      if (crit?.allowBackedMinting && addrMatches(a.toListId, backingAddr)) return true;
       if (a.approvalId && /unbacking/i.test(a.approvalId)) return true;
+      if (a.approvalId && /vault-withdraw/i.test(a.approvalId)) return true;
       return false;
     });
 
@@ -548,74 +600,41 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
     // 4. TRANSFERABILITY ANALYSIS
     // ========================================
 
-    const hasTransferApproval = approvals.some(
-      (a) => a.fromListId === '!Mint' || (a.fromListId !== 'Mint' && !(a.approvalCriteria as Record<string, unknown>)?.allowBackedMinting)
-    );
+    // "Soulbound" = no way for tokens to leave their initial minter. Any of
+    // the following counts as a transfer path:
+    //   - A classic !Mint post-mint transfer approval
+    //   - Any non-mint approval that isn't backed minting (free P2P)
+    //   - Backed minting approvals (backing/unbacking) — these let users
+    //     deposit/withdraw from the backing address, which is a real
+    //     transfer path out of the soulbound interpretation
+    const hasTransferApproval =
+      approvals.some(
+        (a) => a.fromListId === '!Mint' || (a.fromListId !== 'Mint' && !(a.approvalCriteria as Record<string, unknown>)?.allowBackedMinting)
+      ) || hasBackingApproval || hasUnbackingApproval;
 
     if (!hasTransferApproval && approvals.length > 0) {
       findings.push({
         severity: 'info',
         category: 'transferability',
-        title: 'No post-mint transfer approval found (non-transferable / soulbound)',
-        detail: 'The collection has no approval allowing transfers between non-Mint addresses. Tokens are soulbound after minting.',
-        recommendation: 'If this is intentional (soulbound tokens), this is correct. Add a free-transfer approval (fromListId: "!Mint") if transfers should be allowed.'
+        title: 'Tokens are non-transferable / soulbound',
+        detail: 'The collection has no approval allowing tokens to move between non-Mint addresses. Tokens cannot leave their initial holder once they are in circulation.',
+        recommendation: 'If non-transferable tokens are intentional, this is correct. Otherwise add a free-transfer approval (fromListId: "!Mint") so holders can move tokens to other addresses.'
       });
     }
 
-    // Check noForcefulPostMintTransfers invariant
-    if (!invariants.noForcefulPostMintTransfers) {
-      const potentialForceful = approvals.some((a) => {
-        if (a.fromListId === 'Mint') return false;
-        const initiated = a.initiatedByListId as string;
-        const anyoneCanInitiate = initiated === 'All' || initiated === '!Mint' || initiated === 'AllWithMint';
-        if (!anyoneCanInitiate) return false;
-        const crit = a.approvalCriteria as Record<string, unknown> | undefined;
-        return !crit?.requireToEqualsInitiatedBy;
-      });
-      if (potentialForceful) {
-        findings.push({
-          severity: 'warning',
-          category: 'transferability',
-          title: 'noForcefulPostMintTransfers is not set',
-          detail: 'The invariant noForcefulPostMintTransfers is false/unset, and there are approvals that could allow forceful transfers. The manager or third parties might be able to move tokens from holders without consent.',
-          recommendation: 'Set invariants.noForcefulPostMintTransfers: true if forceful transfers should never be possible.'
-        });
-      }
-    }
-
-    // ========================================
-    // 4b. AMOUNT SCALING RISK ANALYSIS
-    // ========================================
-
-    for (const a of approvals) {
-      const crit = a.approvalCriteria as Record<string, unknown> | undefined;
-      if (!crit) continue;
-      const incrementedBal = (crit.predeterminedBalances as Record<string, unknown> | undefined)?.incrementedBalances as
-        | Record<string, unknown>
-        | undefined;
-      if (!incrementedBal?.allowAmountScaling) continue;
-      const aId = (a as Record<string, unknown>).approvalId as string || 'unnamed';
-
-      const hasCoinOverride = ((crit.coinTransfers as Array<Record<string, unknown>>) || []).some(
-        (ct) => ct.overrideFromWithApproverAddress
-      );
-      if (hasCoinOverride) {
-        findings.push({
-          severity: 'warning',
-          category: 'approval-design',
-          title: `Amount scaling with approver-funded payments ("${aId}")`,
-          detail: 'This approval uses allowAmountScaling with overrideFromWithApproverAddress on coin transfers. Users can multiply payment amounts drawn from the approver/escrow. This is expected for prediction markets and credit tokens but dangerous for bids or offers.',
-          recommendation: 'Verify maxScalingMultiplier is set to a reasonable cap. Review who can initiate transfers through this approval.'
-        });
-      }
-    }
+    // "noForcefulPostMintTransfers not set" and "amount scaling with
+    // approver-funded payments" moved to review-ux/approvals.ts
+    // (review.ux.forceful_transfers_allowed + review.ux.amount_scaling_with_approver_funds).
 
     // ========================================
     // 5. INVARIANTS ANALYSIS
     // ========================================
 
     if (invariants.cosmosCoinBackedPath) {
-      if (!col.aliasPathsToAdd || col.aliasPathsToAdd.length === 0) {
+      // Tolerate both shapes: create Msgs use aliasPathsToAdd, frontend
+      // collection store uses aliasPaths. Either one counts.
+      const aliasPaths = (col as any).aliasPaths || col.aliasPathsToAdd || [];
+      if (aliasPaths.length === 0) {
         findings.push({
           severity: 'info',
           category: 'smart-token',
@@ -630,14 +649,24 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
     // 6. METADATA & STANDARDS CHECKS
     // ========================================
 
-    const collectionUri = col.collectionMetadata?.uri || '';
-    if (collectionUri.startsWith('ipfs://METADATA_') || collectionUri === '') {
+    // Collection metadata URI placeholder check — suppressed when the
+    // frontend WithDetails shape is present (nested metadata.metadata
+    // with inline name / image / description). In that state the URI is
+    // intentionally blank pre-upload; the auto-apply flow resolves it
+    // on submit. `ipfs://METADATA_*` internal placeholders from the
+    // session/template flow are also valid and don't trigger this.
+    const collectionMeta: any = col.collectionMetadata;
+    const collectionUri: string = collectionMeta?.uri || '';
+    const collectionInline = collectionMeta?.metadata;
+    const hasInlineContent = !!(collectionInline && (collectionInline.name || collectionInline.image || collectionInline.description));
+    const isInternalPlaceholder = /^ipfs:\/\/METADATA_[A-Z]/.test(collectionUri);
+    if (!hasInlineContent && !isInternalPlaceholder && collectionUri === '') {
       findings.push({
         severity: 'info',
         category: 'metadata',
-        title: 'Collection metadata URI is a placeholder',
-        detail: `URI is "${collectionUri}". This needs to be replaced with actual IPFS metadata before deployment.`,
-        recommendation: 'Upload metadata to IPFS and replace placeholder URIs. If using return transaction for user review, metadataPlaceholders handles this automatically.'
+        title: 'Collection metadata URI is not set',
+        detail: 'collectionMetadata.uri is empty. Upload metadata to IPFS and set the URI, or populate inline metadata so the auto-apply flow can substitute it on submit.',
+        recommendation: 'Set collectionMetadata.uri to an uploaded IPFS URI, or populate collectionMetadata.metadata with name/image/description so the auto-apply flow handles it.'
       });
     }
 
@@ -669,29 +698,9 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
       }
     }
 
-    // Standards consistency
-    if (standards.includes('NFTs') && maxSupply !== '1') {
-      findings.push({
-        severity: 'warning',
-        category: 'standards',
-        title: 'NFT standard but maxSupplyPerId is not 1',
-        detail: `Collection has "NFTs" standard but maxSupplyPerId is "${maxSupply || '0'}". NFTs should have exactly 1 per token ID.`,
-        recommendation: 'Set invariants.maxSupplyPerId: "1" for NFT collections.'
-      });
-    }
-
-    if (standards.includes('Fungible Tokens') && col.validTokenIds) {
-      const hasMultipleTokenIds = col.validTokenIds.some((r) => r.start !== r.end && !(r.start === '1' && r.end === '1'));
-      if (hasMultipleTokenIds) {
-        findings.push({
-          severity: 'warning',
-          category: 'standards',
-          title: 'Fungible token with multiple token IDs',
-          detail: 'Fungible tokens typically use a single token ID (start: "1", end: "1"). Multiple token IDs may cause confusion.',
-          recommendation: 'Use validTokenIds: [{ start: "1", end: "1" }] for standard fungible tokens.'
-        });
-      }
-    }
+    // Standards consistency ("NFT standard but maxSupplyPerId is not 1",
+    // "Fungible token with multiple token IDs") moved to review-ux/skills.ts
+    // (review.ux.nft_no_supply_cap, review.ux.fungible_multiple_token_ids).
 
     // ========================================
     // 7. SERIALIZATION CHECKS
@@ -809,24 +818,16 @@ export function auditCollection(input: { collection: Record<string, unknown>; co
           findings.push({
             severity: 'critical',
             category: 'approval-bug',
-            title: 'Missing autoApproveAllIncomingTransfers for mint collection',
-            detail: 'defaultBalances.autoApproveAllIncomingTransfers is not true, but the collection has mint approvals. Recipients will not be able to receive minted tokens.',
+            title: 'Recipients cannot receive newly created tokens',
+            detail: 'defaultBalances.autoApproveAllIncomingTransfers is not true, but the collection has token creation approvals (fromListId: "Mint"). Recipients will not be able to receive the tokens unless they first configure incoming approvals themselves.',
             recommendation: 'Set defaultBalances.autoApproveAllIncomingTransfers: true.'
           });
         }
       }
-    } else {
-      const hasMint = approvals.some((a) => a.fromListId === 'Mint');
-      if (hasMint && col.collectionId === '0') {
-        findings.push({
-          severity: 'warning',
-          category: 'approval-bug',
-          title: 'No defaultBalances specified with mint approvals',
-          detail: 'The collection has mint approvals but no defaultBalances. The chain defaults may not include autoApproveAllIncomingTransfers: true.',
-          recommendation: 'Explicitly set defaultBalances with autoApproveAllIncomingTransfers: true for mint collections.'
-        });
-      }
     }
+    // "autoApproveAllIncomingTransfers missing on mint collections
+    // without defaultBalances set" moved to review-ux/approvals.ts
+    // (review.ux.auto_approve_disabled_on_mintable).
 
     // ========================================
     // BUILD SUMMARY
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/address-list.ts b/packages/bitbadgesjs-sdk/src/core/builders/address-list.ts
index d1d28edbae..c5a808e7c8 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/address-list.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/address-list.ts
@@ -6,8 +6,7 @@ import {
   FOREVER,
   BURN_ADDRESS,
   buildMsg,
-  emptyPermissions,
-  mintToBurnBalances,
+  baselinePermissions,
   defaultBalances
 } from './shared.js';
 
@@ -16,31 +15,49 @@ export interface AddressListParams {
   image?: string;
   description?: string;
   manager?: string; // bb1... address that can add/remove members (defaults to creator)
+  /**
+   * Creator address — used as the default manager when `manager` isn't
+   * specified. The CLI passes this through from `--creator`. If neither
+   * `manager` nor `creator` is provided, the builder leaves the field
+   * empty and the CLI emit()'s defensive pass will fill it in from the
+   * post-build `creator` it sets on the message itself.
+   */
+  creator?: string;
 }
 
 export function buildAddressList(params: AddressListParams): any {
+  // Default the list manager to the creator when not explicitly set.
+  // An address-list MUST have a non-empty initiatedByListId on its
+  // approvals — the chain rejects "" with "initiated by list id is
+  // uninitialized" — so we have to pick a sensible default rather than
+  // leave it blank.
+  const initiatedBy = params.manager || params.creator || '';
   const collectionApprovals = [
     // Manager Add — mint tokens to add addresses
     {
       fromListId: 'Mint',
       toListId: 'All',
-      initiatedByListId: params.manager || '',
+      initiatedByListId: initiatedBy,
       approvalId: 'manager-add',
       transferTimes: FOREVER,
       tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
       version: '0',
       approvalCriteria: {
-        predeterminedBalances: mintToBurnBalances(),
         overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true
+        overridesToIncomingApprovals: false
       }
     },
-    // Manager Remove — burn tokens to remove addresses
+    // Manager Remove — burn tokens to remove addresses. fromListId is
+    // `'!Mint'` (NOT `'All'`) because the chain rejects `'All'` here
+    // with "Mint address cannot be included in address list with other
+    // addresses" (validate at msg_server_universal_update_collection.go:146).
+    // The earlier skill-audit suggestion to use `'All'` was wrong; the
+    // chain enforces the exclusion of Mint from address-list approvals.
     {
       fromListId: '!Mint',
       toListId: BURN_ADDRESS,
-      initiatedByListId: params.manager || '',
+      initiatedByListId: initiatedBy,
       approvalId: 'manager-remove',
       transferTimes: FOREVER,
       tokenIds: [{ start: '1', end: '1' }],
@@ -48,7 +65,7 @@ export function buildAddressList(params: AddressListParams): any {
       version: '0',
       approvalCriteria: {
         overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true
+        overridesToIncomingApprovals: false
       }
     }
   ];
@@ -57,11 +74,9 @@ export function buildAddressList(params: AddressListParams): any {
     collectionApprovals,
     standards: ['Address List'],
     manager: params.manager || '',
-    collectionPermissions: emptyPermissions(),
+    collectionPermissions: baselinePermissions(),
     invariants: {
       noCustomOwnershipTimes: true,
-      maxSupplyPerId: '0',
-      noForcefulPostMintTransfers: false,
       disablePoolCreation: true
     },
     defaultBalances: defaultBalances({ autoApproveAllIncomingTransfers: true })
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/auction.ts b/packages/bitbadgesjs-sdk/src/core/builders/auction.ts
index 5a598fb974..3d487c2ac2 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/auction.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/auction.ts
@@ -3,19 +3,14 @@
  * @module core/builders/auction
  */
 import {
-  MAX_UINT64,
   FOREVER,
   BURN_ADDRESS,
   parseDuration,
   durationToTimestamp,
   buildMsg,
-  buildAliasPath,
   frozenPermissions,
   defaultBalances,
   metadataPlaceholders,
-  singleTokenMetadata,
-  mintToBurnBalances,
-  zeroAmounts,
   zeroMaxTransfers
 } from './shared.js';
 
@@ -25,31 +20,73 @@ export interface AuctionParams {
   name?: string;
   description?: string;
   image?: string;
+  /**
+   * Seller address — used as `initiatedByListId` on the mint-to-winner
+   * approval so only the seller can accept the winning bid. Falls back
+   * to the CLI-passed `creator` when not set.
+   */
+  seller?: string;
+  creator?: string;
 }
 
 export function buildAuction(params: AuctionParams): any {
   const bidDeadlineTs = durationToTimestamp(params.bidDeadline || '7d');
   const acceptEndTs = String(Number(bidDeadlineTs) + Number(parseDuration(params.acceptWindow || '7d')));
+  const sellerAddr = params.seller || params.creator || '';
+  const randomId = () => Math.random().toString(16).slice(2, 18);
+
+  // Mint the auction NFT (1x token 1) on settlement. The frontend
+  // AuctionRegistry calls this `mintToSellerBalances`, but the actual
+  // destination is set by the approval's `toListId` + the transfer
+  // recipient — this function just says "create 1 new token 1".
+  const mintOneTokenOneBalances = {
+    manualBalances: [],
+    orderCalculationMethod: {
+      useOverallNumTransfers: true,
+      usePerToAddressNumTransfers: false,
+      usePerFromAddressNumTransfers: false,
+      usePerInitiatedByAddressNumTransfers: false,
+      useMerkleChallengeLeafIndex: false,
+      challengeTrackerId: ''
+    },
+    incrementedBalances: {
+      startBalances: [
+        { amount: '1', tokenIds: [{ start: '1', end: '1' }], ownershipTimes: FOREVER }
+      ],
+      incrementTokenIdsBy: '0',
+      incrementOwnershipTimesBy: '0',
+      durationFromTimestamp: '0',
+      allowOverrideTimestamp: false,
+      recurringOwnershipTimes: { startTime: '0', intervalLength: '0', chargePeriodLength: '0' },
+      allowOverrideWithAnyValidToken: false,
+      allowAmountScaling: false,
+      maxScalingMultiplier: '0'
+    }
+  };
 
   const collectionApprovals = [
-    // Mint-to-Winner — seller accepts winning bid during accept window
+    // Mint-to-Winner — seller accepts winning bid during accept window.
+    // `initiatedByListId: sellerAddr` locks acceptance to the seller.
     {
       fromListId: 'Mint',
       toListId: 'All',
-      initiatedByListId: '',
-      approvalId: 'mint-to-winner',
+      initiatedByListId: sellerAddr,
+      approvalId: `auction-mint-to-winner-${randomId()}`,
       transferTimes: [{ start: bidDeadlineTs, end: acceptEndTs }],
-      tokenIds: FOREVER,
+      tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
       version: '0',
       approvalCriteria: {
-        predeterminedBalances: mintToBurnBalances(),
+        predeterminedBalances: mintOneTokenOneBalances,
         maxNumTransfers: {
           ...zeroMaxTransfers('auction-tracker'),
           overallMaxNumTransfers: '1'
         },
         overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true,
+        // Must be FALSE so the winning bidder's incoming payment intent
+        // (their bid approval) still gets matched. Setting this true
+        // would bypass the bidder's incoming approvals entirely.
+        overridesToIncomingApprovals: false,
         autoDeletionOptions: {
           afterOneUse: true,
           afterOverallMaxNumTransfers: true,
@@ -63,15 +100,27 @@ export function buildAuction(params: AuctionParams): any {
       fromListId: '!Mint',
       toListId: BURN_ADDRESS,
       initiatedByListId: 'All',
-      approvalId: 'burn',
+      approvalId: `auction-burn-${randomId()}`,
       transferTimes: FOREVER,
-      tokenIds: FOREVER,
+      tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
       version: '0'
     }
   ];
 
-  const { collectionMetadata } = metadataPlaceholders(params.name || 'Auction');
+  // Auctions are 1-of-1 NFTs, so the token-level metadata is always an
+  // identical mirror of the collection-level metadata. Reuse the default
+  // token entry emitted by metadataPlaceholders() (keyed by
+  // ipfs://METADATA_TOKEN_DEFAULT, same content as the collection) and
+  // narrow its tokenIds range to [1,1] so it doesn't bleed into any
+  // future higher IDs. This matches the custom-2fa / single-NFT pattern
+  // where collection image == token image automatically — no separate
+  // tokenMetadata path to drift out of sync.
+  const { collectionMetadata, tokenMetadata, placeholders: collectionPlaceholders } = metadataPlaceholders(
+    params.name || 'Auction',
+    params.description,
+    params.image
+  );
 
   return buildMsg({
     collectionApprovals,
@@ -81,11 +130,22 @@ export function buildAuction(params: AuctionParams): any {
     invariants: {
       noCustomOwnershipTimes: true,
       maxSupplyPerId: '0',
-      noForcefulPostMintTransfers: false,
+      // Non-mint approvals (auction-burn) have no override flags, so
+      // forceful post-mint transfers can be permanently locked.
+      noForcefulPostMintTransfers: true,
       disablePoolCreation: true
     },
-    aliasPathsToAdd: [buildAliasPath('uauction', 'AUCTION', 0)],
+    // Auctions are 1-of-1 NFTs — no fractional denom unit needed. The
+    // previous version added an alias path with `decimals: 0` which the
+    // chain rejected with "denom unit decimals cannot be 0". The auction
+    // doesn't need a fungible representation; the NFT itself is the only
+    // tradable surface.
+    aliasPathsToAdd: [],
     collectionMetadata,
-    tokenMetadata: [singleTokenMetadata('1', params.name || 'Auction Item', params.description, params.image)]
+    tokenMetadata: tokenMetadata.map((entry) => ({
+      ...entry,
+      tokenIds: [{ start: '1', end: '1' }]
+    })),
+    metadataPlaceholders: collectionPlaceholders
   });
 }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/bounty.ts b/packages/bitbadgesjs-sdk/src/core/builders/bounty.ts
index 3cdea92ad7..d8ee2393fe 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/bounty.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/bounty.ts
@@ -11,7 +11,6 @@ import {
   durationToTimestamp,
   uniqueId,
   buildMsg,
-  buildAliasPath,
   frozenPermissions,
   defaultBalances,
   metadataPlaceholders,
@@ -55,7 +54,7 @@ export function buildBounty(params: BountyParams): any {
           {
             proposalId: uniqueId('bounty-accept'),
             quorumThreshold: '100',
-            voters: [{ address: params.verifier, weight: '100' }]
+            voters: [{ address: params.verifier, weight: '1' }]
           }
         ],
         coinTransfers: [
@@ -90,7 +89,7 @@ export function buildBounty(params: BountyParams): any {
           {
             proposalId: uniqueId('bounty-deny'),
             quorumThreshold: '100',
-            voters: [{ address: params.verifier, weight: '100' }]
+            voters: [{ address: params.verifier, weight: '1' }]
           }
         ],
         coinTransfers: [
@@ -135,7 +134,7 @@ export function buildBounty(params: BountyParams): any {
     }
   ];
 
-  const { collectionMetadata, tokenMetadata } = metadataPlaceholders(params.name || 'Bounty');
+  const { collectionMetadata, tokenMetadata, placeholders } = metadataPlaceholders(params.name || 'Bounty');
 
   return buildMsg({
     collectionApprovals,
@@ -145,12 +144,16 @@ export function buildBounty(params: BountyParams): any {
     invariants: {
       noCustomOwnershipTimes: true,
       maxSupplyPerId: '0',
-      noForcefulPostMintTransfers: false,
+      noForcefulPostMintTransfers: true,
       disablePoolCreation: true
     },
-    aliasPathsToAdd: [buildAliasPath('ubounty', 'BOUNTY', 0)],
+    // Bounty receipt is a 1-of-1 NFT-style token — no fractional denom
+    // unit needed. The previous version added an alias path with
+    // `decimals: 0` which the chain rejects.
+    aliasPathsToAdd: [],
     mintEscrowCoinsToTransfer: [{ amount: baseAmount, denom: coin.denom }],
     collectionMetadata,
-    tokenMetadata
+    tokenMetadata,
+    metadataPlaceholders: placeholders
   });
 }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/builders.spec.ts b/packages/bitbadgesjs-sdk/src/core/builders/builders.spec.ts
index 15d7cba048..f49eeea7a9 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/builders.spec.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/builders.spec.ts
@@ -106,8 +106,10 @@ describe('vault builder', () => {
   test('has deposit and withdrawal approvals', () => {
     expect(r.collectionApprovals.length).toBe(2);
     const ids = r.collectionApprovals.map((a: any) => a.approvalId);
-    expect(ids).toContain('deposit');
-    expect(ids).toContain('withdrawal');
+    // Vault uses `vault-deposit` + a randomized `vault-withdraw-<hex>`
+    // id to match VaultApprovalRegistry's collision-avoidance pattern.
+    expect(ids).toContain('vault-deposit');
+    expect(ids.some((id: string) => id.startsWith('vault-withdraw-'))).toBe(true);
   });
 
   test('backing approvals have mustPrioritize and allowBackedMinting', () => {
@@ -117,16 +119,21 @@ describe('vault builder', () => {
     }
   });
 
+  // Helper: the withdraw approval has a random suffix, so tests find it
+  // by prefix rather than exact match.
+  const findWithdraw = (approvals: any[]) =>
+    approvals.find((a: any) => typeof a.approvalId === 'string' && a.approvalId.startsWith('vault-withdraw-'));
+
   test('daily withdraw limit adds approvalAmounts', () => {
     const limited = val(buildVault({ backingCoin: 'USDC', dailyWithdrawLimit: 100 }));
-    const withdrawal = limited.collectionApprovals.find((a: any) => a.approvalId === 'withdrawal');
+    const withdrawal = findWithdraw(limited.collectionApprovals);
     expect(withdrawal.approvalCriteria.approvalAmounts).toBeDefined();
     expect(withdrawal.approvalCriteria.approvalAmounts.perInitiatedByAddressApprovalAmount).toBe('100000000');
   });
 
   test('require2fa adds mustOwnTokens', () => {
     const twoFa = val(buildVault({ backingCoin: 'USDC', require2fa: '74' }));
-    const withdrawal = twoFa.collectionApprovals.find((a: any) => a.approvalId === 'withdrawal');
+    const withdrawal = findWithdraw(twoFa.collectionApprovals);
     expect(withdrawal.approvalCriteria.mustOwnTokens).toBeDefined();
     expect(withdrawal.approvalCriteria.mustOwnTokens[0].collectionId).toBe('74');
   });
@@ -134,7 +141,7 @@ describe('vault builder', () => {
   test('emergency recovery adds migration approval', () => {
     const recovery = val(buildVault({ backingCoin: 'USDC', emergencyRecovery: 'bb1recovery' }));
     expect(recovery.collectionApprovals.length).toBe(3);
-    const migration = recovery.collectionApprovals.find((a: any) => a.approvalId === 'emergency-migration');
+    const migration = recovery.collectionApprovals.find((a: any) => a.approvalId === 'vault-emergency-migration');
     expect(migration.toListId).toBe('bb1recovery');
   });
 
@@ -152,8 +159,10 @@ describe('smart-account builder', () => {
   test('has Smart Token standard', () => { expect(r.standards).toContain('Smart Token'); });
   test('has backing and unbacking', () => {
     const ids = r.collectionApprovals.map((a: any) => a.approvalId);
-    expect(ids).toContain('smart-token-backing');
-    expect(ids).toContain('smart-token-unbacking');
+    // Renamed in the parity pass to match CollectionApprovalRegistry's
+    // smart-account-* naming (frontend source of truth).
+    expect(ids).toContain('smart-account-backing');
+    expect(ids).toContain('smart-account-unbacking');
   });
   test('tradable adds Liquidity Pools', () => {
     const t = val(buildSmartAccount({ backingCoin: 'USDC', tradable: true }));
@@ -188,12 +197,15 @@ describe('subscription builder', () => {
     expect(mt.validTokenIds).toEqual([{ start: '1', end: '3' }]);
     expect(mt.collectionApprovals.length).toBe(3);
   });
-  test('multiple payouts', () => {
+  test('multiple payouts (single denom)', () => {
+    // Subscription protocol requires all coin transfers to share a denom.
+    // Treasury splits across multiple recipients with the same coin are
+    // legitimate; mixed denoms throw at build time (see builder.ts).
     const mp = val(buildSubscription({
       interval: 'monthly',
       payouts: [
         { recipient: 'bb1a', amount: 5, denom: 'USDC' },
-        { recipient: 'bb1b', amount: 3, denom: 'BADGE' }
+        { recipient: 'bb1b', amount: 3, denom: 'USDC' }
       ]
     }));
     const cts = mp.collectionApprovals[0].approvalCriteria.coinTransfers;
@@ -201,6 +213,18 @@ describe('subscription builder', () => {
     expect(cts[0].to).toBe('bb1a');
     expect(cts[1].to).toBe('bb1b');
   });
+
+  test('multiple payouts with mixed denoms throws', () => {
+    expect(() =>
+      buildSubscription({
+        interval: 'monthly',
+        payouts: [
+          { recipient: 'bb1a', amount: 5, denom: 'USDC' },
+          { recipient: 'bb1b', amount: 3, denom: 'BADGE' }
+        ]
+      })
+    ).toThrow(/single denom/);
+  });
   test('passes verification', () => {
     expect(verifyBuilder(msg).violations.filter((vi: any) => vi.standard === 'Subscription')).toEqual([]);
   });
@@ -340,7 +364,7 @@ describe('quests builder', () => {
   test('has Quests standard', () => { expect(r.standards).toEqual(['Quests']); });
   test('correct escrow', () => { expect(r.mintEscrowCoinsToTransfer[0].amount).toBe('1000000000000'); });
   test('quest approval with escrow payout', () => {
-    const q = r.collectionApprovals.find((a: any) => a.approvalId === 'quest-approval');
+    const q = r.collectionApprovals.find((a: any) => a.approvalId === 'quests-approval');
     expect(q.approvalCriteria.coinTransfers[0].overrideFromWithApproverAddress).toBe(true);
     expect(q.approvalCriteria.coinTransfers[0].overrideToWithInitiator).toBe(true);
   });
@@ -462,7 +486,12 @@ describe('all collection builders pass verifyStandardsCompliance with zero viola
     ['smart-account (ai-agent)', buildSmartAccount({ backingCoin: 'BADGE', aiAgentVault: true })],
     ['subscription (single)', buildSubscription({ interval: 'monthly', price: 10, denom: 'USDC', recipient: 'bb1test' })],
     ['subscription (multi-tier)', buildSubscription({ interval: 'daily', price: 5, denom: 'BADGE', recipient: 'bb1r', tiers: 3 })],
-    ['subscription (multi-payout)', buildSubscription({ interval: 'monthly', payouts: [{ recipient: 'bb1a', amount: 5, denom: 'USDC' }, { recipient: 'bb1b', amount: 3, denom: 'BADGE' }] })],
+    // Subscription faucet approvals must use a SINGLE denom — see
+    // buildSubscription's runtime check and the proto-level
+    // `doesCollectionFollowSubscriptionProtocol()` rule. Multiple
+    // recipients sharing one denom is valid (treasury split); mixing
+    // denoms is not.
+    ['subscription (multi-payout)', buildSubscription({ interval: 'monthly', payouts: [{ recipient: 'bb1a', amount: 5, denom: 'USDC' }, { recipient: 'bb1b', amount: 3, denom: 'USDC' }] })],
     ['bounty', buildBounty({ amount: 100, denom: 'USDC', verifier: 'bb1v', recipient: 'bb1r' })],
     ['bounty (BADGE)', buildBounty({ amount: 50, denom: 'BADGE', verifier: 'bb1v', recipient: 'bb1r', expiration: '7d' })],
     ['crowdfund', buildCrowdfund({ goal: 1000, denom: 'USDC' })],
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/credit-token.ts b/packages/bitbadgesjs-sdk/src/core/builders/credit-token.ts
index 6c3e58d07d..259bc8095d 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/credit-token.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/credit-token.ts
@@ -8,7 +8,9 @@ import {
   resolveCoin,
   buildMsg,
   buildAliasPath,
+  sanitizeCosmosPathName,
   frozenPermissions,
+  defaultBalances,
   scalingBalances
 } from './shared.js';
 
@@ -23,10 +25,12 @@ export interface CreditTokenParams {
 export function buildCreditToken(params: CreditTokenParams): any {
   const coin = resolveCoin(params.paymentDenom);
   const tokensPerUnit = params.tokensPerUnit ?? 100;
-  const symbol = params.symbol || 'CREDIT';
+  // Same chain regex as smart-account / vault — strip non-allowed
+  // characters before deriving the lowercase denom. See sanitizeCosmosPathName.
+  const symbol = sanitizeCosmosPathName(params.symbol || 'CREDIT', 'symbol');
 
   const creditMint = {
-    approvalId: 'credit-mint',
+    approvalId: 'credit-scaled',
     fromListId: 'Mint',
     toListId: 'All',
     initiatedByListId: 'All',
@@ -55,17 +59,20 @@ export function buildCreditToken(params: CreditTokenParams): any {
     }
   };
 
+  const alias = buildAliasPath('u' + symbol.toLowerCase(), symbol, coin.decimals, undefined, params.name);
+
   return buildMsg({
     collectionApprovals: [creditMint],
     validTokenIds: [{ start: '1', end: '1' }],
     standards: ['Credit Token'],
     collectionPermissions: frozenPermissions(),
+    defaultBalances: defaultBalances({ autoApproveAllIncomingTransfers: true }),
     invariants: {
       noCustomOwnershipTimes: true,
-      maxSupplyPerId: '0',
-      noForcefulPostMintTransfers: false,
+      noForcefulPostMintTransfers: true,
       disablePoolCreation: true
     },
-    aliasPathsToAdd: [buildAliasPath('u' + symbol.toLowerCase(), symbol, coin.decimals)]
+    aliasPathsToAdd: [alias.path],
+    metadataPlaceholders: { ...alias.placeholders }
   });
 }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/crowdfund.ts b/packages/bitbadgesjs-sdk/src/core/builders/crowdfund.ts
index 167e26ffa1..a67981e99f 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/crowdfund.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/crowdfund.ts
@@ -10,7 +10,6 @@ import {
   toBaseUnits,
   durationToTimestamp,
   buildMsg,
-  buildAliasPath,
   frozenPermissions,
   defaultBalances,
   metadataPlaceholders,
@@ -24,12 +23,26 @@ export interface CrowdfundParams {
   crowdfunder?: string; // bb1... address — who receives funds on success (creator fills in if empty)
   deadline?: string; // duration shorthand, default "30d"
   name?: string;
+  /**
+   * Creator address — used as the default crowdfunder when `crowdfunder`
+   * isn't specified. The CLI passes this through from `--creator`.
+   * Without a real address the resulting tx is broken (the success/refund
+   * approvals would have `toListId: 'All'` which is meaningless for an
+   * escrow payout).
+   */
+  creator?: string;
 }
 
 export function buildCrowdfund(params: CrowdfundParams): any {
   const coin = resolveCoin(params.denom);
   const goalBase = toBaseUnits(params.goal, coin.decimals);
   const deadlineTs = durationToTimestamp(params.deadline || '30d');
+  // Resolve the crowdfunder destination once. Falling back to 'All'
+  // would produce an unsigned-payout-target collection that the chain
+  // would accept but no one could practically use. Prefer the explicit
+  // flag, then the creator (passed through from CLI --creator), and
+  // only as a last resort use 'All' (which the reviewer flags).
+  const crowdfunderAddr = params.crowdfunder || params.creator || 'All';
 
   const collectionApprovals = [
     // Deposit-Refund — public deposit, mints refund receipt (token 1)
@@ -38,7 +51,7 @@ export function buildCrowdfund(params: CrowdfundParams): any {
       toListId: 'All',
       initiatedByListId: 'All',
       approvalId: 'deposit-refund',
-      transferTimes: FOREVER,
+      transferTimes: [{ start: '1', end: deadlineTs }],
       tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
       version: '0',
@@ -54,35 +67,51 @@ export function buildCrowdfund(params: CrowdfundParams): any {
             overrideToWithInitiator: false
           }
         ],
+        // Mint approval: outgoing override required by standard.
+        // Incoming: recipient auto-approves via defaultBalances.
         overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true
+        overridesToIncomingApprovals: false
       }
     },
-    // Deposit-Progress — tracks total deposits via token 2 to creator
+    // Deposit-Progress — tracks total deposits via token 2 to creator.
+    // toListId falls back to 'All' if --crowdfunder isn't set; the reviewer
+    // will flag the ambiguity so callers pass a concrete address.
     {
       fromListId: 'Mint',
-      toListId: params.crowdfunder || '',
+      toListId: crowdfunderAddr,
       initiatedByListId: 'All',
       approvalId: 'deposit-progress',
-      transferTimes: FOREVER,
+      transferTimes: [{ start: '1', end: deadlineTs }],
       tokenIds: [{ start: '2', end: '2' }],
       ownershipTimes: FOREVER,
       version: '0',
       approvalCriteria: {
         allowAmountScaling: true,
         predeterminedBalances: scalingBalances('1'),
+        // Mint approval: outgoing override required by standard.
+        // Incoming: crowdfunder auto-approves via defaultBalances.
         overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true
+        overridesToIncomingApprovals: false
       }
     },
-    // Success — creator withdraws funds after deadline if goal met
+    // Success — crowdfunder withdraws funds after deadline if goal met.
+    // toListId is BURN_ADDRESS: the success approval burns the deposit
+    // receipt token and the coinTransfer (with
+    // overrideFromWithApproverAddress) routes the underlying funds to
+    // the crowdfunder via the escrow. Routing tokens to
+    // crowdfunderAddr directly would mint an NFT to them, which isn't
+    // the intended semantic.
     {
       fromListId: 'Mint',
-      toListId: params.crowdfunder || '',
-      initiatedByListId: params.crowdfunder || '',
+      toListId: BURN_ADDRESS,
+      initiatedByListId: crowdfunderAddr,
       approvalId: 'success',
-      transferTimes: [{ start: deadlineTs, end: MAX_UINT64 }],
-      tokenIds: FOREVER,
+      // Strictly AFTER deadline — `deadlineTs + 1` prevents the
+      // success claim from racing the final deposit at the exact
+      // deadline second. Matches CrowdfundRegistry's
+      // `{start: deadlineTime + 1n, end: MAX_UINT}`.
+      transferTimes: [{ start: String(BigInt(deadlineTs) + 1n), end: MAX_UINT64 }],
+      tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
       version: '0',
       approvalCriteria: {
@@ -93,7 +122,7 @@ export function buildCrowdfund(params: CrowdfundParams): any {
             ownershipTimes: FOREVER,
             tokenIds: [{ start: '2', end: '2' }],
             overrideWithCurrentTime: true,
-            mustSatisfyForAllAssets: false
+            mustSatisfyForAllAssets: true
           }
         ],
         coinTransfers: [
@@ -104,6 +133,16 @@ export function buildCrowdfund(params: CrowdfundParams): any {
             overrideToWithInitiator: true
           }
         ],
+        // Only one successful withdrawal ever — the crowdfunder claims
+        // the escrowed funds once. Frontend uses overall:1.
+        maxNumTransfers: {
+          overallMaxNumTransfers: '1',
+          perToAddressMaxNumTransfers: '0',
+          perFromAddressMaxNumTransfers: '0',
+          perInitiatedByAddressMaxNumTransfers: '0',
+          amountTrackerId: 'crowdfund-success',
+          resetTimeIntervals: { startTime: '0', intervalLength: '0' }
+        },
         predeterminedBalances: scalingBalances('1'),
         overridesFromOutgoingApprovals: true
       }
@@ -114,7 +153,9 @@ export function buildCrowdfund(params: CrowdfundParams): any {
       toListId: BURN_ADDRESS,
       initiatedByListId: 'All',
       approvalId: 'refund',
-      transferTimes: [{ start: deadlineTs, end: MAX_UINT64 }],
+      // Same `deadlineTs + 1` boundary as the success approval — no
+      // refunds at the exact deadline second, only strictly after.
+      transferTimes: [{ start: String(BigInt(deadlineTs) + 1n), end: MAX_UINT64 }],
       tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
       version: '0',
@@ -126,7 +167,7 @@ export function buildCrowdfund(params: CrowdfundParams): any {
             ownershipTimes: FOREVER,
             tokenIds: [{ start: '2', end: '2' }],
             overrideWithCurrentTime: true,
-            mustSatisfyForAllAssets: false
+            mustSatisfyForAllAssets: true
           }
         ],
         coinTransfers: [
@@ -137,10 +178,25 @@ export function buildCrowdfund(params: CrowdfundParams): any {
             overrideToWithInitiator: true
           }
         ],
+        // Refunds unlimited in aggregate — each backer gates themselves
+        // via their own deposit receipt ownership (mustOwnTokens).
+        maxNumTransfers: {
+          overallMaxNumTransfers: MAX_UINT64,
+          perToAddressMaxNumTransfers: '0',
+          perFromAddressMaxNumTransfers: '0',
+          perInitiatedByAddressMaxNumTransfers: '0',
+          amountTrackerId: 'crowdfund-refund',
+          resetTimeIntervals: { startTime: '0', intervalLength: '0' }
+        },
         allowAmountScaling: true,
         predeterminedBalances: scalingBalances('1'),
-        overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true
+        // No overrides: holder self-initiates their own refund burn and
+        // auto-approves via defaultBalances. Previously both overrides
+        // were true, which let any third party initiate the burn and
+        // redirect the refund payout via overrideToWithInitiator —
+        // a theft vector closed.
+        overridesFromOutgoingApprovals: false,
+        overridesToIncomingApprovals: false
       }
     },
     // Burn — general burn, always allowed
@@ -150,13 +206,23 @@ export function buildCrowdfund(params: CrowdfundParams): any {
       initiatedByListId: 'All',
       approvalId: 'burn',
       transferTimes: FOREVER,
-      tokenIds: FOREVER,
+      tokenIds: [{ start: '1', end: '2' }],
       ownershipTimes: FOREVER,
       version: '0'
     }
   ];
 
-  const { collectionMetadata } = metadataPlaceholders(params.name || 'Crowdfund');
+  const { collectionMetadata, placeholders: collectionPlaceholders } = metadataPlaceholders(
+    params.name || 'Crowdfund'
+  );
+  const refundToken = singleTokenMetadata('1', 'Refund Token', 'Refundable share of the crowdfund pool.');
+  const progressToken = singleTokenMetadata('2', 'Progress Token', 'Tracks total deposits in the crowdfund pool.');
+
+  // Strip the per-token default that metadataPlaceholders() seeds — this
+  // template defines its own per-token entries below, so the default
+  // ipfs://METADATA_TOKEN_DEFAULT shouldn't end up in the sidecar.
+  const { 'ipfs://METADATA_TOKEN_DEFAULT': _drop, ...collectionOnlyPlaceholders } = collectionPlaceholders;
+  void _drop;
 
   return buildMsg({
     collectionApprovals,
@@ -167,17 +233,21 @@ export function buildCrowdfund(params: CrowdfundParams): any {
     invariants: {
       noCustomOwnershipTimes: true,
       maxSupplyPerId: '0',
-      noForcefulPostMintTransfers: false,
+      // Non-mint approvals (refund, burn) no longer use override flags,
+      // so forceful post-mint transfers can be permanently locked.
+      noForcefulPostMintTransfers: true,
       disablePoolCreation: true
     },
-    aliasPathsToAdd: [
-      buildAliasPath('urefund', 'REFUND', 0),
-      buildAliasPath('utotaldeposit', 'TOTALDEPOSIT', 0)
-    ],
+    // Refund + total-deposit tokens are 1-of-1 receipt-style — no
+    // fractional denom unit needed. The previous version added alias
+    // paths with `decimals: 0` which the chain rejects.
+    aliasPathsToAdd: [],
     collectionMetadata,
-    tokenMetadata: [
-      singleTokenMetadata('1', 'Refund Token'),
-      singleTokenMetadata('2', 'Progress Token')
-    ]
+    tokenMetadata: [refundToken.entry, progressToken.entry],
+    metadataPlaceholders: {
+      ...collectionOnlyPlaceholders,
+      [refundToken.placeholder.uri]: refundToken.placeholder.content,
+      [progressToken.placeholder.uri]: progressToken.placeholder.content
+    }
   });
 }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/custom-2fa.ts b/packages/bitbadgesjs-sdk/src/core/builders/custom-2fa.ts
index db819f459d..97a7c7803d 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/custom-2fa.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/custom-2fa.ts
@@ -6,8 +6,9 @@ import {
   FOREVER,
   BURN_ADDRESS,
   buildMsg,
-  emptyPermissions,
-  alwaysLockedPermission
+  baselinePermissions,
+  alwaysLockedPermission,
+  alwaysLockedTokenIdsPermission
 } from './shared.js';
 
 export interface Custom2FAParams {
@@ -31,15 +32,19 @@ export function buildCustom2FA(params: Custom2FAParams): any {
       ownershipTimes: FOREVER,
       version: '0',
       approvalCriteria: {
+        // Expiration is runtime-enforced by the frontend at mint time
+        // via `getCustom2FAOwnershipTimes()` + `allowPurgeIfExpired`;
+        // the approval itself doesn't encode a duration. Use an empty
+        // `startBalances` so the chain's "exactly one
+        // orderCalculationMethod flag must be true" rule doesn't fire
+        // (it only applies when startBalances is non-empty).
         predeterminedBalances: {
           manualBalances: [],
           incrementedBalances: {
-            startBalances: [
-              { amount: '1', tokenIds: [{ start: '1', end: '1' }], ownershipTimes: FOREVER }
-            ],
+            startBalances: [],
             incrementTokenIdsBy: '0',
             incrementOwnershipTimesBy: '0',
-            durationFromTimestamp: '300000',
+            durationFromTimestamp: '0',
             allowOverrideTimestamp: false,
             recurringOwnershipTimes: { startTime: '0', intervalLength: '0', chargePeriodLength: '0' },
             allowOverrideWithAnyValidToken: false,
@@ -50,13 +55,13 @@ export function buildCustom2FA(params: Custom2FAParams): any {
             useOverallNumTransfers: false,
             usePerToAddressNumTransfers: false,
             usePerFromAddressNumTransfers: false,
-            usePerInitiatedByAddressNumTransfers: true,
+            usePerInitiatedByAddressNumTransfers: false,
             useMerkleChallengeLeafIndex: false,
             challengeTrackerId: ''
           }
         },
         overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true,
+        overridesToIncomingApprovals: false,
         autoDeletionOptions: {
           afterOneUse: false,
           afterOverallMaxNumTransfers: false,
@@ -105,7 +110,7 @@ export function buildCustom2FA(params: Custom2FAParams): any {
     canUpdateCustomData: [alwaysLockedPermission()],
     canUpdateManager: [],
     canUpdateCollectionMetadata: [],
-    canUpdateValidTokenIds: [alwaysLockedPermission()],
+    canUpdateValidTokenIds: [alwaysLockedTokenIdsPermission()],
     canUpdateTokenMetadata: [],
     canUpdateCollectionApprovals: [],
     canAddMoreAliasPaths: [alwaysLockedPermission()],
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/pm-buy-intent.ts b/packages/bitbadgesjs-sdk/src/core/builders/pm-buy-intent.ts
index 8b03420c95..2a4355e329 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/pm-buy-intent.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/pm-buy-intent.ts
@@ -26,6 +26,11 @@ export interface PmBuyIntentParams {
 }
 
 export function buildPmBuyIntent(params: PmBuyIntentParams): any {
+  if (!Number.isInteger(params.amount) || params.amount <= 0) {
+    throw new Error(
+      `buildPmBuyIntent: amount must be a positive integer (got ${params.amount}). Prediction market tokens are unitless counts, not fractional.`
+    );
+  }
   const coin = resolveCoin(params.denom);
   const basePrice = toBaseUnits(params.price, coin.decimals);
   const expirationTs = durationToTimestamp(params.expiration || '7d');
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/pm-sell-intent.ts b/packages/bitbadgesjs-sdk/src/core/builders/pm-sell-intent.ts
index a44e385e74..be5dc88680 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/pm-sell-intent.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/pm-sell-intent.ts
@@ -26,6 +26,11 @@ export interface PmSellIntentParams {
 }
 
 export function buildPmSellIntent(params: PmSellIntentParams): any {
+  if (!Number.isInteger(params.amount) || params.amount <= 0) {
+    throw new Error(
+      `buildPmSellIntent: amount must be a positive integer (got ${params.amount}). Prediction market tokens are unitless counts, not fractional.`
+    );
+  }
   const coin = resolveCoin(params.denom);
   const basePrice = toBaseUnits(params.price, coin.decimals);
   const expirationTs = durationToTimestamp(params.expiration || '7d');
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/prediction-market.ts b/packages/bitbadgesjs-sdk/src/core/builders/prediction-market.ts
index f6d403b00e..e36926e0c6 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/prediction-market.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/prediction-market.ts
@@ -28,9 +28,18 @@ export function buildPredictionMarket(params: PredictionMarketParams): any {
   const yesTokenIds = [{ start: '1', end: '1' }];
   const noTokenIds = [{ start: '2', end: '2' }];
 
+  const randomId = () => Math.random().toString(16).slice(2, 18);
+  const mintId = randomId();
+  const transferId = randomId();
+  const redeemId = randomId();
+  const settleYesId = randomId();
+  const settleNoId = randomId();
+  const settlePushYesId = randomId();
+  const settlePushNoId = randomId();
+
   // 1. Paired Mint — mint both YES and NO by depositing USDC
   const pairedMint = {
-    approvalId: 'paired-mint',
+    approvalId: `pm-mint-${mintId}`,
     fromListId: 'Mint',
     toListId: 'All',
     initiatedByListId: 'All',
@@ -54,15 +63,18 @@ export function buildPredictionMarket(params: PredictionMarketParams): any {
           overrideToWithInitiator: false
         }
       ],
+      // Mint approval: outgoing override required by standard.
+      // Incoming: recipient auto-approves via defaultBalances +
+      // requireToEqualsInitiatedBy (depositor receives their own mint).
       overridesFromOutgoingApprovals: true,
-      overridesToIncomingApprovals: true,
+      overridesToIncomingApprovals: false,
       requireToEqualsInitiatedBy: true
     }
   };
 
   // 2. Free transfer — tokens are freely transferable
   const freeTransfer = {
-    approvalId: 'free-transfer',
+    approvalId: `pm-transfer-${transferId}`,
     fromListId: '!Mint',
     toListId: 'All',
     initiatedByListId: 'All',
@@ -75,7 +87,7 @@ export function buildPredictionMarket(params: PredictionMarketParams): any {
 
   // 3. Pre-Settlement Redeem — burn both YES+NO to get USDC back
   const preRedeem = {
-    approvalId: 'pre-redeem',
+    approvalId: `pm-redeem-${redeemId}`,
     fromListId: '!Mint',
     toListId: BURN_ADDRESS,
     initiatedByListId: 'All',
@@ -99,18 +111,43 @@ export function buildPredictionMarket(params: PredictionMarketParams): any {
           overrideToWithInitiator: true
         }
       ],
-      requireFromEqualsInitiatedBy: true,
-      overridesFromOutgoingApprovals: true,
-      overridesToIncomingApprovals: true
+      // Chain rule: overrideFromWithApproverAddress requires
+      // maxNumTransfers to set at least one non-zero limit. Pre-redeem
+      // is unbounded (any holder can redeem any number of pairs) so we
+      // set overall to MAX_UINT64 rather than capping per initiator.
+      // Frontend PredictionMarketRegistry uses the same shape.
+      maxNumTransfers: {
+        overallMaxNumTransfers: MAX_UINT64,
+        perToAddressMaxNumTransfers: '0',
+        perFromAddressMaxNumTransfers: '0',
+        perInitiatedByAddressMaxNumTransfers: '0',
+        amountTrackerId: `pm-redeem-${redeemId}`,
+        resetTimeIntervals: { startTime: '0', intervalLength: '0' }
+      },
+      // No overrides: holder self-initiates their own pair burn and
+      // auto-approves the outgoing side via defaultBalances
+      // (autoApproveSelfInitiatedOutgoingTransfers). No requireFromEqualsInitiatedBy
+      // either — leaving open-ended so a holder can delegate via their
+      // own user-level outgoing approval if they want.
+      // Burn-address destination auto-approves incoming.
+      overridesFromOutgoingApprovals: false,
+      overridesToIncomingApprovals: false
     }
   };
 
-  // 4-7. Settlement outcomes
+  // 4-7. Settlement outcomes. `burnAmount` is the number of tokens
+  // consumed per 1 coin of payout — 1 for a winning side (burn 1,
+  // get 1 back) and 2 for a push (burn 2, get 1 back). `allowAmountScaling: true`
+  // lets holders scale to whatever balance they actually hold, so
+  // the numbers here encode the ratio, not a hard minimum.
+  // Matches PredictionMarketRegistry.settlementApproval() in the
+  // frontend: `burnAmount = isPush ? depositAmount * 2n : depositAmount`.
   function settlementApproval(
     approvalId: string,
     tokenIds: any[],
     proposalId: string,
-    coinAmount: string
+    burnAmount: string,
+    payoutAmount: string
   ) {
     return {
       approvalId,
@@ -122,39 +159,56 @@ export function buildPredictionMarket(params: PredictionMarketParams): any {
       tokenIds,
       version: '0',
       approvalCriteria: {
-        predeterminedBalances: scalingBalances('1'),
+        predeterminedBalances: scalingBalances(burnAmount),
         coinTransfers: [
           {
             to: '',
-            coins: [{ amount: coinAmount, denom: coin.denom }],
+            coins: [{ amount: payoutAmount, denom: coin.denom }],
             overrideFromWithApproverAddress: true,
             overrideToWithInitiator: true
           }
         ],
+        // Chain rule: overrideFromWithApproverAddress requires
+        // maxNumTransfers to set at least one non-zero limit. Each
+        // settlement claim per holder.
+        maxNumTransfers: {
+          overallMaxNumTransfers: '0',
+          perToAddressMaxNumTransfers: '0',
+          perFromAddressMaxNumTransfers: '0',
+          perInitiatedByAddressMaxNumTransfers: '1',
+          amountTrackerId: approvalId,
+          resetTimeIntervals: { startTime: '0', intervalLength: '0' }
+        },
         votingChallenges: [
           {
             proposalId,
             quorumThreshold: '100',
-            voters: [{ address: params.verifier, weight: '100' }]
+            voters: [{ address: params.verifier, weight: '1' }]
           }
         ],
-        overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true
+        // No overrides: winning-side holder self-initiates their own
+        // settlement burn and auto-approves via defaultBalances. The
+        // verifier vote gates WHICH proposal can execute but the actual
+        // claim must come from the token holder.
+        overridesFromOutgoingApprovals: false,
+        overridesToIncomingApprovals: false
       }
     };
   }
 
-  const settleYes = settlementApproval('settle-yes', yesTokenIds, 'settlement-yes', '1');
-  const settleNo = settlementApproval('settle-no', noTokenIds, 'settlement-no', '1');
-  const settlePushYes = settlementApproval('settle-push-yes', yesTokenIds, 'settlement-push-yes', '1');
-  const settlePushNo = settlementApproval('settle-push-no', noTokenIds, 'settlement-push-no', '1');
+  // Win: burn 1 token → 1 coin. Push: burn 2 tokens → 1 coin.
+  const settleYes = settlementApproval(`pm-settle-yes-${settleYesId}`, yesTokenIds, `pm-settle-yes-${settleYesId}`, '1', '1');
+  const settleNo = settlementApproval(`pm-settle-no-${settleNoId}`, noTokenIds, `pm-settle-no-${settleNoId}`, '1', '1');
+  const settlePushYes = settlementApproval(`pm-settle-push-yes-${settlePushYesId}`, yesTokenIds, `pm-settle-push-yes-${settlePushYesId}`, '2', '1');
+  const settlePushNo = settlementApproval(`pm-settle-push-no-${settlePushNoId}`, noTokenIds, `pm-settle-push-no-${settlePushNoId}`, '2', '1');
 
   const collectionApprovals = [pairedMint, freeTransfer, preRedeem, settleYes, settleNo, settlePushYes, settlePushNo];
 
-  const tokenMetadata = [
-    singleTokenMetadata('1', 'YES', params.description, params.image),
-    singleTokenMetadata('2', 'NO', params.description, params.image)
-  ];
+  const yesToken = singleTokenMetadata('1', 'YES', params.description, params.image);
+  const noToken = singleTokenMetadata('2', 'NO', params.description, params.image);
+  const tokenMetadata = [yesToken.entry, noToken.entry];
+  const yesAlias = buildAliasPath('uyes', 'YES', coin.decimals, params.image, 'YES', params.description);
+  const noAlias = buildAliasPath('uno', 'NO', coin.decimals, params.image, 'NO', params.description);
 
   return buildMsg({
     collectionApprovals,
@@ -162,15 +216,20 @@ export function buildPredictionMarket(params: PredictionMarketParams): any {
     standards: ['Prediction Market'],
     collectionPermissions: frozenPermissions(),
     tokenMetadata,
+    metadataPlaceholders: {
+      [yesToken.placeholder.uri]: yesToken.placeholder.content,
+      [noToken.placeholder.uri]: noToken.placeholder.content,
+      ...yesAlias.placeholders,
+      ...noAlias.placeholders
+    },
     invariants: {
       noCustomOwnershipTimes: true,
       maxSupplyPerId: '0',
-      noForcefulPostMintTransfers: false,
+      // Non-mint approvals (redeem, settlements) no longer use override
+      // flags, so forceful post-mint transfers can be permanently locked.
+      noForcefulPostMintTransfers: true,
       disablePoolCreation: false
     },
-    aliasPathsToAdd: [
-      buildAliasPath('uyes', 'YES', coin.decimals),
-      buildAliasPath('uno', 'NO', coin.decimals)
-    ]
+    aliasPathsToAdd: [yesAlias.path, noAlias.path]
   });
 }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/product-catalog.ts b/packages/bitbadgesjs-sdk/src/core/builders/product-catalog.ts
index 2468a31d7c..020f8fb948 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/product-catalog.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/product-catalog.ts
@@ -31,12 +31,14 @@ export interface ProductCatalogParams {
 
 export function buildProductCatalog(params: ProductCatalogParams): any {
   const { products, storeAddress } = params;
+  const randomId = () => Math.random().toString(16).slice(2, 18);
 
   const purchaseApprovals = products.map((product, i) => {
     const idx = i + 1;
     const coin = resolveCoin(product.denom);
     const basePrice = toBaseUnits(product.price, coin.decimals);
     const tokenIds = [{ start: String(idx), end: String(idx) }];
+    const approvalId = `product-purchase-${randomId()}`;
 
     const predeterminedBalances = {
       ...mintToBurnBalances(),
@@ -47,7 +49,7 @@ export function buildProductCatalog(params: ProductCatalogParams): any {
     };
 
     return {
-      approvalId: `purchase-${idx}`,
+      approvalId,
       fromListId: 'Mint',
       toListId: product.burn ? BURN_ADDRESS : 'All',
       initiatedByListId: 'All',
@@ -71,7 +73,7 @@ export function buildProductCatalog(params: ProductCatalogParams): any {
               perToAddressMaxNumTransfers: '0',
               perFromAddressMaxNumTransfers: '0',
               perInitiatedByAddressMaxNumTransfers: '0',
-              amountTrackerId: `purchase-${idx}-tracker`,
+              amountTrackerId: approvalId,
               resetTimeIntervals: { startTime: '0', intervalLength: '0' }
             }
           : zeroMaxTransfers(),
@@ -84,7 +86,7 @@ export function buildProductCatalog(params: ProductCatalogParams): any {
 
   // Burn approval: anyone can burn their tokens
   const burnApproval = {
-    approvalId: 'burn',
+    approvalId: `product-burn-${randomId()}`,
     fromListId: '!Mint',
     toListId: BURN_ADDRESS,
     initiatedByListId: 'All',
@@ -97,7 +99,17 @@ export function buildProductCatalog(params: ProductCatalogParams): any {
 
   const collectionApprovals = [...purchaseApprovals, burnApproval];
 
-  const tokenMetadata = products.map((product, i) => singleTokenMetadata(String(i + 1), product.name));
+  // Per-product metadata: each product gets its own placeholder URI keyed
+  // by token id. Accumulate the sidecar entries so the auto-apply flow has
+  // full coverage.
+  const tokenMetadataAndPlaceholders = products.map((product, i) =>
+    singleTokenMetadata(String(i + 1), product.name)
+  );
+  const tokenMetadata = tokenMetadataAndPlaceholders.map((t) => t.entry);
+  const productPlaceholders: Record<string, { name: string; description: string; image: string }> = {};
+  for (const t of tokenMetadataAndPlaceholders) {
+    productPlaceholders[t.placeholder.uri] = t.placeholder.content;
+  }
 
   return buildMsg({
     collectionApprovals,
@@ -107,9 +119,8 @@ export function buildProductCatalog(params: ProductCatalogParams): any {
     tokenMetadata,
     invariants: {
       noCustomOwnershipTimes: true,
-      maxSupplyPerId: '0',
-      noForcefulPostMintTransfers: false,
       disablePoolCreation: true
-    }
+    },
+    metadataPlaceholders: productPlaceholders
   });
 }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/quests.ts b/packages/bitbadgesjs-sdk/src/core/builders/quests.ts
index 0487989f07..4a28489df1 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/quests.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/quests.ts
@@ -8,7 +8,7 @@ import {
   resolveCoin,
   toBaseUnits,
   buildMsg,
-  emptyPermissions,
+  baselinePermissions,
   mintToBurnBalances
 } from './shared.js';
 
@@ -23,13 +23,21 @@ export function buildQuests(params: QuestsParams): any {
   const coin = resolveCoin(params.denom);
   const rewardBase = toBaseUnits(params.reward, coin.decimals);
 
+  // Fixed `'quests-approval'` id matches the frontend quests.tsx page
+  // which hardcodes this value when calling
+  // `CollectionApprovalRegistry.questsApproval({ approvalId: 'quests-approval' })`.
+  // Quests collections use a singleton claim approval (one per
+  // collection), so there's no collision risk that would justify a
+  // random suffix. The amountTrackerId mirrors the approvalId.
+  const questApprovalId = 'quests-approval';
+
   const collectionApprovals = [
     // Quest claim approval
     {
       fromListId: 'Mint',
       toListId: 'All',
       initiatedByListId: 'All',
-      approvalId: 'quest-approval',
+      approvalId: questApprovalId,
       transferTimes: FOREVER,
       tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
@@ -41,7 +49,7 @@ export function buildQuests(params: QuestsParams): any {
           perToAddressMaxNumTransfers: '0',
           perFromAddressMaxNumTransfers: '0',
           perInitiatedByAddressMaxNumTransfers: '0',
-          amountTrackerId: 'quest-tracker',
+          amountTrackerId: questApprovalId,
           resetTimeIntervals: { startTime: '0', intervalLength: '0' }
         },
         coinTransfers: [
@@ -61,7 +69,7 @@ export function buildQuests(params: QuestsParams): any {
       fromListId: '!Mint',
       toListId: BURN_ADDRESS,
       initiatedByListId: 'All',
-      approvalId: 'burn',
+      approvalId: 'burnable-approval',
       transferTimes: FOREVER,
       tokenIds: [{ start: '1', end: '1' }],
       ownershipTimes: FOREVER,
@@ -73,12 +81,12 @@ export function buildQuests(params: QuestsParams): any {
   return buildMsg({
     collectionApprovals,
     standards: ['Quests'],
-    collectionPermissions: emptyPermissions(),
+    collectionPermissions: baselinePermissions(),
     invariants: {
       noCustomOwnershipTimes: true,
       maxSupplyPerId: '0',
       noForcefulPostMintTransfers: false,
-      disablePoolCreation: true
+      disablePoolCreation: false
     },
     mintEscrowCoinsToTransfer: [
       { amount: String(BigInt(rewardBase) * BigInt(params.maxClaims)), denom: coin.denom }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/recurring-payment.ts b/packages/bitbadgesjs-sdk/src/core/builders/recurring-payment.ts
index 31f093e59f..5b57471812 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/recurring-payment.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/recurring-payment.ts
@@ -48,13 +48,16 @@ export function buildRecurringPayment(params: RecurringPaymentParams): any {
           startBalances: [{ amount: '1', tokenIds: [{ start: '1', end: '1' }], ownershipTimes: FOREVER }],
           incrementTokenIdsBy: '0',
           incrementOwnershipTimesBy: '0',
+          // Chain rule: only ONE of `durationFromTimestamp`,
+          // `incrementOwnershipTimesBy`, or non-zero
+          // `recurringOwnershipTimes` can be set. `durationFromTimestamp`
+          // alone is enough for the subscriber-side approval — the
+          // interval is already encoded there. Setting
+          // `recurringOwnershipTimes` too would double-define the
+          // schedule and the validator throws.
           durationFromTimestamp: intervalMs,
           allowOverrideTimestamp: true,
-          recurringOwnershipTimes: {
-            startTime: String(Date.now()),
-            intervalLength: intervalMs,
-            chargePeriodLength: intervalMs
-          },
+          recurringOwnershipTimes: { startTime: '0', intervalLength: '0', chargePeriodLength: '0' },
           allowOverrideWithAnyValidToken: false,
           allowAmountScaling: false,
           maxScalingMultiplier: '0'
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/shared.ts b/packages/bitbadgesjs-sdk/src/core/builders/shared.ts
index 87e688fe45..87047e39e9 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/shared.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/shared.ts
@@ -109,27 +109,71 @@ export function uniqueId(prefix?: string): string {
 
 // ── Common builder helpers ───────────────────────────────────────────────────
 
+/**
+ * A sidecar map of placeholder URI → off-chain metadata content. Templates
+ * accumulate these and attach them to the emitted Msg as `value._meta.metadataPlaceholders`
+ * so the CLI's Metadata To Upload section (and any frontend consumer)
+ * knows which placeholder URIs already have content provided.
+ */
+export type PlaceholderSidecar = Record<string, { name: string; description: string; image: string }>;
+
+/**
+ * Build collection + default-token metadata using placeholder URIs that the
+ * metadata auto-apply flow understands. Returns three things:
+ *
+ *   - `collectionMetadata` and `tokenMetadata` to drop into `buildMsg(...)`
+ *   - `placeholders` — a sidecar map keyed by the placeholder URIs above,
+ *     populated with the supplied name/description/image (or sane defaults).
+ *
+ * Callers should merge the returned `placeholders` into their own sidecar and
+ * pass the combined map to `buildMsg({ ..., metadataPlaceholders })`, which
+ * surfaces it on the emitted Msg as `value._meta.metadataPlaceholders`.
+ */
 export function metadataPlaceholders(name: string, description?: string, image?: string) {
+  const collectionUri = 'ipfs://METADATA_COLLECTION';
+  const tokenUri = 'ipfs://METADATA_TOKEN_DEFAULT';
+  const content = {
+    name,
+    description: description || '',
+    image: image || BITBADGES_DEFAULT_IMAGE
+  };
   return {
-    collectionMetadata: {
-      uri: DEFAULT_METADATA_URI,
-      customData: JSON.stringify({ name, description: description || '', image: image || BITBADGES_DEFAULT_IMAGE })
-    },
+    collectionMetadata: { uri: collectionUri, customData: '' },
     tokenMetadata: [
-      {
-        uri: DEFAULT_METADATA_URI,
-        customData: '',
-        tokenIds: FOREVER
-      }
-    ]
+      { uri: tokenUri, customData: '', tokenIds: FOREVER }
+    ],
+    placeholders: {
+      [collectionUri]: { ...content },
+      [tokenUri]: { ...content }
+    } as PlaceholderSidecar
   };
 }
 
+/**
+ * Build a per-token metadata entry using a placeholder URI scoped to the
+ * token id. Returns `{ entry, placeholder }`:
+ *
+ *   - `entry` is the object to push into `tokenMetadata: [...]`
+ *   - `placeholder` is the sidecar entry the caller should merge into its
+ *     accumulated PlaceholderSidecar and pass to buildMsg via
+ *     `metadataPlaceholders`.
+ */
 export function singleTokenMetadata(tokenId: string, name: string, description?: string, image?: string) {
+  const uri = `ipfs://METADATA_TOKEN_${tokenId}`;
   return {
-    uri: DEFAULT_METADATA_URI,
-    customData: JSON.stringify({ name, description: description || '', image: image || '' }),
-    tokenIds: [{ start: tokenId, end: tokenId }]
+    entry: {
+      uri,
+      customData: '',
+      tokenIds: [{ start: tokenId, end: tokenId }]
+    },
+    placeholder: {
+      uri,
+      content: {
+        name,
+        description: description || '',
+        image: image || BITBADGES_DEFAULT_IMAGE
+      }
+    }
   };
 }
 
@@ -152,8 +196,23 @@ export function buildMsg(params: {
   aliasPathsToAdd?: any[];
   cosmosCoinWrapperPathsToAdd?: any[];
   mintEscrowCoinsToTransfer?: any[];
+  /**
+   * Off-chain metadata sidecar the template accumulated. Attached to the
+   * output Msg as `value._meta.metadataPlaceholders`. Templates that don't have
+   * specific content should still pass an empty {} so the auto-apply flow
+   * knows to treat default placeholder URIs as NEEDED.
+   */
+  metadataPlaceholders?: PlaceholderSidecar;
 }) {
-  return {
+  // Default to placeholder URIs (not the legacy DEFAULT_METADATA_URI). The
+  // metadata auto-apply flow recognizes `ipfs://METADATA_*` and substitutes
+  // them with real uploaded URIs after the off-chain JSON is provided.
+  const collectionMetadata = params.collectionMetadata || { uri: 'ipfs://METADATA_COLLECTION', customData: '' };
+  const tokenMetadata = params.tokenMetadata || [
+    { uri: 'ipfs://METADATA_TOKEN_DEFAULT', customData: '', tokenIds: FOREVER }
+  ];
+
+  const msg: any = {
     typeUrl: '/tokenization.MsgUniversalUpdateCollection',
     value: {
       creator: params.creator || '',
@@ -161,19 +220,19 @@ export function buildMsg(params: {
       updateValidTokenIds: true,
       validTokenIds: params.validTokenIds || [{ start: '1', end: '1' }],
       updateCollectionPermissions: true,
-      collectionPermissions: params.collectionPermissions || emptyPermissions(),
+      collectionPermissions: params.collectionPermissions || baselinePermissions(),
       updateManager: true,
       manager: params.manager || '',
       updateCollectionMetadata: true,
-      collectionMetadata: params.collectionMetadata || { uri: DEFAULT_METADATA_URI, customData: '' },
+      collectionMetadata,
       updateTokenMetadata: true,
-      tokenMetadata: params.tokenMetadata || [{ uri: DEFAULT_METADATA_URI, customData: '', tokenIds: FOREVER }],
+      tokenMetadata,
       updateCustomData: true,
       customData: params.customData || '',
       updateCollectionApprovals: true,
       collectionApprovals: params.collectionApprovals.map((a: any) => ({
         ...a,
-        uri: a.uri || DEFAULT_METADATA_URI
+        uri: a.uri || `ipfs://METADATA_APPROVAL_${a.approvalId || 'unnamed'}`
       })),
       updateStandards: true,
       standards: params.standards || [],
@@ -186,6 +245,21 @@ export function buildMsg(params: {
       cosmosCoinWrapperPathsToAdd: params.cosmosCoinWrapperPathsToAdd || []
     }
   };
+
+  // Attach the sidecar as a per-msg `_meta` annotation on value, keyed
+  // by placeholder URIs that only live inside this msg's body. This is
+  // the single canonical location for the placeholder sidecar; every
+  // producer writes here and every consumer reads from here. There is
+  // no top-level `tx.metadataPlaceholders` copy anywhere in the code-
+  // base. Proto classes strip unknown fields on round-trip, so any
+  // place that reconstructs the msg through a Msg class must preserve
+  // `value._meta` explicitly (see core/review-normalize.ts
+  // reattachInlineMetadata).
+  if (params.metadataPlaceholders && Object.keys(params.metadataPlaceholders).length > 0) {
+    msg.value._meta = { metadataPlaceholders: params.metadataPlaceholders };
+  }
+
+  return msg;
 }
 
 /**
@@ -194,13 +268,20 @@ export function buildMsg(params: {
  */
 export function buildUserApprovalMsg(params: {
   collectionId: string;
+  /**
+   * Optional creator override. The CLI's `emit()` backfills this from
+   * the `--creator` flag after build, so most templates don't need to
+   * pass it through. Provided here for callers that want to set it
+   * explicitly (e.g. unit tests, other tooling).
+   */
+  creator?: string;
   outgoingApprovals?: any[];
   incomingApprovals?: any[];
 }) {
   return {
     typeUrl: '/tokenization.MsgUpdateUserApprovals',
     value: {
-      creator: '',
+      creator: params.creator || '',
       collectionId: params.collectionId,
       updateOutgoingApprovals: (params.outgoingApprovals?.length ?? 0) > 0,
       outgoingApprovals: params.outgoingApprovals || [],
@@ -212,11 +293,79 @@ export function buildUserApprovalMsg(params: {
 
 // ── Permission helpers ───────────────────────────────────────────────────────
 
+/**
+ * Bare action permission — used for canDeleteCollection, canArchiveCollection,
+ * canUpdateStandards, canUpdateCustomData, canUpdateManager,
+ * canUpdateCollectionMetadata, canAddMoreAliasPaths,
+ * canAddMoreCosmosCoinWrapperPaths. These permission types take no extra
+ * scoping fields.
+ */
 export function alwaysLockedPermission() {
   return { permanentlyPermittedTimes: [], permanentlyForbiddenTimes: FOREVER };
 }
 
-export function emptyPermissions() {
+/**
+ * Token-scoped action permission — used for canUpdateValidTokenIds and
+ * canUpdateTokenMetadata, which require a `tokenIds` field that narrows
+ * which token IDs the permission applies to. Defaults to all token IDs.
+ */
+export function alwaysLockedTokenIdsPermission() {
+  return {
+    tokenIds: FOREVER,
+    permanentlyPermittedTimes: [],
+    permanentlyForbiddenTimes: FOREVER
+  };
+}
+
+/**
+ * Approval-scoped action permission — used for canUpdateCollectionApprovals.
+ * Requires fromListId / toListId / initiatedByListId plus tokenIds and
+ * transferTimes. Defaults to "all approvals, forever" so the resulting
+ * permission locks the whole approval set.
+ */
+export function alwaysLockedCollectionApprovalPermission() {
+  return {
+    fromListId: 'All',
+    toListId: 'All',
+    initiatedByListId: 'All',
+    transferTimes: FOREVER,
+    tokenIds: FOREVER,
+    approvalId: 'All',
+    amountTrackerId: 'All',
+    challengeTrackerId: 'All',
+    permanentlyPermittedTimes: [],
+    permanentlyForbiddenTimes: FOREVER
+  };
+}
+
+/**
+ * Baseline collection-permission set used as the default when a
+ * template doesn't override. **NOT actually empty** — six fields
+ * are pre-locked via `alwaysLockedPermission()`:
+ *
+ *   canDeleteCollection           locked (safety: never burn the collection)
+ *   canArchiveCollection          locked (safety: never archive)
+ *   canUpdateStandards            locked (the standards tag commits the schema)
+ *   canUpdateCustomData           locked (no ad-hoc proto-level mutations)
+ *   canUpdateValidTokenIds        locked (supply immutability)
+ *   canAddMoreAliasPaths          locked (no post-create alias path expansion)
+ *   canAddMoreCosmosCoinWrapperPaths locked (same for wrapper paths)
+ *
+ * The four permissions left OPEN (empty array = neutral):
+ *
+ *   canUpdateManager              manager can be rotated
+ *   canUpdateCollectionMetadata   manager can update the collection metadata URI
+ *   canUpdateTokenMetadata        manager can update per-token metadata
+ *   canUpdateCollectionApprovals  approval set can still be edited
+ *
+ * This is the "safe default for most mintable token collections" — the
+ * metadata + manager + approvals can still evolve, but the collection
+ * itself can't be deleted or have its standards/tokenIds shifted under
+ * holders. Templates that need total immutability use
+ * `frozenPermissions()` instead. Templates that need fully neutral
+ * (everything mutable) should construct their own permission object.
+ */
+export function baselinePermissions() {
   return {
     canDeleteCollection: [alwaysLockedPermission()],
     canArchiveCollection: [alwaysLockedPermission()],
@@ -224,7 +373,7 @@ export function emptyPermissions() {
     canUpdateCustomData: [alwaysLockedPermission()],
     canUpdateManager: [],
     canUpdateCollectionMetadata: [],
-    canUpdateValidTokenIds: [alwaysLockedPermission()],
+    canUpdateValidTokenIds: [alwaysLockedTokenIdsPermission()],
     canUpdateTokenMetadata: [],
     canUpdateCollectionApprovals: [],
     canAddMoreAliasPaths: [alwaysLockedPermission()],
@@ -232,20 +381,24 @@ export function emptyPermissions() {
   };
 }
 
+/** @deprecated Renamed to `baselinePermissions` — this helper returns
+ * the default-locked permission set, not an actually-empty one. Kept as
+ * an alias for one release so external consumers (if any) don't break. */
+export const emptyPermissions = baselinePermissions;
+
 export function frozenPermissions() {
-  const locked = [alwaysLockedPermission()];
   return {
-    canDeleteCollection: locked,
-    canArchiveCollection: locked,
-    canUpdateStandards: locked,
-    canUpdateCustomData: locked,
-    canUpdateManager: locked,
-    canUpdateCollectionMetadata: locked,
-    canUpdateValidTokenIds: locked,
-    canUpdateTokenMetadata: locked,
-    canUpdateCollectionApprovals: locked,
-    canAddMoreAliasPaths: locked,
-    canAddMoreCosmosCoinWrapperPaths: locked
+    canDeleteCollection: [alwaysLockedPermission()],
+    canArchiveCollection: [alwaysLockedPermission()],
+    canUpdateStandards: [alwaysLockedPermission()],
+    canUpdateCustomData: [alwaysLockedPermission()],
+    canUpdateManager: [alwaysLockedPermission()],
+    canUpdateCollectionMetadata: [alwaysLockedPermission()],
+    canUpdateValidTokenIds: [alwaysLockedTokenIdsPermission()],
+    canUpdateTokenMetadata: [alwaysLockedTokenIdsPermission()],
+    canUpdateCollectionApprovals: [alwaysLockedCollectionApprovalPermission()],
+    canAddMoreAliasPaths: [alwaysLockedPermission()],
+    canAddMoreCosmosCoinWrapperPaths: [alwaysLockedPermission()]
   };
 }
 
@@ -267,7 +420,8 @@ export function defaultBalances(overrides?: Partial<{
       canUpdateIncomingApprovals: [],
       canUpdateOutgoingApprovals: [],
       canUpdateAutoApproveSelfInitiatedIncomingTransfers: [],
-      canUpdateAutoApproveSelfInitiatedOutgoingTransfers: []
+      canUpdateAutoApproveSelfInitiatedOutgoingTransfers: [],
+      canUpdateAutoApproveAllIncomingTransfers: []
     },
     ...overrides
   };
@@ -349,24 +503,134 @@ export function scalingBalances(amount: string, maxMultiplier?: string) {
 
 // ── Alias path builder ───────────────────────────────────────────────────────
 
-export function buildAliasPath(denom: string, symbol: string, decimals: number, image?: string) {
-  const img = image || BITBADGES_DEFAULT_IMAGE;
+/**
+ * Build an alias path for a denom. PathMetadata only accepts
+ * `{ uri, customData }` — the image belongs inside the off-chain JSON
+ * referenced by `metadata.uri`. We emit placeholder URIs by default so
+ * users / agents can either (a) leave them and substitute after upload
+ * via `builder metadata apply`, or (b) pass a real URI up front.
+ *
+ * @param image Optional image URI. Kept in the parameter list for callers
+ *   that already pass it, but currently unused — the image must live in
+ *   the off-chain JSON, not the on-chain PathMetadata. Will be surfaced
+ *   through the metadata placeholder system.
+ */
+/**
+ * Strip any character not in `[a-zA-Z_{}-]` from a candidate cosmos
+ * wrapper path denom or symbol. The chain regex
+ * `^[a-zA-Z_{}-]+$` is enforced by `ValidateCosmosWrapperPathSymbol`
+ * (chain side at validate_basic.go:80-94). Digits are common in
+ * user-supplied symbols (e.g. "vUSDC9", "BADGE2") and must be removed
+ * before they reach the chain.
+ *
+ * Throws if the result is empty so callers don't accidentally produce
+ * a wrapper path with no name.
+ */
+export function sanitizeCosmosPathName(input: string, label: 'denom' | 'symbol' = 'symbol'): string {
+  const cleaned = input.replace(/[^a-zA-Z_{}\-]/g, '');
+  if (cleaned.length === 0) {
+    throw new Error(
+      `sanitizeCosmosPathName: input "${input}" produced an empty ${label} after stripping invalid characters. Provide a value containing at least one letter (a-zA-Z), underscore, brace, or dash.`
+    );
+  }
+  return cleaned;
+}
+
+/**
+ * Build an alias path entry for aliasPathsToAdd plus the matching metadata
+ * placeholder sidecar entries for both the path-level metadata URI and the
+ * denom unit's metadata URI. Returns `{ path, placeholders }`:
+ *
+ *   - `path` is the object to push into `aliasPathsToAdd: [...]`
+ *   - `placeholders` is a PlaceholderSidecar keyed by the two URIs the
+ *     path references. Callers should merge it into the accumulated
+ *     sidecar passed to buildMsg via `metadataPlaceholders`.
+ *
+ * Image/name/description intentionally flow through the sidecar — never
+ * onto the proto. The auto-apply flow on the frontend reads them from
+ * `metadataPlaceholders` keyed by the path/unit metadata URI.
+ */
+export function buildAliasPath(
+  denom: string,
+  symbol: string,
+  decimals: number,
+  image?: string,
+  name?: string,
+  description?: string
+) {
+  // Chain rule: denom unit decimals must be > 0. The chain rejects
+  // `decimals: '0'` with "denom unit decimals cannot be 0". Fail fast at
+  // build time so callers get a clear error instead of a chain rejection
+  // ten steps later.
+  if (!Number.isInteger(decimals) || decimals < 1) {
+    throw new Error(
+      `buildAliasPath: decimals must be an integer >= 1 (got ${decimals}). Use 1 for whole-unit-only tokens (e.g. NFTs that still need an alias path) or skip the alias path entirely if no fungible representation is needed.`
+    );
+  }
+  // Both denom and symbol must satisfy the chain's wrapper-path regex
+  // (`[a-zA-Z_{}-]+`). Validate up-front so callers get a clear error
+  // instead of a chain "invalid characters" rejection at simulate time.
+  const re = /^[a-zA-Z_{}\-]+$/;
+  if (!re.test(denom)) {
+    throw new Error(
+      `buildAliasPath: denom "${denom}" contains invalid characters. Allowed: a-zA-Z, _, {, }, -. Use sanitizeCosmosPathName() to clean user input.`
+    );
+  }
+  if (!re.test(symbol)) {
+    throw new Error(
+      `buildAliasPath: symbol "${symbol}" contains invalid characters. Allowed: a-zA-Z, _, {, }, -. Use sanitizeCosmosPathName() to clean user input.`
+    );
+  }
+  // Chain rule: denom and symbol can't be the same string because the
+  // chain validates them against a SHARED `symbolPaths` map per tx
+  // (msg_server_universal_update_collection.go validatePathSymbols).
+  // We already work around this by leaving the path-level symbol empty
+  // below; this guard catches any caller that might pass the same
+  // string for both fields explicitly.
+  if (denom === symbol) {
+    throw new Error(
+      `buildAliasPath: denom and symbol cannot be identical ("${denom}"). The chain rejects this with "duplicate denom unit symbol" because both fields are validated against the same per-tx map. Use different strings (e.g. denom="usymbol", symbol="SYMBOL").`
+    );
+  }
+  const pathUri = `ipfs://METADATA_ALIAS_${denom}`;
+  const unitUri = `ipfs://METADATA_ALIAS_${denom}_UNIT`;
+  const content = {
+    name: name || symbol,
+    description: description || '',
+    image: image || BITBADGES_DEFAULT_IMAGE
+  };
   return {
-    denom,
-    conversion: {
-      sideA: { amount: '1' },
-      sideB: [{ amount: '1', tokenIds: [{ start: '1', end: '1' }], ownershipTimes: FOREVER }]
+    path: {
+      denom,
+      conversion: {
+        sideA: { amount: '1' },
+        sideB: [{ amount: '1', tokenIds: [{ start: '1', end: '1' }], ownershipTimes: FOREVER }]
+      },
+      // Path-level symbol intentionally LEFT EMPTY. The chain validates
+      // path-level symbols and denom-unit-level symbols against the SAME
+      // `symbolPaths` map per tx (validatePathSymbols in
+      // msg_server_universal_update_collection.go:673). When both are set
+      // to the same string, the second insertion fails with "duplicate
+      // denom unit symbol", even though there's only one alias path with
+      // one denom unit. Skipping the path-level entry (chain check is
+      // gated on `if pathSymbol != ""`) avoids the spurious collision
+      // while keeping the user-facing symbol on the denom unit, which is
+      // what the frontend / wallets actually display.
+      symbol: '',
+      denomUnits: [
+        {
+          decimals: String(decimals),
+          symbol,
+          isDefaultDisplay: true,
+          metadata: { uri: unitUri, customData: '' }
+        }
+      ],
+      metadata: { uri: pathUri, customData: '' }
     },
-    symbol,
-    denomUnits: [
-      {
-        decimals: String(decimals),
-        symbol,
-        isDefaultDisplay: true,
-        metadata: { uri: '', customData: '', image: img }
-      }
-    ],
-    metadata: { uri: '', customData: '', image: img }
+    placeholders: {
+      [pathUri]: { ...content },
+      [unitUri]: { ...content }
+    } as PlaceholderSidecar
   };
 }
 
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/smart-account.ts b/packages/bitbadgesjs-sdk/src/core/builders/smart-account.ts
index 9160a828bc..a15dc6516d 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/smart-account.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/smart-account.ts
@@ -7,10 +7,12 @@ import {
   resolveCoin,
   buildMsg,
   buildAliasPath,
+  sanitizeCosmosPathName,
   ibcBackedInvariants,
   generateAliasAddressForIBCBackedDenom,
-  emptyPermissions,
-  alwaysLockedPermission
+  baselinePermissions,
+  alwaysLockedPermission,
+  alwaysLockedCollectionApprovalPermission
 } from './shared.js';
 
 export interface SmartAccountParams {
@@ -32,7 +34,7 @@ export function buildSmartAccount(params: SmartAccountParams): any {
       fromListId: backingAddr,
       toListId: `!${backingAddr}`,
       initiatedByListId: 'All',
-      approvalId: 'smart-token-backing',
+      approvalId: 'smart-account-backing',
       transferTimes: FOREVER,
       tokenIds: FOREVER,
       ownershipTimes: FOREVER,
@@ -42,12 +44,15 @@ export function buildSmartAccount(params: SmartAccountParams): any {
         allowBackedMinting: true
       }
     },
-    // Unbacking
+    // Unbacking. `fromListId` excludes both Mint AND the backing alias
+    // itself so the backing address can't initiate circular unbacks.
+    // The colon-separated exclude syntax is how the chain allows
+    // specifying multiple excluded lists.
     {
-      fromListId: '!Mint',
+      fromListId: `!Mint:${backingAddr}`,
       toListId: backingAddr,
       initiatedByListId: 'All',
-      approvalId: 'smart-token-unbacking',
+      approvalId: 'smart-account-unbacking',
       transferTimes: FOREVER,
       tokenIds: FOREVER,
       ownershipTimes: FOREVER,
@@ -65,7 +70,7 @@ export function buildSmartAccount(params: SmartAccountParams): any {
       fromListId: '!Mint',
       toListId: 'All',
       initiatedByListId: 'All',
-      approvalId: 'free-transfer',
+      approvalId: 'transferable-approval',
       transferTimes: FOREVER,
       tokenIds: FOREVER,
       ownershipTimes: FOREVER,
@@ -86,19 +91,26 @@ export function buildSmartAccount(params: SmartAccountParams): any {
   };
 
   const permissions = {
-    ...emptyPermissions(),
-    canUpdateCollectionApprovals: [alwaysLockedPermission()],
+    ...baselinePermissions(),
+    canUpdateCollectionApprovals: [alwaysLockedCollectionApprovalPermission()],
     canAddMoreAliasPaths: [alwaysLockedPermission()],
     canAddMoreCosmosCoinWrapperPaths: [alwaysLockedPermission()]
   };
 
-  const denomStr = 'u' + symbol.toLowerCase();
+  // Chain rule: cosmos wrapper path denom AND symbol must match
+  // `[a-zA-Z_{}-]+`. Sanitize the user-provided symbol once and
+  // derive the denom from the cleaned form so they round-trip through
+  // the chain validator without "invalid characters" rejections.
+  const cleanSymbol = sanitizeCosmosPathName(symbol, 'symbol');
+  const denomStr = 'u' + cleanSymbol.toLowerCase();
+  const alias = buildAliasPath(denomStr, cleanSymbol, coin.decimals, params.image || coin.image);
 
   return buildMsg({
     collectionApprovals,
     standards,
     invariants,
-    aliasPathsToAdd: [buildAliasPath(denomStr, symbol, coin.decimals, coin.image)],
+    aliasPathsToAdd: [alias.path],
+    metadataPlaceholders: { ...alias.placeholders },
     collectionPermissions: permissions
   });
 }
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/subscription.ts b/packages/bitbadgesjs-sdk/src/core/builders/subscription.ts
index dcc6c167f5..3f32aab4f0 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/subscription.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/subscription.ts
@@ -8,7 +8,7 @@ import {
   toBaseUnits,
   parseDuration,
   buildMsg,
-  emptyPermissions,
+  baselinePermissions,
   defaultBalances
 } from './shared.js';
 
@@ -49,6 +49,20 @@ export function buildSubscription(params: SubscriptionParams): any {
     throw new Error('Subscription requires either --price/--denom/--recipient or --payouts array');
   }
 
+  // Subscription standard requires every coin transfer in the faucet
+  // approval to use a SINGLE denom — the SDK's
+  // `doesCollectionFollowSubscriptionProtocol()` rejects mixed-denom
+  // approvals because the subscription unit (one period × one price)
+  // doesn't translate to "X USDC + Y BADGE" semantically. Fail fast at
+  // build time with a clear hint instead of producing a tx that the
+  // frontend silently won't recognize as a subscription.
+  const uniqueDenoms = Array.from(new Set(payouts.map((p) => p.denom)));
+  if (uniqueDenoms.length > 1) {
+    throw new Error(
+      `Subscription must use a single denom across all payouts. Got ${uniqueDenoms.length}: ${uniqueDenoms.join(', ')}. Use one shared denom (e.g. all in USDC) or split into separate subscription collections.`
+    );
+  }
+
   const collectionApprovals = [];
 
   for (let tier = 1; tier <= tiers; tier++) {
@@ -78,10 +92,10 @@ export function buildSubscription(params: SubscriptionParams): any {
             maxScalingMultiplier: '0'
           },
           orderCalculationMethod: {
-            useOverallNumTransfers: false,
+            useOverallNumTransfers: true,
             usePerToAddressNumTransfers: false,
             usePerFromAddressNumTransfers: false,
-            usePerInitiatedByAddressNumTransfers: true,
+            usePerInitiatedByAddressNumTransfers: false,
             useMerkleChallengeLeafIndex: false,
             challengeTrackerId: ''
           }
@@ -93,7 +107,12 @@ export function buildSubscription(params: SubscriptionParams): any {
           overrideToWithInitiator: false
         })),
         overridesFromOutgoingApprovals: true,
-        overridesToIncomingApprovals: true
+        // Subscriptions must NOT override the recipient's incoming approvals.
+        // The frontend's `doesCollectionFollowSubscriptionProtocol()` rejects
+        // subscription faucet approvals that override incoming, because the
+        // recipient still needs `autoApproveAllIncomingTransfers: true` to
+        // gate whether they actually receive the minted token.
+        overridesToIncomingApprovals: false
       }
     });
   }
@@ -116,12 +135,12 @@ export function buildSubscription(params: SubscriptionParams): any {
     collectionApprovals,
     standards: ['Subscriptions'],
     validTokenIds: [{ start: '1', end: String(tiers) }],
-    collectionPermissions: emptyPermissions(),
+    collectionPermissions: baselinePermissions(),
     invariants: {
       noCustomOwnershipTimes: false,
       maxSupplyPerId: '0',
       noForcefulPostMintTransfers: false,
-      disablePoolCreation: true
+      disablePoolCreation: false
     },
     defaultBalances: defaultBalances({ autoApproveAllIncomingTransfers: true })
   });
diff --git a/packages/bitbadgesjs-sdk/src/core/builders/vault.ts b/packages/bitbadgesjs-sdk/src/core/builders/vault.ts
index 3ef6a1f69c..4789ea781a 100644
--- a/packages/bitbadgesjs-sdk/src/core/builders/vault.ts
+++ b/packages/bitbadgesjs-sdk/src/core/builders/vault.ts
@@ -11,9 +11,10 @@ import {
   parseDuration,
   buildMsg,
   buildAliasPath,
+  sanitizeCosmosPathName,
   ibcBackedInvariants,
   generateAliasAddressForIBCBackedDenom,
-  emptyPermissions
+  baselinePermissions
 } from './shared.js';
 
 export interface VaultParams {
@@ -30,15 +31,22 @@ export interface VaultParams {
 export function buildVault(params: VaultParams): any {
   const coin = resolveCoin(params.backingCoin);
   const backingAddr = generateAliasAddressForIBCBackedDenom(coin.denom);
-  const symbol = params.symbol || 'v' + coin.symbol;
+  // Sanitize the symbol to the chain's wrapper-path regex
+  // (`[a-zA-Z_{}-]+`) — see sanitizeCosmosPathName for the rule. Users
+  // commonly include digits ("vUSDC9", "BADGE2") that would be rejected
+  // at simulate time with "symbol contains invalid characters".
+  const symbol = sanitizeCosmosPathName(params.symbol || 'v' + coin.symbol, 'symbol');
 
   const collectionApprovals: any[] = [
-    // Deposit (backing)
+    // Deposit (backing). `toListId` excludes the backing address itself
+    // so the backing alias can't receive its own wrapper tokens (which
+    // would be nonsensical and matches the frontend VaultApprovalRegistry
+    // default).
     {
       fromListId: backingAddr,
-      toListId: 'All',
+      toListId: `!${backingAddr}`,
       initiatedByListId: 'All',
-      approvalId: 'deposit',
+      approvalId: 'vault-deposit',
       transferTimes: FOREVER,
       tokenIds: FOREVER,
       ownershipTimes: FOREVER,
@@ -55,7 +63,7 @@ export function buildVault(params: VaultParams): any {
       fromListId: '!Mint',
       toListId: backingAddr,
       initiatedByListId: 'All',
-      approvalId: 'withdrawal',
+      approvalId: `vault-withdraw-${Math.random().toString(16).slice(2, 10)}`,
       transferTimes: FOREVER,
       tokenIds: FOREVER,
       ownershipTimes: FOREVER,
@@ -98,7 +106,7 @@ export function buildVault(params: VaultParams): any {
       fromListId: '!Mint',
       toListId: params.emergencyRecovery,
       initiatedByListId: params.emergencyRecovery,
-      approvalId: 'emergency-migration',
+      approvalId: 'vault-emergency-migration',
       transferTimes: FOREVER,
       tokenIds: FOREVER,
       ownershipTimes: FOREVER,
@@ -115,12 +123,25 @@ export function buildVault(params: VaultParams): any {
     disablePoolCreation: true
   };
 
+  // Derive the denom from the (sanitized) symbol — chain enforces
+  // global denom uniqueness, so a hardcoded 'uvault' would collide
+  // for any user creating more than one vault on the same chain.
+  const alias = buildAliasPath(
+    'u' + symbol.toLowerCase(),
+    symbol,
+    coin.decimals,
+    params.image || coin.image,
+    params.name,
+    params.description
+  );
+
   return buildMsg({
     collectionApprovals,
     standards: ['Smart Token', 'Vault'],
     invariants,
-    aliasPathsToAdd: [buildAliasPath('uvault', symbol, coin.decimals, coin.image)],
-    collectionPermissions: emptyPermissions()
+    aliasPathsToAdd: [alias.path],
+    metadataPlaceholders: { ...alias.placeholders },
+    collectionPermissions: baselinePermissions()
   });
 }
 
diff --git a/packages/bitbadgesjs-sdk/src/core/crowdfunds.ts b/packages/bitbadgesjs-sdk/src/core/crowdfunds.ts
index d1198b9512..5b8eb151ef 100644
--- a/packages/bitbadgesjs-sdk/src/core/crowdfunds.ts
+++ b/packages/bitbadgesjs-sdk/src/core/crowdfunds.ts
@@ -82,18 +82,23 @@ export const validateCrowdfundCollection = (collection: Readonly<iCollectionDoc<
   details.goalAmount = success.approvalCriteria?.mustOwnTokens?.[0]?.amountRange?.start;
 
   // Validate deposit-refund
+  // overridesFromOutgoingApprovals is required by the Mint approval standard.
+  // overridesToIncomingApprovals is NOT required — the recipient
+  // auto-approves via defaultBalances.autoApproveAllIncomingTransfers and/or
+  // autoApproveSelfInitiatedIncomingTransfers, so the collection-level
+  // incoming override would be redundant. Setting it to true is allowed
+  // but not required; setting it to false is the preferred default.
   const drCriteria = depositRefund.approvalCriteria;
   if (!drCriteria?.overridesFromOutgoingApprovals) errors.push('Deposit-refund: overridesFromOutgoingApprovals must be true');
-  if (!drCriteria?.overridesToIncomingApprovals) errors.push('Deposit-refund: overridesToIncomingApprovals must be true');
   if (!drCriteria?.requireToEqualsInitiatedBy) errors.push('Deposit-refund: requireToEqualsInitiatedBy must be true');
   const drIb = drCriteria?.predeterminedBalances?.incrementedBalances;
   if (!drIb?.allowAmountScaling) errors.push('Deposit-refund: allowAmountScaling must be true');
   if (!drCriteria?.coinTransfers?.length) errors.push('Deposit-refund: must have coinTransfers');
 
   // Validate deposit-progress
+  // Same incoming-override rationale as deposit-refund.
   const dpCriteria = depositProgress.approvalCriteria;
   if (!dpCriteria?.overridesFromOutgoingApprovals) errors.push('Deposit-progress: overridesFromOutgoingApprovals must be true');
-  if (!dpCriteria?.overridesToIncomingApprovals) errors.push('Deposit-progress: overridesToIncomingApprovals must be true');
   const dpIb = dpCriteria?.predeterminedBalances?.incrementedBalances;
   if (!dpIb?.allowAmountScaling) errors.push('Deposit-progress: allowAmountScaling must be true');
 
diff --git a/packages/bitbadgesjs-sdk/src/core/index.ts b/packages/bitbadgesjs-sdk/src/core/index.ts
index 02bd10f34e..2fd61e9b9b 100644
--- a/packages/bitbadgesjs-sdk/src/core/index.ts
+++ b/packages/bitbadgesjs-sdk/src/core/index.ts
@@ -59,5 +59,6 @@ export * from './validate.js';
 export * from './blankCriteria.js';
 export * from './audit.js';
 export * from './verify-standards.js';
+export * from './review.js';
 
 export * from './builders/index.js';
diff --git a/packages/bitbadgesjs-sdk/src/core/review-normalize.ts b/packages/bitbadgesjs-sdk/src/core/review-normalize.ts
new file mode 100644
index 0000000000..a12fd47c3d
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-normalize.ts
@@ -0,0 +1,144 @@
+/**
+ * Collection value normalization for the review pipeline.
+ *
+ * Extracted into a standalone file so `verifyStandardsCompliance` and
+ * `auditCollection` can import it without creating a circular
+ * dependency with `review.ts` (which depends on them).
+ *
+ * Every review consumer runs `normalizeForReview` on its input so
+ * downstream checks can assume a single canonical shape:
+ *
+ * - All numeric fields are bigints. Numbers are converted via the
+ *   registered `MsgUniversalUpdateCollection` class + each nested
+ *   class's `getNumberFieldNames()` — addresses, URIs, denoms, IDs
+ *   stay as strings. This is strictly safer than a recursive walk.
+ * - Alias path / wrapper path field names are mirrored so both
+ *   `aliasPaths` (frontend/on-chain shape) and `aliasPathsToAdd`
+ *   (Msg create shape) are always populated together.
+ *
+ * The function is idempotent: passing an already-normalized value
+ * through again is a no-op (the class constructor just rewraps).
+ */
+
+import { BigIntify } from '../common/string-numbers.js';
+import { MsgUniversalUpdateCollection } from '../transactions/messages/bitbadges/tokenization/msgUniversalUpdateCollection.js';
+
+/**
+ * Unwrap any of: transaction (`{ messages: [...] }`), raw message
+ * (`{ typeUrl, value }`), or a bare collection value object. Ported from
+ * the frontend `extractValue` helper in `reviewItems.ts`.
+ */
+export function extractCollectionValue(input: unknown): any {
+  if (!input || typeof input !== 'object') return input;
+  const obj = input as any;
+  const messages = obj.messages || (Array.isArray(obj) ? obj : undefined);
+  if (messages && Array.isArray(messages) && messages.length > 0) {
+    const msg = messages[0];
+    return msg?.value || msg || input;
+  }
+  if (obj.value && typeof obj.value === 'object') return obj.value;
+  return obj;
+}
+
+function mirrorPathFieldNames(value: Record<string, any>): Record<string, any> {
+  const out = { ...value };
+  if (out.aliasPaths && !out.aliasPathsToAdd) out.aliasPathsToAdd = out.aliasPaths;
+  if (out.aliasPathsToAdd && !out.aliasPaths) out.aliasPaths = out.aliasPathsToAdd;
+  if (out.cosmosCoinWrapperPaths && !out.cosmosCoinWrapperPathsToAdd)
+    out.cosmosCoinWrapperPathsToAdd = out.cosmosCoinWrapperPaths;
+  if (out.cosmosCoinWrapperPathsToAdd && !out.cosmosCoinWrapperPaths)
+    out.cosmosCoinWrapperPaths = out.cosmosCoinWrapperPathsToAdd;
+  return out;
+}
+
+/**
+ * Re-attach fields that the proto-spec classes strip during conversion
+ * but that review checks still need to see. The SDK has two parallel
+ * class hierarchies: the "Msg" shape (proto-spec only) used by
+ * MsgUniversalUpdateCollection, and the "WithDetails" shape used by
+ * the frontend / on-chain hydrated state, which adds nested inline
+ * content not present in the proto. When we run the Msg class to get
+ * BigIntify conversion, the extra WithDetails fields are dropped.
+ *
+ * Specifically:
+ *   - PathMetadata only keeps { uri, customData }; WithDetails adds
+ *     a nested `metadata: { name, image, description }` for
+ *     pre-upload inline content.
+ *   - CollectionMetadata same.
+ *   - CollectionApproval only keeps proto fields; WithDetails adds
+ *     `details: { name, description, image }` for the approval card.
+ *
+ * This helper walks the raw (pre-conversion) input and copies those
+ * dropped fields onto the converted output. Non-mutating to the raw
+ * input; mutates the converted result in place.
+ */
+function reattachInlineMetadata(converted: any, raw: any): void {
+  // Collection metadata
+  const rawCm = raw?.collectionMetadata;
+  if (rawCm?.metadata && converted?.collectionMetadata) {
+    converted.collectionMetadata.metadata = rawCm.metadata;
+  }
+  // Alias paths (both field names may exist after mirroring)
+  for (const field of ['aliasPathsToAdd', 'aliasPaths'] as const) {
+    const rawList = raw?.[field];
+    const outList = converted?.[field];
+    if (!Array.isArray(rawList) || !Array.isArray(outList)) continue;
+    for (let i = 0; i < Math.min(rawList.length, outList.length); i++) {
+      const rawInline = rawList[i]?.metadata?.metadata;
+      if (rawInline && outList[i]?.metadata) outList[i].metadata.metadata = rawInline;
+      const rawUnits = rawList[i]?.denomUnits || [];
+      const outUnits = outList[i]?.denomUnits || [];
+      for (let j = 0; j < Math.min(rawUnits.length, outUnits.length); j++) {
+        const rawUnitInline = rawUnits[j]?.metadata?.metadata;
+        if (rawUnitInline && outUnits[j]?.metadata) outUnits[j].metadata.metadata = rawUnitInline;
+      }
+    }
+  }
+  // Approval details — each collectionApproval may have a WithDetails
+  // `details: { name, description, image }` sibling that the proto
+  // CollectionApproval class strips. The unnamed_approvals review check
+  // reads `a.details?.name`, so we need this back on the converted list.
+  const rawApprovals = raw?.collectionApprovals;
+  const outApprovals = converted?.collectionApprovals;
+  if (Array.isArray(rawApprovals) && Array.isArray(outApprovals)) {
+    for (let i = 0; i < Math.min(rawApprovals.length, outApprovals.length); i++) {
+      const rawDetails = rawApprovals[i]?.details;
+      if (rawDetails && outApprovals[i] !== undefined && outApprovals[i] !== null) {
+        outApprovals[i].details = rawDetails;
+      }
+    }
+  }
+  // Per-msg `_meta` sidecar — the proto class strips it as an unknown
+  // field, but the review-ux metadata checks read
+  // `value._meta.metadataPlaceholders` to decide whether placeholder
+  // entries have real content. Preserve it on the converted value.
+  if (raw?._meta && typeof raw._meta === 'object') {
+    converted._meta = raw._meta;
+  }
+}
+
+export function normalizeForReview(input: unknown): any {
+  const raw = extractCollectionValue(input);
+  if (!raw || typeof raw !== 'object') return raw;
+  const mirrored = mirrorPathFieldNames(raw as Record<string, any>);
+  try {
+    // Wrap in the Msg class and convert numeric fields to bigints via
+    // each nested class's registered number-field list.
+    const msg = new MsgUniversalUpdateCollection(mirrored as any);
+    const converted = msg.convert(BigIntify) as any;
+    // The class only stores Msg-shape fields; downstream checks may
+    // still look up `aliasPaths` (frontend shape). Copy the converted
+    // list into both names.
+    if (converted.aliasPathsToAdd && !converted.aliasPaths) converted.aliasPaths = converted.aliasPathsToAdd;
+    if (converted.cosmosCoinWrapperPathsToAdd && !converted.cosmosCoinWrapperPaths)
+      converted.cosmosCoinWrapperPaths = converted.cosmosCoinWrapperPathsToAdd;
+    // Re-attach WithDetails inline metadata that the proto classes drop.
+    reattachInlineMetadata(converted, mirrored);
+    return converted;
+  } catch {
+    // Fallback: if class construction/conversion fails (unknown shape),
+    // return the mirrored-but-unconverted value. Checks that expect
+    // bigints may misfire, but the pipeline doesn't crash.
+    return mirrored;
+  }
+}
diff --git a/packages/bitbadgesjs-sdk/src/core/review-types.ts b/packages/bitbadgesjs-sdk/src/core/review-types.ts
new file mode 100644
index 0000000000..a07e5206d7
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-types.ts
@@ -0,0 +1,83 @@
+/**
+ * Unified review types — kept in a standalone file so the review-ux check
+ * modules can import types without creating a circular dependency with
+ * `review.ts` (which imports the check modules at runtime).
+ */
+
+export type Severity = 'critical' | 'warning' | 'info';
+export type FindingSource = 'audit' | 'standards' | 'ux';
+
+/**
+ * Localized string bag. `en` is always populated. Additional language
+ * codes (e.g. `es`) are optional — consumers should fall back to `en`
+ * when the user's preferred language is missing.
+ *
+ * Strings are pre-interpolated at finding-creation time. There is no
+ * runtime template substitution — if a check needs to inject a name or
+ * count, it builds the string inline via template literals.
+ */
+export interface Localized {
+  en: string;
+  [lang: string]: string | undefined;
+}
+
+/**
+ * A single review finding. All three text fields (`title`, `detail`,
+ * `recommendation`) are required. Info-severity items whose recommendation
+ * is a no-op should still populate it with something like
+ * "No action required — surfaced for visibility."
+ */
+export interface Finding {
+  /** Stable machine identifier, e.g. `review.ux.forceful_transfers_allowed`. */
+  code: string;
+  severity: Severity;
+  source: FindingSource;
+  /** Free-form grouping label (e.g. `approvals`, `metadata`, `diff`). */
+  category: string;
+  /** Short label shown as the finding's headline. */
+  title: Localized;
+  /** Full explanation — the "why it matters" paragraph. */
+  detail: Localized;
+  /** How to fix it. Always populated. */
+  recommendation: Localized;
+  /**
+   * Agent-only escape hatch. When `true`, the finding is hidden from
+   * human consumers (frontend sidebar) but surfaced to agents
+   * (CLI / indexer / MCP). Default is `false` / absent — everyone sees
+   * the finding. Use sparingly for items that are genuinely
+   * agent-internal (e.g. meta-level tool feedback).
+   */
+  agentOnly?: boolean;
+}
+
+export interface ReviewContext {
+  /**
+   * Prior on-chain collection state. Required for diff checks
+   * (deleted approvals, tracker-id changes, claim plugin diffs) and
+   * for update-only suppressions. Everything else runs purely on the
+   * proposed collection's structure.
+   */
+  onChainCollection?: unknown;
+  /**
+   * Skip whole finding families by source. Frontend humans can pass
+   * `['audit']` to hide design-noise, but the default is to show
+   * everything. Agents typically omit this entirely.
+   */
+  skipSources?: FindingSource[];
+  /**
+   * When `true`, drop findings tagged `agentOnly: true`. Frontend
+   * human consumers set this. CLI / indexer / MCP callers leave it
+   * unset (agents see everything).
+   */
+  hideAgentOnly?: boolean;
+}
+
+export interface ReviewResult {
+  findings: Finding[];
+  summary: {
+    critical: number;
+    warning: number;
+    info: number;
+    verdict: 'pass' | 'warn' | 'fail';
+  };
+}
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/approvals.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/approvals.ts
new file mode 100644
index 0000000000..44f62665c2
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/approvals.ts
@@ -0,0 +1,678 @@
+/**
+ * Approval structural checks — ported from frontend reviewItems.ts.
+ * Covers mint-approval overrides, forceful transfers, max-transfer limits,
+ * claim structure, reset epochs, and wrapper-path prerequisites.
+ */
+
+import type { Finding } from '../review-types.js';
+import type { UxCheck } from './shared.js';
+import { MAX_UINT, getApprovals, getAllApprovals, isTransferabilityPermanentlyLocked } from './shared.js';
+
+export const approvalsChecks: UxCheck[] = [
+  // P5-1: fromListId "All" on non-mint approvals accidentally allows minting
+  (value) => {
+    const out: Finding[] = [];
+    const nonMint = getApprovals(value).filter((a: any) => a.fromListId !== 'Mint');
+    for (const approval of nonMint) {
+      if (approval.fromListId === 'All') {
+        const name = approval.approvalId || 'unnamed';
+        out.push({
+          code: 'review.ux.all_list_includes_mint',
+          severity: 'critical',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: `"${name}" uses fromListId "All" which includes Mint`
+          },
+          detail: {
+            en: 'The "All" address list includes the Mint address. This approval accidentally allows new tokens to be created from the Mint address. Use "!Mint" instead for approvals that should only govern tokens already in circulation.'
+          },
+          recommendation: {
+            en: 'Change fromListId from "All" to "!Mint" to exclude the Mint address'
+          }
+        });
+      }
+    }
+    return out;
+  },
+
+  // Mint approval missing overridesFromOutgoingApprovals (minting will fail)
+  (value) => {
+    const out: Finding[] = [];
+    const mint = getApprovals(value).filter((a: any) => a.fromListId === 'Mint');
+    for (const approval of mint) {
+      if (!approval.approvalCriteria?.overridesFromOutgoingApprovals) {
+        const name = approval.approvalId || 'unnamed';
+        out.push({
+          code: 'review.ux.mint_approval_missing_override',
+          severity: 'critical',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: `Mint approval "${name}" will fail`
+          },
+          detail: {
+            en: 'Mint approvals must have the outgoing override enabled. Without this, the Mint address cannot send tokens.'
+          },
+          recommendation: {
+            en: `Enable the outgoing override on mint approval "${name}"`
+          }
+        });
+      }
+    }
+    return out;
+  },
+
+  // Forceful override checks
+  (value) => {
+    const out: Finding[] = [];
+    const invariants = value?.invariants || {};
+    const nonMint = getApprovals(value).filter((a: any) => a.fromListId !== 'Mint');
+    const invariantBlocksForceful = !!invariants.noForcefulPostMintTransfers;
+    const forcefulApprovals = nonMint.filter((a: any) => {
+      if (a.approvalCriteria?.allowBackedMinting && a.approvalCriteria?.mustPrioritize) return false;
+      return (
+        a.approvalCriteria?.overridesFromOutgoingApprovals === true ||
+        a.approvalCriteria?.overridesToIncomingApprovals === true
+      );
+    });
+    const hasOverrides = forcefulApprovals.length > 0;
+
+    // Is canUpdateCollectionApprovals permanently forbidden with a
+    // true blanket scope? The helper below checks all 8 scope fields
+    // (fromListId / toListId / initiatedByListId / transferTimes /
+    // tokenIds / approvalId / amountTrackerId / challengeTrackerId)
+    // plus permanentlyForbiddenTimes covering forever. If so, no
+    // approvals can ever be added / removed / modified post-creation,
+    // and the "future approvals could enable forceful" finding is
+    // redundant — we append a note to that effect.
+    const transferabilityPermanentlyLocked = isTransferabilityPermanentlyLocked(value);
+
+    // Four outcome cases — one silent, three critical:
+    //   hasOverrides + !invariantBlocksForceful  → critical (tokens
+    //                                              can be moved without
+    //                                              holder consent; verify)
+    //   hasOverrides + invariantBlocksForceful   → critical (on-chain
+    //                                              failure at broadcast)
+    //   !hasOverrides + !invariantBlocksForceful → critical (invariant
+    //                                              can't be added later;
+    //                                              holders trust the
+    //                                              manager forever).
+    //                                              Exception: downgrade
+    //                                              to info when
+    //                                              transferability is
+    //                                              permanently locked.
+    //   !hasOverrides + invariantBlocksForceful  → silent (locked and
+    //                                              no overrides — safe)
+    if (hasOverrides && !invariantBlocksForceful) {
+      const names = forcefulApprovals
+        .map((a: any) => a.approvalId || 'unnamed')
+        .slice(0, 5)
+        .join(', ');
+      const more = forcefulApprovals.length > 5 ? ` (+${forcefulApprovals.length - 5} more)` : '';
+      out.push({
+        code: 'review.ux.forceful_transfers_allowed',
+        severity: 'critical',
+        source: 'ux',
+        category: 'approvals',
+        title: { en: 'Forceful transfer overrides enabled' },
+        detail: {
+          en: `${forcefulApprovals.length} non-mint approval(s) override outgoing or incoming consent: ${names}${more}. Tokens under these approvals can be moved without the holder's permission. This is a legitimate design choice for some flows (subscription revoke, auction settlement, prediction market resolution) — verify each listed approval is intentional.`
+        },
+        recommendation: {
+          en: 'Verify each listed approval is intentional. If any should not allow forceful transfers, remove its override flags.'
+        }
+      });
+    }
+
+    if (hasOverrides && invariantBlocksForceful) {
+      const names = forcefulApprovals
+        .map((a: any) => a.approvalId || 'unnamed')
+        .slice(0, 5)
+        .join(', ');
+      const more = forcefulApprovals.length > 5 ? ` (+${forcefulApprovals.length - 5} more)` : '';
+      out.push({
+        code: 'review.ux.forceful_override_mismatch',
+        severity: 'critical',
+        source: 'ux',
+        category: 'approvals',
+        title: {
+          en: 'Forceful transfer mismatch — overrides will fail on-chain'
+        },
+        detail: {
+          en: `${forcefulApprovals.length} non-mint approval(s) set overridesFromOutgoingApprovals or overridesToIncomingApprovals: ${names}${more}. The noForcefulPostMintTransfers invariant is ALSO set to true, which the chain interprets as "no approval may ever override consent." These overrides will be rejected on-chain at broadcast time.`
+        },
+        recommendation: {
+          en: 'If the listed approvals need forceful transfers (auction settlement, prediction market resolution, subscription revoke, etc.), set invariants.noForcefulPostMintTransfers = false (or leave unset). If forceful transfers should be permanently blocked, remove the override flags from the listed approvals.'
+        }
+      });
+    }
+
+    // Case B: no current forceful approvals but the invariant does
+    // not block them (explicitly false OR unset — either way, the
+    // collection permits forceful transfers post-mint). The invariant
+    // is locked at creation time, so any approval the manager adds
+    // later could introduce forceful transfers. Fires as `critical`
+    // because holders depend on transferability being stable and the
+    // current state is an unfixable trust assumption on the manager.
+    //
+    // Special case: if transferability is already permanently locked
+    // via a blanket canUpdateCollectionApprovals forbidden entry, the
+    // warning is neutralized (no future approvals can be added), so
+    // we downgrade to info and append a note.
+    if (!hasOverrides && !invariantBlocksForceful) {
+      // Distinguish explicit-false from unset so the text is accurate.
+      const invariantValue = invariants.noForcefulPostMintTransfers;
+      const isExplicitFalse = invariantValue === false;
+      const stateText = isExplicitFalse
+        ? 'This collection has noForcefulPostMintTransfers set to false, which permits forceful post-mint transfers.'
+        : 'The noForcefulPostMintTransfers invariant is not set, which by default permits forceful post-mint transfers.';
+      const baseDetail = `${stateText} No approvals currently enable them, but since the invariant is locked at creation time, any approval the manager adds later could introduce forceful transfers.`;
+      const suffix = transferabilityPermanentlyLocked
+        ? ' This is likely redundant in your case — canUpdateCollectionApprovals is permanently locked, so no future approvals can be added anyway.'
+        : '';
+      out.push({
+        code: 'review.ux.forceful_transfers_not_locked',
+        severity: transferabilityPermanentlyLocked ? 'info' : 'critical',
+        source: 'ux',
+        category: 'approvals',
+        title: { en: 'Forceful transfers are not permanently blocked' },
+        detail: { en: baseDetail + suffix },
+        recommendation: {
+          en: 'If forceful transfers should be permanently impossible, set invariants.noForcefulPostMintTransfers = true at creation — it cannot be toggled later. If forceful transfers are intentional for this collection (auction settlement, subscription revoke, prediction market resolution, etc.), you can safely ignore this.'
+        }
+      });
+    }
+
+    const backing = nonMint.filter(
+      (a: any) =>
+        a.approvalCriteria?.allowBackedMinting &&
+        a.approvalCriteria?.mustPrioritize &&
+        (a.approvalCriteria?.overridesFromOutgoingApprovals === true ||
+          a.approvalCriteria?.overridesToIncomingApprovals === true)
+    );
+    if (backing.length > 0) {
+      out.push({
+        code: 'review.ux.backing_approval_override_info',
+        severity: 'info',
+        source: 'ux',
+        category: 'approvals',
+        title: {
+          en: 'Backing approval has unnecessary overrides'
+        },
+        detail: {
+          en: 'Backing and unbacking approvals have transfer overrides enabled, but these are irrelevant for protocol-controlled backing addresses. It is recommended to remove them for clarity.'
+        },
+        recommendation: {
+          en: 'Remove the transfer override flags from the backing and unbacking approvals'
+        }
+      });
+    }
+    return out;
+  },
+
+  // autoApproveAllIncomingTransfers not true on mintable collections.
+  // Skipped on updates: defaultBalances is immutable post-creation,
+  // so flagging it on an existing collection is noise the user can't fix.
+  // Update detection is structural (collectionId !== '0'), not ctx-based —
+  // matches diff.ts and works for all callers (frontend, CLI, indexer, MCP).
+  (value) => {
+    const out: Finding[] = [];
+    // collectionId stays string because it's not a "number-typed field"
+    // in the Msg class — it's an ID. BigIntify doesn't convert it.
+    const isUpdate = value?.collectionId && value.collectionId !== '0';
+    if (isUpdate) return out;
+    const mint = getApprovals(value).filter((a: any) => a.fromListId === 'Mint');
+    if (mint.length > 0) {
+      const autoApprove = value?.defaultBalances?.autoApproveAllIncomingTransfers;
+      if (autoApprove !== true && autoApprove !== 'true') {
+        out.push({
+          code: 'review.ux.auto_approve_disabled_on_mintable',
+          severity: 'critical',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: 'Incoming transfers not auto-approved'
+          },
+          detail: {
+            en: 'This collection creates new tokens (it has approvals with fromListId: "Mint") but incoming transfers are not auto-approved. Recipients must opt-in before they can receive the created tokens, which means the creation flow will silently fail for most users.'
+          },
+          recommendation: {
+            en: 'Enable auto-approve for all incoming transfers in the default balance settings'
+          }
+        });
+      }
+    }
+    return out;
+  },
+
+  // P4-7: Infinite drain risk
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getApprovals(value)) {
+      const criteria = approval.approvalCriteria || {};
+      const hasCoinOverride = (criteria.coinTransfers || []).some((ct: any) => ct.overrideFromWithApproverAddress);
+      if (!hasCoinOverride) continue;
+      const mnt = criteria.maxNumTransfers || {};
+      const hasAnyLimit = [
+        'overallMaxNumTransfers',
+        'perToAddressMaxNumTransfers',
+        'perFromAddressMaxNumTransfers',
+        'perInitiatedByAddressMaxNumTransfers'
+      ].some((k) => mnt[k] !== undefined && mnt[k] !== 0n);
+      if (!hasAnyLimit) {
+        const name = approval.approvalId || 'unnamed';
+        out.push({
+          code: 'review.ux.infinite_drain_risk',
+          severity: 'critical',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: `Unlimited fund drain risk on "${name}"`
+          },
+          detail: {
+            en: 'This approval pays out from the escrow/approver on every transfer but has no transfer limit set. Anyone matching the approval can drain funds indefinitely.'
+          },
+          recommendation: {
+            en: 'Set a maximum number of transfers to cap the total payout'
+          }
+        });
+      }
+    }
+    return out;
+  },
+
+  // P4-9: Amount scaling with approver-funded coin transfers
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getApprovals(value)) {
+      const criteria = approval.approvalCriteria || {};
+      const incrementedBal = criteria.predeterminedBalances?.incrementedBalances;
+      if (!incrementedBal?.allowAmountScaling) continue;
+      const hasCoinOverride = (criteria.coinTransfers || []).some((ct: any) => ct.overrideFromWithApproverAddress);
+      if (hasCoinOverride) {
+        const name = approval.approvalId || 'unnamed';
+        out.push({
+          code: 'review.ux.amount_scaling_with_approver_funds',
+          severity: 'warning',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: `Amount scaling with approver-funded payments on "${name}"`
+          },
+          detail: {
+            en: 'This approval uses amount scaling with overrideFromWithApproverAddress. Users can multiply payment amounts drawn from the approver/escrow up to the maxScalingMultiplier. Verify that the per-use amount under scaling makes sense for your use case.'
+          },
+          recommendation: {
+            en: 'Verify maxScalingMultiplier is set to a reasonable cap and that the resulting per-use payout matches what the approval is meant to deliver.'
+          }
+        });
+      }
+    }
+    return out;
+  },
+
+  // P4-8: Per-user max exceeds overall max
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getApprovals(value)) {
+      const mnt = approval.approvalCriteria?.maxNumTransfers || {};
+      const overall = mnt.overallMaxNumTransfers;
+      if (overall === undefined || overall === 0n) continue;
+      for (const perKey of [
+        'perToAddressMaxNumTransfers',
+        'perFromAddressMaxNumTransfers',
+        'perInitiatedByAddressMaxNumTransfers'
+      ] as const) {
+        const perVal = mnt[perKey];
+        if (perVal !== undefined && perVal !== 0n && perVal > overall) {
+          const name = approval.approvalId || 'unnamed';
+          const perUser = String(perVal);
+          const overallStr = String(overall);
+          out.push({
+            code: 'review.ux.per_user_exceeds_overall',
+            severity: 'warning',
+            source: 'ux',
+            category: 'approvals',
+            title: {
+              en: `Per-user limit exceeds overall limit on "${name}"`
+            },
+            detail: {
+              en: `A per-user limit (${perUser}) is higher than the overall limit (${overallStr}). The per-user limit can never be reached since the overall limit will be hit first.`
+            },
+            recommendation: {
+              en: 'Set the per-user limit to be less than or equal to the overall limit'
+            }
+          });
+          break;
+        }
+      }
+    }
+    return out;
+  },
+
+  // Claims used — critical trust assumption
+  (value) => {
+    const out: Finding[] = [];
+    const hasClaims = getAllApprovals(value).some(
+      (a: any) =>
+        Array.isArray(a?.approvalCriteria?.merkleChallenges) &&
+        a.approvalCriteria.merkleChallenges.some((mc: any) => mc?.claimConfig || mc?.challengeInfoDetails?.claim)
+    );
+    if (hasClaims) {
+      out.push({
+        code: 'review.ux.collection_uses_claims',
+        severity: 'critical',
+        source: 'ux',
+        category: 'claims',
+        title: {
+          en: 'Collection uses claims'
+        },
+        detail: {
+          en: 'This collection uses off-chain claims, which introduces trust assumptions on BitBadges for managing claims and verifying criteria, as well as any third-party dependencies you add (passwords, codes, webhooks). Design accordingly, especially for high-value use cases. Design with off-chain failures in mind. For a fully on-chain or fully self-hosted solution, gate by your own on-chain dynamic store or by another token that you control.',
+          es: 'Esta colección utiliza reclamaciones fuera de cadena, lo que introduce suposiciones de confianza en BitBadges para gestionar reclamaciones y verificar criterios, así como cualquier dependencia de terceros que agregue (contraseñas, códigos, webhooks). Diseñe en consecuencia, especialmente para casos de alto valor. Diseñe teniendo en cuenta posibles fallos fuera de cadena. Para una solución completamente en cadena o auto-alojada, controle el acceso mediante su propio almacén dinámico en cadena o mediante otro token que usted controle.'
+        },
+        recommendation: {
+          en: 'If trust assumptions are unacceptable, consider using on-chain-only criteria instead of off-chain claims'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Claim without initiatedBy plugin — no sign-in verification
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getAllApprovals(value)) {
+      const challenges: any[] = approval.approvalCriteria?.merkleChallenges || [];
+      for (const mc of challenges) {
+        const plugins: any[] = mc?.claimConfig?.plugins || [];
+        if (plugins.length === 0) continue;
+        const hasInitiatedBy = plugins.some((p: any) => p.pluginId === 'initiatedBy');
+        if (!hasInitiatedBy) {
+          const label = mc.claimConfig?.label || approval.approvalId || 'unnamed';
+          out.push({
+            code: 'review.ux.claim_missing_signin',
+            severity: 'critical',
+            source: 'ux',
+            category: 'claims',
+            title: {
+              en: `Claim "${label}" has no sign-in requirement`
+            },
+            detail: {
+              en: 'Claims default to no sign-in required. Without the sign-in plugin, anyone can claim without proving they own an address. For claims linked to on-chain transfers, sign-in is essential because users must sign the eventual transaction.'
+            },
+            recommendation: {
+              en: `Add the sign-in requirement plugin to the "${label}" claim`
+            }
+          });
+        }
+      }
+    }
+    return out;
+  },
+
+  // Claim numUses vs on-chain overallMaxNumTransfers mismatch
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getApprovals(value)) {
+      const challenges: any[] = approval.approvalCriteria?.merkleChallenges || [];
+      const onChainMax = approval.approvalCriteria?.maxNumTransfers?.overallMaxNumTransfers;
+      for (const mc of challenges) {
+        const plugins: any[] = mc?.claimConfig?.plugins || [];
+        const numUsesPlugin = plugins.find((p: any) => p.pluginId === 'numUses');
+        if (!numUsesPlugin) continue;
+        const offChainMax = numUsesPlugin.publicParams?.maxUses;
+        if (offChainMax == null || onChainMax == null || onChainMax === 0n) continue;
+        if (Number(offChainMax) !== Number(onChainMax)) {
+          const label = mc.claimConfig?.label || approval.approvalId || 'unnamed';
+          const offChain = Number(offChainMax);
+          const onChain = Number(onChainMax);
+          out.push({
+            code: 'review.ux.claim_numuses_mismatch',
+            severity: 'critical',
+            source: 'ux',
+            category: 'claims',
+            title: {
+              en: `Claim "${label}" has mismatched limits`
+            },
+            detail: {
+              en: `The claim allows ${offChain} uses but the on-chain transfer limit is ${onChain}. These must match — otherwise users can claim off-chain but fail on-chain, or on-chain slots go unused.`
+            },
+            recommendation: {
+              en: `Set both the claim max uses and the on-chain transfer limit to the same value for "${label}"`
+            }
+          });
+        }
+      }
+    }
+    return out;
+  },
+
+  // P5-6: Claim maxUsesPerLeaf should be "1"
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getAllApprovals(value)) {
+      const challenges: any[] = approval.approvalCriteria?.merkleChallenges || [];
+      for (const mc of challenges) {
+        if (
+          mc.claimConfig?.plugins?.length > 0 &&
+          mc.maxUsesPerLeaf !== undefined &&
+          mc.maxUsesPerLeaf !== 1n &&
+          mc.maxUsesPerLeaf !== 0n
+        ) {
+          const label = mc.claimConfig?.label || approval.approvalId || 'unnamed';
+          out.push({
+            code: 'review.ux.claim_replay_risk',
+            severity: 'warning',
+            source: 'ux',
+            category: 'claims',
+            title: {
+              en: `Claim "${label}" may be vulnerable to replay`
+            },
+            detail: {
+              en: 'maxUsesPerLeaf is not set to 1. Without this, the same claim proof could be reused multiple times.'
+            },
+            recommendation: {
+              en: 'Set maxUsesPerLeaf to 1 to ensure each claim code can only be used once'
+            }
+          });
+        }
+      }
+    }
+    return out;
+  },
+
+  // P5-7: allowCounterpartyPurge requires single-address initiatedByList
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getApprovals(value)) {
+      if (!approval.approvalCriteria?.autoDeletionOptions?.allowCounterpartyPurge) continue;
+      const listId = approval.initiatedByListId || '';
+      const isSingleAddress = /^bb1[a-z0-9]+$/.test(listId);
+      if (!isSingleAddress) {
+        const name = approval.approvalId || 'unnamed';
+        out.push({
+          code: 'review.ux.counterparty_purge_multi_address',
+          severity: 'warning',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: `Counterparty purge on "${name}" requires single-address initiator`
+          },
+          detail: {
+            en: 'allowCounterpartyPurge is enabled but the initiatedByList is not a single address. The chain requires exactly one address to have purge rights.'
+          },
+          recommendation: {
+            en: 'Set initiatedByListId to a single bb1 address for counterparty purge to work'
+          }
+        });
+      }
+    }
+    return out;
+  },
+
+  // P5-8: Default balances must be auto-scan compatible
+  (value) => {
+    const out: Finding[] = [];
+    const defaultIncoming: any[] = value?.defaultBalances?.incomingApprovals || [];
+    const defaultOutgoing: any[] = value?.defaultBalances?.outgoingApprovals || [];
+    for (const da of [...defaultIncoming, ...defaultOutgoing]) {
+      const c = da.approvalCriteria || {};
+      const hasNonScannable =
+        (c.coinTransfers?.length > 0) ||
+        (c.merkleChallenges?.length > 0) ||
+        (c.ethSignatureChallenges?.length > 0) ||
+        (c.predeterminedBalances?.incrementedBalances?.startBalances?.length > 0) ||
+        (c.predeterminedBalances?.manualBalances?.length > 0);
+      if (hasNonScannable) {
+        out.push({
+          code: 'review.ux.default_balance_not_scannable',
+          severity: 'warning',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: 'Default balance approvals not auto-scan compatible'
+          },
+          detail: {
+            en: 'Default balance approvals contain features that are not compatible with auto-scan mode (coin transfers, claims, predetermined balances, or signature challenges). These are creation-only and may cause issues.'
+          },
+          recommendation: {
+            en: 'Simplify default balance approvals to only use basic transfer rules without complex criteria'
+          }
+        });
+        return out;
+      }
+    }
+    return out;
+  },
+
+  // Wrapper path transferability + approval prerequisite
+  (value) => {
+    const out: Finding[] = [];
+    const wrapperPaths: any[] = value?.cosmosCoinWrapperPathsToAdd || value?.cosmosCoinWrapperPaths || [];
+    if (wrapperPaths.length === 0) return out;
+    out.push({
+      code: 'review.ux.wrapper_path_transferability',
+      severity: 'warning',
+      source: 'ux',
+      category: 'approvals',
+      title: {
+        en: 'Cosmos wrapper paths — transferability caveat'
+      },
+      detail: {
+        en: "This collection has cosmos wrapper paths. Once tokens are wrapped to ICS20, they are freely transferable via IBC regardless of your collection's transfer rules. BitBadges transferability only applies in the siloed (unwrapped) environment."
+      },
+      recommendation: {
+        en: 'Ensure transfer restrictions are enforced before wrapping, not after'
+      }
+    });
+    const hasWrapApproval = getApprovals(value).some((a: any) => a.approvalCriteria?.allowSpecialWrapping === true);
+    if (!hasWrapApproval) {
+      out.push({
+        code: 'review.ux.wrapper_path_missing_approval',
+        severity: 'critical',
+        source: 'ux',
+        category: 'approvals',
+        title: {
+          en: 'Cosmos wrapper path but no wrapping approval'
+        },
+        detail: {
+          en: 'Wrapper paths are configured but no approval has allowSpecialWrapping enabled. Wrapping and unwrapping will not function without this.'
+        },
+        recommendation: {
+          en: 'Add approvals with allowSpecialWrapping: true and mustPrioritize: true targeting the wrapper address'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Reset interval with startTime = 0
+  (value) => {
+    const out: Finding[] = [];
+    const seen = new Set<string>();
+    for (const approval of getAllApprovals(value)) {
+      const criteria = approval.approvalCriteria || {};
+      for (const field of ['approvalAmounts', 'maxNumTransfers'] as const) {
+        const rti = criteria[field]?.resetTimeIntervals;
+        if (!rti) continue;
+        const interval = rti.intervalLength ?? 0n;
+        const start = rti.startTime ?? 0n;
+        if (interval !== 0n && start === 0n) {
+          const name = approval.approvalId || 'unnamed';
+          const key = name;
+          if (seen.has(key)) break;
+          seen.add(key);
+          out.push({
+            code: 'review.ux.reset_epoch_zero',
+            severity: 'warning',
+            source: 'ux',
+            category: 'approvals',
+            title: {
+              en: `Reset interval on "${name}" uses epoch start time`
+            },
+            detail: {
+              en: 'This approval has a time-based reset interval but the start time is set to 0 (January 1, 1970). This means resets happen at fixed UTC midnight boundaries, and users could exploit the boundary by making two withdrawals minutes apart across a reset. Use a recent timestamp as the start time instead.'
+            },
+            recommendation: {
+              en: 'Change the reset start time to a recent timestamp (use get_current_timestamp) instead of 0'
+            }
+          });
+          break;
+        }
+      }
+    }
+    return out;
+  },
+
+  // Royalty missing percentage or address
+  (value) => {
+    const out: Finding[] = [];
+    for (const approval of getApprovals(value)) {
+      const royalty = approval.approvalCriteria?.userRoyalties;
+      if (!royalty) continue;
+      const hasPercentage = royalty.percentage !== undefined && royalty.percentage !== 0n;
+      const hasAddress = royalty.payoutAddress && royalty.payoutAddress !== '';
+      const name = approval.approvalId || 'unnamed';
+      if (hasPercentage && !hasAddress) {
+        out.push({
+          code: 'review.ux.royalty_missing_address',
+          severity: 'warning',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: `Royalty on "${name}" has no payout address`
+          },
+          detail: {
+            en: 'A royalty percentage is set but no payout address. Royalties will not be sent anywhere.'
+          },
+          recommendation: {
+            en: 'Set a payout address for the royalty'
+          }
+        });
+      }
+      if (!hasPercentage && hasAddress) {
+        out.push({
+          code: 'review.ux.royalty_missing_percentage',
+          severity: 'warning',
+          source: 'ux',
+          category: 'approvals',
+          title: {
+            en: `Royalty on "${name}" has no percentage`
+          },
+          detail: {
+            en: 'A royalty payout address is set but the percentage is zero. No royalties will be collected.'
+          },
+          recommendation: {
+            en: 'Set a royalty percentage or remove the payout address'
+          }
+        });
+      }
+    }
+    return out;
+  }
+];
+
+// Exported constant reference to keep MAX_UINT imported (used by diff/permissions modules).
+export const _MAX_UINT = MAX_UINT;
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/diff.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/diff.ts
new file mode 100644
index 0000000000..b23f09d251
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/diff.ts
@@ -0,0 +1,163 @@
+/**
+ * On-chain diff checks — compare the proposed transaction against the existing
+ * on-chain collection passed via ReviewContext.onChainCollection.
+ *
+ * Ported from the update-specific section of frontend reviewItems.ts.
+ */
+
+import type { Finding } from '../review-types.js';
+import type { UxCheck } from './shared.js';
+
+function normalizeOnChain(oc: any): any {
+  if (!oc || typeof oc !== 'object') return oc;
+  // Frontend hydrated shape already has collectionApprovals at the top level.
+  // Indexer cache shape may wrap the actual collection under a `collection` key.
+  if (Array.isArray(oc.collectionApprovals)) return oc;
+  if (oc.collection && typeof oc.collection === 'object') return oc.collection;
+  return oc;
+}
+
+export const diffChecks: UxCheck[] = [
+  (value, ctx) => {
+    const out: Finding[] = [];
+    const onChain = normalizeOnChain(ctx.onChainCollection);
+    // collectionId is an ID, stays string (BigIntify doesn't touch it)
+    const isUpdate = value?.collectionId && value.collectionId !== '0' && value?.updateCollectionApprovals;
+    if (!isUpdate || !onChain) return out;
+
+    const onChainApprovals: any[] = onChain.collectionApprovals || [];
+    const proposedApprovals: any[] = value.collectionApprovals || [];
+
+    // Deleted approvals
+    const proposedIds = new Set(proposedApprovals.map((a: any) => a.approvalId));
+    const deleted = onChainApprovals.filter((a: any) => a.approvalId && !proposedIds.has(a.approvalId));
+    if (deleted.length > 0) {
+      const names = deleted.map((a: any) => a.approvalId).slice(0, 3).join(', ');
+      const count = deleted.length;
+      out.push({
+        code: 'review.ux.diff_deleted_approvals',
+        severity: 'critical',
+        source: 'ux',
+        category: 'diff',
+        title: {
+          en: 'Existing approval rules removed'
+        },
+        detail: {
+          en: `${count} existing approval rule(s) will be removed: ${names}. All accumulated state (claim counts, transfer limits) for these rules will be lost.`
+        },
+        recommendation: {
+          en: 'If this is unintentional, add the removed approval rules back with their original IDs'
+        }
+      });
+    }
+
+    // Tracker ID changes
+    const onChainById = new Map(onChainApprovals.map((a: any) => [a.approvalId, a]));
+    for (const proposed of proposedApprovals) {
+      const existing: any = onChainById.get(proposed.approvalId);
+      if (!existing) continue;
+      const ec = existing.approvalCriteria || {};
+      const pc = proposed.approvalCriteria || {};
+      const changes: string[] = [];
+
+      const et = ec.maxNumTransfers?.amountTrackerId;
+      const pt = pc.maxNumTransfers?.amountTrackerId;
+      if (et && et !== pt) changes.push('transfer tracker');
+
+      const ea = ec.approvalAmounts?.amountTrackerId;
+      const pa = pc.approvalAmounts?.amountTrackerId;
+      if (ea && ea !== pa) changes.push('amount tracker');
+
+      const ech = ec.predeterminedBalances?.orderCalculationMethod?.challengeTrackerId;
+      const pch = pc.predeterminedBalances?.orderCalculationMethod?.challengeTrackerId;
+      if (ech && ech !== pch) changes.push('challenge tracker');
+
+      if (changes.length > 0) {
+        const name = proposed.approvalId;
+        const trackers = changes.join(', ');
+        out.push({
+          code: 'review.ux.diff_tracker_id_changed',
+          severity: 'critical',
+          source: 'ux',
+          category: 'diff',
+          title: {
+            en: `Tracker ID changed on "${name}"`
+          },
+          detail: {
+            en: `The ${trackers} ID was changed on an existing approval. This loses all accumulated state (used claims, transfer counts, amount tracking). If you want a fresh state, create a new approval instead.`
+          },
+          recommendation: {
+            en: `Restore the original tracker IDs on "${name}" to preserve on-chain state`
+          }
+        });
+      }
+    }
+
+    // Claim plugin diffs
+    for (const proposed of proposedApprovals) {
+      const existing: any = onChainById.get(proposed.approvalId);
+      if (!existing) continue;
+      const existingChallenges: any[] = existing.approvalCriteria?.merkleChallenges || [];
+      const proposedChallenges: any[] = proposed.approvalCriteria?.merkleChallenges || [];
+      for (let ci = 0; ci < Math.max(existingChallenges.length, proposedChallenges.length); ci++) {
+        const eMc = existingChallenges[ci];
+        const pMc = proposedChallenges[ci];
+        const ePlugins: any[] = eMc?.claimConfig?.plugins || [];
+        const pPlugins: any[] = pMc?.claimConfig?.plugins || [];
+        const claimLabel = pMc?.claimConfig?.label || eMc?.claimConfig?.label || proposed.approvalId || 'unnamed';
+        if (ePlugins.length === 0 && pPlugins.length === 0) continue;
+
+        const pByInstance = new Map(pPlugins.filter((p: any) => p.instanceId).map((p: any) => [p.instanceId, p]));
+
+        const deletedPlugins = ePlugins.filter((p: any) => p.instanceId && !pByInstance.has(p.instanceId));
+        if (deletedPlugins.length > 0) {
+          const names = deletedPlugins.map((p: any) => p.pluginId).join(', ');
+          out.push({
+            code: 'review.ux.diff_claim_plugins_deleted',
+            severity: 'warning',
+            source: 'ux',
+            category: 'diff',
+            title: {
+              en: `Claim plugins removed on "${claimLabel}"`
+            },
+            detail: {
+              en: `The following claim plugins were removed: ${names}. This may invalidate existing claim flows and affect users who have already started claiming.`
+            },
+            recommendation: {
+              en: 'Verify that removing these plugins is intentional and won\'t break existing claim flows'
+            }
+          });
+        }
+
+        const eByInstance = new Map(ePlugins.filter((p: any) => p.instanceId).map((p: any) => [p.instanceId, p]));
+        for (const pp of pPlugins) {
+          if (!pp.instanceId) continue;
+          const ep: any = eByInstance.get(pp.instanceId);
+          if (!ep) continue;
+          const paramsChanged =
+            JSON.stringify(ep.publicParams) !== JSON.stringify(pp.publicParams) ||
+            JSON.stringify(ep.privateParams) !== JSON.stringify(pp.privateParams);
+          if (paramsChanged) {
+            out.push({
+              code: 'review.ux.diff_claim_plugin_params_changed',
+              severity: 'warning',
+              source: 'ux',
+              category: 'diff',
+              title: {
+                en: `Claim plugin "${pp.pluginId}" params changed on "${claimLabel}"`
+              },
+              detail: {
+                en: 'The parameters for this claim plugin were modified. This may affect existing claim state and could cause mismatches between off-chain claims and on-chain limits.'
+              },
+              recommendation: {
+                en: 'Verify the parameter changes are intentional and won\'t cause state mismatches with on-chain counters'
+              }
+            });
+          }
+        }
+      }
+    }
+
+    return out;
+  }
+];
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/index.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/index.ts
new file mode 100644
index 0000000000..4df15c79f2
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/index.ts
@@ -0,0 +1,40 @@
+/**
+ * Review UX check registry.
+ *
+ * `runUxChecks()` executes every ported frontend UX check and returns a flat
+ * list of {@link Finding}s. Each check file exports an array of `UxCheck`
+ * pure functions keyed by domain.
+ */
+
+import type { Finding, ReviewContext } from '../review-types.js';
+import type { UxCheck } from './shared.js';
+import { approvalsChecks } from './approvals.js';
+import { metadataChecks } from './metadata.js';
+import { permissionsChecks } from './permissions.js';
+import { diffChecks } from './diff.js';
+import { skillChecks } from './skills.js';
+import { registriesChecks } from './registries.js';
+
+const ALL_CHECKS: UxCheck[] = [
+  ...approvalsChecks,
+  ...metadataChecks,
+  ...permissionsChecks,
+  ...diffChecks,
+  ...skillChecks,
+  ...registriesChecks
+];
+
+export function runUxChecks(value: unknown, context: ReviewContext): Finding[] {
+  const out: Finding[] = [];
+  for (const check of ALL_CHECKS) {
+    try {
+      const res = check(value, context);
+      if (res && res.length) out.push(...res);
+    } catch {
+      // Individual check failure must not kill the whole review
+    }
+  }
+  return out;
+}
+
+export { approvalsChecks, metadataChecks, permissionsChecks, diffChecks, skillChecks, registriesChecks };
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/metadata.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/metadata.ts
new file mode 100644
index 0000000000..f94a38cd56
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/metadata.ts
@@ -0,0 +1,186 @@
+/**
+ * Metadata / image placeholder checks — ported from frontend reviewItems.ts.
+ */
+
+import type { Finding } from '../review-types.js';
+import type { UxCheck } from './shared.js';
+import { isPlaceholderImage, isMissingImage, PLACEHOLDER_PATTERNS, getApprovals } from './shared.js';
+
+// System approvals generated by SDK builders / AI builder tools that
+// don't need a custom display name — the ID itself is self-documenting
+// and the frontend renders a canonical label for each. Matched by
+// PREFIX because the AI builder tool appends a random hex suffix
+// (e.g. `smart-token-backing_5745316c`).
+const KNOWN_SYSTEM_APPROVAL_PREFIXES = [
+  'transferable-approval',
+  'transferable',
+  'burnable-approval',
+  'burnable',
+  // Two naming conventions in the SDK: core/builders uses
+  // smart-account-*, builder/tools/components uses smart-token-*.
+  // Accept either.
+  'smart-account-backing',
+  'smart-account-unbacking',
+  'smart-token-backing',
+  'smart-token-unbacking',
+  'quests-approval',
+  'credit-scaled',
+  // AuctionRegistry / PredictionMarketRegistry / CrowdfundRegistry /
+  // VaultApprovalRegistry approvals all use the prefix-<hex> pattern.
+  'auction-mint-to-winner',
+  'auction-burn',
+  'pm-mint',
+  'pm-redeem',
+  'pm-settle-yes',
+  'pm-settle-no',
+  'pm-settle-push-yes',
+  'pm-settle-push-no',
+  'pm-transfer',
+  'crowdfund-deposit-refund',
+  'crowdfund-deposit-progress',
+  'crowdfund-success',
+  'crowdfund-refund',
+  'crowdfund-burn',
+  'vault-deposit',
+  'vault-withdraw',
+  'vault-internal-transfer',
+  'vault-emergency-migration',
+  'manager-add',
+  'manager-remove'
+];
+
+function isKnownSystemApproval(id: string): boolean {
+  return KNOWN_SYSTEM_APPROVAL_PREFIXES.some(
+    (prefix) => id === prefix || id.startsWith(prefix + '_') || id.startsWith(prefix + '-')
+  );
+}
+
+export const metadataChecks: UxCheck[] = [
+  // Placeholder images in metadataPlaceholders (excluding approval metadata)
+  (value) => {
+    const out: Finding[] = [];
+    // metadataPlaceholders lives at value._meta.metadataPlaceholders —
+    // per-msg sidecar keyed by URI strings inside the msg body.
+    // review-normalize.ts reattaches `_meta` after the proto class
+    // conversion strips it, so this lookup is safe after normalization.
+    const metadataPlaceholders: Record<string, { name?: string; description?: string; image?: string }> =
+      value?._meta?.metadataPlaceholders || {};
+    const placeholderImageEntries = Object.entries(metadataPlaceholders).filter(
+      ([key, meta]) => !key.includes('METADATA_APPROVAL_') && isPlaceholderImage(meta?.image)
+    );
+    if (placeholderImageEntries.length > 0) {
+      const count = placeholderImageEntries.length;
+      out.push({
+        code: 'review.ux.placeholder_images',
+        severity: 'info',
+        source: 'ux',
+        category: 'metadata',
+        title: {
+          en: 'Metadata uses placeholder or default images'
+        },
+        detail: {
+          en: `${count} metadata entries use placeholder images or the default BitBadges logo. Consider uploading custom images for a more polished look.`
+        },
+        recommendation: {
+          en: 'Upload custom images for your collection and token metadata'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Unnamed approvals
+  (value) => {
+    const out: Finding[] = [];
+    const approvals = getApprovals(value);
+    const metadataPlaceholders: Record<string, { name?: string }> = value?._meta?.metadataPlaceholders || {};
+    const unnamed = approvals.filter((a: any) => {
+      const id = a.approvalId || '';
+      if (id.startsWith('default-') || id === '') return false;
+      if (isKnownSystemApproval(id)) return false;
+      if (a.details?.name) return false;
+      const uri = a.uri || '';
+      if (!uri) return true;
+      const placeholder = metadataPlaceholders[uri];
+      if (placeholder && placeholder.name) return false;
+      return PLACEHOLDER_PATTERNS.some((p) => p.test(uri)) && !placeholder?.name;
+    });
+    if (unnamed.length > 0) {
+      const names =
+        unnamed.map((a: any) => a.approvalId || 'unnamed').slice(0, 3).join(', ') +
+        (unnamed.length > 3 ? ` (+${unnamed.length - 3})` : '');
+      out.push({
+        code: 'review.ux.unnamed_approvals',
+        severity: 'info',
+        source: 'ux',
+        category: 'metadata',
+        title: {
+          en: 'Some approval rules are missing names'
+        },
+        detail: {
+          en: `The following approval rules don't have a display name or description: ${names}. Adding names helps users understand what each rule does.`
+        },
+        recommendation: {
+          en: 'Add descriptive names and descriptions to all approval rules'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Alias paths without images
+  //
+  // Images for alias paths live inside the off-chain JSON referenced by
+  // metadata.uri — NOT on the proto. This check looks in the right place:
+  // the metadataPlaceholders sidecar keyed by the path/unit uri, which is
+  // what the auto-apply flow consumes. If the sidecar is missing for the
+  // relevant placeholder, the path will deploy without an image.
+  //
+  // Legacy .metadata.image fields on the proto are a shape error, not a
+  // "missing image" — verifyStandards already throws on that path.
+  (value) => {
+    const out: Finding[] = [];
+    const aliasPaths: any[] = value?.aliasPaths || value?.aliasPathsToAdd || [];
+    const metadataPlaceholders: Record<string, { image?: string }> = value?._meta?.metadataPlaceholders || {};
+    const missing = aliasPaths.filter((path: any) => {
+      const denomUnits: any[] = path.denomUnits || [];
+      const defaultUnit = denomUnits.find((u: any) => u.isDefaultDisplay);
+      const unitMeta = defaultUnit?.metadata;
+      const pathMeta = path.metadata;
+      // Three places a path image can live:
+      //   1. metadataPlaceholders sidecar keyed by pathMeta.uri (agent shape)
+      //   2. Same sidecar keyed by unitMeta.uri (denom unit variant)
+      //   3. Inline nested metadata.metadata.image (frontend WithDetails
+      //      shape, pre-upload state — the auto-apply flow will move this
+      //      to an IPFS URI on submit)
+      const pathUri: string = pathMeta?.uri || '';
+      const unitUri: string = unitMeta?.uri || '';
+      const pathSidecarImage = metadataPlaceholders[pathUri]?.image;
+      const unitSidecarImage = metadataPlaceholders[unitUri]?.image;
+      const pathInlineImage = pathMeta?.metadata?.image;
+      const unitInlineImage = unitMeta?.metadata?.image;
+      const pathOk = !isMissingImage(pathSidecarImage) || !isMissingImage(pathInlineImage);
+      const unitOk = !isMissingImage(unitSidecarImage) || !isMissingImage(unitInlineImage);
+      return !pathOk && !unitOk;
+    });
+    if (missing.length > 0) {
+      const count = missing.length;
+      out.push({
+        code: 'review.ux.alias_paths_missing_images',
+        severity: 'info',
+        source: 'ux',
+        category: 'metadata',
+        title: {
+          en: 'Alias paths missing display images'
+        },
+        detail: {
+          en: `${count} alias paths are missing a metadata image for the display unit. This image is shown when users view the token in wallets and exchanges.`
+        },
+        recommendation: {
+          en: 'Add metadata images to all alias path display units'
+        }
+      });
+    }
+    return out;
+  }
+];
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/permissions.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/permissions.ts
new file mode 100644
index 0000000000..0f47882b15
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/permissions.ts
@@ -0,0 +1,78 @@
+/**
+ * Permission-related UX checks — ported from frontend reviewItems.ts.
+ */
+
+import type { Finding } from '../review-types.js';
+import type { UxCheck } from './shared.js';
+import { MAX_UINT } from './shared.js';
+
+export const permissionsChecks: UxCheck[] = [
+  // permanentlyPermittedTimes set to FOREVER on permissions
+  (value) => {
+    const out: Finding[] = [];
+    const permissions = value?.collectionPermissions || {};
+    for (const [permName, permEntries] of Object.entries(permissions)) {
+      if (!Array.isArray(permEntries)) continue;
+      let flagged = false;
+      for (const entry of permEntries as any[]) {
+        const pt = entry.permanentlyPermittedTimes;
+        if (
+          Array.isArray(pt) &&
+          pt.some((t: any) => t.start === 1n && t.end === MAX_UINT)
+        ) {
+          flagged = true;
+          break;
+        }
+      }
+      if (flagged) {
+        out.push({
+          code: 'review.ux.permission_permanently_permitted_' + permName.toLowerCase(),
+          severity: 'warning',
+          source: 'ux',
+          category: 'permissions',
+          title: {
+            en: `Permission "${permName}" is permanently permitted`
+          },
+          detail: {
+            en: 'This permission can never be locked or frozen in the future. Use neutral (empty) permissions instead to preserve the flexibility to lock it later.'
+          },
+          recommendation: {
+            en: 'Change the permission to neutral (empty array) instead of permanently permitted'
+          }
+        });
+      }
+    }
+    return out;
+  },
+
+  // Backed path requires Mint approval permissions locked
+  (value) => {
+    const out: Finding[] = [];
+    const invariants = value?.invariants || {};
+    if (!invariants.cosmosCoinBackedPath) return out;
+    const permEntries: any[] = value?.collectionPermissions?.canUpdateCollectionApprovals || [];
+    const hasMintLock = permEntries.some((e: any) => {
+      const ft = e.permanentlyForbiddenTimes;
+      const isForbidden = Array.isArray(ft) && ft.some((t: any) => t.start === 1n && t.end === MAX_UINT);
+      return isForbidden && (e.fromListId === 'Mint' || e.fromListId === 'All');
+    });
+    if (!hasMintLock) {
+      out.push({
+        code: 'review.ux.backed_path_mint_not_locked',
+        severity: 'warning',
+        source: 'ux',
+        category: 'permissions',
+        title: {
+          en: 'Backed path but Mint permissions not locked'
+        },
+        detail: {
+          en: 'This collection uses IBC-backed minting but the permission to update Mint approvals is not permanently locked. The manager could add unauthorized mint approvals later.'
+        },
+        recommendation: {
+          en: 'Lock the permission to update Mint address approvals'
+        }
+      });
+    }
+    return out;
+  }
+];
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/registries.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/registries.ts
new file mode 100644
index 0000000000..946b1a4590
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/registries.ts
@@ -0,0 +1,56 @@
+/**
+ * Registry/reserved collision checks.
+ *
+ * Uses SDK's MAINNET_COINS_REGISTRY + TESTNET_COINS_REGISTRY (which is the same
+ * underlying data the frontend's `CoinsRegistry` proxies over).
+ */
+
+import type { Finding } from '../review-types.js';
+import type { UxCheck } from './shared.js';
+import { MAINNET_COINS_REGISTRY, TESTNET_COINS_REGISTRY } from '../../common/constants.js';
+
+const RESERVED_COIN_SYMBOLS: Set<string> = new Set(
+  [...Object.values(MAINNET_COINS_REGISTRY), ...Object.values(TESTNET_COINS_REGISTRY)]
+    .map((c: any) => (c.symbol || '').toUpperCase())
+    .filter((s: string) => s.length > 0)
+);
+
+export const registriesChecks: UxCheck[] = [
+  // Alias path symbols collide with reserved/registered coin symbols
+  (value) => {
+    const out: Finding[] = [];
+    const aliasPaths: any[] = value?.aliasPaths || value?.aliasPathsToAdd || [];
+    const conflicting = aliasPaths.filter((path: any) => {
+      const denomUnits: any[] = path.denomUnits || [];
+      return denomUnits.some(
+        (u: any) => u.symbol && RESERVED_COIN_SYMBOLS.has(u.symbol.toUpperCase())
+      );
+    });
+    if (conflicting.length > 0) {
+      const symbols = conflicting
+        .flatMap((p: any) =>
+          (p.denomUnits || [])
+            .filter((u: any) => u.symbol && RESERVED_COIN_SYMBOLS.has(u.symbol.toUpperCase()))
+            .map((u: any) => u.symbol)
+        )
+        .slice(0, 3);
+      const symbolsJoined = symbols.join('", "');
+      out.push({
+        code: 'review.ux.alias_symbol_reserved_collision',
+        severity: 'warning',
+        source: 'ux',
+        category: 'registries',
+        title: {
+          en: 'Alias symbol conflicts with an existing coin'
+        },
+        detail: {
+          en: `The symbols "${symbolsJoined}" match existing registered coins on the network. This can cause confusion. Use unique symbols with a "w" prefix instead.`
+        },
+        recommendation: {
+          en: 'Rename the conflicting alias symbols to avoid confusion with existing coins (e.g., prefix with "w")'
+        }
+      });
+    }
+    return out;
+  }
+];
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/shared.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/shared.ts
new file mode 100644
index 0000000000..7c893e2199
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/shared.ts
@@ -0,0 +1,100 @@
+/**
+ * Shared helpers for review-ux check modules.
+ */
+
+import type { Finding, ReviewContext } from '../review-types.js';
+
+export type UxCheck = (value: any, context: ReviewContext) => Finding[];
+
+export const MAX_UINT = 18446744073709551615n;
+
+export const BITBADGES_DEFAULT_LOGO = 'QmNTpizCkY5tcMpPMf1kkn7Y5YxFQo3oT54A9oKP5ijP9E';
+
+export const PLACEHOLDER_PATTERNS: RegExp[] = [
+  /^ipfs:\/\/METADATA_/i,
+  /^ipfs:\/\/IMAGE_\d+$/i,
+  /^placeholder/i,
+  /^https?:\/\/example\.com/i,
+  /^$/
+];
+
+export function isPlaceholderImage(image: string | undefined): boolean {
+  if (!image) return true;
+  if (image.includes(BITBADGES_DEFAULT_LOGO)) return true;
+  return PLACEHOLDER_PATTERNS.some((p) => p.test(image));
+}
+
+export function isMissingImage(image: string | undefined): boolean {
+  if (!image) return true;
+  if (image.includes(BITBADGES_DEFAULT_LOGO)) return false;
+  return PLACEHOLDER_PATTERNS.some((p) => p.test(image));
+}
+
+export function getApprovals(value: any): any[] {
+  return Array.isArray(value?.collectionApprovals) ? value.collectionApprovals : [];
+}
+
+export function getAllApprovals(value: any): any[] {
+  const approvals = getApprovals(value);
+  const inc = Array.isArray(value?.defaultBalances?.incomingApprovals)
+    ? value.defaultBalances.incomingApprovals
+    : [];
+  const out = Array.isArray(value?.defaultBalances?.outgoingApprovals)
+    ? value.defaultBalances.outgoingApprovals
+    : [];
+  return [...approvals, ...inc, ...out];
+}
+
+/**
+ * True if a UintRange array covers the full uint64 range (start=1 → end=MAX).
+ * Treats an empty/undefined array as NOT covering full (the chain's default
+ * for a forbidden-times list; the check below uses that as "not locked").
+ */
+function isForeverRange(ranges: any): boolean {
+  if (!Array.isArray(ranges) || ranges.length === 0) return false;
+  return ranges.some((r: any) => r?.start === 1n && r?.end === MAX_UINT);
+}
+
+/**
+ * True if a `canUpdateCollectionApprovals` permission entry represents
+ * a BLANKET permanent lock — that is, every scope field is set to its
+ * "match anything" wildcard AND `permanentlyForbiddenTimes` covers
+ * forever. The full set of scope fields on a CollectionApprovalPermission:
+ *
+ *   fromListId           === 'All'
+ *   toListId             === 'All'
+ *   initiatedByListId    === 'All'
+ *   transferTimes        covers [1 → MAX_UINT]
+ *   tokenIds             covers [1 → MAX_UINT]
+ *   approvalId           === 'All'
+ *   amountTrackerId      === 'All'
+ *   challengeTrackerId   === 'All'
+ *
+ * If every one of those matches AND the forbidden-times range is
+ * forever, no approval can ever be added / removed / modified via
+ * MsgUniversalUpdateCollection, and transferability is permanently
+ * fixed at creation. Partial locks (e.g. "Mint scope forbidden forever")
+ * don't qualify — they only freeze a subset of approvals.
+ */
+export function isCollectionApprovalBlanketLocked(entry: any): boolean {
+  if (!entry) return false;
+  if (entry.fromListId !== 'All') return false;
+  if (entry.toListId !== 'All') return false;
+  if (entry.initiatedByListId !== 'All') return false;
+  if (!isForeverRange(entry.transferTimes)) return false;
+  if (!isForeverRange(entry.tokenIds)) return false;
+  if (entry.approvalId !== 'All') return false;
+  if (entry.amountTrackerId !== 'All') return false;
+  if (entry.challengeTrackerId !== 'All') return false;
+  return isForeverRange(entry.permanentlyForbiddenTimes);
+}
+
+/**
+ * True if the collection's `canUpdateCollectionApprovals` permission
+ * contains any entry that is a blanket permanent lock. Convenience
+ * wrapper over {@link isCollectionApprovalBlanketLocked}.
+ */
+export function isTransferabilityPermanentlyLocked(value: any): boolean {
+  const entries: any[] = value?.collectionPermissions?.canUpdateCollectionApprovals || [];
+  return entries.some(isCollectionApprovalBlanketLocked);
+}
diff --git a/packages/bitbadgesjs-sdk/src/core/review-ux/skills.ts b/packages/bitbadgesjs-sdk/src/core/review-ux/skills.ts
new file mode 100644
index 0000000000..fffdb23d77
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review-ux/skills.ts
@@ -0,0 +1,287 @@
+/**
+ * Skill-specific UX checks — NFT/fungible shape, protocol matchers, mint approvals,
+ * liquidity pools, backed paths. Ported from frontend reviewItems.ts.
+ *
+ * All checks in this file gate on the collection's declared `standards` or on
+ * structural markers (cosmosCoinBackedPath, allowBackedMinting, wrapper paths).
+ * We do NOT gate on `ctx.selectedSkills` — ctx-less callers like the indexer
+ * and MCP would otherwise misfire on every collection.
+ */
+
+import type { Finding } from '../review-types.js';
+import type { UxCheck } from './shared.js';
+import { getApprovals, getAllApprovals } from './shared.js';
+import { doesCollectionFollowSubscriptionProtocol } from '../subscriptions.js';
+import { doesCollectionFollowQuestProtocol } from '../quests.js';
+import { doesCollectionFollowBountyProtocol } from '../bounties.js';
+import { doesCollectionFollowCrowdfundProtocol } from '../crowdfunds.js';
+import { doesCollectionFollowAuctionProtocol } from '../auctions.js';
+import { doesCollectionFollowProductProtocol } from '../products.js';
+
+interface ProtocolCopy {
+  title: string;
+  detail: string;
+  recommendation: string;
+}
+
+const PROTOCOL_COPY: Record<string, ProtocolCopy> = {
+  subscription: {
+    title: 'Collection does not follow the subscription protocol',
+    detail:
+      'This collection has the Subscriptions standard but does not meet all the requirements for a valid subscription. It may not work correctly with subscription features like auto-renewal and recurring payments.',
+    recommendation: 'Fix the subscription setup to follow the subscription protocol requirements'
+  },
+  quest: {
+    title: 'Collection does not follow the quest protocol',
+    detail:
+      'This collection has the Quests standard but does not meet all the requirements for a valid quest collection.',
+    recommendation: 'Fix the quest setup to follow the quest protocol requirements'
+  },
+  bounty: {
+    title: 'Collection does not follow the bounty protocol',
+    detail: 'This collection has the Bounty standard but does not meet all the requirements for a valid bounty.',
+    recommendation: 'Fix the bounty setup to follow the bounty protocol requirements'
+  },
+  crowdfund: {
+    title: 'Collection does not follow the crowdfund protocol',
+    detail:
+      'This collection has the Crowdfund standard but does not meet all the requirements for a valid crowdfund.',
+    recommendation: 'Fix the crowdfund setup to follow the crowdfund protocol requirements'
+  },
+  auction: {
+    title: 'Collection does not follow the auction protocol',
+    detail: 'This collection has the Auction standard but does not meet all the requirements for a valid auction.',
+    recommendation: 'Fix the auction setup to follow the auction protocol requirements'
+  },
+  product_catalog: {
+    title: 'Collection does not follow the product catalog protocol',
+    detail:
+      'This collection has the Products standard but does not meet all the requirements for a valid product catalog.',
+    recommendation: 'Fix the product catalog setup to follow the product catalog protocol requirements'
+  }
+};
+
+export const skillChecks: UxCheck[] = [
+  // NFT without maxSupplyPerId = 1. Gated on the NFTs standard (not the
+  // skill) so ctx-less callers like the indexer don't misfire on fungible
+  // / credit / address-list collections that legitimately have no cap.
+  (value) => {
+    const out: Finding[] = [];
+    const standards: string[] = value?.standards || [];
+    if (!standards.includes('NFTs')) return out;
+    const invariants = value?.invariants || {};
+    if (!invariants.maxSupplyPerId || invariants.maxSupplyPerId === 0n) {
+      out.push({
+        code: 'review.ux.nft_no_supply_cap',
+        severity: 'warning',
+        source: 'ux',
+        category: 'skills',
+        title: {
+          en: 'NFT without per-token supply cap'
+        },
+        detail: {
+          en: 'The per-token supply cap is not set to 1. Multiple copies of the same NFT token ID can be minted.'
+        },
+        recommendation: {
+          en: 'Set the per-token supply cap to 1 so each NFT token ID is unique'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Fungible token with multiple token IDs. Gated on the Fungible Tokens
+  // standard (not the skill) so ctx-less callers don't misfire on NFT /
+  // multi-tier collections.
+  (value) => {
+    const out: Finding[] = [];
+    const standards: string[] = value?.standards || [];
+    if (!standards.includes('Fungible Tokens')) return out;
+    const validTokenIds: any[] = value?.validTokenIds || [];
+    if (validTokenIds.length === 0) return out;
+    const totalIds = validTokenIds.reduce(
+      (sum: number, r: any) => sum + (Number(r.end || 0) - Number(r.start || 0) + 1),
+      0
+    );
+    if (totalIds > 1) {
+      out.push({
+        code: 'review.ux.fungible_multiple_token_ids',
+        severity: 'warning',
+        source: 'ux',
+        category: 'skills',
+        title: {
+          en: 'Fungible token has multiple token IDs'
+        },
+        detail: {
+          en: `Expected a single token ID for a fungible token, but found ${totalIds} IDs. Fungible tokens typically use only token ID 1.`
+        },
+        recommendation: {
+          en: 'Change valid token IDs to only include token ID 1'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Protocol matcher checks — gated on declared standard only
+  (value) => {
+    const out: Finding[] = [];
+    const standards: string[] = value?.standards || [];
+    const protocolChecks: Array<{
+      standard: string;
+      check: (c: any) => boolean;
+      key: string;
+    }> = [
+      { standard: 'Subscriptions', check: doesCollectionFollowSubscriptionProtocol as any, key: 'subscription' },
+      { standard: 'Quests', check: doesCollectionFollowQuestProtocol as any, key: 'quest' },
+      { standard: 'Bounty', check: doesCollectionFollowBountyProtocol as any, key: 'bounty' },
+      { standard: 'Crowdfund', check: doesCollectionFollowCrowdfundProtocol as any, key: 'crowdfund' },
+      { standard: 'Auction', check: doesCollectionFollowAuctionProtocol as any, key: 'auction' },
+      { standard: 'Products', check: doesCollectionFollowProductProtocol as any, key: 'product_catalog' }
+    ];
+    for (const { standard, check, key } of protocolChecks) {
+      if (!standards.includes(standard)) continue;
+      try {
+        if (!check(value)) {
+          const copy = PROTOCOL_COPY[key];
+          out.push({
+            code: `review.ux.protocol_mismatch_${key}`,
+            severity: 'critical',
+            source: 'ux',
+            category: 'skills',
+            title: { en: copy.title },
+            detail: { en: copy.detail },
+            recommendation: { en: copy.recommendation }
+          });
+        }
+      } catch {
+        // Collection may not be fully hydrated — skip
+      }
+    }
+    return out;
+  },
+
+  // No mint approvals (nothing can be minted). Smart-token collections are
+  // excluded structurally via hasBackedMinting — they mint via backed paths
+  // / wrapper paths, not Mint approvals.
+  (value) => {
+    const out: Finding[] = [];
+    const approvals = getApprovals(value);
+    const mintApprovals = approvals.filter((a: any) => a.fromListId === 'Mint');
+    const hasBackedMinting =
+      getAllApprovals(value).some((a: any) => a.approvalCriteria?.allowBackedMinting) ||
+      (Array.isArray(value?.cosmosCoinWrapperPaths) && value.cosmosCoinWrapperPaths.length > 0) ||
+      (Array.isArray(value?.cosmosCoinWrapperPathsToAdd) && value.cosmosCoinWrapperPathsToAdd.length > 0);
+    if (mintApprovals.length === 0 && approvals.length > 0 && !hasBackedMinting) {
+      out.push({
+        code: 'review.ux.no_mint_approvals',
+        severity: 'warning',
+        source: 'ux',
+        category: 'skills',
+        title: {
+          en: 'No token-creation approvals configured'
+        },
+        detail: {
+          en: 'The collection has transfer approvals but no approvals that create new tokens. Nothing can enter circulation. Smart tokens that create supply via IBC backing or wrapper paths are excluded from this check.'
+        },
+        recommendation: {
+          en: 'Add a creation approval with fromListId: "Mint", or configure an IBC backing path / wrapper path if this is a smart token.'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Backed path requires exactly 1 token ID
+  (value) => {
+    const out: Finding[] = [];
+    const invariants = value?.invariants || {};
+    if (!invariants.cosmosCoinBackedPath) return out;
+    const validTokenIds: any[] = value?.validTokenIds || [];
+    const total = validTokenIds.reduce(
+      (sum: number, r: any) => sum + (Number(r.end || 0) - Number(r.start || 0) + 1),
+      0
+    );
+    if (total > 1) {
+      out.push({
+        code: 'review.ux.backed_path_multi_token',
+        severity: 'warning',
+        source: 'ux',
+        category: 'skills',
+        title: {
+          en: 'Smart token has multiple token IDs'
+        },
+        detail: {
+          en: 'IBC-backed smart tokens must have exactly one token ID. Multiple token IDs are not supported for backed collections.'
+        },
+        recommendation: {
+          en: 'Set valid token IDs to exactly one token (1-1)'
+        }
+      });
+    }
+    return out;
+  },
+
+  // Credit tokens should be non-transferable (increment-only)
+  (value) => {
+    const out: Finding[] = [];
+    const standards: string[] = value?.standards || [];
+    if (!standards.includes('Credit Token')) return out;
+    const nonMint = getApprovals(value).filter((a: any) => a.fromListId !== 'Mint' && a.fromListId !== 'All');
+    if (nonMint.length === 0) return out;
+    out.push({
+      code: 'review.ux.credit_token_transfers_allowed',
+      severity: 'warning',
+      source: 'ux',
+      category: 'skills',
+      title: {
+        en: 'Credit token allows transfers'
+      },
+      detail: {
+        en: 'Credit tokens are typically non-transferable (increment-only). This collection has non-mint transfer approvals which would allow credits to be sent between users.'
+      },
+      recommendation: {
+        en: 'Remove the non-mint transfer approvals to make this a non-transferable credit token'
+      }
+    });
+    return out;
+  },
+
+  // `review.ux.mint_escrow_unfunded` removed.
+  //
+  // The check read `value.mintEscrowCoinsToTransfer` from the collection
+  // WIP state, but the frontend never populates that field there —
+  // `withCoinsToEscrow` is a separate form state tracked in
+  // TxTimelineContext and only attached to the Msg at the final
+  // broadcast step in CreateTxMsgUniversalUpdateCollection.tsx.
+  // That meant the warning fired on every quest / subscription /
+  // crowdfund / auction form no matter what the user set. Since the
+  // mint escrow can also be topped up at any time post-creation, the
+  // check was noise without a reliable signal. Removed.
+
+  // Liquidity Pools standard requires alias paths
+  (value) => {
+    const out: Finding[] = [];
+    const standards: string[] = value?.standards || [];
+    if (!standards.includes('Liquidity Pools')) return out;
+    const aliasPaths: any[] = value?.aliasPaths || value?.aliasPathsToAdd || [];
+    if (aliasPaths.length === 0) {
+      out.push({
+        code: 'review.ux.liquidity_pool_no_alias',
+        severity: 'critical',
+        source: 'ux',
+        category: 'skills',
+        title: {
+          en: 'Liquidity Pools standard but no alias paths'
+        },
+        detail: {
+          en: 'This collection has the Liquidity Pools standard but no alias paths configured. Alias paths are required for DEX trading denomination display.'
+        },
+        recommendation: {
+          en: 'Add at least one alias path for the trading denomination'
+        }
+      });
+    }
+    return out;
+  }
+];
diff --git a/packages/bitbadgesjs-sdk/src/core/review.spec.ts b/packages/bitbadgesjs-sdk/src/core/review.spec.ts
new file mode 100644
index 0000000000..c3dbd8b1cb
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review.spec.ts
@@ -0,0 +1,242 @@
+/**
+ * Unit tests for reviewCollection() and the ported UX checks.
+ */
+
+import { reviewCollection, extractCollectionValue, fromAuditFinding, fromStandardsFinding, type Finding } from './review.js';
+import { runUxChecks } from './review-ux/index.js';
+
+function findByCode(findings: Finding[], code: string): Finding | undefined {
+  return findings.find((f) => f.code === code);
+}
+
+describe('reviewCollection — smoke', () => {
+  it('returns a ReviewResult with summary for an empty collection', () => {
+    const result = reviewCollection({
+      collectionApprovals: [],
+      invariants: { noForcefulPostMintTransfers: true }
+    });
+    expect(Array.isArray(result.findings)).toBe(true);
+    expect(['pass', 'warn', 'fail']).toContain(result.summary.verdict);
+    // Summary counts must match finding list
+    const total = result.summary.critical + result.summary.warning + result.summary.info;
+    expect(total).toBe(result.findings.length);
+  });
+
+  it('extractCollectionValue unwraps transaction, message, and raw collection', () => {
+    expect(extractCollectionValue({ messages: [{ value: { a: 1 } }] })).toEqual({ a: 1 });
+    expect(extractCollectionValue({ typeUrl: 'x', value: { a: 2 } })).toEqual({ a: 2 });
+    expect(extractCollectionValue({ a: 3 })).toEqual({ a: 3 });
+  });
+
+  it('summary counts align with severities', () => {
+    const result = reviewCollection({
+      collectionApprovals: [
+        { fromListId: 'Mint', approvalId: 'x', approvalCriteria: {} }
+      ]
+    });
+    const total =
+      result.summary.critical + result.summary.warning + result.summary.info;
+    expect(total).toBe(result.findings.length);
+    expect(result.summary.verdict).toBe('fail');
+  });
+});
+
+describe('adapters', () => {
+  it('fromAuditFinding builds a stable code', () => {
+    const f = fromAuditFinding({
+      severity: 'warning',
+      category: 'centralization',
+      title: 'Manager can change',
+      detail: 'details',
+      recommendation: 'lock it'
+    });
+    expect(f.code).toMatch(/^review\.audit\./);
+    expect(f.source).toBe('audit');
+    expect(f.recommendation.en).toBe('lock it');
+  });
+
+  it('fromStandardsFinding marks source=standards and severity=critical', () => {
+    const f = fromStandardsFinding({
+      standard: 'Subscriptions',
+      field: 'collectionApprovals',
+      message: 'must have mint approval'
+    });
+    expect(f.source).toBe('standards');
+    expect(f.severity).toBe('critical');
+    expect(f.code).toMatch(/^review\.standards\./);
+  });
+});
+
+describe('UX checks — representative sample', () => {
+  const ctx = {};
+
+  it('flags mint approval missing override', () => {
+    const findings = runUxChecks(
+      {
+        collectionApprovals: [{ approvalId: 'mint1', fromListId: 'Mint', approvalCriteria: {} }]
+      },
+      ctx
+    );
+    expect(findByCode(findings, 'review.ux.mint_approval_missing_override')).toBeDefined();
+  });
+
+  it('flags placeholder images on metadataPlaceholders', () => {
+    const findings = runUxChecks(
+      {
+        collectionApprovals: [],
+        _meta: { metadataPlaceholders: { 'ipfs://METADATA_1': { image: 'ipfs://IMAGE_1' } } }
+      },
+      ctx
+    );
+    expect(findByCode(findings, 'review.ux.placeholder_images')).toBeDefined();
+  });
+
+  it('flags permission permanently permitted forever', () => {
+    // review-ux checks run after normalizeForReview has converted all
+    // numeric fields to bigints via the Msg class .convert(BigIntify)
+    // pipeline. Tests call runUxChecks directly so must supply bigints.
+    const findings = runUxChecks(
+      {
+        collectionApprovals: [],
+        collectionPermissions: {
+          canUpdateCollectionMetadata: [
+            { permanentlyPermittedTimes: [{ start: 1n, end: 18446744073709551615n }] }
+          ]
+        }
+      },
+      ctx
+    );
+    const permFinding = findings.find((f) => f.code.startsWith('review.ux.permission_permanently_permitted_'));
+    expect(permFinding).toBeDefined();
+  });
+
+  it('flags missing aliases image', () => {
+    const findings = runUxChecks(
+      {
+        collectionApprovals: [],
+        aliasPaths: [{ denomUnits: [{ isDefaultDisplay: true, metadata: {} }], metadata: {} }]
+      },
+      ctx
+    );
+    expect(findByCode(findings, 'review.ux.alias_paths_missing_images')).toBeDefined();
+  });
+
+  it('flags on-chain diff: deleted approvals', () => {
+    const findings = runUxChecks(
+      {
+        collectionId: '42',
+        updateCollectionApprovals: true,
+        collectionApprovals: [{ approvalId: 'keep' }]
+      },
+      {
+        onChainCollection: {
+          collectionApprovals: [{ approvalId: 'keep' }, { approvalId: 'delete-me' }]
+        }
+      }
+    );
+    expect(findByCode(findings, 'review.ux.diff_deleted_approvals')).toBeDefined();
+  });
+
+  it('flags forceful_transfers_allowed when overrides exist without invariant', () => {
+    const findings = runUxChecks(
+      {
+        collectionApprovals: [
+          {
+            approvalId: 'forceful1',
+            fromListId: 'All',
+            approvalCriteria: { overridesFromOutgoingApprovals: true }
+          }
+        ],
+        invariants: {}
+      },
+      ctx
+    );
+    // Matches old frontend: overrides + no invariant -> single finding, no separate invariant check
+    expect(findByCode(findings, 'review.ux.forceful_transfers_allowed')).toBeDefined();
+    expect(findByCode(findings, 'review.ux.forceful_invariant_not_set')).toBeUndefined();
+  });
+
+  it('forceful mismatch fires as the only finding when overrides exist AND invariant set', () => {
+    // Both set -> forceful_override_mismatch only (critical; no duplicate warning)
+    const both = runUxChecks(
+      {
+        collectionApprovals: [
+          {
+            approvalId: 'x',
+            fromListId: 'bb1user',
+            approvalCriteria: { overridesFromOutgoingApprovals: true }
+          }
+        ],
+        invariants: { noForcefulPostMintTransfers: true }
+      },
+      ctx
+    );
+    expect(findByCode(both, 'review.ux.forceful_transfers_allowed')).toBeUndefined();
+    expect(findByCode(both, 'review.ux.forceful_override_mismatch')).toBeDefined();
+
+    // No overrides + invariant set -> no finding (locked as expected)
+    const invOnly = runUxChecks(
+      { collectionApprovals: [], invariants: { noForcefulPostMintTransfers: true } },
+      ctx
+    );
+    expect(findByCode(invOnly, 'review.ux.forceful_transfers_allowed')).toBeUndefined();
+    expect(findByCode(invOnly, 'review.ux.forceful_override_mismatch')).toBeUndefined();
+  });
+
+  it('flags credit_token_transfers_allowed when Credit Token standard + non-mint approvals', () => {
+    const findings = runUxChecks(
+      {
+        standards: ['Credit Token'],
+        collectionApprovals: [
+          { approvalId: 'm', fromListId: 'Mint', approvalCriteria: { overridesFromOutgoingApprovals: true } },
+          { approvalId: 't', fromListId: 'bb1holder', approvalCriteria: {} }
+        ]
+      },
+      ctx
+    );
+    expect(findByCode(findings, 'review.ux.credit_token_transfers_allowed')).toBeDefined();
+  });
+
+  it('flags reserved coin symbol collisions on alias paths', () => {
+    const findings = runUxChecks(
+      {
+        collectionApprovals: [],
+        aliasPaths: [{ denomUnits: [{ symbol: 'BADGE' }] }]
+      },
+      ctx
+    );
+    // The finding is only emitted if BADGE is in the registry; defensively
+    // just check that the module did not throw and the call completed.
+    expect(Array.isArray(findings)).toBe(true);
+  });
+});
+
+describe('reviewCollection — snapshot across sources', () => {
+  it('returns findings from all three sources on a broken collection', () => {
+    const broken = {
+      collectionId: '0',
+      manager: 'bb1deadbeef',
+      collectionApprovals: [
+        { approvalId: 'bad-mint', fromListId: 'Mint', approvalCriteria: {} },
+        { approvalId: 'all-list', fromListId: 'All', approvalCriteria: {} }
+      ],
+      standards: [],
+      _meta: { metadataPlaceholders: { 'ipfs://METADATA_X': { image: 'ipfs://IMAGE_1' } } }
+    };
+    const result = reviewCollection(broken);
+    expect(result.summary.verdict).toBe('fail');
+    // Must include at least one ux finding
+    expect(result.findings.some((f) => f.source === 'ux')).toBe(true);
+    // Every finding must have a stable code and the three required localized strings
+    for (const f of result.findings) {
+      expect(typeof f.code).toBe('string');
+      expect(f.code).toMatch(/^review\.(audit|standards|ux)\./);
+      expect(typeof f.title.en).toBe('string');
+      expect(f.title.en.length).toBeGreaterThan(0);
+      expect(typeof f.detail.en).toBe('string');
+      expect(f.detail.en.length).toBeGreaterThan(0);
+      expect(typeof f.recommendation.en).toBe('string');
+      expect(f.recommendation.en.length).toBeGreaterThan(0);
+    }
+  });
+});
diff --git a/packages/bitbadgesjs-sdk/src/core/review.ts b/packages/bitbadgesjs-sdk/src/core/review.ts
new file mode 100644
index 0000000000..3b7f239bc0
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/review.ts
@@ -0,0 +1,159 @@
+/**
+ * Unified deterministic review for collections.
+ *
+ * `reviewCollection(collection, context)` is the one source of truth that
+ * composes three existing check families:
+ *
+ *   1. `auditCollection()` — security/permission audit (src/core/audit.ts)
+ *   2. `verifyStandardsCompliance()` — protocol conformance (src/core/verify-standards.ts)
+ *   3. `runUxChecks()` — the ported frontend UX checks (src/core/review-ux/*)
+ *
+ * All three are normalized into a single {@link Finding} shape with a
+ * stable machine `code`, a severity, and three required localized strings
+ * (`title`, `detail`, `recommendation`). Localization lives inline in the
+ * finding — callers never need to look up locale keys externally.
+ *
+ * The legacy `auditCollection` and `verifyStandardsCompliance` functions are
+ * untouched — they keep working identically for direct callers.
+ */
+
+import { auditCollection, type AuditFinding, type AuditSeverity } from './audit.js';
+import { verifyStandardsCompliance, type StandardViolation } from './verify-standards.js';
+import { runUxChecks } from './review-ux/index.js';
+import type { Finding, FindingSource, Localized, ReviewContext, ReviewResult, Severity } from './review-types.js';
+import { normalizeForReview, extractCollectionValue } from './review-normalize.js';
+
+export { normalizeForReview, extractCollectionValue } from './review-normalize.js';
+
+// Re-export the types so `reviewCollection` + types are importable from one entry.
+export type { Finding, FindingSource, Localized, ReviewContext, ReviewResult, Severity } from './review-types.js';
+
+// ---------------------------------------------------------------------------
+// Normalization helpers
+// ---------------------------------------------------------------------------
+// extractCollectionValue + normalizeForReview live in ./review-normalize.js
+// so auditCollection and verifyStandardsCompliance can also run them
+// without creating a circular import. Re-exported above for callers who
+// import everything from this module.
+
+/**
+ * Wrap a plain English string as a `Localized` bag. Used by adapters
+ * that inherit legacy single-language content from audit / standards
+ * internal shapes.
+ */
+function en(s: string): Localized {
+  return { en: s };
+}
+
+// ---------------------------------------------------------------------------
+// Adapters from legacy finding shapes to unified Finding
+// ---------------------------------------------------------------------------
+
+function snakeCase(s: string): string {
+  return s
+    .replace(/[^A-Za-z0-9]+/g, '_')
+    .replace(/([a-z])([A-Z])/g, '$1_$2')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase();
+}
+
+function mapAuditSeverity(s: AuditSeverity): Severity {
+  return s; // identical set
+}
+
+export function fromAuditFinding(f: AuditFinding): Finding {
+  const codeSuffix = snakeCase(f.category || 'finding') + '.' + snakeCase(f.title || 'item');
+  return {
+    code: 'review.audit.' + codeSuffix,
+    severity: mapAuditSeverity(f.severity),
+    source: 'audit',
+    category: f.category,
+    title: en(f.title),
+    detail: en(f.detail),
+    recommendation: en(f.recommendation || 'No action required — surfaced for visibility.'),
+    ...(f.agentOnly ? { agentOnly: true } : {})
+  };
+}
+
+export function fromStandardsFinding(v: StandardViolation): Finding {
+  const codeSuffix = snakeCase(v.standard || 'standard') + '.' + snakeCase(v.field || 'field');
+  const title = `${v.standard} standard violation: ${v.field}`;
+  return {
+    code: 'review.standards.' + codeSuffix,
+    severity: 'critical',
+    source: 'standards',
+    category: 'standards:' + v.standard,
+    title: en(title),
+    detail: en(v.message),
+    recommendation: en(v.fix || 'No action required — surfaced for visibility.')
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+export function reviewCollection(collection: unknown, context?: ReviewContext): ReviewResult {
+  const ctx: ReviewContext = context || {};
+  const skip = new Set<FindingSource>(ctx.skipSources || []);
+  // Single normalization pass: bigint/number → string, alias path mirror.
+  // Every downstream check sees a canonical shape.
+  const value = normalizeForReview(collection);
+
+  const findings: Finding[] = [];
+
+  if (!skip.has('audit')) {
+    try {
+      const audit = auditCollection({ collection: value as Record<string, unknown> });
+      for (const f of audit.findings || []) findings.push(fromAuditFinding(f));
+    } catch {
+      // auditCollection is defensive; swallow errors to keep review resilient
+    }
+  }
+
+  if (!skip.has('standards')) {
+    try {
+      const std = verifyStandardsCompliance(value, ctx.onChainCollection);
+      for (const v of std.violations || []) findings.push(fromStandardsFinding(v));
+    } catch {
+      // standards may not apply
+    }
+  }
+
+  if (!skip.has('ux')) {
+    try {
+      const ux = runUxChecks(value, ctx);
+      for (const f of ux) findings.push(f);
+    } catch {
+      // UX checks are pure; any throw is a bug, but don't kill the review
+    }
+  }
+
+  // Dedupe by code (keep the first occurrence — usually the most specific).
+  const seen = new Set<string>();
+  const deduped: Finding[] = [];
+  for (const f of findings) {
+    if (seen.has(f.code)) continue;
+    seen.add(f.code);
+    deduped.push(f);
+  }
+
+  // Drop agent-only findings when the caller opted in via hideAgentOnly.
+  // Frontend humans set this. CLI / indexer / MCP leave it unset.
+  const filtered = ctx.hideAgentOnly ? deduped.filter((f) => !f.agentOnly) : deduped;
+
+  let critical = 0;
+  let warning = 0;
+  let info = 0;
+  for (const f of filtered) {
+    if (f.severity === 'critical') critical++;
+    else if (f.severity === 'warning') warning++;
+    else info++;
+  }
+  const verdict: 'pass' | 'warn' | 'fail' = critical > 0 ? 'fail' : warning > 0 ? 'warn' : 'pass';
+
+  return {
+    findings: filtered,
+    summary: { critical, warning, info, verdict }
+  };
+}
diff --git a/packages/bitbadgesjs-sdk/src/core/simulation.ts b/packages/bitbadgesjs-sdk/src/core/simulation.ts
index 27484a0d8c..7570327ab2 100644
--- a/packages/bitbadgesjs-sdk/src/core/simulation.ts
+++ b/packages/bitbadgesjs-sdk/src/core/simulation.ts
@@ -372,15 +372,25 @@ export function calculateNetChanges(
     coinChanges.get('Network Fee')!.set(feeDenom, coinChanges.get('Network Fee')!.get(feeDenom)! + feeAmount);
   }
 
-  // Known fee collector addresses — transfers to these are already represented by "Network Fee" above
+  // Known fee collector addresses. We only filter transfers TO these when
+  // the caller explicitly passed `fee` + `signerAddress` above — in that
+  // case the fee is already represented as "Network Fee" and we'd
+  // double-count by also aggregating the raw fee-collector transfer.
+  // When no fee arg is provided (the standalone/auto simulate path), the
+  // chain event IS the only signal we have, so include it like any other
+  // transfer — otherwise `coinChanges` ends up empty and the UI prints
+  // "No net balance changes detected." while the Transfers section below
+  // shows the fee transfer. That contradiction was bug #2.
   const FEE_COLLECTOR_ADDRESSES = new Set([
     'bb17xpfvakm2amg962yls6f84z3kell8c5lnytnhv',
     'cosmos17xpfvakm2amg962yls6f84z3kell8c5lserqta'
   ]);
+  const shouldFilterFeeCollector = Boolean(fee && signerAddress);
 
-  // Aggregate coin transfers (skip fee collector since it's already in "Network Fee")
+  // Aggregate coin transfers (skip fee collector only when fee was
+  // explicitly accounted for above).
   for (const event of parsed.coinTransferEvents) {
-    if (FEE_COLLECTOR_ADDRESSES.has(event.to)) continue;
+    if (shouldFilterFeeCollector && FEE_COLLECTOR_ADDRESSES.has(event.to)) continue;
 
     const amount = event.amount;
     const denom = event.denom;
diff --git a/packages/bitbadgesjs-sdk/src/core/uintRanges.spec.ts b/packages/bitbadgesjs-sdk/src/core/uintRanges.spec.ts
index 036b4d525f..678efb8d9b 100644
--- a/packages/bitbadgesjs-sdk/src/core/uintRanges.spec.ts
+++ b/packages/bitbadgesjs-sdk/src/core/uintRanges.spec.ts
@@ -79,4 +79,43 @@ describe('UintRange and UintRangeArray', () => {
     const index = sortedArr.searchIndex(11n);
     expect(index === 0n).toBe(true);
   });
+
+  describe('UintRangeArray.From defensive guards', () => {
+    it('null/undefined → empty array', () => {
+      expect(UintRangeArray.From(null).length).toBe(0);
+      expect(UintRangeArray.From(undefined).length).toBe(0);
+    });
+
+    it('single-object form accepted', () => {
+      const arr = UintRangeArray.From({ start: '1', end: '5' });
+      expect(arr.length).toBe(1);
+      expect(String(arr[0].start)).toBe('1');
+    });
+
+    it('null/undefined elements filtered out (regression: would crash inside new UintRange(null))', () => {
+      // Round 4 sweep: subagent caught that From([null]) crashed with
+      // "Cannot read properties of null (reading 'start')". The
+      // top-level guard wasn't enough — element-level filtering needed.
+      const arr = UintRangeArray.From([
+        null as any,
+        undefined as any,
+        { start: '1', end: '5' },
+        null as any,
+        { start: '7', end: '9' }
+      ]);
+      expect(arr.length).toBe(2);
+      expect(String(arr[0].start)).toBe('1');
+      expect(String(arr[1].start)).toBe('7');
+    });
+
+    it('non-object elements (numbers, strings) filtered out', () => {
+      const arr = UintRangeArray.From([
+        123 as any,
+        'string' as any,
+        { start: '1', end: '5' }
+      ]);
+      expect(arr.length).toBe(1);
+      expect(String(arr[0].start)).toBe('1');
+    });
+  });
 });
diff --git a/packages/bitbadgesjs-sdk/src/core/uintRanges.ts b/packages/bitbadgesjs-sdk/src/core/uintRanges.ts
index b6ddee0c7b..b6d699a06a 100644
--- a/packages/bitbadgesjs-sdk/src/core/uintRanges.ts
+++ b/packages/bitbadgesjs-sdk/src/core/uintRanges.ts
@@ -238,9 +238,26 @@ export class UintRangeArray<T extends NumberType> extends BaseTypedArray<UintRan
     return new UintRangeArray(UintRange.FullRange());
   }
 
-  static From<T extends NumberType>(arr: iUintRange<T>[] | iUintRange<T> | UintRangeArray<T>): UintRangeArray<T> {
+  static From<T extends NumberType>(
+    arr: iUintRange<T>[] | iUintRange<T> | UintRangeArray<T> | null | undefined
+  ): UintRangeArray<T> {
+    // Defend against missing optional fields. Many wrapper-class
+    // constructors blindly call `UintRangeArray.From(msg.ownershipTimes)`
+    // (or similar) without checking presence first; passing undefined
+    // through would crash on `new UintRange(undefined)`. Treating
+    // null/undefined as an empty array matches the proto3 semantics
+    // (a missing repeated field is an empty list).
+    if (arr === null || arr === undefined) return new UintRangeArray();
     const wrappedArr = Array.isArray(arr) ? arr : [arr];
-    return new UintRangeArray(...wrappedArr.map((i) => new UintRange(i)));
+    // Element-level defense: filter out null/undefined and reject
+    // non-object elements (numbers, strings, etc.) before constructing
+    // UintRange. Without this, `From([null])` crashes inside
+    // `new UintRange(null)` reading `.start` on null. Same defensive
+    // posture as the top-level guard above; just at the element level.
+    const safeElements = wrappedArr.filter(
+      (i): i is iUintRange<T> => i !== null && i !== undefined && typeof i === 'object'
+    );
+    return new UintRangeArray(...safeElements.map((i) => new UintRange(i)));
   }
 
   /**
diff --git a/packages/bitbadgesjs-sdk/src/core/validate-msgtypes.spec.ts b/packages/bitbadgesjs-sdk/src/core/validate-msgtypes.spec.ts
new file mode 100644
index 0000000000..e1e155309b
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/validate-msgtypes.spec.ts
@@ -0,0 +1,244 @@
+/**
+ * Tests for the validation passes added this session:
+ *
+ *   1. All three collection typeUrls accepted (Create / Update / Universal)
+ *   2. Update-specific rules:
+ *      - must have non-zero collectionId
+ *      - must NOT set defaultBalances
+ *      - must NOT set invariants (genesis-only)
+ *   3. Create accepts missing collectionId + missing update flags without
+ *      firing spurious errors (constructor check implies flags=true)
+ *   4. User-level approval msg branches:
+ *      - MsgUpdateUserApprovals
+ *      - MsgSetIncomingApproval / MsgSetOutgoingApproval
+ *      - MsgDeleteIncoming/OutgoingApproval (approvalId required)
+ *   5. Approval-level gating: collection-only rules (Mint override,
+ *      subscriptions, backing-address warning) are skipped when the level
+ *      is 'outgoing' or 'incoming'.
+ */
+
+import { validateTransaction, validateApprovals, type ValidationIssue } from './validate.js';
+
+const CREATE = '/tokenization.MsgCreateCollection';
+const UPDATE = '/tokenization.MsgUpdateCollection';
+const UNIVERSAL = '/tokenization.MsgUniversalUpdateCollection';
+
+const baseCreatorValue = () => ({
+  creator: 'bb1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqpdguex7'
+});
+
+// Minimal field shapes to keep validateMsgConstructorFields happy.
+const MIN_COLLECTION_VALUE = () => ({
+  ...baseCreatorValue(),
+  validTokenIds: [],
+  standards: [],
+  collectionApprovals: [],
+  tokenMetadata: [],
+  aliasPathsToAdd: [],
+  cosmosCoinWrapperPathsToAdd: [],
+  mintEscrowCoinsToTransfer: []
+});
+
+function wrap(typeUrl: string, value: any) {
+  return { messages: [{ typeUrl, value }] };
+}
+
+describe('validateTransaction — all three collection typeUrls accepted', () => {
+  it('MsgCreateCollection with minimal valid value is clean', () => {
+    const result = validateTransaction(wrap(CREATE, MIN_COLLECTION_VALUE()));
+    expect(result.valid).toBe(true);
+  });
+
+  it('MsgUpdateCollection with non-zero collectionId is clean', () => {
+    const result = validateTransaction(
+      wrap(UPDATE, { ...MIN_COLLECTION_VALUE(), collectionId: '42' })
+    );
+    expect(result.valid).toBe(true);
+  });
+
+  it('MsgUniversalUpdateCollection with collectionId still works (legacy path)', () => {
+    const result = validateTransaction(
+      wrap(UNIVERSAL, { ...MIN_COLLECTION_VALUE(), collectionId: '0' })
+    );
+    expect(result.valid).toBe(true);
+  });
+});
+
+describe('MsgUpdateCollection — Update-specific rules', () => {
+  const minUpdate = () => ({ ...MIN_COLLECTION_VALUE(), collectionId: '42' });
+
+  it('requires non-zero collectionId', () => {
+    const result = validateTransaction(
+      wrap(UPDATE, { ...MIN_COLLECTION_VALUE(), collectionId: '0' })
+    );
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => /non-zero "collectionId"/.test(i.message))).toBe(true);
+  });
+
+  it('rejects defaultBalances (create-only)', () => {
+    const result = validateTransaction(
+      wrap(UPDATE, { ...minUpdate(), defaultBalances: { autoApproveAllIncomingTransfers: true } })
+    );
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => /defaultBalances/.test(i.message) && /create-only/.test(i.message))).toBe(true);
+  });
+
+  it('rejects invariants (genesis-only)', () => {
+    const result = validateTransaction(
+      wrap(UPDATE, { ...minUpdate(), invariants: { maxSupplyPerId: '1' } })
+    );
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => /invariants/.test(i.message) && /genesis/.test(i.message))).toBe(true);
+  });
+});
+
+describe('MsgCreateCollection — no spurious errors for missing update flags', () => {
+  it('does not complain about missing collectionId', () => {
+    const value = MIN_COLLECTION_VALUE(); // no collectionId
+    const result = validateTransaction(wrap(CREATE, value));
+    // Errors must not reference collectionId at all (Create omits it).
+    const collectionIdErrors = result.issues.filter(
+      (i) => i.severity === 'error' && /collectionId/.test(i.message)
+    );
+    expect(collectionIdErrors).toEqual([]);
+  });
+
+  it('does not complain about missing updateXxxTimeline flags', () => {
+    const result = validateTransaction(wrap(CREATE, MIN_COLLECTION_VALUE()));
+    const flagErrors = result.issues.filter(
+      (i) => i.severity === 'error' && /updateValidTokenIds|updateCollectionApprovals/.test(i.message)
+    );
+    expect(flagErrors).toEqual([]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// User-level approval msg branches
+// ---------------------------------------------------------------------------
+
+const USER_APPROVALS = '/tokenization.MsgUpdateUserApprovals';
+const SET_INCOMING = '/tokenization.MsgSetIncomingApproval';
+const SET_OUTGOING = '/tokenization.MsgSetOutgoingApproval';
+const DELETE_INCOMING = '/tokenization.MsgDeleteIncomingApproval';
+const DELETE_OUTGOING = '/tokenization.MsgDeleteOutgoingApproval';
+
+describe('user-level approval msg validation', () => {
+  it('MsgUpdateUserApprovals: requires creator and non-zero collectionId', () => {
+    const result = validateTransaction(
+      wrap(USER_APPROVALS, { collectionId: '0' })
+    );
+    expect(result.valid).toBe(false);
+    const msgs = result.issues.map((i) => i.message).join('\n');
+    expect(msgs).toMatch(/creator/);
+    expect(msgs).toMatch(/non-zero "collectionId"/);
+  });
+
+  it('MsgUpdateUserApprovals: runs validateApprovals on outgoingApprovals', () => {
+    // Approval missing required approvalId — should be flagged.
+    const result = validateTransaction(
+      wrap(USER_APPROVALS, {
+        creator: 'bb1abc',
+        collectionId: '42',
+        updateOutgoingApprovals: true,
+        outgoingApprovals: [
+          {
+            // approvalId intentionally missing
+            toListId: 'All',
+            initiatedByListId: 'All',
+            transferTimes: [{ start: '1', end: '2' }],
+            tokenIds: [{ start: '1', end: '1' }],
+            ownershipTimes: [{ start: '1', end: '2' }]
+          }
+        ]
+      })
+    );
+    expect(result.issues.some((i) => /approvalId/.test(i.message))).toBe(true);
+  });
+
+  it('MsgSetIncomingApproval: wraps single approval into array and validates', () => {
+    const result = validateTransaction(
+      wrap(SET_INCOMING, {
+        creator: 'bb1abc',
+        collectionId: '42',
+        approval: {
+          // approvalId intentionally missing
+          fromListId: 'All',
+          initiatedByListId: 'All'
+        }
+      })
+    );
+    expect(result.issues.some((i) => /approvalId/.test(i.message))).toBe(true);
+  });
+
+  it('MsgSetOutgoingApproval: missing approval object raises error', () => {
+    const result = validateTransaction(
+      wrap(SET_OUTGOING, { creator: 'bb1abc', collectionId: '42' })
+    );
+    expect(result.issues.some((i) => /"approval" object/.test(i.message))).toBe(true);
+  });
+
+  it.each([DELETE_INCOMING, DELETE_OUTGOING])(
+    '%s: requires non-empty approvalId',
+    (typeUrl) => {
+      const result = validateTransaction(
+        wrap(typeUrl, { creator: 'bb1abc', collectionId: '42', approvalId: '' })
+      );
+      expect(result.issues.some((i) => /approvalId/.test(i.message))).toBe(true);
+    }
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Approval-level gating
+// ---------------------------------------------------------------------------
+
+describe('validateApprovals — level-aware collection-only rules', () => {
+  // A Mint approval that does NOT set overridesFromOutgoingApprovals.
+  // At collection level this should fire "Mint approvals MUST have …".
+  // At outgoing/incoming level it should NOT fire because
+  // OutgoingApprovalCriteria / IncomingApprovalCriteria don't have that
+  // field in the proto at all.
+  const mintApprovalWithoutOverride = {
+    approvalId: 'mint-1',
+    fromListId: 'Mint',
+    toListId: 'All',
+    initiatedByListId: 'All',
+    approvalCriteria: {}
+  };
+
+  it('collection level: flags missing overridesFromOutgoingApprovals on Mint', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals([mintApprovalWithoutOverride], 'path', issues, undefined, 'collection');
+    expect(issues.some((i) => /overridesFromOutgoingApprovals/.test(i.message))).toBe(true);
+  });
+
+  it('outgoing level: does NOT fire Mint override rule', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals([mintApprovalWithoutOverride], 'path', issues, undefined, 'outgoing');
+    expect(issues.some((i) => /overridesFromOutgoingApprovals/.test(i.message))).toBe(false);
+  });
+
+  it('incoming level: does NOT fire Mint override rule either', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals([mintApprovalWithoutOverride], 'path', issues, undefined, 'incoming');
+    expect(issues.some((i) => /overridesFromOutgoingApprovals/.test(i.message))).toBe(false);
+  });
+
+  it('approvalId requirement fires at every level', () => {
+    const noId = { fromListId: 'All', toListId: 'All', initiatedByListId: 'All' };
+    for (const level of ['collection', 'outgoing', 'incoming'] as const) {
+      const issues: ValidationIssue[] = [];
+      validateApprovals([noId], 'path', issues, undefined, level);
+      expect(issues.some((i) => /approvalId/.test(i.message))).toBe(true);
+    }
+  });
+
+  it('toListId "Mint" is rejected at every level', () => {
+    const bad = { approvalId: 'x', toListId: 'Mint', initiatedByListId: 'All' };
+    for (const level of ['collection', 'outgoing', 'incoming'] as const) {
+      const issues: ValidationIssue[] = [];
+      validateApprovals([bad], 'path', issues, undefined, level);
+      expect(issues.some((i) => /toListId cannot be "Mint"/.test(i.message))).toBe(true);
+    }
+  });
+});
diff --git a/packages/bitbadgesjs-sdk/src/core/validate.spec.ts b/packages/bitbadgesjs-sdk/src/core/validate.spec.ts
new file mode 100644
index 0000000000..f40c22fc81
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/core/validate.spec.ts
@@ -0,0 +1,909 @@
+/**
+ * Tests for validate.ts — transaction validation utilities.
+ *
+ * Covers: isValidListId, checkNumbersAreStrings, checkUintRangeFormat,
+ * findAndValidateUintRanges, validateOrderCalculationMethod, validateApprovals,
+ * validateTokenMetadata, validatePermissions, validateApprovalCriteria,
+ * validateMsgConstructorFields, validateTransaction
+ */
+
+import {
+  isValidListId,
+  checkNumbersAreStrings,
+  checkUintRangeFormat,
+  findAndValidateUintRanges,
+  validateOrderCalculationMethod,
+  validateApprovals,
+  validateTokenMetadata,
+  validatePermissions,
+  validateApprovalCriteria,
+  validateMsgConstructorFields,
+  validateTransaction,
+  validateSubscriptionApproval,
+  type ValidationIssue
+} from './validate.js';
+
+// ---------------------------------------------------------------------------
+// isValidListId
+// ---------------------------------------------------------------------------
+
+describe('isValidListId', () => {
+  it('accepts "All"', () => {
+    expect(isValidListId('All')).toBe(true);
+  });
+
+  it('accepts "Mint"', () => {
+    expect(isValidListId('Mint')).toBe(true);
+  });
+
+  it('accepts "!Mint"', () => {
+    expect(isValidListId('!Mint')).toBe(true);
+  });
+
+  it('accepts "AllWithMint"', () => {
+    expect(isValidListId('AllWithMint')).toBe(true);
+  });
+
+  it('rejects garbage string', () => {
+    expect(isValidListId('not-a-valid-list')).toBe(false);
+  });
+
+  it('rejects empty string', () => {
+    expect(isValidListId('')).toBe(false);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkNumbersAreStrings
+// ---------------------------------------------------------------------------
+
+describe('checkNumbersAreStrings', () => {
+  it('no issues for null/undefined', () => {
+    const issues: ValidationIssue[] = [];
+    checkNumbersAreStrings(null, 'root', issues);
+    checkNumbersAreStrings(undefined, 'root', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('flags a bare number', () => {
+    const issues: ValidationIssue[] = [];
+    checkNumbersAreStrings(42, 'root', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].severity).toBe('error');
+    expect(issues[0].message).toContain('"42"');
+  });
+
+  it('no issues for string values', () => {
+    const issues: ValidationIssue[] = [];
+    checkNumbersAreStrings({ amount: '100', name: 'test' }, 'root', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('flags nested number in object', () => {
+    const issues: ValidationIssue[] = [];
+    checkNumbersAreStrings({ outer: { inner: 7 } }, 'root', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].path).toBe('root.outer.inner');
+  });
+
+  it('flags number inside array', () => {
+    const issues: ValidationIssue[] = [];
+    checkNumbersAreStrings([1, '2', 3], 'arr', issues);
+    expect(issues).toHaveLength(2);
+    expect(issues[0].path).toBe('arr[0]');
+    expect(issues[1].path).toBe('arr[2]');
+  });
+
+  it('skips claimConfig subtrees', () => {
+    const issues: ValidationIssue[] = [];
+    checkNumbersAreStrings({ claimConfig: { maxUses: 100 } }, 'root', issues);
+    expect(issues).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// checkUintRangeFormat
+// ---------------------------------------------------------------------------
+
+describe('checkUintRangeFormat', () => {
+  it('no issues for null', () => {
+    const issues: ValidationIssue[] = [];
+    checkUintRangeFormat(null, 'path', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('no issues for valid range', () => {
+    const issues: ValidationIssue[] = [];
+    checkUintRangeFormat({ start: '1', end: '10' }, 'range', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('flags missing start', () => {
+    const issues: ValidationIssue[] = [];
+    checkUintRangeFormat({ end: '10' }, 'range', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('missing "start"');
+  });
+
+  it('flags missing end', () => {
+    const issues: ValidationIssue[] = [];
+    checkUintRangeFormat({ start: '1' }, 'range', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('missing "end"');
+  });
+
+  it('flags non-string start', () => {
+    const issues: ValidationIssue[] = [];
+    checkUintRangeFormat({ start: 1, end: '10' }, 'range', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('"start" must be a string');
+  });
+
+  it('flags non-string end', () => {
+    const issues: ValidationIssue[] = [];
+    checkUintRangeFormat({ start: '1', end: 10 }, 'range', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('"end" must be a string');
+  });
+
+  it('ignores objects without start or end', () => {
+    const issues: ValidationIssue[] = [];
+    checkUintRangeFormat({ foo: 'bar' }, 'path', issues);
+    expect(issues).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// findAndValidateUintRanges
+// ---------------------------------------------------------------------------
+
+describe('findAndValidateUintRanges', () => {
+  it('finds nested invalid range', () => {
+    const issues: ValidationIssue[] = [];
+    findAndValidateUintRanges({ tokenIds: [{ start: 1, end: '5' }] }, 'root', issues);
+    expect(issues.length).toBeGreaterThan(0);
+    // Should flag the non-string start
+    expect(issues.some((i) => i.message.includes('"start" must be a string'))).toBe(true);
+  });
+
+  it('skips claimConfig subtrees', () => {
+    const issues: ValidationIssue[] = [];
+    findAndValidateUintRanges({ claimConfig: { range: { start: 1, end: 2 } } }, 'root', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('no issues for primitives', () => {
+    const issues: ValidationIssue[] = [];
+    findAndValidateUintRanges('hello', 'root', issues);
+    findAndValidateUintRanges(null, 'root', issues);
+    expect(issues).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateOrderCalculationMethod
+// ---------------------------------------------------------------------------
+
+describe('validateOrderCalculationMethod', () => {
+  it('no issues for exactly one true', () => {
+    const issues: ValidationIssue[] = [];
+    validateOrderCalculationMethod({ useOverallNumTransfers: true }, 'path', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('error for multiple true', () => {
+    const issues: ValidationIssue[] = [];
+    validateOrderCalculationMethod(
+      { useOverallNumTransfers: true, usePerToAddressNumTransfers: true },
+      'path',
+      issues
+    );
+    expect(issues).toHaveLength(1);
+    expect(issues[0].severity).toBe('error');
+    expect(issues[0].message).toContain('exactly ONE');
+  });
+
+  it('warning for zero true', () => {
+    const issues: ValidationIssue[] = [];
+    validateOrderCalculationMethod({}, 'path', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].severity).toBe('warning');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateSubscriptionApproval
+// ---------------------------------------------------------------------------
+
+describe('validateSubscriptionApproval', () => {
+  it('no issues when no approvalCriteria', () => {
+    const issues: ValidationIssue[] = [];
+    validateSubscriptionApproval({}, 'path', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('warns on overrideFromWithApproverAddress: true', () => {
+    const issues: ValidationIssue[] = [];
+    validateSubscriptionApproval(
+      {
+        approvalCriteria: {
+          coinTransfers: [{ overrideFromWithApproverAddress: true }]
+        }
+      },
+      'path',
+      issues
+    );
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('overrideFromWithApproverAddress');
+  });
+
+  it('warns on overrideToWithInitiator: true', () => {
+    const issues: ValidationIssue[] = [];
+    validateSubscriptionApproval(
+      {
+        approvalCriteria: {
+          coinTransfers: [{ overrideToWithInitiator: true }]
+        }
+      },
+      'path',
+      issues
+    );
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('overrideToWithInitiator');
+  });
+
+  it('warns on durationFromTimestamp being 0', () => {
+    const issues: ValidationIssue[] = [];
+    validateSubscriptionApproval(
+      {
+        approvalCriteria: {
+          predeterminedBalances: {
+            incrementedBalances: { durationFromTimestamp: '0' }
+          }
+        }
+      },
+      'path',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('durationFromTimestamp'))).toBe(true);
+  });
+
+  it('warns when allowOverrideTimestamp is not true', () => {
+    const issues: ValidationIssue[] = [];
+    validateSubscriptionApproval(
+      {
+        approvalCriteria: {
+          predeterminedBalances: {
+            incrementedBalances: { durationFromTimestamp: '1000', allowOverrideTimestamp: false }
+          }
+        }
+      },
+      'path',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('allowOverrideTimestamp'))).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateApprovals
+// ---------------------------------------------------------------------------
+
+describe('validateApprovals', () => {
+  it('flags invalid list ID', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals(
+      [{ fromListId: 'bogus-id', toListId: 'All', initiatedByListId: 'All', approvalId: 'a1' }],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('Invalid list ID'))).toBe(true);
+  });
+
+  it('flags Mint in toListId', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals(
+      [{ fromListId: 'All', toListId: 'Mint', initiatedByListId: 'All', approvalId: 'a1' }],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('toListId cannot be "Mint"'))).toBe(true);
+  });
+
+  it('flags Mint in initiatedByListId', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals(
+      [{ fromListId: 'All', toListId: 'All', initiatedByListId: 'Mint', approvalId: 'a1' }],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('initiatedByListId cannot be "Mint"'))).toBe(true);
+  });
+
+  it('flags Mint approval without overridesFromOutgoingApprovals', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals(
+      [
+        {
+          fromListId: 'Mint',
+          toListId: 'All',
+          initiatedByListId: 'All',
+          approvalId: 'mint-1',
+          approvalCriteria: { overridesFromOutgoingApprovals: false }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('overridesFromOutgoingApprovals: true'))).toBe(true);
+  });
+
+  it('no issues for valid Mint approval', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals(
+      [
+        {
+          fromListId: 'Mint',
+          toListId: 'All',
+          initiatedByListId: 'All',
+          approvalId: 'mint-1',
+          approvalCriteria: { overridesFromOutgoingApprovals: true }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    // No errors about overrides
+    expect(issues.filter((i) => i.severity === 'error')).toHaveLength(0);
+  });
+
+  it('flags missing approvalId', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals([{ fromListId: 'All', toListId: 'All', initiatedByListId: 'All' }], 'approvals', issues);
+    expect(issues.some((i) => i.message.includes('approvalId'))).toBe(true);
+  });
+
+  it('skips non-object entries', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovals([null, undefined, 'string'], 'approvals', issues);
+    expect(issues).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateTokenMetadata
+// ---------------------------------------------------------------------------
+
+describe('validateTokenMetadata', () => {
+  it('flags entry without tokenIds', () => {
+    const issues: ValidationIssue[] = [];
+    validateTokenMetadata([{ uri: 'https://example.com' }], 'meta', issues);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].message).toContain('tokenIds');
+  });
+
+  it('flags entry with empty tokenIds array', () => {
+    const issues: ValidationIssue[] = [];
+    validateTokenMetadata([{ tokenIds: [] }], 'meta', issues);
+    expect(issues).toHaveLength(1);
+  });
+
+  it('no issues for valid entry', () => {
+    const issues: ValidationIssue[] = [];
+    validateTokenMetadata([{ tokenIds: [{ start: '1', end: '10' }] }], 'meta', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('skips null entries', () => {
+    const issues: ValidationIssue[] = [];
+    validateTokenMetadata([null], 'meta', issues);
+    expect(issues).toHaveLength(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validatePermissions
+// ---------------------------------------------------------------------------
+
+describe('validatePermissions', () => {
+  const allPermFields = () => ({
+    canDeleteCollection: [],
+    canArchiveCollection: [],
+    canUpdateStandards: [],
+    canUpdateCustomData: [],
+    canUpdateManager: [],
+    canUpdateCollectionMetadata: [],
+    canUpdateValidTokenIds: [],
+    canUpdateTokenMetadata: [],
+    canUpdateCollectionApprovals: [],
+    canAddMoreAliasPaths: [],
+    canAddMoreCosmosCoinWrapperPaths: []
+  });
+
+  it('no issues for complete permission object', () => {
+    const issues: ValidationIssue[] = [];
+    validatePermissions(allPermFields(), 'perms', issues);
+    expect(issues.filter((i) => i.severity === 'error')).toHaveLength(0);
+  });
+
+  it('flags missing required fields', () => {
+    const issues: ValidationIssue[] = [];
+    validatePermissions({}, 'perms', issues);
+    // Should flag all 11 missing fields
+    expect(issues.filter((i) => i.severity === 'error').length).toBe(11);
+  });
+
+  it('flags non-array permission field', () => {
+    const issues: ValidationIssue[] = [];
+    const perms = { ...allPermFields(), canDeleteCollection: 'not-an-array' };
+    validatePermissions(perms, 'perms', issues);
+    expect(issues.some((i) => i.message.includes('must be an array'))).toBe(true);
+  });
+
+  it('passthrough for null/undefined', () => {
+    const issues: ValidationIssue[] = [];
+    validatePermissions(null, 'perms', issues);
+    validatePermissions(undefined, 'perms', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('warns on both-empty time arrays', () => {
+    const issues: ValidationIssue[] = [];
+    const perms = {
+      ...allPermFields(),
+      canDeleteCollection: [{ permanentlyPermittedTimes: [], permanentlyForbiddenTimes: [] }]
+    };
+    validatePermissions(perms, 'perms', issues);
+    expect(issues.some((i) => i.severity === 'warning' && i.message.includes('both time arrays empty'))).toBe(true);
+  });
+
+  it('flags canUpdateTokenMetadata entry missing tokenIds when times are set', () => {
+    const issues: ValidationIssue[] = [];
+    const perms = {
+      ...allPermFields(),
+      canUpdateTokenMetadata: [
+        {
+          permanentlyPermittedTimes: [{ start: '1', end: '100' }],
+          permanentlyForbiddenTimes: []
+        }
+      ]
+    };
+    validatePermissions(perms, 'perms', issues);
+    expect(issues.some((i) => i.message.includes('MUST include tokenIds'))).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateApprovalCriteria
+// ---------------------------------------------------------------------------
+
+describe('validateApprovalCriteria', () => {
+  it('no issues for empty array', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria([], 'approvals', issues);
+    expect(issues).toHaveLength(0);
+  });
+
+  it('flags more than 1 merkleChallenge', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [{ approvalCriteria: { merkleChallenges: [{}, {}] } }],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('at most 1 merkleChallenge'))).toBe(true);
+  });
+
+  it('flags missing numUses plugin in claim', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [
+        {
+          approvalCriteria: {
+            merkleChallenges: [
+              {
+                claimConfig: {
+                  plugins: [{ pluginId: 'codes', publicParams: {} }]
+                }
+              }
+            ]
+          }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('numUses plugin'))).toBe(true);
+  });
+
+  it('flags numUses maxUses exceeding 50000', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [
+        {
+          approvalCriteria: {
+            merkleChallenges: [
+              {
+                claimConfig: {
+                  plugins: [{ pluginId: 'numUses', publicParams: { maxUses: 100000 } }]
+                }
+              }
+            ]
+          }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('exceeds 50,000'))).toBe(true);
+  });
+
+  it('flags codes numCodes exceeding 50000', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [
+        {
+          approvalCriteria: {
+            merkleChallenges: [
+              {
+                claimConfig: {
+                  plugins: [
+                    { pluginId: 'numUses', publicParams: { maxUses: 100 } },
+                    { pluginId: 'codes', publicParams: { numCodes: 60000 } }
+                  ]
+                }
+              }
+            ]
+          }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('codes numCodes'))).toBe(true);
+  });
+
+  it('warns when off-chain maxUses exceeds on-chain overallMaxNumTransfers', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [
+        {
+          approvalCriteria: {
+            merkleChallenges: [
+              {
+                claimConfig: {
+                  plugins: [{ pluginId: 'numUses', publicParams: { maxUses: 500 } }]
+                }
+              }
+            ],
+            maxNumTransfers: { overallMaxNumTransfers: '100' }
+          }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('exceeds on-chain'))).toBe(true);
+  });
+
+  it('warns when overallMaxNumTransfers is 0 but maxUses is set', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [
+        {
+          approvalCriteria: {
+            merkleChallenges: [
+              {
+                claimConfig: {
+                  plugins: [{ pluginId: 'numUses', publicParams: { maxUses: 10 } }]
+                }
+              }
+            ],
+            maxNumTransfers: { overallMaxNumTransfers: '0' }
+          }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('overallMaxNumTransfers is unset or "0"'))).toBe(true);
+  });
+
+  it('flags duplicate approvalIds', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [
+        { approvalId: 'dup', approvalCriteria: {} },
+        { approvalId: 'dup', approvalCriteria: {} }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('Duplicate approval IDs'))).toBe(true);
+  });
+
+  it('warns when both predeterminedBalances and approvalAmounts are set', () => {
+    const issues: ValidationIssue[] = [];
+    validateApprovalCriteria(
+      [
+        {
+          approvalCriteria: {
+            predeterminedBalances: {
+              incrementedBalances: { startBalances: [{ amount: '1' }] }
+            },
+            approvalAmounts: { overallApprovalAmount: '100' }
+          }
+        }
+      ],
+      'approvals',
+      issues
+    );
+    expect(issues.some((i) => i.message.includes('both predeterminedBalances and approvalAmounts'))).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateMsgConstructorFields
+// ---------------------------------------------------------------------------
+
+describe('validateMsgConstructorFields', () => {
+  it('flags non-array top-level field', () => {
+    const issues: ValidationIssue[] = [];
+    validateMsgConstructorFields({ validTokenIds: 'not-array' }, 'msg', issues);
+    expect(issues.some((i) => i.message.includes('"validTokenIds" must be an array'))).toBe(true);
+  });
+
+  it('flags missing collectionPermissions when updateCollectionPermissions is true', () => {
+    const issues: ValidationIssue[] = [];
+    validateMsgConstructorFields({ updateCollectionPermissions: true }, 'msg', issues);
+    expect(issues.some((i) => i.message.includes('collectionPermissions must be an object'))).toBe(true);
+  });
+
+  it('flags missing collectionMetadata when updateCollectionMetadata is true', () => {
+    const issues: ValidationIssue[] = [];
+    validateMsgConstructorFields({ updateCollectionMetadata: true }, 'msg', issues);
+    expect(issues.some((i) => i.message.includes('collectionMetadata must be an object'))).toBe(true);
+  });
+
+  it('flags missing defaultBalances fields', () => {
+    const issues: ValidationIssue[] = [];
+    validateMsgConstructorFields({ defaultBalances: {} }, 'msg', issues);
+    // Should flag balances, outgoingApprovals, incomingApprovals, userPermissions
+    expect(issues.filter((i) => i.severity === 'error').length).toBeGreaterThanOrEqual(4);
+  });
+
+  it('flags missing userPermissions sub-fields', () => {
+    const issues: ValidationIssue[] = [];
+    validateMsgConstructorFields(
+      {
+        defaultBalances: {
+          balances: [],
+          outgoingApprovals: [],
+          incomingApprovals: [],
+          userPermissions: {}
+        }
+      },
+      'msg',
+      issues
+    );
+    // Should flag all 5 user permission fields
+    expect(issues.filter((i) => i.message.includes('userPermissions.')).length).toBe(5);
+  });
+
+  it('flags collectionApprovals missing required fields', () => {
+    const issues: ValidationIssue[] = [];
+    validateMsgConstructorFields({ collectionApprovals: [{}] }, 'msg', issues);
+    // Should flag fromListId, toListId, initiatedByListId, approvalId, tokenIds, transferTimes, ownershipTimes, version
+    expect(issues.filter((i) => i.message.includes('missing required field')).length).toBe(8);
+  });
+
+  it('flags tokenMetadata entries without tokenIds', () => {
+    const issues: ValidationIssue[] = [];
+    validateMsgConstructorFields({ tokenMetadata: [{ uri: 'https://x.com' }] }, 'msg', issues);
+    expect(issues.some((i) => i.message.includes('tokenIds'))).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// validateTransaction (main orchestrator)
+// ---------------------------------------------------------------------------
+
+describe('validateTransaction', () => {
+  it('returns error for non-object input', () => {
+    const result = validateTransaction(null);
+    expect(result.valid).toBe(false);
+    expect(result.issues[0].message).toContain('must be a JSON object');
+  });
+
+  it('returns error for missing messages array', () => {
+    const result = validateTransaction({});
+    expect(result.valid).toBe(false);
+    expect(result.issues.some((i) => i.message.includes('"messages" array'))).toBe(true);
+  });
+
+  it('returns valid for minimal valid transaction', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgTransferTokens',
+          value: {
+            creator: 'bb1abc',
+            transfers: [{ prioritizedApprovals: [] }]
+          }
+        }
+      ]
+    });
+    expect(result.valid).toBe(true);
+  });
+
+  it('flags message missing typeUrl', () => {
+    const result = validateTransaction({ messages: [{ value: {} }] });
+    expect(result.issues.some((i) => i.message.includes('typeUrl'))).toBe(true);
+  });
+
+  it('flags message missing value', () => {
+    const result = validateTransaction({ messages: [{ typeUrl: '/tokenization.MsgTransferTokens' }] });
+    expect(result.issues.some((i) => i.message.includes('missing "value"'))).toBe(true);
+  });
+
+  it('flags MsgTransferTokens missing creator', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgTransferTokens',
+          value: { transfers: [] }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('MsgTransferTokens missing "creator"'))).toBe(true);
+  });
+
+  it('flags MsgTransferTokens missing transfers', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgTransferTokens',
+          value: { creator: 'bb1abc' }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('missing "transfers"'))).toBe(true);
+  });
+
+  it('warns when transfer missing prioritizedApprovals', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgTransferTokens',
+          value: { creator: 'bb1abc', transfers: [{}] }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('prioritizedApprovals'))).toBe(true);
+  });
+
+  it('flags MsgUniversalUpdateCollection missing creator', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgUniversalUpdateCollection',
+          value: {}
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('missing "creator"'))).toBe(true);
+  });
+
+  it('warns on non-bb1 creator address', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgUniversalUpdateCollection',
+          value: { creator: '0x1234', collectionId: '0' }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('should start with "bb1"'))).toBe(true);
+  });
+
+  it('flags missing collectionId', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgUniversalUpdateCollection',
+          value: { creator: 'bb1abc' }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('missing "collectionId"'))).toBe(true);
+  });
+
+  it('flags mintEscrowCoinsToTransfer > 1 entry', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgUniversalUpdateCollection',
+          value: {
+            creator: 'bb1abc',
+            collectionId: '1',
+            mintEscrowCoinsToTransfer: [{ denom: 'ubadge', amount: '1' }, { denom: 'ustake', amount: '2' }]
+          }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('at most 1 coin entry'))).toBe(true);
+  });
+
+  it('flags new mint collection without autoApproveAllIncomingTransfers', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgUniversalUpdateCollection',
+          value: {
+            creator: 'bb1abc',
+            collectionId: '0',
+            collectionApprovals: [
+              {
+                fromListId: 'Mint',
+                toListId: 'All',
+                initiatedByListId: 'All',
+                approvalId: 'mint-1',
+                tokenIds: [{ start: '1', end: '1' }],
+                transferTimes: [{ start: '1', end: '18446744073709551615' }],
+                ownershipTimes: [{ start: '1', end: '18446744073709551615' }],
+                version: '0',
+                approvalCriteria: { overridesFromOutgoingApprovals: true }
+              }
+            ],
+            defaultBalances: {
+              balances: [],
+              outgoingApprovals: [],
+              incomingApprovals: [],
+              autoApproveAllIncomingTransfers: false,
+              userPermissions: {
+                canUpdateOutgoingApprovals: [],
+                canUpdateIncomingApprovals: [],
+                canUpdateAutoApproveSelfInitiatedOutgoingTransfers: [],
+                canUpdateAutoApproveSelfInitiatedIncomingTransfers: [],
+                canUpdateAutoApproveAllIncomingTransfers: []
+              }
+            }
+          }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('autoApproveAllIncomingTransfers is not true'))).toBe(true);
+  });
+
+  it('flags numbers used where strings expected (recursive)', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgUniversalUpdateCollection',
+          value: {
+            creator: 'bb1abc',
+            collectionId: 0 // number instead of string
+          }
+        }
+      ]
+    });
+    expect(result.issues.some((i) => i.message.includes('Number value found where string expected'))).toBe(true);
+  });
+
+  it('valid is true when only warnings (no errors)', () => {
+    const result = validateTransaction({
+      messages: [
+        {
+          typeUrl: '/tokenization.MsgTransferTokens',
+          value: {
+            creator: 'bb1abc',
+            transfers: [{}] // missing prioritizedApprovals is only a warning
+          }
+        }
+      ]
+    });
+    // prioritizedApprovals warning shouldn't make valid = false
+    expect(result.valid).toBe(true);
+    expect(result.issues.length).toBeGreaterThan(0);
+  });
+});
diff --git a/packages/bitbadgesjs-sdk/src/core/validate.ts b/packages/bitbadgesjs-sdk/src/core/validate.ts
index 005de95cb4..fcae0e392a 100644
--- a/packages/bitbadgesjs-sdk/src/core/validate.ts
+++ b/packages/bitbadgesjs-sdk/src/core/validate.ts
@@ -1,8 +1,8 @@
 /**
  * Transaction validation utilities for BitBadges.
  *
- * Pure validation logic extracted from the MCP validate_transaction tool.
- * No Zod schemas, no MCP tool definitions, no MCP response formatting.
+ * Pure validation logic extracted from the builder validate_transaction tool.
+ * No Zod schemas, no tool definitions, no response formatting.
  *
  * @module
  */
@@ -273,7 +273,23 @@ export function validateSubscriptionApproval(approval: Record<string, unknown>,
 /**
  * Validate approvals array — list IDs, Mint rules, backing address rules, required fields.
  */
-export function validateApprovals(approvals: unknown[], path: string, issues: ValidationIssue[], standards?: string[]): void {
+/**
+ * Approval level — determines which rules apply. Collection approvals carry
+ * the full `ApprovalCriteria` proto (overridesFromOutgoingApprovals,
+ * allowBackedMinting, etc.); user-level outgoing/incoming approvals carry
+ * the narrower `OutgoingApprovalCriteria` / `IncomingApprovalCriteria`
+ * proto types that omit the collection-only fields. Rules that reference
+ * those omitted fields are skipped when the level isn't 'collection'.
+ */
+export type ApprovalLevel = 'collection' | 'outgoing' | 'incoming';
+
+export function validateApprovals(
+  approvals: unknown[],
+  path: string,
+  issues: ValidationIssue[],
+  standards?: string[],
+  level: ApprovalLevel = 'collection'
+): void {
   const isSubscription = Array.isArray(standards) && standards.includes('Subscriptions');
 
   approvals.forEach((approval, index) => {
@@ -284,7 +300,9 @@ export function validateApprovals(approvals: unknown[], path: string, issues: Va
     const a = approval as Record<string, unknown>;
     const approvalPath = `${path}[${index}]`;
 
-    // Check list IDs
+    // Check list IDs — `fromListId` is absent on UserOutgoingApproval and
+    // `toListId` is absent on UserIncomingApproval, so the `in a` guard
+    // cleanly skips the missing field at each level.
     (['fromListId', 'toListId', 'initiatedByListId'] as const).forEach((field) => {
       if (field in a && typeof a[field] === 'string') {
         if (!isValidListId(a[field] as string)) {
@@ -297,7 +315,12 @@ export function validateApprovals(approvals: unknown[], path: string, issues: Va
       }
     });
 
-    // "Mint" must only appear in fromListId — it is the minting source, not a destination or initiator.
+    // "Mint" must only appear in fromListId — it is the minting source, not
+    // a destination or initiator. Applies at every level: even a user-level
+    // outgoing approval can't legitimately have `toListId: "Mint"`, and
+    // `initiatedByListId: "Mint"` is nonsense everywhere. On incoming,
+    // `fromListId: "Mint"` IS legitimate (receiving from the mint source)
+    // and is intentionally not checked here.
     if (typeof a.toListId === 'string' && (a.toListId === 'Mint' || (a.toListId as string).includes('Mint'))) {
       issues.push({
         severity: 'error',
@@ -313,36 +336,42 @@ export function validateApprovals(approvals: unknown[], path: string, issues: Va
       });
     }
 
-    // Check Mint approval override
-    if (a.fromListId === 'Mint') {
-      const criteria = a.approvalCriteria as Record<string, unknown> | undefined;
-      if (criteria && criteria.overridesFromOutgoingApprovals !== true) {
-        issues.push({
-          severity: 'error',
-          message: 'Mint approvals MUST have overridesFromOutgoingApprovals: true',
-          path: `${approvalPath}.approvalCriteria.overridesFromOutgoingApprovals`
-        });
-      }
+    // The next three rules inspect collection-only criteria fields
+    // (`overridesFromOutgoingApprovals`, `allowBackedMinting`) and the
+    // Subscriptions standard which only lives on the collection. Skip
+    // entirely for user-level approvals.
+    if (level === 'collection') {
+      // Check Mint approval override
+      if (a.fromListId === 'Mint') {
+        const criteria = a.approvalCriteria as Record<string, unknown> | undefined;
+        if (criteria && criteria.overridesFromOutgoingApprovals !== true) {
+          issues.push({
+            severity: 'error',
+            message: 'Mint approvals MUST have overridesFromOutgoingApprovals: true',
+            path: `${approvalPath}.approvalCriteria.overridesFromOutgoingApprovals`
+          });
+        }
 
-      // Subscription-specific validations
-      if (isSubscription) {
-        validateSubscriptionApproval(a, approvalPath, issues);
+        // Subscription-specific validations
+        if (isSubscription) {
+          validateSubscriptionApproval(a, approvalPath, issues);
+        }
       }
-    }
 
-    // Check backing address approvals should NOT have overridesFromOutgoingApprovals: true
-    if (typeof a.fromListId === 'string' && (a.fromListId as string).startsWith('bb1') && !(a.fromListId as string).includes('Mint')) {
-      const criteria = a.approvalCriteria as Record<string, unknown> | undefined;
-      if (criteria && criteria.overridesFromOutgoingApprovals === true && criteria.allowBackedMinting === true) {
-        issues.push({
-          severity: 'warning',
-          message: 'Backing address approvals should NOT have overridesFromOutgoingApprovals: true',
-          path: `${approvalPath}.approvalCriteria.overridesFromOutgoingApprovals`
-        });
+      // Check backing address approvals should NOT have overridesFromOutgoingApprovals: true
+      if (typeof a.fromListId === 'string' && (a.fromListId as string).startsWith('bb1') && !(a.fromListId as string).includes('Mint')) {
+        const criteria = a.approvalCriteria as Record<string, unknown> | undefined;
+        if (criteria && criteria.overridesFromOutgoingApprovals === true && criteria.allowBackedMinting === true) {
+          issues.push({
+            severity: 'warning',
+            message: 'Backing address approvals should NOT have overridesFromOutgoingApprovals: true',
+            path: `${approvalPath}.approvalCriteria.overridesFromOutgoingApprovals`
+          });
+        }
       }
     }
 
-    // Check approvalId exists
+    // Check approvalId exists — applies at every level.
     if (!a.approvalId || typeof a.approvalId !== 'string') {
       issues.push({
         severity: 'error',
@@ -567,6 +596,60 @@ export function validateApprovalCriteria(approvals: unknown[], path: string, iss
       }
     }
 
+    // --- approvalAmounts / maxNumTransfers: complete object required ---
+    // Proto defines these as fixed-shape messages. Missing sibling fields on a partially-
+    // populated object are a shape-error — the SDK constructor will produce undefined values
+    // that crash toProto(). Throw clearly so the AI fixes the shape rather than silently
+    // coercing. Also enforce that any non-zero limit must have an amountTrackerId so
+    // independent approvals don't share a tracker and cross-contaminate.
+    const AA_FIELDS = [
+      'overallApprovalAmount',
+      'perToAddressApprovalAmount',
+      'perFromAddressApprovalAmount',
+      'perInitiatedByAddressApprovalAmount'
+    ];
+    const MNT_FIELDS = [
+      'overallMaxNumTransfers',
+      'perToAddressMaxNumTransfers',
+      'perFromAddressMaxNumTransfers',
+      'perInitiatedByAddressMaxNumTransfers'
+    ];
+    const checkCompleteLimit = (
+      obj: Record<string, any> | undefined,
+      fields: string[],
+      label: string,
+      subPath: string
+    ) => {
+      if (!obj) return;
+      const missing = fields.filter((f) => !(f in obj));
+      if (missing.length > 0 && missing.length < fields.length) {
+        issues.push({
+          severity: 'error',
+          message: `${label} is missing sibling fields [${missing.join(', ')}]. The proto expects a complete object with all ${fields.length} amount fields (use "0" for unbounded). Partial objects produce undefined values and crash the SDK constructor.`,
+          path: `${approvalPath}.approvalCriteria.${subPath}`
+        });
+      }
+      // resetTimeIntervals must exist as an object if the parent is set
+      if (!obj.resetTimeIntervals || typeof obj.resetTimeIntervals !== 'object') {
+        issues.push({
+          severity: 'error',
+          message: `${label}.resetTimeIntervals is required. Use { startTime: "0", intervalLength: "0" } for no reset interval.`,
+          path: `${approvalPath}.approvalCriteria.${subPath}.resetTimeIntervals`
+        });
+      }
+      // amountTrackerId must be set when any non-zero limit is configured (prevents cross-contamination)
+      const hasLimit = fields.some((f) => obj[f] && String(obj[f]) !== '0');
+      if (hasLimit && (!obj.amountTrackerId || String(obj.amountTrackerId).trim() === '')) {
+        issues.push({
+          severity: 'error',
+          message: `${label} has a non-zero limit but amountTrackerId is empty. Set amountTrackerId to a unique string (typically the approvalId) so this tracker does not collide with other approvals.`,
+          path: `${approvalPath}.approvalCriteria.${subPath}.amountTrackerId`
+        });
+      }
+    };
+    checkCompleteLimit(criteria.approvalAmounts as Record<string, any> | undefined, AA_FIELDS, 'approvalAmounts', 'approvalAmounts');
+    checkCompleteLimit(criteria.maxNumTransfers as Record<string, any> | undefined, MNT_FIELDS, 'maxNumTransfers', 'maxNumTransfers');
+
     // predeterminedBalances + approvalAmounts — unusual combination warning
     const predet = criteria.predeterminedBalances as Record<string, any> | undefined;
     const amounts = criteria.approvalAmounts as Record<string, any> | undefined;
@@ -665,17 +748,78 @@ export function validateMsgConstructorFields(value: Record<string, unknown>, bas
     // Detailed field checks are handled by validatePermissions()
   }
 
-  // --- collectionMetadata: must be an object with uri ---
-  if (value.updateCollectionMetadata === true) {
+  // --- collectionMetadata: must be an object (not an array) with uri + customData ---
+  // Proto CollectionMetadata has only { uri, customData } — it is NOT a repeated field.
+  // Claude occasionally hallucinates an array (confusing it with tokenMetadata[]); reject loudly.
+  if (Array.isArray(value.collectionMetadata)) {
+    issues.push({
+      severity: 'error',
+      message:
+        'collectionMetadata must be an object { uri, customData }, not an array. You may be confusing it with tokenMetadata (which IS an array of { uri, customData, tokenIds }).',
+      path: `${basePath}.collectionMetadata`
+    });
+  } else if (value.updateCollectionMetadata === true) {
     if (!value.collectionMetadata || typeof value.collectionMetadata !== 'object') {
       issues.push({
         severity: 'error',
         message: 'collectionMetadata must be an object when updateCollectionMetadata is true.',
         path: `${basePath}.collectionMetadata`
       });
+    } else {
+      const cm = value.collectionMetadata as Record<string, unknown>;
+      if ('image' in cm || 'name' in cm || 'description' in cm) {
+        issues.push({
+          severity: 'error',
+          message:
+            'collectionMetadata only has { uri, customData } fields per the proto spec. Fields like "image", "name", and "description" belong inside the off-chain JSON referenced by uri (or in metadataPlaceholders), not directly on collectionMetadata.',
+          path: `${basePath}.collectionMetadata`
+        });
+      }
     }
   }
 
+  // --- aliasPathsToAdd / cosmosCoinWrapperPathsToAdd: PathMetadata has { uri, customData } ONLY ---
+  // The proto PathMetadata message has no image/name/description. Claude hallucinates these at the
+  // wrong nesting level (they belong inside the off-chain JSON at `uri`). Throw clearly.
+  const checkPathMetadata = (paths: unknown, parentField: string) => {
+    if (!Array.isArray(paths)) return;
+    (paths as unknown[]).forEach((p, i) => {
+      if (!p || typeof p !== 'object') return;
+      const path = p as Record<string, unknown>;
+      const md = path.metadata as Record<string, unknown> | undefined;
+      if (md && typeof md === 'object') {
+        for (const bad of ['image', 'name', 'description']) {
+          if (bad in md) {
+            issues.push({
+              severity: 'error',
+              message: `${parentField}[${i}].metadata.${bad} is not a valid field. PathMetadata only has { uri, customData } — put "${bad}" inside the off-chain JSON referenced by metadata.uri.`,
+              path: `${basePath}.${parentField}[${i}].metadata.${bad}`
+            });
+          }
+        }
+      }
+      if (Array.isArray(path.denomUnits)) {
+        (path.denomUnits as unknown[]).forEach((du, duIdx) => {
+          if (!du || typeof du !== 'object') return;
+          const duMd = (du as Record<string, unknown>).metadata as Record<string, unknown> | undefined;
+          if (duMd && typeof duMd === 'object') {
+            for (const bad of ['image', 'name', 'description']) {
+              if (bad in duMd) {
+                issues.push({
+                  severity: 'error',
+                  message: `${parentField}[${i}].denomUnits[${duIdx}].metadata.${bad} is not a valid field. PathMetadata only has { uri, customData }.`,
+                  path: `${basePath}.${parentField}[${i}].denomUnits[${duIdx}].metadata.${bad}`
+                });
+              }
+            }
+          }
+        });
+      }
+    });
+  };
+  checkPathMetadata(value.aliasPathsToAdd, 'aliasPathsToAdd');
+  checkPathMetadata(value.cosmosCoinWrapperPathsToAdd, 'cosmosCoinWrapperPathsToAdd');
+
   // --- defaultBalances: full structure check ---
   if (value.defaultBalances && typeof value.defaultBalances === 'object') {
     const db = value.defaultBalances as Record<string, unknown>;
@@ -876,10 +1020,41 @@ export function validateTransaction(txBody: any): ValidationResult {
 
     const value = message.value as Record<string, unknown>;
 
-    // Validate MsgUniversalUpdateCollection
-    if (message.typeUrl === '/tokenization.MsgUniversalUpdateCollection') {
+    // Validate MsgCreateCollection / MsgUpdateCollection / legacy
+    // MsgUniversalUpdateCollection. All three share the collection
+    // configuration shape — Create omits `collectionId` + the update flags,
+    // Update rejects `defaultBalances` + `invariants`. Validation is
+    // field-driven, not type-url-driven, so the same rules apply and we
+    // only branch on type-url for the two create/update-specific checks.
+    const _tUrl = typeof message.typeUrl === 'string' ? message.typeUrl : '';
+    const _isCreate = _tUrl.endsWith('.MsgCreateCollection');
+    const _isUpdate = _tUrl.endsWith('.MsgUpdateCollection');
+    const _isUniversal = _tUrl.endsWith('.MsgUniversalUpdateCollection');
+    if (_isCreate || _isUpdate || _isUniversal) {
       // --- Constructor sanity check: ensure all fields the SDK constructor expects exist ---
-      validateMsgConstructorFields(value, `${msgPath}.value`, issues);
+      // MsgCreateCollection has no `updateXxxTimeline` flags — every field
+      // you set IS set, and every field you DIDN'T set is simply absent
+      // (no "do not update" semantics, because there's nothing to update
+      // from). The downstream constructor check is gated on
+      // `updateXxx === true` + required field shape. For Create, only set
+      // the implied flag if the corresponding value field is actually
+      // present; missing fields mean "default empty" and shouldn't
+      // trigger "missing required object" errors.
+      const _ctorValue: Record<string, unknown> = _isCreate
+        ? {
+            ...value,
+            ...(value.validTokenIds !== undefined && { updateValidTokenIds: true }),
+            ...(value.collectionPermissions !== undefined && { updateCollectionPermissions: true }),
+            ...(value.manager !== undefined && { updateManager: true }),
+            ...(value.collectionMetadata !== undefined && { updateCollectionMetadata: true }),
+            ...(value.tokenMetadata !== undefined && { updateTokenMetadata: true }),
+            ...(value.customData !== undefined && { updateCustomData: true }),
+            ...(value.collectionApprovals !== undefined && { updateCollectionApprovals: true }),
+            ...(value.standards !== undefined && { updateStandards: true }),
+            ...(value.isArchived !== undefined && { updateIsArchived: true })
+          }
+        : value;
+      validateMsgConstructorFields(_ctorValue, `${msgPath}.value`, issues);
 
       // --- mintEscrowCoinsToTransfer max 1 ---
       if (Array.isArray(value.mintEscrowCoinsToTransfer) && (value.mintEscrowCoinsToTransfer as unknown[]).length > 1) {
@@ -896,7 +1071,7 @@ export function validateTransaction(txBody: any): ValidationResult {
       if (!value.creator || typeof value.creator !== 'string') {
         issues.push({
           severity: 'error',
-          message: 'MsgUniversalUpdateCollection missing "creator" field',
+          message: 'Collection message missing "creator" field',
           path: `${msgPath}.value.creator`
         });
       } else if (!(value.creator as string).startsWith('bb1')) {
@@ -907,8 +1082,17 @@ export function validateTransaction(txBody: any): ValidationResult {
         });
       }
 
-      // Check collectionId
-      if (!('collectionId' in value)) {
+      // Check collectionId — required on Update/Universal, must be absent
+      // (or "0") on Create per proto. We only flag the Update case.
+      if (_isUpdate) {
+        if (!('collectionId' in value) || value.collectionId === '0' || value.collectionId === 0) {
+          issues.push({
+            severity: 'error',
+            message: 'MsgUpdateCollection requires a non-zero "collectionId"',
+            path: `${msgPath}.value.collectionId`
+          });
+        }
+      } else if (_isUniversal && !('collectionId' in value)) {
         issues.push({
           severity: 'error',
           message: 'MsgUniversalUpdateCollection missing "collectionId" field',
@@ -916,6 +1100,27 @@ export function validateTransaction(txBody: any): ValidationResult {
         });
       }
 
+      // Chain-only fields that are illegal on Update (proto comment on
+      // invariants: "set upon genesis and cannot be modified"; Update drops
+      // `defaultBalances` entirely). Catch these at static validation so
+      // the user sees the problem before the chain rejects the tx.
+      if (_isUpdate) {
+        if (value.defaultBalances !== undefined) {
+          issues.push({
+            severity: 'error',
+            message: 'MsgUpdateCollection must not set "defaultBalances" (create-only field).',
+            path: `${msgPath}.value.defaultBalances`
+          });
+        }
+        if (value.invariants !== undefined) {
+          issues.push({
+            severity: 'error',
+            message: 'MsgUpdateCollection must not set "invariants" (set at genesis only).',
+            path: `${msgPath}.value.invariants`
+          });
+        }
+      }
+
       // Validate collectionApprovals
       if (Array.isArray(value.collectionApprovals)) {
         const standards = Array.isArray(value.standards) ? (value.standards as string[]) : undefined;
@@ -923,13 +1128,30 @@ export function validateTransaction(txBody: any): ValidationResult {
         validateApprovalCriteria(value.collectionApprovals as unknown[], `${msgPath}.value.collectionApprovals`, issues);
       }
 
-      // Validate approval criteria in defaultBalances
+      // Validate approval criteria in defaultBalances. These live on the
+      // collection msg but are user-level approvals (the default the user
+      // gets on first receipt), so validate them with the matching level
+      // to avoid false positives from collection-only rules.
       if (value.defaultBalances && typeof value.defaultBalances === 'object') {
         const db = value.defaultBalances as Record<string, unknown>;
         if (Array.isArray(db.incomingApprovals)) {
+          validateApprovals(
+            db.incomingApprovals as unknown[],
+            `${msgPath}.value.defaultBalances.incomingApprovals`,
+            issues,
+            undefined,
+            'incoming'
+          );
           validateApprovalCriteria(db.incomingApprovals as unknown[], `${msgPath}.value.defaultBalances.incomingApprovals`, issues);
         }
         if (Array.isArray(db.outgoingApprovals)) {
+          validateApprovals(
+            db.outgoingApprovals as unknown[],
+            `${msgPath}.value.defaultBalances.outgoingApprovals`,
+            issues,
+            undefined,
+            'outgoing'
+          );
           validateApprovalCriteria(db.outgoingApprovals as unknown[], `${msgPath}.value.defaultBalances.outgoingApprovals`, issues);
         }
       }
@@ -987,6 +1209,106 @@ export function validateTransaction(txBody: any): ValidationResult {
       }
     }
 
+    // ── User-level approval messages ────────────────────────────────────
+    //
+    // MsgUpdateUserApprovals / MsgSetIncomingApproval / MsgSetOutgoingApproval
+    // all carry UserIncomingApproval / UserOutgoingApproval objects that
+    // share the same `approvalCriteria` shape as collection approvals — so
+    // we reuse `validateApprovals` + `validateApprovalCriteria` against
+    // them. The CLI is the only consumer of user-level validation; the
+    // frontend / indexer AI builder stay CRUD-collection-scoped per product
+    // decision.
+    //
+    // Shared creator-field check first, then per-msg field dispatch.
+    const _isUserApprovalMsg =
+      message.typeUrl === '/tokenization.MsgUpdateUserApprovals' ||
+      message.typeUrl === '/tokenization.MsgSetIncomingApproval' ||
+      message.typeUrl === '/tokenization.MsgSetOutgoingApproval' ||
+      message.typeUrl === '/tokenization.MsgDeleteIncomingApproval' ||
+      message.typeUrl === '/tokenization.MsgDeleteOutgoingApproval' ||
+      message.typeUrl === '/tokenization.MsgPurgeApprovals';
+    if (_isUserApprovalMsg) {
+      if (!value.creator || typeof value.creator !== 'string') {
+        issues.push({
+          severity: 'error',
+          message: `${message.typeUrl} missing "creator" field`,
+          path: `${msgPath}.value.creator`
+        });
+      } else if (!(value.creator as string).startsWith('bb1')) {
+        issues.push({
+          severity: 'warning',
+          message: 'Creator address should start with "bb1"',
+          path: `${msgPath}.value.creator`
+        });
+      }
+      // collectionId is required & non-zero on every user-level approval msg.
+      if (!('collectionId' in value) || value.collectionId === '0' || value.collectionId === 0) {
+        issues.push({
+          severity: 'error',
+          message: `${message.typeUrl} requires a non-zero "collectionId"`,
+          path: `${msgPath}.value.collectionId`
+        });
+      }
+    }
+
+    if (message.typeUrl === '/tokenization.MsgUpdateUserApprovals') {
+      if (value.updateOutgoingApprovals === true && Array.isArray(value.outgoingApprovals)) {
+        validateApprovals(
+          value.outgoingApprovals as unknown[],
+          `${msgPath}.value.outgoingApprovals`,
+          issues,
+          undefined,
+          'outgoing'
+        );
+        validateApprovalCriteria(value.outgoingApprovals as unknown[], `${msgPath}.value.outgoingApprovals`, issues);
+      }
+      if (value.updateIncomingApprovals === true && Array.isArray(value.incomingApprovals)) {
+        validateApprovals(
+          value.incomingApprovals as unknown[],
+          `${msgPath}.value.incomingApprovals`,
+          issues,
+          undefined,
+          'incoming'
+        );
+        validateApprovalCriteria(value.incomingApprovals as unknown[], `${msgPath}.value.incomingApprovals`, issues);
+      }
+    }
+
+    if (
+      message.typeUrl === '/tokenization.MsgSetIncomingApproval' ||
+      message.typeUrl === '/tokenization.MsgSetOutgoingApproval'
+    ) {
+      if (!value.approval || typeof value.approval !== 'object') {
+        issues.push({
+          severity: 'error',
+          message: `${message.typeUrl} missing "approval" object`,
+          path: `${msgPath}.value.approval`
+        });
+      } else {
+        // validateApprovals / validateApprovalCriteria expect an array —
+        // wrap the single approval. The rendered path will read
+        // `.approval[0]` but the user knows they only set one.
+        const single = [value.approval as unknown];
+        const level: ApprovalLevel =
+          message.typeUrl === '/tokenization.MsgSetIncomingApproval' ? 'incoming' : 'outgoing';
+        validateApprovals(single, `${msgPath}.value.approval`, issues, undefined, level);
+        validateApprovalCriteria(single, `${msgPath}.value.approval`, issues);
+      }
+    }
+
+    if (
+      message.typeUrl === '/tokenization.MsgDeleteIncomingApproval' ||
+      message.typeUrl === '/tokenization.MsgDeleteOutgoingApproval'
+    ) {
+      if (!value.approvalId || typeof value.approvalId !== 'string' || !(value.approvalId as string).trim()) {
+        issues.push({
+          severity: 'error',
+          message: `${message.typeUrl} requires a non-empty "approvalId"`,
+          path: `${msgPath}.value.approvalId`
+        });
+      }
+    }
+
     // Validate MsgTransferTokens
     if (message.typeUrl === '/tokenization.MsgTransferTokens') {
       // Check creator
diff --git a/packages/bitbadgesjs-sdk/src/core/verify-standards.ts b/packages/bitbadgesjs-sdk/src/core/verify-standards.ts
index fba9f4c763..ecb9e24a85 100644
--- a/packages/bitbadgesjs-sdk/src/core/verify-standards.ts
+++ b/packages/bitbadgesjs-sdk/src/core/verify-standards.ts
@@ -13,9 +13,10 @@
 
 import { CollectionDoc } from '../api-indexer/docs-types/docs.js';
 import { doesCollectionFollowSubscriptionProtocol } from './subscriptions.js';
+import { normalizeForReview } from './review-normalize.js';
 
-const MAX_UINT64 = '18446744073709551615';
-const FOREVER = [{ start: '1', end: MAX_UINT64 }];
+const MAX_UINT64 = 18446744073709551615n;
+const FOREVER = [{ start: 1n, end: MAX_UINT64 }];
 const BURN_ADDRESS = 'bb1qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqs7gvmv';
 
 // ============================================================
@@ -41,12 +42,12 @@ export interface VerificationResult {
 
 function isForever(times: any[]): boolean {
   if (!Array.isArray(times) || times.length !== 1) return false;
-  return String(times[0]?.start) === '1' && String(times[0]?.end) === MAX_UINT64;
+  return times[0]?.start === 1n && times[0]?.end === MAX_UINT64;
 }
 
 function isSingleToken(tokenIds: any[]): boolean {
   if (!Array.isArray(tokenIds) || tokenIds.length !== 1) return false;
-  return String(tokenIds[0]?.start) === '1' && String(tokenIds[0]?.end) === '1';
+  return tokenIds[0]?.start === 1n && tokenIds[0]?.end === 1n;
 }
 
 function getApprovals(value: any): any[] {
@@ -174,8 +175,11 @@ function verifySmartToken(value: any): StandardViolation[] {
     });
   }
 
-  // Must have alias path
-  const hasAliasPath = (value.aliasPathsToAdd && value.aliasPathsToAdd.length > 0) || invariants.aliasPath;
+  // Must have alias path. Tolerate both field names:
+  //   - aliasPathsToAdd (MsgUniversalUpdateCollection create shape)
+  //   - aliasPaths (frontend collection store shape)
+  const aliasPaths = value.aliasPathsToAdd || value.aliasPaths || [];
+  const hasAliasPath = aliasPaths.length > 0 || invariants.aliasPath;
   if (!hasAliasPath) {
     violations.push({
       standard: std,
@@ -194,7 +198,7 @@ function verifySubscription(value: any): StandardViolation[] {
 
   // validTokenIds must start at 1 (one range, supports multi-tier)
   const vt = value.validTokenIds;
-  if (!Array.isArray(vt) || vt.length !== 1 || String(vt[0]?.start) !== '1') {
+  if (!Array.isArray(vt) || vt.length !== 1 || vt[0]?.start !== 1n) {
     violations.push({
       standard: std,
       field: 'validTokenIds',
@@ -247,7 +251,7 @@ function verifySubscription(value: any): StandardViolation[] {
         field: `${prefix}.predeterminedBalances.incrementedBalances.startBalances`,
         message: `Subscription approval "${approval.approvalId}" startBalances must have exactly 1 entry.`
       });
-    } else if (String(ib.startBalances[0]?.amount) !== '1') {
+    } else if (ib.startBalances[0]?.amount !== 1n) {
       violations.push({
         standard: std,
         field: `${prefix}.predeterminedBalances.incrementedBalances.startBalances[0].amount`,
@@ -256,7 +260,7 @@ function verifySubscription(value: any): StandardViolation[] {
     }
 
     // durationFromTimestamp must be non-zero
-    if (!ib.durationFromTimestamp || ib.durationFromTimestamp === '0') {
+    if (!ib.durationFromTimestamp || ib.durationFromTimestamp === 0n) {
       violations.push({
         standard: std,
         field: `${prefix}.predeterminedBalances.incrementedBalances.durationFromTimestamp`,
@@ -275,31 +279,31 @@ function verifySubscription(value: any): StandardViolation[] {
       });
     }
 
-    // incrementTokenIdsBy and incrementOwnershipTimesBy should be "0"
-    if (ib.incrementTokenIdsBy && ib.incrementTokenIdsBy !== '0') {
+    // incrementTokenIdsBy and incrementOwnershipTimesBy should be 0
+    if (ib.incrementTokenIdsBy && ib.incrementTokenIdsBy !== 0n) {
       violations.push({
         standard: std,
         field: `${prefix}.predeterminedBalances.incrementedBalances.incrementTokenIdsBy`,
-        message: `Subscription approval "${approval.approvalId}" incrementTokenIdsBy should be "0" (single token ID for subscriptions).`
+        message: `Subscription approval "${approval.approvalId}" incrementTokenIdsBy should be 0 (single token ID for subscriptions).`
       });
     }
-    if (ib.incrementOwnershipTimesBy && ib.incrementOwnershipTimesBy !== '0') {
+    if (ib.incrementOwnershipTimesBy && ib.incrementOwnershipTimesBy !== 0n) {
       violations.push({
         standard: std,
         field: `${prefix}.predeterminedBalances.incrementedBalances.incrementOwnershipTimesBy`,
-        message: `Subscription approval "${approval.approvalId}" incrementOwnershipTimesBy should be "0".`
+        message: `Subscription approval "${approval.approvalId}" incrementOwnershipTimesBy should be 0.`
       });
     }
 
     // Mutual exclusivity: only ONE of durationFromTimestamp, incrementOwnershipTimesBy, recurringOwnershipTimes can be non-zero
     const rot = ib.recurringOwnershipTimes;
-    const hasDuration = ib.durationFromTimestamp && ib.durationFromTimestamp !== '0';
-    const hasIncrement = ib.incrementOwnershipTimesBy && ib.incrementOwnershipTimesBy !== '0';
+    const hasDuration = ib.durationFromTimestamp && ib.durationFromTimestamp !== 0n;
+    const hasIncrement = ib.incrementOwnershipTimesBy && ib.incrementOwnershipTimesBy !== 0n;
     const hasRecurring =
       rot &&
-      ((rot.startTime && rot.startTime !== '0') ||
-        (rot.intervalLength && rot.intervalLength !== '0') ||
-        (rot.chargePeriodLength && rot.chargePeriodLength !== '0'));
+      ((rot.startTime && rot.startTime !== 0n) ||
+        (rot.intervalLength && rot.intervalLength !== 0n) ||
+        (rot.chargePeriodLength && rot.chargePeriodLength !== 0n));
     const activeCount = [hasDuration, hasIncrement, hasRecurring].filter(Boolean).length;
     if (activeCount > 1) {
       violations.push({
@@ -391,7 +395,7 @@ function verifyNFTCollection(value: any): StandardViolation[] {
   const invariants = getInvariants(value);
 
   // maxSupplyPerId should be "1" for true NFTs
-  if (!invariants.maxSupplyPerId || String(invariants.maxSupplyPerId) !== '1') {
+  if (!invariants.maxSupplyPerId || invariants.maxSupplyPerId !== 1n) {
     violations.push({
       standard: std,
       field: 'invariants.maxSupplyPerId',
@@ -568,30 +572,12 @@ function verifyCreditToken(value: any): StandardViolation[] {
   return violations;
 }
 
-function verifyQuest(value: any): StandardViolation[] {
-  const violations: StandardViolation[] = [];
-  const std = 'Quest';
-  const mintApprovals = getMintApprovals(value);
-
-  // Should have at least one mint approval with coinTransfers (reward payout)
-  const hasRewardApproval = mintApprovals.some(
-    (a: any) => a.approvalCriteria?.coinTransfers && a.approvalCriteria.coinTransfers.length > 0
-  );
-
-  // Check escrow vs payout — warning only (user can fund later)
-  if (hasRewardApproval) {
-    const escrowCoins = value.mintEscrowCoinsToTransfer || [];
-    if (escrowCoins.length === 0) {
-      violations.push({
-        standard: std,
-        field: 'mintEscrowCoinsToTransfer',
-        message:
-          'Quest has reward payouts but no escrow funding configured. Users will not be able to claim rewards until the escrow is funded. You can fund it later by sending coins to the mint escrow address.'
-      });
-    }
-  }
-
-  return violations;
+function verifyQuest(_value: any): StandardViolation[] {
+  // Quest-specific checks moved to review-ux/skills.ts so they can ship
+  // as soft warnings instead of critical standards violations. The user
+  // can fund mint escrow post-creation by sending coins to the escrow
+  // address, so "no escrow configured" is informational not blocking.
+  return [];
 }
 
 function verifyTradableNFT(value: any): StandardViolation[] {
@@ -648,13 +634,37 @@ function verifyNonTransferable(value: any): StandardViolation[] {
 // Common Mint Approval Checks (run for ALL standards with mint approvals)
 // ============================================================
 
+/**
+ * True when the transaction targets an existing collection — i.e. it's
+ * an update, not a create. Detected by a non-"0" collectionId (chain
+ * convention for new collections). Used to skip structural checks on
+ * CREATE-ONLY fields (defaultBalances, invariants) that the chain
+ * ignores on MsgUpdateCollection and that the session layer already
+ * blocks the AI from modifying on update builds.
+ */
+function isUpdateTransaction(value: any): boolean {
+  const cid = value?.collectionId;
+  if (cid == null) return false;
+  const s = String(cid);
+  return s !== '' && s !== '0';
+}
+
 function verifyCommonMintRules(value: any): StandardViolation[] {
   const violations: StandardViolation[] = [];
   const mintApprovals = getMintApprovals(value);
   const defaultBalances = value.defaultBalances || {};
 
+  // defaultBalances is a CREATION-ONLY field — the chain ignores it on
+  // MsgUpdateCollection and the session layer blocks set_default_balances
+  // on updates. For an update tx the on-chain collection already has its
+  // defaultBalances set; we can't change it from this message anyway.
+  // Checking the tx body here fires on every update that adds or touches
+  // a Mint approval (see ses_1ps5eu91pxxa). Skip the auto-approve
+  // incoming rule for updates; it remains enforced on create.
+  const isUpdate = isUpdateTransaction(value);
+
   // If there are mint approvals, defaultBalances should have autoApproveAllIncomingTransfers
-  if (mintApprovals.length > 0) {
+  if (mintApprovals.length > 0 && !isUpdate) {
     if (
       defaultBalances.autoApproveAllIncomingTransfers !== true &&
       defaultBalances.autoApproveAllIncomingTransfers !== 'true'
@@ -663,7 +673,7 @@ function verifyCommonMintRules(value: any): StandardViolation[] {
         standard: 'Common',
         field: 'defaultBalances.autoApproveAllIncomingTransfers',
         message:
-          'Collections with mint approvals MUST have defaultBalances.autoApproveAllIncomingTransfers: true. Without this, recipients cannot receive minted tokens.',
+          'Collections with token-creation (Mint) approvals MUST have defaultBalances.autoApproveAllIncomingTransfers: true. Without this, recipients cannot receive newly created tokens.',
         fix: 'Set defaultBalances.autoApproveAllIncomingTransfers: true.'
       });
     }
@@ -682,11 +692,24 @@ function verifyCommonMintRules(value: any): StandardViolation[] {
     }
   }
 
-  // Mint approvals with predeterminedBalances must have exactly one orderCalculationMethod
+  // Mint approvals with predeterminedBalances must have exactly one
+  // orderCalculationMethod — but ONLY when the predetermined balances
+  // are actually being used. Per `approvalCriteriaUsesPredeterminedBalances`,
+  // that means either `incrementedBalances.startBalances` OR
+  // `manualBalances` is non-empty. The chain's `validate_basic.go` rule
+  // is "when using predetermined balances, exactly one order calculation
+  // can be set to true". An approval with both arrays empty (e.g.
+  // custom-2fa, which enforces expiration via allowPurgeIfExpired) has
+  // nothing to order, so the chain accepts all flags false.
   for (const approval of mintApprovals) {
     const ac = approval.approvalCriteria || {};
     const pb = ac.predeterminedBalances;
-    if (pb?.orderCalculationMethod) {
+    const incStart = pb?.incrementedBalances?.startBalances;
+    const manual = pb?.manualBalances;
+    const usesPredetermined =
+      (Array.isArray(incStart) && incStart.length > 0) ||
+      (Array.isArray(manual) && manual.length > 0);
+    if (pb?.orderCalculationMethod && usesPredetermined) {
       const ocm = pb.orderCalculationMethod;
       const trueCount = [
         ocm.useOverallNumTransfers,
@@ -700,7 +723,7 @@ function verifyCommonMintRules(value: any): StandardViolation[] {
         violations.push({
           standard: 'Common',
           field: `collectionApprovals[${approval.approvalId}].predeterminedBalances.orderCalculationMethod`,
-          message: `Approval "${approval.approvalId}" uses predeterminedBalances but no orderCalculationMethod is set to true. Exactly one must be true.`,
+          message: `Approval "${approval.approvalId}" uses predeterminedBalances (incrementedBalances.startBalances or manualBalances) but no orderCalculationMethod is set to true. Exactly one must be true.`,
           fix: 'Set useOverallNumTransfers: true (most common default).'
         });
       } else if (trueCount > 1) {
@@ -745,7 +768,7 @@ function verifyBounty(value: any): StandardViolation[] {
     }
     // Each should have maxNumTransfers.overallMaxNumTransfers = 1
     const mnt = ac.maxNumTransfers;
-    if (mnt && String(mnt.overallMaxNumTransfers) !== '1') {
+    if (mnt && mnt.overallMaxNumTransfers !== 1n) {
       violations.push({ standard: std, field: `collectionApprovals[${a.approvalId}].maxNumTransfers`, message: `Bounty approval "${a.approvalId}" overallMaxNumTransfers must be "1".` });
     }
   }
@@ -770,7 +793,7 @@ function verifyCrowdfund(value: any): StandardViolation[] {
 
   // Must have 2 token IDs (refund + progress)
   const tokenIds = value.validTokenIds;
-  if (!Array.isArray(tokenIds) || tokenIds.length !== 1 || String(tokenIds[0]?.start) !== '1' || String(tokenIds[0]?.end) !== '2') {
+  if (!Array.isArray(tokenIds) || tokenIds.length !== 1 || tokenIds[0]?.start !== 1n || tokenIds[0]?.end !== 2n) {
     violations.push({ standard: std, field: 'validTokenIds', message: 'Crowdfund collections MUST have validTokenIds = [{ start: "1", end: "2" }] (refund + progress tokens).' });
   }
 
@@ -805,8 +828,9 @@ function verifyAuction(value: any): StandardViolation[] {
   const approvals = getApprovals(value);
   const mintApprovals = getMintApprovals(value);
 
+  // Post-settlement state is valid: the mint-to-winner approval uses
+  // autoDeletionOptions.afterOneUse, so it's gone once the auction settles.
   if (mintApprovals.length === 0) {
-    violations.push({ standard: std, field: 'collectionApprovals', message: 'Auction requires at least one mint approval (mint-to-winner).' });
     return violations;
   }
 
@@ -817,7 +841,7 @@ function verifyAuction(value: any): StandardViolation[] {
     }
     // Must have maxNumTransfers = 1
     const mnt = ac.maxNumTransfers;
-    if (mnt && String(mnt.overallMaxNumTransfers) !== '1') {
+    if (mnt && mnt.overallMaxNumTransfers !== 1n) {
       violations.push({ standard: std, field: `collectionApprovals[${a.approvalId}].maxNumTransfers`, message: `Auction mint-to-winner overallMaxNumTransfers must be "1".` });
     }
     // Transfer times should be bounded (not FOREVER)
@@ -869,7 +893,7 @@ function verifyPredictionMarket(value: any): StandardViolation[] {
 
   // Must have 2 token IDs (YES/NO)
   const tokenIds = value.validTokenIds;
-  if (!Array.isArray(tokenIds) || tokenIds.length !== 1 || String(tokenIds[0]?.start) !== '1' || String(tokenIds[0]?.end) !== '2') {
+  if (!Array.isArray(tokenIds) || tokenIds.length !== 1 || tokenIds[0]?.start !== 1n || tokenIds[0]?.end !== 2n) {
     violations.push({ standard: std, field: 'validTokenIds', message: 'Prediction market MUST have validTokenIds = [{ start: "1", end: "2" }] (YES + NO tokens).' });
   }
 
@@ -1192,6 +1216,36 @@ function isFakeOrMissingImage(image: string | undefined): boolean {
   return FAKE_IMAGE_PATTERNS.some((p) => p.test(image));
 }
 
+/**
+ * True if a PathMetadata.uri is missing, blank, or matches one of the
+ * known fake/placeholder patterns. Empty `ipfs://METADATA_*` internal
+ * placeholders from the template/session flow count as VALID here — they
+ * intentionally mark "substitute this at deploy time" and are honoured by
+ * the metadata auto-apply layer.
+ */
+function isFakeOrMissingUri(uri: string | undefined): boolean {
+  if (!uri || uri.trim() === '') return true;
+  // Internal placeholders emitted by buildAliasPath / session builders
+  // are valid — they're substituted during the metadata auto-apply flow.
+  if (/^ipfs:\/\/METADATA_[A-Z]/.test(uri)) return false;
+  return FAKE_IMAGE_PATTERNS.some((p) => p.test(uri));
+}
+
+/**
+ * True if a path metadata object is in the frontend "WithDetails" shape
+ * — a nested `metadata.metadata` object with inline name / image /
+ * description. The frontend stores this pre-upload; the metadata
+ * auto-apply flow uploads the inline content to IPFS and populates the
+ * `uri` field on submit. When in this state, the `uri` is intentionally
+ * blank and "missing URI" violations are false positives.
+ */
+function isPreApplyMetadata(m: any): boolean {
+  if (!m || typeof m !== 'object') return false;
+  const inner = m.metadata;
+  if (!inner || typeof inner !== 'object') return false;
+  return Boolean(inner.name || inner.image || inner.description);
+}
+
 function verifyMetadataPlaceholders(value: any): StandardViolation[] {
   const violations: StandardViolation[] = [];
   const std = 'Common';
@@ -1232,7 +1286,11 @@ function verifyMetadataPlaceholders(value: any): StandardViolation[] {
     }
   }
 
-  // Check alias path metadata — ALL alias paths and denomUnits MUST have metadata with an image
+  // Check alias path metadata — PathMetadata only has {uri, customData}. The
+  // image lives inside the off-chain JSON referenced by `uri`. Every alias
+  // path and every denomUnit MUST have a metadata.uri set (ideally a
+  // placeholder like ipfs://METADATA_ALIAS_<denom> that gets substituted
+  // post-build via the metadata auto-apply flow).
   const aliasPaths = value.aliasPathsToAdd || [];
   for (let i = 0; i < aliasPaths.length; i++) {
     const ap = aliasPaths[i];
@@ -1240,18 +1298,26 @@ function verifyMetadataPlaceholders(value: any): StandardViolation[] {
       violations.push({
         standard: std,
         field: `aliasPathsToAdd[${i}].metadata`,
-        message: `Alias path "${ap.denom || i}" is missing metadata entirely. All alias paths MUST have metadata with a uri, customData, and image.`,
-        fix: `Add metadata: { uri: "", customData: "", image: "${BITBADGES_DEFAULT_IMAGE}" }.`
+        message: `Alias path "${ap.denom || i}" is missing PathMetadata entirely. All alias paths MUST have metadata: { uri, customData }.`,
+        fix: `Add metadata: { uri: "ipfs://METADATA_ALIAS_${ap.denom || '<DENOM>'}", customData: "" } and upload the image inside the JSON at that URI via the auto-apply flow.`
       });
-    } else if (isFakeOrMissingImage(ap.metadata?.image)) {
+    } else if (isFakeOrMissingUri(ap.metadata?.uri) && !isPreApplyMetadata(ap.metadata)) {
+      violations.push({
+        standard: std,
+        field: `aliasPathsToAdd[${i}].metadata.uri`,
+        message: `Alias path "${ap.denom || i}" metadata.uri is missing or is a fake placeholder. The image must live inside the off-chain JSON at this URI.`,
+        fix: `Set metadata.uri to a placeholder like "ipfs://METADATA_ALIAS_${ap.denom || '<DENOM>'}" (the metadata auto-apply flow replaces this with a real upload) or to a real uploaded URI directly.`
+      });
+    }
+    if ('image' in (ap.metadata || {})) {
       violations.push({
         standard: std,
         field: `aliasPathsToAdd[${i}].metadata.image`,
-        message: `Alias path metadata has no image or uses a fake placeholder. Use the BitBadges default: "${BITBADGES_DEFAULT_IMAGE}" or the user-provided image.`,
-        fix: `Set metadata.image to "${BITBADGES_DEFAULT_IMAGE}".`
+        message: `aliasPathsToAdd[${i}].metadata.image is not a valid field. PathMetadata only has { uri, customData }. Put the image inside the off-chain JSON referenced by metadata.uri.`,
+        fix: `Remove metadata.image and place the image field inside the JSON blob hosted at metadata.uri.`
       });
     }
-    // Check denomUnit metadata — each denomUnit MUST have metadata with an image
+    // Check denomUnit metadata — each denomUnit MUST have PathMetadata with uri
     if (Array.isArray(ap.denomUnits)) {
       for (let j = 0; j < ap.denomUnits.length; j++) {
         const du = ap.denomUnits[j];
@@ -1259,22 +1325,30 @@ function verifyMetadataPlaceholders(value: any): StandardViolation[] {
           violations.push({
             standard: std,
             field: `aliasPathsToAdd[${i}].denomUnits[${j}].metadata`,
-            message: `Denom unit "${du.symbol || j}" is missing metadata entirely. All denomUnits MUST have metadata with a uri, customData, and image.`,
-            fix: `Add metadata: { uri: "", customData: "", image: "${BITBADGES_DEFAULT_IMAGE}" }.`
+            message: `Denom unit "${du.symbol || j}" is missing PathMetadata entirely. All denomUnits MUST have metadata: { uri, customData }.`,
+            fix: `Add metadata: { uri: "ipfs://METADATA_ALIAS_${ap.denom || '<DENOM>'}_UNIT", customData: "" }.`
           });
-        } else if (isFakeOrMissingImage(du.metadata?.image)) {
+        } else if (isFakeOrMissingUri(du.metadata?.uri) && !isPreApplyMetadata(du.metadata)) {
+          violations.push({
+            standard: std,
+            field: `aliasPathsToAdd[${i}].denomUnits[${j}].metadata.uri`,
+            message: `Denom unit "${du.symbol || j}" metadata.uri is missing or is a fake placeholder.`,
+            fix: `Set metadata.uri to a placeholder like "ipfs://METADATA_ALIAS_${ap.denom || '<DENOM>'}_UNIT" or to a real uploaded URI directly.`
+          });
+        }
+        if ('image' in (du.metadata || {})) {
           violations.push({
             standard: std,
             field: `aliasPathsToAdd[${i}].denomUnits[${j}].metadata.image`,
-            message: `Denom unit "${du.symbol || j}" metadata has no image or uses a fake placeholder.`,
-            fix: `Set metadata.image to "${BITBADGES_DEFAULT_IMAGE}".`
+            message: `denomUnits[${j}].metadata.image is not a valid field. PathMetadata only has { uri, customData }. Put the image inside the off-chain JSON referenced by metadata.uri.`,
+            fix: `Remove metadata.image and place the image field inside the JSON blob hosted at metadata.uri.`
           });
         }
       }
     }
   }
 
-  // Check cosmos coin wrapper path metadata
+  // Check cosmos coin wrapper path metadata — same PathMetadata shape
   const wrapperPaths = value.cosmosCoinWrapperPathsToAdd || [];
   for (let i = 0; i < wrapperPaths.length; i++) {
     const wp = wrapperPaths[i];
@@ -1282,15 +1356,23 @@ function verifyMetadataPlaceholders(value: any): StandardViolation[] {
       violations.push({
         standard: std,
         field: `cosmosCoinWrapperPathsToAdd[${i}].metadata`,
-        message: `Cosmos coin wrapper path is missing metadata entirely. MUST have metadata with image.`,
-        fix: `Add metadata: { uri: "", customData: "", image: "${BITBADGES_DEFAULT_IMAGE}" }.`
+        message: `Cosmos coin wrapper path is missing PathMetadata entirely. MUST have metadata: { uri, customData }.`,
+        fix: `Add metadata: { uri: "ipfs://METADATA_WRAPPER_${wp.denom || '<DENOM>'}", customData: "" }.`
       });
-    } else if (isFakeOrMissingImage(wp.metadata?.image)) {
+    } else if (isFakeOrMissingUri(wp.metadata?.uri)) {
+      violations.push({
+        standard: std,
+        field: `cosmosCoinWrapperPathsToAdd[${i}].metadata.uri`,
+        message: `Cosmos coin wrapper path metadata.uri is missing or is a fake placeholder.`,
+        fix: `Set metadata.uri to a placeholder like "ipfs://METADATA_WRAPPER_${wp.denom || '<DENOM>'}" or a real uploaded URI.`
+      });
+    }
+    if ('image' in (wp.metadata || {})) {
       violations.push({
         standard: std,
         field: `cosmosCoinWrapperPathsToAdd[${i}].metadata.image`,
-        message: `Cosmos coin wrapper path metadata has no image or uses a fake placeholder.`,
-        fix: `Set metadata.image to "${BITBADGES_DEFAULT_IMAGE}".`
+        message: `cosmosCoinWrapperPathsToAdd[${i}].metadata.image is not a valid field. PathMetadata only has { uri, customData }.`,
+        fix: `Remove metadata.image and place the image field inside the JSON blob hosted at metadata.uri.`
       });
     }
   }
@@ -1369,11 +1451,27 @@ function verifyApprovalTrackingFields(value: any): StandardViolation[] {
  * Runs with 0 AI tokens — pure structural validation.
  *
  * @param transaction - The full transaction object (with messages array)
+ * @param onChainCollection - Optional prior on-chain state. Required for
+ *   accurate verification of update transactions — the chain ignores
+ *   `defaultBalances` and `invariants` on MsgUpdateCollection, so those
+ *   fields are absent from the tx body even though the checks below
+ *   depend on them. When supplied, we splice the on-chain values onto
+ *   the verification view so every downstream check runs against the
+ *   full effective collection state.
  * @returns VerificationResult with violations and checked standards
  */
-export function verifyStandardsCompliance(transaction: any): VerificationResult {
-  const msg = transaction?.messages?.[0] || transaction?.msgs?.[0];
-  const value = msg?.value || msg;
+export function verifyStandardsCompliance(
+  transaction: any,
+  onChainCollection?: any
+): VerificationResult {
+  // normalizeForReview unwraps tx/msg wrappers, mirrors aliasPaths field
+  // names, and converts all numeric fields to bigints via the Msg class's
+  // registered .convert(BigIntify). Every downstream check here assumes
+  // that normalized shape. Idempotent — safe to run on already-normalized
+  // input (reviewCollection pipeline) or raw input (direct callers like
+  // the builders test suite).
+  const normalized = normalizeForReview(transaction);
+  let value: any = normalized && typeof normalized === 'object' ? normalized : null;
   if (!value) {
     return {
       valid: false,
@@ -1382,6 +1480,23 @@ export function verifyStandardsCompliance(transaction: any): VerificationResult
     };
   }
 
+  // For update transactions, overlay on-chain create-only fields onto
+  // the verification view. If the caller didn't supply on-chain state,
+  // the per-field checks already short-circuit via isUpdateTransaction()
+  // so they don't fire spurious "missing default" errors — see
+  // verifyCommonMintRules() and ses_1ps5eu91pxxa for the motivating case.
+  if (isUpdateTransaction(value) && onChainCollection && typeof onChainCollection === 'object') {
+    const chainValue =
+      (onChainCollection as any)?.messages?.[0]?.value ||
+      (onChainCollection as any)?.messages?.[0] ||
+      onChainCollection;
+    value = {
+      ...value,
+      defaultBalances: value.defaultBalances ?? chainValue?.defaultBalances,
+      invariants: value.invariants ?? chainValue?.invariants
+    };
+  }
+
   const standards = getStandards(value);
   const violations: StandardViolation[] = [];
   const standardsChecked: string[] = [];
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/fromJson.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/fromJson.ts
new file mode 100644
index 0000000000..ce17870f52
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/fromJson.ts
@@ -0,0 +1,184 @@
+/**
+ * JSON → proto dispatcher for every tokenization Msg type.
+ *
+ * This is the single place that knows how to turn an agent-friendly
+ * `{ typeUrl, value }` (or `{ "@type", value }`) shape into a proto
+ * `Message` instance ready for `createTxBroadcastBody()`. It's used by the
+ * indexer's `/api/v0/simulate` JSON fast path so agents can POST raw
+ * message JSON instead of having to proto-encode + sign client-side just
+ * to dry-run a tx.
+ *
+ * Covers every `tokenization.Msg*` request type (Create/Update/Universal
+ * collection, transfers, per-field setters, user-level approvals, dynamic
+ * stores, vote, address lists, etc.). Unknown typeUrls throw a typed error
+ * so callers can distinguish "we don't support this message type yet"
+ * from a generic encoding failure.
+ */
+
+import type { Message } from '@bufbuild/protobuf';
+
+import { MsgCastVote } from './msgCastVote.js';
+import { MsgCreateAddressLists } from './msgCreateAddressLists.js';
+import { MsgCreateCollection } from './msgCreateCollection.js';
+import { MsgCreateDynamicStore } from './msgCreateDynamicStore.js';
+import { MsgDeleteCollection } from './msgDeleteCollection.js';
+import { MsgDeleteDynamicStore } from './msgDeleteDynamicStore.js';
+import { MsgDeleteIncomingApproval } from './msgDeleteIncomingApproval.js';
+import { MsgDeleteOutgoingApproval } from './msgDeleteOutgoingApproval.js';
+import { MsgPurgeApprovals } from './msgPurgeApprovals.js';
+import { MsgSetCollectionApprovals } from './msgSetCollectionApprovals.js';
+import { MsgSetCollectionMetadata } from './msgSetCollectionMetadata.js';
+import { MsgSetCustomData } from './msgSetCustomData.js';
+import { MsgSetDynamicStoreValue } from './msgSetDynamicStoreValue.js';
+import { MsgSetIncomingApproval } from './msgSetIncomingApproval.js';
+import { MsgSetIsArchived } from './msgSetIsArchived.js';
+import { MsgSetManager } from './msgSetManager.js';
+import { MsgSetOutgoingApproval } from './msgSetOutgoingApproval.js';
+import { MsgSetStandards } from './msgSetStandards.js';
+import { MsgSetTokenMetadata } from './msgSetTokenMetadata.js';
+import { MsgSetValidTokenIds } from './msgSetValidTokenIds.js';
+import { MsgTransferTokens } from './msgTransferTokens.js';
+import { MsgUniversalUpdateCollection } from './msgUniversalUpdateCollection.js';
+import { MsgUpdateCollection } from './msgUpdateCollection.js';
+import { MsgUpdateDynamicStore } from './msgUpdateDynamicStore.js';
+import { MsgUpdateUserApprovals } from './msgUpdateUserApprovals.js';
+
+/**
+ * Error thrown when `encodeTokenizationMsgFromJson` receives a typeUrl it
+ * doesn't know how to build. Callers can catch this specifically to return
+ * a nicer "unsupported message type" response to the agent rather than
+ * crashing on a generic constructor failure.
+ */
+export class UnsupportedMessageTypeError extends Error {
+  readonly typeUrl: string;
+  constructor(typeUrl: string) {
+    super(
+      `No JSON→proto encoder for typeUrl "${typeUrl}". Supported: every /tokenization.Msg* request type. ` +
+        `For other cosmos-sdk modules, proto-encode client-side and POST the tx_bytes instead.`
+    );
+    this.name = 'UnsupportedMessageTypeError';
+    this.typeUrl = typeUrl;
+  }
+}
+
+/**
+ * Error thrown when `encodeTokenizationMsgFromJson` recognized the typeUrl
+ * but the wrapper-class constructor threw on the malformed `value` (missing
+ * required fields, wrong types, etc.). Wraps the underlying TypeError so
+ * agents and HTTP callers see "/tokenization.MsgX: missing field foo"
+ * instead of a raw `Cannot read properties of undefined (reading 'foo')`
+ * stack trace.
+ */
+export class InvalidMessageValueError extends Error {
+  readonly typeUrl: string;
+  readonly cause: unknown;
+  constructor(typeUrl: string, cause: unknown) {
+    const causeMsg = cause instanceof Error ? cause.message : String(cause);
+    super(
+      `Invalid value for ${typeUrl}: ${causeMsg}. Check that all required fields are present and shaped correctly.`
+    );
+    this.name = 'InvalidMessageValueError';
+    this.typeUrl = typeUrl;
+    this.cause = cause;
+  }
+}
+
+type Builder = (value: any) => Message;
+
+// typeUrl → wrapper-class constructor. The wrapper classes normalize
+// string/number/nested-object inputs and expose `.toProto()` that emits a
+// buf-protobuf `Message` suitable for `createTxBroadcastBody()`.
+//
+// Keep this table in sync with the list in `src/transactions/messages/
+// bitbadges/tokenization/index.ts` — there should be one entry per Msg
+// request file (response messages are not signable).
+const BUILDERS: Record<string, Builder> = {
+  '/tokenization.MsgCastVote': (v) => new MsgCastVote(v).toProto(),
+  '/tokenization.MsgCreateAddressLists': (v) => new MsgCreateAddressLists(v).toProto(),
+  '/tokenization.MsgCreateCollection': (v) => new MsgCreateCollection(v).toProto(),
+  '/tokenization.MsgCreateDynamicStore': (v) => new MsgCreateDynamicStore(v).toProto(),
+  '/tokenization.MsgDeleteCollection': (v) => new MsgDeleteCollection(v).toProto(),
+  '/tokenization.MsgDeleteDynamicStore': (v) => new MsgDeleteDynamicStore(v).toProto(),
+  '/tokenization.MsgDeleteIncomingApproval': (v) => new MsgDeleteIncomingApproval(v).toProto(),
+  '/tokenization.MsgDeleteOutgoingApproval': (v) => new MsgDeleteOutgoingApproval(v).toProto(),
+  '/tokenization.MsgPurgeApprovals': (v) => new MsgPurgeApprovals(v).toProto(),
+  '/tokenization.MsgSetCollectionApprovals': (v) => new MsgSetCollectionApprovals(v).toProto(),
+  '/tokenization.MsgSetCollectionMetadata': (v) => new MsgSetCollectionMetadata(v).toProto(),
+  '/tokenization.MsgSetCustomData': (v) => new MsgSetCustomData(v).toProto(),
+  '/tokenization.MsgSetDynamicStoreValue': (v) => new MsgSetDynamicStoreValue(v).toProto(),
+  '/tokenization.MsgSetIncomingApproval': (v) => new MsgSetIncomingApproval(v).toProto(),
+  '/tokenization.MsgSetIsArchived': (v) => new MsgSetIsArchived(v).toProto(),
+  '/tokenization.MsgSetManager': (v) => new MsgSetManager(v).toProto(),
+  '/tokenization.MsgSetOutgoingApproval': (v) => new MsgSetOutgoingApproval(v).toProto(),
+  '/tokenization.MsgSetStandards': (v) => new MsgSetStandards(v).toProto(),
+  '/tokenization.MsgSetTokenMetadata': (v) => new MsgSetTokenMetadata(v).toProto(),
+  '/tokenization.MsgSetValidTokenIds': (v) => new MsgSetValidTokenIds(v).toProto(),
+  '/tokenization.MsgTransferTokens': (v) => new MsgTransferTokens(v).toProto(),
+  '/tokenization.MsgUniversalUpdateCollection': (v) => new MsgUniversalUpdateCollection(v).toProto(),
+  '/tokenization.MsgUpdateCollection': (v) => new MsgUpdateCollection(v).toProto(),
+  '/tokenization.MsgUpdateDynamicStore': (v) => new MsgUpdateDynamicStore(v).toProto(),
+  '/tokenization.MsgUpdateUserApprovals': (v) => new MsgUpdateUserApprovals(v).toProto()
+};
+
+/**
+ * Turn a single JSON-shaped tokenization message into a proto `Message`.
+ *
+ * Accepts both `{ typeUrl, value }` (what the builder pipeline emits) and
+ * `{ '@type', ... }` (what Cosmos-style Amino JSON uses). Also tolerates
+ * the entire value living on the top-level object when `value` is absent.
+ *
+ * @throws {UnsupportedMessageTypeError} if the typeUrl isn't a known
+ *   tokenization request message.
+ * @throws {InvalidMessageValueError} if the typeUrl is known but the
+ *   wrapper-class constructor crashed on the malformed value (missing
+ *   required fields, wrong types). Wraps the underlying TypeError with
+ *   the typeUrl baked into the message so agents see context-rich
+ *   errors instead of "Cannot read properties of undefined".
+ */
+export function encodeTokenizationMsgFromJson(msg: any): Message {
+  if (!msg || typeof msg !== 'object') {
+    throw new Error('encodeTokenizationMsgFromJson: message must be an object');
+  }
+  const typeUrl: string = msg.typeUrl || msg['@type'] || '';
+  if (!typeUrl) {
+    throw new Error('encodeTokenizationMsgFromJson: message missing "typeUrl"');
+  }
+  const builder = BUILDERS[typeUrl];
+  if (!builder) {
+    throw new UnsupportedMessageTypeError(typeUrl);
+  }
+  const value = msg.value !== undefined ? msg.value : msg;
+  // Reject obviously-wrong value shapes up front so the wrapper class
+  // doesn't get a chance to throw a confusing field-access error.
+  if (value === null) {
+    throw new InvalidMessageValueError(typeUrl, new Error('value cannot be null'));
+  }
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new InvalidMessageValueError(
+      typeUrl,
+      new Error(`value must be an object, got ${Array.isArray(value) ? 'array' : typeof value}`)
+    );
+  }
+  try {
+    return builder(value);
+  } catch (cause) {
+    // Wrapper-class constructors crash on missing required fields with
+    // raw TypeErrors like "Cannot read properties of undefined (reading
+    // 'creator')". Wrap with typed error so agents see a clean
+    // "/tokenization.MsgX: <reason>" message.
+    if (cause instanceof UnsupportedMessageTypeError || cause instanceof InvalidMessageValueError) {
+      throw cause;
+    }
+    throw new InvalidMessageValueError(typeUrl, cause);
+  }
+}
+
+/** Convenience wrapper — map an array of JSON messages to proto in one call. */
+export function encodeTokenizationMsgsFromJson(msgs: any[]): Message[] {
+  return msgs.map((m) => encodeTokenizationMsgFromJson(m));
+}
+
+/** List of supported typeUrls. Useful for error messages and tooling. */
+export function supportedTokenizationTypeUrls(): string[] {
+  return Object.keys(BUILDERS);
+}
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgPurgeApprovals.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgPurgeApprovals.ts
index 4c1ce27544..8a0fde8138 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgPurgeApprovals.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgPurgeApprovals.ts
@@ -29,7 +29,7 @@ export class MsgPurgeApprovals<T extends NumberType> extends CustomTypeClass<Msg
     this.purgeExpired = msg.purgeExpired;
     this.approverAddress = msg.approverAddress;
     this.purgeCounterpartyApprovals = msg.purgeCounterpartyApprovals;
-    this.approvalsToPurge = msg.approvalsToPurge.map((approval) => new ApprovalIdentifierDetails(approval));
+    this.approvalsToPurge = msg.approvalsToPurge?.map((approval) => new ApprovalIdentifierDetails(approval)) ?? [];
   }
 
   toProto(): prototokenization.MsgPurgeApprovals {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionApprovals.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionApprovals.ts
index 31fd997fe8..203a100053 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionApprovals.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionApprovals.ts
@@ -30,7 +30,7 @@ export class MsgSetCollectionApprovals<T extends NumberType>
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
     this.collectionApprovals = msg.collectionApprovals.map((approval) => new CollectionApproval(approval));
-    this.canUpdateCollectionApprovals = msg.canUpdateCollectionApprovals.map((permission) => new CollectionApprovalPermission(permission));
+    this.canUpdateCollectionApprovals = msg.canUpdateCollectionApprovals?.map((permission) => new CollectionApprovalPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetCollectionApprovals {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionMetadata.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionMetadata.ts
index 17d2adc387..102c5311f8 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionMetadata.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCollectionMetadata.ts
@@ -31,7 +31,7 @@ export class MsgSetCollectionMetadata<T extends NumberType>
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
     this.collectionMetadata = msg.collectionMetadata;
-    this.canUpdateCollectionMetadata = msg.canUpdateCollectionMetadata.map((permission) => new ActionPermission(permission));
+    this.canUpdateCollectionMetadata = msg.canUpdateCollectionMetadata?.map((permission) => new ActionPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetCollectionMetadata {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCustomData.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCustomData.ts
index e415a9ee53..fb880e93e1 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCustomData.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetCustomData.ts
@@ -26,7 +26,7 @@ export class MsgSetCustomData<T extends NumberType> extends CustomTypeClass<MsgS
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
     this.customData = msg.customData;
-    this.canUpdateCustomData = msg.canUpdateCustomData.map((permission) => new ActionPermission(permission));
+    this.canUpdateCustomData = msg.canUpdateCustomData?.map((permission) => new ActionPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetCustomData {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetIsArchived.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetIsArchived.ts
index edfd6eeef1..8bf82272e3 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetIsArchived.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetIsArchived.ts
@@ -26,7 +26,7 @@ export class MsgSetIsArchived<T extends NumberType> extends CustomTypeClass<MsgS
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
     this.isArchived = msg.isArchived;
-    this.canArchiveCollection = msg.canArchiveCollection.map((permission) => new ActionPermission(permission));
+    this.canArchiveCollection = msg.canArchiveCollection?.map((permission) => new ActionPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetIsArchived {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetManager.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetManager.ts
index 4915f1ce7e..d556909cca 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetManager.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetManager.ts
@@ -26,7 +26,7 @@ export class MsgSetManager<T extends NumberType> extends CustomTypeClass<MsgSetM
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
     this.manager = msg.manager;
-    this.canUpdateManager = msg.canUpdateManager.map((permission) => new ActionPermission(permission));
+    this.canUpdateManager = msg.canUpdateManager?.map((permission) => new ActionPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetManager {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetStandards.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetStandards.ts
index bf874738c5..0814314f29 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetStandards.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetStandards.ts
@@ -26,7 +26,7 @@ export class MsgSetStandards<T extends NumberType> extends CustomTypeClass<MsgSe
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
     this.standards = msg.standards;
-    this.canUpdateStandards = msg.canUpdateStandards.map((permission) => new ActionPermission(permission));
+    this.canUpdateStandards = msg.canUpdateStandards?.map((permission) => new ActionPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetStandards {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetTokenMetadata.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetTokenMetadata.ts
index 6e930e181a..56396d9133 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetTokenMetadata.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetTokenMetadata.ts
@@ -27,7 +27,7 @@ export class MsgSetTokenMetadata<T extends NumberType> extends CustomTypeClass<M
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
     this.tokenMetadata = msg.tokenMetadata.map((tm) => new TokenMetadata(tm));
-    this.canUpdateTokenMetadata = msg.canUpdateTokenMetadata.map((permission) => new TokenIdsActionPermission(permission));
+    this.canUpdateTokenMetadata = msg.canUpdateTokenMetadata?.map((permission) => new TokenIdsActionPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetTokenMetadata {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetValidTokenIds.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetValidTokenIds.ts
index 268950775d..52b3d25f68 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetValidTokenIds.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/bitbadges/tokenization/msgSetValidTokenIds.ts
@@ -26,8 +26,8 @@ export class MsgSetValidTokenIds<T extends NumberType> extends CustomTypeClass<M
     super();
     this.creator = msg.creator;
     this.collectionId = msg.collectionId;
-    this.validTokenIds = msg.validTokenIds.map((range) => new UintRange(range));
-    this.canUpdateValidTokenIds = msg.canUpdateValidTokenIds.map((permission) => new TokenIdsActionPermission(permission));
+    this.validTokenIds = msg.validTokenIds?.map((range) => new UintRange(range)) ?? [];
+    this.canUpdateValidTokenIds = msg.canUpdateValidTokenIds?.map((permission) => new TokenIdsActionPermission(permission)) ?? [];
   }
 
   toProto(): prototokenization.MsgSetValidTokenIds {
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/fromJson.spec.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/fromJson.spec.ts
new file mode 100644
index 0000000000..c534b29ad7
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/fromJson.spec.ts
@@ -0,0 +1,277 @@
+/**
+ * Tests for the top-level JSON → proto dispatcher used by the indexer's
+ * simulate endpoint JSON fast path. We verify:
+ *   - Every tokenization typeUrl round-trips into a proto Message with
+ *     non-empty `toBinary()` output (sanity — the wrapper class accepted
+ *     the JSON and serialized something non-trivial).
+ *   - Cosmos baseline tier (bank/staking/distribution/ibc/authz) dispatches.
+ *   - Unsupported typeUrls throw `UnsupportedMessageTypeError` with the
+ *     typeUrl exposed on the error.
+ *   - `{ typeUrl, value }` and `{ "@type", ...fields }` shapes both work.
+ *   - `encodeMsgsFromJson` batch helper walks arrays.
+ */
+
+import {
+  encodeMsgFromJson,
+  encodeMsgsFromJson,
+  supportedJsonTypeUrls,
+  UnsupportedMessageTypeError,
+  InvalidMessageValueError
+} from './fromJson.js';
+import {
+  encodeTokenizationMsgFromJson,
+  supportedTokenizationTypeUrls
+} from './bitbadges/tokenization/fromJson.js';
+
+// Minimal valid-enough values per tokenization msg type. These don't need
+// to be chain-valid — they just need to satisfy the wrapper-class
+// constructors so `.toProto()` succeeds.
+const TOKENIZATION_FIXTURES: Record<string, any> = {
+  '/tokenization.MsgCreateCollection': { creator: 'bb1abc' },
+  '/tokenization.MsgUpdateCollection': { creator: 'bb1abc', collectionId: '42' },
+  '/tokenization.MsgUniversalUpdateCollection': { creator: 'bb1abc', collectionId: '0' },
+  '/tokenization.MsgDeleteCollection': { creator: 'bb1abc', collectionId: '42' },
+  '/tokenization.MsgTransferTokens': { creator: 'bb1abc', collectionId: '42', transfers: [] },
+  '/tokenization.MsgCreateAddressLists': { creator: 'bb1abc', addressLists: [] },
+  '/tokenization.MsgUpdateUserApprovals': { creator: 'bb1abc', collectionId: '42' },
+  '/tokenization.MsgSetIncomingApproval': {
+    creator: 'bb1abc',
+    collectionId: '42',
+    approval: {
+      approvalId: 'test',
+      fromListId: 'All',
+      initiatedByListId: 'All',
+      transferTimes: [{ start: '1', end: '18446744073709551615' }],
+      tokenIds: [{ start: '1', end: '1' }],
+      ownershipTimes: [{ start: '1', end: '18446744073709551615' }]
+    }
+  },
+  '/tokenization.MsgDeleteIncomingApproval': { creator: 'bb1abc', collectionId: '42', approvalId: 'test' },
+  '/tokenization.MsgSetOutgoingApproval': {
+    creator: 'bb1abc',
+    collectionId: '42',
+    approval: {
+      approvalId: 'test',
+      toListId: 'All',
+      initiatedByListId: 'All',
+      transferTimes: [{ start: '1', end: '18446744073709551615' }],
+      tokenIds: [{ start: '1', end: '1' }],
+      ownershipTimes: [{ start: '1', end: '18446744073709551615' }]
+    }
+  },
+  '/tokenization.MsgDeleteOutgoingApproval': { creator: 'bb1abc', collectionId: '42', approvalId: 'test' },
+  '/tokenization.MsgPurgeApprovals': { creator: 'bb1abc', collectionId: '42', purgeExpired: true },
+  '/tokenization.MsgCreateDynamicStore': { creator: 'bb1abc' },
+  '/tokenization.MsgUpdateDynamicStore': { creator: 'bb1abc', storeId: '1' },
+  '/tokenization.MsgDeleteDynamicStore': { creator: 'bb1abc', storeId: '1' },
+  '/tokenization.MsgSetDynamicStoreValue': { creator: 'bb1abc', storeId: '1', address: 'bb1abc', value: true },
+  '/tokenization.MsgSetValidTokenIds': { creator: 'bb1abc', collectionId: '42' },
+  '/tokenization.MsgSetManager': { creator: 'bb1abc', collectionId: '42', manager: 'bb1new' },
+  '/tokenization.MsgSetCollectionMetadata': {
+    creator: 'bb1abc',
+    collectionId: '42',
+    collectionMetadata: { uri: 'ipfs://test', customData: '' }
+  },
+  '/tokenization.MsgSetTokenMetadata': { creator: 'bb1abc', collectionId: '42', tokenMetadata: [] },
+  '/tokenization.MsgSetCustomData': { creator: 'bb1abc', collectionId: '42', customData: 'hello' },
+  '/tokenization.MsgSetStandards': { creator: 'bb1abc', collectionId: '42', standards: [] },
+  '/tokenization.MsgSetCollectionApprovals': { creator: 'bb1abc', collectionId: '42', collectionApprovals: [] },
+  '/tokenization.MsgSetIsArchived': { creator: 'bb1abc', collectionId: '42', isArchived: false },
+  '/tokenization.MsgCastVote': {
+    creator: 'bb1abc',
+    collectionId: '42',
+    approvalLevel: 'collection',
+    approverAddress: '',
+    approvalId: 'test',
+    proposalId: 'prop1',
+    yesWeight: '1'
+  }
+};
+
+describe('encodeTokenizationMsgFromJson — tokenization tier', () => {
+  it('covers every typeUrl exported from supportedTokenizationTypeUrls()', () => {
+    const exported = supportedTokenizationTypeUrls().sort();
+    const fixtured = Object.keys(TOKENIZATION_FIXTURES).sort();
+    expect(fixtured).toEqual(exported);
+  });
+
+  it.each(Object.entries(TOKENIZATION_FIXTURES))(
+    'round-trips %s to a non-empty proto binary',
+    (typeUrl, value) => {
+      const proto = encodeTokenizationMsgFromJson({ typeUrl, value });
+      const bin = proto.toBinary();
+      expect(bin).toBeInstanceOf(Uint8Array);
+      // Every encoded Msg with a creator field is at least a few bytes.
+      expect(bin.length).toBeGreaterThan(0);
+    }
+  );
+
+  it('throws UnsupportedMessageTypeError for unknown tokenization typeUrls', () => {
+    expect(() =>
+      encodeTokenizationMsgFromJson({ typeUrl: '/tokenization.MsgTotallyFake', value: {} })
+    ).toThrow(UnsupportedMessageTypeError);
+  });
+
+  it('surfaces the offending typeUrl on the error', () => {
+    try {
+      encodeTokenizationMsgFromJson({ typeUrl: '/tokenization.MsgFake', value: {} });
+      fail('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(UnsupportedMessageTypeError);
+      expect((err as UnsupportedMessageTypeError).typeUrl).toBe('/tokenization.MsgFake');
+    }
+  });
+});
+
+describe('InvalidMessageValueError — wrap wrapper-class crashes', () => {
+  it('wraps null value with typed error including the typeUrl', () => {
+    expect(() =>
+      encodeMsgFromJson({ typeUrl: '/tokenization.MsgCreateCollection', value: null })
+    ).toThrow(InvalidMessageValueError);
+    try {
+      encodeMsgFromJson({ typeUrl: '/tokenization.MsgCreateCollection', value: null });
+    } catch (err) {
+      expect((err as InvalidMessageValueError).typeUrl).toBe('/tokenization.MsgCreateCollection');
+      expect((err as Error).message).toContain('value cannot be null');
+    }
+  });
+
+  it('rejects non-object value (array, string, number)', () => {
+    for (const bad of [[], 'hello', 42] as any[]) {
+      expect(() =>
+        encodeMsgFromJson({ typeUrl: '/tokenization.MsgCreateCollection', value: bad })
+      ).toThrow(InvalidMessageValueError);
+    }
+  });
+
+  it('wraps wrapper-class field-access crashes with typeUrl context', () => {
+    // MsgTransferTokens with empty value used to crash with raw
+    // "Cannot read properties of undefined (reading 'map')".
+    // Now wrapped as InvalidMessageValueError with the typeUrl baked in.
+    try {
+      encodeMsgFromJson({ typeUrl: '/tokenization.MsgTransferTokens', value: {} });
+      fail('expected throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(InvalidMessageValueError);
+      expect((err as InvalidMessageValueError).typeUrl).toBe('/tokenization.MsgTransferTokens');
+      expect((err as Error).message).toContain('/tokenization.MsgTransferTokens');
+    }
+  });
+});
+
+describe('encodeMsgFromJson — top-level dispatcher', () => {
+  it('routes /tokenization.* through the tokenization tier', () => {
+    const proto = encodeMsgFromJson({
+      typeUrl: '/tokenization.MsgCreateCollection',
+      value: { creator: 'bb1abc' }
+    });
+    expect(proto).toBeDefined();
+    expect(proto.toBinary().length).toBeGreaterThan(0);
+  });
+
+  it('routes /cosmos.bank.v1beta1.MsgSend through the cosmos tier', () => {
+    const proto = encodeMsgFromJson({
+      typeUrl: '/cosmos.bank.v1beta1.MsgSend',
+      value: {
+        fromAddress: 'bb1abc',
+        toAddress: 'bb1def',
+        amount: [{ denom: 'ubadge', amount: '1000' }]
+      }
+    });
+    expect(proto.toBinary().length).toBeGreaterThan(0);
+  });
+
+  it('handles staking MsgDelegate with BigInt amounts (coerced to string)', () => {
+    const proto = encodeMsgFromJson({
+      typeUrl: '/cosmos.staking.v1beta1.MsgDelegate',
+      value: {
+        delegatorAddress: 'bb1abc',
+        validatorAddress: 'bbvaloper1xyz',
+        amount: { amount: 1000000, denom: 'ubadge' }
+      }
+    });
+    expect(proto.toBinary().length).toBeGreaterThan(0);
+  });
+
+  it('handles IBC MsgTransfer', () => {
+    const proto = encodeMsgFromJson({
+      typeUrl: '/ibc.applications.transfer.v1.MsgTransfer',
+      value: {
+        sourcePort: 'transfer',
+        sourceChannel: 'channel-0',
+        token: { amount: '1000', denom: 'ubadge' },
+        sender: 'bb1abc',
+        receiver: 'cosmos1def',
+        timeoutTimestamp: '9999999999999'
+      }
+    });
+    expect(proto.toBinary().length).toBeGreaterThan(0);
+  });
+
+  it('accepts { "@type", ...fields } Amino-style shape', () => {
+    const proto = encodeMsgFromJson({
+      '@type': '/tokenization.MsgCreateCollection',
+      creator: 'bb1abc'
+    });
+    expect(proto.toBinary().length).toBeGreaterThan(0);
+  });
+
+  it('throws UnsupportedMessageTypeError for cosmos modules we do not yet cover', () => {
+    expect(() =>
+      encodeMsgFromJson({ typeUrl: '/cosmos.gov.v1.MsgSubmitProposal', value: {} })
+    ).toThrow(UnsupportedMessageTypeError);
+  });
+
+  it('throws for missing typeUrl', () => {
+    expect(() => encodeMsgFromJson({ value: { creator: 'bb1abc' } })).toThrow(/missing "typeUrl"/);
+  });
+
+  it('throws for non-object input', () => {
+    expect(() => encodeMsgFromJson(null as any)).toThrow(/must be an object/);
+    expect(() => encodeMsgFromJson('string' as any)).toThrow(/must be an object/);
+  });
+});
+
+describe('encodeMsgsFromJson — batch', () => {
+  it('walks an array and returns one Message per input', () => {
+    const msgs = [
+      { typeUrl: '/tokenization.MsgCreateCollection', value: { creator: 'bb1abc' } },
+      {
+        typeUrl: '/tokenization.MsgTransferTokens',
+        value: { creator: 'bb1abc', collectionId: '42', transfers: [] }
+      }
+    ];
+    const protos = encodeMsgsFromJson(msgs);
+    expect(protos).toHaveLength(2);
+    expect(protos.every((p) => p.toBinary().length > 0)).toBe(true);
+  });
+
+  it('propagates UnsupportedMessageTypeError from any element', () => {
+    const msgs = [
+      { typeUrl: '/tokenization.MsgCreateCollection', value: { creator: 'bb1abc' } },
+      { typeUrl: '/cosmos.gov.v1.MsgSubmitProposal', value: {} }
+    ];
+    expect(() => encodeMsgsFromJson(msgs)).toThrow(UnsupportedMessageTypeError);
+  });
+});
+
+describe('supportedJsonTypeUrls', () => {
+  it('includes the full tokenization tier plus the cosmos baseline', () => {
+    const all = supportedJsonTypeUrls();
+    // Tokenization tier present in full
+    for (const t of supportedTokenizationTypeUrls()) {
+      expect(all).toContain(t);
+    }
+    // A few cosmos baseline entries
+    expect(all).toContain('/cosmos.bank.v1beta1.MsgSend');
+    expect(all).toContain('/cosmos.staking.v1beta1.MsgDelegate');
+    expect(all).toContain('/cosmos.authz.v1beta1.MsgExec');
+    expect(all).toContain('/ibc.applications.transfer.v1.MsgTransfer');
+  });
+
+  it('the count reflects the advertised surface (25 tokenization + 8 cosmos baseline)', () => {
+    expect(supportedTokenizationTypeUrls().length).toBe(25);
+    // Cosmos tier: bank(1) + staking(3) + distribution(1) + authz(3) + ibc(1) = 9
+    expect(supportedJsonTypeUrls().length).toBe(25 + 9);
+  });
+});
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/fromJson.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/fromJson.ts
new file mode 100644
index 0000000000..0521c34892
--- /dev/null
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/fromJson.ts
@@ -0,0 +1,172 @@
+/**
+ * Top-level JSON → proto dispatcher.
+ *
+ * Agents (and anything else that wants to simulate a tx without writing
+ * SDK code) POST `{ typeUrl, value }` JSON. This dispatcher turns each
+ * message into a proto `Message` that `createTxBroadcastBody()` can then
+ * wrap into the `tx_bytes` the Cosmos LCD simulate endpoint expects.
+ *
+ * Tiers:
+ *
+ *   1. **Tokenization** — every `tokenization.Msg*` request type. Lives in
+ *      its own self-contained dispatcher at
+ *      `bitbadges/tokenization/fromJson.ts` so the most common agent flow
+ *      (build → simulate) has the tightest coverage. This file delegates
+ *      to it for any typeUrl with a `.Msg*Collection` / `.Msg*Approval` /
+ *      etc. shape.
+ *
+ *   2. **Cosmos baseline** — the day-to-day Cosmos SDK messages the
+ *      frontend TxModal already knows how to build: bank send, staking
+ *      (delegate/undelegate/redelegate), distribution (withdraw reward),
+ *      IBC transfer, authz (grant/revoke/exec). Hand-registered below.
+ *
+ *   3. **Everything else** — gamm, cosmos.group, wasmx, cosmwasm, maps,
+ *      anchor, managersplitter. Not registered yet; unsupported typeUrls
+ *      raise `UnsupportedMessageTypeError` so callers can either fall
+ *      back to client-side proto-encoding + tx_bytes upload or open an
+ *      issue to add coverage.
+ *
+ * The dispatcher is intentionally read-only — no state, no side effects,
+ * no network. Call it from anywhere (indexer, CLI, tests) and it gives
+ * you a `Message` instance.
+ */
+
+import type { Message } from '@bufbuild/protobuf';
+
+import * as bank from '@/proto/cosmos/bank/v1beta1/index.js';
+import * as staking from '@/proto/cosmos/staking/v1beta1/index.js';
+import * as distribution from '@/proto/cosmos/distribution/v1beta1/index.js';
+import * as authz from '@/proto/cosmos/authz/v1beta1/index.js';
+import * as ibc from '@/proto/ibc/index.js';
+
+import {
+  encodeTokenizationMsgFromJson,
+  supportedTokenizationTypeUrls,
+  UnsupportedMessageTypeError
+} from './bitbadges/tokenization/fromJson.js';
+
+export { UnsupportedMessageTypeError, InvalidMessageValueError } from './bitbadges/tokenization/fromJson.js';
+
+type Builder = (value: any) => Message;
+
+// ---------------------------------------------------------------------------
+// Cosmos baseline — registered below tokenization so a typeUrl that somehow
+// collides would prefer the tokenization path (there is no actual overlap;
+// tokenization lives under `/tokenization.*` and cosmos lives under
+// `/cosmos.*` / `/ibc.*`).
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize each Cosmos `Coin.amount` field to a string. The proto class
+ * expects string amounts; agents often pass numbers/BigInts. We walk the
+ * coin arrays up front so the builder entries below don't each have to
+ * repeat the same normalization.
+ */
+const coinStr = (c: any) => ({ amount: String(c.amount), denom: c.denom });
+const coinsStr = (arr: any[]) => (Array.isArray(arr) ? arr.map(coinStr) : arr);
+
+const COSMOS_BUILDERS: Record<string, Builder> = {
+  // ── cosmos.bank ────────────────────────────────────────────────────────
+  '/cosmos.bank.v1beta1.MsgSend': (v) =>
+    new bank.MsgSend({
+      fromAddress: v.fromAddress,
+      toAddress: v.toAddress,
+      amount: coinsStr(v.amount)
+    }),
+
+  // ── cosmos.staking ─────────────────────────────────────────────────────
+  '/cosmos.staking.v1beta1.MsgDelegate': (v) =>
+    new staking.MsgDelegate({
+      delegatorAddress: v.delegatorAddress,
+      validatorAddress: v.validatorAddress,
+      amount: coinStr(v.amount)
+    }),
+  '/cosmos.staking.v1beta1.MsgUndelegate': (v) =>
+    new staking.MsgUndelegate({
+      delegatorAddress: v.delegatorAddress,
+      validatorAddress: v.validatorAddress,
+      amount: coinStr(v.amount)
+    }),
+  '/cosmos.staking.v1beta1.MsgBeginRedelegate': (v) =>
+    new staking.MsgBeginRedelegate({
+      delegatorAddress: v.delegatorAddress,
+      validatorSrcAddress: v.validatorSrcAddress,
+      validatorDstAddress: v.validatorDstAddress,
+      amount: coinStr(v.amount)
+    }),
+
+  // ── cosmos.distribution ────────────────────────────────────────────────
+  '/cosmos.distribution.v1beta1.MsgWithdrawDelegatorReward': (v) =>
+    new distribution.MsgWithdrawDelegatorReward({
+      delegatorAddress: v.delegatorAddress,
+      validatorAddress: v.validatorAddress
+    }),
+
+  // ── cosmos.authz ───────────────────────────────────────────────────────
+  // MsgGrant/MsgExec wrap inner messages as binary payloads. We pass them
+  // through as-is; callers that want to nest additional messages inside
+  // must pre-encode them. The frontend's TxModal does the same — it walks
+  // ProtoTypeRegistry and binarizes — but that path belongs on the client.
+  '/cosmos.authz.v1beta1.MsgGrant': (v) => new authz.MsgGrant(v),
+  '/cosmos.authz.v1beta1.MsgRevoke': (v) => new authz.MsgRevoke(v),
+  '/cosmos.authz.v1beta1.MsgExec': (v) => new authz.MsgExec(v),
+
+  // ── ibc ────────────────────────────────────────────────────────────────
+  '/ibc.applications.transfer.v1.MsgTransfer': (v) =>
+    new ibc.MsgTransfer({
+      sourcePort: v.sourcePort,
+      sourceChannel: v.sourceChannel,
+      token: v.token ? coinStr(v.token) : undefined,
+      sender: v.sender,
+      receiver: v.receiver,
+      timeoutHeight: v.timeoutHeight,
+      timeoutTimestamp: v.timeoutTimestamp != null ? BigInt(v.timeoutTimestamp) : undefined,
+      memo: v.memo
+    })
+};
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+/**
+ * Turn a single JSON-shaped message into a proto `Message`. Accepts both
+ * `{ typeUrl, value }` and `{ "@type", ... }`; values can live either on
+ * `.value` or directly on the top-level object.
+ *
+ * @throws {UnsupportedMessageTypeError} if the typeUrl isn't in either
+ *   the tokenization tier or the Cosmos baseline tier.
+ */
+export function encodeMsgFromJson(msg: any): Message {
+  if (!msg || typeof msg !== 'object') {
+    throw new Error('encodeMsgFromJson: message must be an object');
+  }
+  const typeUrl: string = msg.typeUrl || msg['@type'] || '';
+  if (!typeUrl) {
+    throw new Error('encodeMsgFromJson: message missing "typeUrl"');
+  }
+
+  // Tokenization tier — the 95% path for BitBadges agents.
+  if (typeUrl.startsWith('/tokenization.')) {
+    return encodeTokenizationMsgFromJson(msg);
+  }
+
+  // Cosmos baseline tier.
+  const builder = COSMOS_BUILDERS[typeUrl];
+  if (builder) {
+    const value = msg.value !== undefined ? msg.value : msg;
+    return builder(value);
+  }
+
+  throw new UnsupportedMessageTypeError(typeUrl);
+}
+
+/** Convenience wrapper — proto-encode an entire `messages[]` array. */
+export function encodeMsgsFromJson(msgs: any[]): Message[] {
+  return msgs.map((m) => encodeMsgFromJson(m));
+}
+
+/** All supported typeUrls across both tiers. Useful for error reporting. */
+export function supportedJsonTypeUrls(): string[] {
+  return [...supportedTokenizationTypeUrls(), ...Object.keys(COSMOS_BUILDERS)];
+}
diff --git a/packages/bitbadgesjs-sdk/src/transactions/messages/index.ts b/packages/bitbadgesjs-sdk/src/transactions/messages/index.ts
index 4512961c02..750994488c 100644
--- a/packages/bitbadgesjs-sdk/src/transactions/messages/index.ts
+++ b/packages/bitbadgesjs-sdk/src/transactions/messages/index.ts
@@ -1,3 +1,9 @@
 export * from './base.js';
 export * from './bitbadges/index.js';
 export * from './common.js';
+export * from './fromJson.js';
+export {
+  encodeTokenizationMsgFromJson,
+  encodeTokenizationMsgsFromJson,
+  supportedTokenizationTypeUrls
+} from './bitbadges/tokenization/fromJson.js';