diff --git a/website/blog/2026-06-03-copilot-config-files-guide.md b/website/blog/2026-06-03-copilot-config-files-guide.md
new file mode 100644
index 0000000..acd75e2
--- /dev/null
+++ b/website/blog/2026-06-03-copilot-config-files-guide.md
@@ -0,0 +1,412 @@
+---
+slug: /2026-06-03-copilot-config-files-guide
+authors: [dfberry]
+date: 2026-06-03
+image: ./media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png
+canonical_url: https://dfberry.github.io/blog/2026-06-03-copilot-config-files-guide
+custom_edit_url: null
+sidebar_label: "2026.06.03 Copilot Config Files"
+title: "Copilot Configuration Files: What They Are, Where They Live, and When to Use Them"
+description: "A practical guide to `.github/copilot-instructions.md`, agents, skills, prompts, and workflows — what each one does, where to find accurate examples, and how they fit together."
+draft: true
+tags:
+ - copilot
+ - configuration
+ - repository-patterns
+ - reference
+updated: 2026-06-02 09:30 PST
+keywords:
+ - copilot-instructions
+ - copilot-agents
+ - copilot-skills
+ - copilot-prompts
+ - github-configuration
+ - ai-workflow
+---
+
+When I work with repos that use Copilot, I keep running into the same issue: people have these files scattered across `.github/`, but I'm not sure what each one does, why they exist separately, or how they're supposed to work together.
+
+I'll see `.github/copilot-instructions.md` and `.github/agents/` in the same repo, then a `prompts/` folder, then maybe a workflow file that looks half like YAML and half like agent instructions. The files exist, but my mental model doesn't.
+
+This guide is my attempt to create that mental model. I want to know what each file is for, where real repos keep them, and how they are used.
+
+
+
+*At first glance, these configuration files look related — but how they nest relate to each other isn't obvious until you see the full picture.*
+
+## Quick Reference: The Six File Families
+
+| # | File | Lives at | Purpose | When to use |
+|---|------|----------|---------|------------|
+| 1 | **Copilot instructions** | `.github/copilot-instructions.md` | Repository-wide governance (always-on context) | "All Copilot work in this repo should follow these rules" |
+| 2 | **Path-specific instructions** | `.github/instructions/*.instructions.md` | Scoped rules for specific directories or file patterns | "My monorepo has areas with different conventions" |
+| 3 | **Agent definitions** | `.github/agents/` | Specialist persona with its own scope, tools, and constraints | "This task needs a reviewer or specialist with tighter boundaries" |
+| 4 | **Skills** | `.github/skills/{name}/SKILL.md` | Reusable workflow package with instructions, resources, and optional scripts | "This is a repeatable procedure Copilot should know how to do" |
+| 5 | **Prompt files / prompt docs** | Official prompt files: `.github/prompts/*.prompt.md`; repo-local docs often live in `.github/prompts/*.md` | Reusable prompt template or task-specific reference context | "I need either a reusable prompt in the IDE or a deeper reference doc for a specific task" |
+| 6 | **Workflows** | `.github/workflows/` | GitHub Actions automation and remote triggers | "I need this to run on a label, schedule, dispatch, or PR event" |
+
+
+
+*This structure diagram turns the six file families into one navigable map so you can see which pieces are baseline, specialized, reusable, or event-driven.*
+
+
+
+*The folder-house metaphor emphasizes that these files live together, but each room has a different job.*
+
+
+
+Those are the most commonly confused files. There are also `AGENTS.md` (an OpenAI/Anthropic agent convention — not a GitHub Copilot feature), hooks, and MCP configs.
+
+## The Copilot Instructions File: Governance Layer
+
+`/.github/copilot-instructions.md` is the ambient context that sits behind Copilot work in a repo. It's not something I invoke manually. It's the baseline.
+
+**What it contains:**
+- Coding standards and conventions
+- Architecture guidelines
+- Documentation expectations
+- Review requirements
+- What "done" looks like
+- Security constraints
+- Naming conventions
+
+**Real examples:**
+
+[Microsoft MCP Copilot Instructions](https://github.com/microsoft/mcp/blob/main/.github/copilot-instructions.md) — a focused baseline file. The heading is `Coding Instructions for GitHub Copilot`, not "Comprehensive Overview," and it goes straight into always-apply rules, build expectations, and PR guidance.
+
+[Azure SDK for JavaScript Copilot Instructions](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/copilot-instructions.md) — a denser governance file. The Azure SDK guidance gets specific about API design, implementation choices, and when to explain a deviation from the house style. In my experience, this kind of baseline makes Copilot more likely to produce code aligned with review expectations.
+
+**When you use it in Copilot:**
+- Open Copilot chat in the repo
+- Ask it to "write a PR description"
+- Copilot includes the repo instructions automatically
+
+**How long should it be?**
+Short enough that a human can still scan it. MCP's file is compact. Azure's is more opinionated. If the instructions file starts reading like a runbook instead of repo policy, I move the task-specific detail somewhere else.
+
+**Key rule:** Instructions describe outcomes and standards. They are the repo's rules of engagement, not the step-by-step workflow.
+
+### Path-Specific Instructions: Scoped Rules
+
+I missed this feature entirely until I was reviewing a monorepo that had three different instruction files and I couldn't figure out why Copilot kept changing tone between the frontend and backend code. Turns out, Copilot supports **path-specific instruction files** in `.github/instructions/` — and they're additive with the repo-wide file.
+
+**Format:** `{name}.instructions.md` files inside `.github/instructions/`
+
+**Example structure:**
+```
+.github/
+ copilot-instructions.md # repo-wide (always-on)
+ instructions/
+ frontend.instructions.md # applies to /frontend
+ backend.instructions.md # applies to /backend
+ tests.instructions.md # applies to test files
+```
+
+Each file uses YAML frontmatter with an `applyTo` key to declare which paths it covers:
+
+```yaml
+---
+applyTo: "src/frontend/**"
+---
+Use React functional components with TypeScript.
+Prefer CSS modules over inline styles.
+```
+
+**Key behavior:** When I'm working in a file that matches a path-specific instruction, Copilot combines **both** the repo-wide instructions and the path-specific ones. It doesn't replace — it layers. This is different from how I initially assumed it worked.
+
+**When to use path-specific instructions instead of the repo-wide file:**
+- Your monorepo has distinct language/framework areas with different conventions
+- Test files need different guidance than production code
+- API code has stricter rules than internal scripts
+
+**When NOT to use them:**
+- Rules that apply everywhere (keep those in `copilot-instructions.md`)
+- Task-specific procedures (those belong in skills)
+- One-off guidance (just say it in chat)
+
+**Official docs:** [Adding path-specific custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions#creating-path-specific-custom-instructions)
+
+---
+
+## Agent Definitions: Specialist Persona
+
+`.github/agents/` is where I expect to find specialist agents — focused reviewers or operators with their own scope, tool boundaries, and output format.
+
+**What an agent file contains:**
+- What the agent specializes in
+- Which tools it can access
+- Task-specific constraints
+- Expected output format
+- When to use it over the default assistant
+
+**Real examples:**
+
+[Azure SDK: archie.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md) — architecture review specialist. The file defines the reviewer's purpose, allowed tools, scope, and output format. It also references `../prompts/architecture-review-guidelines.md` to load its review guidelines.
+
+[Azure SDK: scribe.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/scribe.agent.md) — documentation review specialist. Same pattern, different charter: README, CHANGELOG, snippets, samples, and TSDoc.
+
+**How to invoke it:**
+The exact path depends on the surface. GitHub's [customization cheat sheet](https://docs.github.com/en/copilot/reference/customization-cheat-sheet) is the clearest map I found: select the custom agent in the UI, use `/agent` in Copilot CLI, or reference the agent naturally in chat.
+
+**How it differs from instructions:**
+- **Instructions:** Always-on, repo-wide governance
+- **Agent:** Specialized, on-demand, with its own boundaries
+
+I don't need agents for every repo. A lot of projects are fine with instructions alone. But once I have a recurring task like architecture review or docs review, an agent gives that work a clear owner.
+
+---
+
+## Skills: Reusable Procedures
+
+A skill is a folder with a `SKILL.md` file plus whatever supporting templates, scripts, or resources the workflow needs. GitHub's docs describe skills as packages that Copilot can load when they're relevant to a task. That detail matters. A skill is not just a long prompt. It's a reusable procedure.
+
+**What a skill contains:**
+- When to use the skill
+- What it does
+- Input requirements
+- Output expectations
+- Links to deeper references
+- Templates or helper assets
+- Scripts or automation, if the workflow needs them
+
+**Real examples:**
+
+[OpenAI Agents Python: code-change-verification](https://github.com/openai/openai-agents-python/blob/main/.agents/skills/code-change-verification/SKILL.md) — a concrete verification skill. It tells Copilot when to run the verification stack and points to scripts that execute the checks.
+
+[Vercel Next.js: authoring-skills](https://github.com/vercel/next.js/blob/canary/.agents/skills/authoring-skills/SKILL.md) — a nice example of a skill that explains what belongs in a skill versus in `AGENTS.md`.
+
+**How it gets used:**
+- In surfaces that support skills, Copilot may auto-load it when the task matches
+- You can ask for that workflow explicitly
+- A custom agent can rely on it as part of a larger procedure
+
+**Where they live:**
+- `.github/skills/` — the GitHub Copilot canonical path
+- `.agents/skills/` — the cross-agent open standard path (used by OpenAI, Vercel, and others)
+
+**Skill vs. Agent vs. Instructions — the mental model:**
+
+GitHub's documentation describes what each feature does, but doesn't frame the relationship as explicitly as I'd like. Here's my mental model: **Instructions set the rules. Agents decide. Skills execute.** This is my interpretation, not GitHub's official framing, but it helps me remember which tool to reach for.
+
+
+
+*This cascade makes the control flow explicit: rules constrain decisions, and decisions choose the reusable execution path.*
+
+---
+
+## Skills vs. Prompts: The Critical Difference
+
+This is the distinction that tripped me up most, because people use the word "prompt" to mean two different things.
+
+| Aspect | Skill | Prompt file / prompt doc |
+|--------|-------|--------------------------|
+| **What it is** | Agent-skill package with instructions, resources, and sometimes scripts | Either an official `.prompt.md` template or a repo-local markdown doc used as reference context |
+| **How it gets used** | In supported surfaces, Copilot may auto-load it when relevant, or you ask for it explicitly | Official prompt files are typically user-selected or referenced in supported IDEs; repo-local docs can also be linked from agents or workflows |
+| **What's inside** | Steps, commands, templates, helper assets | Examples, patterns, checklists, input variables, edge cases |
+| **CLI support** | Yes | Official `.prompt.md` prompt files are IDE-focused, not Copilot CLI |
+
+**The caveat that matters:** Official GitHub prompt files use `.prompt.md` and are an IDE feature. Azure's `.github/prompts/*.md` files are different. They're repo-local reference docs that agents or workflows load, not the product feature GitHub documents as prompt files.
+
+That means my old rule of thumb was too neat. Prompts are not always passive reference, and skills are not always the only place with step-by-step guidance. The better distinction is this: skills are packaged workflows Copilot can use as skills; prompt files and prompt docs are reusable context.
+
+
+
+*The decision tree compresses the distinction into one question sequence: reusable workflow first, reusable prompt second, reference doc third.*
+
+---
+
+## Prompts: Task-Specific Expertise
+
+`.github/prompts/` is where many repos store task-specific context. Sometimes those files are official GitHub prompt files ending in `.prompt.md`. Sometimes, and this is what Azure JS does, they are plain markdown docs that reviewers load as guidance.
+
+**What a prompt file or prompt doc contains:**
+- Patterns and examples
+- Detailed guidance for a specific task
+- Decision rules
+- Known edge cases
+- Sometimes input placeholders if it's an official prompt file
+
+**Real examples:**
+
+[Azure SDK: architecture-review-guidelines.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md) — a repo-local reference doc. It defines the review scope and checklist for architecture review, and [Archie points to it directly](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md).
+
+[GitHub gh-aw: create-agentic-workflow.md](https://github.com/github/gh-aw/blob/v0.71.1/.github/aw/create-agentic-workflow.md#L13-L25) — another repo-local guide. It explains the markdown workflow structure used by `gh-aw`. Useful context, yes. An official GitHub prompt-file feature, no.
+
+**How agents use them:**
+Agents or workflows can read these docs at runtime. In Azure JS, the architecture review guidance also points back to `.github/copilot-instructions.md`, which is a nice example of the layers staying connected instead of duplicating each other.
+
+**Where they live:**
+- Official prompt files: `.github/prompts/*.prompt.md`
+- Repo-local reference docs: often `.github/prompts/*.md`
+- Organized by task: architecture review, dependency review, release prep, and so on
+
+**Why separate files?**
+Because the detail belongs close to the task, not smeared across every Copilot interaction. When instructions become hard to scan, moving task-specific context into separate files keeps the baseline clean.
+
+---
+
+## Workflows: Automation Triggers
+
+`.github/workflows/` is standard GitHub Actions. I include it here because people often blame Copilot for behavior that is really coming from a workflow trigger.
+
+**What a workflow does:**
+- Listens for triggers such as push, label, schedule, or manual dispatch
+- Runs remote automation on GitHub
+- Starts a reviewer or other automation path
+- Posts status, comments, or checks back to the PR
+
+**Real example:**
+
+[Azure SDK for JavaScript reviewer workflows](https://github.com/Azure/azure-sdk-for-js/tree/main/.github/workflows) — not one big controller that fans everything out. Each reviewer has its own workflow file. [Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md) and [Dexter](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md) both trigger on `pull_request_target` with `types: [labeled]`, and [Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md) says plainly that its job is to review a PR for performance regressions.
+
+**How it connects to agents and skills:**
+The workflow is the remote trigger. In Azure JS, each reviewer workflow posts its own findings back to the PR. In other repos, a workflow might also call a custom agent or load a skill, but that's not the part I can prove from this example.
+
+---
+
+## How They Wire Together: A Real Workflow
+
+Here's the version of the Azure SDK flow I can actually defend with links.
+
+**1. A label triggers the run**
+In Azure JS, the review workflows listen for `pull_request_target` with `types: [labeled]`, not for PR creation. You can see that in [archie.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md) and [dexter.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md).
+
+**2. Each reviewer has its own workflow**
+[Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md), [Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md), [Dexter](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md), and [Scribe](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/scribe.md) are separate files under `.github/workflows/`. They can run independently when their trigger label appears. This is not one workflow spawning four reviewers in parallel.
+
+**3. The workflow itself states the review job**
+[Dash](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md) literally says it reviews the PR for performance regressions and anti-patterns. Archie and Dexter follow the same pattern for architecture and dependency review.
+
+**4. Agent files and prompt docs are the reusable layer**
+Separately from the workflow trigger, [archie.agent.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md) defines the architecture reviewer as a reusable custom agent and references `../prompts/architecture-review-guidelines.md`. That prompt doc then points back to the repo instructions in [architecture-review-guidelines.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md).
+
+**5. Findings land on the PR from each workflow**
+[Archie](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md) and [Scribe](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/scribe.md) both declare `create-pull-request-review-comment` and `submit-pull-request-review` in `safe-outputs`, with run messages for the PR review lifecycle. So the accurate mental model is: each reviewer workflow posts its own findings. There isn't a separate "collector" workflow in this example.
+
+**6. Skills are adjacent, not proven by this example**
+Skills still matter to the overall ecosystem, but Azure's review workflows are not the example I would use to claim that agents are invoking skills behind the scenes. If I want to show skills, I use an actual `SKILL.md` repo.
+
+That's the loop I trust: a label starts a workflow, the workflow runs the reviewer, the reviewer uses repo guidance, and comments come back to the PR.
+
+
+
+*This sequence shows the asynchronous handoff from label to workflow to reviewer guidance and back to a PR comment.*
+
+---
+
+## Using Copilot with These Files: Chat and CLI
+
+### In Copilot Chat (Browser or VS Code)
+
+**Scenario:** You're in a repo and you open Copilot chat.
+
+```
+You: write a PR description
+```
+
+Copilot reads `.github/copilot-instructions.md` and picks up things like:
+- PR title format
+- Required sections
+- Review expectations
+
+Result: the draft is much more likely to match the repo's stored rules.
+
+**Scenario 2:** You want the specialist reviewer.
+
+```
+You: use the archie agent to review my API changes
+```
+
+Depending on the surface, you might select `archie` in the agent picker, use `/agent` in Copilot CLI, or reference it naturally in chat. The important part is the same: the agent file gives that review task its own scope and constraints.
+
+### In Copilot CLI
+
+**Scenario:** You're working locally and you want a code review from the terminal.
+
+```shell
+copilot
+/review focus on bugs and security issues in my current changes
+```
+
+GitHub documents `/review` as the CLI code review path in its [Copilot CLI docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli) and [agentic code review guide](https://docs.github.com/en/copilot/how-tos/copilot-cli/use-copilot-cli/agentic-code-review). This is the replacement for the old `gh copilot pr-review` mental model I had in my head.
+
+**Scenario 2:** You want to trigger the remote GitHub Actions reviewer from your terminal.
+
+```shell
+gh workflow run archie.md -f item_number=42
+```
+
+That command is a **remote workflow dispatch through GitHub CLI**, not local Copilot behavior. Azure's reviewer workflows expose `workflow_dispatch` with an `item_number` input in [archie.md](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/archie.md), so `gh` can start the run on GitHub.
+
+---
+
+## Decision Table: Which File for What?
+
+
+
+*This placement tree turns the file choice into a routing problem: match the task shape, then drop it in the right folder.*
+
+| I need to... | Put it in... | Why |
+|--------------|--------------|-----|
+| Set coding standards | Copilot instructions | Always-on, repo-wide governance |
+| Require testing notes on all PRs | Copilot instructions | It's a rule, not a workflow |
+| Automate PR review on labels | Workflows + reviewer definitions | Labels are a GitHub Actions trigger, and the reviewer needs its own scope |
+| Store detailed architecture patterns | Prompt docs | Too bulky for baseline instructions; reviewers can load them when needed |
+| Make code generation or verification repeatable | Skills | Copilot can load the packaged workflow when the task matches |
+| Handle a one-time task | Chat | Some work doesn't need a file at all |
+
+---
+
+## Minimal Repo Setup
+
+If I'm starting fresh and I don't want to overengineer this, I keep it boring.
+
+**Minimal viable setup:**
+- `.github/copilot-instructions.md` (recommended baseline)
+- No agents yet unless I have a recurring specialist task
+- No skills yet unless I keep repeating the same workflow
+- No prompt docs yet unless the task-specific context is making the instructions file noisy
+
+**As the repo grows:**
+- Add agents when a task needs its own tool restrictions or review charter
+- Add skills when a workflow deserves packaging
+- Add prompt docs when a reviewer or task needs deeper context than the baseline file should carry
+
+Start minimal, then add layers only when each layer removes confusion.
+
+---
+
+## How to Find Examples in Real Repos
+
+Here are the examples I would study first.
+
+**Azure SDK for JavaScript** — the clearest end-to-end example I found
+- Instructions baseline: [`.github/copilot-instructions.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/copilot-instructions.md)
+- Architecture reviewer: [`.github/agents/archie.agent.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/archie.agent.md)
+- Prompt doc Archie loads: [`.github/prompts/architecture-review-guidelines.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/prompts/architecture-review-guidelines.md)
+- Performance reviewer workflow: [`.github/workflows/dash.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dash.md)
+- Dependency reviewer workflow: [`.github/workflows/dexter.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/workflows/dexter.md)
+- Documentation reviewer: [`.github/agents/scribe.agent.md`](https://github.com/Azure/azure-sdk-for-js/blob/main/.github/agents/scribe.agent.md)
+
+**Microsoft MCP** — a readable baseline instructions file
+- Instructions: [`.github/copilot-instructions.md`](https://github.com/microsoft/mcp/blob/main/.github/copilot-instructions.md)
+
+**GitHub gh-aw** — a good example of repo-local workflow guidance that looks prompt-like
+- Workflow authoring guide: [`.github/aw/create-agentic-workflow.md` lines 13-25](https://github.com/github/gh-aw/blob/v0.71.1/.github/aw/create-agentic-workflow.md#L13-L25)
+
+**Vercel Next.js** — useful for skill design patterns
+- Skill example: [`.agents/skills/authoring-skills/SKILL.md`](https://github.com/vercel/next.js/blob/canary/.agents/skills/authoring-skills/SKILL.md)
+
+
+---
+
+## The One-Sentence Rule
+
+
+
+If I'm stuck deciding where something belongs, this is still the fastest check I know:
+- If it reads like a rule, put it in instructions.
+- If it reads like a reusable workflow, put it in a skill.
+- If it reads like task-specific context, put it in a prompt doc or prompt file.
+- If it has to run on GitHub events, put it in a workflow.**
+
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3-color.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3-color.svg
new file mode 100644
index 0000000..b53771a
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3-color.svg
@@ -0,0 +1,68 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3.svg
new file mode 100644
index 0000000..be23c16
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-1-mental-model-v3.svg
@@ -0,0 +1,68 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg
new file mode 100644
index 0000000..ebf8f86
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-light.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-v2.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-v2.svg
new file mode 100644
index 0000000..16538f3
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure-v2.svg
@@ -0,0 +1,118 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure.svg
new file mode 100644
index 0000000..23ef79b
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-configuration-files-structure.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-file-families-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-file-families-v3.svg
new file mode 100644
index 0000000..8686499
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-2-file-families-v3.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg
new file mode 100644
index 0000000..9f3102c
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree-light.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg
new file mode 100644
index 0000000..9565a0d
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-skills-vs-prompts-decision-tree.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg
new file mode 100644
index 0000000..5586f50
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-3-top-level-routing-v3.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-agent-routing-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-agent-routing-v3.svg
new file mode 100644
index 0000000..e22782c
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-agent-routing-v3.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-color.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-color.svg
new file mode 100644
index 0000000..3aa505b
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-color.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg
new file mode 100644
index 0000000..fe3a729
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger-light.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg
new file mode 100644
index 0000000..1dc7aa7
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-4-azure-sdk-workflow-trigger.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg
new file mode 100644
index 0000000..c864bbd
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree-light.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg
new file mode 100644
index 0000000..51cc322
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-file-placement-decision-tree.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-input-parsing-v3.svg b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-input-parsing-v3.svg
new file mode 100644
index 0000000..6e93562
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/diagram-5-input-parsing-v3.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/generate-images.sh b/website/blog/media/2026-06-03-copilot-config-files-guide/generate-images.sh
new file mode 100644
index 0000000..b081f84
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/generate-images.sh
@@ -0,0 +1,178 @@
+#!/bin/bash
+# Image Generation Script for Copilot Configuration Files Guide Blog Post
+# Generated: 2026-05-31
+# Purpose: Regenerate all SVG diagrams, PNG infographics, and watercolor illustrations
+#
+# All commands use the Stable Diffusion image generation pipeline.
+# Prompt source: image-specs-and-prompts.md and watercolor-prompts.md
+# Device auto-detection: uses CUDA if available, MPS on Apple Silicon, falls back to CPU
+#
+# Usage: bash generate-images.sh [filter]
+# filter (optional): "svg", "png", or "watercolor" to run only that subset
+# Example: bash generate-images.sh watercolor
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+OUTPUT_DIR="$SCRIPT_DIR"
+SEED_BASE=52
+
+# Colors for terminal output
+GREEN='\033[0;32m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}=== Copilot Config Files Guide: Image Generation ===${NC}\n"
+
+# ============================================================================
+# SVG DIAGRAMS (Mermaid → SVG export)
+# ============================================================================
+
+generate_svg_diagrams() {
+ echo -e "${GREEN}Generating SVG diagrams...${NC}\n"
+
+ # Diagram 1: Mental Model (three rings with cards)
+ echo "1. diagram-1-mental-model-v3.svg"
+ echo " Cards: INSTRUCTIONS, AGENTS, SKILLS around three nested rings"
+ echo " Color: White bg, black text, light gray lines (#cccccc), light fills (#f5f7fa)"
+ echo " ✓ Manual Mermaid export or direct SVG creation\n"
+
+ # Diagram 2: File Families Decision Tree
+ echo "2. diagram-2-file-families-v3.svg"
+ echo " Structure: Root node → 5 file family branches (instructions, agents, skills, prompts, workflows)"
+ echo " Labels: concise routing decisions"
+ echo " ✓ Manual Mermaid export or direct SVG creation\n"
+
+ # Diagram 3: Skills vs. Prompts Decision Tree
+ echo "3. diagram-3-top-level-routing-v3.svg"
+ echo " Decision flow: Does it reuse? → skills | Is it situational? → prompts"
+ echo " ✓ Manual Mermaid export or direct SVG creation\n"
+
+ # Diagram 4: Agent Routing (agents → handlers → channels)
+ echo "4. diagram-4-agent-routing-v3.svg"
+ echo " Flow: Multiple agents dispatched based on role + task type"
+ echo " ✓ Manual Mermaid export or direct SVG creation\n"
+
+ # Diagram 5: File Placement Decision Tree
+ echo "5. diagram-5-input-parsing-v3.svg"
+ echo " Decision: Where do these config files live? (.github, root, dotenv, etc.)"
+ echo " ✓ Manual Mermaid export or direct SVG creation\n"
+}
+
+# ============================================================================
+# PNG INFOGRAPHICS (Simple stable-diffusion generation)
+# ============================================================================
+
+generate_png_infographics() {
+ echo -e "${GREEN}Generating PNG infographics...${NC}\n"
+
+ # Image 1: Quick Reference Table (visual rendering of file families table)
+ echo "📋 image-1-quick-reference-table.png"
+ python3 simple_config.py \
+ --prompt "A clean reference table layout showing file families, descriptions, and locations in a organized grid format, light background, black text, minimal design, professional appearance, no decorative elements, clear typography" \
+ --preset production \
+ --style infographic \
+ --size blog-hero \
+ --seed $((SEED_BASE + 1)) \
+ --output "$OUTPUT_DIR/image-1-quick-reference-table.png" \
+ --modifier clarity \
+ --modifier organized
+ echo " ✓ Generated\n"
+
+ # Image 2: Where They Live (file system layout visualization)
+ echo "📂 image-2-where-they-live.png"
+ python3 simple_config.py \
+ --prompt "Folder and file structure diagram showing .github directory, root config files, environment variables, visual hierarchy with clear separation between file types, light background, monochrome, professional infographic style, no text labels inside boxes" \
+ --preset production \
+ --style infographic \
+ --size blog-hero \
+ --seed $((SEED_BASE + 2)) \
+ --output "$OUTPUT_DIR/image-2-where-they-live.png" \
+ --modifier structure \
+ --modifier clarity
+ echo " ✓ Generated\n"
+}
+
+# ============================================================================
+# WATERCOLOR ILLUSTRATIONS (Story-driven, character-focused)
+# ============================================================================
+
+generate_watercolors() {
+ echo -e "${GREEN}Generating watercolor illustrations...${NC}\n"
+
+ # Watercolor 1: Mapping the Five File Families
+ echo "🎨 watercolor-1-mapping-file-families.png"
+ python3 simple_config.py \
+ --prompt "Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \
+ --preset production \
+ --style watercolor \
+ --size blog-hero \
+ --seed $((SEED_BASE + 3)) \
+ --output "$OUTPUT_DIR/watercolor-1-mapping-file-families.png" \
+ --modifier painterly \
+ --modifier loose
+ echo " ✓ Generated\n"
+
+ # Watercolor 2: Understanding the Layers
+ echo "🎨 watercolor-2-understanding-layers.png"
+ python3 simple_config.py \
+ --prompt "Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \
+ --preset production \
+ --style watercolor \
+ --size blog-hero \
+ --seed $((SEED_BASE + 4)) \
+ --output "$OUTPUT_DIR/watercolor-2-understanding-layers.png" \
+ --modifier painterly \
+ --modifier loose
+ echo " ✓ Generated\n"
+
+ # Watercolor 3: Tracing a Real Workflow
+ echo "🎨 watercolor-3-tracing-workflow.png"
+ python3 simple_config.py \
+ --prompt "Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \
+ --preset production \
+ --style watercolor \
+ --size blog-hero \
+ --seed $((SEED_BASE + 5)) \
+ --output "$OUTPUT_DIR/watercolor-3-tracing-workflow.png" \
+ --modifier painterly \
+ --modifier loose
+ echo " ✓ Generated\n"
+}
+
+# ============================================================================
+# MAIN EXECUTION
+# ============================================================================
+
+FILTER="${1:-all}"
+
+case "$FILTER" in
+ svg)
+ generate_svg_diagrams
+ ;;
+ png)
+ generate_png_infographics
+ ;;
+ watercolor)
+ generate_watercolors
+ ;;
+ all)
+ generate_svg_diagrams
+ generate_png_infographics
+ generate_watercolors
+ ;;
+ *)
+ echo "Unknown filter: $FILTER"
+ echo "Usage: bash generate-images.sh [svg|png|watercolor|all]"
+ exit 1
+ ;;
+esac
+
+echo -e "${GREEN}✓ Image generation complete!${NC}\n"
+echo "Generated files are in: $OUTPUT_DIR"
+echo ""
+echo "Next steps:"
+echo "1. Review all generated images in the media folder"
+echo "2. Compare against image-specs-and-prompts.md specifications"
+echo "3. Update blog post references if needed"
+echo "4. Commit all images with: git add media/2026-05-31-copilot-config-files-guide/*.{svg,png}"
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/image-2-where-they-live.png b/website/blog/media/2026-06-03-copilot-config-files-guide/image-2-where-they-live.png
new file mode 100644
index 0000000..8b15cf9
Binary files /dev/null and b/website/blog/media/2026-06-03-copilot-config-files-guide/image-2-where-they-live.png differ
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/image-generation-reference.md b/website/blog/media/2026-06-03-copilot-config-files-guide/image-generation-reference.md
new file mode 100644
index 0000000..14045fb
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/image-generation-reference.md
@@ -0,0 +1,321 @@
+---
+title: "Image Generation CLI Reference"
+---
+
+# Image Generation Commands Reference
+
+This document contains all CLI commands for regenerating the blog post's visual assets. Use this when modifying prompts, regenerating specific images, or troubleshooting output.
+
+## Quick Start
+
+```bash
+# Regenerate all images
+bash generate-images.sh all
+
+# Regenerate only watercolors
+bash generate-images.sh watercolor
+
+# Regenerate only PNG infographics
+bash generate-images.sh png
+
+# Regenerate only SVG diagrams
+bash generate-images.sh svg
+```
+
+---
+
+## Image Specifications
+
+### Design System (All Images)
+- **Background:** Light (#ffffff or #f5f7fa)
+- **Text:** Black (#000000)
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Size:** 1536×1024 pixels (blog-hero standard)
+- **Text Constraint:** No overlapping text; minimum 8-24px clearance from shapes
+- **Style:** Monochrome, no gradients, no accent colors
+
+### Color Schema (Watercolors Only)
+- **Technique:** Soft wet-on-wet washes
+- **Texture:** Visible paper texture
+- **Tones:** Warm, muted palette
+- **Brushwork:** Loose, painterly
+- **Text:** None
+
+---
+
+## SVG Diagrams
+
+### 1. Mental Model (Three Rings + Cards)
+```
+diagram-1-mental-model-v3.svg
+```
+- **Content:** Three nested rings (Instructions → Agents → Skills cascade)
+- **Cards:** INSTRUCTIONS (top), AGENTS (right), SKILLS (left) with light backgrounds (#f5f7fa)
+- **Layout:** Symmetric, centered
+- **Clearance:** 24px minimum from text to shapes
+
+**Manual regeneration:**
+1. Export from Mermaid diagram editor
+2. Post-process: ensure card fills are #f5f7fa, no pill labels
+3. Verify clearance zones: top card INSTRUCTIONS | right card AGENTS | left card SKILLS | center copy
+
+### 2. File Families Decision Tree
+```
+diagram-2-file-families-v3.svg
+```
+- **Root Node:** "Config Files"
+- **Branches:** Instructions | Agents | Skills | Prompts | Workflows
+- **Edge Labels:** Routing decisions (2-3 words max)
+- **Layout:** Hierarchical tree
+
+### 3. Skills vs. Prompts Decision Tree
+```
+diagram-3-top-level-routing-v3.svg
+```
+- **Decision Point:** "Does it reuse across many prompts?"
+- **Left path:** "Yes" → Skills
+- **Right path:** "No" → Prompts
+- **Layout:** Binary decision flow
+
+### 4. Agent Routing
+```
+diagram-4-agent-routing-v3.svg
+```
+- **Flow:** Agents (by role + task type) → Handlers → Execution Channels
+- **Elements:** Agent boxes, handler boxes, channel endpoints
+- **Connectors:** Labeled edges showing routing logic
+
+### 5. File Placement Decision Tree
+```
+diagram-5-input-parsing-v3.svg
+```
+- **Question:** "Where do these files live?"
+- **Decisions:** Scope (repo-wide vs. per-branch) → Location (.github vs. root vs. dotenv)
+- **Leaf nodes:** Final placement recommendations
+
+---
+
+## PNG Infographics
+
+### Image 1: Quick Reference Table
+```bash
+python3 simple_config.py \
+ --prompt "A clean reference table layout showing file families, descriptions, and locations in a organized grid format, light background, black text, minimal design, professional appearance, no decorative elements, clear typography" \
+ --preset production \
+ --style infographic \
+ --size blog-hero \
+ --seed 53 \
+ --output outputs/image-1-quick-reference-table.png \
+ --cpu \
+ --modifier clarity \
+ --modifier organized
+```
+
+**What it shows:**
+- Structured table of file families (Instructions, Agents, Skills, Prompts, Workflows)
+- Columns: Family Name | Purpose | File Name(s) | Location
+- Professional grid layout, no decorative elements
+
+### Image 2: Where They Live (File System Structure)
+```bash
+python3 simple_config.py \
+ --prompt "Folder and file structure diagram showing .github directory, root config files, environment variables, visual hierarchy with clear separation between file types, light background, monochrome, professional infographic style, no text labels inside boxes" \
+ --preset production \
+ --style infographic \
+ --size blog-hero \
+ --seed 54 \
+ --output outputs/image-2-where-they-live.png \
+ --cpu \
+ --modifier structure \
+ --modifier clarity
+```
+
+**What it shows:**
+- Visual tree of `.github/` directory structure
+- Root-level config files (copilot.json, etc.)
+- Environment variable locations
+- Clear visual separation of file types
+
+---
+
+## Watercolor Illustrations
+
+Each watercolor uses **tight, focused prompts** (~20 words) to avoid competing visual details. See `watercolor-prompts.md` for narrative context.
+
+### Watercolor 1: Mapping the Five File Families
+```bash
+python3 simple_config.py \
+ --prompt "Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \
+ --preset production \
+ --style watercolor \
+ --size blog-hero \
+ --seed 55 \
+ --output outputs/watercolor-1-mapping-file-families.png \
+ --cpu \
+ --modifier painterly \
+ --modifier loose
+```
+
+**Narrative:** Opening section — woman physically organizing the five file families into one usable mental model.
+
+**Key elements:**
+- Normal woman (average features, practical clothes)
+- Desk with papers/folders
+- Five distinct stacks being sorted
+- Warm, loose watercolor technique
+
+### Watercolor 2: Understanding the Layers
+```bash
+python3 simple_config.py \
+ --prompt "Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \
+ --preset production \
+ --style watercolor \
+ --size blog-hero \
+ --seed 56 \
+ --output outputs/watercolor-2-understanding-layers.png \
+ --cpu \
+ --modifier painterly \
+ --modifier loose
+```
+
+**Narrative:** Instructions, Agents, Skills section — woman examining nested layers to understand how they sit together.
+
+**Key elements:**
+- Woman at desk
+- Transparent/translucent layers (trays or sheets)
+- One layer lifted/compared to another
+- Focused, curious expression
+- Watercolor technique
+
+### Watercolor 3: Tracing a Real Workflow
+```bash
+python3 simple_config.py \
+ --prompt "Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text" \
+ --preset production \
+ --style watercolor \
+ --size blog-hero \
+ --seed 57 \
+ --output outputs/watercolor-3-tracing-workflow.png \
+ --cpu \
+ --modifier painterly \
+ --modifier loose
+```
+
+**Narrative:** Azure workflow section and decision table — woman tracing a concrete path from abstract categories to real implementation.
+
+**Key elements:**
+- Woman at home office
+- Pinned notes on wall or board
+- Workflow folders/documents
+- Following a line/path between elements
+- Hands-on, investigative posture
+- Watercolor technique
+
+---
+
+## Prompt Engineering Rules
+
+### Watercolor Prompts (Critical)
+- **Length:** Keep to ~20 words (PRDs blog style)
+- **Structure:** `[Subject] [one clear focal action] [technique keywords] [result constraint]`
+- **Avoid:** Multiple competing actions, vague subjects, text overlays
+- **Character:** Always "normal woman" (not beautified, not styled)
+- **Setting:** Grounded work environment (desk, home office, etc.)
+- **Technique keywords:** "watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text"
+
+### PNG Infographic Prompts
+- **Length:** 15–25 words
+- **Style:** "light background, black text, minimal design, professional"
+- **Avoid:** Decorative elements, gradients, accent colors
+- **Modifiers:** `--modifier clarity`, `--modifier organized`, `--modifier structure`
+
+### Common Modifiers
+| Modifier | Effect |
+|----------|--------|
+| `painterly` | Loose, artistic technique |
+| `loose` | Relaxed brushwork (watercolor) |
+| `clarity` | Sharp focus, clear text |
+| `organized` | Clean layout, grid structure |
+| `structure` | Visual hierarchy, spatial relationships |
+| `crisper` | Defined edges, precision |
+| `more-detailed` | Additional visual information |
+
+---
+
+## Seed Values
+
+**Base seed:** 52 (assigned at start of image generation batch)
+
+**Increment:** +1 for each subsequent image in order:
+- PNG Image 1: seed 53
+- PNG Image 2: seed 54
+- Watercolor 1: seed 55
+- Watercolor 2: seed 56
+- Watercolor 3: seed 57
+
+**Why:** Consistent but varied results. Change the base seed (e.g., 100, 200) to explore different style directions while keeping relative relationships.
+
+---
+
+## Troubleshooting
+
+### Images Look Poor Quality or Confusing
+**Likely cause:** Prompt is too verbose or has competing visual elements.
+
+**Fix:** Tighten the prompt. Remove secondary actions. Focus on ONE clear subject + ONE action. Example:
+- ❌ "Woman at desk working on files, thinking deeply, with visible code snippets and diagrams around her"
+- ✅ "Woman at desk sorting five distinct stacks of repository files, watercolor illustration"
+
+### Text Overlaps Other Elements
+**Likely cause:** Mermaid diagram text clearance zones not respected.
+
+**Fix:** Review `image-specs-and-prompts.md` clearance constraints. Ensure 8–24px minimum space around all text.
+
+### Watercolor Colors Don't Match PRDs Blog Style
+**Likely cause:** Seed or modifier settings differ.
+
+**Fix:** Check exact seed value and modifiers (`--modifier painterly --modifier loose`). Compare against reference images from PRDs blog. If still incorrect, adjust prompt to be more specific about tone (e.g., "ochre and soft blue undertones").
+
+### SVG Diagrams Not Rendering in Docusaurus
+**Likely cause:** SVG file size, missing xmlns, or embedded elements.
+
+**Fix:** Verify SVG has `xmlns="http://www.w3.org/2000/svg"`. Check file size (should be <50KB). Test rendering locally: `npm start` in website directory.
+
+---
+
+## File Organization
+
+All images live in:
+```
+website/blog/media/2026-05-31-copilot-config-files-guide/
+```
+
+**Naming convention:**
+- SVGs: `diagram-{N}-{kebab-case-name}-v3.svg`
+- PNG infographics: `image-{N}-{kebab-case-name}.png`
+- Watercolors: `watercolor-{N}-{kebab-case-name}.png`
+
+**Referenced in blog post:**
+```markdown
+
+
+```
+
+---
+
+## Next Steps
+
+1. **Review regenerated images** against `image-specs-and-prompts.md`
+2. **Integrate into blog post** (markdown image references)
+3. **Test Docusaurus build:** `npm run build` in website directory
+4. **Commit all media:** `git add media/2026-05-31-copilot-config-files-guide/`
+5. **Publish blog post** when ready
+
+---
+
+## Reference Files
+
+- **`watercolor-prompts.md`** — Narrative context and exact prompts for all 3 watercolor illustrations
+- **`image-specs-and-prompts.md`** — Master reference with production specs, layout rationale, and modification guides for all 7 visual assets
+- **`watercolor-manifest.md`** — Tracking file for watercolor generation status
+- **`generate-images.sh`** — Bash script to regenerate all images with one command
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/image-specs-and-prompts.md b/website/blog/media/2026-06-03-copilot-config-files-guide/image-specs-and-prompts.md
new file mode 100644
index 0000000..249318c
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/image-specs-and-prompts.md
@@ -0,0 +1,440 @@
+# Image Specs and Prompts
+
+These specs were extracted from the existing 7 assets in this folder.
+
+Notes:
+- For SVGs, I read the source and reconstructed editable structure.
+- For PNGs, I examined the rendered image and provide a faithful editable production spec.
+- I did **not** find a separate original prompt file for these 7 assets in the repo, so the PNG sections include an extracted **specification/prompt** rather than a repo-authored source prompt.
+
+---
+
+## 1. `diagram-1-mental-model.svg`
+
+**Type:** custom SVG composition
+
+### Design System (applies to all diagrams)
+- **Background:** White or light gray (#ffffff, #f5f5f5)
+- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc)
+- **Text color:** Black (#000000) always
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room.
+
+**Canvas:** `viewBox="0 0 807 646"`
+**Title in file:** `Layers of Governance`
+
+Production specification (revised for text layout)
+This is not a native Mermaid diagram; it is a custom SVG built around the post's mental model: instructions create the boundary, agents interpret inside it, and skills sit at the execution center.
+
+```text
+Canvas: viewBox 0 0 807 646 on a white background (#ffffff).
+Use black text only (#000000), light-gray strokes (#cccccc), and white/light fills only where specified.
+Treat the composition as four protected text zones: the top INSTRUCTIONS card, the right AGENTS card, the left SKILLS card, and the inner-circle center copy. Text from one zone must never enter another zone.
+Build the diagram around a centered three-ring system. Keep generous negative space around the rings so the rings read as layers, not collisions.
+Top card: place a rounded rectangle centered above the rings for INSTRUCTIONS with a soft light fill such as #f5f7fa (or #f0f4f8) so it pops against the white canvas while staying subtle. Keep at least 24px of vertical gap between the bottom of this card and any connector. Inside the card, use 18-20px side padding, at least 16px top/bottom padding, a bold all-caps heading, then two short lines of body copy. If the text feels tight, increase card height before reducing spacing.
+Right card: place a rounded rectangle to the right of the rings for AGENTS using the same soft light fill (#f5f7fa or #f0f4f8). Keep at least 24px of horizontal clearance between the card edge and the outer ring. Put the AGENTS label inside the card as the card heading, then keep the body copy inside the card with 18-20px internal padding and no more than two short lines.
+Left card: place a rounded rectangle lower-left for SKILLS using the same soft light fill (#f5f7fa or #f0f4f8). Keep at least 24px of clearance from the outer ring and enough width that the supporting copy stays fully inside the card. Put the SKILLS label inside the card as the card heading. Increase card height or width instead of squeezing text.
+Connectors: use thin light-gray connectors, but route them so they stop before any text area. No connector may pass under or through a text label.
+Center copy: place three stacked lines inside the inner circle only. Keep all center text at least 16px away from the inner circle boundary on every side. Use shorter lines and a slightly smaller size than the card headings so the hierarchy stays clear.
+Typography for web-sized viewing (~600px content column): card headings should read like 18-20px, supporting copy like 13-15px, center copy like 15-17px, title like 24-28px, and subtitle like 14-16px.
+Bottom title block: keep the title, subtitle, and three dots centered below the diagram with enough separation that the caption reads as a footer, not part of the rings.
+Overall style: minimal editorial explainer, monochrome, airy, and legible at small blog-column display sizes, with softly tinted cards on a white canvas for contrast.
+```
+
+### What each element represents
+- **Top card:** the always-on repo rules and guardrails that shape the space before anything else happens.
+- **Right card:** agents as the interpretation layer that decides how to apply those rules in context.
+- **Left card:** skills as reusable procedures and assets that carry out the chosen work.
+- **Rings:** a nested-ring cascade, not three unrelated badges: instructions define the outer boundary, agents work inside it, and skills sit at the center where execution happens.
+- **Center copy:** the author's shorthand for remembering the model: `Instructions set the rules. Agents decide. Skills execute.`
+- **Bottom title block:** the caption that restates the blog's key claim that rules constrain decisions and decisions choose the execution path.
+
+### Layout choices
+- The composition reads like a cascade into the center, not just cards surrounding circles.
+- The instructions card sits highest and feeds straight into the rings to signal baseline governance.
+- The agents card is offset right and tied to the upper rings so it feels like the interpretation layer.
+- The skills card sits lower-left and closer to the core so execution reads as downstream from agent choice.
+- The title/caption is isolated below the diagram so the visual makes the mental model first and the text closes the argument.
+
+### How to modify it
+- **Change a label:** edit the `` or `` values.
+- **Add a new governance layer:** add another circle around the existing ring group, then reposition connector paths.
+- **Add another callout card:** duplicate one `` card block, move its `rect` and text coordinates, then add a new connector ``.
+- **Adjust emphasis:** increase stroke width or font weight for one layer.
+- **Keep visual consistency:** white canvas, `#f5f7fa` (or `#f0f4f8`) card fills, `#cccccc` stroke, black text, rounded rectangles, and airy spacing.
+
+---
+
+## 2. `diagram-2-configuration-files-structure.svg`
+
+**Type:** Mermaid-generated flowchart SVG
+
+### Design System (applies to all diagrams)
+- **Background:** White or light gray (#ffffff, #f5f5f5)
+- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc)
+- **Text color:** Black (#000000) always
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room.
+
+**Canvas:** `viewBox="0 0 1584.6875 673"`
+
+### Editable Mermaid reconstruction
+```mermaid
+%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap.
+flowchart LR
+ root[".github/"]
+
+ subgraph governance["Governance"]
+ ci["copilot-instructions.md"]
+ end
+
+ subgraph workflows["workflows/"]
+ wf["archie.yml / *.yml"]
+ end
+
+ subgraph skills["skills/"]
+ skill["{name}/SKILL.md"]
+ end
+
+ subgraph agents["agents/"]
+ archie["archie.agent.md"]
+ scribe["scribe.agent.md"]
+ end
+
+ subgraph prompts["prompts/"]
+ promptdoc["architecture-review-guidelines.md"]
+ promptfile["*.prompt.md"]
+ end
+
+ root --> ci
+ root --> archie
+ root --> scribe
+ root --> skill
+ root --> promptdoc
+ root --> promptfile
+ root --> wf
+
+ ci -. governs .-> archie
+ ci -. governs .-> scribe
+ ci -. governs .-> skill
+ ci -. governs .-> wf
+
+ archie -. loads .-> promptdoc
+ wf -->|triggers| archie
+ wf -. can trigger .-> scribe
+ skill -. shares reference patterns with .-> promptfile
+```
+
+### What each element represents
+- **`.github/` root node:** the shared home for the whole configuration ecosystem.
+- **Governance cluster:** the baseline instruction layer that applies across the repo.
+- **Agents cluster:** specialist reviewer/persona files with tighter scope and boundaries.
+- **Skills cluster:** packaged, repeatable procedures Copilot can reuse.
+- **Prompts cluster:** both official `.prompt.md` templates and repo-local reference docs.
+- **Workflows cluster:** GitHub Actions entry points for label-, schedule-, dispatch-, or PR-driven automation.
+- **Dotted labeled edges:** the blog's relationship layer — who governs, loads, triggers, or shares patterns with what.
+- **Solid root edges:** the simple file-placement fact that all five families live under one `.github` home.
+
+### Layout choices
+- The diagram reads left-to-right as `.github` -> five file families -> cross-links.
+- Governance sits closest to the root because it is the baseline layer.
+- Skills and workflows occupy the middle because they represent the reusable and event-driven operational paths.
+- Agents and prompts sit farther right to show specialists depending on loaded guidance and reference material.
+- The overall framing matches the post's quick-reference lens: one navigable map of baseline, specialized, reusable, reference, and event-driven files.
+
+### How to modify it
+- **Add a new file family:** add another `subgraph` and connect it from `root`.
+- **Add another agent:** add a node inside `agents` and optionally connect governance/workflow edges.
+- **Add a new relationship:** add a dotted edge with a label.
+- **Rename paths/files:** change the node labels only; the structure can stay the same.
+
+---
+
+## 3. `diagram-3-skills-vs-prompts-decision-tree.svg`
+
+**Type:** Mermaid-generated decision tree
+
+### Design System (applies to all diagrams)
+- **Background:** White or light gray (#ffffff, #f5f5f5)
+- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc)
+- **Text color:** Black (#000000) always
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room.
+
+**Canvas:** `viewBox="0 0 665.625 1080.9375"`
+
+### Editable Mermaid reconstruction
+```mermaid
+%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap.
+flowchart TD
+ start{"Need reusable workflow?"}
+ promptReuse{"Need reusable user-selected template?"}
+ promptDoc{"Need deeper task reference context?"}
+
+ skill["Use Skill"]
+ official["Use Official Prompt"]
+ doc["Use Prompt Doc"]
+ none["No file needed"]
+
+ start -- Yes --> skill
+ start -- No --> promptReuse
+ promptReuse -- Yes --> official
+ promptReuse -- No --> promptDoc
+ promptDoc -- Yes --> doc
+ promptDoc -- No --> none
+```
+
+### What each element represents
+- **Diamond 1:** the first and most important question from the post — is this a reusable workflow?
+- **Diamond 2:** only appears if the answer is no; it checks whether you need an official reusable prompt template instead.
+- **Diamond 3:** if it is not a prompt template, it asks whether the task needs deeper repo-local reference context.
+- **Terminal boxes:** the four outcomes the article distinguishes: skill, official prompt file, prompt doc, or no extra file.
+
+### Layout choices
+- The strict top-to-bottom order mirrors the blog's sequence: reusable workflow first, reusable prompt second, reference doc third.
+- “Yes” exits early because the whole point is to stop once you have the right file family.
+- Uniform outcome boxes keep the emphasis on the routing questions instead of making one option feel privileged.
+
+### How to modify it
+- **Add another decision:** insert another diamond between `promptDoc` and the terminal nodes.
+- **Change wording:** update node labels directly.
+- **Change file taxonomy:** rename `Use Official Prompt`, `Use Prompt Doc`, etc.
+- **Preserve readability:** keep the branching direction consistent (`Yes`/`No`).
+
+---
+
+## 4. `diagram-4-azure-sdk-workflow-trigger.svg`
+
+**Type:** Mermaid-generated sequence diagram
+
+### Design System (applies to all diagrams)
+- **Background:** White or light gray (#ffffff, #f5f5f5)
+- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc)
+- **Text color:** Black (#000000) always
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room.
+
+**Canvas:** `viewBox="-50 -10 1478 572"`
+
+### Editable Mermaid reconstruction
+```mermaid
+%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap.
+sequenceDiagram
+ participant Dev as Developer
+ participant GH as GitHub Actions
+ participant WF as archie.yml
+ participant Agent as archie.agent.md
+ participant Guide as guidelines.md
+ participant PR as Pull Request
+
+ Dev->>PR: Add archie label to PR
+ PR->>GH: Trigger pull_request_target[labeled]
+ Note over GH,WF: Async GitHub-hosted run
+ WF->>Agent: Load reviewer definition
+ Agent->>Guide: Load architecture checklist
+ Guide-->>Agent: Return guidance + repo links
+ Agent-->>WF: Architecture review findings
+ WF->>PR: Create review + comments
+ PR-->>Dev: Comment appears on PR
+```
+
+### What each element represents
+- **Developer:** the person who adds the reviewer label to the PR.
+- **Pull Request:** both the trigger surface and the place where findings show up again as comments.
+- **GitHub Actions / archie.yml:** the remote asynchronous workflow layer started by that label event.
+- **archie.agent.md:** the reusable architecture-reviewer definition the workflow loads.
+- **guidelines.md:** the repo guidance/checklist that the reviewer uses as reference context.
+- **Return arrows:** findings come back directly to the PR from the workflow path shown here; the post is explicit that there is no separate collector loop in this example.
+
+### Layout choices
+- Left-to-right order follows the loop the article says it trusts: label -> workflow -> reviewer -> guidance -> PR comment.
+- The PR remains at the far right because it is both the initiation target and the visible output surface.
+- The async note sits between GitHub Actions and the workflow file to emphasize GitHub-hosted automation rather than local Copilot behavior.
+
+### How to modify it
+- **Add another reviewer asset:** insert another participant between `Agent` and `Guide`.
+- **Add another step:** add a new message line in sequence order.
+- **Rename the workflow:** change `archie.yml` everywhere.
+- **Show additional outputs:** add another message from `WF` to `PR` or another participant.
+
+---
+
+## 5. `diagram-5-file-placement-decision-tree.svg`
+
+**Type:** Mermaid-generated routing diagram
+
+### Design System (applies to all diagrams)
+- **Background:** White or light gray (#ffffff, #f5f5f5)
+- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc)
+- **Text color:** Black (#000000) always
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room.
+
+**Canvas:** `viewBox="0 0 1441.15625 336.78125"`
+
+### Editable Mermaid reconstruction
+```mermaid
+%% Color Scheme: Light backgrounds, black text, gray lines. No text overlap.
+flowchart TB
+ start{"What's the task?"}
+
+ standards["Coding standards .github/copilot-instructions.md"]
+ recurring["Recurring specialist task .github/agents/"]
+ repeatable["Repeatable workflow .github/skills/"]
+ onetime["One-time prompt or reference .github/prompts/"]
+ events["Schedule, label, or PR event .github/workflows/"]
+
+ start --> standards
+ start --> recurring
+ start --> repeatable
+ start --> onetime
+ start --> events
+```
+
+### What each element represents
+- **Center diamond:** the routing question the section cares about — what shape of task is this?
+- **Five output boxes:** the same five file families from the quick reference and decision table.
+- **Two-line box labels:** line one names the task pattern; line two gives the folder/path so you can match the task shape and drop it in the right place.
+
+### Layout choices
+- A single fan-out keeps the emphasis on classification rather than process.
+- The five destination boxes spread horizontally so the families read like peers in one routing table.
+- There are no deeper branches because this section is a placement cheat sheet, not a nuanced workflow diagram.
+
+### How to modify it
+- **Add a sixth destination:** add another box and connect from `start`.
+- **Change repo paths:** update the second line in each node.
+- **Simplify for a smaller image:** collapse to three outputs or split into two rows.
+
+---
+
+## 6. `image-1-layers.png`
+
+**Type:** raster infographic
+
+### Design System (applies to all diagrams)
+- **Background:** White or light gray (#ffffff, #f5f5f5)
+- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc)
+- **Text color:** Black (#000000) always
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room.
+
+**Size:** `1614 x 1292`
+
+
+### Visual metaphor and hierarchy
+- **Metaphor:** the blog's nested-ring governance model.
+- **Primary visual:** three concentric circles that make the control flow explicit rather than decorative.
+- **Supporting callouts:** instructions above, agents to the right, and skills lower-left, each feeding into the same ring system.
+- **Narrative hierarchy:** instructions shape the space -> agents interpret inside that boundary -> skills execute at the center -> the caption restates that rules constrain decisions.
+
+### Shapes and geometry
+- White background.
+- Three light-gray concentric circles.
+- Three large rounded cards: top, right, lower-left.
+- Two capsule labels embedded over the circles: `AGENTS` and `SKILLS`.
+- Thin connector lines from the cards into the circular system.
+- Bottom title block and three small centered dots.
+
+### Colors
+Approximate palette from the rendered image:
+- Background: white
+- Lines and borders: light gray
+- Text: black
+- No accent fill colors; the design is monochrome/minimal
+
+### Editable production specification
+Use this if recreating in Figma, Illustrator, or SVG:
+
+```text
+Canvas: 1614x1292. Use a white or very light background (#ffffff or #f5f5f5).
+All text must be black only (#000000).
+All ring strokes, card borders, capsule outlines, and connector lines must be light gray (#cccccc).
+All shapes should use white or very light fills (#ffffff or #fafafa) with light gray borders.
+Build the composition as four clearly separated text regions: top INSTRUCTIONS card, right AGENTS card, lower-left SKILLS card, and center-copy inside the inner ring. Never let text from one region cross into another.
+Center a three-ring system in the upper-middle of the canvas so it reads like nested governance rings, but reserve dedicated label lanes around it before placing any text.
+Top card: use a rounded rectangle for INSTRUCTIONS with a bold all-caps heading and at most two short lines of supporting copy. Keep 20-24px internal side padding, at least 18px top/bottom padding, and at least 24px of vertical clearance between the card and any ring label below it.
+Right card: place AGENTS far enough right that the card does not collide with the center copy or ring labels. Keep at least 24px between the card edge and the outer ring, and keep all supporting copy fully inside the card with 20px padding.
+Lower-left card: place SKILLS far enough left and low that its body copy stays inside the card and does not run into the ring system. Keep at least 24px between the card and the outer ring. If needed, widen or heighten the card rather than shrinking padding.
+Ring pills: use AGENTS and SKILLS pill labels only if each pill has its own isolated space. Do not place the AGENTS pill inside the top INSTRUCTIONS card. Keep every pill at least 12px from a ring stroke and at least 16px from any card, connector, or other text. If space is tight, move the pill outside the ring and connect it with a short leader line.
+Center copy: keep the three statements inside the inner circle only, on three separate lines, with at least 20px clearance from the circle boundary. Use shorter line lengths, lighter weight, or slightly smaller type before allowing any overlap.
+Connectors: keep all connectors thin and behind the composition, but do not let them pass under text. End connector lines before they enter a text box or pill.
+Typography must remain readable when the image is displayed in a ~600px-wide blog column. Target an effective display scale of roughly: card headings 18-22px, supporting copy 13-15px, pill labels 16-18px, center copy 15-17px, title 24-28px, subtitle 14-16px.
+At the bottom center, place the title “Layers of Governance”, then the subtitle “Rules constrain decisions, then reusable skills carry out the work.”, then three small black dots. Keep generous spacing so the footer reads separately from the diagram.
+Style: minimal editorial explainer, monochrome, airy, and easy to read — more like a remembered mental model than a product UI mock.
+```
+
+### How to modify it
+- **Best option:** edit `diagram-1-mental-model.svg` and re-export PNG.
+- **If editing the PNG design manually:** keep the circle system centered and keep all callout boxes aligned to the current top/right/lower-left pattern.
+- **If adding another layer:** add another ring and corresponding callout card.
+- **If changing the message:** update the center copy first, then title/subtitle if needed.
+
+---
+
+## 7. `image-2-where-they-live.png`
+
+**Type:** raster infographic
+
+### Design System (applies to all diagrams)
+- **Background:** White or light gray (#ffffff, #f5f5f5)
+- **Shapes:** Light fills (#fafafa) or white with light gray borders (#cccccc)
+- **Text color:** Black (#000000) always
+- **Lines/Connectors:** Light gray (#cccccc)
+- **Constraint:** NO text can overlap or touch other text, shapes, or connectors. All text must have clear breathing room.
+
+**Size:** `1400 x 900`
+
+
+### Visual metaphor and hierarchy
+- **Metaphor:** a single `.github` home with distinct rooms, matching the blog's point that these files live together but do different jobs.
+- **Primary focal point:** one large neutral folder-house container on the left-middle with `.github` text in black.
+- **Secondary structure:** five family labels stacked on the right, one for each room/file family.
+- **Connector logic:** light-gray lines show that every family belongs to the same home while staying separate by purpose.
+- **Reading order:** title -> subtitle -> shared home/container -> room labels.
+
+### Shapes and geometry
+- White or very light full-bleed background.
+- Large folder/house shape with white or very light fill and a light-gray outline, including a tab/roof shape at the upper-left.
+- Five rounded pill/box labels stacked vertically on the right.
+- Five diagonal light-gray connector lines from the folder body to each pill.
+
+### Colors
+Standardized production palette:
+- Background: white or very light gray (`#ffffff`, `#f5f5f5`)
+- Folder house and pills: white or very light fill (`#ffffff`, `#fafafa`)
+- Borders and connector lines: light gray (`#cccccc`)
+- All text, including `.github`, title, subtitle, and labels: black (`#000000`)
+- No accent colors, gradients, or dark theme treatments
+
+### Editable production prompt/specification
+No separate prompt file was found in the repo; use this extracted art-direction spec:
+
+```text
+Create a 1400x900 editorial infographic with a white or very light background (#ffffff or #f5f5f5).
+All text must be black only (#000000).
+All shape outlines and connector lines must be light gray (#cccccc).
+Top-left: large black title “Where They Live”.
+Below it: smaller black subtitle reading “A single .github home with distinct rooms for rules, specialists, reusable procedures, prompts, and triggers.”
+Center-left: a large stylized `.github` folder that also reads as one shared home. Use a light background (white or #f5f5f5). Text must be black (#000000).
+All shape outlines must be light gray (#cccccc).
+Connector lines must be light gray (#cccccc).
+Text labels for file families (copilot-instructions.md, agents/, skills/, prompts/, workflows/) must each have minimum 8–10px clearance from adjacent shapes and from each other. No overlaps.
+Right side: stack five rounded rectangular pills vertically with generous spacing, one per file family.
+Label them, top to bottom:
+1. copilot-instructions.md
+2. agents/
+3. skills/
+4. prompts/
+5. workflows/
+Connect the folder-house to each pill with its own light-gray line so each line reads like a room assignment inside the same home.
+Use white or very light fills for the folder-house and each pill, keeping the design monochrome and editorial.
+All text labels must have minimum 8px clearance from adjacent shapes and other text, with 8–10px preferred.
+Style: clean explainer graphic, flat vector shapes, soft rounded corners, no texture, strong contrast, and a clear “live together, different jobs” message.
+```
+
+### How to modify it
+- **Change a family name:** edit the text inside one pill only.
+- **Add a new family:** add another pill to the stack and route a new light-gray connector line from the folder.
+- **Change the metaphor:** keep the same connector system, but swap the folder-house for another “single home/container” shape.
+- **Keep hierarchy stable:** title and subtitle stay top-left; container stays left; destinations stay right.
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png
new file mode 100644
index 0000000..f068d01
Binary files /dev/null and b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-layers-of-governance.png differ
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-mapping-file-families.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-mapping-file-families.png
new file mode 100644
index 0000000..5cbee2a
Binary files /dev/null and b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-1-mapping-file-families.png differ
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-2-understanding-layers.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-2-understanding-layers.png
new file mode 100644
index 0000000..6d6803c
Binary files /dev/null and b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-2-understanding-layers.png differ
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-4-skills-vs-prompts.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-4-skills-vs-prompts.png
new file mode 100644
index 0000000..ee295b2
Binary files /dev/null and b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-4-skills-vs-prompts.png differ
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-5-putting-it-together.png b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-5-putting-it-together.png
new file mode 100644
index 0000000..6045fc4
Binary files /dev/null and b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-5-putting-it-together.png differ
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-manifest.md b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-manifest.md
new file mode 100644
index 0000000..5a4e179
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-manifest.md
@@ -0,0 +1,17 @@
+# Generated Watercolor Illustrations
+
+Generated on: 2026-05-31 20:47:16
+
+## Images
+
+1. watercolor-1-mapping-file-families.png
+ - Purpose: Opening section and quick reference table, where the post turns scattered `.github` files into one usable mental model.
+ - Status: ✅ Generated
+
+2. watercolor-2-understanding-layers.png
+ - Purpose: Instructions, agents, and skills section, where the post builds the author's mental model of governance, decision-making, and reusable execution.
+ - Status: ✅ Generated
+
+3. watercolor-3-tracing-workflow.png
+ - Purpose: The Azure workflow section and the later decision table, where the post moves from abstract categories to a concrete path the author can actually defend with links.
+ - Status: ✅ Generated
diff --git a/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-prompts.md b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-prompts.md
new file mode 100644
index 0000000..3d5e4f1
--- /dev/null
+++ b/website/blog/media/2026-06-03-copilot-config-files-guide/watercolor-prompts.md
@@ -0,0 +1,24 @@
+---
+title: "Watercolor Prompts for Copilot Config Files Guide"
+---
+
+# Watercolor Illustration Prompts
+
+## Style & Character
+Style: Watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text
+Character: Normal woman with average appearance and practical clothes in a grounded work setting
+
+## 1. Mapping the Five File Families
+- **Narrative context:** Opening section and quick reference table, where the post turns scattered `.github` files into one usable mental model.
+- **Woman's activity:** She sits at a desk with folders, notes, and small stacks representing instructions, agents, skills, prompts, and workflows, physically sorting them into a layout that finally makes sense.
+- **Prompt:** Normal woman at desk sorting five distinct stacks of repository files into order, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text
+
+## 2. Understanding the Layers
+- **Narrative context:** Instructions, agents, and skills section, where the post builds the author's mental model of governance, decision-making, and reusable execution.
+- **Woman's activity:** She studies nested trays or transparent layers on a desk, lifting one layer at a time to understand how the pieces sit together instead of blending into one confusing pile.
+- **Prompt:** Normal woman examining nested transparent layers of governance documents, comparing one layer to another, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text
+
+## 3. Tracing a Real Workflow
+- **Narrative context:** The Azure workflow section and the later decision table, where the post moves from abstract categories to a concrete path the author can actually defend with links.
+- **Woman's activity:** She follows a line of pinned notes and folders from one workstation area to another, checking how a label, a workflow, a reviewer, and a returned comment connect in practice.
+- **Prompt:** Normal woman in home office tracing a path between pinned repository notes and workflow folders, watercolor illustration, soft wet-on-wet washes, visible paper texture, warm muted tones, loose brushwork, no text