docs: add AGENTS.md and llms.txt, retire blueprint.yaml

.github/ISSUE_TEMPLATE/unexpected_agent_output.md

@@ -0,0 +1,58 @@
+---
+name: Unexpected agent output
+about: Report an AI agent that recommended the wrong pattern, misstated VPC Lattice behaviour, or produced IaC that doesn't work while using this repository
+title: ''
+labels: bug
+assignees: pablo19sc
+
+---
+
+<!--
+Before submitting, search open and closed issues for the same behavior.
+
+Redact credentials, tokens, account IDs, ARNs containing account IDs, private
+hostnames and IP addresses, customer or organization names, and other
+confidential information. Use consistent placeholders so the prompt and the
+output can still be compared. Do not report potential security vulnerabilities
+publicly; follow the process in CONTRIBUTING.md instead.
+-->
+
+- [ ] I have searched the open and closed issues and did not find this behavior.
+
+## Agent context [Required]
+
+- Agent or tool:
+- Model and version, if known:
+- What the agent was given (`llms.txt`, `AGENTS.md`, `SKILLS.md`, the skill package under `skills/`, a local clone, or other), with the revision, commit, or URL:
+
+## Original prompt [Required]
+
+<!-- Paste the complete original prompt after redacting sensitive information. Mark each redaction consistently. -->
+
+```text
+
+```
+
+## Agent output [Required]
+
+<!-- Paste the complete output: the recommended pattern and reasoning, or the generated CloudFormation or Terraform. -->
+
+```text
+
+```
+
+## Expected output or issue comments [Required]
+
+Provide at least one of the following.
+
+### Expected output
+
+<!-- The pattern, answer, or IaC you expected, if known. -->
+
+### Comments on the issue
+
+<!-- If the expected output is not known, identify the wrong pattern, incorrect VPC Lattice fact, invalid property, or deployment error, and explain what you expected instead. -->
+
+## Additional context
+
+<!-- Include relevant agent messages, assumptions, CloudFormation stack events, or Terraform errors. Do not include secrets or confidential information. -->

.github/pull_request_template.md

