diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e348af4..88201af 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -19,6 +19,12 @@ claude --plugin-dir .
 
 `--plugin-dir .` tells Claude Code to load the plugin manifest from `.claude-plugin/plugin.json` and discover skills in `skills/*/SKILL.md`. The plugin runs entirely locally — no build step, no compilation.
 
+### VS Code + GitHub Copilot setup
+
+If you use VS Code with GitHub Copilot Agent, `.vscode/mcp.json` pre-configures the `gh-aw` MCP server so Copilot can call `gh aw` tools directly (compile, validate, audit, etc.). No manual setup required — open the repo in VS Code and the MCP server activates automatically.
+
+`.vscode/settings.json` marks `*.md` files in `.github/workflows/` as the `github-agentic-workflow` language so Copilot provides correct completions for workflow frontmatter.
+
 ## How the plugin works
 
 ```
diff --git a/README.md b/README.md
index 944f714..b0f38d8 100644
--- a/README.md
+++ b/README.md
@@ -117,12 +117,29 @@ skills/
     q.{md,lock.yml}
     markdown-linter.{md,lock.yml}
     pr-nitpick-reviewer.{md,lock.yml}
+    agentics-maintenance.yml       # auto-generated by gh-aw; manages expiring issues/PRs
+    copilot-setup-steps.yml        # installs gh-aw CLI for GitHub Copilot Agent sessions
     shared/
       reporting.md                 # shared reporting component (run-link formatting)
+
+.vscode/
+  mcp.json                         # MCP server config (gh-aw tools for Copilot in VS Code)
+  settings.json                    # GitHub Copilot markdown association settings
 ```
 
 `.lock.yml` files are marked as `linguist-generated` and `merge=ours` in `.gitattributes` to prevent spurious merge conflicts.
 
+### Infrastructure workflows
+
+Two workflow files are not user-installed — they are managed entirely by `gh aw`:
+
+| File | How it's created | Purpose |
+|---|---|---|
+| `agentics-maintenance.yml` | Auto-generated on `gh aw compile` when any workflow uses `expires:` | Cleans up time-limited issues and PRs on a schedule |
+| `copilot-setup-steps.yml` | Manually committed once | Pre-installs the `gh-aw` CLI extension so GitHub Copilot Agent sessions have it available |
+
+Do not edit `agentics-maintenance.yml` by hand — it is regenerated automatically.
+
 ## Local development
 
 ```bash