docs: add AEO 1.1 draft spec

[farizanjum]

Summary

Adds the first draft of AEO Spec v1.1 in spec/v1.1-draft.md.

This draft proposes three additive extensions:

• /sitemap.md for markdown twin discovery
• stable section anchors for deep links into markdown twins
• structured-data hints via fenced markdown blocks

Scope

This is spec only. It does not change packages, adapters, examples, CLI checks, conformance scoring, or runtime behavior.

Compatibility

AEO v1.0 conformance remains valid. The v1.1 features are additive and can be adopted independently.

Discussion

GitHub Discussions are not enabled for this repository, so please use this PR thread for design feedback before merge. General feedback can go in the PR conversation, and detailed feedback can use inline comments on spec/v1.1-draft.md.

The draft calls out open questions around:

• flat versus grouped /sitemap.md
• optional token counts
• aeo-schema aliases
• explicit anchors versus fallback slugs
• markdown variant signaling
• sitemap shards
• canonical markdown twin metadata

Verification

• bunx prettier --check spec/v1.1-draft.md
• git diff --check

Refs #18

[vercel]

@farizanjum is attempting to deploy a commit to the Dodo Payments Team on Vercel.

A member of the Team first needs to authorize it.

[dodo-squirrels]

Review: docs: add AEO 1.1 draft spec

Verdict: LGTM — approving. Well-constructed, backward-compatible draft. One integration note about the docs mirror below (non-blocking).

Reviewed the full 390-line draft (single new file spec/v1.1-draft.md, no code).

Technical soundness — strong

• RFC 2119 discipline is consistent and correct throughout; MUST/SHOULD/MAY are used precisely (e.g. "clients MUST treat missing tokens as unknown, not 0" is exactly the right normative call).
• Backward-compat framing is airtight: §1 explicitly states v1.0 servers remain conformant, features are additive/independent, and clients MUST NOT assume one feature implies the others. This is the correct way to stage a minor-version draft.
• Three proposed features (/sitemap.md, section anchors, aeo-schema hints) are each self-contained and opt-in.
• Nice separation of concerns: /sitemap.md (mechanical md-twin inventory) vs sitemap.xml (crawler standard) vs llms.txt (curated guide) — §3.1 draws the boundary cleanly.
• Security §5.4 (no secrets/PII in hints, visible markdown is source of truth, hints MUST NOT contradict visible content) is a thoughtful inclusion.

Verified

• All cross-references resolve: README.md, discovery.md, headers.md, conformance.md, llms-txt-extensions.md, content-negotiation.md all exist, and the content-negotiation.md#6-canonical-markdown-url fragment matches the actual ## 6. Canonical Markdown URL heading.
• Re-implemented the §4.3 fallback slug algorithm and reproduced every row of the example table exactly (## Refunds→#refunds, ### Can I get a refund?→#can-i-get-a-refund, ## 🚀 Getting Started→#getting-started, ## 🚀→empty→section-1, duplicate ## Pricing→#pricing-2). Internally consistent.
• aeo-schema fenced-block examples (FAQPage / Article / SoftwareApplication / BreadcrumbList) are valid JSON-LD.
• §7 Open Questions honestly scopes what's still unsettled (canonicalization key, shard size limits, attribute-ID syntax) — appropriate for a draft.

Docs mirror note (non-blocking)

apps/docs/scripts/sync-spec.mjs mirrors spec/*.md into the docs site via a hardcoded FILE_MAP, and if (!meta) continue; silently skips any file not in the map. Since v1.1-draft.md isn't added to FILE_MAP, it won't surface on dualmark.dev. That's very possibly intentional for a "draft for discussion" — just flagging so it's a conscious choice. If you do want it published, add an entry (e.g. { slug: "v1.1-draft", title: "v1.1 (draft)", ... }). Docs build is unaffected either way (I confirmed the app still builds; the file is simply skipped).

Correctly marked as spec-draft (no AEO_SPEC_VERSION bump, no changeset — right, per §6/§0 this isn't a finalized conformance target yet). Approving.