# JV Shopify Content Population ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Master Plan

> **Goal:** the `jv-dashboard` becomes the central content production workspace for the Just Vitamins Shopify migration. All metaobject + product content is generated, reviewed, approved here, then exported as Matrixify CSVs and shipped to Lewis (Kubix) for import. Nothing goes direct-to-Shopify.

## Continuation checkpoint - 20 May 2026

Current continuation status:
- DataForSEO has been re-checked with the real credentials loaded from `C:\Users\uldvs\OneDrive\Desktop\work\pi-fresh-foundation\.env`; `bun run dataforseo:live-asin-evidence` confirms the account with `20000 Ok`, keeps `credentialPrinted=false`, rebuilds the ASIN evidence from saved live Product Search results, and leaves the paid Reviews pilot blocked until provider endpoint/support/spend gates are cleared.
- A dated daily handoff snapshot is now available with `bun run handoff:daily-status`; it writes `daily_status_<current Malaysia date>.md/csv/json`, summarizes the live blockers, and repeats the no-fake-approval/no-fake-claim/no-guessed-credential guardrails.
- A strict completion evidence dossier is available with `bun run handoff:evidence-dossier`; it writes `handoff_evidence_dossier.md/csv/json` and ties each master-plan requirement area to the current evidence file, proof, and remaining blocker before anyone can claim the goal is complete.
- A reviewer decision workbook is available with `bun run handoff:reviewer-workbook`; it writes `reviewer_decision_workbook.md/csv/json` plus `reviewer_completion_commands.csv` so compliance, Umar/JV, Lewis/Euan, and the provider-spend owner have exact editable files, required fields, commands, and guardrails.
- The one-command handoff refresh has been expanded: `bun run refresh:packet` now regenerates the source-acquisition control packet, compliance/approval gates, reviewer workbook, reviewer input preflight, delivery indexes, verifier, evidence dossier, daily status, artifact freshness validation, and final delivery index while distinguishing expected blockers from actual refresh failures, so daily status reflects the latest verifier output and packet completeness is checked against current-run freshness.
- A reviewer input preflight is now available with `bun run handoff:reviewer-preflight`; it writes `reviewer_input_preflight.md/csv/json` and validates the human-editable compliance, product-approval, DataForSEO provider/spend, and staging evidence files before the heavier gates are rerun.
- Owner handoff messages are now available with `bun run handoff:owner-messages`; it writes `owner_handoff_messages.md/csv/json` with copy-paste asks for compliance, product approval, Lewis/Euan staging, and DataForSEO provider/spend owners while preserving the no-fake-approval/no-paid-retry guardrails.
- Owner response intake is now available with `bun run handoff:owner-responses`; it writes `owner_response_intake.md/csv/json` and creates the editable `data/handoff/owner-response-intake.json` tracker so replies/evidence updates can be recorded before rerunning the authoritative gates.
- A verifier gate dependency map is now available with `bun run handoff:gate-map`; it writes `handoff_gate_dependency_map.md/csv/json` plus `handoff_gate_dependency_by_owner.csv` so each blocked master verifier gate is tied to the exact owner input, evidence blocker, and rerun command.
- Staging evidence intake is now available with `bun run staging:intake`; it writes `staging_evidence_intake.md/csv/json`, initializes `data/staging/cutover-approval.json` as a pending editable tracker, and adds README instructions for real import-log/PDP-check folders without creating fake staging evidence.
- A post-owner response rerun plan is now available with `bun run handoff:post-response-rerun`; it writes `post_owner_response_rerun_plan.md/csv/json` and holds lane command sequences until `owner-response-intake.json` records usable owner evidence, preventing blind reruns from being mistaken for approvals.
- An owner evidence acceptance guide is now available with `bun run handoff:evidence-guide`; it writes `owner_evidence_acceptance_guide.md/csv/json` and defines the valid fields, valid/invalid examples, guardrails, and validators for every owner-editable evidence file.
- Export Console and `/api/export/status` now expose the latest `dailyStatus` artifact beside the blocker burn-down, so the current operating status is discovered from the newest `daily_status_*.json` file instead of a hardcoded date.
- This checkpoint does **not** mark the handoff complete: the goal remains blocked by 185 compliance blank/source-backed claim decisions, 190 product approvals, staging import logs, PDP spot checks, cutover approval, and DataForSEO Reviews endpoint availability.

## Implementation checkpoint - 19 May 2026

Current dashboard build status:
- Content workspace is now in place for the full known catalogue: 190 product-content records under `data/content/products/` and 190 workflow records under `data/content/workflow/`.
- Pilot content exists for `JV-D1000`, `JV-D4000`, and `JV-TURMERIC500`; the remaining 187 catalogue records are intentionally marked `pending_intelligence`.
- New dashboard surfaces are wired: Product Content Editor, Metaobject Editor, Approval Queue, Compliance Trail, Image Pipeline, Export Console, and the new market-intelligence views.
- Source Readiness is wired to show whether Feefo, competitor PDPs, Amazon, Trustpilot, Reddit, and clinical claims inputs are actually present before generated content is treated as handoff-ready.
- Matrixify preview/export tooling exists in both the dashboard and migration folder:
  - dashboard: `bun run export:content`
  - migration handoff: `py build_metaobjects_csv.py`, `py build_products_csv_v5.py`, `py build_smart_collections_csv.py`, `py validate_assets_manifest.py`
- Dashboard export now writes a handoff pack alongside the preview CSVs:
  - `content_population_exports/handoff_manifest.json`
  - `content_population_exports/handoff_summary.md`
  - `content_population_exports/export_blockers.csv`
- External blocker work orders can now be generated with `bun run source:pack`:
  - `content_population_exports/source_request_items.csv` (raw evidence/source drops needed by lane)
  - `content_population_exports/clinical_claims_request.csv` (VoC themes that require clinical/regulatory evidence before use in `clinically_shown_to`)
  - `content_population_exports/image_production_brief.csv` (570 PDP image production rows)
  - `content_population_exports/source_request_pack.md` and `source_request_manifest.json`
