justvitamin/CONTENT_POPULATION_PLAN.md

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:

  { "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.rn4. 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
4. 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.