Avanade · chullybun · Jul 6, 2026 · Jul 2, 2026 · Jul 2, 2026 · Jul 2, 2026
diff --git a/.claude/commands/coreex-docs-sync.md b/.claude/commands/coreex-docs-sync.md
@@ -1,87 +1,76 @@
 ---
-description: "Fetch the CoreEx sample architecture docs and all per-package AI usage guides from GitHub and cache them locally under .github/docs/coreex/ for offline, faster expert guidance."
-allowed-tools: [Read, Write, Glob, Grep, WebFetch]
+description: "Refresh the full CoreEx AI workflow asset bundle (instructions, skills, prompts, the coreex-expert agent, and the .github/docs/coreex/ docs cache) to the CoreEx.Template release matching the project's installed CoreEx NuGet version. Version-pinned — never fetches unreleased GitHub main content."
+allowed-tools: [Read, Bash, Glob, Grep]
 ---
 
-Sync the CoreEx docs to `.github/docs/coreex/`. Follow these steps exactly.
+<!--
+  AI workflow asset — dual-audience notice:
+  - In the Avanade/CoreEx repository: this file is the authored source. Edit it here.
+  - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via
+    `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly —
+    propose the change upstream in Avanade/CoreEx instead, then refresh once it is released.
+-->
 
-## Step 1 — Detect current CoreEx version
+Refresh the CoreEx AI asset bundle. Follow these steps exactly.
+
+## Step 1 — Detect the target CoreEx version
 
 Search for the `CoreEx` NuGet package version in this order, stopping at the first match:
 1. `Directory.Packages.props` — look for `<PackageVersion Include="CoreEx" Version="..." />`
 2. Any `*.csproj` file — look for `<PackageReference Include="CoreEx" Version="..." />`
 3. `Directory.Build.props`
 
-Record the version (or `unknown` if not found). Use it in the manifest.
+If none is found, stop and tell the user this project has no `CoreEx` reference yet — there is nothing to pin a refresh to. `CoreEx.Template` and `CoreEx` are released from the same repo at the same version number, so this detected version is also the exact `CoreEx.Template` version to install.
 
-## Step 2 — Detect referenced CoreEx packages (for manifest only)
+## Step 2 — Check the current manifest
 
-Scan `Directory.Packages.props` and all `*.csproj` files for `PackageVersion` or `PackageReference` entries whose `Include` attribute starts with `CoreEx`. Collect the distinct package names. This list goes into the manifest so the CoreEx Expert knows which packages the project currently uses — it does not limit which guides are synced.
+Read `.github/docs/coreex/manifest.txt` if it exists and extract its `coreex-version` value.
 
-## Step 3 — Create cache directories
+- If the manifest is missing, continue to Step 3.
+- If the manifest's `coreex-version` already equals the version detected in Step 1, report **already in sync** and stop — nothing to do.
+- Otherwise, continue to Step 3.
 
-Ensure both directories exist. Create them if absent:
-- `.github/docs/coreex/`
-- `.github/docs/coreex/agents/`
+## Step 3 — Install the pinned template version
 
-## Step 4 — Fetch and write the sample architecture docs
+Run, substituting the version detected in Step 1:
 
-Fetch each URL below and write to the corresponding local path. Report each as it completes.
+```bash
+dotnet new install CoreEx.Template::<version>
+```
 
-| URL | Local path |
-|---|---|
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/local-dev.md` | `.github/docs/coreex/local-dev.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/layers.md` | `.github/docs/coreex/layers.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/patterns.md` | `.github/docs/coreex/patterns.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/contracts-layer.md` | `.github/docs/coreex/contracts-layer.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/domain-layer.md` | `.github/docs/coreex/domain-layer.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/application-layer.md` | `.github/docs/coreex/application-layer.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/infrastructure-layer.md` | `.github/docs/coreex/infrastructure-layer.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/hosts-layer.md` | `.github/docs/coreex/hosts-layer.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/testing.md` | `.github/docs/coreex/testing.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/tooling.md` | `.github/docs/coreex/tooling.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/samples/docs/aspire.md` | `.github/docs/coreex/aspire.md` |
+Never install a bare `dotnet new install CoreEx.Template` — it silently resolves to whatever is latest and can desync the AI assets from the project's actual `CoreEx` version.
 
-## Step 5 — Fetch and write all per-package guides
+## Step 4 — Dry-run first
 
-Fetch the `AGENTS.md` for every CoreEx package listed below — regardless of whether the project currently references them. This allows the CoreEx Expert to guide on and recommend any package, including ones not yet adopted.
+Run (add `--app-folder <path>` if this is a monorepo, per the recorded app folder):
 
