docs: Add llms.txt and make guidance pages self-describing

[pablo19sc]

Description

Guidance pages here are usually reached directly — from a link someone sent, or from a search — rather than by browsing from the README. Three changes make a page state what it covers before anyone opens it, plus an index for tooling that fetches the repository.

1. llms.txt at the repository root. An annotated index of every policy/ page and every infra/ pattern, one line each, saying which question that resource answers. Written for an AI agent that has fetched the repository and needs to know what is here rather than guessing at the directory structure — the observed failure mode was a model inventing directory names. Relative links only, and deliberately no llms-full.txt.

2. title and description front matter on all 10 policy/ pages and all 7 tier 1 / tier 2 infra/ READMEs. Each title says what the page answers instead of repeating the filename:

   Before	After
   # Service insertion	Cloud WAN service insertion: send-to and send-via for centralized traffic inspection
   # Static routes	Cloud WAN static routes: create-route and blackhole routes in a segment

   Headings, anchors and technical content are unchanged; each page gains five lines.

3. Retitled ## and ### headings on policy/3-attachment_policies.md and policy/7-routing_policies.md — 14 headings. These are the two longest capability pages, and their use-case sections were titled as prose statements naming none of the mechanisms they demonstrate. "An external partner gets its own segment" offers nothing to a reader scanning for account conditions. Each heading now names the policy key or attribute and the scenario, which is how 5-service_insertion.md, 8- and 9- were already written:

   Before	After
   ### An external partner gets its own segment	### account conditions with association-method: constant: an external partner gets its own segment
   ### Preferring one Region's hybrid edge	### prepend-asn-list: AS_PATH prepending to prefer one Region's hybrid edge
   ### Verify policy effects with the right API	### get-network-routes versus list-core-network-routing-information: verify policy effects with the right API

   No body text, code block or policy JSON was changed. The only non-heading edits are four internal anchor links that the renames broke.

CONVENTIONS.md gains two rules so this does not decay: Front matter on guidance pages (§2, next to Documentation tiers, whose tier vocabulary it uses) and Headings name the mechanism, not only the scenario (§6). llms.txt is registered in the existing index-synchronization rule, so it must be updated whenever a page or pattern is added, removed or renamed.

Breaking: moved anchors

Deep links to these policy/3-attachment_policies.md sections will 404. Every in-repo link is updated; no redirect stubs, given the pending org transfer.

#who-controls-the-tags
  → #who-controls-the-tags-in-a-shared-core-network

#vpcs-choose-their-own-segment
  → #tag-based-attachment-policy-vpcs-choose-their-own-segment-with-association-method-tag

#an-external-partner-gets-its-own-segment
  → #account-conditions-with-association-method-constant-an-external-partner-gets-its-own-segment

#attachment-policies-in-practice
  → #attachment-policy-examples-association-by-tag-attachment-type-account-and-region

Nine section anchors on policy/7-routing_policies.md moved as well. The anchors linked from elsewhere in the repository — #action, #routing-policy-direction, #routing-policy-rules, #how-rules-are-evaluated — were left unchanged on purpose, so no cross-file link required editing.

Where is the change?

• infra/ — front matter on the 7 pattern/index READMEs only; no IaC, no template, no baseline policy changed
• policy/ — front matter on all 10 pages, plus headings on 3- and 7-
• SKILLS.md — unchanged

Checklist for every change

• I have read CONVENTIONS.md and this change conforms to it. It also extends it with the two rules above.
• pre-commit run --all-files passes locally — verified for every hook this change can affect: check-policies, check-yaml, check-json, lychee, end-of-file-fixer, trailing-whitespace, check-merge-conflict. The Terraform, cfn-lint and Checkov hooks act only on files this PR does not touch.
• N/A — no IaC changed, so no new Checkov findings and no new suppressions.

If the change is in infra/

• Unaffected: no IaC changed, so CloudFormation/Terraform parity is untouched and each pattern is still defined only by the attachment types it creates.
• Indexes agree: no pattern was added, removed or renamed, so infra/README.md and the SKILLS.md selector are unchanged and still accurate. The tags the IaC applies and the attachment-policies that expect them are both untouched. llms.txt lists all six patterns.
• N/A — no new IaC source files, so no license headers to add.
• N/A — no resource changes, so Cost and Cleanup are unaffected.

If the change is in policy/

• Examples remain composable snippets. No complete deployable policy document was added — in fact no snippet was modified at all; check_policies.py counts the same 64 inline snippets as before.
• Capability indexes agree. Filenames and # headings are unchanged, so policy/README.md and both SKILLS.md tables still resolve. llms.txt lists all nine capability pages.
• N/A — no new constraint or caveat. No technical content changed, so SKILLS.md needs no update.
• Fenced JSON snippets parse (python3 .github/scripts/check_policies.py): 7 policy documents, 64 snippets, all pass.

Testing

Static validation only. Nothing was deployed — this change touches documentation exclusively, and no template, Terraform file or baseline policy was modified.

• pre-commit hooks listed above all pass, including lychee across every markdown file.
• python3 .github/scripts/check_policies.py passes: CloudFormation templates still match their baseline.json, all documents structurally valid, 64 snippets parse.
• Anchor verification: 104 in-repo anchor and file links resolve, checked by reimplementing GitHub's heading-anchor algorithm and resolving every ](...) target. This is what caught that four self-links inside policy/3 and policy/7 needed updating.
• Confirmed the four cross-page anchors into these two pages — from SKILLS.md (×2), policy/5-service_insertion.md and policy/9-attachment_routing_policy_rules.md — all target headings that were deliberately left unchanged.
• Heading review: every retitled heading was checked against its own section body, to confirm it names what that section actually covers and uses only vocabulary already present there. This caught and reverted two headings that named a mechanism appearing only incidentally in an example.
• Front matter validated: 17 files, parses as YAML, exactly title and description, blank line before the # heading.
• No absolute github.com/aws-samples/... URLs added anywhere, so nothing in this PR breaks at the pending org transfer and rename.