{
  "project": "gpu-pilot",
  "doc": "docs/superpowers/specs/2026-07-18-commutingcost-pilot-design.md",
  "title": "\u25c6 SPEC 7/18 \u2014 commutingcost.com redesign pilot (design spec: SEO/GEO/AEO + motion + conversion)",
  "oneline": "The design spec the plan implements. Approach C \u2014 balanced pilot slice: take one fully-realized vertical slice (homepage + metro-page template), do all four layers on it end to end, ship it, then fan the pattern out to the remaining pages and to multimodal + losingground. Defines the four success outcomes (get discovered / convert visitors / delight & shares / investor-ready polish), the GEO and AEO artifact set, the motion inventory with its Core Web Vitals guardrails, and the component kit both pilot pages establish.",
  "tldr": [
    "The pilot is NOT 'create SEO from scratch' \u2014 build_metros_seo.py already generates per-metro title, meta_description, h1, GEO intro paragraphs, a real faq[] and json_ld_facts from live DB numbers. The work is (1) RENDER it fully and server-side, (2) ADD the missing GEO/AEO artifacts, (3) SHARPEN conversion, (4) LAYER ON motion within a CWV budget.",
    "GEO (be cited by ChatGPT/Perplexity/Claude/AI Overviews): llms.txt + llms-full.txt, answer-ready structure with the quotable answer FIRST, an explicit freshness stamp, inline source citations, and a /methodology authority page as the canonical explainer. AEO: question H2s with 40-55 word answer paragraphs, a visible FAQ backed by FAQPage schema, and snippet-friendly comparison tables.",
    "HARD CONSTRAINT: motion must not blow Core Web Vitals (LCP<2.5s, CLS<0.1, INP<200ms) because CWV is itself a ranking signal \u2014 motion pays for delight AND must protect discovery. All motion is transform/opacity only, gated behind prefers-reduced-motion, and must never delay the LCP element.",
    "SPEC CORRECTION recorded by the plan (C-1): spec sections 7/10 mandate /usr/bin/python3 for the data pipeline. That is WRONG \u2014 it lacks pyarrow and every new script reads network parquet. Use venv/bin/python. Do not 'fix' the scripts back.",
    "Section 11 (design direction) is now CLOSED: Editorial Warm was selected, then extended with the per-page transit-vehicle motion system and GTFS-derived dominant mode. The live reference implementation is at commutingcost.com/preview/design-directions.html."
  ],
  "updated": "2026-07-18 07:39",
  "sections": [
    {
      "level": 1,
      "title": "Design Spec \u2014 commutingcost.com Redesign Pilot"
    },
    {
      "level": 3,
      "title": "SEO / GEO / AEO + Motion Design + Conversion \u2014 the vertical-slice pilot"
    },
    {
      "level": 2,
      "title": "1. Summary"
    },
    {
      "level": 2,
      "title": "2. Goals & success metrics"
    },
    {
      "level": 2,
      "title": "3. Scope"
    },
    {
      "level": 2,
      "title": "4. Current state (known; some pending live audit)"
    },
    {
      "level": 2,
      "title": "5. Design layers"
    },
    {
      "level": 3,
      "title": "5.1 Discovery \u2014 SEO / GEO / AEO"
    },
    {
      "level": 3,
      "title": "5.2 Motion \u2014 \"Claude Design\" (delight)"
    },
    {
      "level": 3,
      "title": "5.3 GTM \u2014 Conversion"
    },
    {
      "level": 2,
      "title": "6. Architecture & components"
    },
    {
      "level": 2,
      "title": "7. Content pipeline changes"
    },
    {
      "level": 2,
      "title": "8. Rollout plan"
    },
    {
      "level": 2,
      "title": "9. Testing & validation"
    },
    {
      "level": 2,
      "title": "10. Risks & open questions"
    },
    {
      "level": 2,
      "title": "11. Design direction \u2014 PENDING USER PICK"
    },
    {
      "level": 2,
      "title": "Appendix A \u2014 Pilot page inventory"
    },
    {
      "level": 2,
      "title": "Appendix B \u2014 Metro-page JSON-LD (shape, from existing `json_ld_facts` + `seo.faq`)"
    },
    {
      "level": 2,
      "title": "Appendix C \u2014 `llms.txt` (shape)"
    },
    {
      "level": 1,
      "title": "CommutingCost \u2014 the true dollar cost of commuting"
    },
    {
      "level": 2,
      "title": "Methodology"
    },
    {
      "level": 2,
      "title": "Metros (62)"
    },
    {
      "level": 2,
      "title": "Rankings"
    },
    {
      "level": 2,
      "title": "Attribution"
    }
  ],
  "stats": {
    "lines": 225,
    "words": 2499
  },
  "html": "https://board.certihomes.com/project-docs/gpu-pilot/docs-superpowers-specs-2026-07-18-commutingcost-pilot-design.html",
  "out_name": "docs-superpowers-specs-2026-07-18-commutingcost-pilot-design.md",
  "comments_api": "https://board.certihomes.com/api/doc-comments?project=gpu-pilot&doc=docs/superpowers/specs/2026-07-18-commutingcost-pilot-design.md"
}