Proposal: add optional utility page metadata

[KimHyeongRae0]

Proposal

Explore optional page metadata that lets users mark high-utility pages such as calculators, comparison pages, templates, checklists, or troubleshooting guides.

Why

Answer engines often benefit from pages that solve a concrete task rather than only describing a topic. aeo.js already accepts page-level content metadata, but it does not expose a structured way to classify utility-oriented pages or surface them differently in generated AI-facing assets.

Possible API Shape

One option is to add an optional field to PageEntry:

type PageUtilityKind =
  | 'calculator'
  | 'comparison'
  | 'template'
  | 'checklist'
  | 'troubleshooting'
  | 'guide';

interface PageEntry {
  utilityKind?: PageUtilityKind;
}

Generated assets could then include this metadata in ai-index.json, reports, or future recommendations.

Questions

• Should this be a single utilityKind field, a broader tags field, or both?
• Which generated outputs should expose this metadata first?
• Should this influence audit/citability hints, or stay purely descriptive at first?

Non-Goals

• No automatic content classification in the initial version.
• No ranking claims.
• No required changes for existing users.

[rubenmarcus]

The underlying insight is right — answer engines do reward pages that solve a concrete task. Two refinements before locking in the shape:

1. Prefer tags?: string[] over the utilityKind enum.
The enum is opinionated and won't cover every site (interactive demo? video walkthrough? data viz? changelog?). A free-form tags array is more flexible, keeps the type system simpler, and still lets users mark 'calculator', 'template', etc. We can document a recommended vocabulary without enforcing it at the type level.

2. Start descriptive, not prescriptive.
Surface the tags in ai-index.json metadata first. Hold off on tying them into audit/citability scoring until we have real data showing they correlate with citation outcomes — otherwise we're adding scoring noise. Keep the first iteration purely informational.

If that direction works for you, the spec would be:

interface PageEntry {
  tags?: string[]; // user-defined, surfaced verbatim in ai-index.json
}

Happy to review a PR. Thanks for the proposal.