justvitamin/PLAN_v2_2026-06-02.md

JV Content Population — Plan v2 (2 June 2026)

Supersedes CONTENT_POPULATION_PLAN.md. The earlier plan still applies for the dashboard audit, Matrixify schema, and competitor research lanes; this v2 narrows scope to what Umar called out in the 21 May + 1 June Looms and rebases the dashboard around the 8 metaobjects that actually drive the new PDP.

---

1. The narrow brief (what Umar actually asked for)

Per the 21 May Loom (55449ee0013148e7936344b83caf9ba8) and the 1 June Loom (ce4501e9de834cfdae628c60fe9e41d3), the immediate scope across the JV catalogue is 4 PDP sections built from 8 metaobject types:

PDP section	Metaobject types	Reference design (from 21 May Loom)
Scientific Studies	scientific_study	Wild Nutrition "Food-Grown Magnesium" — headline + paragraph + 2-3 stat tiles + image. Currently missing from JV template — Umar flagged to Lewis 1 June.
Results / Timeline	timeline_phase + timeline_block	Spacegoods 90-Day; JV's own Figma — "Results / What you can expect" with linked scientific study + Month 1/2/3/4+ phases
Comparison Tables	comparison_column + comparison_row + comparison_table	Grüns "Us vs. Them" (3-col, ✓/✗); Club EarlyBird "Brain Drops" (4-col, values + notes)
FAQs	faq_pair + faq_block	JV Figma — 3 product-specific + 4 standard pairs; collapsible rows; "Still unsure? Get in touch" CTA

Plus the broader Matrixify metaobjects from the original template (still needed but lower urgency): dietary_tag, health_goals, key_ingredients, benefits, clinically_shown_to, promo_card.

Umar's stated priority order (21 May email):

1. Meta Objects + Content Population
2. NPD Research (Collagen)
3. Social Media Content / Activation
4. Influencer Marketing Scraping

---

2. The 8 new metaobject schemas

scientific_study
  - name_internal           (handle)
  - headline                (e.g. "Scientifically supported sleep")
  - body_copy               (paragraph; cites study source)
  - link_url                (NIH/PubMed/EFSA citation)
  - link_label              (e.g. "Independent scientific human study")
  - stat_1_value, stat_1_label
  - stat_2_value, stat_2_label
  - stat_3_value, stat_3_label   (optional)
  - image                   (file_reference)

timeline_phase
  - phase_label             (e.g. "Month 1", "Day 30")
  - body_copy               (single paragraph)

timeline_block
  - name_internal
  - headline                (e.g. "Results")
  - subtitle                (e.g. "What you can expect")
  - intro_copy              (1-2 lines that sit above the phases)
  - study_link_label        (e.g. "independent scientific human study")
  - study_link_url
  - phases                  (list.metaobject_reference → timeline_phase)

comparison_column
  - name                    (e.g. "Grüns", "Generic Multivitamin")
  - is_us                   (boolean)
  - accent_colour           (hex)
  - image                   (optional thumbnail)

comparison_row
  - feature_label           (e.g. "Cost Per Serving", "Taste")
  - values                  (json: index → { mark: ✓/✗/star/text, value, note })

comparison_table
  - name_internal
  - section_title           (e.g. "Us vs. Them", "Not All Brain Fuel Is Created Equal")
  - subtitle
  - columns                 (list → comparison_column)
  - rows                    (list → comparison_row)

faq_pair
  - scope                   ("standard" | "product")
  - question
  - answer                  (multi_line)
  - source_citation_id      (optional → conversion-blocker rank or study id)

faq_block
  - section_title           ("Frequently asked questions")
  - cta_label               ("Still unsure? Get in touch")
  - cta_url
  - pairs                   (list → faq_pair)

These extend (do not replace) the original Matrixify template's clinically_shown_to, key_ingredients, benefits, etc. The original faq.heading_one/two/three trio is deprecated — replaced by faq_block referencing a list of faq_pairs. Lewis confirmation needed that Shopify metaobject list.metaobject_reference is supported in his template.

---

3. Data source hierarchy (ground truth → directional)

Ranked by trustworthiness for citation purposes:

