Add read-only merch readiness reporter

[WalksWithASwagger]

Type

tech-debt

Priority

P3 low — useful after commerce truth is settled, not urgent before that.

Summary

Create a local report that compares catalog products, Shopify config flags, env key names, docs, and expected readiness state without touching Shopify.

Why This Matters

The current commerce drift would have been easier to catch with a source-of-truth report.

Evidence

Fact:

• src/shop-data.js contains product IDs, status, shopify.enabled, and env key names.
• .env.example lists product env vars.
• merch/shopify-launch.md documents staged product launch rules.
• The roadmap research identified “Merch Readiness Reporter” as a power-user feature.

Scope

In scope:

• Static local checks against repo files.
• Print mismatches and missing docs/env keys.
• Optional JSON output.

Out of scope:

• Reading secret env var values.
• Shopify API calls.
• Product creation.
• Vercel env mutations.

Proposed Approach

Add a Node script that imports src/shop-data.js, parses .env.example, and verifies each Shopify-wired product has matching docs/env references.

Acceptance Criteria

• Script reports product count by live, candidate, concept.
• Script reports Shopify-wired products and env key coverage.
• Script flags docs/env/catalog mismatches.
• Script is documented.
• npm run build passes.
• npm run lint passes.
• No secrets are printed.

Tests Required

• Manual test: run script on current repo and confirm output is sensible.
• Regression test: optionally include a fixture or dry-run mode for known mismatch.

Evals Required

Evals required: none, because this issue does not affect AI/agent behavior.

Definition of Done

A future agent can detect merch catalog drift before making commerce changes.

PR Readiness Gate

Before this issue can become a PR, the implementing agent must provide:

• Sample output
• Files changed
• Tests run
• Known limitations

Dependencies

Commerce truth issue should land first.

Risks

False confidence if report implies Shopify admin truth. Keep it explicitly repo-only.

Agent Suitability

Safe for agent after commerce truth is resolved.

Suggested PR Title

Add repo-only merch readiness reporter

Suggested PR Body

Summary

Adds a local report for merch/catalog readiness.

Why

Prevents future drift between catalog, docs, and env references.

Changes

Adds read-only script and docs.

Tests

Run report, build, lint.

Evals

None.

Risks

Repo-only report does not prove Shopify admin state.

Follow-up

Optional production health script can consume its expected count.