3.9 KiB
Phase 25: Catalog Enrichment & Agent Tools - Discussion Log
Audit trail only. Do not use as input to planning, research, or execution agents. Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
Date: 2026-04-10 Phase: 25-catalog-enrichment-agent-tools Areas discussed: Attribution data model, Uniqueness constraint design, Bulk import API design, MCP tool scope Mode: --batch --auto (all decisions auto-selected)
Attribution Data Model
| Option | Description | Selected |
|---|---|---|
| manufacturer is alias for brand | No new column — existing brand field serves as manufacturer |
✓ |
| Separate manufacturer column | Add manufacturer alongside brand for cases where they differ |
User's choice: [auto] manufacturer is alias for brand (recommended default)
Notes: The brand field already captures manufacturer identity. Adding a separate column would create confusion about which to use. Three new columns added: sourceUrl, imageCredit, imageSourceUrl.
| Option | Description | Selected |
|---|---|---|
| Inline below image | Show attribution directly below the product image | ✓ |
| Collapsible section | Hide attribution in an expandable panel | |
| Footer area | Show attribution at bottom of detail page |
User's choice: [auto] Inline below image (recommended default) Notes: Transparency is a project value — attribution should be visible, not hidden.
Uniqueness Constraint Design
| Option | Description | Selected |
|---|---|---|
| Unique on (brand, model) only | Category is classification, not identity | ✓ |
| Unique on (brand, model, category) | Allow same product in different categories |
User's choice: [auto] Unique on (brand, model) only (recommended default) Notes: A physical product is one thing regardless of how it's categorized. Prevents duplicates when agents might categorize differently.
Bulk Import API Design
| Option | Description | Selected |
|---|---|---|
| API key auth (existing) | Same auth as other write endpoints | ✓ |
| Special admin token | Separate credential for bulk operations |
User's choice: [auto] API key auth (recommended default) Notes: No admin role system exists. API key is sufficient for single-admin setup.
| Option | Description | Selected |
|---|---|---|
| All-or-nothing transaction | Reject entire batch on any validation failure | ✓ |
| Partial success | Import valid items, skip invalid ones |
User's choice: [auto] All-or-nothing transaction (recommended default) Notes: Upsert handles conflicts. Validation failures are data quality issues — better to fix and retry than have partial imports.
| Option | Description | Selected |
|---|---|---|
| 100 items per request | Reasonable batch for agents | ✓ |
| 50 items per request | Conservative limit | |
| 500 items per request | Large batch for bulk seeding |
User's choice: [auto] 100 items per request (recommended default)
MCP Tool Scope
| Option | Description | Selected |
|---|---|---|
| Standard auth (API key/OAuth) | Same as existing MCP tools | ✓ |
| Unauthenticated catalog writes | Allow any MCP client to write catalog |
User's choice: [auto] Standard auth (recommended default) Notes: Catalog tools follow the same auth pattern as all other MCP tools.
Claude's Discretion
- Drizzle migration approach for new columns and unique constraint
- Zod validation schemas for bulk import payload
- MCP tool descriptions and parameter documentation
- Tag handling in upsert (create-if-not-exists vs require existing)
- Response shape for bulk import
Deferred Ideas
- SEED-04: actual seeding run (future requirement)
- Admin role for catalog management
- Catalog item edit UI (web editor)