{"description":"Structured real-site comparison contract for reference studies, scoring dimensions, reusable patterns, gaps, evidence, follow-up tasks, QA gates, and stress tests.","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.","real_site_comparisons":{"objective":"Make real-site learning repeatable by comparing target sites against reference studies with explicit dimensions, evidence, scoring, and follow-up tasks.","why":"Agents can overfit to one attractive site or ignore useful failures. A comparison contract forces them to separate reusable patterns, context-specific choices, and issues that should become QA or backlog work.","comparisonDimensions":[{"id":"entity-focus","label":"Entity and topical focus","why":"Strong sites make it clear what entity, market, services, and proof surfaces answer systems should associate with them.","evidenceSources":["/site-studies.json","/seo-aeo-evaluation.json","/aeo-geo-context.json"],"scoringQuestion":"Does the site reinforce a coherent entity and topic set without unsupported sprawl?"},{"id":"machine-readable-surface","label":"Machine-readable surface","why":"Agent and answer-engine readiness depends on llms files, schemas, sitemaps, crawl evidence, and context endpoints.","evidenceSources":["/llms.txt","/llms-full.txt","/schemamap.xml","/schema.json","/crawl-evidence.json"],"scoringQuestion":"Can a crawler or agent discover the site's purpose, facts, schema, and evidence without guessing?"},{"id":"crawl-and-domain-health","label":"Crawl and domain health","why":"A polished site can still fail common hostnames, metadata, H1s, response codes, or indexability checks.","evidenceSources":["/crawl-evidence.json","reports/crawl/","reports/domain/"],"scoringQuestion":"Do core crawl and domain variants produce clean evidence?"},{"id":"source-and-claim-safety","label":"Source and claim safety","why":"The best examples are not worth copying if they encourage unsupported claims or private-source leakage.","evidenceSources":["/source-traceability.json","data/working/","data/derived/"],"scoringQuestion":"Can visible claims, schema facts, and answer summaries be traced to approved source evidence?"},{"id":"design-operability","label":"Design operability","why":"Design should improve comprehension and evidence discovery instead of hiding the operating contract.","evidenceSources":["/design-system-contracts.json","/browser-visual-qa.json","reports/browser/"],"scoringQuestion":"Does the visual layer preserve scanning, responsiveness, accessibility, and QA evidence?"}],"scoringModel":[{"score":0,"meaning":"Missing or contradicted by evidence."},{"score":1,"meaning":"Present but weak, incomplete, or unsupported."},{"score":2,"meaning":"Adequate and source-backed, with clear follow-up."},{"score":3,"meaning":"Strong reusable pattern with evidence and low residual risk."}],"comparisonProfiles":[{"id":"nectiv-to-agent-reference","referenceStudyId":"nectiv-digital-seo-aeo-2026-06-04","target":"Agent Website Reference","why":"Nectiv provides a strong SEO/AEO pattern set plus concrete gaps that this reference should prevent through contracts and QA.","reusablePatterns":["Focused AI-search/AEO entity architecture","Commercial service pages mapped to specific buying jobs","Technology and method pages that make differentiation inspectable","Stable schema entities across page types"],"gapsToPrevent":["Missing llms.txt or llms-full.txt on AI-search positioned sites","www/TLS domain variant failures","Indexable pages missing H1 or meta description","Crawler-visible media or internal 4xx issues"],"mappedContracts":["/site-studies.json","/seo-aeo-evaluation.json","/crawl-evidence.json","/aeo-geo-context.json","/why-explanations.json"],"followUpTasks":["add-production-domain-and-crawl-evidence-runners","add-nectiv-derived-seo-aeo-checks","expand-site-study-library-across-site-types"]},{"id":"specification-website-to-agent-reference","referenceStudyId":"specification-website-agent-reference-2026-06-09","target":"Agent Website Reference","why":"Specification Website is a direct reference for the kind of agent-facing discovery, well-known surfaces, API hints, security headers, and documentation IA this product should learn from.","reusablePatterns":["LLM and well-known discovery surfaces are advertised through headers and routes","MCP, A2A, API catalog, sitemap index, RSS, and security policy are discoverable without visual browsing","Documentation IA uses stable category and detail routes","Security and policy headers are part of the public contract"],"gapsToPrevent":["External standards links aging into 404 or crawler-blocked states without classification","Documentation overview/detail pages duplicating title and H1 intent without rationale","API or agent endpoints being misclassified as broken HTML routes because method behavior is not tested separately"],"mappedContracts":["/site-studies.json","/real-site-comparisons.json","/aeo-geo-context.json","/crawl-evidence.json","/why-explanations.json"],"followUpTasks":["add-aeo-geo-model-context-fixtures","add-crawl-stress-suite","expand-site-study-library-across-site-types"]}],"comparisonWorkflow":["Choose a reference study from /site-studies.json.","Choose a target site or current build surface.","Score each comparison dimension from 0 to 3 with evidence.","Separate reusable patterns from context-specific patterns and anti-patterns.","Map each gap to a QA check, contract change, backlog task, or explicit non-action.","Record residual risk and evidence paths before claiming the comparison is complete."],"qaGates":["npm run qa:aeo","npm run qa:seo","npm run qa:crawl","npm run qa:browser","npm run qa:all"],"stressTests":["Compare a strong reference site and ensure at least one reusable pattern maps to a local contract.","Compare a weak reference site and ensure at least one anti-pattern maps to a QA check or task.","Remove the referenced site study and confirm QA fails.","Score a dimension without evidence and reject the comparison.","Ask an agent to justify the next task using the comparison profile."],"passCriteria":["Comparison dimensions are explicit and evidence-backed.","At least one comparison profile references an existing site study.","Profiles list reusable patterns and gaps to prevent.","Profiles map to local contracts and follow-up tasks.","QA validates referenced study IDs and roadmap/task links."],"warningCriteria":["A comparison has evidence but no follow-up task.","A reusable pattern is too brand-specific to adapt safely.","A score is plausible but lacks a cited evidence path.","A gap is context-specific and should become a non-action rather than a rule."],"failCriteria":["A comparison profile references a missing site study.","A comparison score has no evidence source.","A gap is identified but not mapped to a check, task, contract, or non-action.","An agent copies brand, copy, or assets from a reference site."],"objectiveAlignment":"Turns real-site research into durable operating-system improvements instead of informal inspiration."}}