Improve B2C merchant block documentation

_dropin-enrichments/merchant-blocks/REQUIREMENTS-README.md

@@ -0,0 +1,91 @@
+# Merchant Block Requirements - Documentation
+
+## Overview
+
+The Requirements section provides merchants with immediate actionable information about what customers can do with each block and what needs to be configured.
+
+## Format
+
+**Customer-capability first:**
+```
+[Customer capability]. Enable [feature] in your Adobe Commerce admin panel before using this block.
+```
+
+### Example:
+```
+Company administrators add team members, assign roles, and manage user access through this block. Enable company features in your Adobe Commerce admin panel before using this block.
+```
+
+## Priority System
+
+The generator uses a 2-tier priority system:
+
+1. **Priority 1**: Enriched requirements from `requirements.json` (ALWAYS used if present)
+2. **Priority 2**: Auto-extracted from README files (fallback only)
+
+## File: `requirements.json`
+
+### Structure:
+```json
+{
+  "metadata": {
+    "description": "Merchant-focused requirements for B2B commerce blocks",
+    "format": "[Customer capability]. Enable [feature] in your Adobe Commerce admin panel before using this block.",
+    "last_updated": "2025-12-07",
+    "verified": true
+  },
+  "requirements": {
+    "block-name": "Requirement text following the format above..."
+  }
+}
+```
+
+### Maintenance:
+
+When updating requirements:
+1. Edit `requirements.json` with the new requirement text
+2. Follow the customer-capability-first format
+3. Update the `last_updated` date in metadata
+4. Regenerate merchant documentation
+
+Requirements in `requirements.json` will **never be overwritten** by README extraction.
+
+## Writing Guidelines
+
+### ✅ DO:
+- Lead with what customers can do
+- Use active voice
+- Be specific about capabilities
+- Keep the admin reference simple ("Enable X in your Adobe Commerce admin panel")
+- Focus on merchant value
+
+### ❌ DON'T:
+- Use passive voice ("This block requires...")
+- List technical prerequisites without context
+- Provide complex admin paths
+- Focus on technical details
+
+## Example Transformations
+
+### Before (Technical, Generic):
+> Users must authenticate and have purchase order permissions to view purchase order history.
+
+### After (Customer-Capability First):
+> Users view audit trails showing who approved orders, when actions occurred, and status changes for compliance through this block. Enable purchase orders in your Adobe Commerce admin panel before using this block.
+
+---
+
+## Generator Integration
+
+**File:** `scripts/@generate-merchant-block-docs.js`
+
+**Function:** `generateRequirementsSection()` (lines 828-870)
+
+The function:
+1. Checks `requirements.json` first
+2. If enriched requirement exists, uses it
+3. Otherwise falls back to README extraction
+4. Formats output for MDX
+
+**This ensures requirements are never overwritten during regeneration.**
+

_dropin-enrichments/merchant-blocks/requirements.json

@@ -0,0 +1 @@
+fatal: path '_dropin-enrichments/merchant-blocks/requirements.json' exists on disk, but not in 'b2b-documentation'

astro.config.mjs

@@ -905,17 +905,25 @@ async function config() {
                       },
                     ],
                   },
+                  {
+                    label: 'Setup guides',
+                    collapsed: true,
+                    items: [
+                      { label: 'Personalization', link: '/merchants/commerce-blocks/personalization/' },
+                      { label: 'Product Recommendations', link: '/merchants/commerce-blocks/product-recommendations/' },
+                    ],
+                  },
                   {
                     label: 'Commerce blocks',
                     items: [
                       { label: 'Overview', link: '/merchants/commerce-blocks/' },
-                      { label: 'Personalization', link: '/merchants/commerce-blocks/personalization/' },
-                      { label: 'Product recommendations', link: '/merchants/commerce-blocks/product-recommendations/' },
                       { label: 'Account Header', link: '/merchants/blocks/commerce-account-header/' },
+                      { label: 'Account Navigation', link: '/merchants/blocks/commerce-account-nav/' },
                       { label: 'Account Sidebar', link: '/merchants/blocks/commerce-account-sidebar/' },
                       { label: 'Addresses', link: '/merchants/blocks/commerce-addresses/' },
                       { label: 'Cart', link: '/merchants/blocks/commerce-cart/' },
                       { label: 'Checkout', link: '/merchants/blocks/commerce-checkout/' },
+                      { label: 'Checkout Success', link: '/merchants/blocks/commerce-checkout-success/' },
                       { label: 'Confirm Account', link: '/merchants/blocks/commerce-confirm-account/' },
                       { label: 'Create Account', link: '/merchants/blocks/commerce-create-account/' },
                       { label: 'Create Password', link: '/merchants/blocks/commerce-create-password/' },
@@ -936,6 +944,7 @@ async function config() {
                       { label: 'Returns List', link: '/merchants/blocks/commerce-returns-list/' },
                       { label: 'Search Order', link: '/merchants/blocks/commerce-search-order/' },
                       { label: 'Shipping Status', link: '/merchants/blocks/commerce-shipping-status/' },
+                      { label: 'Personalization', link: '/merchants/blocks/targeted-block/' },
                       { label: 'Wishlist', link: '/merchants/blocks/commerce-wishlist/' },
                       { label: 'Product Details', link: '/merchants/blocks/product-details/' },
                       { label: 'Product List Page', link: '/merchants/blocks/product-list-page/' },