Randy Olson

Store operating guide

Repository-only instructions. Do not copy this guide, manifests, credentials, production files, or review evidence into public/, posts, or generated feeds. This GitHub repository is public: confidential information stays outside Git.

Live setup

Catalog: https://www.randalolson.com/store/; checkout: https://store.randalolson.com/.
Fourthwall: Randy Olson Data Art, admin slug randy-olson-data-art, shop ID sh_725f3983-738f-4e68-8878-210ff8185a5a. Separate shop from Optimal Road Trips, same login.
Free plan, connected payouts, shipping charged at checkout. No automatic free-shipping promotion.
Native Fourthwall custom domain and HTTPS are active; DNS is managed in Squarespace. Preserve its validated storefront/email records. support.store.randalolson.com is a mail subdomain, not the recipient address.
Fourthwall handles standard order support; escalations and name requests go to randal.s.olson@gmail.com.
Website pushes to main deploy through Railway. The Name Age Calculator frontend deploys from its own repository. Ship destination routes before calculator links.
Website links use HTTPS www: Squarespace apex forwarding preserves paths but drops query parameters. Its target is https://www.randalolson.com with permanent redirect.
Launch verification: October 7, 2026. 46 public listings, 3 public collections, 14 underlying designs. Recheck live state before changes; do not treat these counts as permanent requirements.

Ownership and integration

File or repository	Owns
`src/data/store-catalog.json`	Website designs, offers, prices, preview paths, post mapping, purchase URLs
`scripts/store/fourthwall-manifest.json`	Shop identity, remote IDs/URLs, master hashes, costs, verification, checkout evidence
`src/lib/store.ts`	Grouping, allowed referrals, detail and purchase links
`src/components/store-{catalog,product,offers,link,callout}.tsx`	Catalog, selectors, checkout links, referral persistence, post callouts
`src/app/store/page.tsx`, `src/app/store/[slug]/page.tsx`	Routes and artwork-specific Open Graph/Twitter metadata
`scripts/store/`	Rendering, source data, provider adaptations, draft creation, synchronization, tests
`name-age-calculator` repository	Result-page handoff in `apps/frontend/src/components/NamePrintLink.tsx`; matching in `apps/frontend/src/lib/name-prints.ts`

/store/: category filters and pagination (9 designs/page). Each artwork has a detail page; all names share /store/name-prints/?print=NAME_ID. Legacy catalog hash links resolve to details.
Names match exact name and SSA category, ignoring case and surrounding whitespace. Unknown names browse the collection. Email requests ask for future additions, not custom orders.
Format/size buttons select the matching composition, price, and URL. Selection persists within the tab and across name changes. Downloads include both sizes, so have no size selector. Black-frame previews are illustrations.
Activate website links with node scripts/store/sync-products.mjs --write only after hosted verification. Null URLs hide purchase links. --check detects drift and wrong-shop links.
Preserve existing product IDs and slugs when changing titles; save the old URL if Fourthwall offers to rename it. Hosted edits must also update local metadata.

Catalog and files

Offering	Sizes (inches)	USD prices
3 artworks: hurricane tracks, Kyoto, Roman reigns	18 x 24; 24 x 36	Matte $39/$55; black-framed $99/$149; download $9
10 name-age portraits	12 x 16; 18 x 24	Matte $29/$39; download $9
Hurricane desk mat	31.5 x 15.5	$39

Hurricane prints hang horizontally: customer-facing dimensions are 24 x 18 and 36 x 24. Provider size labels may reverse this order.
Name pilot: James, Michael, John, Robert, David, Mary, Patricia, Jennifer, Linda, Elizabeth. Fixed editions, no per-order editing.
Collections: Art prints, Name prints, Downloads; membership can overlap. Collection availability must remain enabled or member products appear sold out. Visibility and availability are separate settings.
Current costs and prices live in the manifest. Requote before new products or price changes; payment fees are additional.
Ignored build/store/: 300 ppi sRGB PNG masters, exact-size raster PDFs, deterministic ZIPs, checksums, provider assets, upload cache, review evidence. Never deploy this directory.
Public public/assets/store/: reduced JPEG previews only. Artwork and physical quality are different checks; never claim a physical inspection without a sample.
Each download ZIP includes 2 PNGs, 2 PDFs, DATA.csv, printing instructions, source credits, usage terms, and checksums. Full-resolution delivery is through Fourthwall after purchase.
Website download selections and hosted descriptions explain sizes, formats, personal display/gifts, print-shop permission, no physical shipment, and no redistribution/resale/commercial reproductions. Original-design terms must preserve source-data rights.

Artwork and data constraints

