# 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)