@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/00-START-HERE/readme.md

@@ -1,237 +1,237 @@
-# Fluent Commerce Connect SDK Documentation
-
-Comprehensive documentation for the Fluent Commerce Connect SDK - a TypeScript/JavaScript library for building integrations with inventory ingestion and extraction capabilities.
-
-**Current Version:** Latest
-**Node.js:** >= 18.0.0
-**TypeScript:** 5.9.2
-**Platform Support:** Node.js, Deno, Versori
-
-> **Tip:** For installation and quick start, see the main [readme.md](../../readme.md). This document provides navigation to detailed guides.
-
----
-
-## 📑 Documentation Index
-
-### 🚀 Quick Start
-
-- **[Getting Started](./getting-started.md)** - Installation, configuration, and quick examples
-- **[Mapper Quick Decision Guide](./mapper-quick-decision-guide.md)** - 🆕 **Which mapper to use?** (2-minute read)
-- **[CLI Tools](./cli-documentation-index.md)** - Analyze data files and generate mapping templates 🆕
-- **[API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete API documentation for all SDK methods
-- **[SDK Philosophy](./sdk-philosophy.md)** - Design principles and architecture decisions
-
-### 🏗️ Architecture
-
-- **[Architecture Overview](../04-REFERENCE/architecture/readme.md)** - Complete SDK architecture documentation
-- **[Client Architecture](../04-REFERENCE/architecture/architecture-02-client-architecture.md)** - Client system design
-- **[Data Flow](../04-REFERENCE/architecture/architecture-03-data-flow.md)** - How data moves through the SDK
-- **[Service Layer](../04-REFERENCE/architecture/architecture-04-service-layer.md)** - Service organization and patterns
-- **[State Management](../04-REFERENCE/architecture/architecture-06-state-management.md)** - State tracking and duplicate prevention
-
-### 🎯 Scenarios & Patterns
-
-- **[Connector Scenarios](../03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md)** - Example connector scenarios
-- **[Integration Patterns](../03-PATTERN-GUIDES/integration-patterns/)** - Common patterns and practices
-- **[Orchestrators Guide](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md)** - Production orchestrators for inventory workflows
-
-### 🔄 Data Workflows
-
-- **[Ingestion Guide](../02-CORE-GUIDES/ingestion/)** - Complete guide for ingesting data into Fluent Commerce
-- **[Extraction Guide](../02-CORE-GUIDES/extraction/)** - Extract and transform data from Fluent Commerce
-- **[Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/)** - 🌟 Automatic GraphQL pagination with zero boilerplate (modules + examples)
-
-### 🔄 Data Transformation
-
-- **[Universal Mapping Guide](../02-CORE-GUIDES/mapping/mapping-readme.md)** - Progressive learning path for field mapping and transformation
-- **[Resolver Guide](../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md)** - Complete resolver development guide with modules and cookbook patterns
-- **[Resolver Signature](../04-REFERENCE/resolver-signature/resolver-signature-readme.md)** - Detailed resolver function signatures and contracts
-- **[GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - Map XML/JSON to GraphQL mutations
-- **[Multiple Connections](../03-PATTERN-GUIDES/multiple-connections/multiple-connections-readme.md)** - Handle multiple Fluent connections
-
-### 📄 Parser Learning Paths
-
-- **[CSV Parser](../02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md#csv-parser)** - Built-in CSV parsing with validation
-- **[Parser Guide](../02-CORE-GUIDES/parsers/parsers-readme.md)** - Complete learning path for JSON/JSONL and XML parsing with streaming support
-- **[Parquet Guide](../03-PATTERN-GUIDES/parquet/)** - Work with Parquet files for big data operations
-
-### 📁 Data Sources Learning Paths
-
-- **[Data Sources Guide](../02-CORE-GUIDES/data-sources/data-sources-readme.md)** - Complete learning path for S3 and SFTP integrations
-- **[SFTP Quick Reference](../02-CORE-GUIDES/data-sources/data-sources-quick-reference.md)** - Quick examples and recipes
-- **[File Operations Guide](../03-PATTERN-GUIDES/file-operations/file-operations-readme.md)** - Overview of all file operation capabilities
-
-### 🔒 Validation & Security
-
-- **[Webhook Validation Guide](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)** - Validate webhook signatures from Fluent Commerce
-- **[Error Handling Guide](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md)** - Comprehensive error handling patterns and strategies
-- **[GraphQL Mapping Error Handling](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)** - Error handling for GraphQL operations
-- **[Testing Guide](../04-REFERENCE/testing/testing-readme.md)** - Test utilities and validation tools
-
-### 🌐 Platform Integration
-
-- **[Versori Platform](../04-REFERENCE/platforms/versori/)** - Complete Versori platform integration guide
-- **[Versori Webhook Response Patterns](../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)** - ⚠️ **CRITICAL**: Returning XML/HTML/CSV from webhooks
-- **[Deno Compatibility](../04-REFERENCE/platforms/deno/)** - Deno runtime support and compatibility
-
-### 📚 Use Cases & Examples
-
-- **[Use Cases Index](../01-TEMPLATES/readme.md)** - Complete catalog of use cases and examples with decision tree
-
-#### Patterns (Reusable Components)
-
-- **[Custom Resolvers](../01-TEMPLATES/patterns/custom-resolvers.md)** - Custom transformation functions
-- **[Error Handling & Retry](../01-TEMPLATES/patterns/error-handling-retry.md)** - Circuit breakers, retries, fallbacks
-- **[Field Mapping Universal](../01-TEMPLATES/patterns/field-mapping-universal.md)** - Universal field transformation patterns
-- **[Pagination & Streaming](../01-TEMPLATES/patterns/pagination-streaming.md)** - Handle large datasets efficiently
-- **[State & Duplicate Prevention](../01-TEMPLATES/patterns/state-duplicate-prevention.md)** - Prevent duplicate processing
-- **[Large File Splitting](../01-TEMPLATES/patterns/large-file-splitting.md)** - Handle GB-sized files
-- **[Master Data ETL](../01-TEMPLATES/patterns/master-data-etl.md)** - Load locations, products, controls
-- **[CSV Schema Validation](../01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md)** - Validate and report CSV issues
-
-#### Standalone Scripts (Node.js/Deno)
-
-- **[S3 CSV → Batch API](../01-TEMPLATES/standalone/s3-csv-batch-api.md)** - Complete standalone S3 CSV ingestion
-- **[SFTP XML → GraphQL](../01-TEMPLATES/standalone/sftp-xml-graphql.md)** - SFTP XML order ingestion
-- **[GraphQL Query Export](../01-TEMPLATES/standalone/graphql-query-export.md)** - Export data via GraphQL queries
-- **[Multi-Source Aggregation](../01-TEMPLATES/standalone/multi-source-aggregation.md)** - Combine multiple data sources
-- **[S3 CSV Inventory Batch](../01-TEMPLATES/standalone/s3-csv-batch-api.md)** - CSV inventory processing
-- **[GraphQL → Parquet S3](../01-TEMPLATES/standalone/graphql-to-parquet-partitioned-s3.md)** - Export to partitioned Parquet
-- **[Multi-Channel Sync](../01-TEMPLATES/standalone/multi-channel-inventory-sync.md)** - Sync across channels
-- **[ASN Inbound Processing](../01-TEMPLATES/standalone/asn-inbound-processing.md)** - Process ASN/EDI 856 files
-
-#### Versori Platform Examples
-
-**Webhooks** (Real-time):
-- **[XML Order Ingestion](../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)** - Process XML orders via webhooks
-- **[Dropship Routing](../01-TEMPLATES/versori/webhooks/template-webhook-dropship-routing.md)** - Route dropship orders
-- **[Flash Sale Reserve](../01-TEMPLATES/versori/webhooks/template-webhook-flash-sale-reserve.md)** - Handle flash sale reservations
-- **[Generic XML Order](../01-TEMPLATES/versori/webhooks/template-webhook-generic-xml-order.md)** - Generic XML order processing
-- **[RMA Returns](../01-TEMPLATES/versori/webhooks/template-webhook-rma-returns-comprehensive.md)** - Comprehensive returns processing
-- **[ASN Purchase Order](../01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md)** - ASN webhook processing
-
-**Scheduled** (Batch):
-- **[Bulk Price Updates](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Schedule price updates
-- **[CSV Inventory Sync](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled CSV ingestion
-- **[Cycle Count Reconciliation](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Inventory counting
-- **[Master Data Adapter](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Master data loading
-- **[Multi-Channel Sync](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled multi-channel sync
-- **[SFTP CSV Ingestion](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)** - SFTP scheduled ingestion
-
-**Patterns** (Versori-specific):
-- **[Dual Workflow Connector](../01-TEMPLATES/versori/patterns/dual-workflow-connector.md)** - Webhook + scheduled combination
-- **[KV State Management](../01-TEMPLATES/versori/patterns/kv-state-management.md)** - Versori KV store patterns
-- **[XML Response Patterns](../01-TEMPLATES/versori/patterns/xml-response-patterns.md)** - Return XML from webhooks
-
-**Business Examples** (Complex workflows):
-- **[Dropship Order Routing](../01-TEMPLATES/versori/business-examples/dropship-order-routing.md)** - Complete dropship workflow
-- **[GraphQL Parquet Extraction](../01-TEMPLATES/versori/business-examples/graphql-parquet-extraction.md)** - Extract to Parquet format
-- **[Inter-Location Transfers](../01-TEMPLATES/versori/business-examples/inter-location-transfers.md)** - Transfer inventory between locations
-- **[Pre-Order Allocation](../01-TEMPLATES/versori/business-examples/pre-order-allocation.md)** - Pre-order reservation system
-
----
-
-## 🔍 Find What You Need
-
-| **I Want To...** | **Start Here** | **Then See** |
-|---|---|---|
-| **Analyze my data files** | 🆕 [CLI Tools](./cli-documentation-index.md) | [CLI User Guide](./cli-analyze-source-structure-guide.md) |
-| **Build a production connector** | 🌟 [Connector Scenarios](../03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md) | [Integration Patterns](../03-PATTERN-GUIDES/integration-patterns/) |
-| **Get started quickly** | [Getting Started](./getting-started.md) | [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) |
-| **Fetch ALL results (not just first page)** | ⚠️ [Auto-Pagination](../02-CORE-GUIDES/auto-pagination/) | [Quick Start](../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md) |
-| **Set up inventory sync** | [Ingestion Guide](../02-CORE-GUIDES/ingestion/) | [Data Sources](../02-CORE-GUIDES/data-sources/data-sources-readme.md) |
-| **Use SFTP (no platform needed)** | 🌟 [Data Sources Guide](../02-CORE-GUIDES/data-sources/data-sources-readme.md) | [SFTP Quick Reference](../02-CORE-GUIDES/data-sources/data-sources-quick-reference.md) |
-| **Export data from Fluent** | [Extraction Guide](../02-CORE-GUIDES/extraction/) | [ExtractionOrchestrator Summary](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) |
-| **High-level extraction (auto-pagination)** | 🌟 [ExtractionOrchestrator](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [Extraction Guide](../02-CORE-GUIDES/extraction/) |
-| **Handle webhooks** | [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Webhook Examples](../01-TEMPLATES/versori/webhooks/) |
-| **Validate webhook signatures** | [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Webhook Implementation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) |
-| **Track job lifecycle** | [JobTracker Usage](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [State Management](../04-REFERENCE/architecture/architecture-06-state-management.md) |
-| **Retry partial batch failures** | [Batch Recovery Patterns](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [PartialBatchRecovery API](../02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md#partialbatchrecovery-new) |
-| **Pre-validate connector config** | [PreflightValidator Guide](../04-REFERENCE/testing/testing-readme.md) | [Testing Patterns](../04-REFERENCE/testing/) |
-| **Return XML/HTML from webhook** | ⚠️ [Webhook Response Patterns](../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) | [Versori Platform](../04-REFERENCE/platforms/versori/) |
-| **Deploy on Versori** | [Versori Platform](../04-REFERENCE/platforms/versori/) | [Versori Examples](../01-TEMPLATES/versori/) |
-| **Look up API methods** | [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) | [SDK Philosophy](./sdk-philosophy.md) |
-| **Transform data fields** | 🆕 [Mapper Quick Decision Guide](./mapper-quick-decision-guide.md) | [Universal Mapping](../02-CORE-GUIDES/mapping/mapping-readme.md) |
-| **Choose which mapper to use** | 🆕 [Mapper Quick Decision Guide](./mapper-quick-decision-guide.md) | [Complete Comparison](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) |
-| **Parse CSV data** | [API Reference](../02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md) | [CSV Validation Pattern](../01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md) |
-| **Parse XML/JSON data** | [Parser Guide](../02-CORE-GUIDES/parsers/parsers-readme.md) | [GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/) |
-| **Work with S3** | [Data Sources Guide](../02-CORE-GUIDES/data-sources/data-sources-readme.md) | [S3 Examples](../01-TEMPLATES/standalone/s3-csv-batch-api.md) |
-| **Debug issues** | [Error Handling Guide](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [Testing Guide](../04-REFERENCE/testing/testing-readme.md) |
-| **Prevent duplicates** | [State Management](../01-TEMPLATES/patterns/state-duplicate-prevention.md) | [Architecture](../04-REFERENCE/architecture/architecture-06-state-management.md) |
-| **Handle large files** | [Large File Splitting](../01-TEMPLATES/patterns/large-file-splitting.md) | [Pagination & Streaming](../01-TEMPLATES/patterns/pagination-streaming.md) |
-| **See complete examples** | [Use Cases Index](../01-TEMPLATES/readme.md) | [FAQ](../01-TEMPLATES/faq.md) |
-
----
-
-## 📖 Documentation Structure
-
-**New 5-folder organization** for better AI context loading and navigation:
-
-```
-docs/
-├── readme.md (this file)
-├── template-loading-matrix.md (template selection guide)
-│
-├── 00-START-HERE/ (essential docs - read first)
-│   ├── getting-started.md (installation & setup)
-│   ├── decision-tree.md (which approach to use)
-│   ├── sdk-philosophy.md (design principles)
-│   └── troubleshooting-quick-reference.md (90% of issues)
-│
-├── 01-TEMPLATES/ (complete working examples)
-│   ├── readme.md (complete catalog with decision tree)
-│   ├── faq.md (troubleshooting guide)
-│   ├── patterns/ (9 reusable components)
-│   ├── standalone/ (9 Node.js/Deno scripts)
-│   └── versori/ (31 Versori platform examples)
-│       ├── webhooks/ (6 real-time)
-│       ├── scheduled/ (6 batch)
-│       ├── patterns/ (3 Versori-specific)
-│       └── business-examples/ (4 complex workflows)
-│
-├── 02-CORE-GUIDES/ (progressive learning paths)
-│   ├── api-reference/ (complete API docs)
-│   ├── ingestion/ (data into Fluent)
-│   ├── extraction/ (data from Fluent)
-│   ├── auto-pagination/ (7 modules - cursor pagination)
-│   ├── data-sources/ (S3, SFTP guides)
-│   ├── parsers/ (CSV, XML, JSON, Parquet)
-│   ├── webhook-validation/ (webhook security)
-│   └── mapping/ (field transformation)
-│       ├── modules/ (universal mapping)
-│       ├── resolvers/ (7 modules - custom functions)
-│       └── graphql-mutation-mapping/ (XML/JSON → GraphQL)
-│
-├── 03-PATTERN-GUIDES/ (reusable patterns)
-│   ├── error-handling/ (retry, circuit breakers)
-│   ├── file-operations/ (S3, SFTP patterns)
-│   ├── integration-patterns/ (common workflows)
-│   ├── multiple-connections/ (multi-tenant)
-│   ├── orchestrators/ (high-level workflows)
-│   ├── parquet/ (big data operations)
-│   └── [other patterns]
-│
-└── 04-REFERENCE/ (deep dives & platform docs)
-    ├── architecture/ (7 docs - system design)
-    ├── testing/ (test utilities)
-    ├── platforms/versori/ (Versori integration)
-    ├── schema/ (GraphQL schema docs)
-    └── troubleshooting/ (detailed debugging)
-```
-
----
-
-## 🔗 External Resources
-
-- **[NPM Package](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)** - Install the SDK
-- **[GitHub Repository](https://github.com/fluentcommerce/fc-connect-sdk)** - Source code and issues
-- **[Fluent Commerce API Docs](https://docs.fluentcommerce.com)** - Fluent Commerce platform documentation
-- **[Versori Platform](https://versori.com)** - Versori integration platform
-
----
-
-## 📝 Contributing
-
-Found an issue or want to improve the docs? Please see the main [readme.md](../../readme.md) for contribution guidelines.
-
-**License:** MIT | **Current Version:** Latest
+# Fluent Commerce Connect SDK Documentation
+
+Comprehensive documentation for the Fluent Commerce Connect SDK - a TypeScript/JavaScript library for building integrations with inventory ingestion and extraction capabilities.
+
+**Current Version:** Latest
+**Node.js:** >= 18.0.0
+**TypeScript:** 5.9.2
+**Platform Support:** Node.js, Deno, Versori
+
+> **Tip:** For installation and quick start, see the main [readme.md](../../readme.md). This document provides navigation to detailed guides.
+
+---
+
+## 📑 Documentation Index
+
+### 🚀 Quick Start
+
+- **[Getting Started](./getting-started.md)** - Installation, configuration, and quick examples
+- **[Mapper Quick Decision Guide](./mapper-quick-decision-guide.md)** - 🆕 **Which mapper to use?** (2-minute read)
+- **[CLI Tools](./cli-documentation-index.md)** - Analyze data files and generate mapping templates 🆕
+- **[API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md)** - Complete API documentation for all SDK methods
+- **[SDK Philosophy](./sdk-philosophy.md)** - Design principles and architecture decisions
+
+### 🏗️ Architecture
+
+- **[Architecture Overview](../04-REFERENCE/architecture/readme.md)** - Complete SDK architecture documentation
+- **[Client Architecture](../04-REFERENCE/architecture/architecture-02-client-architecture.md)** - Client system design
+- **[Data Flow](../04-REFERENCE/architecture/architecture-03-data-flow.md)** - How data moves through the SDK
+- **[Service Layer](../04-REFERENCE/architecture/architecture-04-service-layer.md)** - Service organization and patterns
+- **[State Management](../04-REFERENCE/architecture/architecture-06-state-management.md)** - State tracking and duplicate prevention
+
+### 🎯 Scenarios & Patterns
+
+- **[Connector Scenarios](../03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md)** - Example connector scenarios
+- **[Integration Patterns](../03-PATTERN-GUIDES/integration-patterns/)** - Common patterns and practices
+- **[Orchestrators Guide](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md)** - Production orchestrators for inventory workflows
+
+### 🔄 Data Workflows
+
+- **[Ingestion Guide](../02-CORE-GUIDES/ingestion/)** - Complete guide for ingesting data into Fluent Commerce
+- **[Extraction Guide](../02-CORE-GUIDES/extraction/)** - Extract and transform data from Fluent Commerce
+- **[Auto-Pagination Guide](../02-CORE-GUIDES/auto-pagination/)** - 🌟 Automatic GraphQL pagination with zero boilerplate (modules + examples)
+
+### 🔄 Data Transformation
+
+- **[Universal Mapping Guide](../02-CORE-GUIDES/mapping/mapping-readme.md)** - Progressive learning path for field mapping and transformation
+- **[Resolver Guide](../02-CORE-GUIDES/mapping/resolvers/mapping-resolvers-readme.md)** - Complete resolver development guide with modules and cookbook patterns
+- **[Resolver Signature](../04-REFERENCE/resolver-signature/resolver-signature-readme.md)** - Detailed resolver function signatures and contracts
+- **[GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/)** - Map XML/JSON to GraphQL mutations
+- **[Multiple Connections](../03-PATTERN-GUIDES/multiple-connections/multiple-connections-readme.md)** - Handle multiple Fluent connections
+
+### 📄 Parser Learning Paths
+
+- **[CSV Parser](../02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md#csv-parser)** - Built-in CSV parsing with validation
+- **[Parser Guide](../02-CORE-GUIDES/parsers/parsers-readme.md)** - Complete learning path for JSON/JSONL and XML parsing with streaming support
+- **[Parquet Guide](../03-PATTERN-GUIDES/parquet/)** - Work with Parquet files for big data operations
+
+### 📁 Data Sources Learning Paths
+
+- **[Data Sources Guide](../02-CORE-GUIDES/data-sources/data-sources-readme.md)** - Complete learning path for S3 and SFTP integrations
+- **[SFTP Quick Reference](../02-CORE-GUIDES/data-sources/data-sources-quick-reference.md)** - Quick examples and recipes
+- **[File Operations Guide](../03-PATTERN-GUIDES/file-operations/file-operations-readme.md)** - Overview of all file operation capabilities
+
+### 🔒 Validation & Security
+
+- **[Webhook Validation Guide](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md)** - Validate webhook signatures from Fluent Commerce
+- **[Error Handling Guide](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md)** - Comprehensive error handling patterns and strategies
+- **[GraphQL Mapping Error Handling](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/modules/graphql-mutation-mapping-11-error-handling.md)** - Error handling for GraphQL operations
+- **[Testing Guide](../04-REFERENCE/testing/testing-readme.md)** - Test utilities and validation tools
+
+### 🌐 Platform Integration
+
+- **[Versori Platform](../04-REFERENCE/platforms/versori/)** - Complete Versori platform integration guide
+- **[Versori Webhook Response Patterns](../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)** - ⚠️ **CRITICAL**: Returning XML/HTML/CSV from webhooks
+- **[Deno Compatibility](../04-REFERENCE/platforms/deno/)** - Deno runtime support and compatibility
+
+### 📚 Use Cases & Examples
+
+- **[Use Cases Index](../01-TEMPLATES/readme.md)** - Complete catalog of use cases and examples with decision tree
+
+#### Patterns (Reusable Components)
+
+- **[Custom Resolvers](../01-TEMPLATES/patterns/custom-resolvers.md)** - Custom transformation functions
+- **[Error Handling & Retry](../01-TEMPLATES/patterns/error-handling-retry.md)** - Circuit breakers, retries, fallbacks
+- **[Field Mapping Universal](../01-TEMPLATES/patterns/field-mapping-universal.md)** - Universal field transformation patterns
+- **[Pagination & Streaming](../01-TEMPLATES/patterns/pagination-streaming.md)** - Handle large datasets efficiently
+- **[State & Duplicate Prevention](../01-TEMPLATES/patterns/state-duplicate-prevention.md)** - Prevent duplicate processing
+- **[Large File Splitting](../01-TEMPLATES/patterns/large-file-splitting.md)** - Handle GB-sized files
+- **[Master Data ETL](../01-TEMPLATES/patterns/master-data-etl.md)** - Load locations, products, controls
+- **[CSV Schema Validation](../01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md)** - Validate and report CSV issues
+
+#### Standalone Scripts (Node.js/Deno)
+
+- **[S3 CSV → Batch API](../01-TEMPLATES/standalone/s3-csv-batch-api.md)** - Complete standalone S3 CSV ingestion
+- **[SFTP XML → GraphQL](../01-TEMPLATES/standalone/sftp-xml-graphql.md)** - SFTP XML order ingestion
+- **[GraphQL Query Export](../01-TEMPLATES/standalone/graphql-query-export.md)** - Export data via GraphQL queries
+- **[Multi-Source Aggregation](../01-TEMPLATES/standalone/multi-source-aggregation.md)** - Combine multiple data sources
+- **[S3 CSV Inventory Batch](../01-TEMPLATES/standalone/s3-csv-batch-api.md)** - CSV inventory processing
+- **[GraphQL → Parquet S3](../01-TEMPLATES/standalone/graphql-to-parquet-partitioned-s3.md)** - Export to partitioned Parquet
+- **[Multi-Channel Sync](../01-TEMPLATES/standalone/multi-channel-inventory-sync.md)** - Sync across channels
+- **[ASN Inbound Processing](../01-TEMPLATES/standalone/asn-inbound-processing.md)** - Process ASN/EDI 856 files
+
+#### Versori Platform Examples
+
+**Webhooks** (Real-time):
+- **[XML Order Ingestion](../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)** - Process XML orders via webhooks
+- **[Dropship Routing](../01-TEMPLATES/versori/webhooks/template-webhook-dropship-routing.md)** - Route dropship orders
+- **[Flash Sale Reserve](../01-TEMPLATES/versori/webhooks/template-webhook-flash-sale-reserve.md)** - Handle flash sale reservations
+- **[Generic XML Order](../01-TEMPLATES/versori/webhooks/template-webhook-generic-xml-order.md)** - Generic XML order processing
+- **[RMA Returns](../01-TEMPLATES/versori/webhooks/template-webhook-rma-returns-comprehensive.md)** - Comprehensive returns processing
+- **[ASN Purchase Order](../01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md)** - ASN webhook processing
+
+**Scheduled** (Batch):
+- **[Bulk Price Updates](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Schedule price updates
+- **[CSV Inventory Sync](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled CSV ingestion
+- **[Cycle Count Reconciliation](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Inventory counting
+- **[Master Data Adapter](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Master data loading
+- **[Multi-Channel Sync](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-s3-csv-inventory-batch.md)** - Scheduled multi-channel sync
+- **[SFTP CSV Ingestion](../01-TEMPLATES/versori/workflows/ingestion/batch-api/template-ingestion-sftp-csv-inventory-batch.md)** - SFTP scheduled ingestion
+
+**Patterns** (Versori-specific):
+- **[Dual Workflow Connector](../01-TEMPLATES/versori/patterns/dual-workflow-connector.md)** - Webhook + scheduled combination
+- **[KV State Management](../01-TEMPLATES/versori/patterns/kv-state-management.md)** - Versori KV store patterns
+- **[XML Response Patterns](../01-TEMPLATES/versori/patterns/xml-response-patterns.md)** - Return XML from webhooks
+
+**Business Examples** (Complex workflows):
+- **[Dropship Order Routing](../01-TEMPLATES/versori/business-examples/dropship-order-routing.md)** - Complete dropship workflow
+- **[GraphQL Parquet Extraction](../01-TEMPLATES/versori/business-examples/graphql-parquet-extraction.md)** - Extract to Parquet format
+- **[Inter-Location Transfers](../01-TEMPLATES/versori/business-examples/inter-location-transfers.md)** - Transfer inventory between locations
+- **[Pre-Order Allocation](../01-TEMPLATES/versori/business-examples/pre-order-allocation.md)** - Pre-order reservation system
+
+---
+
+## 🔍 Find What You Need
+
+| **I Want To...** | **Start Here** | **Then See** |
+|---|---|---|
+| **Analyze my data files** | 🆕 [CLI Tools](./cli-documentation-index.md) | [CLI User Guide](./cli-analyze-source-structure-guide.md) |
+| **Build a production connector** | 🌟 [Connector Scenarios](../03-PATTERN-GUIDES/connector-scenarios/connector-scenarios-readme.md) | [Integration Patterns](../03-PATTERN-GUIDES/integration-patterns/) |
+| **Get started quickly** | [Getting Started](./getting-started.md) | [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) |
+| **Fetch ALL results (not just first page)** | ⚠️ [Auto-Pagination](../02-CORE-GUIDES/auto-pagination/) | [Quick Start](../02-CORE-GUIDES/auto-pagination/modules/auto-pagination-02-quick-start.md) |
+| **Set up inventory sync** | [Ingestion Guide](../02-CORE-GUIDES/ingestion/) | [Data Sources](../02-CORE-GUIDES/data-sources/data-sources-readme.md) |
+| **Use SFTP (no platform needed)** | 🌟 [Data Sources Guide](../02-CORE-GUIDES/data-sources/data-sources-readme.md) | [SFTP Quick Reference](../02-CORE-GUIDES/data-sources/data-sources-quick-reference.md) |
+| **Export data from Fluent** | [Extraction Guide](../02-CORE-GUIDES/extraction/) | [ExtractionOrchestrator Summary](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) |
+| **High-level extraction (auto-pagination)** | 🌟 [ExtractionOrchestrator](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [Extraction Guide](../02-CORE-GUIDES/extraction/) |
+| **Handle webhooks** | [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Webhook Examples](../01-TEMPLATES/versori/webhooks/) |
+| **Validate webhook signatures** | [Webhook Validation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) | [Webhook Implementation](../02-CORE-GUIDES/webhook-validation/webhook-validation-readme.md) |
+| **Track job lifecycle** | [JobTracker Usage](../02-CORE-GUIDES/extraction/modules/02-core-guides-extraction-08-extraction-orchestrator.md) | [State Management](../04-REFERENCE/architecture/architecture-06-state-management.md) |
+| **Retry partial batch failures** | [Batch Recovery Patterns](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [PartialBatchRecovery API](../02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md#partialbatchrecovery-new) |
+| **Pre-validate connector config** | [PreflightValidator Guide](../04-REFERENCE/testing/testing-readme.md) | [Testing Patterns](../04-REFERENCE/testing/) |
+| **Return XML/HTML from webhook** | ⚠️ [Webhook Response Patterns](../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) | [Versori Platform](../04-REFERENCE/platforms/versori/) |
+| **Deploy on Versori** | [Versori Platform](../04-REFERENCE/platforms/versori/) | [Versori Examples](../01-TEMPLATES/versori/) |
+| **Look up API methods** | [API Reference](../02-CORE-GUIDES/api-reference/api-reference-readme.md) | [SDK Philosophy](./sdk-philosophy.md) |
+| **Transform data fields** | 🆕 [Mapper Quick Decision Guide](./mapper-quick-decision-guide.md) | [Universal Mapping](../02-CORE-GUIDES/mapping/mapping-readme.md) |
+| **Choose which mapper to use** | 🆕 [Mapper Quick Decision Guide](./mapper-quick-decision-guide.md) | [Complete Comparison](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) |
+| **Parse CSV data** | [API Reference](../02-CORE-GUIDES/api-reference/modules/api-reference-07-parsers.md) | [CSV Validation Pattern](../01-TEMPLATES/patterns/csv-schema-validation-and-rejection-report.md) |
+| **Parse XML/JSON data** | [Parser Guide](../02-CORE-GUIDES/parsers/parsers-readme.md) | [GraphQL Mutation Mapping](../02-CORE-GUIDES/mapping/graphql-mutation-mapping/) |
+| **Work with S3** | [Data Sources Guide](../02-CORE-GUIDES/data-sources/data-sources-readme.md) | [S3 Examples](../01-TEMPLATES/standalone/s3-csv-batch-api.md) |
+| **Debug issues** | [Error Handling Guide](../03-PATTERN-GUIDES/error-handling/error-handling-readme.md) | [Testing Guide](../04-REFERENCE/testing/testing-readme.md) |
+| **Prevent duplicates** | [State Management](../01-TEMPLATES/patterns/state-duplicate-prevention.md) | [Architecture](../04-REFERENCE/architecture/architecture-06-state-management.md) |
+| **Handle large files** | [Large File Splitting](../01-TEMPLATES/patterns/large-file-splitting.md) | [Pagination & Streaming](../01-TEMPLATES/patterns/pagination-streaming.md) |
+| **See complete examples** | [Use Cases Index](../01-TEMPLATES/readme.md) | [FAQ](../01-TEMPLATES/faq.md) |
+
+---
+
+## 📖 Documentation Structure
+
+**New 5-folder organization** for better AI context loading and navigation:
+
+```
+docs/
+├── readme.md (this file)
+├── template-loading-matrix.md (template selection guide)
+│
+├── 00-START-HERE/ (essential docs - read first)
+│   ├── getting-started.md (installation & setup)
+│   ├── decision-tree.md (which approach to use)
+│   ├── sdk-philosophy.md (design principles)
+│   └── troubleshooting-quick-reference.md (90% of issues)
+│
+├── 01-TEMPLATES/ (complete working examples)
+│   ├── readme.md (complete catalog with decision tree)
+│   ├── faq.md (troubleshooting guide)
+│   ├── patterns/ (9 reusable components)
+│   ├── standalone/ (9 Node.js/Deno scripts)
+│   └── versori/ (31 Versori platform examples)
+│       ├── webhooks/ (6 real-time)
+│       ├── scheduled/ (6 batch)
+│       ├── patterns/ (3 Versori-specific)
+│       └── business-examples/ (4 complex workflows)
+│
+├── 02-CORE-GUIDES/ (progressive learning paths)
+│   ├── api-reference/ (complete API docs)
+│   ├── ingestion/ (data into Fluent)
+│   ├── extraction/ (data from Fluent)
+│   ├── auto-pagination/ (7 modules - cursor pagination)
+│   ├── data-sources/ (S3, SFTP guides)
+│   ├── parsers/ (CSV, XML, JSON, Parquet)
+│   ├── webhook-validation/ (webhook security)
+│   └── mapping/ (field transformation)
+│       ├── modules/ (universal mapping)
+│       ├── resolvers/ (7 modules - custom functions)
+│       └── graphql-mutation-mapping/ (XML/JSON → GraphQL)
+│
+├── 03-PATTERN-GUIDES/ (reusable patterns)
+│   ├── error-handling/ (retry, circuit breakers)
+│   ├── file-operations/ (S3, SFTP patterns)
+│   ├── integration-patterns/ (common workflows)
+│   ├── multiple-connections/ (multi-tenant)
+│   ├── orchestrators/ (high-level workflows)
+│   ├── parquet/ (big data operations)
+│   └── [other patterns]
+│
+└── 04-REFERENCE/ (deep dives & platform docs)
+    ├── architecture/ (7 docs - system design)
+    ├── testing/ (test utilities)
+    ├── platforms/versori/ (Versori integration)
+    ├── schema/ (GraphQL schema docs)
+    └── troubleshooting/ (detailed debugging)
+```
+
+---
+
+## 🔗 External Resources
+
+- **[NPM Package](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk)** - Install the SDK
+- **[GitHub Repository](https://github.com/fluentcommerce/fc-connect-sdk)** - Source code and issues
+- **[Fluent Commerce API Docs](https://docs.fluentcommerce.com)** - Fluent Commerce platform documentation
+- **[Versori Platform](https://versori.com)** - Versori integration platform
+
+---
+
+## 📝 Contributing
+
+Found an issue or want to improve the docs? Please see the main [readme.md](../../readme.md) for contribution guidelines.
+
+**License:** MIT | **Current Version:** Latest