Imported from enzo-prism/rebellious-aging (AGENTS.md). Install upstream with npx skills add enzo-prism/rebellious-aging. Copyright stays with the author.

Repository Guidelines

MCP Usage

Do not use any MCP tools or servers for this project. Work only with the local filesystem and shell commands.

Project Structure & Module Organization

App Router entry points live in app/; route files there should stay thin and import view components from src/views. Shared building blocks live in src/components, shadcn primitives in src/components/ui, reusable hooks in src/hooks, data helpers in src/data and src/lib, and third-party clients in src/integrations. Static assets remain in public/, static export output lands in out/, and Supabase assets (migrations plus functions/submit-quiz) live in supabase/.

Build, Test, and Development Commands

• npm install installs dependencies after cloning or whenever package.json changes (prefer npm to keep package-lock.json authoritative).
• npm run dev launches the Next.js dev server at http://localhost:3000.
• npm run llms regenerates public/llms.txt (canonical URLs, key sections, and the free-guides list) via scripts/generate-llms.ts.
• npm run sitemap writes public/sitemap.xml from static SEO routes plus blog, recipe, speaking-event, and guide entries. NOTE: this file is a build artifact only — the sitemap that actually ships is regenerated into out/sitemap.xml by app/sitemap.ts during next build (see "Generated Assets").
• npm run build:search regenerates public/search-index.json from content data files.
• npm run prerender audits route metadata coverage and writes public/seo-route-audit.json (it does not rewrite exported HTML).
• npm run build runs npm run llms, npm run sitemap, npm run build:search, next build, and npm run prerender in sequence.
• npm run build:dev runs a development-mode Next build (useful for debugging build output).
• npm run preview serves the production bundle locally for manual smoke-testing.
• npm run lint executes the TypeScript + React ESLint suite; keep the tree clean before opening a PR.
• npm run test / npm run test:unit runs the Vitest unit suite; npm run test:e2e runs the Playwright end-to-end suite in tests/e2e/ (route matrix, search, accessibility, readiness, performance).
• npm run readiness:verify runs the full pre-publish gate: regenerates SEO assets, then lint + build + unit + e2e.

Coding Style & Naming Conventions

Use TypeScript function components with PascalCase filenames (Team.tsx) and camelCase helpers (useQuizForm). Favor the @/ alias defined in tsconfig.json for internal imports. ESLint enforces React Hooks rules—fix dependency prompts instead of muting them. Tailwind utilities drive styling; pull shared patterns into src/components/ui. Keep the existing 2-space indentation, semicolons, and descriptive prop names. Treat generated files such as src/integrations/supabase/client.ts as read-only and regenerate via Lovable when credentials change.

Content, SEO, and Search Workflow

• Route metadata lives in src/data/seoRoutes.ts and powers App Router generateMetadata plus scripts/prerender.tsx.
• Blog metadata is in src/data/blogPosts.ts; blog bodies live in src/data/blogPostContent.tsx (keyed by post id). src/views/BlogPost.tsx is a thin renderer that looks up blogPostContent[postId].
• Search uses public/search-index.json, generated by scripts/build-search-index.ts from content data files.
• Free booklets/guides live in src/data/guides.ts (the Guide interface + guides array, with getGuideBySlug/getGuidePath helpers). They power src/views/Guides.tsx (/guides hub) and src/views/GuideDetail.tsx (/guides/[slug]), and feed the sitemap, search index, and llms.txt.
• src/lib/siteMetadata.ts supplies baseUrl, default descriptions, and social image defaults used by SEO helpers and sitemap generation.
• Title policy is intentionally minimal: the homepage title is Rebellious Aging | Age Boldly, Live Loudly (the / entry in src/data/seoRoutes.ts), static pages use concise titles from seoRoutes.ts, and blog/recipe/guide detail pages use the content title without a site-name suffix.
• src/components/seo/Seo.tsx is retained for JSON-LD and legacy non-route flows; route-level <title> and <meta name="description"> tags come from Next metadata, not that component.
• After editing SEO routes, blog metadata, or search-relevant content, rerun npm run build (or the specific llms / sitemap / build:search scripts) to keep public/ and the out/ export in sync.

