{"description":"Structured infrastructure decision system for choosing hosting, rendering, CMS, data, auth, forms, media, search, analytics, payments, DNS/CDN, security, deployment, and handoff tiers.","objective":"Give a future agent enough structure to start from the main URL and understand how to inspect, plan, build, validate, and improve a serious website without needing prior chat context.","infrastructure_decisions":{"objective":"Teach agents how to choose website infrastructure by decision tier instead of defaulting to a preferred platform.","why":"A good website is partly content and UX, but infrastructure determines what can be built, how safely it can launch, how much it costs to maintain, how quickly it loads, who can edit it, how data is protected, and how future agents can continue the work. Agents need explicit decision tiers so a brochure site does not inherit SaaS complexity and a transactional product does not ship on infrastructure that cannot support it.","decisionPrinciples":["Start with the simplest infrastructure that satisfies the verified requirements.","After requirements are clear, apply the owner-stack preference when it fits because familiar infrastructure reduces delivery risk and future-agent confusion.","Do not add runtime, database, auth, or CMS complexity until a real workflow requires it.","Separate launch requirements from future wishes; document future upgrade paths without building them prematurely.","Choose infrastructure that future agents can inspect, test, and hand off with evidence.","Treat privacy, security, compliance, ownership, backups, and rollback as first-order decisions, not cleanup tasks."],"ownerStackPreference":{"objective":"Bias infrastructure decisions toward Aaron's proven operating stack when it satisfies requirements, while preserving explicit override logic.","why":"A theoretically neutral stack can be worse in practice if it increases maintenance load, deployment friction, account confusion, or future-agent uncertainty. The correct decision should account for the infrastructure Aaron already knows, trusts, pays for, documents, and can hand off.","defaultStack":[{"layer":"source-control-and-collaboration","preferred":"GitHub","defaultUse":"Use as source of truth for code, issues/PRs when relevant, CI triggers, review history, and durable agent handoff.","why":"GitHub is the familiar shared workspace and keeps future-agent continuation anchored in repo state.","overrideOnlyIf":["Client requires another source host","Existing production repo already lives elsewhere","Compliance or enterprise policy requires another system"]},{"layer":"edge-hosting-and-dns","preferred":"Cloudflare","defaultUse":"Prefer for static or edge-friendly marketing sites, DNS/CDN, redirects, security headers, Pages/Workers where appropriate, and public performance/security surfaces.","why":"Cloudflare matches the existing infrastructure pattern for public sites and gives strong DNS/CDN/deploy primitives.","overrideOnlyIf":["Cloudflare account ownership is unclear","Client requires another host","Framework/runtime needs are better supported elsewhere","Existing domain/DNS governance makes another provider safer"]},{"layer":"content-and-marketing-framework","preferred":"Astro","defaultUse":"Prefer for marketing, SEO/AEO, documentation, local service, professional services, content-heavy, and agent-reference sites.","why":"Astro keeps static-first sites fast, inspectable, simpler to crawl, and easier to reason about for agents.","overrideOnlyIf":["The site is truly app-like","The team needs deep React app patterns","Request-time personalization is central","Shared component/runtime requirements point to another framework"]},{"layer":"app-framework","preferred":"Next.js","defaultUse":"Use when the build is a real app or app-adjacent system with auth, dashboards, dynamic user state, richer React UI, Stripe account flows, admin tools, SSR, or team familiarity reducing risk.","why":"Next.js is familiar and still a safe mainstream choice for serious React app work, but should not be the automatic choice for ordinary websites.","overrideOnlyIf":["Astro is enough because the site is mostly public/static","A lighter Vite/React app has no SEO/SSR need","A future app discussion chooses a different framework based on concrete requirements","The client/team has a stronger existing framework standard"]},{"layer":"payments","preferred":"Stripe","defaultUse":"Prefer for payment links, checkout, subscriptions, deposits, portals, invoices, and payment-webhook workflows unless commerce needs clearly point elsewhere.","why":"Stripe is the clearest known payment portal and supports both simple payment links and deeper app workflows.","overrideOnlyIf":["Shopify or commerce platform owns catalog/checkout","Client already has a required processor","Marketplace/tax/fulfillment needs exceed the planned Stripe setup","Compliance or geography requires another provider"]}],"frameworkDecisionRules":[{"id":"astro-first-for-websites","rule":"If the project is a website before it is an app, start with Astro.","chooseAstroWhen":["Mostly public pages","SEO/AEO matters","Content/reference/docs/local-service/professional-services site","Static-first delivery is enough","Cloudflare Pages deployment is a natural fit"],"chooseNextWhen":["Auth or dashboards are central","Per-user state drives the experience","SSR/server actions/API routes are central","React app familiarity materially reduces risk","Stripe portal/account flows require app-like behavior"],"agentCheck":"Can every requested dynamic feature be handled with static pages, forms, external tools, or small serverless functions? If yes, do not default to Next.js."},{"id":"next-js-not-by-habit","rule":"Do not pick Next.js only because it is familiar.","acceptableReasons":["The project is app-like","The user explicitly wants Next.js","Existing codebase is Next.js","Team maintenance favors Next.js","Required integrations are already built around Next.js"],"unacceptableReasons":["Default comfort alone","Marketing site with no runtime needs","A small content site where Astro is simpler","A desire to future-proof without concrete app requirements"],"agentCheck":"Write the exact app requirement that Astro cannot satisfy before choosing Next.js."}],"overrideEvidenceRequired":["State the default owner-stack choice that would normally apply.","State the requirement or constraint that makes the default weaker.","Name the alternative and its operational tradeoffs.","Identify migration, rollback, account ownership, and future-agent handoff impacts.","Record the decision in handoff evidence before implementation."],"antiBiasRules":["Owner-stack preference is a bias to reduce practical risk, not a rule to ignore requirements.","Do not recommend a different stack for novelty or model preference.","Do not recommend the owner stack if the project requirements clearly exceed it.","If Cloudflare account state matters, follow Cloudflare/Wrangler safety rules before any mutation.","If payment processing changes from Stripe, document why Stripe is not sufficient."]},"decisionAreas":[{"id":"rendering-and-hosting","name":"Rendering and hosting","objective":"Choose static, SSR, serverless, or application hosting based on update frequency, personalization, data needs, and operational complexity.","tiers":[{"tier":"static-cdn","chooseWhen":"The site is mostly public content, has no per-user state, and can rebuild when content changes.","examples":["marketing site","local service site","documentation hub","agent reference site"],"tradeoffs":["Fast and cheap","Simple rollback","Limited runtime personalization"]},{"tier":"ssr-or-edge","chooseWhen":"Pages need request-time data, personalization, localization, experiments, or frequent content changes without full rebuilds.","examples":["pricing by region","logged-out app marketing with dynamic content","large content library"],"tradeoffs":["More flexible","More moving parts","Requires runtime observability"]},{"tier":"application-platform","chooseWhen":"The website is also a product with accounts, dashboards, payments, workflows, or heavy integrations.","examples":["SaaS app","client portal","marketplace","member platform"],"tradeoffs":["Supports real app behavior","Higher maintenance","Security and data ownership matter more"]}],"agentQuestions":["Does any page require request-time data?","Can content updates wait for a rebuild?","What must happen if the host is down?","Who owns rollback?"],"guardrails":["Do not add SSR only for marketing copy","Do not host authenticated workflows as a static-only site","Document the deployment and rollback path before launch"]},{"id":"content-management","name":"Content management","objective":"Decide whether content belongs in code, files, a headless CMS, a visual CMS, or an app database.","tiers":[{"tier":"code-and-files","chooseWhen":"Developers or agents own updates and content changes are infrequent or review-heavy.","examples":["source-backed starter","technical docs","small service site"],"tradeoffs":["Version controlled","Strong review path","Less friendly for nontechnical editors"]},{"tier":"headless-cms","chooseWhen":"Nontechnical editors need structured content workflows, drafts, roles, scheduled publishing, or large content inventories.","examples":["resource library","multi-author blog","multi-location pages"],"tradeoffs":["Editor-friendly","Adds integration and schema drift risk","Needs backup/export plan"]},{"tier":"visual-builder","chooseWhen":"Marketing teams need fast visual iteration and accept platform constraints.","examples":["campaign landing pages","brand-managed microsites"],"tradeoffs":["Fast editing","Can hurt source traceability","Harder to enforce code-level QA"]}],"agentQuestions":["Who edits content after launch?","Does content require approval workflow?","Can source traceability survive the CMS?","How is content exported or backed up?"],"guardrails":["Do not choose a CMS without an ownership and backup plan","Do not let visual editing bypass claim/source rules","Keep schema and page content aligned"]},{"id":"data-and-state","name":"Data and state","objective":"Decide whether the site needs no database, lightweight storage, managed relational data, search index, or event stream.","tiers":[{"tier":"no-database","chooseWhen":"The site only serves public content and sends users to external contact or booking flows.","examples":["brochure site","proof site","agent reference"],"tradeoffs":["Lowest operational risk","No in-site records","External systems own state"]},{"tier":"managed-database","chooseWhen":"The site stores accounts, leads, orders, preferences, submissions, or workflow state.","examples":["portal","member site","lead database","commerce workflow"],"tradeoffs":["Persistent state","Needs backups and access control","Data model becomes a contract"]},{"tier":"specialized-indexes","chooseWhen":"The site needs full-text search, vector search, analytics events, queues, or high-volume logs.","examples":["large knowledge base","AI search","event-heavy product"],"tradeoffs":["Better retrieval/performance","More sync paths","More drift to monitor"]}],"agentQuestions":["What data is created by users?","What must be retained or deleted?","What is the backup and restore plan?","What data is private?"],"guardrails":["Do not store form data without retention and access rules","Do not introduce a database for content that can live in versioned files","Document migrations and restore tests"]},{"id":"identity-and-access","name":"Identity and access","objective":"Choose no auth, gated content, member auth, admin auth, or enterprise SSO based on real access needs.","tiers":[{"tier":"public-only","chooseWhen":"Every page can be public and no private data is collected.","examples":["marketing site","public docs","SEO resource hub"],"tradeoffs":["Simple","Crawlable","No personalization"]},{"tier":"simple-gates","chooseWhen":"Downloads, webinars, or resources need light qualification or email capture.","examples":["lead magnet","workshop registration","private PDF"],"tradeoffs":["Supports lead flow","Needs consent/privacy handling","Not true account security"]},{"tier":"full-auth","chooseWhen":"Users need accounts, private dashboards, roles, billing, or protected records.","examples":["member area","client portal","SaaS dashboard"],"tradeoffs":["Real access control","Security burden","Session and permission testing required"]}],"agentQuestions":["What content or data must be private?","Who can access admin tools?","Does the site need roles?","What happens when access is revoked?"],"guardrails":["Do not use client-side hiding for private data","Do not collect gated data without consent copy","Test role boundaries before launch"]},{"id":"forms-and-lead-routing","name":"Forms and lead routing","objective":"Choose contact links, embedded forms, managed form backends, CRM routing, or custom workflows based on lead value and operational needs.","tiers":[{"tier":"direct-contact","chooseWhen":"A phone, email, calendar, or external form is enough.","examples":["small service site","initial MVP"],"tradeoffs":["Simple","Less tracking","External system owns reliability"]},{"tier":"managed-forms","chooseWhen":"The site needs spam controls, notification routing, field validation, and saved submissions.","examples":["contact forms","quote requests","event registrations"],"tradeoffs":["Faster to ship","Vendor dependence","Privacy and retention rules needed"]},{"tier":"crm-workflow","chooseWhen":"Submissions need assignment, scoring, enrichment, automations, or sales handoff.","examples":["high-value B2B leads","multi-location intake","partner/referral intake"],"tradeoffs":["Better operations","More integration failure points","Requires tracking and consent alignment"]}],"agentQuestions":["Who receives submissions?","What fields are necessary?","What consent is needed?","How is spam handled?","What is the SLA?"],"guardrails":["Do not collect unnecessary sensitive fields","Do not route leads without testing notifications","Document where submissions are stored"]},{"id":"media-and-assets","name":"Media and assets","objective":"Choose local assets, optimized image pipeline, DAM, video host, or streaming platform based on volume, performance, and ownership.","tiers":[{"tier":"local-optimized-assets","chooseWhen":"The site has a small, stable asset set.","examples":["logo","social image","small proof screenshots"],"tradeoffs":["Versioned","Fast","Requires build optimization"]},{"tier":"managed-media","chooseWhen":"Editors upload assets frequently or there are many transformations/sizes.","examples":["blog images","case study galleries","team photos"],"tradeoffs":["Editor-friendly","Costs and vendor lock-in","Needs alt/metadata rules"]},{"tier":"video-platform","chooseWhen":"Video quality, privacy, captions, analytics, or streaming reliability matter.","examples":["course library","webinar archive","sales videos"],"tradeoffs":["Reliable playback","External dependency","Accessibility/caption QA required"]}],"agentQuestions":["Who uploads assets?","What formats and sizes are needed?","Do videos need captions or privacy?","What alt text is required?"],"guardrails":["Do not ship unoptimized hero media","Do not use stock-like assets when product/place proof matters","Do not publish video without captions when accessibility matters"]},{"id":"search-and-discovery","name":"Search and discovery","objective":"Choose no internal search, static search, hosted search, or AI/vector retrieval based on content depth and answer needs.","tiers":[{"tier":"navigation-only","chooseWhen":"The site has few pages and clear IA.","examples":["small service site","single offer site"],"tradeoffs":["Simple","No search maintenance","Navigation must be excellent"]},{"tier":"indexed-site-search","chooseWhen":"Users need keyword discovery across many pages or resources.","examples":["knowledge base","resource library","docs"],"tradeoffs":["Better discovery","Index freshness concerns","Needs noindex/private filtering"]},{"tier":"ai-retrieval","chooseWhen":"Users or agents need answer synthesis over source-backed content.","examples":["agent reference","technical docs","support knowledge base"],"tradeoffs":["Powerful answers","Citation and hallucination risk","Requires source boundaries"]}],"agentQuestions":["Can users find content through navigation?","What content must never be indexed?","Do answers need citations?","How is index freshness checked?"],"guardrails":["Do not expose private content to search indexes","Do not use AI retrieval without citations","Keep robots, llms, sitemap, and source boundaries aligned"]},{"id":"analytics-and-observability","name":"Analytics and observability","objective":"Choose privacy-light analytics, product analytics, server logs, uptime monitoring, and error tracking based on risk and decision needs.","tiers":[{"tier":"privacy-light-analytics","chooseWhen":"The site needs basic traffic and conversion visibility without heavy tracking.","examples":["marketing site","content site"],"tradeoffs":["Low privacy burden","Less granular","Good for launch basics"]},{"tier":"product-analytics","chooseWhen":"User behavior, funnels, cohorts, or feature usage drive decisions.","examples":["SaaS app","member area","conversion experiments"],"tradeoffs":["Better insight","Consent and privacy complexity","Event taxonomy required"]},{"tier":"operational-observability","chooseWhen":"Runtime errors, uptime, latency, queues, or integrations affect business outcomes.","examples":["SSR app","checkout flow","lead routing system"],"tradeoffs":["Faster incident response","More setup","Alert ownership required"]}],"agentQuestions":["What decisions will analytics support?","What events are necessary?","What consent is required?","Who receives alerts?"],"guardrails":["Do not install analytics without privacy review","Do not track sensitive fields","Do not launch runtime systems without error and uptime evidence"]},{"id":"payments-and-commerce","name":"Payments and commerce","objective":"Choose external checkout, embedded checkout, subscription billing, marketplace payments, or no payments based on transaction risk.","tiers":[{"tier":"no-payments-or-external","chooseWhen":"Sales happen by invoice, proposal, or external checkout link.","examples":["agency service","consulting","manual proposal"],"tradeoffs":["Simple site","Less integrated UX","External system owns payment risk"]},{"tier":"embedded-checkout","chooseWhen":"The site sells simple products, deposits, workshops, or subscriptions.","examples":["course sale","event ticket","membership"],"tradeoffs":["Better conversion","Needs tax/refund/terms clarity","Webhook reliability matters"]},{"tier":"custom-commerce","chooseWhen":"Orders, fulfillment, discounts, tax, inventory, entitlements, or marketplaces require custom logic.","examples":["commerce platform","multi-vendor marketplace","complex subscriptions"],"tradeoffs":["Flexible","High compliance and testing load","Requires operational ownership"]}],"agentQuestions":["What is being sold?","Are refunds, taxes, subscriptions, or entitlements involved?","What terms must appear before payment?","How are payment failures handled?"],"guardrails":["Do not build custom checkout unless needed","Do not hide refund/cancellation terms","Do not ignore webhook and receipt testing"]},{"id":"dns-cdn-security","name":"DNS, CDN, and security headers","objective":"Choose DNS/CDN/security posture based on host, risk, domain ownership, cache needs, and public exposure.","tiers":[{"tier":"basic-managed-dns","chooseWhen":"A low-risk static site only needs stable records and HTTPS.","examples":["starter site","small brochure site"],"tradeoffs":["Simple","Low overhead","Limited advanced protection"]},{"tier":"cdn-and-cache-control","chooseWhen":"Performance, global delivery, cache rules, redirects, or asset control matter.","examples":["content-heavy site","multi-region audience","large media"],"tradeoffs":["Better performance","Cache invalidation risk","Needs header testing"]},{"tier":"advanced-security-edge","chooseWhen":"The site has auth, payments, private data, public APIs, or attack exposure.","examples":["app with accounts","checkout","admin portal"],"tradeoffs":["Stronger controls","More configuration","Requires monitoring and incident plan"]}],"agentQuestions":["Who controls DNS?","Are redirects and canonical hosts defined?","What headers are required?","What is cached and for how long?"],"guardrails":["Do not mutate Cloudflare/Wrangler accounts without explicit account confirmation","Do not launch with unknown canonical host behavior","Do not cache private responses publicly"]},{"id":"deployment-and-handoff","name":"Deployment and handoff","objective":"Choose deployment workflow, preview environments, rollback, secrets handling, and evidence handoff based on team maturity and risk.","tiers":[{"tier":"manual-static-deploy","chooseWhen":"A small low-risk site can be deployed by a responsible operator with documented commands.","examples":["temporary microsite","internal reference"],"tradeoffs":["Simple","Human-dependent","Can drift without notes"]},{"tier":"ci-preview-deploys","chooseWhen":"Changes need review, preview URLs, automated tests, and safe rollback.","examples":["client site","production marketing site","multi-agent work"],"tradeoffs":["Better quality","More setup","Requires CI ownership"]},{"tier":"multi-environment-release","chooseWhen":"The product has staging, production data, migrations, integrations, or compliance review.","examples":["SaaS","portal","commerce"],"tradeoffs":["Controlled releases","Higher process cost","Requires release discipline"]}],"agentQuestions":["Where are secrets stored?","How are previews created?","How is rollback done?","What evidence must be generated before deploy?"],"guardrails":["Never commit secrets","Do not deploy without QA evidence","Do not leave handoff without commands, risks, and rollback notes"]}],"internationalisation":{"id":"internationalisation","objective":"Decide whether and how to localize before content scales, because retrofitting i18n onto a grown site is the most expensive version of the work.","decisionRule":"Localize when a measurable audience segment cannot buy or comply in the site language, not because a market might exist someday.","tiers":[{"tier":"deliberately-monolingual","chooseWhen":"The audience operates in one language and no regulatory or market evidence demands more.","examples":["this reference (en, documented as deliberate)","local service sites","single-market SaaS"],"tradeoffs":["Zero i18n complexity","Document the decision so it reads as chosen, not forgotten"]},{"tier":"localized-subpaths","chooseWhen":"Two to five locales with shared branding and a translation workflow that can keep parity.","examples":["/es/ subpath localization","docs in two languages"],"tradeoffs":["One domain and zone","hreflang pairs required on every localized page","Stale-translation risk needs a parity check"]},{"tier":"localized-domains-or-subdomains","chooseWhen":"Locales have separate legal entities, pricing, or search markets that justify independent properties.","examples":["country ccTLDs","regional subdomains"],"tradeoffs":["Strongest geo-targeting","Multiplies every QA, crawl, and evidence surface per locale"]}],"technicalRules":["html lang is always set (enforced by qa:seo even on monolingual sites).","hreflang must be reciprocal and include x-default when any second locale ships.","Canonical URLs and hreflang must agree; a localized page canonicalizing to another locale destroys the cluster.","Translate metadata, schema text fields, llms surfaces, and alt text with the copy, or the localized page fails the same QA gates as the original."],"agentQuestions":["Which locale demand is evidence and which is hope?","Who owns translation parity after launch?","Do prices, claims, and legal pages differ by locale?"],"guardrails":["No machine-translated pages without review on claim-bearing copy","No locale launch without its own QA evidence run"]},"siteTypeRecommendations":[{"siteType":"local-service","defaultTiers":["static-cdn","code-and-files","no-database","public-only","direct-contact","privacy-light-analytics"],"upgradeTriggers":["Multiple editors","CRM lead routing","location inventory","booking/payment workflow","large resource library"]},{"siteType":"b2b-saas","defaultTiers":["static-cdn or ssr-or-edge for marketing","headless-cms when marketing owns content","full-auth for app","product-analytics","operational-observability"],"upgradeTriggers":["Logged-in marketing personalization","trial signup","pricing experiments","docs search","security/compliance needs"]},{"siteType":"professional-services","defaultTiers":["static-cdn","code-and-files or headless-cms","managed-forms","indexed-site-search for insights library","privacy-light-analytics"],"upgradeTriggers":["Multi-author publishing","private client resources","webinar workflows","CRM scoring","credential/proof library scale"]},{"siteType":"agent-reference-or-docs","defaultTiers":["static-cdn","code-and-files","ai-retrieval when source citations exist","ci-preview-deploys","crawl/browser/contract QA"],"upgradeTriggers":["Large source corpus","authenticated internal docs","live tool execution","multi-repo documentation","model-evaluation harnesses"]}],"scenarioExamples":[{"id":"owner-stack-marketing-site","scenario":"Public marketing, local service, or professional-services website where SEO/AEO, fast load, source-backed copy, and simple handoff matter more than runtime app behavior.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Keeps source truth, review history, issues, CI, and future-agent continuation in one inspectable place."},{"layer":"framework","choice":"Astro","why":"Static-first pages are simpler to crawl, faster to ship, easier to audit, and enough when there is no account state."},{"layer":"hosting-dns-cdn","choice":"Cloudflare Pages plus Cloudflare DNS","why":"Matches owner infrastructure, supports fast static hosting, redirects, security headers, previews, and domain control."},{"layer":"forms","choice":"Managed form or direct contact path","why":"Avoids custom backend state until lead routing, CRM sync, or saved submissions are proven requirements."},{"layer":"analytics","choice":"Privacy-light analytics","why":"Gives launch visibility without heavy consent or event-taxonomy complexity."}],"decisionPath":["Confirm the site is public-first and does not require user accounts.","Confirm content can be generated from source files and rebuilt on changes.","Use Astro unless a concrete app requirement cannot be satisfied by static pages, forms, or small serverless functions.","Use Cloudflare only after account ownership and deployment target are clear.","Document upgrade triggers for CMS, CRM, auth, payments, or app behavior without building them early."],"explicitTradeoffs":["Nontechnical editing is weaker unless a CMS is later added.","Runtime personalization should be deferred or handled by small edge/serverless functions.","Lead data lives in the selected form/CRM system, not in the static site repo."],"qaEvidence":["npm run qa:all","npm run qa:domain","npm run qa:crawl-runner","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["Client requires Webflow or a visual CMS","Multiple editors need drafts and approvals","Content inventory is large enough to require CMS governance","Personalized app-like flows become launch requirements"],"blockedChoices":["Next.js chosen only because it is familiar","Custom database for ordinary contact forms","Cloudflare mutation without account confirmation"]},{"id":"technical-docs-agent-reference","scenario":"Documentation, specification, or agent-reference website where agents need to traverse files, endpoints, LLM summaries, route fixtures, schemas, and QA evidence.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Versioned docs, schemas, generated endpoints, and QA evidence need durable source control."},{"layer":"framework","choice":"Astro","why":"Static docs and machine-readable endpoints stay crawlable, inspectable, and easy for agents to reason about."},{"layer":"hosting-dns-cdn","choice":"Cloudflare Pages plus explicit well-known routes","why":"Static distribution, security headers, and discovery surfaces align with agent-readiness goals."},{"layer":"search","choice":"Static search or source-backed AI retrieval only when citations exist","why":"Agent answers must cite visible/source-backed content instead of synthesizing from private or stale data."},{"layer":"observability","choice":"Domain checks, crawl evidence, browser QA, and contract drift QA","why":"The product is only useful if discovery surfaces and machine contracts stay synchronized."}],"decisionPath":["Start from the main URL and confirm agents can discover manifest, file map, QA contract, LLM files, schemas, and fixture routes.","Keep docs and contracts in versioned source files before adding a CMS.","Expose structured JSON and schemas for every critical concept.","Add AI retrieval only after source boundaries, citation rules, and answer-evidence fixtures exist.","Treat every new endpoint as a contract with schema, registry entry, QA, and handoff evidence."],"explicitTradeoffs":["Static source files require repo access for edits, but preserve traceability.","Adding a CMS can improve editing but risks drift between prose, schemas, and QA contracts.","AI retrieval raises citation, privacy, and stale-source risks unless evidence is enforced."],"qaEvidence":["npm run qa:aeo","npm run qa:contracts","npm run qa:fixtures","npm run qa:all"],"overrideTriggers":["Large documentation team needs editorial roles","Private internal docs require auth","Live tool execution requires server runtime","Search volume requires a dedicated index"],"blockedChoices":["CMS added without export and source-traceability plan","AI retrieval without citations","Agent/API endpoint without method-aware QA"]},{"id":"next-app-with-stripe-portal","scenario":"App-like system with user accounts, dashboards, billing portal, checkout, account state, admin flows, or dynamic React UI where Next.js is justified by real runtime requirements.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Application changes need review, CI, deployment history, and rollback visibility."},{"layer":"framework","choice":"Next.js","why":"Auth, dashboards, API routes/server actions, dynamic user state, and richer React app patterns make Next.js a practical owner-stack choice."},{"layer":"payments","choice":"Stripe Checkout, Billing Portal, and webhooks","why":"Stripe handles payment collection, subscriptions, invoices, customer portal, and event-driven account updates."},{"layer":"data","choice":"Managed database with migrations and backups","why":"Accounts, entitlements, billing status, and admin workflows require durable state."},{"layer":"observability","choice":"Error tracking, uptime checks, logs, and webhook replay plan","why":"Runtime app behavior and payment flows need operational evidence beyond static crawl checks."}],"decisionPath":["Write the app requirement Astro cannot satisfy before selecting Next.js.","Identify the private data model, roles, auth provider, and account lifecycle.","Map every Stripe event that changes access, subscription, entitlement, or receipt state.","Define database backup, migration, rollback, and secret-management rules.","Add runtime, payment, auth, and webhook QA to the handoff report before launch."],"explicitTradeoffs":["Next.js adds runtime, dependency, deployment, and monitoring complexity compared with Astro.","Stripe simplifies payment collection but shifts correctness to webhook handling and entitlement logic.","Database-backed apps require backup, migration, access-control, and privacy policies."],"qaEvidence":["npm run qa:all","Payment webhook test report","Auth/role boundary test report","Database backup and rollback notes","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["The app is mostly public content and does not need accounts","Shopify owns commerce catalog and checkout","Existing production app uses a different framework","Compliance requires another payment or auth provider"],"blockedChoices":["Next.js for a simple content site","Stripe webhook launch without replay/test evidence","Private data stored without retention and access policy"]},{"id":"content-team-cms-site","scenario":"Marketing or resource website where nontechnical editors need drafts, approvals, scheduled publishing, structured content, or large content inventory management.","recommendedStack":[{"layer":"source","choice":"GitHub for code plus CMS export/backup","why":"Code and infrastructure stay versioned while content governance is handled by the CMS."},{"layer":"framework","choice":"Astro unless runtime personalization is required","why":"Static-first rendering keeps public content crawlable while consuming structured CMS content."},{"layer":"cms","choice":"Headless CMS with roles, schema, drafts, and export path","why":"Editors need workflow support, but future agents need content structure and backup evidence."},{"layer":"hosting","choice":"Cloudflare Pages with rebuild hooks or equivalent preview deploys","why":"Public content can remain static while editorial changes trigger rebuilds."},{"layer":"search","choice":"Indexed site search when the content library is large","why":"Navigation alone becomes insufficient once resources, articles, glossary, and comparison pages scale."}],"decisionPath":["Confirm who edits content and whether they can work through GitHub.","Define CMS content types, required source fields, approval workflow, and export/backup process.","Prove CMS content can still map to page patterns, schema, claim IDs, and LLM summaries.","Set preview and rebuild behavior before editors publish.","Document what content lives in code versus CMS."],"explicitTradeoffs":["CMS improves editing but introduces content/schema drift risk.","Preview and rebuild automation become part of launch readiness.","Source-traceability fields must exist in the CMS, not only in repo docs."],"qaEvidence":["CMS schema/export notes","Preview deploy evidence","npm run qa:aeo","npm run qa:crawl-runner","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["Only agents/developers edit content","Client requires a visual builder","Content changes are rare and review-heavy","Private editorial workflow requires an authenticated app"],"blockedChoices":["CMS with no export path","CMS fields that bypass claim/source rules","Visual builder that prevents route/schema/LLM QA"]},{"id":"commerce-or-workshop-checkout","scenario":"Site selling a workshop, deposit, subscription, productized service, or paid resource where payment is part of the public conversion path.","recommendedStack":[{"layer":"source","choice":"GitHub","why":"Offer copy, terms, checkout links, and handoff evidence need review history."},{"layer":"framework","choice":"Astro for simple public checkout paths; Next.js only for account/stateful purchase flows","why":"Most simple offers can link to Stripe without adding app runtime."},{"layer":"payments","choice":"Stripe Payment Links or Checkout first","why":"Stripe covers simple payment collection without custom checkout complexity."},{"layer":"forms-crm","choice":"Managed form or CRM routing for qualification","why":"High-touch offers often need qualification before or after payment."},{"layer":"legal-ops","choice":"Visible terms, refund/cancellation policy, receipts, and support path","why":"Payment conversion is not ready without buyer expectations and operational follow-through."}],"decisionPath":["Classify whether the site sells directly, collects deposits, or routes to invoice/proposal.","Use Stripe Payment Links or Checkout before custom payment UI.","State refund, cancellation, delivery, tax, and support expectations near the payment path.","Add webhooks only if access, fulfillment, receipts, or entitlement state must update automatically.","Test the full payment path before launch and save evidence."],"explicitTradeoffs":["Simple Stripe-hosted checkout is less customizable but safer and faster.","Custom checkout can improve UX but increases testing, compliance, and webhook burden.","Subscriptions require cancellation, portal, entitlement, and dunning decisions."],"qaEvidence":["Stripe test-mode checkout evidence","Terms/refund page evidence","npm run qa:seo","npm run qa:aeo","reports/handoff/generated-handoff-report.json"],"overrideTriggers":["Shopify owns catalog, inventory, tax, or fulfillment","Marketplace payments are required","Client already has a required processor","Entitlements require app accounts"],"blockedChoices":["Custom checkout without need","Payment path without refund/cancellation terms","Subscription without billing portal or support path"]}],"agentWorkflow":["Classify the site type and business model before choosing tools.","List the required workflows: edit content, collect leads, authenticate users, store data, take payment, search content, publish media, monitor runtime, and deploy safely.","For each workflow, choose the lowest tier that satisfies current requirements.","Document upgrade triggers separately from launch requirements.","Add guardrails for secrets, privacy, backups, rollback, canonical host, and data retention.","Map infrastructure choices back to QA evidence: route, SEO, AEO, browser, crawl, domain, copy, contract, and handoff checks.","Record remaining infrastructure risks in the handoff report."],"antiPatterns":[{"id":"platform-first-thinking","issue":"The agent starts with a favorite platform instead of requirements.","fix":"Classify workflows and choose tiers from explicit needs."},{"id":"premature-app-complexity","issue":"A public marketing site inherits auth, databases, and runtime hosting without a real workflow.","fix":"Default to static/CDN until dynamic behavior is required."},{"id":"cms-without-governance","issue":"A CMS is added without source traceability, permissions, backup/export, or approval workflow.","fix":"Define editor roles, content schema, export path, and claim rules before adoption."},{"id":"runtime-without-observability","issue":"SSR, serverless, integrations, or checkout launch without logs, alerts, and error evidence.","fix":"Add monitoring and incident ownership before launch."},{"id":"hidden-ops-ownership","issue":"The repo does not say who owns DNS, deploys, secrets, backups, analytics, or rollback.","fix":"Record ownership and commands in docs and handoff reports."}],"qaGates":["npm run qa:aeo","npm run qa:domain","npm run qa:crawl-runner","npm run qa:handoff","npm run qa:all"],"passCriteria":["Every major infrastructure area has tiered options, choose-when guidance, tradeoffs, agent questions, and guardrails.","Site-type recommendations give default tiers and upgrade triggers.","Agents can explain why the chosen infrastructure is enough for launch and what would trigger an upgrade.","Infrastructure choices map to QA and handoff evidence.","No infrastructure recommendation requires guessing a vendor account, secret, or deployment target."],"objectiveAlignment":"Adds the missing infrastructure decision layer so future agents can choose the right technical foundation for each website rather than treating all builds as the same template."}}