@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-11-cli-tools.md

@@ -1,423 +1,423 @@
-# Module 11: CLI Tools
-
-**Level:** Advanced
-**Category:** Command Line
-
-## Overview
-
-The SDK includes powerful CLI tools for schema introspection, mapping generation, validation, and coverage analysis to streamline development workflows.
-
-## Table of Contents
-
-- [Main CLI](#main-cli)
-- [generate-mutation-mapping](#generate-mutation-mapping)
-- [generate-query-mapping](#generate-query-mapping)
-- [analyze-source-structure](#analyze-source-structure)
-- [introspect-schema](#introspect-schema)
-- [validate-schema](#validate-schema)
-- [analyze-coverage](#analyze-coverage)
-- [CLI Workflow Example](#cli-workflow-example)
-- [See Also](#see-also)
-
----
-
-## Main CLI
-
-Access all SDK command-line tools through the main CLI entry point.
-
-```bash
-# Show help
-npx fc-connect help
-
-# Show version
-npx fc-connect version
-
-# Run specific command
-npx fc-connect <command> [options]
-```
-
-**Available Commands:**
-- `generate-mutation-mapping` - Generate mapping template for mutations (ingest)
-- `generate-query-mapping` - Generate mapping template for queries (extract)
-- `analyze-source-structure` - Analyze source files (XML/JSON/CSV/Parquet) and suggest mapping paths
-- `introspect-schema` - Fetch and cache GraphQL schema
-- `validate-schema` - Validate mapping against schema
-- `analyze-coverage` - Analyze field coverage in mappings
-
-## generate-mutation-mapping
-
-Generate mapping templates for GraphQL mutations (ingest direction).
-
-**Usage:**
-```bash
-npx fc-connect generate-mutation-mapping [OPTIONS]
-```
-
-**Options:**
-- `-f, --file <path>` - GraphQL mutation file path
-- `-m, --mutation <string>` - Inline GraphQL mutation string
-- `-e, --endpoint <url>` - GraphQL endpoint for schema introspection
-- `-s, --schema <path>` - JSON schema introspection file (alternative to endpoint)
-- `-o, --output <path>` - Output file path (defaults to stdout)
-- `--format <xml|json|csv>` - Source data format (default: xml)
-- `-p, --prefix <string>` - Source path prefix (e.g., $radial., $source.)
-- `--nodes` - Include nodes configuration for nested data extraction
-- `--node-config <path>` - JSON file with node configuration
-- `--custom-resolvers` - Generate custom resolver placeholders
-- `-h, --help` - Show help message
-
-**Examples:**
-
-```bash
-# Basic: Generate from file with schema introspection
-npx fc-connect generate-mutation-mapping \
-  --file ./mutations/createOrder.graphql \
-  --endpoint https://api.fluentcommerce.com/graphql
-
-# SFCC-style with nodes and prefix
-npx fc-connect generate-mutation-mapping \
-  --file ./mutations/createOrder.graphql \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --format xml \
-  --prefix '$radial.' \
-  --nodes \
-  --node-config ./nodes/radial-config.json \
-  --output ./mappings/createOrder-mapping.json
-
-# Using pre-fetched schema (faster)
-npx fc-connect generate-mutation-mapping \
-  --file ./mutations/createOrder.graphql \
-  --schema ./fluent-schema.json \
-  --output ./mappings/createOrder-mapping.json
-```
-
-**Output:**
-Generates a JSON mapping template with:
-- `direction`: "ingest"
-- `mutation`: operation name
-- `fields`: INPUT field mappings with placeholders
-- `nodes`: (optional) nested data extraction config
-- All required vs optional fields marked
-- Type information in comments
-
-## generate-query-mapping
-
-Generate mapping templates for GraphQL queries (extraction direction).
-
-**Usage:**
-```bash
-npx fc-connect generate-query-mapping [OPTIONS]
-```
-
-**Options:**
-- `-f, --file <path>` - GraphQL query file path
-- `-q, --query <string>` - Inline GraphQL query string
-- `-e, --endpoint <url>` - GraphQL endpoint for schema introspection
-- `-s, --schema <path>` - JSON schema introspection file
-- `-o, --output <path>` - Output file path
-- `--format <csv|json|xml>` - Target output format (default: json)
-- `-h, --help` - Show help message
-
-**Examples:**
-
-```bash
-# Basic usage
-npx fc-connect generate-query-mapping \
-  --file ./queries/getOrders.graphql \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --format csv \
-  --output ./mappings/extract-orders.json
-
-# With output format configuration
-npx fc-connect generate-query-mapping \
-  --query "query GetProducts { products { edges { node { id ref name } } } }" \
-  --schema ./schema.json \
-  --format json \
-  --output ./mappings/extract-products.json
-```
-
-## introspect-schema
-
-Fetch and cache GraphQL schema for offline use.
-
-**Usage:**
-```bash
-npx fc-connect introspect-schema [OPTIONS]
-```
-
-**Options:**
-- `-e, --endpoint <url>` - GraphQL endpoint URL (required)
-- `-o, --output <path>` - Output file path for schema JSON (required)
-- `--header <header>` - Custom headers (can be used multiple times)
-- `-h, --help` - Show help message
-
-**Examples:**
-
-```bash
-# Introspect and save schema
-npx fc-connect introspect-schema \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --output ./schema/fluent-schema.json
-
-# With authentication
-npx fc-connect introspect-schema \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --header "Authorization: Bearer YOUR_TOKEN" \
-  --output ./schema/fluent-schema.json
-
-# Multiple custom headers
-npx fc-connect introspect-schema \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --header "Authorization: Bearer YOUR_TOKEN" \
-  --header "X-Custom-Header: value" \
-  --output ./schema/fluent-schema.json
-```
-
-**Benefits:**
-- Cache schema for offline development
-- Faster mapping generation (no network calls)
-- Version control your schema snapshots
-- Consistent schema across team
-
-## validate-schema
-
-Validate your mapping configurations against the GraphQL schema.
-
-**Usage:**
-```bash
-npx fc-connect validate-schema [OPTIONS]
-```
-
-**Options:**
-- `-m, --mapping <path>` - Mapping file or glob pattern (required)
-- `-s, --schema <path>` - GraphQL schema JSON file (required)
-- `--strict` - Enable strict validation mode
-- `-h, --help` - Show help message
-
-**Examples:**
-
-```bash
-# Validate single mapping
-npx fc-connect validate-schema \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json
-
-# Validate multiple mappings with glob pattern
-npx fc-connect validate-schema \
-  --mapping "./mappings/*.json" \
-  --schema ./schema/fluent-schema.json
-
-# Strict mode (fails on warnings)
-npx fc-connect validate-schema \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json \
-  --strict
-```
-
-**Validation Checks:**
-- Required fields are mapped
-- Field types match schema
-- Array configurations are correct
-- Transformation functions are valid
-- Node configurations are correct
-
-## analyze-source-structure
-
-Analyze source files (XML/JSON/CSV/Parquet) to understand their structure and generate mapping configuration suggestions with automatic resolver detection.
-
-**Usage:**
-```bash
-npx fc-connect analyze-source-structure [OPTIONS]
-```
-
-**Options:**
-- `-f, --file <path>` - Source file to analyze (required)
-- `--format <xml|json|csv|parquet>` - File format (auto-detected from extension)
-- `-o, --output <path>` - Output file path for mapping template (optional)
-- `--show-structure` - Show parsed JavaScript object structure
-- `--show-json` - Show parsed structure as formatted JSON
-- `--direction <ingest|extract>` - Generate mapping for ingest or extract direction
-- `--mapper <universal|graphql>` - Generate mapping for universal or graphql mapper
-- `--markdown [path]` - Generate comprehensive markdown documentation (default: `analysis-documentation.md`)
-- `--docs [path]` - Alias for `--markdown`
-- `-h, --help` - Show help message
-
-**Examples:**
-```bash
-# Analyze XML file
-npx fc-connect analyze-source-structure \
-  --file ./order.xml \
-  --format xml \
-  --show-structure \
-  --output ./order-mapping.json
-
-# Generate markdown documentation
-npx fc-connect analyze-source-structure \
-  --file ./inventory.csv \
-  --format csv \
-  --markdown ./docs/inventory-analysis.md
-
-# Analyze and generate template with resolvers
-npx fc-connect analyze-source-structure \
-  --file ./products.json \
-  --output ./product-mapping.json
-```
-
-**Key Features:**
-- ✅ **Automatic Resolver Detection** - Detects data types and includes appropriate resolvers (`sdk.parseInt`, `sdk.parseDate`, `sdk.trim`, etc.)
-- ✅ **XML Attribute Parsing** - Automatically detects and maps XML attributes (e.g., `@sku`, `@id`)
-- ✅ **Array Detection** - Identifies arrays and generates item-relative field paths
-- ✅ **Markdown Documentation** - Generate comprehensive analysis documentation
-
-**Note:** Resolvers are automatically included in generated mapping templates based on detected data types. See [Module 12: Analyze Source Structure](./api-reference-12-analyze-source-structure.md) for complete documentation.
-
-## analyze-coverage
-
-Analyze mapping field coverage and identify gaps with detailed reports.
-
-**Usage:**
-```bash
-npx fc-connect analyze-coverage [OPTIONS]
-```
-
-**Options:**
-- `-m, --mapping <path>` - Mapping file or glob pattern (required)
-- `-s, --schema <path>` - GraphQL schema JSON file (required)
-- `--min-coverage <percent>` - Minimum total coverage % (fails if below)
-- `--min-required <percent>` - Minimum required field coverage % (fails if below)
-- `--show-missing` - Show detailed list of missing fields
-- `--format <table|json|markdown>` - Output format (default: table)
-- `-o, --output <path>` - Save report to file
-- `-h, --help` - Show help message
-
-**Examples:**
-
-```bash
-# Basic coverage report
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json
-
-# With coverage thresholds (for CI/CD)
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json \
-  --min-coverage 80 \
-  --min-required 100
-
-# Show missing fields
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json \
-  --show-missing
-
-# JSON output for automation
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/*.json \
-  --schema ./schema/fluent-schema.json \
-  --format json \
-  --output coverage-report.json
-
-# Markdown report for documentation
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json \
-  --format markdown \
-  --output ./docs/coverage.md
-```
-
-**Coverage Metrics:**
-- **Required Coverage**: % of required fields that are mapped
-- **Optional Coverage**: % of optional fields that are mapped
-- **Total Coverage**: % of all fields (required + optional) that are mapped
-
-**Example Output:**
-```
-╔═══════════════════════════════════════════════════════════════════════╗
-║  Coverage Report: createOrder-mapping.json                            ║
-╠═══════════════════════════════════════════════════════════════════════╣
-║  Operation:       createOrder                                         ║
-║  Direction:       ingest                                              ║
-╠═══════════════════════════════════════════════════════════════════════╣
-║  Required Fields: 10/10               (100%) ✅                       ║
-║  Optional Fields: 5/20                (25%)                           ║
-║  Total Coverage:  15/30               (50%)                           ║
-╚═══════════════════════════════════════════════════════════════════════╝
-```
-
-**Exit Codes:**
-- `0` - Coverage meets thresholds
-- `1` - Coverage below thresholds
-- `2` - Invalid arguments or file errors
-
-**CI/CD Integration:**
-
-```yaml
-# GitHub Actions - Enforce coverage thresholds
-- name: Check mapping coverage
-  run: |
-    npx fc-connect analyze-coverage \
-      --mapping ./mappings/*.json \
-      --schema ./schema.json \
-      --min-coverage 80 \
-      --min-required 100
-```
-
-```bash
-# Pre-commit hook
-#!/bin/bash
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/*.json \
-  --schema ./schema.json \
-  --min-required 100 \
-  || { echo "❌ Required fields not fully mapped"; exit 1; }
-```
-
-## CLI Workflow Example
-
-Complete workflow for creating and validating mappings:
-
-```bash
-# 1. Introspect and cache the schema
-npx fc-connect introspect-schema \
-  --endpoint https://api.fluentcommerce.com/graphql \
-  --output ./schema/fluent-schema.json
-
-# 2. Generate mutation mapping template
-npx fc-connect generate-mutation-mapping \
-  --file ./mutations/createOrder.graphql \
-  --schema ./schema/fluent-schema.json \
-  --output ./mappings/createOrder.json
-
-# 3. Edit the mapping file (replace TODO placeholders)
-# vim ./mappings/createOrder.json
-
-# 4. Validate the mapping
-npx fc-connect validate-schema \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json
-
-# 5. Check coverage
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/createOrder.json \
-  --schema ./schema/fluent-schema.json \
-  --show-missing \
-  --min-required 100
-
-# 6. Generate coverage report for documentation
-npx fc-connect analyze-coverage \
-  --mapping ./mappings/*.json \
-  --schema ./schema/fluent-schema.json \
-  --format markdown \
-  --output ./docs/mapping-coverage.md
-```
-
-## See Also
-
-- [Module 05: Services](./api-reference-05-services.md#universal-mapper) - Using generated mappings
-- [Getting Started Guide](../../../00-START-HERE/getting-started.md) - Basic setup
-- [CLI Tools Documentation](../../../../bin/readme.md) - Complete CLI documentation
-
----
-
-**[← Previous: Module 10 - Utilities](./api-reference-10-utilities.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 12 - Testing →](./api-reference-12-testing.md)**
+# Module 11: CLI Tools
+
+**Level:** Advanced
+**Category:** Command Line
+
+## Overview
+
+The SDK includes powerful CLI tools for schema introspection, mapping generation, validation, and coverage analysis to streamline development workflows.
+
+## Table of Contents
+
+- [Main CLI](#main-cli)
+- [generate-mutation-mapping](#generate-mutation-mapping)
+- [generate-query-mapping](#generate-query-mapping)
+- [analyze-source-structure](#analyze-source-structure)
+- [introspect-schema](#introspect-schema)
+- [validate-schema](#validate-schema)
+- [analyze-coverage](#analyze-coverage)
+- [CLI Workflow Example](#cli-workflow-example)
+- [See Also](#see-also)
+
+---
+
+## Main CLI
+
+Access all SDK command-line tools through the main CLI entry point.
+
+```bash
+# Show help
+npx fc-connect help
+
+# Show version
+npx fc-connect version
+
+# Run specific command
+npx fc-connect <command> [options]
+```
+
+**Available Commands:**
+- `generate-mutation-mapping` - Generate mapping template for mutations (ingest)
+- `generate-query-mapping` - Generate mapping template for queries (extract)
+- `analyze-source-structure` - Analyze source files (XML/JSON/CSV/Parquet) and suggest mapping paths
+- `introspect-schema` - Fetch and cache GraphQL schema
+- `validate-schema` - Validate mapping against schema
+- `analyze-coverage` - Analyze field coverage in mappings
+
+## generate-mutation-mapping
+
+Generate mapping templates for GraphQL mutations (ingest direction).
+
+**Usage:**
+```bash
+npx fc-connect generate-mutation-mapping [OPTIONS]
+```
+
+**Options:**
+- `-f, --file <path>` - GraphQL mutation file path
+- `-m, --mutation <string>` - Inline GraphQL mutation string
+- `-e, --endpoint <url>` - GraphQL endpoint for schema introspection
+- `-s, --schema <path>` - JSON schema introspection file (alternative to endpoint)
+- `-o, --output <path>` - Output file path (defaults to stdout)
+- `--format <xml|json|csv>` - Source data format (default: xml)
+- `-p, --prefix <string>` - Source path prefix (e.g., $radial., $source.)
+- `--nodes` - Include nodes configuration for nested data extraction
+- `--node-config <path>` - JSON file with node configuration
+- `--custom-resolvers` - Generate custom resolver placeholders
+- `-h, --help` - Show help message
+
+**Examples:**
+
+```bash
+# Basic: Generate from file with schema introspection
+npx fc-connect generate-mutation-mapping \
+  --file ./mutations/createOrder.graphql \
+  --endpoint https://api.fluentcommerce.com/graphql
+
+# SFCC-style with nodes and prefix
+npx fc-connect generate-mutation-mapping \
+  --file ./mutations/createOrder.graphql \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --format xml \
+  --prefix '$radial.' \
+  --nodes \
+  --node-config ./nodes/radial-config.json \
+  --output ./mappings/createOrder-mapping.json
+
+# Using pre-fetched schema (faster)
+npx fc-connect generate-mutation-mapping \
+  --file ./mutations/createOrder.graphql \
+  --schema ./fluent-schema.json \
+  --output ./mappings/createOrder-mapping.json
+```
+
+**Output:**
+Generates a JSON mapping template with:
+- `direction`: "ingest"
+- `mutation`: operation name
+- `fields`: INPUT field mappings with placeholders
+- `nodes`: (optional) nested data extraction config
+- All required vs optional fields marked
+- Type information in comments
+
+## generate-query-mapping
+
+Generate mapping templates for GraphQL queries (extraction direction).
+
+**Usage:**
+```bash
+npx fc-connect generate-query-mapping [OPTIONS]
+```
+
+**Options:**
+- `-f, --file <path>` - GraphQL query file path
+- `-q, --query <string>` - Inline GraphQL query string
+- `-e, --endpoint <url>` - GraphQL endpoint for schema introspection
+- `-s, --schema <path>` - JSON schema introspection file
+- `-o, --output <path>` - Output file path
+- `--format <csv|json|xml>` - Target output format (default: json)
+- `-h, --help` - Show help message
+
+**Examples:**
+
+```bash
+# Basic usage
+npx fc-connect generate-query-mapping \
+  --file ./queries/getOrders.graphql \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --format csv \
+  --output ./mappings/extract-orders.json
+
+# With output format configuration
+npx fc-connect generate-query-mapping \
+  --query "query GetProducts { products { edges { node { id ref name } } } }" \
+  --schema ./schema.json \
+  --format json \
+  --output ./mappings/extract-products.json
+```
+
+## introspect-schema
+
+Fetch and cache GraphQL schema for offline use.
+
+**Usage:**
+```bash
+npx fc-connect introspect-schema [OPTIONS]
+```
+
+**Options:**
+- `-e, --endpoint <url>` - GraphQL endpoint URL (required)
+- `-o, --output <path>` - Output file path for schema JSON (required)
+- `--header <header>` - Custom headers (can be used multiple times)
+- `-h, --help` - Show help message
+
+**Examples:**
+
+```bash
+# Introspect and save schema
+npx fc-connect introspect-schema \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --output ./schema/fluent-schema.json
+
+# With authentication
+npx fc-connect introspect-schema \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --header "Authorization: Bearer YOUR_TOKEN" \
+  --output ./schema/fluent-schema.json
+
+# Multiple custom headers
+npx fc-connect introspect-schema \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --header "Authorization: Bearer YOUR_TOKEN" \
+  --header "X-Custom-Header: value" \
+  --output ./schema/fluent-schema.json
+```
+
+**Benefits:**
+- Cache schema for offline development
+- Faster mapping generation (no network calls)
+- Version control your schema snapshots
+- Consistent schema across team
+
+## validate-schema
+
+Validate your mapping configurations against the GraphQL schema.
+
+**Usage:**
+```bash
+npx fc-connect validate-schema [OPTIONS]
+```
+
+**Options:**
+- `-m, --mapping <path>` - Mapping file or glob pattern (required)
+- `-s, --schema <path>` - GraphQL schema JSON file (required)
+- `--strict` - Enable strict validation mode
+- `-h, --help` - Show help message
+
+**Examples:**
+
+```bash
+# Validate single mapping
+npx fc-connect validate-schema \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json
+
+# Validate multiple mappings with glob pattern
+npx fc-connect validate-schema \
+  --mapping "./mappings/*.json" \
+  --schema ./schema/fluent-schema.json
+
+# Strict mode (fails on warnings)
+npx fc-connect validate-schema \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json \
+  --strict
+```
+
+**Validation Checks:**
+- Required fields are mapped
+- Field types match schema
+- Array configurations are correct
+- Transformation functions are valid
+- Node configurations are correct
+
+## analyze-source-structure
+
+Analyze source files (XML/JSON/CSV/Parquet) to understand their structure and generate mapping configuration suggestions with automatic resolver detection.
+
+**Usage:**
+```bash
+npx fc-connect analyze-source-structure [OPTIONS]
+```
+
+**Options:**
+- `-f, --file <path>` - Source file to analyze (required)
+- `--format <xml|json|csv|parquet>` - File format (auto-detected from extension)
+- `-o, --output <path>` - Output file path for mapping template (optional)
+- `--show-structure` - Show parsed JavaScript object structure
+- `--show-json` - Show parsed structure as formatted JSON
+- `--direction <ingest|extract>` - Generate mapping for ingest or extract direction
+- `--mapper <universal|graphql>` - Generate mapping for universal or graphql mapper
+- `--markdown [path]` - Generate comprehensive markdown documentation (default: `analysis-documentation.md`)
+- `--docs [path]` - Alias for `--markdown`
+- `-h, --help` - Show help message
+
+**Examples:**
+```bash
+# Analyze XML file
+npx fc-connect analyze-source-structure \
+  --file ./order.xml \
+  --format xml \
+  --show-structure \
+  --output ./order-mapping.json
+
+# Generate markdown documentation
+npx fc-connect analyze-source-structure \
+  --file ./inventory.csv \
+  --format csv \
+  --markdown ./docs/inventory-analysis.md
+
+# Analyze and generate template with resolvers
+npx fc-connect analyze-source-structure \
+  --file ./products.json \
+  --output ./product-mapping.json
+```
+
+**Key Features:**
+- ✅ **Automatic Resolver Detection** - Detects data types and includes appropriate resolvers (`sdk.parseInt`, `sdk.parseDate`, `sdk.trim`, etc.)
+- ✅ **XML Attribute Parsing** - Automatically detects and maps XML attributes (e.g., `@sku`, `@id`)
+- ✅ **Array Detection** - Identifies arrays and generates item-relative field paths
+- ✅ **Markdown Documentation** - Generate comprehensive analysis documentation
+
+**Note:** Resolvers are automatically included in generated mapping templates based on detected data types. See [Module 12: Analyze Source Structure](./api-reference-12-analyze-source-structure.md) for complete documentation.
+
+## analyze-coverage
+
+Analyze mapping field coverage and identify gaps with detailed reports.
+
+**Usage:**
+```bash
+npx fc-connect analyze-coverage [OPTIONS]
+```
+
+**Options:**
+- `-m, --mapping <path>` - Mapping file or glob pattern (required)
+- `-s, --schema <path>` - GraphQL schema JSON file (required)
+- `--min-coverage <percent>` - Minimum total coverage % (fails if below)
+- `--min-required <percent>` - Minimum required field coverage % (fails if below)
+- `--show-missing` - Show detailed list of missing fields
+- `--format <table|json|markdown>` - Output format (default: table)
+- `-o, --output <path>` - Save report to file
+- `-h, --help` - Show help message
+
+**Examples:**
+
+```bash
+# Basic coverage report
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json
+
+# With coverage thresholds (for CI/CD)
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json \
+  --min-coverage 80 \
+  --min-required 100
+
+# Show missing fields
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json \
+  --show-missing
+
+# JSON output for automation
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/*.json \
+  --schema ./schema/fluent-schema.json \
+  --format json \
+  --output coverage-report.json
+
+# Markdown report for documentation
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json \
+  --format markdown \
+  --output ./docs/coverage.md
+```
+
+**Coverage Metrics:**
+- **Required Coverage**: % of required fields that are mapped
+- **Optional Coverage**: % of optional fields that are mapped
+- **Total Coverage**: % of all fields (required + optional) that are mapped
+
+**Example Output:**
+```
+╔═══════════════════════════════════════════════════════════════════════╗
+║  Coverage Report: createOrder-mapping.json                            ║
+╠═══════════════════════════════════════════════════════════════════════╣
+║  Operation:       createOrder                                         ║
+║  Direction:       ingest                                              ║
+╠═══════════════════════════════════════════════════════════════════════╣
+║  Required Fields: 10/10               (100%) ✅                       ║
+║  Optional Fields: 5/20                (25%)                           ║
+║  Total Coverage:  15/30               (50%)                           ║
+╚═══════════════════════════════════════════════════════════════════════╝
+```
+
+**Exit Codes:**
+- `0` - Coverage meets thresholds
+- `1` - Coverage below thresholds
+- `2` - Invalid arguments or file errors
+
+**CI/CD Integration:**
+
+```yaml
+# GitHub Actions - Enforce coverage thresholds
+- name: Check mapping coverage
+  run: |
+    npx fc-connect analyze-coverage \
+      --mapping ./mappings/*.json \
+      --schema ./schema.json \
+      --min-coverage 80 \
+      --min-required 100
+```
+
+```bash
+# Pre-commit hook
+#!/bin/bash
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/*.json \
+  --schema ./schema.json \
+  --min-required 100 \
+  || { echo "❌ Required fields not fully mapped"; exit 1; }
+```
+
+## CLI Workflow Example
+
+Complete workflow for creating and validating mappings:
+
+```bash
+# 1. Introspect and cache the schema
+npx fc-connect introspect-schema \
+  --endpoint https://api.fluentcommerce.com/graphql \
+  --output ./schema/fluent-schema.json
+
+# 2. Generate mutation mapping template
+npx fc-connect generate-mutation-mapping \
+  --file ./mutations/createOrder.graphql \
+  --schema ./schema/fluent-schema.json \
+  --output ./mappings/createOrder.json
+
+# 3. Edit the mapping file (replace TODO placeholders)
+# vim ./mappings/createOrder.json
+
+# 4. Validate the mapping
+npx fc-connect validate-schema \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json
+
+# 5. Check coverage
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/createOrder.json \
+  --schema ./schema/fluent-schema.json \
+  --show-missing \
+  --min-required 100
+
+# 6. Generate coverage report for documentation
+npx fc-connect analyze-coverage \
+  --mapping ./mappings/*.json \
+  --schema ./schema/fluent-schema.json \
+  --format markdown \
+  --output ./docs/mapping-coverage.md
+```
+
+## See Also
+
+- [Module 05: Services](./api-reference-05-services.md#universal-mapper) - Using generated mappings
+- [Getting Started Guide](../../../00-START-HERE/getting-started.md) - Basic setup
+- [CLI Tools Documentation](../../../../bin/readme.md) - Complete CLI documentation
+
+---
+
+**[← Previous: Module 10 - Utilities](./api-reference-10-utilities.md)** | **[API Reference Home](../api-reference-readme.md)** | **[Next: Module 12 - Testing →](./api-reference-12-testing.md)**