# Decision Record: V2 Gift Runtime Feed

Date: 2026-05-04
Change ID: DEC-20260504-01
Branch: main

## Decision

The canonical gift system is the v2 pipeline.

Canonical source inputs:

- `data/dog-gifts-base.json`
- `data/gift-batches/*.json`
- `data/dog-gifts-preferred.json`

Canonical generated outputs:

- `data/dog-gifts-catalog.json`
- `data/dog-gifts-merged.json`

The canonical runtime gift feed path is `data/dog-gifts-merged.json`. GitHub Pages publishes that same repo path at `https://candidquality.github.io/Barkday/data/dog-gifts-merged.json`. There is no separate promote step in the current workflow; rebuilding and committing the merged output lets the normal Pages deployment publish the updated feed.

Root-level `dog-gifts.json` and `dog-gifts.schema.json` are legacy compatibility artifacts only. New product work should not be added to that path unless a temporary compatibility export is explicitly needed.

Raw Amazon files under `data/raw-amazon/` are evidence and import material only, not runtime feeds.

## Update Workflow

1. Edit only v2 source inputs: base, batch, or preferred overlay files.
2. Run `.\tools\run-barkday-checks.ps1`.
3. Inspect the source and generated output diffs.
4. If runtime behavior changed, verify gift loading locally.
5. Commit the source changes and regenerated v2 outputs together.

The helper rebuilds `data/dog-gifts-catalog.json`, validates v2 catalog/preferred data, merges `data/dog-gifts-merged.json`, runs gift smoke checks, and runs `node .\scripts\barkday-doctor.mjs`.

## Guardrail

`node .\scripts\barkday-doctor.mjs` reports the canonical local feed path, the published Pages feed URL, the expected 182-item launch catalog size, and the deprecated status of the root legacy gift files.