Ecommerce AI Discoverability Audit

What it does

• Scores a brand across seven pillarsContent & AEO, Data ↔ Schema Unification, Entity Resolution, Authority & Trust Graph, Crawler & Protocol Directives, Agentic Commerce Readiness, Measurement & Feedback. Each pillar gets a 0–10 score, a severity band (strong / ok / weak / critical), and 1–3 findings tagged win / gap / risk.
• Gathers evidence directly from the live brandHomepage, sample PDP and PLP, robots.txt, sitemap, llms.txt, products.json, About / policy pages — plus bot-UA spoofing (Googlebot / GPTBot / ClaudeBot / PerplexityBot) to measure crawler-access parity, plus SERP / Wikidata / Trustpilot / press-coverage probes for entity and authority signals.
• Diagnoses parity contradictionsCurrency vs. TLD, schema vs. visible content, JSON-LD GTINs vs. /products.json barcodes, Organization sameAs vs. observable social presence, JS-injected review schema vs. SSR HTML, vendor-string drift across the catalog.
• Composes a 90-day roadmapThree 30-day sprints (Foundation / Content & Commerce / Authority & Loop) with each task tagged to its binding pillar, ordered to unblock downstream pillars first.
• Files the audit as a durable artifactMarkdown synthesis under wiki/syntheses/ for the prose record, and a TypeScript data file under viewer/app/data/ that the viewer renders into a brand-styled report at /audit/{brand}.
• Maintains the knowledge layerEvery audit cites back to wiki pages (concepts/audit-pillars, playbooks/fact-rich-product-pages, entities/llms-txt, concepts/data-unification-feed-vs-schema, etc.), and every audit can amend those pages when methodology evolves.

Tech stack

Engineering highlights

• H.01

  Framework-as-code

  The seven-pillar definition lives in a single TypeScript file (audit-template.ts) that the viewer imports directly. Per-brand audit files re-export the same types — when the framework evolves, the viewer picks it up automatically and every shipped audit gets a chance to amend in place.

• H.02

  Score-honesty rules baked into the methodology

  P07 (Measurement & Feedback) is largely merchant-side and not fully externally observable, so the audit pillar has an explicit rule: all-nulls defaults to 3.0/weak, not 2.0/critical — absence of external evidence ≠ evidence of absence. Every pillar has analogous guardrails to prevent over-reach.

• H.03

  Cross-artifact propagation as a named operation

  The amend operation requires propagating changes through the full chain (synthesis → viewer data → routes → index → log). Partial propagation is worse than none, and the operation’s log entry surfaces it.

• H.04

  Cross-check is semantic, not structural

  Different from lint (orphans, stale dates, missing pages), cross-check walks an audit against the methodology playbook it claims to implement and surfaces drift — items in the playbook not addressed by the audit, claims in the audit not supported by the playbook, scores that should match across artifacts but don’t.

• H.05

  Audit visualization is data-driven, not hand-built

  Every brand audit is a 30-line route component plus a data file. Adding a new brand never requires writing JSX; the report is a function of the data.

• H.06

  Adjacent-but-separate visualization layer

  The viewer is gitignored from the wiki and never appears in ingests, queries, or lint runs. Wiki content drives the viewer; the viewer doesn’t contribute back.

What it demonstrates

• Operationalizing AI discoverability — translating the diffuse "GEO / AEO / agentic commerce" surface area into a fixed, scoreable checklist with explicit severity bands and named binding constraints.
• Treating an audit framework as software: pillar definitions, severity rules, scoring guardrails, and sidebar surfaces live in one canonical location and flow into both prose and visualization.
• LLM-as-auditor pattern with structured outputs — every audit follows the same schema, cites the same wiki framework, and propagates into the same downstream artifacts. Repeatable enough to baseline a brand, re-score it 90 days later, and surface the delta.
• Disciplined separation between raw evidence, synthesized findings, control-plane configuration, and presentation layer — each with its own conventions and rules of engagement.