Document Metadata

• title: Shopify Headless Storefront Project Reintroduction Intake
• description: Source-backed project dossier for reintroducing the Shopify Headless Storefront into Hyphenomenon with linked chat, screenshots, hydration, and workflow evidence.
• status: active
• lastUpdated: 2026-05-23 15:26 EDT (America/New_York, UTC-04:00)
• owner: Product/Engineering

Project Intake - Shopify Headless Storefront

1) Executive Summary

2) Project Type and Domain

• Project type: program
• Domains: builder, entrepreneur
• Primary audience: Rock Paper Scissors shoppers, Maggie as storefront/catalog operator, and AI/agentic discovery clients
• Public posture: production storefront plus repo-native evidence system

3) Repository and Live URLs

• GitHub repo: https://github.com/maggielerman/shopify-headless
• Production storefront: https://www.rockpaperscisso.rs
• Local source repo path: /Users/maggielerman/Github/shopify-headless
• Related Hyphenomenon chat: codex://session/019e45cf-299f-7ae0-aff9-fef3a18f5d44
• Related Hyphenomenon chat route: /chats/shopify-headless-blog-audit-and-anna-remediation-019e45cf

4) Product/User Journey Summary

The related 019e45cf thread is part of this project history because it audited Shopify-backed article content from the live storefront, found link/media/content quality issues, and carried the approved Anna Atkins artwork mockup into production verification.

5) Architecture and Stack Summary

• Runtime app: Next.js App Router storefront with React UI.
• Commerce source: Shopify Storefront API for catalog/cart reads and checkout handoff; Shopify Admin operations are used for approved live content/catalog mutations.
• Content surfaces: Shopify-backed /blogs, /blogs/[blog], and /blogs/[blog]/[article] routes, product/collection routes, taxonomy landing pages, JSON landing pages, and LLM discovery endpoints.
• Agentic surfaces: feature-flagged /api/agents/catalog and /api/agents/checkout endpoints with readonly/checkout modes and origin controls.
• Evidence stack: repo-native docs under docs/, cutover preflight/master-pack commands, catalog-review packets, generated product-media change ledger, and project lifecycle docs.
• Verification stack: pnpm build, unit/e2e tests, SEO/GEO audit, parity audit, catalog-agent audit, media-ledger drift check, and live production checks.

6) Key Workflows and Operational Flows

• Storefront release loop: code changes are reviewed with build/test/audit commands before deployment.
• Catalog review loop: a numbered project doc defines the target, generated review boards collect human feedback, bounded apply passes update Shopify, and verification artifacts land under docs/evidence/.
• Cutover proof loop: pnpm cutover:preflight, pnpm cutover:compare, and pnpm cutover:master-pack normalize pre/post-cutover evidence into repeatable packets.
• Product media governance loop: generated media upload reports are rolled into an offline product-media change ledger and checked in CI.
• Blog remediation loop: live Shopify article content is audited for article disposition, semantic link quality, media, alt text, public HTML, and headless layout behavior before production verification.
• Agentic discovery loop: catalog/API readiness is governed by feature flags, allowed origins, localized market path validation, and explicit catalog/checkout response contracts.

7) AI Context: Prompts, Chats, Agent Workflows

The source Codex chat 019e45cf-299f-7ae0-aff9-fef3a18f5d44 is a related project evidence object, not a standalone note. It established a reusable blog-audit posture for this storefront: when Shopify API auth is unavailable, inspect live public HTML and the headless route/query implementation; evaluate content, links, and media separately; and treat approved artwork mockups as production content only after review and live verification.

This project also has agentic-commerce surfaces in the source repo. Those are runtime APIs for external agents, while this Hyphenomenon intake records the operator-facing evidence and project narrative.

8) Supporting Docs and External Resources

Hydration Source Artifacts

Path	Source URL	Type	Rationale
README.md	GitHub	markdown	Defines the storefront features, Shopify/blog/customer account/agentic/feed surfaces, credential model, and validation commands.
docs/product/product-brief.md	GitHub	markdown	Captures the user problem, MVP scope, and why headless iteration matters for Shopify campaigns and landing pages.
docs/product/prd.md	GitHub	markdown	Defines MVP goals, non-goals, requirements, analytics, and platform constraints.
docs/development/cutover-evidence-system.md	GitHub	markdown	Documents the repo-canonical evidence packet workflow for cutover proof and repeatable automated checks.
docs/development/catalog-review-workflow.md	GitHub	markdown	Defines the numbered review-board and human-feedback loop used for catalog optimization.
docs/api/agentic-endpoints.md	GitHub	markdown	Provides the controlled agentic catalog and checkout API contracts and runtime gates.
docs/PROJECTS/in-review/1110_blog-content-audit-and-remediation.md	GitHub	markdown	Source project for the blog audit/remediation work connected to chat 019e45cf.
public/brand/primary-logo-rps.png	GitHub	image	Brand image artifact for the production storefront identity.

No .docx or .pdf source artifacts were selected for hydration in this pass; the source repo keeps its durable project/evidence records primarily as Markdown, JSON, CSV, and generated image/PDF proof packets.

9) Screenshot Gallery (with relative links + captions)

• - Production storefront homepage at https://www.rockpaperscisso.rs/.
• - Shopify-backed collection surface at /collections/wall-art.
• - Shopify product detail page with customer-facing product media and purchase pathway.
• - Shopify-backed blog article surface connected to project 1110 and the 019e45cf audit/remediation context.

10) Candidate Import Nodes and Relationships

• Project: shopify-headless-storefront / 4016
• Chat: chat-codex-019e45cf-shopify-headless-blog-audit
• Workflow: workflow-shopify-headless-evidence-gated-storefront-operations
• Notes: hydrated notes from the source README, product brief, PRD, cutover evidence system, catalog review workflow, agentic endpoints, and project 1110
• Data models: storefront commerce model, agentic API gate model, and cutover/catalog evidence model
• Relationship: the Shopify Headless project owns the storefront, source docs, product surfaces, workflow, screenshots, and hydrated notes; the 019e45cf chat is related evidence for the blog/content remediation lane; the 1074 Maggie Todo intake batch reintroduced this project into Hyphenomenon after the placeholder looked empty.

11) Risks, Gaps, and Unknowns

• Live Shopify Admin state can drift after this intake; source docs and screenshots are point-in-time evidence captured on 2026-05-23.
• The storefront source repo is dirty in the local checkout and was treated as read-only for this Hyphenomenon work.
• Production screenshots were captured from public routes, not from authenticated Shopify Admin surfaces.
• The previous repaired 1044 Shopify project record was absent from the current local/production DB; this pass intentionally reintroduces the project with fresh packet-backed evidence instead of assuming the historical row still exists.

12) Handoff Checklist for Hyphenomenon Import

• Preserve the relationship to Codex chat 019e45cf-299f-7ae0-aff9-fef3a18f5d44.
• Capture production storefront screenshots for homepage, collection, product, and blog/article surfaces.
• Create curated hydration sources from the source repo.
• Create a project-page packet with narrative sections, product surfaces, tech stack, key dates, and data-model proof.
• Create a workflow packet for the evidence-gated storefront/content/catalog operating loop.
• Run hydration extraction, intake validation, dry-run, apply, chat reapply, workflow apply, drift check, and route verification.

Dataset Preview

• Raw CSV row/table content is available in the source artifact.