- Template schema validation is now available with `bun run validate:template`, comparing dashboard + migration CSV headers against `C:\Users\uldvs\Downloads\Just Vitamins - Content Population Templates (1).xlsx`.
- Collection promo-card candidates can now be seeded with `bun run seed:promo-cards`; it selects review-backed draft testimonials from existing Feefo raw reviews and maps the current Vitamin D and Joint Care smart collections to draft `promo_card.*` metaobjects for human review.
- Claims-library validation/template lane is available with `bun run validate:claims`; it emits `claims_library_template.json`, `claims_library_validation.json`, and `claims_library_validation.csv` so regulatory/compliance can fill `data/sources/claims/claims-library.json` in the required source-backed shape.
- Raw Amazon/Trustpilot/Reddit drop validation is available with `bun run validate:sources`; it creates JSON templates under `data/sources/_templates/` and writes `source_drop_validation.json/csv` so incoming source files can be checked before extraction.
- Deterministic PDP image filenames can now be assigned with `bun run assign:image-filenames`; planned filenames are exported to `planned_image_filenames.json/csv`, and export readiness now treats missing local/Shopify Files uploads as `asset_upload` blockers rather than only checking whether a filename exists. Metaobject SVG assets can now be generated repeatably with `bun run assets:metaobject-svgs`; this writes the 16 required metaobject icon/ingredient SVG files into `C:\Users\uldvs\OneDrive\Desktop\jv-assets` and records `metaobject_svg_asset_generation.json/csv`. Draft PDP PNG assets can now be generated repeatably with `bun run assets:draft-pdp`; this writes 570 review-marked draft PDP assets into the same asset root and records `draft_pdp_asset_generation.json/csv` while keeping image approval blocked until human review.
- Consolidated readiness audit is available with `bun run audit:content`; it writes `content_population_readiness.json/csv/md` and fails until every gate in this plan is actually satisfied.
- Export Console now surfaces the consolidated readiness audit and intelligence-generation workqueue from `/api/export/status`, so Lewis/Euan handoff readiness is not hidden behind only product-level blockers.
- Owner-facing handoff action plan is available with `bun run handoff:actions`; it writes `handoff_action_plan.md/csv/json` and now separates completed/covered lanes from active blockers: 6 accountable lanes total, currently 0 active P0, 1 active P1, 1 active P2, 3 Done/covered, and 1 Watch. Executive decision brief is available with `bun run handoff:decision-brief`; it writes `executive_decision_brief.md/json`, `executive_decision_brief_decisions.csv`, and `executive_decision_brief_readiness.csv` to assign the remaining compliance, approval, staging, and source-provider decisions without claiming them complete. Blocker burn-down is available with `bun run handoff:burndown`; it writes `blocker_burndown.md/json/csv` and `blocker_burndown_next_actions.csv` to track remaining evidence counts by lane. Export Console displays those actions and decisions from `/api/export/status`.
- Staging import checklist is available with `bun run staging:checklist`; it writes `staging_import_checklist.md/csv/json` and separates preflight evidence from Lewis/Euan Matrixify import/PDP spot-check evidence. Lewis/Euan staging handoff packet is available with `bun run staging:handoff-packet`; it writes `staging_handoff_packet.md/json`, `staging_handoff_import_files.csv`, `staging_pdp_spot_check_queue.csv`, `staging_handoff_actions.csv`, plus 10 queued PDP check templates under `data/staging/pdp-check-queue/`. Export Console now displays the blocking checklist rows and handoff packet from `/api/export/status`.
- Staging evidence validation is available with `bun run staging:evidence`; it writes templates under `data/staging/_templates/` plus `staging_evidence_validation.md/csv/json`, and requires clean Matrixify import logs, 5+ passing PDP checks, and cutover approval before staging can be marked complete. Export Console now displays this evidence gate from `/api/export/status`.
- Master handoff verification is available with `bun run verify:handoff`; it runs all handoff gates in sequence, including compliance blank decisions, product approval decisions, executive decision brief, staging handoff packet, staging evidence, delivery index, and content audit, then writes `handoff_verification_run.md/csv/json`. Export Console now displays the blocked verification checks from `/api/export/status`.
- Delivery packet index is available with `bun run delivery:index`; it writes `delivery_index.md/csv/json` and maps 179 handoff, blocker, validation, source-request, source-acquisition, intelligence, staging, current daily-status, completion-evidence, reviewer-workbook, reviewer-preflight, owner-message/response-intake, owner-evidence-guide, post-response-rerun, gate-dependency, packet-refresh, artifact-freshness, and migration artifacts. Export Console now displays packet group coverage from `/api/export/status`.
- Staged source acquisition plan is available with `bun run source:acquisition`; it writes `source_acquisition_plan.md/json`, `source_acquisition_stages.csv`, and `source_acquisition_targets.csv`. The plan recommends DataForSEO first for a capped structured pilot, with Apify reserved for targeted gap-fills after raw output inspection. Export Console now displays the staged provider plan from `/api/export/status`.
- Latest verified counts:
  - Dashboard export: 190 product records / 375 blockers.
  - Migration product export: 350 product/variant rows / 375 blockers.
  - Metaobjects: dashboard template export now includes source-backed `clinically_shown_to` rows; migration emitter writes 98 total metaobject rows, while dashboard Matrixify row shape expands to 118 rows. Do not treat those row counts as the same format.
  - Asset validation: 643 local files found after generating 16 metaobject SVGs and 570 draft PDP PNGs, 586 required filenames, 0 missing referenced uploads/files, and 0 missing filename refs.
  - Handoff manifest: not ready for Lewis/Euan; current dashboard/migration exports report 375 blockers, now concentrated in 185 unmatched clinical-claim/compliance rows plus 190 human approval rows rather than missing asset files.
  - Source request pack: 206 source request rows, 16 clinical-claim request rows, and 570 image-production rows.
  - Template schema validation passes for dashboard products, migration products, dashboard/migration smart collections, dashboard metaobjects, and migration metaobjects.
  - Promo cards: 2 draft Feefo-backed promo cards generated, 2/2 smart collections mapped; dashboard metaobject export includes promo cards and source-backed clinical-claim metaobjects, while migration metaobjects emit 14 promo-card rows inside the 98-row migration format.
  - Claims validation now reports ready=true with 4 source-backed draft authorised nutrient/function claim entries in `data/sources/claims/claims-library.json`; `bun run claims:sync-content` maps 5 products to source-backed draft clinical claim refs and deliberately leaves 185 unmatched SKUs blank for human compliance review. Final human compliance/content approval remains a separate blocker.
  - Editable CSV decision inputs now exist for human review: `data/content/compliance/clinical-blank-decisions.csv` and `data/content/approvals/product-approval-decisions.csv`. Scripts read these CSVs back into the JSON gates, so reviewers can work in spreadsheet form without the dashboard inventing approvals.
  - Compliance review packets: `bun run claims:unmatched-review` writes `unmatched_claims_review_packet.md/csv/json` for the 185 SKUs with blank clinical-claim refs. `bun run compliance:blank-decisions` writes `clinical_blank_decision_template.md/csv/json` plus editable decision inputs `data/content/compliance/clinical-blank-decisions.json` and `data/content/compliance/clinical-blank-decisions.csv`; a blank clinical-claim field is export-safe only if compliance records `decision=approved_blank`, approver, timestamp, rationale, and `constraintsAcknowledged=true`. `bun run approval:review-packet` writes `product_approval_review_packet.md/csv/json` for all 190 product approval decisions. `bun run approval:decisions` writes `product_approval_decision_gate.md/csv/json` plus editable decision inputs `data/content/approvals/product-approval-decisions.json` and `data/content/approvals/product-approval-decisions.csv`; it applies approvals only when a human fills `decision=approve_all`, approver, timestamp, review evidence, all lane acknowledgements, and no-fake-evidence acknowledgement. These scripts fail by design while rows remain unresolved; they are review queues/gates, not approval bypasses.
  - Source-drop validation now reports ready=true with Amazon 1/1, Trustpilot 1/1, and Reddit 1/1. The Amazon file is a limited competitor/category Amazon UK public-snippet seed drop (`data/sources/amazon/amazon-uk-vitamin-d3-k2-public-snippet-2026-05-19.json`), not a full catalogue Amazon export.
  - Image filenames/assets: 570 deterministic product image filenames assigned, 16/16 required metaobject SVG icon/image assets generated, 570/570 draft PDP PNG assets generated as review-marked placeholders, 0 missing filename refs, and 0 missing asset-upload/file blockers remain; image approval is still blocked because draft assets are not final human-approved creative.
  - Migration handoff scripts now share the same asset gate as the dashboard: `validate_assets_manifest.py` checks 586 refs with 0 missing assets and `build_products_csv_v5.py` now reports 375 blockers, no longer asset-upload blockers.
  - Readiness audit: 10/12 gates passing. Passing gates are catalogue content seeded, workflow seeded, template schema, asset filenames assigned, asset uploads ready, source request pack, source drops, claims library, promo cards seeded, and full intelligence coverage. Blocked gates are handoff readiness and human approval.
  - Intelligence generation workqueue: `bun run intelligence:queue` writes `intelligence_generation_workqueue.json/csv`, `intelligence_generation_by_sku.csv`, and `intelligence_generation_summary.csv`; it now passes with 0 missing intelligence tasks across 190 products. `bun run extract:claims`, `bun run scrape:amazon`, `bun run scrape:reddit`, `bun run extract:audience`, `bun run build:competitors`, `bun run extract:flavor`, and `bun run intelligence:catalog-queues` now create catalogue-wide queue/evidence files for all 12 required intelligence views. Important caveat: many non-pilot files are clearly marked as queue scaffolds/source-seeded drafts, not final quote-level or human-approved evidence.
  - Handoff action plan: `bun run handoff:actions` currently fails by design with ready=false, 6 owner-facing actions, 0 active P0 blockers, 2 active blocked actions, 375 export blockers, 0 missing assets, and 0 missing intelligence tasks.
  - Staging checklist: `bun run staging:checklist` currently fails by design with ready=false, 18 checks, and 9 blocking checks because preflight blockers and Lewis/Euan staging evidence are still missing.
  - Staging evidence validation: `bun run staging:evidence` currently fails by design with ready=false, 5/5 evidence gates blocking, 0 import logs, and 0 PDP spot checks; templates are written to `data/staging/_templates/`.
  - Master handoff verification: `bun run verify:handoff` currently fails by design with ready=false, 8/17 checks passing, and 9 blocked checks (`clinical_blank_decisions`, `product_approval_decisions`, `product_approval_review_packet`, `handoff:actions`, `executive_decision_brief`, `staging_handoff_packet`, `staging:evidence`, `staging:checklist`, `audit:content`).
  - Delivery index: `bun run delivery:index` currently passes with 144/144 packet files present after adding the unmatched-claims, blank-decision, product-approval review, product-approval decision, staging-handoff, executive-decision, and blocker-burndown packets; this proves packet completeness only, not final handoff readiness.
  - Source acquisition plan: `bun run source:acquisition` writes a 4-stage credit-controlled plan with 9 DataForSEO Stage 1 pilot targets and 7 Apify-only gap-fill competitor targets; `bun run apify:gapfill` writes a no-spend Stage 2 packet with 3 first-batch targets, 4 held targets, and 7 existing PDP probes; `bun run dataforseo:pilot` writes the Stage 1 ASIN intake/payload packet and currently reports 6 ready task rows / 3 missing ASINs after live DataForSEO product-result confirmation; `bun run dataforseo:products-live` is the guarded repeatable live Amazon Products search runner (requires `JV_SOURCE_ALLOW_PAID=dataforseo-product-search`), and `bun run dataforseo:live-asin-evidence` refreshes the live account/evidence report from `data/sources/dataforseo/products_raw/` without printing credentials; `bun run dataforseo:asin-candidates` writes `dataforseo_asin_candidate_report.md/csv/json` from the no-spend candidate log and currently reports 4 ASIN-shaped candidates, 0 Amazon-confirmed/high-confidence candidates, and 4 still requiring Amazon product-page confirmation; `bun run dataforseo:asin-web-evidence` writes `dataforseo_asin_web_evidence.md/csv/json` from public no-spend lookup evidence and currently records 4 third-party lookup aids, 0 Amazon-confirmed exact matches, and 2 rejected not-target leads; `bun run dataforseo:unresolved-asins` writes `dataforseo_unresolved_asin_evidence.md/csv/json` from the live DataForSEO product-result candidate export and currently inspects 212 candidate rows for the 3 unresolved SKUs, finds 0 exact matches, and keeps all 3 out of the paid payload; `bun run dataforseo:asin-confirmations` writes the manual Amazon-page confirmation worksheet/report (`data/sources/dataforseo/asin-confirmations.csv`, `dataforseo_asin_confirmation_report.md/csv/json`) for all 9 Stage 1 targets and currently reports 0/9 confirmations ready for promotion (4 candidate rows, 5 manual-search rows); `bun run dataforseo:promote-asins` writes `dataforseo_asin_promotion_report.md/csv/json`, safely promotes only Amazon-confirmed/high-confidence candidates into `asin-map.csv`, and currently promotes 0 rows because the candidates are not confirmed; `bun run dataforseo:asin-lookup` writes the ASIN lookup queue; the live DataForSEO product search now confirms 6 ASINs and leaves 3 exact JV ASINs unresolved; `bun run dataforseo:task-preflight` writes `dataforseo_task_preflight.md/csv/json`; `bun run dataforseo:reviews-live` is the guarded repeatable Amazon Reviews pilot runner/status artifact; `bun run dataforseo:reviews-docs-status` fetches the official DataForSEO Amazon Reviews docs and currently detects the provider-published temporary-unavailable note with 2/3 docs checks passing; `bun run dataforseo:support-escalation` writes a credential-free support packet for the archived 50304 Reviews endpoint failure; `bun run dataforseo:support-response` writes `dataforseo_support_response_gate.md/csv/json` plus the editable response tracker `data/sources/provider-responses/dataforseo-reviews-endpoint-response.json` and currently has 3/6 checks passing while the provider response, endpoint/replacement path, and retry-safe confirmation are missing; `bun run dataforseo:approval-request` writes `dataforseo_stage1_approval_request.md/csv/json` as a project-owner approval packet for the one capped pilot and currently has 4/6 approval-prep checks ready (blocked by provider endpoint availability and unapproved local approval file); `bun run amazon:manual-capture` writes `manual_amazon_review_capture.md/csv/json` plus `data/sources/_templates/amazon-manual-review-capture-template.json` as a no-spend fallback queue for the same 6 confirmed ASINs; DataForSEO paid task creation remains blocked with 6/10 preflight checks passing because the paid-run flag, official docs unavailable status, support-response clearance, and spend gate are still blocked; `bun run dataforseo:ingest` prepares the post-pilot raw-result normalization lane and currently reports 0 raw files / 0 converted reviews; `bun run source:pricing-refs` writes `source_acquisition_pricing_references.md/csv/json` from official provider pricing references and currently records 5 references across DataForSEO and Apify; `bun run source:cost-scenarios` writes `source_acquisition_cost_scenarios.md/csv/json` and currently estimates the DataForSEO standard 9-ASIN/depth-10 pilot at $0.00675 while keeping spend blocked; `bun run source:subscription-decision` writes `source_subscription_decision.md/csv/json` and currently says do not subscribe/spend yet, DataForSEO is first once ASINs/gates are ready, and Apify stays held; `bun run source:budget` writes `source_acquisition_budget_gate.md/csv/json` plus the editable cap file `data/sources/budgets/source-acquisition-budget.json` and currently records the DataForSEO Stage 1 local budget cap with 7/9 checks passing; `bun run source:cost-plan` writes `source_acquisition_cost_plan.md/csv/json` plus `data/sources/budgets/source-acquisition-cost-plan.json` and currently records DataForSEO Stage 1 cost readiness with 8/12 cost checks passing; Apify cost remains blocked until a named gap/actor cost exists; `bun run source:approvals` writes `source_acquisition_approval_gate.md/csv/json`, enriches local approval templates, and currently blocks paid usage with 0/23 approval checks passing; `bun run source:spend-gate` currently blocks DataForSEO and Apify spend with 6/14 gate checks passing; DataForSEO ASIN scope, 6-row task payload, budget cap, and cost plan are accepted, while valid approval and provider endpoint readiness still block spend; `bun run dataforseo:review` adds the post-pilot review/scale decision gate and currently reports 1/7 checks passing with decision pending; `bun run source:next-actions` writes the ordered operating checklist and currently says do not subscribe/spend yet, resolve the 3 remaining ASINs or proceed with the 6 confirmed payload rows once budget/spend gates are intentionally opened; `bun run source:refresh-packet` now regenerates the source-acquisition packet and currently reports 32/32 required packet steps passing; current source state is now Amazon 1, Trustpilot 1, Reddit 1 because the guarded DataForSEO Reviews pilot is blocked by approval/spend gates and the latest archived provider call returned `50304 This function temporarily unavailable` before any review task IDs were created.