Preserve approved compositions unless a redesign is requested; render from source, not enlarged blog PNGs. Georgia/Times New Roman on macOS, DejaVu Serif fallback; review any font substitution at physical size.
Hurricanes: dark palette, geography and track segments preserved; color encodes sustained wind, arrows mark endpoints. Natural Earth basemap and NOAA HURDAT2 sources. Different aspect ratios need their own viewport/composition.
Kyoto: retain circular layout, readable title/subtitle, missing-year gaps, and CC BY 4.0 attribution (Aono/Kazui/Saito/Katata via Our World in Data). Existing source covers 812-2026.
Roman: 68 selected rulers from the 2014 analysis, ranked reign-length bars on a shared zero baseline. Dated periods in scripts/store/data/roman-emperors.csv; approximate ranges use midpoints. Keep disputed assassination color distinct but include it in violent-death counts. Callouts are computed from the same data: 35 reigns under 5 years, 27 of those deaths violent. No redundant Years column or repeated death text; definitions belong in download credits.
Names: calculator form, births as a line and estimated survivors as a blue filled area (#0072B2), not bars or mosaics. Balanced age summaries precede the legend, then the chart. Footer combines SSA source/category and estimate year; keep model details in download credits.
build_name_age.py uses name-history.csv and pct_alive_2026.csv to generate name-age-2026.csv: 1900-2025 cohorts, interpolated SSA survival anchors, rounded survivors, weighted birth-year percentiles. Approximate age is 2026 minus birth year. Missing counts remain gaps; count axes start at 0, scales vary by name.
Name prints are a dated 2026 edition, not a live age service. Annual updates require birth records, survival anchors, labels, all assets/downloads, and hosted re-verification together.
Chess remains excluded until commercial source-data rights are resolved.

API access

From this repository or its linked worktree:

python3 scripts/store/fourthwall_api.py --check
python3 scripts/store/fourthwall_api.py --request GET /shops/current

Client.for_project() resolves the Git common directory through private ~/.config/fourthwall/projects.json. Each repository has its own credential file and expected shop ID; unrelated repositories have no default shop.
The installed python3 ~/.config/fourthwall/client.py --check uses the same binding. Credential files are mode 600 in a mode-700 directory outside Git. Never print secrets or pass them in command arguments.
The client checks credential and live shop identity before every request, rejects external paths/redirects, and exposes only HTTP status on API errors.
JSON writes use --request METHOD /relative-path --body-file /private/request.json. Confirm the expected personal-shop ID above before any write.
Generic Fourthwall MCP OAuth is disabled locally; do not reconnect or read Keychain as a fallback. Use shop-bound API access. Use the dashboard for controls the API lacks, with the personal shop visibly selected.
Access does not authorize publication, DNS changes, or purchases. Follow the user’s current authorization; ask only for a consequential action that is not already authorized. Sample budget remains $0.

Production and release

From the repository root, with dependencies installed:

python3 -m venv .venv
.venv/bin/python -m pip install -r scripts/store/requirements.txt
.venv/bin/python scripts/store/build_name_age.py
.venv/bin/python scripts/store/prepare.py --only WORK_ID
.venv/bin/python scripts/store/prepare.py --check
.venv/bin/python scripts/store/prepare_provider_assets.py
.venv/bin/python -m unittest discover -s scripts/store -p 'test_*.py'
node --test scripts/store/tests/*.test.mjs src/lib/store.test.mjs
node scripts/store/sync-products.mjs --check
npm run typecheck
npm run lint
npm run build

Use --only WORK_ID for targeted rendering; omit it only to regenerate the whole collection. Regeneration retains remote IDs but clears verification on changed artwork/listing details. Run sync --write to close affected links until re-verified.
Review exact PDF dimensions, color profiles, margins, readable type, overlap, ZIP contents, and source rights. Provider adaptations are separate: hurricane masters are losslessly quarter-turned into portrait templates; the mat uses its bleed canvas. Do not rotate a designer layer to compensate.
With hosted-creation authorization, create_physical_products.py uploads checked assets and creates missing hidden drafts (publishOnCreate: false); it uses build/store/uploaded-media.json. Inspect unknown outcomes before rerunning to avoid duplicates. Digital uploads and missing controls use the dashboard. Keep new products Private for review.
Verify price/cost, actual size/variant, black frame, print placement/cropping, and public gallery independently. Hurricane galleries must look horizontal even though production masters are rotated.
Before release, check physical-only, digital-only, and mixed carts, plus shipping in US, Canada, UK, Germany, and Australia. Do not submit an order without explicit purchase authorization.
When adding a name, update the calculator’s explicit pilot list in name-prints.ts after the product is verified. Keep its exact SSA category and work ID consistent with this catalog.
After authorized publication, verify public URL, price, gallery, stock, and cart identity; mark verification.status: public-verified, then sync --write, build, and review the website links. Verify mobile selectors, name matching/history, cross-links, and downloads before shipping.
Deployment serves only dist/. Confirm docs, scripts, manifests, full-resolution masters, and ZIPs are absent there and absent from generated llms*.txt/feeds. Restore timestamp-only generated-file churn when unrelated to the change.

Analytics and remaining limits

Shared GA4 ID G-4R2NWZM0C4: website, calculator, and Fourthwall Analytics > Tracking pixels. Native tag loading was verified at launch; do not promise paid purchase reporting until tested.
Post/calculator handoffs emit store_browse; outbound Fourthwall purchase links emit store_click with product_id, product_type, source_page, and UTMs.
storeReferralQuery accepts only known post paths and the calculator source. useStoreReferral preserves them in tab session storage; a fresh recognized referral replaces the old source. Never persist/forward arbitrary queries or searched names.
At launch, all public product URLs and representative carts passed checks; Kyoto shipping quotes were available in the 5 markets above. Paid download delivery and physical fulfillment remain untested. No physical samples were purchased.
Promotion drafts: docs/store-promotion-drafts.md, not posted. No paid promotion or recurring automation. After 8 weeks of sales availability, compare visits, orders, contribution after fees/refunds, and owner hours; separate browsing from checkout clicks. Low traffic alone does not establish poor demand.