feat: add reference_assets to product_card_detailed

[garvitkaushik-123]

Summary

• Adds reference_assets[] to product_card_detailed for typed seller collateral (coverage maps, sample renders, environment photos, media kits)
• New schema core/product-card-reference-asset.json with closed role enum (coverage_map, sample_render, environment_photo, media_kit, logo, other) and role_label escape hatch for other
• Asset payload is a discriminated union over image-asset, video-asset, markdown-asset, url-asset — reuses canonical asset primitives without pulling in the full asset-union.json (which includes serving/tracking types inappropriate for product-card collateral)
• Docs updated in media-products.mdx with reference assets section and example

Per @bokelley's direction: nested inside product_card_detailed (Option B), not a new top-level field.

Non-breaking: all fields optional, existing consumers unaffected.

Closes #5539

Test plan

• npm run build passes (validates $ref chains)
• Pre-commit hooks pass (unit tests, type checks, dynamic imports, server unit tests)
• Changeset: minor (new optional array field)
• Verify schema renders correctly via type generation

🤖 Generated with Claude Code

[aao-release-bot]

⚠️ Argus review could not complete

The automated review encountered an issue (possibly reached max turns, timed out, or failed to post the final gh pr review). A human reviewer should take this PR.

View workflow run

_{This is an automated message from the Argus AI review workflow.}

[aao-secretariat]

Medium: The description claims role_label is "Required when role is 'other'", but the schema does not encode that — no if/then, and role_label is absent from required. A seller emitting {"role": "other"} with no label validates clean, and buyer agents get an unlabeled other slot. The stated contract and the enforced contract diverge. Encode it: "if": {"properties": {"role": {"const": "other"}}}, "then": {"required": ["role_label"]}. Otherwise soften the prose to "SHOULD provide."

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema path requires human/CODEOWNERS review.

This PR is additive: it adds an optional reference_assets array to product_card_detailed and introduces a new core/product-card-reference-asset.json schema for typed seller collateral. The changeset is present and correctly minor; schema↔docs are coherent (roles table matches the enum, example matches the field shape); the asset oneOf is discriminated via asset_type const on all four referenced asset schemas, so the oneOf audit does not regress; no released dist/** artifact is touched.

There is one Medium finding (below), but that is not the blocker. The blocker is the hard approval gate: this PR modifies static/schemas/source/** (gated_paths: true) and review_decision is REVIEW_REQUIRED, not APPROVED. Per decision-table row 2, the outcome must be escalate — human/CODEOWNERS review of the schema change is required before merge.

Medium findings

• static/schemas/source/core/product-card-reference-asset.json:22 — role_label is documented as required-when-other but that conditional is not encoded in the schema.

Escalation reasons

• Touches gated path static/schemas/source/core/product-card-reference-asset.json and static/schemas/source/core/product.json; review_decision is REVIEW_REQUIRED, so a human/CODEOWNERS approval is required before this can merge.

Medium findings

• static/schemas/source/core/product-card-reference-asset.json:22 — role_label 'required when other' is stated but not encoded

Why human review

• Gated path: static/schemas/source/core/product-card-reference-asset.json (added) and static/schemas/source/core/product.json (modified) are under a hard approval gate; review_decision is REVIEW_REQUIRED (not APPROVED), so human/CODEOWNERS review is required before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/product-card-reference-asset.json (added) matches static/schemas/source/**; static/schemas/source/core/product.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'REVIEW_REQUIRED', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.

[aao-secretariat]

Ladon verdict: Escalate to human review

Escalate — gated schema paths require human/CODEOWNERS approval.

This PR adds static/schemas/source/core/product-card-reference-asset.json and modifies static/schemas/source/core/product.json, both under a hard, non-overridable approval gate (static/schemas/source/**). gated_paths is true and review_decision is not APPROVED (unknown/none), so Row 2 of the decision table forces escalation regardless of how clean the diff is.

Iteration credit: The prior run's single medium finding — role_label 'required when other' stated but not encoded (product-card-reference-asset.json:22) — has been resolved. The delta adds an allOf/if/then that encodes the constraint: the if branch requires role and matches const other (so an absent role is fail-safe and does not trigger), and the then branch requires role_label. The reviewer surfaced no new findings in this pass. This is a net improvement over the prior review.

There are no critical/high/medium findings blocking on the merits — the only barrier is the deterministic approval gate. Once a human/CODEOWNERS approval is recorded (review_decision: APPROVED), this can proceed normally.

Escalation reasons:

• static/schemas/source/core/product-card-reference-asset.json (added) and static/schemas/source/core/product.json (modified) are under a hard approval gate (static/schemas/source/**); review_decision is not APPROVED, so human/CODEOWNERS review is required before merge.

Why human review

• Gated path: static/schemas/source/core/product-card-reference-asset.json (added) and static/schemas/source/core/product.json (modified) are under a hard approval gate (static/schemas/source/**); review_decision is not APPROVED, so human/CODEOWNERS review is required before merge.
• This PR touches a path under a hard, non-overridable approval gate (static/schemas/source/core/product-card-reference-asset.json (added) matches static/schemas/source/**; static/schemas/source/core/product.json (modified) matches static/schemas/source/**) and the current GitHub review decision is 'unknown', not APPROVED. This is a hard gate enforced in code — Ladon cannot auto-approve until a human/CODEOWNERS approval is recorded, regardless of how clean the diff is.