- Latest technical verification:
  - `bun run validate:assets` passes and writes `content_population_exports/asset_manifest_validation.*`. `bun run validate:sources` now passes with Amazon 1/1, Trustpilot 1/1, and Reddit 1/1. `bun run scrape:amazon` reports 1 Amazon source file and refreshes the 3 pilot Amazon review queues; `bun run scrape:trustpilot` reports 1 Trustpilot source file; `bun run scrape:reddit` reports 1 Reddit source file and refreshes the 3 pilot Reddit pulse queues.
  - `bun run build` passes.
  - `bun run audit:content` still fails by design with 10/12 gates passing and 2 blocked.
  - `bun run handoff:actions` still fails by design with ready=false and generates the current owner/action pack.
  - `bun run staging:checklist` still fails by design with ready=false and generates the current staging import/PDP spot-check checklist.
  - `bun run staging:evidence` still fails by design with ready=false and writes evidence templates plus validation outputs.
  - `bun run verify:handoff` still fails by design with ready=false, now 8/17 checks passing after adding explicit decision/staging gates to the verifier, and writes the master verification run outputs.
  - `bun run delivery:index` passes and writes the consolidated packet map, now 144/144 files present after adding the metaobject SVG, draft PDP asset, clinical-claim mapping, unmatched-claims, blank-decision, approval review, approval-decision, staging-handoff, executive-decision, and blocker-burndown ledgers. `bun run handoff:burndown` currently tracks 384 remaining evidence items across compliance, approval, staging import, PDP checks, and cutover lanes and fails by design until those evidence files validate. `bun run handoff:decision-brief` currently generates 5 decision rows and fails by design while export blockers remain. `bun run staging:handoff-packet` currently generates 7/7 import/reference files present and a 10-SKU PDP spot-check queue, but fails by design while handoff blockers remain.
  - `bun run source:acquisition` passes as a planning artifact and writes the staged provider/target plan. `bun run source:refresh-packet` passes with 32/32 packet-generation steps and regenerates the staged source-acquisition packet end-to-end without spending provider credits. `bun run source:pricing-refs` passes and writes official pricing references for the cost-plan step. `bun run source:cost-scenarios` passes and writes 5 no-spend cost scenarios, including a DataForSEO standard queue estimate of $0.00675 for the 9-ASIN/depth-10 pilot. `bun run source:subscription-decision` passes and writes a plain-English subscribe/spend decision packet: do not subscribe/spend yet; DataForSEO first later; Apify held. `bun run source:budget` passes as a status artifact and writes explicit max-spend/task hard-stop checks. `bun run source:cost-plan` passes as a status artifact and now records official DataForSEO Stage 1 pricing in the cost-plan file, with 8/12 cost checks passing; Apify cost remains blocked until a named gap and actor-specific cost exist. `bun run source:approvals` passes as a status artifact, enriches local approval templates, and currently records 0/23 approval checks passing so human approval cannot bypass cap/run-limit/no-secret acknowledgements. `bun run source:next-actions` passes and writes the no-spend-first operating checklist (`source_acquisition_next_actions.md/csv/json`). `bun run source:spend-gate` passes as a status artifact and writes explicit provider spend blockers/approval-file templates. `bun run apify:gapfill` passes as a no-spend Stage 2 packet and writes the Apify first-batch/hold queue plus input template. `bun run apify:task-preflight` passes as a no-spend paid-actor gate and writes `apify_task_preflight.md/csv/json` with 2/8 checks passing and 3 first-batch targets still blocked from running. `bun run dataforseo:pilot` passes and writes the ASIN intake, 6-row payload, manifest, plan, and curl template. `bun run dataforseo:asin-candidates` passes as a no-spend candidate report and writes ASIN-shaped candidates for Turmeric, CoQ10, Visisoft, and Starflower while keeping all 4 blocked until Amazon confirmation. `bun run dataforseo:asin-web-evidence` passes as a no-spend public evidence report with 4 third-party lookup aids, 0 Amazon-confirmed exact matches, and 2 rejected not-target search leads. `bun run dataforseo:unresolved-asins` passes as no-spend negative evidence from live DataForSEO product results and records 3 unresolved targets, 212 inspected candidate rows, 0 exact matches, and 3 keep-out-of-paid-payload decisions. `bun run dataforseo:asin-confirmations` passes as the manual Amazon-page confirmation worksheet/report and currently marks 0/9 confirmations ready for promotion. `bun run dataforseo:promote-asins` passes as a no-spend promotion gate and currently promotes 0 rows because none of the candidates are Amazon-confirmed/high-confidence with confirmation evidence. `bun run dataforseo:asin-lookup` passes as a no-spend manual lookup queue and writes Amazon search URLs/actions plus candidate hints. `bun run dataforseo:products-live` now writes a blocked/no-spend run report unless the explicit product-search allow flag is set, preventing future one-off shell guessing; `bun run dataforseo:live-asin-evidence` passes using the real DataForSEO credentials from `C:\Users\uldvs\OneDrive\Desktop\work\pi-fresh-foundation\.env`, confirms the account with `20000 Ok`, and writes `dataforseo_live_connection.md/json`; `bun run dataforseo:task-preflight` passes as a paid-run gate artifact and writes `dataforseo_task_preflight.md/csv/json` with 6/10 checks passing after support-response clearance and official docs availability were added as hard retry gates (credentials, budget, and 6-row payload ready; paid-run flag, support-response clearance, and spend gate still blocked); `bun run dataforseo:reviews-live` writes `dataforseo_reviews_live_pilot.md/json/csv`, refuses to post unless preflight is ready plus the explicit paid-run flag is set, and records the archived `50304` provider failure as the current endpoint blocker; `bun run dataforseo:reviews-docs-status` writes `dataforseo_reviews_docs_status.md/json/csv`, fetches the official DataForSEO docs without credentials, and currently reports endpointTemporarilyUnavailable=true with 2/3 docs checks passing; `bun run dataforseo:support-escalation` writes `dataforseo_support_escalation.md/json/csv`, a send-ready support packet with endpoint, status code, official-docs unavailable evidence, payload shape, and proof that credentials/Product search work but no secrets; `bun run dataforseo:support-response` writes `dataforseo_support_response_gate.md/json/csv` and the local provider-response tracker so a support reply can unblock endpoint availability without guessing; `bun run dataforseo:approval-request` writes `dataforseo_stage1_approval_request.md/json/csv`, a non-approval project-owner packet with the exact capped approval values to use only after DataForSEO confirms Reviews endpoint availability; `bun run amazon:manual-capture` writes `manual_amazon_review_capture.md/json/csv`, a no-spend fallback capture queue for 6 confirmed ASINs and a source-drop template to use if the provider endpoint remains unavailable; `bun run amazon:manual-capture-validate` writes `manual_amazon_review_capture_validation.md/json/csv` and currently shows 0/6 source drops valid with 0 reviews captured because `data/sources/amazon/` has no completed manual source files; `bun run dataforseo:ingest` passes while waiting for raw paid-pilot JSON and writes the ingest validation outputs plus an ignored raw-response example. `bun run dataforseo:review` passes as a status artifact and writes the review decision template/gate.
  - Production smoke tests return 200 for `/product/JV-D1000/export-console` and `/api/export/status`; `/api/export/status` now includes `readinessAudit`, `intelligenceWorkqueue`, `handoffActionPlan`, `stagingChecklist`, `stagingEvidence`, `handoffVerification`, `deliveryIndex`, `sourceAcquisitionPlan`, `apifyGapfill`, `dataforseoPilot`, `dataforseoAsinLookup`, `dataforseoAsinCandidates`, `dataforseoAsinConfirmations`, `dataforseoAsinPromotion`, `dataforseoIngest`, `sourcePricingReferences`, `sourceCostScenarios`, `sourceBudgetGate`, `sourceCostPlan`, `sourceApprovalGate`, `sourceSpendGate`, `dataforseoPilotReview`, `sourceAcquisitionControlRun`, `sourceSubscriptionDecision`, `sourceAcquisitionNextActions`, `dataforseoTaskPreflight`, `dataforseoReviewsLivePilot`, `dataforseoReviewsDocsStatus`, `dataforseoSupportEscalation`, `dataforseoSupportResponseGate`, `dataforseoApprovalRequest`, `manualAmazonReviewCaptureValidation`, `unmatchedClaimsReview`, `clinicalBlankDecisionTemplate`, `productApprovalReview`, `productApprovalDecisionGate`, `executiveDecisionBrief`, `blockerBurndown`, `stagingHandoffPacket`, `dataforseoLiveConnection`, `dataforseoProductsLiveRun`, `dataforseoAsinWebEvidence`, `dataforseoUnresolvedAsinEvidence`, and `apifyTaskPreflight`, reports 190 products, 375 blockers, readinessAudit.ready=false, 0 missing intelligence tasks across 0 affected SKUs, 6 action-plan lanes, 0 active P0 actions, 2 active blocked actions, 0 missing asset uploads, unmatched-claims review 185/190, blank-decision gate 0 valid / 185 pending, product approval review 190 blocked products, product approval decision gate 0 valid / 190 pending, 18 staging checklist rows with 8 blocking, 5 staging evidence gates with 5 blocking, 8/17 master verification checks passing, 144/144 delivery packet files present, source acquisition control run 32/32 steps passing, source pricing references 5 rows across 2 providers, source cost scenarios 5 rows with DataForSEO standard pilot estimate $0.00675 and Apify still held for named gaps, source subscription decision says do not subscribe/spend yet, source acquisition budget gate 7/9 checks passing with the DataForSEO Stage 1 local budget cap enabled and Apify still blocked, source cost plan 8/12 checks passing with DataForSEO Stage 1 cost ready (GBP 0.00675 estimated / GBP 1 cap buffer) and Apify cost still blocked until a named gap/actor cost exists, source approval gate 0/23 checks passing with 0/2 approvals valid, DataForSEO task preflight 6/10 checks passing (credentials loaded from the real env file, DataForSEO budget cap and 6 task rows ready; explicit paid-run flag, official docs unavailable status, support-response clearance, and spend gate still blocked), DataForSEO Reviews official docs status 2/3 checks passing with endpointTemporarilyUnavailable=true, DataForSEO support response gate 3/6 checks passing with provider response/retry path still blocked, manual Amazon capture fallback 6 targets / 6 payload rows represented, manual capture validation 0/6 source drops valid with 0 reviews captured, DataForSEO approval request 4/6 approval-prep checks ready with endpoint availability and approval validity still blocked, Apify task preflight 2/8 checks passing with 3 first-batch targets blocked until DataForSEO review names a gap and spend/token gates are ready, 4 ASIN candidates with 0 Amazon-confirmed/high-confidence candidates, 4 public web lookup aids with 0 Amazon-confirmed exact matches and 2 rejected not-target leads, unresolved ASIN evidence 3 targets / 212 DataForSEO candidate rows / 0 exact matches / 3 kept out of the paid payload, 0/9 ASIN confirmations ready (4 candidate rows and 5 manual-search rows), 0 ASIN promotions and 3 ASINs still missing after 6 live-confirmed DataForSEO product matches, source acquisition next actions open with instruction not to broaden spend: 6 live-confirmed ASINs / 6 payload rows are ready and 3 ASINs remain unresolved/outside the payload, provider spend gate 6/14 checks passing with DataForSEO/Apify spend blocked; DataForSEO ASIN scope, 6-row task payload, budget cap, and cost plan are accepted, but official docs availability, support-response clearance, valid approval, and provider endpoint readiness still block spend, DataForSEO pilot review 1/7 checks passing with decision pending, 7 Apify gap-fill targets with 3 first-batch / 4 held and 7 existing PDP probes, 9 DataForSEO pilot targets, 6 ready DataForSEO payload rows, 6 ASINs present / 3 missing, and 0 DataForSEO review tasks posted by the guarded runner, 0 raw review result files converted, the latest archived provider task creation returned `50304 temporarily unavailable`, and `dataforseo_support_escalation.md` is ready to send to DataForSEO support without credentials.
