⚗️ The Apothecary

The Apothecary is the operating manual for The Herbalist's v2 storefront: how the new AI-natively-controlled Hydrogen site works next to the current GemPages site, every tool connected to it, how changes ship, and what we do if anything goes wrong. The cutover programme itself lives in the 🎯 Game Day tab: everything that must be built, connected, tested and verified before the switch. Written for every member of the digital marketing team. Sections 1 to 8 each end with a Technical details button for the deeper detail that developers and agents need.

Owner: Ismaeel Approver: Matt Status: Pre-game · nothing live has changed Stack verified: 21 Aug 2026 (from the live site's own code)

1 · Start here

For years The Herbalist website has run on Shopify's standard theme system with GemPages, a visual page builder. It is manual but easy: anyone can log in, drag things around, and press publish. We are replacing it with a Hydrogen storefront: a custom-coded site that we fully own, that AI agents can build, test and improve continuously, and that will become the foundation for CRO experiments, A/B testing and our own custom apps.

That is a big step. The current site takes roughly R3.3-4.6M per month in orders. So this document exists to make the switch boring: every risk identified, every integration reconnected, every check written down, and a tested way back if anything misbehaves.

Zero downtime is the rule. The switch itself is a domain reassignment inside Shopify admin, not a DNS migration. The old site stays fully intact and publishable the whole time. If anything goes wrong we point the domain back and we are on the old site again within minutes.

Checkout never changes. Both the old and new site hand customers to the exact same Shopify checkout. Payments, shipping rates and order processing are untouched by this project.

Humans keep the judgement. Agents build, test and monitor. People approve. Nothing reaches the live site without a human saying so on a staging preview first.

Nothing important lives only in chat scrollback. This document is the source of truth for the cutover and for how the site is run afterwards. If a decision changes, this page changes.

Who does what

Person	Role on this project
Ismaeel	Responsible for the whole cutover: builds, integrations, testing, the Game Day run itself, and day-2 operations.
Matt	Approves the go-live decision and production deploys. Runs deploys from his terminal until automatic deploys (CI) are set up, because the Shopify login for deploying is tied to his machine. Owns the Google Ads side.
Kelly	Signs off content parity and the new content-editing workflow (section 8). Owns email, promos and the marketing calendar around the switch date.
Agents (Claude Code + Herbie/Hermes)	Do the heavy lifting: porting code, wiring integrations, running test suites, monitoring after launch. Always through the pipeline in section 6, never straight to production.

2 · Old site vs new site

Think of the current site as a house we rent with furniture included: Shopify renders every page for us, GemPages lets us redecorate visually, and apps bolt features on by injecting their own code. The new site is a house we built ourselves: we write every page, which means total control and speed, but features that used to "just appear" from apps now have to be deliberately built in and connected.

	Current live site (v1)	Hydrogen storefront (v2)
What it is	Shopify Online Store theme + GemPages page builder	Custom-coded Hydrogen app we own end to end
Who edits it	Anyone, visually, in GemPages	Agents + developers through code, via the pipeline in section 6 (content workflows for the team are in section 8)
How apps work	Apps inject their own scripts and widgets automatically	Every integration is deliberately wired in by us (section 4)
Speed	Heavy: ~15 third-party scripts load on every page	Server-rendered and lean; we choose exactly what loads
Checkout	Identical Shopify checkout for both. Nothing changes.
Products, prices, stock, orders	Both read the same Shopify store. One catalog, one admin.
AI-native	No: agents cannot safely edit GemPages	Yes: agents build, test, deploy and monitor through the pipeline

3 · Every site we have, and what happens to each

Over the past months we built several versions of the storefront to explore designs. As of 21 Aug 2026 one build is promoted and everything else is archived, so there is never confusion about which site is "the one".

Site / build	What it is	Status	What happens to it
theherbalist.co.za	The live GemPages site (v1)	Live production	Stays exactly as-is until Game Day. After cutover it remains published on the Online Store channel as our instant rollback for at least 30 days.
storefront-v2 branch	Ismaeel's live-clone build: the chosen v2 base (was `variant/live-clone`)	Promoted	Split into its own repo on 21 Aug: `The-Herbalist-SA/storefront` (main = production, staging). All Game Day build work happens there; the harness keeps the archived builds.
Matt's build (repo `main`)	First Hydrogen build; currently on the stable Oxygen preview URL	Archived	Tagged `archive/main-storefront-build`. Not deleted: it is the parts shop. Reviews data, Buy More & Save, SEO library, contact page and tests get ported from it into storefront-v2.
variant/momentous	Momentous-style design exploration	Archived	Preserved in the archive folder: `archive/` branches plus `archive/variant-` tags (pushed 21 Aug). Nothing is deleted; the old `variant/*` names remain as duplicates and can be tidied later if we ever choose to.
variant/bioteen	BioTeen-style design exploration	Archived
variant/hybrid-premium	Premium-minimal design exploration	Archived
variant/organics-ocean	Organics-Ocean-style design exploration	Archived
PR #7 (header logo size)	Ismaeel's open PR against the archived main build	Decision	Recommend closing as superseded (the v2 base has its own header). Ismaeel closes it with a one-line comment.
herbalist-nextjs-demo.catalystlabs.co.za	Early Next.js design prototype (separate project, not Shopify-connected)	Archived	Keep as a design reference or take the deployment down; either way it plays no role in Game Day.

4 · The connected stack: every tool on the live site

This list was built by reading the live site's own page code on 21 Aug 2026, so it is the real list, not a from-memory one. Every tool below currently loads on theherbalist.co.za. For each one: what it does for us in plain language, and what has to happen before or during Game Day.

Survives keeps working by itself Rebuild we build it into v2 ourselves Reconnect the tool stays, its script must be wired into v2 Decide needs a business decision before Game Day Retires deliberately ends with the old site

Money and selling

Tool	What it does for us	Plan
Shopify checkout + payments	Takes the money. Cards, shipping rates, order creation.	Survives Same checkout for both sites. Verify with one staging test order.
Kaching Bundles	The "Buy More & Save" 1/3/6-bottle offers on product pages. A proven basket-size booster.	Rebuild Native version already exists in the archived main build, including the automatic 5% multi-pack discount. Port it, and confirm the discount still exists in Shopify admin.
Bold Subscriptions (+ legacy Spurit scripts)	The "Once a month" subscribe option on product pages, roughly R20-50K/mo.	Decide Bold does not use Shopify's native selling plans (verified: the API returns none), so v2 cannot simply query it. Options: Bold's headless integration, migrating to a native selling-plan app, or launching v2 without subscriptions and keeping existing subscribers billing through Bold. Quantify revenue first; this is the biggest open product decision.
BOGOS free gifts	Runs free-gift-with-purchase offers (our BOGO promos).	Decide Widget will not load on v2. Check with Kelly whether any BOGO offer is scheduled near Game Day; either rebuild as native discounts or time the cutover between promos.
Rebuy	"You may also like" recommendations and upsells sitewide.	Decide v2 has its own related-products carousel. Pull Rebuy's attributed-revenue number from its dashboard; if material, rebuild smarter recommendations natively or via Rebuy's API. Otherwise cancel the subscription after cutover.

Tracking and marketing data

Tool	What it does for us	Plan
Google tag (GA4 + Google Ads)	Feeds Google Ads conversions, remarketing lists and Smart Bidding signals, plus GA4 analytics and the intel warehouse.	Reconnect Highest-stakes item for our ad account. Wire the tag into v2 and verify remarketing events fire before cutover. Purchase conversions at checkout keep working regardless.
Triple Whale (Tixel)	Attribution: tells us which ads actually drive orders.	Reconnect Add the Tixel/headless snippet to v2 and confirm events in the Triple Whale dashboard from staging.
Meta pixel	Facebook/Instagram ads tracking and audiences (managed outside our remit, but fed by the site).	Reconnect Wire base pixel + events; confirm with whoever runs Meta that events arrive.
TikTok pixel	TikTok ads tracking and audiences.	Reconnect Same treatment as Meta.
Microsoft Clarity	Session recordings and heatmaps for CRO.	Reconnect One script. (Roadmap: PostHog may replace it, section 9.)
Klaviyo onsite	Email capture and browse tracking; powers browse-abandonment flows and "Active on Site" segments.	Reconnect Load Klaviyo JS and wire the footer "Holistic Wellness Course" form to the real Klaviyo form (the form ID is documented in the code). Without this, list growth stops on day one.
t.trackmytarget.com	Unidentified tracker found in the live code (likely an affiliate network).	Decide Identify who added it and why. If it earns nothing, retire it; if it is an active affiliate program, reconnect it.

Experience and content

Tool	What it does for us	Plan
Loox	Collects and shows customer reviews (6,000+), and feeds star ratings to Google.	Rebuild + Survives Review display is rebuilt natively fed by real Loox data (we already sync the full review set via the Loox API). Review-request emails are triggered by orders, not the theme, so collection continues; verify with a staging test order that a request gets scheduled.
GemPages	The page builder the whole v1 site is built in.	Retires Do not cancel billing until 30+ days after cutover (it powers the rollback site). First: rebuild its landing pages natively (six benefit pages + contact page are on the checklist) and self-host the handful of images v2 currently borrows from GemPages' CDN.
BSS Store Locator	The stockists map/list (77 stores).	Rebuild Already done: v2 has a native Store Locator with all 77 stockists. Retire the app after cutover. Decide the update path for new stockists (section 8).
PushOwl	Web push notifications to subscribed browsers.	Decide Push subscriptions are tied to the site's service worker. Check subscriber count and revenue in PushOwl; if material, integrate PushOwl on v2; if not, retire.
Visually.io	A/B testing and personalisation on the live site.	Decide Check with Kelly what experiments are running. Conclude or pause them before cutover. Roadmap replacement is PostHog (section 9).
WhatsApp chat button	The floating green chat bubble; daily customer support channel.	Rebuild Small native component linking wa.me with the support number. Not built yet; on the checklist.

5 · 🎯 Game Day: the cutover checklist

Everything that must be built, configured, tested and verified, in order. A phase only starts when the one before it is done (Phases 1 and 2 can overlap). This is the master list; it should be mirrored into ClickUp tasks so progress is visible to everyone. Nothing in Phases 1-4 touches the live site.

Phase 0 · Decisions Each item names its driver

Ismaeel: pull the real monthly subscription revenue number, then Matt picks the Bold path (headless integration, app migration, or launch without and phase in).
Ismaeel: check the Rebuy, PushOwl, BOGOS, Visually and trackmytarget dashboards for revenue/usage; Matt + Kelly then mark each one Reconnect / Rebuild / Retire in section 4.
Kelly: sign off the content editing workflow after launch (section 8).
Matt: kratom on the storefront: match live (catalog grid shows it) or restrict. Record the decision; hidden b2b collections stay hidden either way.
Decided + done (21 Aug): storefront/ split into The-Herbalist-SA/storefront with history; growth harness moved into the org alongside it.
Matt + Kelly: pick the target cutover window: off-peak, no promo running, Kelly's calendar clear, everyone available for the following 48h.

Phase 1 · Build: make v2 content-true and feature-complete Ismaeel + agents

Done (21 Aug): this doc, the three audits and the cutover queries are committed to the harness repo (The-Herbalist-SA/the-herbalist-growth-harness, commit f120b8c), and the docs site auto-deploys from it on every push to main.
Replace all sample review data with the real Loox dataset; remove invented reviewer cards entirely; products with no reviews show no stars.
Correct every product page's dosage, size and spec copy verbatim against the live site (4 of 5 curated products currently differ; liquid extracts are wrongly described as capsules).
Fix the subscribe option: it currently looks real but adds a one-time purchase. Hide it until the Phase 0 subscription decision lands, then implement that decision.
Port Buy More & Save (1/3/6 bottles) from the archived main build; verify the automatic 5% discount exists in admin.
Build the six benefit landing pages (sleep, stress-relief, concentration-cognitive, fitness-performance, hormones, immunity-adaptogens): currently blank because GemPages renders them on v1.
Build the contact page; redirect the three legacy policy URLs to the working policy pages.
Port from main: cart free-shipping progress bar, styled checkout button, add-to-cart double-click lock, SEO library (titles, meta descriptions, canonicals, product JSON-LD), branded 404 page.
Fix the sitemap (currently emits fake foreign-language URLs), set country to ZA, add mobile hero images, restore the kratom/b2b merchandising guard per the Phase 0 decision, add the WhatsApp button, self-host the footer social icons.
Restore the test suites from main (unit + Playwright) and get them green.

Phase 2 · Connect: tracking and integrations Ismaeel + agents

Extract every tag ID from the live theme (Google tag, Meta, TikTok, Clarity, Klaviyo, Tixel) and record them in the repo.
Wire the pixel layer + CSP allowlist (one build covers all vendors; pattern in section 4's technical details).
Wire the Klaviyo newsletter form. Set PUBLIC_CHECKOUT_DOMAIN and all production environment variables in Oxygen.
Register the production domain with the customer login system (Customer Account API callback URIs) so account login works on theherbalist.co.za.
Set up error monitoring (Sentry) and an external uptime probe with alerts to Slack/ClickUp.

Phase 3 · Pipeline: staging and production Ismaeel + Matt

Done (21 Aug): repo created with main + staging. Still open: branch protection on main (needs a paid GitHub plan for private repos; upgrade the org or enforce PRs by discipline).
Connect GitHub to the Hydrogen channel so every push auto-deploys: staging branch to the staging environment URL, production branch to the production URL.
Mirror all environment variables into both Oxygen environments. Verify staging and production render identically from the same commit.

Phase 4 · Test: prove it end to end on staging Ismaeel + agents, Kelly for content sign-off

Full automated suite green (unit + Playwright end-to-end).
Place a real test order on staging with UTM parameters: verify checkout completes, the order lands correctly attributed in Shopify, every pixel fired (Google, Meta, TikTok, Tixel, Klaviyo), and Loox schedules a review request for it.
Verify every Google Ads final URL resolves: re-run the three saved checks in queries/cutover_*.gaql and fetch every URL against staging. On 12 Aug all ~60 ad URLs, 17 PMax asset-group URLs and the sitelinks passed with zero 404s. The four sitelinks that 404 on live today (unpublished blog articles, an open Ads-side bug) must be fixed in the Ads account first, then re-crawled.
Lighthouse performance + accessibility pass on home, product, collection, cart (mobile and desktop). Target: beat the live site.
Cross-device sweep (iPhone, Android, tablet, desktop; Safari + Chrome) of the money path: home, product, add to cart, checkout entry.
Kelly walks the staging site against the live site page by page and signs off content parity.
Merchant Center: fetch every landing URL in the feed against the staging build; all must return 200 with price, availability and product data rendered to match the feed. Record the run date. (Merchant Center itself crawls only the live domain, so this staging check is the early warning; re-verify in Phase 6.)

Phase 5 · Game Day: the cutover Ismaeel runs it, Matt approves, Kelly on standby

Freeze: no deploys, no promos, no catalog changes during the window.
Deploy the approved staging commit to production; smoke-test the production URL directly.
Go/no-go check with Matt. Then: Shopify admin → Settings → Domains → point theherbalist.co.za at the Hydrogen storefront. No DNS changes. Old site stays published on the Online Store channel.
Immediately verify: homepage loads on the domain, product page loads, add to cart, reach checkout, customer login works, pixels fire on the live domain, SSL valid.
Place one real order end to end. Watch it arrive in Shopify admin correctly attributed.
Announce internally. Start the 48-hour watch (Phase 6).

Phase 6 · The 48-hour watch Ismaeel + agents

Monitor: error rate, uptime probe, conversion rate vs the trailing 7-day baseline, checkout entries, pixel event volumes, Google Ads spend and conversion delivery, Klaviyo flow triggers.
Compare hour-by-hour orders to the same weekday last week. A sustained conversion drop is a rollback trigger (section 7).
Confirm the intel warehouse dashboards still populate; confirm Loox review requests are sending; confirm Merchant Center shows no new disapprovals.
Day 30: if all healthy, retire the decided apps (Rebuy, BSS, GemPages billing per section 4) and close the rollback window.

6 · How changes ship after launch

Once v2 is live, no one edits the live site directly, ever. Every change (a headline tweak, a new landing page, a bug fix, an experiment) travels the same road. This is what makes the site safe to hand to agents:

1 · BranchCreate a feature branch off staging. Build the change with Claude Code or Hermes.

2 · Test locallyRun the site and the test suite on the builder's machine. Everything green.

3 · StagingMerge to the staging branch. It auto-deploys to the staging site, an exact mirror of production.

4 · ApproveA human reviews the change on the staging URL and approves the PR.

5 · ProductionMerge staging into production. Auto-deploy. Verify on the live domain.

Staging and production are identical at rest. The only time they differ is while a change is being tested. Then it either goes to production or gets removed from staging. Staging is never a junk drawer.

Every production deploy is reversible. Each deploy is kept forever with its own URL; rolling back is redeploying the previous one. Roughly two minutes.

Agents propose, humans approve. Claude Code and Hermes can do steps 1-3 autonomously. Step 4 always has a human name on it: Ismaeel for routine changes, Matt for anything touching money paths (checkout links, pricing display, subscriptions, tracking).

Pipeline implementation

Branches (in The-Herbalist-SA/storefront): main is production (deploys to the Oxygen production environment, which owns theherbalist.co.za after cutover) and staging deploys to a stable staging URL. Feature branches: feat/*, fix/*. Merges to main come only from staging, ideally fast-forward so the two are byte-identical at rest. Branch protection on main: PR required, checks required (unit + Playwright + build), no force pushes; enforcement needs the org on a paid plan, discipline until then.

CI: connect the GitHub repo in Shopify admin → Hydrogen channel → the storefront → GitHub. Oxygen then builds and deploys each pushed branch to its own environment automatically, replacing Matt's interactive CLI deploys. With the app now at the root of its own repo, the generated workflow needs no monorepo edits: connect The-Herbalist-SA/storefront and each pushed branch gets its own environment. Until CI is connected, deploys are manual:

cd ~/Projects/the-herbalist-storefront
npx shopify hydrogen deploy          # choose Preview = staging-style URL
npx shopify hydrogen deploy --env production   # production (Matt only)

Environments: both Oxygen environments carry the full env var set (the 8 existing vars plus PUBLIC_CHECKOUT_DOMAIN; add vendor keys as Phase 2 lands them). npx shopify hydrogen env pull syncs a local .env.

Agent access: Claude Code works on Matt's machine and in this repo. Hermes (Herbie VPS) gets a clone of the storefront repo and the same rules: branch, build, test, push to staging, never merge to production without a human approval recorded on the PR. Hermes must not hold Oxygen deploy credentials while deploys are CLI-interactive; once GitHub CI exists, "deploy" for agents means "merge after approval", which is exactly the control we want.

Tests as the gate: the suites restored in Phase 1 (unit + Playwright) run on every PR. A red suite blocks staging and production merges. Add a smoke spec that hits /, one PDP, one collection, cart, and asserts the checkout link resolves.

7 · Emergencies: what we do when something breaks

Three levels. Know which one you are in, act, then write down what happened.

Level	Looks like	What to do
Sev 1 Site down or can't buy	Site not loading, checkout unreachable, prices wrong, sustained conversion collapse	Roll back first, debug later. Point the domain back at the Online Store (old site) in Shopify admin: minutes, no DNS. Or redeploy the previous production deployment if the domain is fine but the latest deploy is bad. Tell Matt + Kelly immediately.
Sev 2 Something important is broken, sales still flow	A page erroring, a pixel gone quiet, login failing, layout broken on mobile	Fix through the pipeline (hotfix branch → staging → verify → production). If the bad change is known, revert it the same way. No cowboy edits to production.
Sev 3 Cosmetic or minor	Typo, spacing issue, slow page	Ticket it in ClickUp, fix in the normal flow.

Who to call

First responder: Ismaeel. Approver and Ads side effects: Matt. Customer communications if the outage is customer-visible: Kelly. Platform or checkout incidents: Shopify Plus support. Phone numbers live in the team Slack channel topic, not only in this document.

Rollback triggers during the 48-hour watch

Agreed in advance so nobody debates them at 11pm: conversion rate down more than 30% vs the same hours last week for 2+ hours, checkout unreachable for more than 5 minutes, error monitoring shows a sustained spike we cannot explain, or payments failing. Any one of these = Sev 1 = roll back.

The old site is the parachute. It stays published, untouched and paid for until at least 30 days after a healthy launch. Nobody edits or unpublishes it during that window.

8 · Upkeep: content, updates and upgrades

On the old site, Kelly edits pages in GemPages and presses publish. On v2, content lives in two places, and it matters which:

Content	Where it lives on v2	How it gets changed
Products, prices, stock, discounts	Shopify admin (unchanged)	Exactly as today. v2 reads it live; no deploy needed.
Blog posts	Shopify admin blog	Kelly publishes as today. (v2 currently pins the 5 live articles in code; the checklist adds an automatic fallback so new posts appear without a deploy.)
Legal policies	Shopify admin policies	As today; v2 reads them live.
Homepage banners, landing pages, FAQ copy, stockists	The storefront code	Request via ClickUp → an agent or Ismaeel makes the change → staging preview link for approval → production. Turnaround target: same day. (Roadmap: move the most-edited pieces to Shopify metafields so the team can edit them in admin directly.)

Recurring jobs

Weekly: refresh review counts and quotes from the Loox sync; check Sentry + uptime + Lighthouse trend; dependency security alerts.
Monthly: Hydrogen/CLI version upgrade on a branch, through the pipeline like any change; re-run the Ads final-URL check; verify staging == production.
When Kelly publishes a blog post or a stockist changes: until the metafield/API work lands, create a ClickUp task from the "sync content" template, assigned to Ismaeel; an agent picks it up and ships the update through staging.

9 · What comes next (after a healthy launch)

The reason for all of this. Once v2 is stable, the site becomes a platform we can compound on:

PostHog: product analytics, session replay, feature flags and experiments in one tool we own. Replaces Clarity (and Visually's role) with something agents can query and act on directly.
CRO agents: agents watching funnels and session data, proposing changes with evidence, shipping them as A/B experiments through the same staging pipeline, and reporting lift.
A/B testing: PostHog feature flags on v2 routes; every experiment is a branch + a flag, evaluated against real conversion data.
Custom apps: subscriptions done our way, bundles, loyalty, quiz funnels: anything the app store used to gate, built natively on our own storefront.
Content system: the most-edited content moved to metafields/metaobjects so the team edits in Shopify admin and v2 renders it live: GemPages' convenience without GemPages.

Each of these gets its own plan when its time comes. None of them start before the 48-hour watch closes green.

10 · Glossary

Hydrogen	Shopify's framework for building fully custom storefronts in code.
Oxygen	Shopify's hosting for Hydrogen storefronts. Where v2 runs. Included with our plan.
Headless	The site's front (what customers see) is separate from Shopify's back (products, orders). v2 is headless; v1 is not.
Storefront API	How v2 reads products, prices, cart and content from Shopify, live.
Staging	A private, exact copy of the production site where changes are tested and approved first.
Deploy	Publishing a version of the site's code. Every deploy is kept and can be returned to.
Pixel / tag	A small piece of tracking code a marketing tool asks us to run on the site (Google, Meta, TikTok, Klaviyo, etc.).
CSP	Content-Security-Policy: v2's allowlist of which outside scripts may run. Blocks anything we didn't approve.
Selling plan	Shopify's native way of describing a subscription. Our current subscription app (Bold) doesn't use it, which is why subscriptions are a Game Day decision.
Cutover	The moment the domain switches from the old site to the new one. The actual "Game Day".
Rollback	Switching back to the old site (or the previous deploy). Minutes, practiced, shame-free.
Branch	A separate working copy of the site's code where a change is built without touching what's live.
PR (pull request)	A request to bring a branch's change into staging or production, reviewed and approved by a person before it merges.
Merge	Accepting a change into a branch. "Merge staging into production" = release the approved changes.
Tag	A permanent bookmark on a version of the code. Our archive/ tags preserve the old builds forever.
CI	Continuous integration: the automation that tests and deploys a branch automatically when it changes.
DNS	The internet's address book, pointing theherbalist.co.za at a server. Game Day does not touch it: the domain already points at Shopify and stays there.

For agents. Canonical source of this document: storefront-docs/index.html in the harness repo (The-Herbalist-SA/the-herbalist-growth-harness, committed 21 Aug). Treat section 4's stack list and section 5's checklist as state: update them in the same PR as the work they describe, keep verification dates current, and republish the artifact after merge. The three audits in audits/ hold the file:line evidence behind every claim here. Do not mark a checklist item done without a verification method actually run. Hosting: the public site is herbie.storefront.catalystlabs.co.za on Vercel, auto-deployed from the harness repo exactly like the Greenhouse: edit this file, commit, push to main, and Vercel rebuilds the live site by itself (its build runs python3 build.py, which prepends the doctype the artifact wrapper normally supplies, and serves deploy/). No manual deploy step.