@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/00-START-HERE/cli-documentation-index.md

@@ -1,202 +1,202 @@
-# CLI Tools - Documentation Index
-
-Complete guide to all command-line tools included in the Fluent Connect SDK.
-
----
-
-## 📋 Quick Links
-
-| Document | Purpose | When to Use |
-|----------|---------|-------------|
-| [CLI User Guide](./cli-analyze-source-structure-guide.md) | Complete guide with workflows | First time users, learning |
-| [Quick Reference Card](./cli-quick-reference.md) | Command cheat sheet | Daily usage, quick lookup |
-| [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) | All CLI tools + options | Developers, advanced usage |
-
----
-
-## 🎯 analyze-source-structure Tool
-
-**Purpose:** Analyze XML/JSON/CSV/Parquet files and generate mapping templates
-
-### Getting Started
-
-**5-Minute Quick Start:**
-```bash
-# 1. Analyze your file
-npx fc-connect analyze-source-structure --file ./data.xml
-
-# 2. Generate template + docs
-npx fc-connect analyze-source-structure \
-  --file ./data.xml \
-  --output ./mapping.json \
-  --markdown
-```
-
-### Documentation
-
-#### [Complete User Guide](./cli-analyze-source-structure-guide.md)
-
-**Read this if you:**
-- Are using the tool for the first time
-- Want to understand common workflows
-- Need troubleshooting help
-- Want to see real-world examples
-
-**What's inside:**
-- What is this tool and why use it?
-- Getting started tutorial
-- Quick start examples
-- Common workflows (new integration, CSV migration, debugging, team collaboration)
-- Understanding the output
-- Best practices
-- Advanced usage
-- Troubleshooting guide
-- FAQ
-
-**Length:** ~20 minutes to read
-
----
-
-#### [Quick Reference Card](./cli-quick-reference.md)
-
-**Read this if you:**
-- Already know the basics
-- Need a quick command reminder
-- Want to copy-paste examples
-- Need resolver suggestions reference
-
-**What's inside:**
-- Basic commands
-- All command options
-- Common workflows (one-liners)
-- Output symbols explained
-- Smart resolver detection table
-- Mapper types comparison
-- Tips and troubleshooting
-
-**Length:** ~2 minutes to scan
-
----
-
-#### [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
-
-**Read this if you:**
-- Need complete option documentation
-- Want to see all CLI tools
-- Are a developer extending the SDK
-- Need technical implementation details
-
-**What's inside:**
-- All CLI tools in the SDK
-- Complete option reference
-- Technical notes and implementation details
-- Example outputs
-- Test coverage information
-
-**Length:** ~10 minutes for relevant sections
-
----
-
-## 📚 Related Documentation
-
-### Mapping Guides
-- [Mapper Comparison Guide](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) - UniversalMapper vs GraphQLMutationMapper
-- [Mapping Modules](../02-CORE-GUIDES/mapping/modules/) - Field mapping patterns and resolvers
-
-### Templates
-- [Templates Directory](../01-TEMPLATES/) - Complete integration examples
-- [Ingestion Templates](../01-TEMPLATES/versori/workflows/ingestion/) - XML/JSON → Fluent
-- [Extraction Templates](../01-TEMPLATES/versori/workflows/extraction/) - Fluent → CSV/Files
-
-### API References
-- [CLI Tools Module](../02-CORE-GUIDES/api-reference/modules/api-reference-11-cli-tools.md) - Technical API docs
-- [Services Module](../02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md) - SDK services used by CLI
-
----
-
-## 🎓 Learning Path
-
-### New to the SDK?
-1. Start with [CLI User Guide](./cli-analyze-source-structure-guide.md) - Example 1
-2. Try analyzing your own data file
-3. Review the [Quick Reference](./cli-quick-reference.md) for daily use
-4. Explore [Templates](../01-TEMPLATES/) for complete examples
-
-### Already familiar with the SDK?
-1. Keep the [Quick Reference](./cli-quick-reference.md) handy
-2. Use the [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for advanced options
-3. Check [Mapper Comparison](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) when choosing mappers
-
-### Need Help?
-1. Check the [FAQ](./cli-analyze-source-structure-guide.md#faq)
-2. Review [Troubleshooting](./cli-analyze-source-structure-guide.md#troubleshooting)
-3. See [Troubleshooting Quick Reference](./troubleshooting-quick-reference.md) for common issues
-
----
-
-## 🔧 Other CLI Tools
-
-The SDK includes additional CLI tools beyond `analyze-source-structure`:
-
-| Tool | Purpose |
-|------|---------|
-| `introspect-schema` | Download Fluent GraphQL schema |
-| `generate-mutation-mapping` | Build ingestion mapping templates |
-| `generate-query-mapping` | Build extraction mapping templates |
-| `validate-schema` | Validate mapping config against schema |
-| `analyze-coverage` | Report field coverage statistics |
-
-See [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for complete documentation of all tools.
-
----
-
-## 🚀 Pro Tips
-
-**Tip 1: Generate docs for every integration**
-```bash
-npx fc-connect analyze-source-structure \
-  --file ./vendor-data.xml \
-  --markdown ./docs/vendor-integration.md
-```
-Future you (and your team) will thank you!
-
-**Tip 2: Keep a quick reference handy**
-Bookmark the [Quick Reference Card](./cli-quick-reference.md) for daily work.
-
-**Tip 3: Use the right mapper**
-Not sure? See the [Mapper Comparison Guide](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md).
-
-**Tip 4: Start with templates**
-Check [Templates Directory](../01-TEMPLATES/) for ready-made solutions.
-
-**Tip 5: Version control your mappings**
-```bash
-git add ./config/mapping.json ./docs/analysis.md
-git commit -m "docs: add vendor data mapping"
-```
-
----
-
-## 📖 Documentation Versions
-
-This documentation is for **SDK version 0.1.41+**
-
-Major changes by version:
-- **v0.1.41**: Fixed GraphQLMutationMapper API consistency (mapWithNodes now returns query)
-- **v0.1.40**: Documentation standardization and code quality improvements
-- **v0.1.31**: Added markdown documentation generation, smart resolver suggestions, 112 unit tests
-- **v0.1.30**: Initial CLI tool release with basic analysis
-
----
-
-## 🤝 Contributing
-
-Found an issue or want to improve the docs?
-- Report issues: [GitHub Issues](https://github.com/fluentcommerce/fc-connect-sdk/issues)
-- Suggest improvements: Submit a pull request
-- Ask questions: See support resources in main README
-
----
-
-**Last Updated:** 2025-11-13
-**SDK Version:** 0.1.41+
+# CLI Tools - Documentation Index
+
+Complete guide to all command-line tools included in the Fluent Connect SDK.
+
+---
+
+## 📋 Quick Links
+
+| Document | Purpose | When to Use |
+|----------|---------|-------------|
+| [CLI User Guide](./cli-analyze-source-structure-guide.md) | Complete guide with workflows | First time users, learning |
+| [Quick Reference Card](./cli-quick-reference.md) | Command cheat sheet | Daily usage, quick lookup |
+| [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) | All CLI tools + options | Developers, advanced usage |
+
+---
+
+## 🎯 analyze-source-structure Tool
+
+**Purpose:** Analyze XML/JSON/CSV/Parquet files and generate mapping templates
+
+### Getting Started
+
+**5-Minute Quick Start:**
+```bash
+# 1. Analyze your file
+npx fc-connect analyze-source-structure --file ./data.xml
+
+# 2. Generate template + docs
+npx fc-connect analyze-source-structure \
+  --file ./data.xml \
+  --output ./mapping.json \
+  --markdown
+```
+
+### Documentation
+
+#### [Complete User Guide](./cli-analyze-source-structure-guide.md)
+
+**Read this if you:**
+- Are using the tool for the first time
+- Want to understand common workflows
+- Need troubleshooting help
+- Want to see real-world examples
+
+**What's inside:**
+- What is this tool and why use it?
+- Getting started tutorial
+- Quick start examples
+- Common workflows (new integration, CSV migration, debugging, team collaboration)
+- Understanding the output
+- Best practices
+- Advanced usage
+- Troubleshooting guide
+- FAQ
+
+**Length:** ~20 minutes to read
+
+---
+
+#### [Quick Reference Card](./cli-quick-reference.md)
+
+**Read this if you:**
+- Already know the basics
+- Need a quick command reminder
+- Want to copy-paste examples
+- Need resolver suggestions reference
+
+**What's inside:**
+- Basic commands
+- All command options
+- Common workflows (one-liners)
+- Output symbols explained
+- Smart resolver detection table
+- Mapper types comparison
+- Tips and troubleshooting
+
+**Length:** ~2 minutes to scan
+
+---
+
+#### [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md)
+
+**Read this if you:**
+- Need complete option documentation
+- Want to see all CLI tools
+- Are a developer extending the SDK
+- Need technical implementation details
+
+**What's inside:**
+- All CLI tools in the SDK
+- Complete option reference
+- Technical notes and implementation details
+- Example outputs
+- Test coverage information
+
+**Length:** ~10 minutes for relevant sections
+
+---
+
+## 📚 Related Documentation
+
+### Mapping Guides
+- [Mapper Comparison Guide](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) - UniversalMapper vs GraphQLMutationMapper
+- [Mapping Modules](../02-CORE-GUIDES/mapping/modules/) - Field mapping patterns and resolvers
+
+### Templates
+- [Templates Directory](../01-TEMPLATES/) - Complete integration examples
+- [Ingestion Templates](../01-TEMPLATES/versori/workflows/ingestion/) - XML/JSON → Fluent
+- [Extraction Templates](../01-TEMPLATES/versori/workflows/extraction/) - Fluent → CSV/Files
+
+### API References
+- [CLI Tools Module](../02-CORE-GUIDES/api-reference/modules/api-reference-11-cli-tools.md) - Technical API docs
+- [Services Module](../02-CORE-GUIDES/api-reference/modules/api-reference-05-services.md) - SDK services used by CLI
+
+---
+
+## 🎓 Learning Path
+
+### New to the SDK?
+1. Start with [CLI User Guide](./cli-analyze-source-structure-guide.md) - Example 1
+2. Try analyzing your own data file
+3. Review the [Quick Reference](./cli-quick-reference.md) for daily use
+4. Explore [Templates](../01-TEMPLATES/) for complete examples
+
+### Already familiar with the SDK?
+1. Keep the [Quick Reference](./cli-quick-reference.md) handy
+2. Use the [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for advanced options
+3. Check [Mapper Comparison](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md) when choosing mappers
+
+### Need Help?
+1. Check the [FAQ](./cli-analyze-source-structure-guide.md#faq)
+2. Review [Troubleshooting](./cli-analyze-source-structure-guide.md#troubleshooting)
+3. See [Troubleshooting Quick Reference](./troubleshooting-quick-reference.md) for common issues
+
+---
+
+## 🔧 Other CLI Tools
+
+The SDK includes additional CLI tools beyond `analyze-source-structure`:
+
+| Tool | Purpose |
+|------|---------|
+| `introspect-schema` | Download Fluent GraphQL schema |
+| `generate-mutation-mapping` | Build ingestion mapping templates |
+| `generate-query-mapping` | Build extraction mapping templates |
+| `validate-schema` | Validate mapping config against schema |
+| `analyze-coverage` | Report field coverage statistics |
+
+See [Technical Reference](../02-CORE-GUIDES/advanced-services/advanced-services-readme.md) for complete documentation of all tools.
+
+---
+
+## 🚀 Pro Tips
+
+**Tip 1: Generate docs for every integration**
+```bash
+npx fc-connect analyze-source-structure \
+  --file ./vendor-data.xml \
+  --markdown ./docs/vendor-integration.md
+```
+Future you (and your team) will thank you!
+
+**Tip 2: Keep a quick reference handy**
+Bookmark the [Quick Reference Card](./cli-quick-reference.md) for daily work.
+
+**Tip 3: Use the right mapper**
+Not sure? See the [Mapper Comparison Guide](../02-CORE-GUIDES/mapping/mapping-mapper-comparison-guide.md).
+
+**Tip 4: Start with templates**
+Check [Templates Directory](../01-TEMPLATES/) for ready-made solutions.
+
+**Tip 5: Version control your mappings**
+```bash
+git add ./config/mapping.json ./docs/analysis.md
+git commit -m "docs: add vendor data mapping"
+```
+
+---
+
+## 📖 Documentation Versions
+
+This documentation is for **SDK version 0.1.41+**
+
+Major changes by version:
+- **v0.1.41**: Fixed GraphQLMutationMapper API consistency (mapWithNodes now returns query)
+- **v0.1.40**: Documentation standardization and code quality improvements
+- **v0.1.31**: Added markdown documentation generation, smart resolver suggestions, 112 unit tests
+- **v0.1.30**: Initial CLI tool release with basic analysis
+
+---
+
+## 🤝 Contributing
+
+Found an issue or want to improve the docs?
+- Report issues: [GitHub Issues](https://github.com/fluentcommerce/fc-connect-sdk/issues)
+- Suggest improvements: Submit a pull request
+- Ask questions: See support resources in main README
+
+---
+
+**Last Updated:** 2025-11-13
+**SDK Version:** 0.1.41+