- Product editor/list metafields are normalized as arrays before saving/export so comma-edited `filter.dietary_tag`, `filter.health_goals`, and `pdp.product_benefits` cannot corrupt Matrixify list output.
- Approval Queue can now update per-SKU approval lanes through `POST /api/content/products/:sku/approval`; updates persist to product content, workflow events, and the workflow index. The UI exposes guarded actions for content approval, image readiness, and export readiness without auto-approving blocked compliance/image work.
- Compliance gate is now explicit in the dashboard:
  - `/api/compliance/status` reports 190 SKUs checked, 3 source-blocked pilot SKUs, 187 pending-intelligence SKUs, 0 source-backed clinical claims, and 16 candidate VoC themes that are allowed for benefit copy but not clinical claims.
- Source readiness gate is now explicit:
  - `/api/sources/status` reports Feefo ready for the 3 pilot SKUs and competitor PDP probes ready for all 7 configured competitors.
  - Amazon now has 1 source file (limited competitor/category public-snippet seed, not full 190-SKU Amazon coverage), Trustpilot is 1/1 from a public-snippet source drop, Reddit is 1/1 from a public-snippet source drop, and claims library is now 1/1 as a source-backed draft library.
  - Intelligence file coverage is now complete at 190/190 for all 12 required views: review-aspects, strengths/weaknesses, conversion blockers, improvements, image audit, photo brief, competitor comparison, Amazon reviews, Reddit pulse, flavour intelligence, audience profile, and claims evidence. Non-pilot files remain queue scaffolds/source-seeded drafts until quote-level extraction, assets, and human approvals are complete.
