docs(25): capture phase context

.planning/phases/25-catalog-enrichment-agent-tools/25-DISCUSSION-LOG.md

@@ -0,0 +1,98 @@
+# 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)