Spelunker's Guide — Johnny Autoseed Codebase

On the web: https://johnnyautoseed.com/spelunkers-guide (local dev: http://localhost:4321/spelunkers-guide)

Purpose: Onboard a human or AI in one sitting. CODEBASE_MAP.md (repo root) stays the authoritative tables of routes, files, and scripts. This guide is the narrative map: how the pieces connect, what to open first, and common workflows.

Last updated: 2026-03-23

0. Choose your route (30 seconds)

• I am evaluating the project (not coding):

  1. https://johnnyautoseed.com
  2. https://johnnyautoseed.com/research
  3. ../README.md (context + key references)

• I am implementing changes in this repo:

  1. ../CLAUDE.md (session workflow)
  2. ../CODEBASE_MAP.md (authoritative map)
  3. ## 1.1 Ten-minute onboarding path in this file

If you only have two minutes, do the implementation path above and then use the recipe table in section 4.

1. Start here (two minutes)

Fast keyword lookup: node scripts/map-lookup.js <query>

1.1 Ten-minute onboarding path

If you are new and want confidence fast, follow this order:

1. Read ../CLAUDE.md quick reference + spinup checklist.
2. Read ../CODEBASE_MAP.md route/component tables.
3. Read ARCHITECTURE_FINDINGS_2026_03_23.md for state, runtime wiring, and likely breakpoints.
4. Open these implementation anchors:
   • src/layouts/BaseLayout.astro
   • src/config/navigation.js
   • src/modules/navigation.js
   • src/modules/site-explorer.js
5. Run:
   • npm run dev
   • npm run build
   • npm run check:security

If all three commands succeed, your local mental model and local toolchain are aligned.

2. Mental model

• 100% static. Astro builds to dist/. There is no runtime app server or database here.
• Routes come from files. src/pages/ maps directly to URLs (index.astro -> /, blog/[slug].astro -> /blog/:slug).
• One shared shell. Most pages use src/layouts/BaseLayout.astro for meta, OG, critical CSS, and layout slots.
• Three ways behavior gets in:
  1. .astro pages: compose layouts/components and pass props.
  2. Entry scripts: page-specific JS (src/main.js, src/research.js, src/engine.js, src/blog.js) that import src/modules/*.
  3. React islands: .jsx components mounted with client:load on selected routes.

3. Where to spelunk

src/pages/

Use this when you need to change a URL. Every file maps to a route. Some routes are intentionally outside primary nav (for example /game, /lab).

src/components/

• sections/: homepage blocks assembled by src/pages/index.astro.
• core/: reusable primitives (wrappers, cards, PDF links, embeds).
• Feature folders (research/, quiz/, playbook/, budget-chart/, food-desert/): scoped UI and related CSS/JS.

src/layouts/

BaseLayout.astro only — the shared document and SEO shell.

src/styles/

src/styles/global.css is the main import chain (base -> layout -> components -> sections -> pages). Prefer new focused files over adding to legacy.css. Design tokens live in src/styles/base/variables.css.

src/modules/

Browser ES modules for navigation, animation, engine logic, newsletter, and playbook behavior. They are not auto-loaded; each entry script imports what its page needs.

src/content/ and src/data/

Markdown content plus schema (src/content/) and static app data (src/data/) like plants.js and dev-playbook.json.

public/

Copied verbatim to dist/: PDFs, icon font subset, media, manifest.json, and _headers. Astro does not optimize images from public/; use src/assets/images/ with <Image /> when optimization matters.

scripts/

Build and ops scripts: CSP/SRI sync, security checks, blog CLI, map-lookup.js, and rollback tooling. See the scripts table in CODEBASE_MAP.md.

tests/

Node-based checks for accessibility, mobile, styles, and link/image helpers. Entry point: tests/run-all-tests.js.

_work_efforts_/

Johnny Decimal tracking (indexes, audits, devlogs). Use it for project history and decisions, not file lookup.

docs/ and wiki/

Human-facing guides, architecture findings, release notes, and CSP/release wiki docs.

• Latest system snapshot: docs/ARCHITECTURE_FINDINGS_2026_03_23.md

Config at repo root

• astro.config.mjs: Astro + React config and static output mode.
• wrangler.toml: Cloudflare Pages/Workers wiring.
• eslint.config.js, .stylelintrc.json, .prettierrc.json: lint/format rules.

4. Recipe book

5. Commands and failure triage

• Canonical command list: use the quick reference in ../CLAUDE.md.
• If behavior is broken but cause is unclear: use the troubleshooting matrix in ARCHITECTURE_FINDINGS_2026_03_23.md first.
• If you only run two commands here: run npm run build and npm run check:security.
• Minimum safety checks after substantial edits:
  • npm run build
  • npm run check:security

6. Sharp edges (read once)

• CSP: Inline style changes (especially in BaseLayout.astro) require a rebuild and committing any resulting public/_headers updates.
• IDs and anchors: Prefer constants from src/consts.ts over hardcoding duplicate ids.
• Images: Optimized pipeline = src/assets/images/; direct URLs = public/ (no build-time optimization).
• Legacy CSS: Avoid adding to legacy.css; add a focused stylesheet and import it from the appropriate layer.
• Map discipline: If you add routes, components, or scripts, update CODEBASE_MAP.md so the next spelunker does not inherit stale tables.

7. Suggested reading order for a new contributor

1. This guide (skim §2–§4).
2. CODEBASE_MAP.md §3 (pages + components + modules).
3. ARCHITECTURE_FINDINGS_2026_03_23.md for runtime/state/deploy risk.
4. src/pages/index.astro — see how the homepage stacks sections.
5. src/config/navigation.js — see how nav and sitemap stay in sync.

Welcome to the cave — bring CODEBASE_MAP.md as the laminated chart.