interface:
  display_name: "Suede SEO Audit"
  short_description: "Evidence-led SEO and AI visibility audit"
  default_prompt: "Use $suede-seo-audit to audit [URL or source file]. Read the current Google guidance reference, inspect live behavior, and run all nine lanes: technical access, search and answer intent, metadata, structure, eligible structured data, generative-search visibility, copy and conversion quality, E-E-A-T, and topic clusters. Add Lane 0 query research when discovery is requested, but label demand and competitive difficulty unknown unless a dated source supports them. Return ranked findings with evidence, exact rewrites, lane grades, and a ship gate."
policy:
  allow_implicit_invocation: true

# Current Google Search Guidance

Use this reference before applying SEO, AEO, generative-search, metadata, or
structured-data findings. It records the primary-source baseline verified on
2026-07-19. Re-check the linked documentation when the current rule affects a
ship decision.

## Generative search

Google Search states that its generative features rely on the same foundational
SEO practices as ordinary Search.

- Google Search does not use `llms.txt` or similar AI text files for visibility
  or ranking. Such a file may serve another explicitly documented consumer,
  but its presence is neutral for Google Search.
- No AI-specific schema or markup is required.
- There is no requirement to split content into tiny chunks or rewrite it for
  AI systems.
- Write useful, accessible, sourceable content for people. Do not create
  repetitive variants for every synonym or long-tail query.