Tier	Source	Status today	Use for
1	JV website DB (tblEcomProduct, tblEcomSKUs, tblEcomProductCategories, tblEcomStockLevels, images_by_guid.json)	Already in JV Migration to shopify/full_db/	Product names, ingredients, strengths, prices, variants, categories, stock — ground truth, every comparison/PDP fact lives here
2	NIH / PubMed (E-utilities API, free, no auth)	Not built	Peer-reviewed evidence for scientific_study stat tiles. Source: https://www.ncbi.nlm.nih.gov/books/NBK25500/
3	EFSA Health Claims Register (UK/EU-approved nutrient/health claims)	Not built	The legally allowable wording for any nutrient claim. Critical compliance gate. Public CSV.
4	Cochrane Library + Examine.com	Not built	Meta-analyses + ingredient evidence summaries. Cochrane open, Examine free abstracts.
5	Feefo (JV first-party reviews)	Pulled for 3 SKUs (_raw_reviews.json)	Customer voice. Umar's compliance ask: every generated benefit/FAQ traces back here. Folder shared 10 Mar.
6	Trustpilot — JV service reviews	Manual files exist	Service signal (delivery, customer service). Re-mapping flagged April.
7	Loox (post-migration)	App deal secured, install pending	Product reviews going forward (replacing Trustpilot for product-level)
8	Amazon — JV products	Not built	Verified-purchase volume + photo content for pdp.results / lifestyle
9	Amazon — competitor products (Elavate, Wild Nutrition, Ancient & Brave, Absolute Collagen, Sunna)	Not built	Competitor signal — Umar explicitly asked: "top competitor — scrape their negative TrustPilot reviews" (Elavate, 21 May)
10	Trustpilot — competitors	Not built	Same as #9
11	Reddit (r/Supplements, r/Nutrition, UK fitness subs)	Not built	Directional sentiment + language patterns for pdp.who_its_for, FAQs
12	Competitor websites (Wild Nutrition, Dirtea, Heights, Spacegoods, Grüns, Club EarlyBird, MoonBrew, Lumity, 8Hours, Heights, Nothing Fishy, Primal Queen, LIT, Ritual, Elavate, Absolute Collagen, Sunna)	Not built	Design pattern reference + claims they use (benchmark, not copy)

Compliance rule: every scientific_study.body_copy, every comparison_row JV-favouring claim, every health-related FAQ answer must cite tier 1-4 sources only. Customer reviews (tier 5-9) are evidence for consumer experience claims ("customers report fewer joint aches") but never for clinical claims ("reduces inflammation").

---

4. Per-section data routing (where each field comes from)

scientific_study

• headline, body_copy → drafted by AI from PubMed abstract(s) + EFSA-approved phrasing → human-edited
• link_url → PubMed DOI or NIH publication URL (preferred); EFSA register entry as fallback
• stat_X_value / stat_X_label → extracted from the cited study's abstract/findings; reviewed by human
• image → Shopify Files (lifestyle photography produced separately, briefed via photo-brief.json)

timeline_phase + timeline_block

• phase_label → fixed schedule per category (collagen: "Month 1/2/3/4+"; energy: "Day 1/30/60/90"; magnesium: "Week 1/2/4/8"). Decide cadence per supplement class.
• body_copy → AI synthesises from:
  • PubMed onset-of-effect data
  • Feefo reviews mentioning timeframes ("after 3 weeks I noticed…")
  • Amazon reviews same
• intro_copy → category-level template
• study_link_* → tier-2 source

comparison_table (comparison_row / comparison_column)

• columns → JV product + 1-3 competitor reference products
• comparison_row.feature_label → product attributes from tblEcomProduct (strength, form, dietary tags, etc.) + sentiment-derived features ("Taste", "Easy to swallow")
• comparison_row.values → JV column from DB ground truth; competitor columns from competitor PDP scrape (competitors/<brand>/<sku>/pdp.json)
• All values reviewed before publish (compliance + fairness)

faq_pair

• scope: "standard" (4 base questions per the 21 May Loom):
  • "How long until I see results?" — answered from timeline_block + reviews
  • "Can I take this with other supplements?" — answered from product DB (form, ingredients) + standard guidance
  • "Is this safe long term?" — answered from EFSA + standard caveats
  • Product-specific catch-all (e.g. "Why include BioPerine?") — from tblEcomProduct.description + key_ingredients data
• scope: "product" (top 3 questions on the page) — auto-suggested from conversion-blockers.json (already exists per SKU)

---

5. Dashboard rebuild (v2, narrow scope)

The current dashboard has 7 views built around intelligence. The v2 dashboard is built around production. See PROPOSED_DASHBOARD_v2.md (to be written) for the full UI design — high level:

• Pipeline — per-SKU status across all 8 metaobjects (draft → ai-generated → reviewed → approved → exported)
• Sources — ingest health: DB row counts, NIH coverage per ingredient, Feefo coverage per SKU, Amazon coverage, Trustpilot, Reddit, competitor PDPs
• Editors — one workspace per metaobject type with source-citation panel, regenerate, approve
• Per-SKU view — all 8 sections for one SKU, single approval gate per SKU
• Compliance Trail — every claim → its tier 1-4 citation chain
• Export — build + validate + ship CSVs to Lewis

Existing views to keep as read-only reference: ReviewInsights, StrengthsWeaknesses, ConversionBlockers, ImageAudit, Improvements. They feed the editors as source-citation data.

Existing views to retire: CatalogOverview (replaced by Pipeline), ConversionDriver (logic absorbed into editors).

---

6. Scraping / extraction lane (concrete scripts to add)

All under jv-dashboard/scripts/ following the existing Bun + TypeScript pattern of tag-reviews.ts:

Script	Source	Output
ingest-db.ts	JV Migration to shopify/full_db/*.xlsx	data/pipeline/catalog.json (extended with full ingredient panel, strength, form)
ingest-feefo.ts	Feefo CSV/folder	data/intelligence/<sku>/_raw_reviews.json (already pattern)
pubmed-evidence.ts	NIH E-utilities API	data/evidence/<ingredient>.json
efsa-claims.ts	EFSA Health Claims Register CSV	data/evidence/efsa-claims.json
examine-evidence.ts	Examine.com (scraped abstracts)	data/evidence/<ingredient>-examine.json
scrape-amazon.ts	Amazon UK (JV + competitor SKUs)	data/reviews/<sku>/amazon.json, data/competitors/<brand>/<sku>/amazon.json
scrape-trustpilot.ts	Trustpilot brand pages	data/reviews/<sku>/trustpilot.json, competitor coverage
scrape-reddit.ts	Reddit API per ingredient/brand	data/research/<topic>/reddit.json
scrape-competitor-pdps.ts	16 competitor sites listed by Umar	data/competitors/<brand>/<sku>/pdp.json
generate-scientific-study.ts	PubMed evidence + EFSA + Feefo	data/metaobjects/scientific_study/<handle>.json
generate-timeline.ts	PubMed onset + Feefo time-mentions	data/metaobjects/timeline_block/<handle>.json
generate-comparison.ts	DB + competitor PDP scrape	data/metaobjects/comparison_table/<handle>.json
generate-faq.ts	conversion-blockers + standard set	data/metaobjects/faq_block/<handle>.json
build-metaobjects-csv.ts	All data/metaobjects/**	Matrixify-format CSVs per definition
build-products-csv-v5.ts	Extend build_products_csv_v4.py	Adds the 19+8 metafield columns
validate-assets-manifest.ts	Cross-check filename references vs Shopify Files API	Validation report

Tooling notes:

• Scrapers use Playwright (already in stack via tools/loom-capture/)
• Amazon/Trustpilot harder — consider Apify actor budget (see Stage 1 DataForSEO section in CONTENT_POPULATION_PLAN.md)
• LLM generation: Claude Opus for synthesis with citations; Gemini Flash for bulk tagging (existing tag-reviews.ts pattern)
• Every generated artefact carries sourceIds: [...] mapping back to source files for the dashboard's Compliance Trail

---

7. Honouring Umar's email-thread asks

Umar's ask	When	How v2 addresses it
Prioritise research (product, competitor, Reddit, Amazon reviews) — Feefo as starting point	13 Mar	Source hierarchy §3; scraping lane §6
Customer language from authentic reviews	1 May	faq_pair.source_citation_id + Compliance Trail view
RAG over Feefo + JV DB	2 May	Editors do retrieval-grounded generation: every regenerate pulls top-N Feefo/DB chunks for the SKU as context
Predictive AI for shipping (net postage cost/income, retention)	2 May	Defer to post-migration; track as separate skill
Collagen NPD priority	6 May	Phase 1 still active — flavor-intelligence.json, competitor-comparison.json, audience-profile.json for collagen
4-section PDP scope (Scientific Studies, Results, Comparison, FAQs)	21 May + 1 June	This entire plan
Standardise timelines + comparison tables across the range	22 May	timeline_block per category cadence (collagen / energy / mineral / vitamin classes share phase schedules); comparison_table reused across SKUs in same category
Shareable front-end URL with blocked-out sections	27 May	Wait for Lewis — track as dependency
Elavate negative Trustpilot scrape	21 May	scrape-trustpilot.ts includes Elavate brand page; sentiment-filtered output

---

8. What changes vs the original plan

• ✅ Scope narrowed from "all 19 product metafields + 6 metaobjects" to "8 new metaobjects driving 4 PDP sections" as immediate target
• ✅ Data hierarchy made explicit, with NIH + EFSA as compliance-safe sources for clinical claims
• ✅ Dashboard rebuild planned to focus on production, not just intelligence
• ✅ All 8 new metaobject schemas defined
• ✅ Per-section data routing made explicit
• ⏸ Original metaobjects (dietary_tag, health_goals, key_ingredients, benefits, clinically_shown_to, promo_card) deferred — still required, after the 4-section batch
• ⏸ Collagen NPD brief still active, runs parallel
• ⏸ Predictive shipping AI deferred

---

9. Loom captures (decoded reference)

Stored under tools/loom-capture/:

• 1-june-pdp-walkthrough/ — 45 frames @ 3s, contact-sheet.jpg, manifest.json — 1 June Loom (2:12)
• 21-may-uiux-walkthrough/ — 54 frames @ 3s, contact-sheet.jpg, manifest.json — 21 May Loom (2:42)
• Both transcript.txt files are empty ({"phrases":[],"schemaVersion":"1.1.3"}) — Umar didn't enable Loom auto-transcription on either video
• See tools/loom-capture/README.md for re-capture instructions