- Claims evidence extraction: `bun run extract:claims` now scans all 190 product content records, matches authorised claim-library entries only when the SKU/name/key-ingredient supports a Vitamin D/K/C match, writes `data/intelligence/<SKU>/claims-evidence.json` for every product, and marks unmatched products as `no_source_backed_claim_matched_for_product` rather than inventing claims.
- Catalogue-wide source queue extraction: `bun run scrape:amazon`, `bun run scrape:reddit`, `bun run extract:audience`, `bun run build:competitors`, `bun run extract:flavor`, and `bun run intelligence:catalog-queues` now scan all 190 product records. For non-pilot products they create source-seeded or queue-scaffold intelligence files and mark them as needing SKU/category validation, visual QA, quote-level extraction, or human approval instead of pretending final evidence is complete.

Current blockers before real handoff:
1. Clinical claims library/regulatory input now exists as a 4-entry source-backed draft authorised-claim library, but final compliance/content approval and product mapping still remain blocked by design.
2. Full-depth Amazon source drops are still incomplete, but the source-drop gate now has one real limited Amazon public-snippet seed; Trustpilot and Reddit also have limited public-snippet source drops; the claims library has 4 authorised-claim draft entries; remaining scripts still avoid synthetic evidence.
3. Product image filenames are assigned for the full catalogue, and all required asset filenames now exist in `C:\Users\uldvs\OneDrive\Desktop\jv-assets` (16 metaobject SVGs plus 570 draft PDP PNGs). The PDP PNGs are deliberately review-marked draft assets generated from dashboard evidence, so image approval remains blocked until human review/final creative replacement.
4. Human approval is still pending for generated product/metaobject content.
5. Lewis/Euan staging import and PDP spot-checks have not happened yet.

---

## Source-of-truth artefacts

