docs: Update documentation for controller PR #1723

[tarrencev]

This PR updates the documentation to reflect changes made in cartridge-gg/controller#1723

**Original PR Details:**
- Title: feat: add listing action from collection pages
- Files changed: examples/next/src/components/Profile.tsx

packages/keychain/src/components/connect/create/useCreateController.ts
packages/keychain/src/utils/controller.ts
packages/profile/package.json
packages/profile/src/components/achievements/index.tsx
packages/profile/src/components/app.tsx
packages/profile/src/components/inventory/collection/collectible-asset.tsx
packages/profile/src/components/inventory/collection/collectible.tsx
packages/profile/src/components/inventory/collection/collection-asset.tsx
packages/profile/src/components/inventory/collection/collection-listing.tsx
packages/profile/src/components/inventory/collection/collection-purchase.tsx
packages/profile/src/components/inventory/collection/collection.tsx
packages/profile/src/components/inventory/collection/collections.tsx
packages/profile/src/components/inventory/collection/header.tsx
packages/profile/src/components/inventory/collection/index.ts
packages/profile/src/components/inventory/collection/send/collection.tsx
packages/profile/src/components/inventory/collection/send/header.tsx
packages/profile/src/components/inventory/index.tsx
packages/profile/src/components/provider/data.tsx
packages/profile/src/components/provider/index.tsx
packages/profile/src/components/provider/marketplace.tsx
packages/profile/src/context/marketplace.ts
packages/profile/src/hooks/collection.ts
packages/profile/src/hooks/entrypoints.ts
packages/profile/src/hooks/marketplace.ts
packages/profile/src/hooks/token.ts
packages/profile/src/hooks/traceabilities.ts
pnpm-lock.yaml
pnpm-workspace.yaml

Please review the documentation changes to ensure they accurately reflect the controller updates.

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
docs	✅ Ready (Inspect)	Visit Preview	Jun 25, 2025 3:05pm

[claude]

Claude finished @tarrencev's task —— View job

---

PR Review Complete ✅

Review Tasks

• Read and analyze inventory.md changes
• Review new marketplace.md documentation
• Check vocs.config.ts navigation updates
• Assess documentation quality and completeness
• Provide comprehensive feedback

---

📋 Review Summary

This PR adds comprehensive marketplace documentation to reflect the new NFT listing functionality from controller PR #1723. The documentation is well-structured and thorough, but there are several areas for improvement.

✅ Strengths

Documentation Quality:

• Excellent comprehensive coverage of marketplace features
• Well-organized structure with logical progression from listing → purchasing → management
• Good balance of high-level concepts and detailed implementation
• Includes troubleshooting section and best practices

Technical Accuracy:

• API usage is consistent with existing patterns (openProfile usage matches achievements:integration.md:42)
• TypeScript examples are properly typed
• Configuration examples align with existing Controller setup patterns

User Experience:

• Clear step-by-step instructions for both sellers and buyers
• Good visual hierarchy with proper markdown formatting
• Seamless integration with existing inventory documentation
• Proper cross-referencing between inventory and marketplace docs

⚠️ Issues & Improvements

1. API Consistency Questions

marketplace.md:159 - The import path seems incomplete:

import { useMarketplace } from "@cartridge/marketplace";

Recommendation: Verify this import path exists. Should it be @cartridge/controller or a different package?

2. Code Example Inconsistency

marketplace.md:149-151 - The openProfile signature with options:

controller.openProfile("inventory", {
  contractAddress: "0x1234...",
});

Issue: This extended signature isn't documented elsewhere and may not exist.
Recommendation: Either document this API or remove the example if it's not implemented.

3. Technical Specification Gaps

Fee Structure Details:

• The fee percentages (1.0% marketplace, 1.0% royalty) in the example may not be accurate
• No mention of how fees are determined or if they're configurable

Contract Integration:

• Missing information about which smart contracts handle marketplace operations
• No mention of required contract approvals or gas considerations

4. Documentation Structure

marketplace.md length: At 313 lines, this is quite comprehensive but might benefit from being split into multiple focused pages:

• Basic marketplace usage
• Advanced features and configuration
• API reference and troubleshooting

5. Missing Examples

Real-world Integration:

• No concrete examples linking to actual implementations (unlike achievements which references DopeWars)
• Could benefit from a working example repository or code sandbox

6. Configuration Verification

Token Contracts (marketplace.md:208-209):

"erc20:0x049d36570d4e46f48e99674bd3fcc84644ddd6b96f7c741b1562b82f9e004dc7", # ETH
"erc20:0x04718f5a0fc34cc1af16a1cdee98ffb20c31f5cd61d6ab07201858f4287c938d", # STRK

Recommendation: Verify these contract addresses are correct for the intended network.

🔧 Minor Issues

1. inventory.md:83 - Link formatting should be consistent: /controller/marketplace vs other internal links
2. marketplace.md:100 - ERC-2981 standard mentioned but not linked to specification
3. marketplace.md:280-311 - API reference types should be verified against actual implementation

🎯 Recommendations

High Priority

1. Verify API imports and signatures - Ensure all code examples work with actual controller implementation
2. Validate contract addresses - Confirm token contract addresses are correct
3. Test documentation flow - Walk through the entire marketplace flow to ensure accuracy

Medium Priority

1. Add real-world examples - Include links to actual implementations
2. Consider documentation split - Break down the large marketplace.md file
3. Add gas estimation guidance - Include typical gas costs for marketplace operations

Low Priority

1. Enhanced troubleshooting - Add more specific error scenarios
2. Performance considerations - Document bulk operation limits
3. Mobile UX notes - Add any mobile-specific marketplace considerations

📊 Overall Assessment

Quality Score: 8/10

• Comprehensive coverage ✅
• Good user experience ✅
• Technical accuracy needs verification ⚠️
• Could benefit from splitting and more examples 💡

The documentation successfully covers the marketplace functionality and provides a solid foundation for users. The main concerns are around verifying technical accuracy and ensuring all code examples work with the actual implementation.

---