-| URL | Local path |
-|---|---|
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.AspNetCore/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.AspNetCore.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.AspNetCore.NSwag/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.AspNetCore.NSwag.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Azure.Messaging.ServiceBus/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Azure.Messaging.ServiceBus.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Caching.FusionCache/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Caching.FusionCache.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.CodeGen/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.CodeGen.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Data/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Data.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Database/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Database.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Database.Postgres/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Database.Postgres.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Database.SqlServer/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Database.SqlServer.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.DomainDriven/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.DomainDriven.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.EntityFrameworkCore/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.EntityFrameworkCore.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Events/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Events.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.RefData/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.RefData.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.UnitTesting/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.UnitTesting.md` |
-| `https://raw.githubusercontent.com/Avanade/CoreEx/main/src/CoreEx.Validation/AGENTS.md` | `.github/docs/coreex/agents/CoreEx.Validation.md` |
+```bash
+dotnet new coreex-ai --dry-run
+```
 
-If any fetch fails, record the failure, skip that file, and continue.
+Always include `--dry-run` explicitly — it is the only invocation guaranteed never to write anything. Omitting `--force` alone is **not** equivalent: it blocks and lists "Overwrite" conflicts only when existing files would change, but if none of the target files exist yet (e.g. a repo missing most of the bundle) it creates them for real with no confirmation. `--dry-run` prints the "Create"/"Overwrite" list of every file that would change and always applies nothing; show it to the user before proceeding.
 
-## Step 6 — Write the manifest
+## Step 5 — Confirm, then apply
 
-Write `.github/docs/coreex/.manifest` with this exact format:
+Ask the user to confirm, then re-run with `--force`:
 
+```bash
+dotnet new coreex-ai --force
 ```
-synced: YYYY-MM-DD
-coreex-version: <version from Step 1, or "unknown">
-referenced-packages: <comma-separated list of packages detected in Step 2, or "none detected">
-```
+
+`--force` overwrites every file the template's current version emits. It does **not** delete files an older/superseded template version left behind (see Step 6).
+
+## Step 6 — Flag possible orphans
+
+Compare the skill folder names under `.github/skills/coreex-*/` against the current known L1 skill set (listed in [`coreex-ai-workflows.md`](/.github/coreex-ai-workflows.md)). Any extra folder is very likely left over from a prior template version and should be flagged for manual review, not assumed safe to delete automatically.
+
+Scoped to the `coreex-` prefix deliberately, not all of `.github/skills/*/`: `CoreEx.Template` only ever installs `coreex-`-prefixed skill folders, and a consumer repo may have other skills installed that this template neither writes nor owns (a personal skill, one from another tool, etc.). Comparing the full folder set would falsely flag those as CoreEx orphans.
 
 ## Step 7 — Report
 
 Summarise:
-- How many architecture docs were written successfully.
-- How many package guides were written successfully (out of 16).
-- Any files that failed to fetch (with the error).
-- The CoreEx version and referenced packages recorded in the manifest.
-- A reminder: *"Re-run `/coreex-docs-sync` after bumping the CoreEx NuGet version or when the CoreEx Expert suggests the cache is stale."*
+- The refreshed `coreex-version` (from the new `.github/docs/coreex/manifest.txt`).
+- The files changed (from the Step 4 dry-run list).
+- Any flagged orphans from Step 6.
+
+There is no live GitHub `main` fetch anywhere in this flow and no age-based staleness check — a version mismatch (or a missing manifest) is the only signal that triggers a refresh.
diff --git a/.claude/commands/coreex-expert.md b/.claude/commands/coreex-expert.md
@@ -1,8 +1,16 @@
 ---
 description: "CoreEx Expert — architecture guidance, pattern decisions, and sample-aligned advice for projects using CoreEx NuGet packages."
-allowed-tools: [Read, Glob, Grep, WebFetch, WebSearch, Edit, Write]
+allowed-tools: [Read, Glob, Grep, WebFetch, WebSearch, Edit, Write, Bash]
 ---
 
+<!--
+  AI workflow asset — dual-audience notice:
+  - In the Avanade/CoreEx repository: this file is the authored source. Edit it here.
+  - In a consumer repository: this file was generated by `dotnet new coreex-ai` (or refreshed via
+    `dotnet new coreex-ai --force` / the `/coreex-docs-sync` skill). Do not hand-edit it directly —
+    propose the change upstream in Avanade/CoreEx instead, then refresh once it is released.
+-->
+
 Read `.github/agents/coreex-expert.agent.md` and follow the instructions in that file.
 
 The user's question or request follows. Apply the CoreEx Expert role, operating rules, and response format defined in the agent file.
diff --git a/.github/AI-WORKFLOWS.md b/.github/AI-WORKFLOWS.md