| Thing | Location |
|---|---|
| Content population template (from Lewis/Euan, 15 May) | `C:\Users\uldvs\Downloads\Just Vitamins - Content Population Templates (1).xlsx` |
| Loom 1 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Metaobjects (Euan) | https://www.loom.com/share/c20a24cdbdd84f6a80450dbbe2f37112 |
| Loom 2 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Products & Collections (Euan) | https://www.loom.com/share/47efa12a45e64cfdbe30840037edaffa |
| Existing dashboard | `C:\Users\uldvs\OneDrive\Desktop\Work 2.0\jv-dashboard\` |
| Existing migration scripts | `C:\Users\uldvs\OneDrive\Desktop\Work 2.0\JV Migration to shopify\` |
| Image assets pipeline | `C:\Users\uldvs\OneDrive\Desktop\jv-assets\` |
| Umar's Sublingual B12 worked example | https://docs.google.com/document/d/1lknZGQpAzIO3DW4Yn5piahu5OS_h1K7kwB3VjoGBk3Q |
| Umar's brand/positioning doc | https://docs.google.com/document/d/1p7kXT_JmM9s8VCK49IZZDo-PHudf_GYjim5XOjUntjg |

## Umar's competitor list (WhatsApp, 13 Mar 2026)
1. Feel ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â wearefeel.com
2. Ancient & Brave ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ancientandbrave.earth
3. Heights ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â heights.com
4. Wild Nutrition ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â wildnutrition.com
5. Dirtea ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â dirteaworld.com
6. Ethical Nutrition ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ethical-nutrition.com (also PDP photography reference)
7. Puro Labs ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â purolabs.com (also PDP styling reference)

## Direct quotes from Umar (use as guiding principles)
- *"Prioritize the research (product, competitor, Reddit, Amazon reviews) but can begin with our Feefo reviews ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â everything else stems from the research"* (13 Mar)
- *"Detailed reviews seems to be missing"* ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â wants competitor coverage to be deep, not just JV (1 May)
- *"Customer language from our original authentic reviews"* ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â reviewable provenance for compliance (1 May)
- *"Source is obviously our Feefo reviews"* ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Feefo = canonical first-party (1 May)
- Asked about **RAG** to connect LLMs to Feefo/DB and **Predictive AI** for shipping analysis (2 May)
- 6 May email ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â **collagen NPD market intelligence brief is top priority, pause other JV work**

---

## Matrixify template schema (from the XLSX)

### Metaobject sheets (long format: one row per Handle ÃƒÆ’Ã†â€™ÃƒÂ¢Ã¢â€šÂ¬Ã¢â‚¬Â Field ÃƒÆ’Ã†â€™ÃƒÂ¢Ã¢â€šÂ¬Ã¢â‚¬Â Value)

| Definition handle | Fields | Source data |
|---|---|---|
| `dietary_tag` | `name`, `icon` (svg filename) | Tag taxonomy from existing products |
| `health_goals` | `name`, `icon` | Tag taxonomy |
| `key_ingredients` | `name`, `description`, `image` (svg) | Existing PDP ingredient panel + AI-rewritten description |
| `benefits` | `name`, `description`, `icon` | Synthesised from `strengths-weaknesses.json` |
| `clinically_shown_to` | `name_internal`, `heading`, `description`, `stat_1_value` (num), `stat_1_name`, `stat_2_value`, `stat_2_name`, `stat_3_value`, `stat_3_name`, `disclaimer` | **Source-backed only ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â compliance gate.** Pull from `claims-evidence.json` |
| `promo_card` | `name`, `title` (quote), `subtitle` (person+location), `button_text`, `button_link`, `background_colour` (hex), `background_image` | Hand-picked testimonial from `_raw_reviews.json` |

### Products sheet (wide format, one row per variant SKU; product-level fields filled only on first variant row)

Column order:
```
Handle
Metafield: filter.dietary_tag                    [list.metaobject_reference]   e.g. "dietary_tag.vegan, dietary_tag.vegetarian"
Metafield: filter.health_goals                   [list.metaobject_reference]
Metafield: pdp.key_ingredients                   [metaobject_reference]
Metafield: pdp.benefits                          [metaobject_reference]
Metafield: pdp.clinically_shown_to               [metaobject_reference]
Metafield: breadcrumb.primary_collection         [collection_reference]        collection handle
Metafield: filter.strength                       [single_line_text]            e.g. "High Strength"
Metafield: pdp.who_its_for                       [single_line_text]
Metafield: pdp.product_benefits                  [list.single_line_text]       JSON array
Metafield: pdp.key_features                      [multi_line_text]             \n-separated
Metafield: pdp.results                           [file_reference]              image filename
Metafield: pdp.results_mobile                    [file_reference]
Metafield: pdp.how_we_compare                    [file_reference]
Metafield: faq.heading_one / two / three         [single_line_text]
Metafield: faq.answer_one / two / three          [multi_line_text]
Variant SKU
Variant Metafield: pdp.tag                       [single_line_text]            e.g. "Most Popular"
Variant Metafield: pdp.colour                    [color]                       hex
Variant Metafield: pdp.price_per                 [single_line_text]            e.g. "12p per capsule"
Variant Metafield: pdp.strapline                 [single_line_text]            only on larger variant
```

### Smart Collections sheet
Two cols: `Handle`, `Metafield: custom.promo_card [metaobject_reference]` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ÃƒÂ¢Ã¢â€šÂ¬Ã¢â€žÂ¢ links each collection to its promo card.

### Critical Matrixify rules
- All referenced **icons + images must be uploaded to Shopify Files BEFORE** the CSV import (Matrixify looks up by filename).
- List metaobject refs: comma-separated `definition.handle` pairs.
- List text: valid JSON array.
- Multi-variant: 1 handle, N rows; only Row 1 has product-level metafields.

---

## Dashboard audit ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â EXISTS vs MISSING

### EXISTS (don't rebuild)
- **App shell**: Vue 3 + Vite + Vue Router (`src/main.js`). Layout = `TopBar` + `Sidebar` + `ProductHeader` + `<router-view>`.
- **API** (`api/server.ts`, Bun, port 3456):
  - `GET /api/products` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â catalog + `hasIntelligence` flag
  - `GET /api/reviews/:sku` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â raw reviews
  - `GET /api/intelligence/:sku/:view` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â auto-merges main + supporting JSONs via `enrichWithSupporting()` (configurable map in `SUPPORTING_VIEWS`)
- **Views (7)**: CatalogOverview, ReviewInsights, ConversionDriver, StrengthsWeaknesses, ProductImprovements, ImageAudit, ConversionBlockers
- **Primitives**: SentimentBadge, JourneyBadge, ClassificationBadge, DifficultyBadge, DotRating, SupportingReviews
- **Composable**: `useSupporting.js` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â generic loader + expand/collapse + supporting-reviews drill. Any new aspect-style view plugs straight in.
- **Data convention** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â every intel file follows:
  ```json
  { "sku", "name", "generatedAt", "generatedBy", "n", "<items>": [{ "rank", ... }] }
  ```
  + matching `<view>-supporting.json` mapping `rank ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ÃƒÂ¢Ã¢â€šÂ¬Ã¢â€žÂ¢ reviewIndices`.
- **Intelligence files per SKU**: `_raw_reviews.json`, `review-aspects(+supporting).json`, `strengths-weaknesses(+supporting).json`, `conversion-blockers(+supporting).json`, `improvements(+supporting).json`, `image-audit.json`, `photo-brief.json`
- **Pilot SKUs**: `JV-D1000`, `JV-D4000`, `JV-TURMERIC500`
- **Scripts**: `scripts/tag-reviews.ts` (Gemini 2.5 Flash, 40/batch ÃƒÆ’Ã†â€™ÃƒÂ¢Ã¢â€šÂ¬Ã¢â‚¬Â 4 concurrent ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ÃƒÂ¢Ã¢â€šÂ¬Ã¢â€žÂ¢ emits `<view>-supporting.json`)
- **Migration scripts** (in `JV Migration to shopify/`): `build_products_csv_v4.py` (29-col Matrixify; **does NOT yet cover the 19 new template metafields**)

### MISSING
**Data sources**: Amazon (JV), Amazon (7 competitors), Trustpilot, Reddit, competitor PDP crawl.
**Intelligence files**: `flavor-intelligence.json` (collagen NPD), `competitor-comparison.json`, `audience-profile.json` (feeds `who_its_for`), `claims-evidence.json` (compliance trail).
**Views**: CompetitorIntel, RedditPulse, AmazonReviews, FlavorIntelligence, MetaobjectEditor (ÃƒÆ’Ã†â€™ÃƒÂ¢Ã¢â€šÂ¬Ã¢â‚¬Â6 types), ProductContentEditor (19 fields), ImagePipeline, ExportConsole, ApprovalQueue, ComplianceTrail.
**Workflow**: per-SKU status flags (`stores/` empty ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â add Pinia), per-field review log, diff view on regenerate, field-level source-citation panel (extend existing review-level `SupportingReviews`).
**Export emitters**: `build_metaobjects_csv.py` (6 long-format sheets), `build_products_csv_v5.py` (+ 19 new metafields), `build_smart_collections_csv.py`, `validate_assets_manifest.py`.

**Estimate: ~35ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã…â€œ40% built. Architecture is clean ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â remaining work = data ingestion + new editor surfaces + export emitters. No re-architecture needed.**

---

## Reuse strategy

1. **Extend, don't reinvent the schema.** Every new intel JSON follows existing convention ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ÃƒÂ¢Ã¢â€šÂ¬Ã¢â€žÂ¢ just add a line to `SUPPORTING_VIEWS` in `api/server.ts` and it works.
2. **Clone existing views.** CompetitorIntel / RedditPulse / FlavorIntelligence are ~70-line clones of `ReviewInsights.vue` using `useSupporting('<new-view>')`.
3. **Net-new view surfaces** (need real design): MetaobjectEditor (ÃƒÆ’Ã†â€™ÃƒÂ¢Ã¢â€šÂ¬Ã¢â‚¬Â6 tabs), ProductContentEditor (19 fields), ApprovalQueue, ExportConsole. ~5 net-new components.
4. **State**: add Pinia ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â `useProductsStore`, `useApprovalStore`, `useEditsStore`.
5. **New ingest scripts** (under `scripts/`): `scrape-amazon.ts`, `scrape-trustpilot.ts`, `scrape-reddit.ts`, `scrape-competitor-pdps.ts`, `extract-claims.ts`, `extract-flavor-signal.ts`, `extract-audience.ts`, `build-competitor-comparison.ts`.
6. **New emitters** (under `JV Migration to shopify/`): see Export emitters above.

---

## Build phases

### Phase 0 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â call with Umar (scheduled 19 May 2026; follow-up status needs live confirmation)
- Confirm outcome/time from WAHA or calendar before claiming the meeting happened; the last recorded evidence only said it was scheduled for 19 May 2026 via WhatsApp.
- Walk dashboard demo
- Lock: competitor scope, SKU rollout order, clinical claims source, image production lane, icon set, RAG over Feefo (Umar asked 2 May), predictive shipping AI (defer), Reviews.io decision (Lewis blocked), Klaviyo vs Attentive, social warming
- Output: shared mini-roadmap to keep board informed

### Phase 1 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Collagen NPD market intelligence brief (Umar's top priority, blocks NPD)
- Inputs: Amazon + Trustpilot + Reddit on competitor collagens
- Outputs:
  - `flavor-intelligence.json` (chalkiness, sweetness, aftertaste, mixability sentiment)
  - `competitor-comparison.json` (price, format, dose, claims, white space)
  - `audience-profile.json` (skin/joint/hair/gut motivations)
  - PDF brief + dashboard view
- Recommend final 3ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã…â€œ4 flavors + differentiation angle + subscription hook

### Phase 2 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Scale intel pipeline to full catalogue
- Extend Feefo ingest to all SKUs
- Add Amazon ingest (JV products)
- Re-run `tag-reviews.ts` across full set
- Generate review-aspects / strengths / blockers / improvements / image-audit / photo-brief per SKU

### Phase 3 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â New intelligence + competitor coverage
- Build `audience-profile.json`, `claims-evidence.json` per SKU
- Scrape & build competitor coverage (7 brands ÃƒÆ’Ã†â€™ÃƒÂ¢Ã¢â€šÂ¬Ã¢â‚¬Â Amazon + Trustpilot + PDPs)
- Build `competitor-comparison.json` per JV SKU
- New views: CompetitorIntel, RedditPulse, AmazonReviews, FlavorIntelligence

### Phase 4 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Metaobject library production
- Inventory pass on existing JV catalogue ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ÃƒÂ¢Ã¢â€šÂ¬Ã¢â€žÂ¢ unique tags / goals / ingredients / benefits / claim blocks / collections needing promo cards
- Icon production (commission or generate; upload to Shopify Files)
- AI copywriting pass + human QA
- **Build** `MetaobjectEditor` view (6 tabs)
- **Build** `build_metaobjects_csv.py` emitter

### Phase 5 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Product content production
- AI generation pass for: `who_its_for`, `product_benefits`, `key_features`, FAQs, `strapline` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â using existing intel files
- Image production for `results` / `results_mobile` / `how_we_compare` (using `photo-brief.json` as input)
- Variant maths: `price_per`, `tag`, `colour`, `strapline`
- **Build** `ProductContentEditor` view
- **Build** `build_products_csv_v5.py` emitter

### Phase 6 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Smart Collections + Approval + Export
- Collection ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â ÃƒÂ¢Ã¢â€šÂ¬Ã¢â€žÂ¢ promo_card mapping
- `ApprovalQueue` view (Umar reviews + signs off per SKU/field)
- `ComplianceTrail` view (citation chain for clinical claims)
- `ImagePipeline` view (production status)
- `ExportConsole` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â preview CSVs, validate refs, ship to Lewis/Euan
- `validate_assets_manifest.py` ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â every referenced filename exists in Shopify Files

### Phase 7 ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Delivery
- Hand-off CSV batch to Lewis/Euan for staging
- Spot-check 5ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã…â€œ10 PDPs in staging
- Iterate on feedback
- Cut over to production

---

## Open dependencies (require Umar/external input)

1. **Clinical claims library / regulatory contact** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â non-negotiable for `clinically_shown_to` content
2. **Icon set** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â JV brand icons or commission?
3. **Image production capacity** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â designer or generative pipeline at scale
4. **Final SKU count in scope** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â drives all timeline estimates
5. **Reviews platform decision** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Reviews.io (Lewis blocked on this)
6. **Email platform** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Klaviyo vs Attentive (Lewis sending rec)
7. **Trustpilot remap v3** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Azreen's lane; flagged SKUs (Turmeric etc.) still mismatching
8. **Recharge GMV/forecast inputs** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â Umar's lane; Wed call with Hugh (Recharge)

---

## Stretch / parallel asks from Umar
- **RAG over Feefo + JV DB** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â spec it, plug into dashboard AI generation
- **Predictive AI for shipping** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â net postage cost vs income, retention ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â defer to post-migration
- **Subscribe & Save** ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â possibly tiered: 10% commodity / 20ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã…â€œ30% premium NPD (raised 16 Mar)
- **Social media warming** pre-rebrand (raised 15 May)
- **Trustpilot Review Mapping v3** with Azreen (Apr) ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â still open

---

## Quickstart for picking this up in a new session

1. Read this file first (`CONTENT_POPULATION_PLAN.md`)
2. Open the template: `C:\Users\uldvs\Downloads\Just Vitamins - Content Population Templates (1).xlsx`
3. Confirm what's been added since last session: `git log`, `bun run handoff:daily-status`, or check `data/intelligence/` for current SKU coverage. The older 19 May 2026 note was written when only the pilot set was established; current generated coverage is catalogue-wide but still contains queue/source-seeded drafts.`r`n4. WAHA chat with Umar: session `omair_personal`, chat id `447835840569@c.us`, group `120363425912974765@g.us` (JustVitamins x Quikcue) ÃƒÆ’Ã‚Â¢ÃƒÂ¢Ã¢â‚¬Å¡Ã‚Â¬ÃƒÂ¢Ã¢â€šÂ¬Ã‚Â see `cabinet4u/waha-export/pull_messages.py` for the read pattern
5. Last meeting status evidence: **19 May 2026** - meeting scheduled via WhatsApp, time being confirmed. On **20 May 2026**, verify WAHA/live calendar before treating the call as completed

---

## Source acquisition staging - DataForSEO first, Apify selective

Decision recorded 19 May 2026: use **DataForSEO first** for the paid review-source pilot because it gives a controlled Amazon Reviews task endpoint, predictable per-task payloads, and a hard stage gate before scaling. Use **Apify selectively** only after the DataForSEO pilot exposes gaps that need browser-style scraping, competitor PDP capture, Trustpilot actor coverage, or non-Amazon enrichment.

### Stage 1 DataForSEO pilot packet

- Command: `bun run source:acquisition`, `bun run dataforseo:pilot`, optionally `JV_SOURCE_ALLOW_PAID=dataforseo-product-search bun run dataforseo:products-live` for a fresh paid product-search refresh, then `bun run dataforseo:live-asin-evidence` to refresh live account/product-result evidence from DataForSEO without printing credentials. Use `bun run dataforseo:reviews-live` only after local approval/spend gates are ready; it is the repeatable Reviews pilot runner and records provider unavailability without placing failed task-post JSON into the ingest queue. If the endpoint still returns 50304, send `content_population_exports/dataforseo_support_escalation.md`.
- No credits are spent by the packet generator; it only creates intake and payload files.
- Capped first pass: 9 JV priority SKUs, recommended depth 10 reviews per ASIN.
- ASIN intake file: `data/sources/dataforseo/asin-map.csv`.
- Paid-call payload: `content_population_exports/dataforseo_amazon_reviews_task_payload.json` (currently 6 rows from live-confirmed ASINs; 3 Stage 1 targets remain unresolved).
- Credential-safe call template: `content_population_exports/dataforseo_amazon_reviews_curl_template.sh`.
- Dashboard visibility: Export Console shows ready payload rows, missing ASINs, depth cap, target statuses, live DataForSEO connection status, confirmed ASINs, and review-endpoint blocker from `/api/export/status`.
- ASIN lookup prep: `bun run dataforseo:asin-lookup` writes `dataforseo_asin_lookup_queue.md/csv/json` with Amazon search URLs and manual confirmation actions. This is still a no-spend step and exists to fill `data/sources/dataforseo/asin-map.csv` before creating any paid task payload.

- ASIN candidate log: `bun run dataforseo:asin-candidates` writes `dataforseo_asin_candidate_report.md/csv/json` from `data/sources/dataforseo/asin-candidates.csv`. Candidate ASINs found from third-party evidence are shown in the lookup queue, but they do not unlock payload rows or provider spend until the Amazon product page is opened, exact Just Vitamins product/pack match is confirmed, and the ASIN is manually copied into `asin-map.csv`.

- ASIN public web evidence: `bun run dataforseo:asin-web-evidence` writes `dataforseo_asin_web_evidence.md/csv/json` from `data/sources/dataforseo/asin-web-evidence.csv`. It records third-party ASIN hints and rejected not-target search leads so the team can avoid repeat checks while still keeping all non-Amazon-confirmed evidence out of `asin-map.csv` and paid task payloads.

- Amazon-page ASIN confirmation: `bun run dataforseo:asin-confirmations` writes `dataforseo_asin_confirmation_report.md/csv/json` and maintains `data/sources/dataforseo/asin-confirmations.csv`. This is the reviewer worksheet for visible Amazon title, brand match, target-product match, pack-size match, reviewer, timestamp, and notes. Promotion remains blocked unless this report marks a candidate `ReadyForPromotion=yes`.

- Confirmed ASIN promotion: `bun run dataforseo:promote-asins` writes `dataforseo_asin_promotion_report.md/csv/json` and copies only candidates with `MatchStatus=amazon_confirmed_exact_match`, `Confidence=high`, and a canonical `https://www.amazon.co.uk/dp/ASIN` URL into `data/sources/dataforseo/asin-map.csv`. Existing ASIN values are never overwritten. This makes the manual confirmation step repeatable without letting low/medium-confidence candidates create paid task rows.

