Athos Integration — Master Step-by-Step

Goal: Get Athos (Searchspring) search + product discovery live on rileyblakedesigns.com (SuiteCommerce Standard), deployed to the Sandbox first, then promoted to prod. Companion docs: athos-theme-devtools-setup.md (toolchain) · athos-frontend-build-kit.md (exact markup) · athos-frontend-integration.md (plan/gap analysis). Already done (don't redo): backend feed Suitelet is live (acct 4582045); feed output verified; bindings confirmed → PDP = itemid, category = External ID.

Phase A — Stand up the toolchain (Cole, ~30–45 min, one-time)

Full detail in athos-theme-devtools-setup.md. Checklist form here.

• ☐ A1. Confirm local prereqs: node -v and gulp -v both return a version. (If gulp missing: npm i -g gulp-cli.)
• ☑ A2. Sandbox account id confirmed from URL → 4582045-sb1 (use --account 4582045-sb1 in all gulp cmds).
• ☑ A3. Downloaded Bundle 521562.zip; latest theme tools inside = ThemeDevelopmentTools-25.1.0.zip (no 26.x exists; 18.2.1 is the old one). Extracted into ~/ai-projects-local/rbd-sc-theme-sandbox/.
• ☑ A4. ⚠️ Tools require Node ^20.10.0 / npm ^10.2.3 with engine-strict=true — Cole's global Node 24 hard-fails. FIX APPLIED: installed nvm (brew), Node 20.20.2; .nvmrc=20 pins the folder; global default kept = system (Node 24). npm install succeeded (ignore the audit warnings — do NOT npm audit fix --force).
• ☑ A5. TBA integration record Athos Theme Dev Tools created in Sandbox (TBA ✅, TBA Auth Flow ✅ + callback http://localhost:7777/tba, Auth Code Grant ⬜, User Credentials ✅). Consumer Key/Secret written to .env (perms 600). ⚠️ Key/secret were pasted in chat → rotate this integration's credentials once fetch is confirmed working.
• ☑ A6. .gitignore in place (.env, node_modules, .DS_Store) — .env protected before any git init.

Note: in v25.1.0 theme:fetch/theme:deploy take no --account flag — auth is a browser authorization flow (localhost:7777/tba); you select the Sandbox during login.

Gate: toolchain installed ✅ + TBA record created + .env filled → Phase B.

Phase B — Clone the active theme (Cole)

Run all gulp cmds from ~/ai-projects-local/rbd-sc-theme-sandbox/ with Node 20 active (nvm use picks up .nvmrc automatically).

• ☐ B1. gulp theme:fetch → browser opens for TBA authorization → log into the Sandbox (4582045-sb1), pick role/account → pulls the active RBD theme (Sass/HTML/templates).
• ☐ B2. gulp theme:local → confirms it compiles and serves locally (sanity check before we touch anything).
• ☐ B3. Hand Claude these 5 base templates from the pulled theme:
• Facets.Browse.View.tpl (search/category results)
• header search form template (desktop + mobile)
• ProductDetails.Full.View.tpl (PDP)
• cart template
• 404 template

Gate: theme cloned + templates shared. → Phase C.

Phase C — Answer 3 binding checks (Cole + Claude, against the cloned theme)

These are the only real unknowns. Claude inspects the pulled templates; Cole confirms in the Sandbox admin where needed.

• ☐ C1. Category External ID — is the category's External ID (e.g. 1191) available in the SC front-end category model? (Internal id definitely is; External ID is the open risk.)
• If yes → §1b of the build kit works as written.
• If no → pick a fix: expose External ID in the category model, or re-key the feed's category column to the SC internal id. (This is the highest-risk item — flag early.)
• ☐ C2. PDP itemid handle — how is the item's itemid surfaced in ProductDetails.Full.View's template context? (Confirms the products: ['«ITEMID»'] binding.)
• ☐ C3. Customer-id handle — which SC session/profile field maps to the Athos customer id, and confirm it's blank/omitted for guests (never emit id:'').

Gate: all 3 answered. → Phase D.

Phase D — Claude writes the override files (Claude)

Using the cloned templates + C1–C3 answers, Claude produces exact override files from athos-frontend-build-kit.md:

• ☐ D1. Global Athos bundle.js head script (all pages).
• ☐ D2. Category head script with resolved External ID binding (§1b).
• ☐ D3. New search-results page: athos-sidebar + athos-content injection divs + ss-shop body class.
• ☐ D4. Search-form rewrite (all forms: action→new page, name="q", strip hidden inputs, disable native type-ahead; old markup commented out for revert).
• ☐ D5. Recommendation blocks: home, PDP (bundle/cross-sell/similar/recently-viewed), cart (view-cart), 404 (.ss__recs__404).

Gate: override files delivered to Cole. → Phase E.

Phase E — Deploy to Sandbox + Athos-side config (Cole + Searchspring)

• ☐ E1. Place the override files in the theme; gulp theme:local to eyeball locally.
• ☐ E2. gulp theme:deploy --account <SANDBOX_ACCT_ID>-sb1 then gulp reactivate.
• ☐ E3. Confirm the custom theme is active on the Sandbox SC site.
• ☐ E4. Give the Sandbox site URL to Searchspring/Athos (Katie Kellogg) so they point their config/crawl at it and enable the profiles (home, bundle, cross-sell, similar, recently-viewed, view-cart, 404).

Gate: Athos rendering on Sandbox. → Phase F.

Phase F — UAT on Sandbox (Cole + Claude + Searchspring)

• ☐ F1. Search: type a query in the header → lands on new page, Athos results + filters render in the injection zones, no SC type-ahead bleed-through.
• ☐ F2. Category page: filters + results render; spot-check that products actually appear (this is where the 29% uncategorized-variant gap shows up — see below).
• ☐ F3. PDP: bundle / cross-sell / similar / recently-viewed populate for a known item.
• ☐ F4. Cart: view-cart recs render. Home: home recs render. 404: recs render on a bad URL.
• ☐ F5. Logged-in vs guest: shopper id present when logged in, cleanly omitted as guest.

Feed-side decision (resolve before/at UAT): 29% of feed rows (all -ROT/variant SKUs) have no category in saved search 988 → they won't appear in category browsing/recs. Decide whether variants inherit parent categories and, if so, patch the feed Suitelet. (Separate from the front-end work; can proceed in parallel.)

Gate: UAT signed off on Sandbox. → Phase G.

Phase G — Promote to production (Cole)

• ☐ G1. Repeat the toolchain against prod in a separate root dir (Oracle rule: prod + sandbox never share a workspace).
• ☐ G2. Apply the same override files; gulp theme:deploy --account 4582045 → gulp reactivate.
• ☐ G3. Point Athos config at the live rileyblakedesigns.com URL; final smoke test of F1–F5 on prod.
• ☐ G4. Keep the old search page/markup commented (not deleted) for one release cycle as a fast revert path.

Open items tracker