Codex CLI Page Checklist

• Add the view component under src/views with a PascalCase filename.
• Register the route in app/ with a page.tsx that imports the view and exports generateMetadata. For a collection of items (guides/recipes/events), back it with a src/data/<name>.ts module and add a dynamic app/<seg>/[slug]/page.tsx with generateStaticParams.
• Add a matching SEO entry in src/data/seoRoutes.ts so generateMetadata and scripts/prerender.tsx stay aligned.
• Add the route to the native sitemap in app/sitemap.ts (this is the sitemap that ships) AND mirror it in scripts/generate-sitemap.ts. Detail/collection pages iterate their data module (see the guideEntries pattern in both files).
• Make the page searchable in scripts/build-search-index.ts — static pages via the STATIC_PATHS set, collections via a build…Docs builder wired into buildSearchIndex (see buildGuideDocs).
• If the page should be surfaced to LLM crawlers, add it to keyPaths (or a dedicated section) in scripts/generate-llms.ts.
• If the page is pillar-related, update the related CTA in src/views/PillarPage.tsx.
• Add navigation links in src/components/layout/Header.tsx and src/components/layout/Footer.tsx when the page should be discoverable.
• Add the route to tests/e2e/route-matrix.spec.ts (the routeMatrix array for static pages, or dynamicChecks for detail slugs) so the 200/heading/share-button contract is enforced.
• For blog updates: add metadata in src/data/blogPosts.ts and the post body (keyed by id) in src/data/blogPostContent.tsx.
• Regenerate generated assets after content updates: npm run llms, npm run sitemap, and/or npm run build:search (or just run npm run build).

Generated Assets (Do Not Hand-Edit)

• out/ is the static-export build output (next.config.js sets output: 'export'); it is overwritten by npm run build. (There is no dist/.)
• public/sitemap.xml is generated by npm run sitemap, but it is NOT the sitemap that ships. app/sitemap.ts (a native Next MetadataRoute.Sitemap) regenerates out/sitemap.xml during next build and that is what deploys. Edit app/sitemap.ts for the live sitemap and keep scripts/generate-sitemap.ts in sync.
• out/robots.txt is generated solely by app/robots.ts during next build (there is no public/robots.txt and no robots script).
• public/llms.txt is generated by npm run llms (scripts/generate-llms.ts).
• public/search-index.json is generated by npm run build:search.

Testing Guidelines

Tests are configured with Vitest (npm run test:unit) for unit/component coverage and Playwright (npm run test:e2e) for end-to-end specs under tests/e2e/ (route matrix, search, accessibility via @axe-core/playwright, readiness, and performance). Colocate unit specs next to the component (Component.test.tsx) or under tests/unit/; add browser specs under tests/e2e/. Run npm run readiness:verify (lint + build + unit + e2e) before opening a PR, and record any new test scripts in package.json.

Commit & Pull Request Guidelines

Recent commits use short, imperative messages (“Add Facebook group page”); keep that style and isolate scope per commit. Pull requests should provide a crisp summary, reference related issues or Supabase changes, include screenshots for UI work, and list manual verification steps. Re-run lint and build before requesting review.

Supabase & Environment

Environment secrets load from .env; never commit production credentials. Frontend builds expect NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY (the client in src/integrations/supabase/client.ts falls back to the legacy VITE_SUPABASE_URL/VITE_SUPABASE_ANON_KEY names only if the NEXT_PUBLIC_* ones are absent). The Supabase client under src/integrations/supabase is auto-generated—regenerate it after rotating keys instead of editing by hand. Develop edge functions with supabase functions serve submit-quiz, then deploy via supabase functions deploy. Keep supabase/config.toml aligned with dashboard settings so preview and production environments stay consistent.

Docs and References

The deeper architectural walkthrough is in docs/project-overview.md, the content map is in README.md, and the current metadata implementation is documented in docs/seo-metadata-implementation.md. Use those when adding new pages, CTAs, or SEO metadata so the site voice stays consistent.