@@ -0,0 +1,50 @@
+## Description
+
+<!-- What does this change do, and why? Link any related issue with "Closes #123". -->
+
+## Where is the change?
+
+<!-- Check every area this PR touches, then complete the matching section(s) below. -->
+
+- [ ] `patterns/` — a **new** deployable pattern
+- [ ] `patterns/` — an **update** to an existing pattern
+- [ ] `patterns/4-auth_policies/` — the auth policies and signing reference toolkit
+- [ ] `SKILLS.md` or `skills/` — agent knowledge
+- [ ] Repository docs or CI only (`README.md`, `CONVENTIONS.md`, `CONTRIBUTING.md`, `AGENTS.md`, `llms.txt`, `.github/`)
+
+## Checklist for every change
+
+<!-- CI enforces most of this automatically. Running the checks locally first is faster than round-tripping through CI. -->
+
+- [ ] I have read [CONVENTIONS.md](../CONVENTIONS.md) and this change conforms to it.
+- [ ] `pre-commit run --all-files` passes locally (see [CONTRIBUTING.md](../CONTRIBUTING.md)).
+- [ ] I reviewed advisory Checkov findings, fixed applicable issues, and included a justification for every new suppression (baseline comment or inline `:reason`).
+- [ ] Any pattern or page added, removed, or renamed is reflected in [`llms.txt`](../llms.txt).
+- [ ] No file or heading linked from outside this repository was renamed or moved (`llms.txt`, the `README.md` anchors `#why-vpc-lattice` and `#key-concepts`, category and pattern READMEs) — or, if one was, the pull request description calls it out.
+- [ ] If a convention or a validation step changed, [`AGENTS.md`](../AGENTS.md) reflects it.
+
+## If the change adds or updates a pattern
+
+<!-- Formatting, generated READMEs, and lint are already enforced by the pre-commit suite above — no separate checkboxes needed. -->
+
+- [ ] CloudFormation and Terraform implementations are in parity, or the exception is stated in the pattern README and the pattern table (as for EKS).
+- [ ] The catalogs agree, per [Catalog and agent-index synchronization](../CONVENTIONS.md#9-catalog-and-agent-index-synchronization): the `README.md` pattern table, the category README, `llms.txt`, and the skill package's `references/pattern-selection.md`.
+- [ ] Version pins follow [CONVENTIONS.md](../CONVENTIONS.md#3-version-pins); any pattern-specific floor is listed there.
+- [ ] Every new IaC source file carries the MIT-0 license header.
+- [ ] Secure defaults are kept: IMDSv2, encrypted EBS root volumes, access logging on by default, and `AWS_IAM` with an open auth policy on service-exposing patterns.
+- [ ] The pattern README's **Testing**, **Cost**, and **Cleanup** sections reflect any resource changes.
+
+## If the change is in `patterns/4-auth_policies/`
+
+- [ ] Each policy remains a complete, copy-paste document for one use case, listed in the `policies/README.md` table.
+- [ ] Signing examples still run against the documented signing name (`vpc-lattice-svcs`).
+
+## If the change is in `SKILLS.md` or `skills/`
+
+- [ ] Shared facts match [CONVENTIONS.md](../CONVENTIONS.md): the DNS ranges and the EKS parity exception.
+- [ ] `python3 skills/vpc-lattice-blueprints/scripts/validate-package.py` passes.
+- [ ] I piloted the change with an agent — gave it the updated skill and a representative question — and its behaviour matched the intent. Describe the pilot under **Testing**.
+
+## Testing
+
+<!-- How was this verified? If a pattern was deployed, say in which Region and account setup, and what was checked (associations, DNS resolution, connectivity tests, teardown). If it was only statically validated, say so. If agent knowledge changed, describe the pilot: the prompt, the model/agent used, and what the response got right. -->

.github/workflows/ci.yml

@@ -308,7 +308,7 @@ jobs:
           output_format: cli
           quiet: true
 
-  # Skill package: frontmatter, paths, blueprint.yaml snapshot sync, evals.
+  # Skill package: frontmatter, paths, snapshot provenance, evals.
   skill-package:
     name: Agent skill package validation
     runs-on: ubuntu-latest

.pre-commit-config.yaml

@@ -69,16 +69,15 @@ repos:
           - "--accept"
           - "200,206,429"
 
-  # Skill package: frontmatter, paths, blueprint.yaml snapshot sync, evals.
-  # Also triggers on the root blueprint.yaml so a stale snapshot fails here.
+  # Skill package: frontmatter, paths, snapshot provenance, evals.
   - repo: local
     hooks:
       - id: skill-package-validate
         name: Agent skill package validation
-        description: Validate the vpc-lattice-blueprints skill package (frontmatter, paths, snapshot sync, evals structure). Mirrors CI.
+        description: Validate the vpc-lattice-blueprints skill package (frontmatter, paths, snapshot provenance, evals structure). Mirrors CI.
         entry: python3 skills/vpc-lattice-blueprints/scripts/validate-package.py
         language: system
-        files: ^(skills/vpc-lattice-blueprints/|blueprint\.yaml$)
+        files: ^skills/vpc-lattice-blueprints/
         pass_filenames: false
 
   # General hygiene.

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+> **Purpose.** Written for an **AI agent working in a local clone** of this repository: editing a pattern, adding one, validating a change, or deploying a pattern to test it. For VPC Lattice knowledge, load [`SKILLS.md`](SKILLS.md). For a human introduction, start with [`README.md`](README.md).
+
+## Find your way around
+
+[`llms.txt`](llms.txt) is the index: every category, pattern and reference page, each with the question it answers and the IaC it ships. Read it before listing directories or searching.
+
+| Directory | Contains |
+|-----------|----------|
+| [`patterns/1-simple_architectures/`](patterns/1-simple_architectures/) | Single-account fundamentals, one pattern per target type (EC2, Auto Scaling group, Lambda, ECS, EKS) plus RDS as a VPC resource |
+| [`patterns/2-multi_account/`](patterns/2-multi_account/) | Cross-account sharing with AWS RAM, in the centralized and distributed models |
+| [`patterns/3-advanced_architectures/`](patterns/3-advanced_architectures/) | Designs beyond basic consumer-provider connectivity |
+| [`patterns/4-auth_policies/`](patterns/4-auth_policies/) | A reference toolkit, not a deployable pattern: auth policy snippets (`policies/`) and SigV4/SigV4A signing (`signing/`) |
+| [`patterns/tf_modules/`](patterns/tf_modules/) | Shared Terraform modules, the only shared-module root |
+
+Each deployable pattern has a `README.md` (architecture, testing, cleanup), a `terraform/` and a `cloudformation/` directory, laid out as in [Directory layout](CONVENTIONS.md#2-directory-layout). Patterns are building blocks: a real design often composes several, so start from the closest one rather than looking for a directory per use case.
+
+## Rules that are easy to break
+
+[`CONVENTIONS.md`](CONVENTIONS.md) is the authoritative contract. These are the rules a change most often breaks:
+
+- **Never hand-edit `terraform/README.md`.** It is generated by terraform-docs from `.header.md` and the module's inputs and outputs; edit `.header.md` and regenerate with `.config/.terraform-docs.yaml`.
+- **Keep CloudFormation and Terraform in parity.** EKS is the only Terraform-only pattern; `patterns/4-auth_policies/` has no IaC.
+- **Take version pins from [Version pins](CONVENTIONS.md#3-version-pins)**, including the pattern-specific floors. Do not write them from memory.
+- **Keep the secure defaults**: IMDSv2, encrypted EBS root volumes, HTTPS listeners, the RDS managed master password, access logging on by default, and `AWS_IAM` with an open auth policy on service-exposing patterns. Every Checkov suppression carries a justification.
+- **Keep the indexes in sync in the same change.** Adding, removing or renaming a pattern updates the catalogs listed in [Catalog and agent-index synchronization](CONVENTIONS.md#9-catalog-and-agent-index-synchronization). A pattern missing from `llms.txt` is a bug.
+- **Treat file paths as a public interface.** `llms.txt`, the `README.md` anchors `#why-vpc-lattice` and `#key-concepts`, and the category and pattern READMEs are linked by path from outside this repository, including the Amazon VPC Lattice agent skill. Do not rename or move them without calling it out in the pull request.
+- **Put the MIT-0 license header on every new IaC source file**, and follow the [naming scheme](CONVENTIONS.md#1-naming-scheme).
+- **Do not hard-wrap human-facing markdown.** One paragraph is one line.
+- **Never invent a VPC Lattice property.** Confirm it against the [Amazon VPC Lattice User Guide](https://docs.aws.amazon.com/vpc-lattice/latest/ug/what-is-vpc-lattice.html) before writing it in a pattern or page.
+
+## Validate a change
+
+Every check is static: none needs AWS credentials or creates a resource. Run the ones that match what you changed, and say in your hand-back which ran and which did not.
+
+| You changed | Run |
+|-------------|-----|
+| Terraform | `terraform fmt`, `terraform validate`, `tflint`, `terraform-docs` — through pre-commit |
+| CloudFormation | `cfn-lint` — through pre-commit |
+| Terraform or CloudFormation | `checkov` — through pre-commit |
+| Any markdown file, or `llms.txt` | `lychee --no-progress --max-retries 2 --accept 200,206,429 <files>` |
+| `skills/` | `python3 skills/vpc-lattice-blueprints/scripts/validate-package.py` |
+| Anything, before opening a pull request | `pre-commit run --all-files` |
+
+The tool versions and install steps are in [Local checks (pre-commit)](CONTRIBUTING.md#local-checks-pre-commit). If a tool is not installed, say so rather than reporting the check as passed.
+
+## Contribute
+
+Follow [`CONTRIBUTING.md`](CONTRIBUTING.md): work on a branch of a fork, open an issue first for significant work, and fill in the [pull request template](.github/pull_request_template.md) — its checklist mirrors the rules above for each area a change touches.
+
+## Deploy a pattern to test a change
+
+- **Ask before deploying.** Every pattern creates billable resources in the user's account. Read the pattern README's cost note first, recommend a non-production account, and run the README's cleanup steps when finished.
+- **Use the pattern's own tooling.** Terraform: `terraform init`, `plan`, `apply`, then `destroy`; multi-account patterns deploy per account and tear down in reverse order. CloudFormation: the pattern's `Makefile` (`make deploy` / `make undeploy`), which pins a Region — edit it to deploy elsewhere.
+- **Test with the README's steps.** A service resolves to a `169.254.171.x` address and a VPC resource to a `129.224.0.x` address; Network Segment Access is the exception and reaches the provider's real IP addresses.
+- **Ask about access control.** Service-exposing patterns ship an open auth policy; if the user wants to restrict access, apply a policy from [`patterns/4-auth_policies/policies/`](patterns/4-auth_policies/policies/).
+- **When a request fails**, follow [How do I troubleshoot VPC Lattice connectivity?](README.md#how-do-i-troubleshoot-vpc-lattice-connectivity) and read the pattern's access logs.

CONTRIBUTING.md

@@ -6,17 +6,19 @@ Please read through this document before submitting any issues or pull requests
 
 ## Repository conventions
 
-Every published pattern follows a single set of conventions covering naming, directory layout, dependency version pins, license headers, the access-logging standard, DNS facts, and CloudFormation/Terraform parity. Before adding or modifying a pattern, read [CONVENTIONS.md](CONVENTIONS.md), it is the contract new patterns must follow. Pull requests are expected to conform to it.
+Every published pattern follows a single set of conventions covering naming, directory layout, dependency version pins, license headers, the access-logging standard, DNS facts, and CloudFormation/Terraform parity. Before adding or modifying a pattern, read [CONVENTIONS.md](CONVENTIONS.md), it is the contract new patterns must follow. Pull requests are expected to conform to it. If you work with an AI agent, point it at [AGENTS.md](AGENTS.md): it summarizes those rules, the checks to run for each kind of change, and how to deploy a pattern safely.
 
 ## Reporting Bugs/Feature Requests
 
-We welcome you to use the GitHub issue tracker to report bugs or suggest features. When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
+We welcome you to use the GitHub issue tracker to report bugs, suggest features, or report unexpected output from an AI agent using this repository. When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
 
 - A reproducible test case or series of steps
 - The version of our code being used
 - Any modifications you've made relevant to the bug
 - Anything unusual about your environment or deployment
 
+For an agent that recommended the wrong pattern, misstated a VPC Lattice fact, or produced IaC that doesn't work, use the [Unexpected agent output template](.github/ISSUE_TEMPLATE/unexpected_agent_output.md). Include the original prompt, the agent's complete output, and what you expected, and redact sensitive information first.
+
 ## Contributing via Pull Requests
 
 Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
@@ -31,7 +33,7 @@ To send us a pull request, please:
 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
 3. Ensure local checks pass. Run `pre-commit run --all-files` before opening a PR so the same static checks CI runs are green locally — see [Local checks (pre-commit)](#local-checks-pre-commit) for setup and required tools.
 4. Commit to your fork using clear commit messages.
-5. Send us a pull request, answering any default questions in the pull request interface.
+5. Send us a pull request, filling in the [pull request template](.github/pull_request_template.md).
 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
 
 GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).