- Apify gap-fill prep: `bun run apify:gapfill` writes `apify_gapfill_runbook.md`, `apify_gapfill_targets.csv/json`, and `apify_competitor_pdp_input_template.json`. It keeps Apify behind the DataForSEO pilot review, limits any first run to 3 competitor domains, and holds the remaining 4 domains until dataset quality/cost is inspected. `bun run apify:task-preflight` writes `apify_task_preflight.md/csv/json` as the final no-spend gate before any paid actor run; it requires APIFY_TOKEN, `JV_SOURCE_ALLOW_PAID=apify-stage2`, budget/spend gates, and a DataForSEO pilot review decision of `run_apify_gapfill` with a named gap.

- Provider subscription decision: `bun run source:subscription-decision` writes `source_subscription_decision.md/csv/json`, a plain-English decision packet that currently says not to subscribe/spend yet, to use DataForSEO first once ASINs and gates are ready, and to keep Apify held until a named post-pilot gap exists.

- Provider pricing references: `bun run source:pricing-refs` writes `source_acquisition_pricing_references.md/csv/json` from official DataForSEO and Apify pricing references so cost planning starts from sourced pricing, not guesses. It does not unlock spend and still requires checking account billing pages before running providers.

- Provider cost scenarios: `bun run source:cost-scenarios` writes `source_acquisition_cost_scenarios.md/csv/json` from the pricing references and current Stage 1/2 caps. It estimates the DataForSEO standard queue 9-ASIN/depth-10 pilot at $0.00675 as a no-spend planning reference, keeps priority queue as reference-only, and keeps Apify as a held Stage 2 estimate until a named gap exists.