Source: [Google's guide to optimizing for generative AI features](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)

## Keywords and content length

- Google defines unnatural repetition intended to manipulate rankings as
  keyword stuffing.
- There is no universal keyword-density target or ideal page length.
- Evaluate whether the page uses the entity and subject language naturally and
  answers the reader's intent. Do not prescribe repetitions per 1,000 words.

Sources:

- [Spam policies for Google web search](https://developers.google.com/search/docs/essentials/spam-policies)
- [SEO Starter Guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide)

## Titles and snippets

- The HTML `title` element and meta description have no fixed Google character
  limit. Search results truncate them as needed for the device and query.
- Google may generate title links and snippets from page content and other
  signals instead of using the supplied fields verbatim.
- Character counts are useful preview diagnostics, not pass/fail ranking rules.

Sources:

- [Influencing title links](https://developers.google.com/search/docs/appearance/title-link)
- [Controlling snippets](https://developers.google.com/search/docs/appearance/snippet)

## Structured data

- Markup must represent visible page content, use a supported type when Google
  Search appearance is the goal, and satisfy that feature's required fields.
- Valid markup creates eligibility; it does not guarantee a rich result.
- FAQ rich results are generally limited to authoritative government and health
  sites. Do not promise FAQ visibility to ordinary product or marketing sites.
- Use the Rich Results Test for Google eligibility and Schema.org Validator for
  general vocabulary/shape checks. Record which validator was used.

Sources:

- [General structured data guidelines](https://developers.google.com/search/docs/appearance/structured-data/sd-policies)
- [Google-supported structured data features](https://developers.google.com/search/docs/appearance/structured-data/search-gallery)
- [FAQ and HowTo search appearance changes](https://developers.google.com/search/blog/2023/08/howto-faq-changes)

## Evidence boundary

Search Console, analytics, third-party SEO tools, and live SERPs measure
different things. Name the source, market, scope, and date. If a metric or
result was not observed, mark it unknown. Never convert a heuristic into a
traffic, ranking, citation, or conversion promise.

# Lane 0: Evidence-Based Keyword Research

Read this file only when keyword discovery is requested. Lane 0 produces a
brief, not a grade.

**Goal:** identify a defensible query theme and content gaps without inventing
search demand, ranking difficulty, or traffic potential.

## Evidence rules

- Record the source, market, device scope, and observation date for every
  numeric search-volume, traffic, CPC, or ranking claim.
- Prefer current first-party data: Search Console queries, site analytics,
  Google Ads Keyword Planner exports, or another user-supplied dated export.
- If no numeric source is available, write `volume: unknown`. Do not infer a
  monthly range from query length, topic breadth, or intuition.
- Distinguish an observed SERP from a ranking guarantee. Search results vary by
  time, location, device, and personalization.
- Do not manufacture difficulty scores. Describe the visible competition and
  evidence instead: result types, recognized domains, page intent, content
  depth, and the target site's existing authority or coverage.
- Use `related topics and entities`, not `LSI keywords`. Include terms only
  when they help a reader understand the subject.

## Protocol

1. **Primary query theme:** choose one phrase or tightly related query family
   that matches the page's purpose. Classify intent as informational,
   navigational, commercial, transactional, or mixed. Cite the evidence used.

2. **Supporting query themes:** list 3-5 related queries that serve the same
   reader without forcing unnatural repetition. Mark each as observed in a
   source, seen on the live SERP, or inferred from the subject.

3. **Related topics and entities:** list the people, products, standards,
   concepts, and subtopics a complete answer should cover. Group them by
   reader need. This is a coverage map, not a density quota.

4. **Competitor content gap:** when competitor URLs are supplied or a live
   search is authorized, inspect the current pages. For each competitor:

   a. Record the URL, access date, title, and relevant H2/H3 sections.
   b. Identify useful subjects the target page omits.
   c. Classify each gap as `critical`, `important`, or `optional` based on
      reader intent, not presumed ranking impact.

   Output:

   ```text
   Competitor: [URL] (checked [YYYY-MM-DD])
   Missing subject: [subject or heading]
   Evidence: [what the competitor covers and the target omits]
   Reader value: [why this helps answer the primary intent]
   Priority: [critical | important | optional]
   ```

   If live competitor pages were not checked, say so. Do not invent their
   headings, rankings, or traffic.

5. **Search-feature eligibility:** name only features supported by current
   Google Search documentation for the page type. Separate:

   - technically eligible;
   - validated in the Rich Results Test;
   - observed in a live result;
   - not verified.

   Structured data can make a page eligible for a supported feature; it does
   not guarantee display.

## Content brief

Generate this only when Lane 0 is active and a page is being built or
substantially revised.

| Field | Guidance |
|---|---|
| Reader and job | Name the reader, question, and useful outcome. |
| Primary query theme | Phrase or query family, intent, evidence source, market, and date. |
| Demand evidence | Numeric value with dated source, or `unknown`. |
| Competitive evidence | URLs and observations checked live, or `not checked`. |
| Required sections | Subjects needed to answer the reader completely; do not copy competitor headings mechanically. |
| Related topics/entities | Natural coverage map; no occurrence quota. |
| Schema eligibility | Supported Google feature and required properties, or `no supported rich-result type identified`. |
| Internal links | Verified anchor text and destinations that help the reader continue. |
| External sources | Current primary or authoritative sources for factual claims. |
| Length | Whatever is needed to answer the intent clearly. Do not assign a universal word-count target. |

## Output

```text
Primary query theme: [query family]
Intent: [informational | navigational | commercial | transactional | mixed]
Evidence source: [source, market, device scope, checked date]
Demand: [sourced value/range | unknown]
Visible competition: [observations with URLs | not checked]
Supporting query themes: [query — observed/inferred — evidence]
Related topics and entities: [grouped list]
Content gaps: [subject — evidence — reader value — priority]
Search-feature eligibility: [feature — eligible/validated/observed/not verified]
Content brief: [reader-first section and source plan]
```

Incorporate this brief into Lanes 2-7 where relevant. Never turn missing
numeric tooling into fabricated precision.

# Lane Checklists

Detailed checklists for suede-seo-audit Lanes 1–4 and 6–9. Read the checklist
for each lane as you run it. Lane 5 (Schema Markup) lives in
references/schema-templates.md. Grade-drop rules and scoring live in SKILL.md.

## Contents

- [Lane 1: Technical Access](#lane-1-technical-access)
- [Lane 2: Search and Answer Intent](#lane-2-search-and-answer-intent)
- [Lane 3: Metadata](#lane-3-metadata)
- [Lane 4: Structure](#lane-4-structure)
- [Lane 6: AI EO (Answer Engine Optimization)](#lane-6-ai-eo-answer-engine-optimization)
- [Lane 7: Copy and Conversion Quality](#lane-7-copy-and-conversion-quality)
- [Lane 8: E-E-A-T Signals](#lane-8-e-e-a-t-signals)
- [Lane 9: Topic Cluster Architecture](#lane-9-topic-cluster-architecture)

---

## Lane 1: Technical Access

- [ ] HTTP status is 200 on the canonical URL
- [ ] Redirects reach the intended canonical without loops or avoidable chains;
      record every hop and its status rather than claiming a fixed equity loss
- [ ] Canonical URL is self-referencing and matches the intended URL
- [ ] Trailing slash is consistent across all internal links to this page
- [ ] www and non-www resolve to the same canonical (no duplicate indexing)
- [ ] http redirects to https (no mixed-content split)
- [ ] `robots.txt` permits the intended Google crawler. Record `*` and
      `Googlebot` rules separately. Check other named crawlers only when the
      audit asks for them; one crawler's rule does not represent another's.
- [ ] `<meta name="robots">` is absent or set to `index, follow`
- [ ] If the site publishes a sitemap, the canonical URL is represented where
      appropriate; `<lastmod>` is present only when it accurately reflects a
      significant page update. A sitemap is a discovery aid, not a guarantee.
- [ ] Compare raw HTML with the rendered DOM. If primary content depends on
      JavaScript, verify the rendered result with an appropriate browser and,
      when available, Google URL Inspection rather than failing it merely for
      using JavaScript.
- [ ] Core Web Vitals measurement protocol (see below — never enters the A-F
      grade)

### Core Web Vitals (measure when possible — never part of the A-F grade)

Measurement protocol:

- [ ] Run `curl -o /dev/null -s -w "%{time_total}" <URL>` as a proxy for server
      response time. curl measures server response, not browser rendering — on
      its own it is never a CWV score.
- [ ] If PageSpeed Insights is accessible at pagespeed.web.dev, fetch it.
      Report LCP, CLS, INP against these thresholds:
      LCP ≤ 2.5s = Good, 2.5–4s = Needs Improvement, >4s = Poor.
      CLS ≤ 0.1 = Good, 0.1–0.25 = Needs Improvement, >0.25 = Poor.
      INP ≤ 200ms = Good, 200–500ms = Needs Improvement, >500ms = Poor.
- [ ] If tooling is unavailable, report each vital as "not measurable" with the
      reason, and record implementation signals to investigate without turning
      them into invented CWV scores: render-blocking work, hero-resource
      priority, image dimensions/compression, font loading, main-thread work,
      long tasks, third-party code, and layout shifts. Do not lazy-load the LCP
      image by rote or prescribe `preconnect`, a format, or code splitting
      without a trace showing the bottleneck.

Do not invent scores; do report observable risks. CWV never enters the lane's
A-F grade.

---

## Lane 2: Search and Answer Intent

- [ ] Name the primary reader in one phrase (e.g., "a creator who wants to
      register a music release")
- [ ] Name the primary query theme (what someone types or asks to land here)
- [ ] Write a standalone definition from the opening section: "[Entity] is
      [what it does] for [who] by [how]." If the page cannot support one,
      report the ambiguity and reader impact. This is a Suede clarity
      diagnostic, not a Google ranking requirement.
- [ ] Name one action the page should earn (install, sign up, read docs, fork
      repo, contact)
- [ ] Check for keyword cannibalization: are there three or more other pages on
      the same site targeting the same primary term? If yes, flag which URL
      should be the canonical topic owner
- [ ] Does the page answer a question a person would plausibly ask aloud?
- [ ] Is the primary intent clear in the opening section without relying on a
      universal word-count cutoff?

---

## Lane 3: Metadata

**Title tag**
- [ ] Present, concise, descriptive, and specific to this page
- [ ] Primary subject or entity is identifiable without forced front-loading
- [ ] Brand naming and separators are accurate and consistent; no separator is
      treated as a ranking requirement
- [ ] Accurately matches the page and visible main heading
- [ ] Does not start with "Welcome to" or the domain name
- [ ] Character count recorded as a preview diagnostic only. Google has no
      fixed title character limit and truncates to fit the result context.

**Meta description**
- [ ] Present and accurately summarizes this page
- [ ] Contains the primary outcome or action, not a feature list
- [ ] Does not duplicate the title
- [ ] Does not contain structured data markup or JSON
- [ ] Character count recorded as a preview diagnostic only. Google has no
      fixed meta-description character limit and may use page content instead.

**Open Graph**
- [ ] og:title and og:description are accurate and preview-tested on the target
      social surfaces; no unsupported universal character cutoff is applied
- [ ] og:image: set and preview-tested at the target platform's current
      recommended dimensions/crop; meaningful content survives cropping
- [ ] og:url: matches canonical URL
- [ ] og:type: set to `website`, `article`, or appropriate type

**Twitter/X card**
- [ ] twitter:card: `summary_large_image` for pages with a hero image
- [ ] twitter:title and twitter:description: set and distinct from OG when
      appropriate
- [ ] twitter:image: set and accessible without authentication

**Other**
- [ ] Informative images have contextual alt text; decorative images use empty
      alt text or equivalent semantics instead of redundant descriptions
- [ ] Author or publisher entity name appears in metadata or schema (not just
      visible copy)
- [ ] Durable entity names are consistent across relevant metadata and visible
      content without requiring repetition in every field

---

## Lane 4: Structure

**Headings**
- [ ] One clear page-level heading or equivalent semantic main heading matches
      the title intent. Multiple H1 elements are not failed solely by count;
      judge hierarchy and accessibility in the actual document.
- [ ] H2s cover the primary sub-topics a searcher would expect
- [ ] H3s are optional but used consistently if present
- [ ] Headings are concise enough to scan and specific enough to identify their
      section; no universal word cutoff is applied

**Retrieval chunking**
- [ ] No heading section exceeds ~375 words (500 tokens), the largest chunk
      Google's Discovery Engine (Vertex AI Search) retrieves. Measure the prose
      between one heading and the next, excluding `<nav>` and `<footer>` chrome.
- [ ] An accordion, tab set, or FAQ whose items are marked up with `<summary>`,
      `<button>`, or `<div>` rather than headings counts as ONE block, however
      many items it holds. Valid FAQPage JSON-LD does not fix this: the schema
      can describe a structure the prose does not have, and a schema-only pass
      is the most common way this defect survives an audit.
- [ ] Each claim worth citing sits inside one chunk together with the heading
      that identifies it. A claim split across a boundary can be retrieved
      without the heading that gives it meaning.
- [ ] Record the largest block's word count and its heading as evidence, not a
      pass/fail alone. A section within ~10% of the limit is worth flagging,
      since routine copy edits push it over.

Chunking check output format:
```
Largest block: [N] words under "[heading]" | limit ~375 | [within/over]
Blocks over limit: [count] of [total headings]
Accordion/FAQ items marked up as headings: [yes/no — N items]
```

**Heading self-sufficiency**
- [ ] Every H2-H6 names its own subject. Discovery Engine carries the ancestor
      headings alongside a chunk OPTIONALLY, so a chunk can arrive holding only
      its own immediate heading. This is NOT the hierarchy check above: a page
      can nest H1 > H2 > H3 perfectly and still have an H3 that identifies
      nothing once detached.
- [ ] No heading is a bare stock phrase — How it works, Pricing, Features,
      Overview, Benefits, FAQ, Get started, Why us, Our process. An H3 reading
      "Pricing" is meaningless away from the H2 that named the subject;
      "How Suede Scan pricing works" survives alone.
- [ ] Single-word headings get the hardest look, since they carry a subject only
      by accident. A heading already holding a proper noun, an acronym, or the
      page's primary subject passes — do not rewrite it.
- [ ] Record each finding with its parent heading, so the fix (folding the
      parent's subject into the child) is visible without opening the page.
- [ ] Warn, never fail, and never drop a grade on this alone. It is a heuristic
      about language. Where bare headings run through the whole page, report one
      finding about the page rather than one per heading.

Heading self-sufficiency output format:
```
Detached heading "[heading]" (H[n], under "[parent]") | [stock phrase/single word] | fix: "[rewritten heading]"
Sub-headings not naming their own subject: [count] of [total]
```

**Table markup**
- [ ] Comparison content uses `<table>`, not CSS grid or flex `<div>`s.
      Discovery Engine parses tables as structured content; a grid-built table
      reads as an undifferentiated run of text, so the row and column
      relationships that make a comparison quotable are lost.
- [ ] Structure carries the finding, never a class name: repeated sibling
      elements with a consistent child count, holding short cell-sized text.
      Confirm the content is genuinely tabular by eye before reporting it.
- [ ] Class names are the weakest signal and prove nothing alone. `flex-row`,
      `grid-rows-*`, `flex-col` and `grow-0` are layout utilities — measured
      against live homepages on 2026-08-22, a substring match on grid|row|col
      fired on four of five.
- [ ] Report as an informational observation, never as a scored failure. CSS
      grid is used for every kind of layout, and a false finding in a paid audit
      costs more than a missing one.
- [ ] A page that already ships a real `<table>` gets the benefit of the doubt:
      the author knows the element, so a grid there is more likely deliberate.

Table markup output format:
```
Unmarked table: [rows] rows x [columns] columns of <[tag] class="[class]"> | tabular by eye: [yes/no]
Page uses <table> anywhere: [yes/no]
```

**Section coverage and order**
- [ ] Opening: what the page is and who it serves
- [ ] Evidence appears near the claims it supports
- [ ] Instructions or explanation follow the reader's natural task order
- [ ] Objections or common questions are addressed when they materially help
- [ ] CTA placement matches the page's funnel stage and does not hide the answer

**Links**
- [ ] Internal links use descriptive anchor text (not "click here" or "read more")
- [ ] Internal links connect to relevant destinations where they help the user
      or discovery; no arbitrary link quota is applied
- [ ] No internal links are broken (verify with fetch or curl)
- [ ] External links go to authoritative sources when making factual claims
- [ ] Link behavior is accessible and predictable. Opening a new tab is a UX
      decision, not an SEO requirement; warn users when a new context opens.

**FAQ (only when useful to the reader)**
- [ ] FAQ section is present only when distinct recurring questions warrant it
- [ ] Each FAQ item is a real question a user or searcher would ask
- [ ] Each FAQ answer is self-contained (the answer makes sense without reading
      the question)
- [ ] Each answer is as short as clarity permits and as long as accuracy needs;
      no unsupported universal word limit is applied

**Topic and entity coverage**
- [ ] The title, H1, and opening make the primary subject unambiguous using
      natural language; exact-match repetition is not required
- [ ] Supporting subjects and entities needed for a complete answer are covered
      where they help the reader
- [ ] No term is repeated unnaturally or inserted solely to manipulate ranking
- [ ] Synonyms and related language are used for clarity, not to satisfy a quota

Coverage check output format:
```
Primary subject "[subject]": title [clear/unclear] | H1 [clear/unclear] | opening [clear/unclear]
Supporting subject/entity "[name]": [covered/missing/not needed] | evidence: [section or selector]
Natural-language check: [clear | repetitive | stuffed] | evidence: [quoted text]
```

---

## Lane 6: AI EO (Answer Engine Optimization)

**Summary and definitions**
- [ ] The opening section contains a clear answer to the page's primary
      question. The answer can stand alone without surrounding context.
- [ ] The product, skill, or service is defined plainly in the first section,
      not assumed
- [ ] No jargon is used without an inline definition on first use
- [ ] Definitions are written as `[Term] is [concise definition].` not buried in
      nested clauses

**Contrast and comparison**
- [ ] Where the subject has named alternatives, a competing approach, or a
      do-nothing option, the page states at least one difference in its own
      words. Google's Discovery Engine (Vertex AI Search) ranks with a
      cross-attention model that reads negation and contrast directly, so
      "unlike X, this does Y" carries meaning that embedding similarity alone
      flattens away. Quote the sentence as evidence; the presence of the word
      "unlike" is not the check.
- [ ] Comparative framing the page already promises is delivered in the body. A
      title, H1, or URL containing "vs", "alternative to", "best ... for", or
      "without ..." commits the page to naming the other option and the
      difference. This is the most common way the gap survives an audit: the
      framing sits in the metadata and nowhere in the prose.
- [ ] Segment framing ("best for {segment}") and constraint framing ("without
      {constraint}") appear where the page genuinely serves a narrower reader
      than its category does. Do not add a segment the product does not serve
      or a constraint it does not remove.
- [ ] A page whose subject has no alternatives and no competitors passes with no
      contrast content at all. Mark it N/A and name why in one line. No
      comparison quota is applied, and a page does not improve by acquiring a
      rival it does not compete with.

Contrast check output format:
```
Alternatives in scope: [named list | none — reason]
Contrast statement: [quoted sentence | absent] | location: [section or selector]
Comparison promised by title/H1/URL: [quoted phrase | none] | delivered: [yes/no]
Segment or constraint framing: [quoted | not applicable]
```

**Answer and source quality**
- [ ] Answers use the format that best serves the content: prose, steps, table,
      or list. Do not claim one format receives automatic citation preference.
- [ ] Ambiguous pronouns do not obscure the subject
- [ ] Material factual claims link to a current primary or authoritative source

**Entity signals**
- [ ] Company/product identity is explicit and consistent in the places where
      readers and parsers need it; schema is included only when warranted
- [ ] Any `sameAs` links identify the same entity and point only to verified
      external profiles. Omit the property when no verified profile exists.
- [ ] URL is stable and descriptive where practical; an opaque legacy URL is
      not treated as a ranking failure by itself

**Accessible content and optional machine-readable files**
- [ ] Record `llms.txt` or another AI-specific file only when a named consumer
      documents support. State explicitly that Google Search ignores
      `llms.txt`, so it neither helps nor harms Google visibility.
- [ ] Primary content is present in the tested rendered output. Record raw-HTML
      dependence as a cross-client/latency risk, not an automatic Google block.
- [ ] Any paywall or auth gate is documented so the audit does not claim that
      inaccessible content was evaluated
- [ ] Headings identify their subject clearly for readers and assistive
      technology; no unverified citation advantage is claimed

**Hallucination risk**
- [ ] Page does not make vague claims an LLM could cite incorrectly (e.g.,
      "used by thousands" without evidence. State the real proof or remove it.)
- [ ] No stat, partner name, or pricing claim is present without a verification
      source

---

## Lane 7: Copy and Conversion Quality

**Directness**
- [ ] First sentence names the outcome, not the feature (outcome: "Register a
      music release with rights and provenance"; feature: "A platform for music
      metadata")
- [ ] No throat-clearing openers ("Welcome to", "In today's digital landscape")
- [ ] Active voice with a named actor in each key sentence
- [ ] Subhead adds proof, audience, or workflow, not a restatement of the hero

**Proof**
- [ ] At least one real artifact: link, command, screenshot reference, file
      name, live URL, or example
- [ ] No invented stats, testimonials, partner names, pricing, or availability
      claims
- [ ] Proof appears before the CTA, not after

**Claims**
- [ ] Every superlative ("only", "best", "first") is either verifiable or
      removed
- [ ] Legal, payment, privacy, or regulatory claims are accurate and sourced
- [ ] Product capabilities described match what is currently shipped and live

**CTA**
- [ ] The primary action is discoverable at the point the target reader is
      ready for it; no fixed fold placement is assumed
- [ ] CTA text is an action + object ("Install the skill", not "Get started")
- [ ] CTA hierarchy is understandable in rendered desktop/mobile tests; do not
      impose a universal count without observing task confusion

**Trust**
- [ ] If testimonials are present, they are real and attributable
- [ ] If testimonials are absent, copy does not imply them
- [ ] Brand vocabulary matches the actual product (no generic AI-music-app
      language when the product does rights infrastructure)

**Filler removal**: the test — if a sentence can be deleted without the reader
losing information, delete it. Apply to transitions, throat-clearing, hedging,
adverb softeners, and exclamation marks.

Flag and remove:
- [ ] Filler transitions ("Additionally", "Furthermore", "It is worth noting")
- [ ] Exclamation points in body copy
- [ ] Em dashes in public copy (use a comma, period, or recast the sentence)
- [ ] Adverb softeners ("simply", "just", "easily", "seamlessly")

---

## Lane 8: E-E-A-T Signals

Use E-E-A-T as a human quality and trust lens. Google describes E-E-A-T as a
concept used by search quality raters, not a standalone score exposed by its
ranking systems. Do not translate this checklist into a ranking promise.

**Experience**: Does the page show first-hand, real-world use of the product or
topic? Look for: demos, screenshots of real output, case studies with specific
results, personal or company proof.

**Expertise**: Does the content demonstrate deep, accurate knowledge? Look for:
technical depth, correct use of domain vocabulary, specific examples over
generic claims, citations to primary sources.

**Authoritativeness**: Is this site or page recognized as a source in the
space? Look for: backlinks from authoritative sites (note if checkable),
mentions in industry press, author credentials visible, organization About page.

**Trustworthiness**: Can users trust this content and site? Look for: HTTPS,
privacy policy, clear contact and company info, accurate and verifiable claims,
no misleading UI patterns, consistent authorship.

Checklist:

- [ ] First-person or company-specific proof present (E: Experience)
- [ ] Accurate technical claims with no puffery (E: Expertise)
- [ ] Author name and credentials visible when relevant (A: Authoritativeness)
- [ ] Privacy policy, contact page, and HTTPS present (T: Trustworthiness)
- [ ] No misleading UI patterns or dark patterns (T: Trustworthiness)
- [ ] Claims are verifiable and sourced (T: Trustworthiness)

---

## Lane 9: Topic Cluster Architecture

Skip for single-page audits. Also mark N/A when the site's user journeys do not
benefit from a pillar/cluster model; a site is not required to adopt this
content architecture.

**Pillar page**: one comprehensive page that owns the site's core topic and
routes readers to deeper supporting material. Do not promise that it will rank
for a broad query.

**Cluster pages**: specific, narrow pages that support the pillar by covering
sub-topics in depth. Each links back to the pillar.

When a cluster strategy is warranted, ask:

1. Does a clear pillar page exist for the site's primary topic?
2. Do cluster pages exist for each major sub-topic?
3. Does each cluster page link to the pillar?
4. Does the pillar page link to each cluster?
5. Are there orphan pages (no internal links in or out)?
6. Are there keyword cannibalization risks (two pages competing for the same
   query)?

Output a simple map:

```
Pillar: [page] — [target keyword]
  Cluster: [page] — [sub-topic keyword]
  Cluster: [page] — [sub-topic keyword]
Orphan pages: [list or "none found"]
Cannibalization risks: [list or "none found"]
```

# Lane 5: Schema Markup — Checklist and Templates

Detailed checklist, retrievability lens, and JSON-LD templates for
suede-seo-audit Lane 5. Grade-drop rules and scoring live in SKILL.md.

## Contents

- [Checklist](#checklist) — validity, eligibility, and truthfulness
- [Retrievability lens](#retrievability-lens) — which fields a model can quote,
  and whether the prose carries the structure the schema declares
- [Minimum templates](#minimum-templates) — Organization, SoftwareApplication,
  FAQPage, Article

## Checklist

- [ ] Decide whether a Google-supported structured-data feature fits the page.
      `No supported feature identified` is a valid result; schema is not
      mandatory for every page.
- [ ] Existing schema vocabulary and shape validate at schema.org/validator
- [ ] Markup intended for a Google feature passes the Rich Results Test and
      meets that feature's current required properties
- [ ] Schema type matches the page purpose:
  - Visible site-authored FAQ → `FAQPage` is valid schema.org vocabulary, but
    Google generally shows FAQ rich results only for authoritative government
    and health sites. Do not promise visibility.
  - One user-submitted question with user-submitted answers → `QAPage`
  - Blog post or article → `Article` or `BlogPosting`
  - Product or app page → `SoftwareApplication` or `Product`
  - Docs or reference page → `TechArticle` or `WebPage`
  - Organization root page → `Organization`
  - Breadcrumb present for deep pages → `BreadcrumbList`
- [ ] FAQ schema represents the complete visible question/answer content (no
      hidden or hallucinated Q&A)
- [ ] `Organization` properties contain only verified facts. Add `logo` or
      `sameAs` only when the URLs are real, public, and identify the same entity.
- [ ] `SoftwareApplication` schema includes: `name`, `applicationCategory`,
      `operatingSystem`; include `offers` only when visible price/currency facts
      are verified and the targeted Google feature calls for them
- [ ] `Article` schema includes: `headline`, `author`, `datePublished`,
      `dateModified`

When warranted schema is missing or existing markup is broken, provide the
exact corrected JSON-LD block inline in the findings. Do not describe it only
in prose. Populate every field from visible page content or verified facts.
Never invent values, and never say valid markup guarantees a rich result.

For Google eligibility and policy, use:

- https://developers.google.com/search/docs/appearance/structured-data/search-gallery
- https://developers.google.com/search/docs/appearance/structured-data/sd-policies
- https://developers.google.com/search/test/rich-results

## Retrievability lens

Run this after the checklist above, over the JSON-LD you already parsed. It is a
second reading of evidence the lane already gathered, not a second fetch.

The checklist above answers *is this markup correct and honest*. It cannot
answer *which of these fields can a model actually quote* — and a page can pass
every validity check while failing that second question.

Google Cloud's Discovery Engine (Vertex AI Search) is Google's own retrieval
product, so its configuration surface is the clearest public statement of how
Google separates the effects a field can have. Read it as that and no more: it
documents a product you can configure, not the behaviour of Google Search. It
exposes three per-field settings, and their independence is documented rather
than inferred:

| Setting | Documented effect | Audit meaning |
|---|---|---|
| `searchable` | "whether this field can be reverse indexed to match unstructured text queries" | recall — can the document be found at all |
| `indexable` | "whether this field can be filtered, faceted, boosted, or sorted" | filtering and ordering |
| `retrievable` | "whether this field can be returned in a search response" | what can reach the model's answer |

> "A field can be searchable without being indexable or retrievable."

So a field can move ranking while never appearing in an answer, or appear in an
answer while moving no ranking. Each setting caps at 50 fields, which makes
retrievability a budget an operator spends — not a property markup carries on
its own.

Sources:

- https://cloud.google.com/generative-ai-app-builder/docs/provide-schema
- https://cloud.google.com/generative-ai-app-builder/docs/configure-field-settings
- https://cloud.google.com/generative-ai-app-builder/docs/add-website-metadata

**Stay inside what is documented.** For a data store you configure, page
schema.org annotations reach these settings only when an operator declares each
path explicitly — `siteSearchSchemaOrgPaths`, for example
`_root.aggregateRating.ratingValue` — and sets the flags on that path. Nothing
is retrievable by default. No Google documentation maps any schema.org property
to any flag inside Google Search, AI Overviews, or AI Mode.

Write findings inside that boundary:

- Supported: "no documentation says this property reaches an answer; the visible
  prose is the part of this claim the audit can verify."
- Supported: "`Article.dateModified` is a required property for the Article
  feature" — cite the search-gallery page that says so.
- Unsupported, and never write it: "Google marks `acceptedAnswer` retrievable",
  or any sentence that names a flag as observed Google Search behavior.

The classifications below are claims about the page in front of you, decided by
evidence you can quote. They are not claims about Google's pipeline.

**Classify every property in every JSON-LD block:**

- [ ] `prose-backed` — the property's value states a claim that also appears in
      visible page text. Evidence: the property value and the quoted prose.
- [ ] `indexable-only` — the value is a filter, sort, or eligibility value (a
      date, rating, price, category, or `@type`) rather than a sentence a reader
      would quote, and a named Google feature lists it as required or
      recommended. Evidence: the search-gallery page for that feature.
- [ ] `decorative` — the property validates, has no prose counterpart, and no
      named Google feature requires it.
- [ ] `unclassified` — evidence supports none of the three. Record
      `unclassified`. Do not round to the nearest label; an unclassified
      property is an honest audit result and a guessed one is an invented claim.

**Flag schema-only claims.** When a property is the page's only
machine-readable statement of a material claim — a price, a date, a credential,
an availability, an answer — record it as a finding. The prose is the surface
both the reader and the audit can verify, so the fix is a prose counterpart,
not more markup. A property classified `indexable-only` or `decorative` is not
a schema-only claim; it carries no reader-facing claim to lose.

**Confirm the prose carries the structure the schema declares.** Some types
assert that the page has a shape. Count the entries in the JSON-LD, count the
matching visible elements, and record both numbers:

| `@type` | Structure declared | Visible prose must carry |
|---|---|---|
| `FAQPage` | N question/answer pairs | N headings, one per question |
| `HowTo` | ordered steps | one heading or list item per step, in document order |
| `ItemList` | N enumerated items | N items a reader can see and count |
| `BreadcrumbList` | a position hierarchy | a visible breadcrumb trail |

`<summary>`, `<button>`, `<dt>`, and styled `<div>` are not headings. Equal
counts pass; a prose count lower than the schema count is the finding, and it
stands even when the markup is valid and its text matches the visible text
character for character. This is the defect a validity-only reading cannot see:
the schema is correct about content the page has and wrong about structure the
page lacks.

Lane 4's **Retrieval chunking** block owns the measurement — the ~375-word
block size and which markup collapses into one block. Lane 5 owns the opposite
direction: the schema declared a structure, so verify the prose has it. Record
the count mismatch here and cite the Lane 4 block for the block size rather
than re-measuring it.

Retrievability check output format:
```
Property: [path] — [prose-backed | indexable-only | decorative | unclassified] — evidence: [quoted prose | feature doc URL | none]
Schema-only claims: [property = value, no prose counterpart] | none
Structure claim: [@type] declares [N] [questions/steps/items] | visible headings: [N] | [match/mismatch]
```

## Minimum templates

### Organization

```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "[Verified organization name]",
  "url": "[Canonical organization URL]"
}
```

Add `logo` and `sameAs` only when each URL is verified, public, and identifies
the same organization. They are not filler fields.

### SoftwareApplication

```json
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "[Product name]",
  "applicationCategory": "[e.g. DeveloperApplication]",
  "operatingSystem": "[e.g. macOS, Web]"
}
```

Add an `offers` object only when the offer is visible and verified. Never infer
that an app is free because no public price was found.

### FAQPage

Every `name` and `text` value must match the visible FAQ. This template
expresses schema.org vocabulary; it does not imply Google FAQ rich-result
eligibility for an ordinary commercial site.

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "[Visible question text]",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "[Visible answer text]"
      }
    }
  ]
}
```

### Article

```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "[Visible headline]",
  "author": { "@type": "Person", "name": "[Author name]" },
  "datePublished": "[YYYY-MM-DD]",
  "dateModified": "[YYYY-MM-DD]"
}
```