- Provider cost plan: `bun run source:cost-plan` writes `source_acquisition_cost_plan.md/csv/json` plus `data/sources/budgets/source-acquisition-cost-plan.json`. It requires current provider pricing source/timestamp, unit cost or expected actor-run cost, capped task/target assumptions, estimated total, and proof the estimate fits the max-spend budget before approvals or spend can unlock.

- Provider approval gate: `bun run source:approvals` writes `source_acquisition_approval_gate.md/csv/json` and enriches local approval templates in `data/sources/approvals/`. It requires approver, timestamp, matching budget cap, target/run/depth caps, hard-stop acknowledgement, no-credential-storage acknowledgement, and for Apify a named gap before approval can become valid.

- Provider spend gate: `bun run source:spend-gate` writes `source_acquisition_spend_gate.md/csv/json` and reads the approval gate rather than a bare approved flag. It blocks DataForSEO until the ASIN scope is explicit, the capped payload is ready, the budget cap is recorded, the cost plan is accepted, and valid approval is ready, and blocks Apify until DataForSEO output has been inspected, a named gap exists, caps are preserved, budget cap is valid, and approval is valid.

- Provider budget gate: `bun run source:budget` writes `source_acquisition_budget_gate.md/csv/json` and creates the editable cap file `data/sources/budgets/source-acquisition-budget.json`. It blocks provider spend until a max spend is enabled for the relevant lane, the task/actor caps stay within the staged plan, and the hard-stop flags remain true. This is separate from approvals so a human approval cannot accidentally bypass the credit cap.

- DataForSEO pilot review gate: `bun run dataforseo:review` writes `dataforseo_pilot_review.md/csv/json` and the decision template `data/sources/reviews/dataforseo-stage1-review.json`. It forces the review of raw output quality, evidence fields, cost, and the explicit scale/Apify/stop decision before any expansion.

- Source acquisition control run: `bun run source:refresh-packet` regenerates the staged source packet (`source:acquisition`, DataForSEO prep/unresolved-ASIN evidence/official reviews docs status/support response/approval request/manual Amazon fallback/manual capture validation/ingest/review, Apify gap-fill prep/preflight, spend gate) and writes `source_acquisition_control_run.md/csv/json`. Run `bun run delivery:index` after it to refresh the overall handoff packet index. This proves source-packet freshness without implying provider spend or handoff readiness.

- Manual Amazon capture fallback: `bun run amazon:manual-capture` writes `manual_amazon_review_capture.md/csv/json` and `data/sources/_templates/amazon-manual-review-capture-template.json`. It gives a no-spend path to collect Amazon reviews for the 6 confirmed ASINs while DataForSEO Reviews remains blocked; completed JSON source drops must be saved into `data/sources/amazon/`, validated first with `bun run amazon:manual-capture-validate`, then validated with `bun run validate:sources`.

- Manual Amazon capture completion gate: `bun run amazon:manual-capture-validate` writes `manual_amazon_review_capture_validation.md/csv/json` and checks the queued `SourceDropPath` files under `data/sources/amazon/` for matching SKU/ASIN/product URL plus non-empty review text, 1-5 rating, and URL. It currently reports 0/6 files present/valid and 0 reviews captured, proving the fallback is queued but not completed source evidence.

- Support response gate: `bun run dataforseo:support-response` writes `dataforseo_support_response_gate.md/csv/json` and creates `data/sources/provider-responses/dataforseo-reviews-endpoint-response.json`. Fill that tracker only after DataForSEO replies; until it records endpoint availability or a replacement endpoint plus retry-safe confirmation, the Reviews pilot remains blocked. This same support-response clearance is now a hard prerequisite in both `bun run dataforseo:task-preflight` and `bun run source:spend-gate`, so approval alone cannot trigger a retry while the 50304 path is unresolved.

- Official DataForSEO docs status gate: `bun run dataforseo:reviews-docs-status` writes `dataforseo_reviews_docs_status.md/csv/json` by fetching the official Amazon Reviews Task POST documentation without credentials or paid calls. It currently detects the official temporary-unavailable note, so the docs gate is now a hard prerequisite in both `bun run dataforseo:task-preflight` and `bun run source:spend-gate`, reinforcing the same no-retry/no-spend instruction as the archived 50304 provider response.

- Approval request packet: `bun run dataforseo:approval-request` writes `dataforseo_stage1_approval_request.md/csv/json`. It pre-fills the exact capped Stage 1 approval values without marking anything approved; approval still requires the project owner to fill `data/sources/approvals/dataforseo-stage1-approval.json`, provider endpoint availability, and a passing approval/spend gate.

- Unresolved-ASIN evidence: `bun run dataforseo:unresolved-asins` writes `dataforseo_unresolved_asin_evidence.md/csv/json` from the saved live DataForSEO Amazon Products results. It is a no-spend anti-guessing report: unresolved SKUs stay out of the paid Reviews payload unless exact match evidence appears.

- Next-action control list: `bun run source:next-actions` writes `source_acquisition_next_actions.md/csv/json`. It turns the DataForSEO-vs-Apify decision into an ordered operating list: first keep the 6 confirmed ASINs as the capped pilot scope while continuing no-spend lookup for the 3 unresolved ASINs, then record explicit Stage 1 spend approval, then run exactly one paid pilot after the DataForSEO Reviews endpoint is available and review raw quality/cost before any scale-up or Apify actor run. Export Console shows this as the current provider-spend instruction from `/api/export/status`.





- Post-pilot normalization: `bun run dataforseo:ingest` reads DataForSEO advanced Amazon Reviews task result JSON from `data/sources/dataforseo/raw/`, converts review items into the existing `data/sources/amazon/` source-drop schema, and writes `dataforseo_ingest_validation.md/csv/json`. This keeps the paid-provider output on the same validation path as manual Amazon source drops (`bun run validate:sources`) instead of creating a parallel evidence standard.


### Spend guardrail

Do not run broad catalogue scraping yet. Use the 6 confirmed ASINs as the capped pilot payload once the budget/spend gates are intentionally opened and the DataForSEO Reviews endpoint is available; keep the 3 unresolved ASINs out of the payload unless exact product evidence is found. Then inspect output quality/cost and decide whether to:

1. scale DataForSEO to the next JV SKU batch,
2. run Apify only for named competitor/Trustpilot/PDP gaps, or
3. stop and adjust the source map before any further spend.





























