[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6FKWMG0K059CE3Z59CGC9ZS":3,"skill-same:01M6FKWMG0K059CE3Z59CGC9ZS":89},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":42,"linkOnly":43,"markdownContent":44,"markdownBody":45,"frontMatter":46,"refName":47,"commitSha":48,"skillDirectory":49,"forksCount":50,"repositoryHtmlUrl":51,"repositoryHomepageUrl":52,"ownerHtmlUrl":53,"ownerBlogUrl":54,"ownerDescription":55,"updatedAt":56,"install":57,"resources":70},"01M6FKWMG0K059CE3Z59CGC9ZS","cli-channel-debugging",null,"Emulates any Aspire CLI build identity (channel, version, commit, package source) from a locally built CLI using ASPIRE_CLI_* environment variables and the install sidecar, so a reported bug can be reproduced and fixed locally without going through the install\u002FPR loop. Use this when asked to reproduce channel\u002Fversion\u002Fquality-specific CLI behavior, simulate a daily\u002Fstaging\u002Fstable\u002FPR build locally, or decide which override knobs to set for a given scenario.","microsoft\u002Faspire","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M6FKTZ7ND1S9JN6JTVK7A7MD",6426,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-channel-debugging\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41],"cli channel debugging","debugging","cli","channel","install","when","source","which","Variables","pr loop","environment variables","scenario","bug","daily","environment","decide","loop","SET","package","pr","aspire","identity","commit","2026-11-10 10:12:30",false,"---\nname: cli-channel-debugging\ndescription: Emulates any Aspire CLI build identity (channel, version, commit, package source) from a locally built CLI using ASPIRE_CLI_* environment variables and the install sidecar, so a reported bug can be reproduced and fixed locally without going through the install\u002FPR loop. Use this when asked to reproduce channel\u002Fversion\u002Fquality-specific CLI behavior, simulate a daily\u002Fstaging\u002Fstable\u002FPR build locally, or decide which override knobs to set for a given scenario.\n---\n\nYou are a specialized agent for reproducing version\u002Fchannel\u002Fquality-specific Aspire CLI\nbehavior from a **locally built CLI**. The CLI resolves its own identity (channel, version,\ncommit, and — optionally — the directory it resolves `Aspire*` packages from) at startup. By\nsetting a few environment variables (or an install sidecar), you can make\n`dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>` behave as if it were any released, staging,\ndaily, or PR build. This lets you reproduce a bug that only manifests on a specific build and\nfix it on the current branch — without waiting for an install or a PR build.\n\nRead `docs\u002Fspecs\u002Fcli-identity-sidecar.md` for the full design. This skill is the operational\nmatrix: which knobs to set for each scenario.\n\n## ⛔ MANDATORY: State the scenario and exact knobs in chat before running\n\nBefore you run **any** emulated CLI command, you MUST write a short line in chat declaring:\n\n1. **Which scenario row** (1–7b below) you are emulating.\n2. **The exact environment variables and values** you are setting (channel, version, commit,\n   packages directory, etc.).\n3. For `ASPIRE_CLI_PACKAGES`: that you **built\u002Fpopulated the directory yourself** and verified\n   it is clean (exactly one version of each `Aspire*` package). Do **not** hand-wave \"you\n   populate the directory\" — actually run the build\u002Fpack, show the command, and list what\n   landed there.\n\nExample:\n\n> Using **Scenario 2** (PR build identity + locally built packages):\n> `ASPIRE_CLI_CHANNEL=pr-18087`, `ASPIRE_CLI_PACKAGES=\u003Crepo>\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping`.\n> Packed locally with `.\u002Fbuild.sh --pack -c Release`; verified Shipping has one version of each\n> `Aspire*` package.\n\nIf you cannot determine the right knobs, ask — don't guess.\n\n## The override knobs\n\n### Identity environment variables (process-local; the source of truth)\n\nThese are read by `IdentityResolver` and flow into `CliExecutionContext`. They change the\nCLI's **global identity**, so they affect hive discovery, package-channel selection, staging\nfeed derivation, `--version`, telemetry identity tags, and the SDK-skew warning. They are\n**stripped before the CLI spawns child Aspire processes**, so they never leak into peer probes\nor `aspire doctor`'s child invocations — treat them as process-local test affordances.\n\n| Env var | Effect |\n|---|---|\n| `ASPIRE_CLI_CHANNEL` | Identity channel: `stable`, `staging`, `daily`, `local`, or `pr-\u003CN>`. Drives hive selection and staging-feed provenance. |\n| `ASPIRE_CLI_VERSION` | Informational version (e.g. `13.5.0-preview.1.26310.9`). Drives version pins, the skew warning, and `--version` output. |\n| `ASPIRE_CLI_COMMIT` | Source commit SHA. Drives the staging darc feed name (`darc-pub-microsoft-aspire-\u003Csha8>`). |\n| `ASPIRE_CLI_PACKAGES` | A flat directory of `.nupkg` files (e.g. `artifacts\u002Fpackages\u002F\u003CConfig>\u002FShipping`). The CLI synthesizes a package channel **named after `ASPIRE_CLI_CHANNEL`** that maps `Aspire*` to this directory (everything else → nuget.org), **replacing** any same-named built-in\u002Fdiscovered\u002FPR channel. See the cleanliness caveat below. |\n| `ASPIRE_CLI_NUGET_SERVICE_INDEX` | Replaces the canonical `https:\u002F\u002Fapi.nuget.org\u002Fv3\u002Findex.json` URL the CLI writes into **newly generated** `NuGet.config` files. Never rewrites URLs read from existing configs. |\n\nWhen any of these is set, the CLI prints a yellow banner on **stderr**:\n`Aspire CLI is emulating identity '\u003Cchannel>' version '\u003Cversion>'...`. Seeing that banner\nconfirms `IdentityOverridden` is true.\n\n### Install sidecar (`.aspire-install.json`)\n\nThe same values can come from the `channel`, `version`, `commit`, `nugetServiceIndexOverride`,\nand `packages` fields of an `.aspire-install.json` sidecar next to the CLI binary. Resolution\norder per field is **env var → sidecar field → assembly-baked stamp**. Use the sidecar when\nyou want a persistent emulated identity for an installed binary; use env vars for one-off runs.\nInstaller-authored `channel`, `version`, and `commit` fields describe the real installed identity\nand do not show the emulation banner, so use `aspire doctor --format Json` to confirm their source.\nThe developer-only `nugetServiceIndexOverride` and `packages` sidecar fields still show the banner.\n\n### Legacy PackagingService config keys (staging-feed routing only)\n\nThese predate the global env vars and are **narrower**: they only influence staging-feed\nrouting decisions inside `PackagingService`; they do **not** change the global identity, hive\nlookups, or `--version`. Set with `aspire config set -g \u003Ckey> \u003Cvalue>`.\n\n| Config key | Effect |\n|---|---|\n| `overrideCliIdentityChannel` | Identity used for **staging-feed decisions only** (validated against the known channel set). |\n| `overrideCliInformationalVersion` | Informational version used to derive the staging SHA-specific feed URL. |\n| `overrideStagingFeed` | Forces staging to be available and points it at an explicit feed URL. |\n| `stagingPinToCliVersion` | When `true` (and using the shared feed), pins resolution to the CLI version. |\n\n**Prefer the `ASPIRE_CLI_*` env vars for whole-identity emulation.** Use the config keys only\nwhen you specifically want to exercise staging-feed routing from an otherwise-plain local build\n(the `eng\u002Fscripts\u002Fdebug-staging.sh` \u002F `debug-stable.sh` recipes do exactly this — see\n`docs\u002Fcli-staging-validation.md`).\n\n## Running the local CLI under an emulated identity\n\n```bash\n# From the repo root. Build once, then run with the knobs set:\nASPIRE_CLI_CHANNEL=daily \\\nASPIRE_CLI_VERSION=13.5.0-preview.1.26310.9 \\\nASPIRE_CLI_COMMIT=95f0d2968... \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccommand>\n```\n\nYou can also run the already-built binary directly to skip the rebuild:\n`artifacts\u002Fbin\u002FAspire.Cli\u002FDebug\u002Fnet11.0\u002Faspire.dll` via `dotnet \u003Cdll> -- \u003Ccommand>`.\n\nConfirm the emulation took effect: `aspire --version` prints the emulated version, and the\nemulation banner appears on stderr. (Note: `aspire doctor` reports some fields from the\nphysical binary by design — see the spec.)\n\n> **Polyglot channel resolution from a source build.** When you run a source (DEBUG) build from\n> inside the Aspire repo, `AspireRepositoryDetector` can match the repo's `Aspire.slnx` (it falls\n> back to the CLI binary's `Environment.ProcessPath`, not the apphost's location). For a polyglot\n> (TypeScript\u002FPython) apphost that would force \"project-reference mode\" and short-circuit channel\n> resolution, so `aspire add` would silently resolve **stable nuget.org** packages instead of the\n> emulated channel's feed. To keep emulation faithful, `GuestAppHostProject.IsUsingProjectReferences`\n> now returns `false` whenever an `ASPIRE_CLI_*` identity override is active — so setting any\n> identity env var makes the source build resolve packages exactly like the installed CLI it is\n> emulating. (A real installed CLI is unaffected: Release builds only honor `ASPIRE_REPO_ROOT`.)\n\n## Helper scripts (bundled with this skill)\n\nTwo scripts live next to this `SKILL.md` (each with a `.sh` and a `.ps1` variant). Always\nprefer them over hand-typing versions — the daily\u002Fstaging feeds are unsorted and interleave\nold `9.x` builds, so eyeballing \"the latest\" is error-prone.\n\n### `get-aspire-channel-version.{sh,ps1}` — resolve the version to emulate\n\nMaps a channel to the exact feed the CLI's built-in package channels resolve `Aspire*` from\n(see `src\u002FAspire.Cli\u002FPackaging\u002FPackagingService.cs`), queries it anonymously, and prints **only**\nthe latest version to stdout (diagnostics go to stderr), so it pipes cleanly into\n`ASPIRE_CLI_VERSION`:\n\n```bash\n.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh stable     # -> 13.4.3 (nuget.org)\n.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh daily      # -> 13.5.0-preview.1.NNNNN.N (dnceng\u002Fdotnet9)\n.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh staging --commit \u003Csha>   # darc-pub-microsoft-aspire-\u003Csha8>\n\nexport ASPIRE_CLI_VERSION=\"$(.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh daily)\"\n```\n\nOptions: `--package \u003Cid>` (default `Aspire.Hosting.AppHost`, present on all three feeds and\nversioned identically to the product), `--stable-only` (daily\u002Fstaging → stable-shaped only),\n`--prerelease` (stable → allow prereleases). Staging requires `--commit`; note darc feeds are\nper-RC-build and may have been garbage-collected for older commits (clean `404` = no such feed).\n\n### `emulate-aspire-cli.{sh,ps1}` — one-line scenario setup (SOURCE it)\n\nSets the `ASPIRE_CLI_*` env vars and defines an `aspire` function pointing at this repo's built\nCLI. For `stable`\u002F`daily`\u002F`staging` it auto-resolves the version via the resolver above. It\n**must be sourced** (bash\u002Fzsh) or **dot-sourced** (pwsh) so the env + function persist:\n\n```bash\n# bash \u002F zsh — builds the CLI, resolves the latest daily version, defines `aspire`\nsource .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh daily\naspire --version            # confirms the emulation banner + version\n```\n\n```pwsh\n. .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.ps1 staging -Commit \u003Csha>\naspire --version\n```\n\nOptions: `--version \u003Cv>` \u002F `-Version` (pin instead of auto-resolving; required for `local`\u002F`pr-\u003CN>`),\n`--commit` \u002F `-Commit`, `--packages \u003Cdir>` \u002F `-Packages` (sets `ASPIRE_CLI_PACKAGES`), `--config`\n\u002F `-Config` (`Debug`|`Release`, default `Debug`), `--no-build` \u002F `-NoBuild` (use an existing binary).\n\n## Driving a scenario from a Terminal canvas (Copilot app)\n\nWhen running inside the Copilot app, give the user a live, reusable shell per scenario by\nopening a **Terminal canvas** rather than only running one-off `bash` tool commands. The flow:\n\n1. **State the scenario + knobs in chat** (mandatory rule above) and, for feed-backed channels,\n   resolve the real version first with `get-aspire-channel-version.sh` so the title and env are\n   accurate.\n2. Build the CLI once (`dotnet build src\u002FAspire.Cli\u002FAspire.Cli.csproj -p:SkipNativeBuild=true`),\n   or let `emulate-aspire-cli.sh` build it.\n3. `open_canvas` with `canvasId: \"terminal\"` and a descriptive `title` (e.g.\n   `aspire (emulating daily 13.5.0-preview.1.NNNNN.N)`); pick a stable `instanceId` per scenario\n   so re-opening focuses the same panel. Open a **separate** instance per identity so the user\n   can keep, say, a `stable` and a `daily` terminal side by side.\n4. Drive it with the `send_terminal_input` action (input must be an **object**, e.g.\n   `{\"input\": \"aspire --version\"}`; a trailing Enter is added by default). The fastest setup is a\n   single `source .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh \u003Cchannel>` line;\n   otherwise send the `export ASPIRE_CLI_*` lines and the `aspire() { dotnet \"\u003Cdll>\" \"$@\"; }`\n   function definition individually.\n5. Verify with `aspire --version`. `read_terminal_output` may be unavailable in some app\n   contexts (\"Terminal not found or not running\"); when it is, confirm the emulation\n   independently by running the same env + built `aspire.dll` through a normal `bash` tool call\n   and checking the banner + version match — the canvas keystrokes are still delivered for the\n   user.\n\nReuse `instanceId`s across turns so \"the daily terminal\" stays the same panel the user is looking at.\n\n## The scenario matrix\n\n| # | Scenario | Identity | `Aspire*` package source | How |\n|---|---|---|---|---|\n| 1 | Local build + locally built packages (local hive) | `local` | `~\u002F.aspire\u002Fhives\u002Flocal\u002Fpackages` **or** local `Shipping` dir | `.\u002Flocalhive.sh` (no env vars) — or `ASPIRE_CLI_PACKAGES=\u003CShipping>` |\n| 2 | PR build identity + locally built packages | `pr-\u003CN>` | local `Shipping` dir | `ASPIRE_CLI_CHANNEL=pr-\u003CN>` + `ASPIRE_CLI_PACKAGES=\u003CShipping>` |\n| 3 | PR build identity + CI-built packages, local CLI | `pr-\u003CN>` | `~\u002F.aspire\u002Fhives\u002Fpr-\u003CN>\u002Fpackages` | `get-aspire-cli-pr.sh --pr \u003CN>`, then `ASPIRE_CLI_CHANNEL=pr-\u003CN>` |\n| 4 | Latest daily, local CLI | `daily` | dnceng\u002Fdotnet9 daily feed | `ASPIRE_CLI_CHANNEL=daily` + `ASPIRE_CLI_VERSION` (+ `ASPIRE_CLI_COMMIT`) |\n| 5 | Staging, unstable version | `staging` | `darc-pub-microsoft-aspire-\u003Csha8>` feed (quality Both) | `ASPIRE_CLI_CHANNEL=staging` + prerelease `ASPIRE_CLI_VERSION` + `ASPIRE_CLI_COMMIT` |\n| 6 | Staging, stable version | `staging` | `darc-pub-microsoft-aspire-\u003Csha8>` feed (quality Both) | `ASPIRE_CLI_CHANNEL=staging` + stable-shaped `ASPIRE_CLI_VERSION` + `ASPIRE_CLI_COMMIT` |\n| 7 | Released build repro | `stable` | nuget.org | `ASPIRE_CLI_CHANNEL=stable` + released `ASPIRE_CLI_VERSION` |\n| 7b | Released repro + CLI+hosting fix spanning packages | `stable` | locally rebuilt `Shipping` dir | as 7 + `ASPIRE_CLI_PACKAGES=\u003Cclean-rebuilt-dir>` |\n\n### Scenario 1 — Local build + locally built packages\n\n`.\u002Flocalhive.sh [-c Release|Debug] [-n \u003Chive>]` packs NuGet packages into\n`artifacts\u002Fpackages\u002F\u003CConfig>\u002FShipping`, creates `~\u002F.aspire\u002Fhives\u002F\u003Chive>\u002Fpackages`, and installs\nthe CLI to `~\u002F.aspire\u002Fbin`. The installed CLI bakes a `local` identity and discovers the hive —\nno env vars needed.\n\nTo skip the hive copy and point a dev-tree CLI straight at the packed output:\n\n```bash\n.\u002Fbuild.sh --pack -c Release        # -> artifacts\u002Fpackages\u002FRelease\u002FShipping\nASPIRE_CLI_PACKAGES=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\n### Scenario 2 — PR build identity + locally built packages (agent builds the packages)\n\nYou (the agent) build the packages, then run the local CLI as the PR build:\n\n```bash\n.\u002Fbuild.sh --pack -c Release        # produces artifacts\u002Fpackages\u002FRelease\u002FShipping\n# Verify the Shipping dir is clean (one version per Aspire* package) before running.\nASPIRE_CLI_CHANNEL=pr-\u003CN> \\\nASPIRE_CLI_PACKAGES=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\n`ASPIRE_CLI_PACKAGES` wins over a same-named hive or PR-install channel, so the CLI resolves\n`Aspire*` from your freshly built packages while presenting a `pr-\u003CN>` identity.\n\n### Scenario 3 — PR build identity + CI-built packages, local CLI\n\nUse this to test something locally against a PR's **CI-built** packages without rebuilding them:\n\n```bash\neng\u002Fscripts\u002Fget-aspire-cli-pr.sh --pr \u003CN>     # populates ~\u002F.aspire\u002Fhives\u002Fpr-\u003CN>\u002Fpackages\nASPIRE_CLI_CHANNEL=pr-\u003CN> dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nNo `ASPIRE_CLI_PACKAGES` — the local CLI discovers `~\u002F.aspire\u002Fhives\u002Fpr-\u003CN>` by name because its\nidentity channel matches. (See `docs\u002Fdogfooding-pull-requests.md` and `eng\u002Fscripts\u002FREADME.md`.)\n\n### Scenario 4 — Latest daily, local CLI\n\n```bash\n# Fast path: resolves the real latest daily version, builds, defines `aspire`.\nsource .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh daily\n\n# Manual equivalent:\nASPIRE_CLI_CHANNEL=daily \\\nASPIRE_CLI_VERSION=\"$(.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh daily)\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nThe `daily` channel maps `Aspire*` to the dnceng `dotnet9` feed. Use the **real** daily version\nof the build you're emulating (the resolver gives it to you) so version pins and the skew\nwarning match what users saw. `ASPIRE_CLI_COMMIT` is optional here — daily resolves from the\nshared feed, not a SHA-specific darc feed.\n\n### Scenarios 5 & 6 — Staging (unstable vs stable version)\n\n```bash\n# 5 — unstable (prerelease-shaped) version -> quality Both\nASPIRE_CLI_CHANNEL=staging \\\nASPIRE_CLI_VERSION=13.4.0-preview.1.26280.6 \\\nASPIRE_CLI_COMMIT=\u003Cfull-commit-sha> \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n\n# 6 — stable-shaped version -> quality Both (the #17527 stabilizing-build scenario)\nASPIRE_CLI_CHANNEL=staging ASPIRE_CLI_VERSION=13.4.0 ASPIRE_CLI_COMMIT=\u003Cfull-commit-sha> \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nStaging feed provenance is derived from the commit: `darc-pub-microsoft-aspire-\u003Csha8>`. The\nchannel uses `Both` for either version shape because a stable-shaped build can still publish\nprerelease-only integrations alongside stable packages.\nAlternatively, `eng\u002Fscripts\u002Fdebug-staging.sh` \u002F `debug-stable.sh` exercise the same routing via\nthe legacy config keys — see `docs\u002Fcli-staging-validation.md`.\n\n### Scenario 7 — Released build repro\n\n```bash\n# Fast path: resolves the latest stable on nuget.org (override with --version for an older release).\nsource .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh stable\n\n# Manual \u002F pin a specific release:\nASPIRE_CLI_CHANNEL=stable ASPIRE_CLI_VERSION=13.4.2 dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nThe `stable` channel maps `Aspire*` to nuget.org. Use the exact released version the bug was\nreported against (`get-aspire-channel-version.sh stable` gives the current latest).\n\n### Scenario 7b — Released repro with a fix spanning CLI **and** hosting packages\n\nWhen the fix touches packages too (e.g. `Aspire.Hosting.*`), rebuild those packages from the\ncurrent branch at the released version into a **clean** directory and layer them in:\n\n```bash\n.\u002Fbuild.sh --pack -c Release                  # rebuild packages from this branch's source\n# Stage exactly the packages you changed into a clean dir (or clean Shipping first).\nASPIRE_CLI_CHANNEL=stable \\\nASPIRE_CLI_VERSION=13.4.2 \\\nASPIRE_CLI_PACKAGES=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nIdentity stays `stable`\u002F`13.4.2` while `Aspire*` resolves from your locally rebuilt packages, so\nyou can validate a CLI+hosting fix together before publishing anything.\n\n### Scenario 7c — All-local \"future release\" (version not yet on nuget.org)\n\nUse this to dry-run a not-yet-shipped release (e.g. emulate a future `13.5.0` stable build)\nentirely from locally built packages — templates and integrations both resolve from a local\ndirectory, nothing has to be published. This is the most self-contained scenario and the one the\nidentity-sidecar package-resolution fix specifically enables.\n\n```bash\n# 1. Build packages in the exact version shape you want to emulate.\n#    Stable shape (no prerelease suffix):\n.\u002Fbuild.sh --pack -c Release \u002Fp:VersionPrefix=13.5.0 \u002Fp:StabilizePackageVersion=true\n#    Prerelease shape instead: \u002Fp:VersionPrefix=13.5.0 \u002Fp:VersionSuffix=preview.1\nSTABLE_DIR=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\"   # clean: one version per Aspire* id\n\n# 2. (Buildability) Register the local dir as an AMBIENT NuGet source — see note below.\ndotnet nuget add source \"$STABLE_DIR\" --name local-emulated-stable\n\n# 3. Emulate the release. aspire new + aspire add now resolve 13.5.0 from the local dir.\nASPIRE_CLI_CHANNEL=stable ASPIRE_CLI_VERSION=13.5.0 ASPIRE_CLI_PACKAGES=\"$STABLE_DIR\" \\\n  dotnet run --project src\u002FAspire.Cli -- new aspire-starter --name MyApp --non-interactive\n```\n\n> **Turnkey alternative — `localhive --version`.** `.\u002Flocalhive.sh --version 13.5.0` (or\n> `.\\localhive.ps1 -Version 13.5.0`) packs the stable shape, populates `~\u002F.aspire\u002Fhives\u002Flocal\u002Fpackages`\n> with **only** the exact `13.5.0` packages, and installs the CLI — no manual `VersionPrefix`\u002F\n> `StabilizePackageVersion` flags and no stale-version cleanup needed. Add `--archive` to also produce a\n> portable `.tar.gz` for the E2E tests (below). You still set the three `ASPIRE_CLI_*` env vars (and the\n> ambient source for buildability) to emulate the release from that hive.\n>\n> **Fully turnkey with `-o DIR`.** `.\u002Flocalhive.sh --version 13.5.0 -o \u002Ftmp\u002Faspire-1350` writes a\n> self-contained portable layout (`bin\u002F`, `hives\u002Flocal\u002Fpackages\u002F`) **and** an `activate.sh`\n> (`localhive.ps1` writes `activate.ps1`). `source \u002Ftmp\u002Faspire-1350\u002Factivate.sh` puts the CLI on PATH,\n> exports the three `ASPIRE_CLI_*` vars (channel=stable, version=`13.5.0`, packages=the hive), sets a\n> **hermetic** `NUGET_PACKAGES` (see the cache hazard below), and drops you into a `work\u002F` dir — a\n> one-command emulated stable session.\n\n> **⚠️ NuGet global-cache pollution when rebuilding a FIXED stable version.** NuGet's global packages\n> folder (`~\u002F.nuget\u002Fpackages\u002F\u003Cid>\u002F\u003Cversion>\u002F`) caches **extracted** packages keyed by the version\n> string. When you emulate a *fixed* stable version like `13.5.0` and then **rebuild** it, a stale\n> `13.5.0` left in that shared cache by an earlier build **silently shadows** the freshly built one —\n> same version string, different content — because restore never re-extracts from your local hive. The\n> stale `Aspire.AppHost.Sdk\u002F13.5.0` can then inject a prerelease version floor (e.g.\n> `Version=\">= 13.5.0-dogfood.…\"`); NuGet picks the lowest version satisfying that floor and restore\n> **drifts** to a stray cached prerelease (e.g. `13.5.0-pr.17781`) instead of your stable packages —\n> visible as `NU1603` warnings and a `project.assets.json` bound to the prerelease. **Remedy:** isolate\n> the cache per emulation with a hermetic `NUGET_PACKAGES` (e.g. `export NUGET_PACKAGES=\u002Ftmp\u002Faspire-1350\u002F.nuget-packages`).\n> `localhive … -o DIR`'s generated `activate.sh`\u002F`activate.ps1` does this for you. CI is unaffected\n> (fresh containers start with an empty cache); this only bites local iterative rebuilds.\n\n> **Automated coverage.** `EmulatedLocalReleaseBuildTests` (C# + TypeScript) exercises this exact\n> scenario end-to-end: it consumes a `localhive --version \u003CX.Y.Z> --archive` archive, emulates the\n> stable identity with `ASPIRE_CLI_PACKAGES` pointed at the hive, and asserts `aspire new`\u002F`aspire add`\n> resolve the future-only version locally. The tests skip unless given a stable-shaped local archive, so\n> they add zero cost to default CI. See `.agents\u002Fskills\u002Fcli-e2e-testing\u002FSKILL.md`.\n\n**Package\u002Ftemplate resolution now honors `ASPIRE_CLI_PACKAGES` for *any* emulated channel name.**\nHistorically the CLI only searched the local-packages channel when its name looked like a\nlocal build (`local`\u002F`pr-\u003CN>`\u002F`run-\u003CN>`); emulating `stable`\u002F`staging`\u002F`daily` silently fell back\nto nuget.org for `aspire new`\u002F`aspire add`. The CLI now recognizes a channel as locally backed by\nits **mappings** (an `Aspire*` mapping pointing at an existing directory), not its name, so the\noverride works under every emulated identity.\n\n> **⚠️ Buildability needs an _ambient_ NuGet source (step 2).** A real `stable` build deliberately\n> drops **no** per-project `NuGet.config` (it relies on nuget.org being an ambient source). When\n> you emulate `stable` with a *local* version that isn't on nuget.org, the apphost still won't\n> **build** unless the local dir is reachable: MSBuild resolves the `Aspire.AppHost.Sdk` **before**\n> restore and reads only `NuGet.config` sources (it ignores `RestoreAdditionalProjectSources` and\n> `ASPIRE_CLI_PACKAGES`). So `aspire new` will scaffold the project (templates come from the local\n> dir), but `aspire add`\u002F`aspire run` fail with `Could not resolve SDK \"Aspire.AppHost.Sdk\u002F13.5.0\"`\n> until you add the local dir as an ambient source (`dotnet nuget add source`, a user\u002Fparent-level\n> `NuGet.config`, etc.). This mirrors how real stable relies on an ambient nuget.org — the local\n> dir is the emulated ambient feed. `aspire add` itself still drops a project `NuGet.config` for the\n> `dotnet add package` restore; the ambient source is only needed for the SDK-resolution build step.\n> Remove the source when done: `dotnet nuget remove source local-emulated-stable`.\n\n## ⚠️ `ASPIRE_CLI_PACKAGES` cleanliness caveat (fail-fast)\n\nA flat directory feed has no \"latest stable vs latest prerelease\" semantics: if the same\n`Aspire*` package id appears with **more than one version**, NuGet would silently resolve the\nhighest and mask the version you meant to test. The CLI therefore **fails fast** with:\n\n> The Aspire CLI packages override directory '\u003Cdir>' contains more than one version of the same\n> Aspire package... Clean the directory so each `Aspire*` package appears exactly once.\n> Conflicts: Aspire.Hosting (13.4.1, 13.4.2).\n\nThis commonly bites because **`.\u002Flocalhive.sh` auto-generates a fresh `local.YYYYMMDD.tHHmmss`\nversion each run and accumulates them in `artifacts\u002Fpackages\u002F\u003CConfig>\u002FShipping`**. Before\npointing `ASPIRE_CLI_PACKAGES` at `Shipping`, clean stale `.nupkg` files (or repack fresh) so\neach `Aspire*` id has exactly one version. The directory must also exist (missing → fail-fast).\n\n## Reproduce → fix → validate loop\n\n1. Identify the reported build (channel + version + commit) and which scenario row it maps to.\n2. **State the scenario and exact knobs in chat** (mandatory section above).\n3. Reproduce the bug with the local CLI under emulation.\n4. Fix on the current branch.\n5. Re-run the same emulated command and confirm the fix; keep the env vars identical so the\n   before\u002Fafter is apples-to-apples.\n\n## References (don't duplicate — link to these)\n\n- `get-aspire-channel-version.{sh,ps1}` + `emulate-aspire-cli.{sh,ps1}` (next to this file) —\n  resolve the version to emulate and one-line scenario setup; see \"Helper scripts\" above.\n- `docs\u002Fspecs\u002Fcli-identity-sidecar.md` — identity resolution design, sidecar schema, the full\n  list of `ASPIRE_CLI_*` overrides including `ASPIRE_CLI_PACKAGES`.\n- `docs\u002Fcli-staging-validation.md` — staging\u002Fstable feed routing and the `debug-staging.sh` \u002F\n  `debug-stable.sh` recipes.\n- `docs\u002Fdogfooding-pull-requests.md` + `eng\u002Fscripts\u002FREADME.md` — installing PR builds with\n  `get-aspire-cli-pr.sh`.\n- `localhive.sh` (repo root) — build packages + CLI + hive locally.\n","You are a specialized agent for reproducing version\u002Fchannel\u002Fquality-specific Aspire CLI\nbehavior from a **locally built CLI**. The CLI resolves its own identity (channel, version,\ncommit, and — optionally — the directory it resolves `Aspire*` packages from) at startup. By\nsetting a few environment variables (or an install sidecar), you can make\n`dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>` behave as if it were any released, staging,\ndaily, or PR build. This lets you reproduce a bug that only manifests on a specific build and\nfix it on the current branch — without waiting for an install or a PR build.\n\nRead `docs\u002Fspecs\u002Fcli-identity-sidecar.md` for the full design. This skill is the operational\nmatrix: which knobs to set for each scenario.\n\n## ⛔ MANDATORY: State the scenario and exact knobs in chat before running\n\nBefore you run **any** emulated CLI command, you MUST write a short line in chat declaring:\n\n1. **Which scenario row** (1–7b below) you are emulating.\n2. **The exact environment variables and values** you are setting (channel, version, commit,\n   packages directory, etc.).\n3. For `ASPIRE_CLI_PACKAGES`: that you **built\u002Fpopulated the directory yourself** and verified\n   it is clean (exactly one version of each `Aspire*` package). Do **not** hand-wave \"you\n   populate the directory\" — actually run the build\u002Fpack, show the command, and list what\n   landed there.\n\nExample:\n\n> Using **Scenario 2** (PR build identity + locally built packages):\n> `ASPIRE_CLI_CHANNEL=pr-18087`, `ASPIRE_CLI_PACKAGES=\u003Crepo>\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping`.\n> Packed locally with `.\u002Fbuild.sh --pack -c Release`; verified Shipping has one version of each\n> `Aspire*` package.\n\nIf you cannot determine the right knobs, ask — don't guess.\n\n## The override knobs\n\n### Identity environment variables (process-local; the source of truth)\n\nThese are read by `IdentityResolver` and flow into `CliExecutionContext`. They change the\nCLI's **global identity**, so they affect hive discovery, package-channel selection, staging\nfeed derivation, `--version`, telemetry identity tags, and the SDK-skew warning. They are\n**stripped before the CLI spawns child Aspire processes**, so they never leak into peer probes\nor `aspire doctor`'s child invocations — treat them as process-local test affordances.\n\n| Env var | Effect |\n|---|---|\n| `ASPIRE_CLI_CHANNEL` | Identity channel: `stable`, `staging`, `daily`, `local`, or `pr-\u003CN>`. Drives hive selection and staging-feed provenance. |\n| `ASPIRE_CLI_VERSION` | Informational version (e.g. `13.5.0-preview.1.26310.9`). Drives version pins, the skew warning, and `--version` output. |\n| `ASPIRE_CLI_COMMIT` | Source commit SHA. Drives the staging darc feed name (`darc-pub-microsoft-aspire-\u003Csha8>`). |\n| `ASPIRE_CLI_PACKAGES` | A flat directory of `.nupkg` files (e.g. `artifacts\u002Fpackages\u002F\u003CConfig>\u002FShipping`). The CLI synthesizes a package channel **named after `ASPIRE_CLI_CHANNEL`** that maps `Aspire*` to this directory (everything else → nuget.org), **replacing** any same-named built-in\u002Fdiscovered\u002FPR channel. See the cleanliness caveat below. |\n| `ASPIRE_CLI_NUGET_SERVICE_INDEX` | Replaces the canonical `https:\u002F\u002Fapi.nuget.org\u002Fv3\u002Findex.json` URL the CLI writes into **newly generated** `NuGet.config` files. Never rewrites URLs read from existing configs. |\n\nWhen any of these is set, the CLI prints a yellow banner on **stderr**:\n`Aspire CLI is emulating identity '\u003Cchannel>' version '\u003Cversion>'...`. Seeing that banner\nconfirms `IdentityOverridden` is true.\n\n### Install sidecar (`.aspire-install.json`)\n\nThe same values can come from the `channel`, `version`, `commit`, `nugetServiceIndexOverride`,\nand `packages` fields of an `.aspire-install.json` sidecar next to the CLI binary. Resolution\norder per field is **env var → sidecar field → assembly-baked stamp**. Use the sidecar when\nyou want a persistent emulated identity for an installed binary; use env vars for one-off runs.\nInstaller-authored `channel`, `version`, and `commit` fields describe the real installed identity\nand do not show the emulation banner, so use `aspire doctor --format Json` to confirm their source.\nThe developer-only `nugetServiceIndexOverride` and `packages` sidecar fields still show the banner.\n\n### Legacy PackagingService config keys (staging-feed routing only)\n\nThese predate the global env vars and are **narrower**: they only influence staging-feed\nrouting decisions inside `PackagingService`; they do **not** change the global identity, hive\nlookups, or `--version`. Set with `aspire config set -g \u003Ckey> \u003Cvalue>`.\n\n| Config key | Effect |\n|---|---|\n| `overrideCliIdentityChannel` | Identity used for **staging-feed decisions only** (validated against the known channel set). |\n| `overrideCliInformationalVersion` | Informational version used to derive the staging SHA-specific feed URL. |\n| `overrideStagingFeed` | Forces staging to be available and points it at an explicit feed URL. |\n| `stagingPinToCliVersion` | When `true` (and using the shared feed), pins resolution to the CLI version. |\n\n**Prefer the `ASPIRE_CLI_*` env vars for whole-identity emulation.** Use the config keys only\nwhen you specifically want to exercise staging-feed routing from an otherwise-plain local build\n(the `eng\u002Fscripts\u002Fdebug-staging.sh` \u002F `debug-stable.sh` recipes do exactly this — see\n`docs\u002Fcli-staging-validation.md`).\n\n## Running the local CLI under an emulated identity\n\n```bash\n# From the repo root. Build once, then run with the knobs set:\nASPIRE_CLI_CHANNEL=daily \\\nASPIRE_CLI_VERSION=13.5.0-preview.1.26310.9 \\\nASPIRE_CLI_COMMIT=95f0d2968... \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccommand>\n```\n\nYou can also run the already-built binary directly to skip the rebuild:\n`artifacts\u002Fbin\u002FAspire.Cli\u002FDebug\u002Fnet11.0\u002Faspire.dll` via `dotnet \u003Cdll> -- \u003Ccommand>`.\n\nConfirm the emulation took effect: `aspire --version` prints the emulated version, and the\nemulation banner appears on stderr. (Note: `aspire doctor` reports some fields from the\nphysical binary by design — see the spec.)\n\n> **Polyglot channel resolution from a source build.** When you run a source (DEBUG) build from\n> inside the Aspire repo, `AspireRepositoryDetector` can match the repo's `Aspire.slnx` (it falls\n> back to the CLI binary's `Environment.ProcessPath`, not the apphost's location). For a polyglot\n> (TypeScript\u002FPython) apphost that would force \"project-reference mode\" and short-circuit channel\n> resolution, so `aspire add` would silently resolve **stable nuget.org** packages instead of the\n> emulated channel's feed. To keep emulation faithful, `GuestAppHostProject.IsUsingProjectReferences`\n> now returns `false` whenever an `ASPIRE_CLI_*` identity override is active — so setting any\n> identity env var makes the source build resolve packages exactly like the installed CLI it is\n> emulating. (A real installed CLI is unaffected: Release builds only honor `ASPIRE_REPO_ROOT`.)\n\n## Helper scripts (bundled with this skill)\n\nTwo scripts live next to this `SKILL.md` (each with a `.sh` and a `.ps1` variant). Always\nprefer them over hand-typing versions — the daily\u002Fstaging feeds are unsorted and interleave\nold `9.x` builds, so eyeballing \"the latest\" is error-prone.\n\n### `get-aspire-channel-version.{sh,ps1}` — resolve the version to emulate\n\nMaps a channel to the exact feed the CLI's built-in package channels resolve `Aspire*` from\n(see `src\u002FAspire.Cli\u002FPackaging\u002FPackagingService.cs`), queries it anonymously, and prints **only**\nthe latest version to stdout (diagnostics go to stderr), so it pipes cleanly into\n`ASPIRE_CLI_VERSION`:\n\n```bash\n.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh stable     # -> 13.4.3 (nuget.org)\n.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh daily      # -> 13.5.0-preview.1.NNNNN.N (dnceng\u002Fdotnet9)\n.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh staging --commit \u003Csha>   # darc-pub-microsoft-aspire-\u003Csha8>\n\nexport ASPIRE_CLI_VERSION=\"$(.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh daily)\"\n```\n\nOptions: `--package \u003Cid>` (default `Aspire.Hosting.AppHost`, present on all three feeds and\nversioned identically to the product), `--stable-only` (daily\u002Fstaging → stable-shaped only),\n`--prerelease` (stable → allow prereleases). Staging requires `--commit`; note darc feeds are\nper-RC-build and may have been garbage-collected for older commits (clean `404` = no such feed).\n\n### `emulate-aspire-cli.{sh,ps1}` — one-line scenario setup (SOURCE it)\n\nSets the `ASPIRE_CLI_*` env vars and defines an `aspire` function pointing at this repo's built\nCLI. For `stable`\u002F`daily`\u002F`staging` it auto-resolves the version via the resolver above. It\n**must be sourced** (bash\u002Fzsh) or **dot-sourced** (pwsh) so the env + function persist:\n\n```bash\n# bash \u002F zsh — builds the CLI, resolves the latest daily version, defines `aspire`\nsource .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh daily\naspire --version            # confirms the emulation banner + version\n```\n\n```pwsh\n. .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.ps1 staging -Commit \u003Csha>\naspire --version\n```\n\nOptions: `--version \u003Cv>` \u002F `-Version` (pin instead of auto-resolving; required for `local`\u002F`pr-\u003CN>`),\n`--commit` \u002F `-Commit`, `--packages \u003Cdir>` \u002F `-Packages` (sets `ASPIRE_CLI_PACKAGES`), `--config`\n\u002F `-Config` (`Debug`|`Release`, default `Debug`), `--no-build` \u002F `-NoBuild` (use an existing binary).\n\n## Driving a scenario from a Terminal canvas (Copilot app)\n\nWhen running inside the Copilot app, give the user a live, reusable shell per scenario by\nopening a **Terminal canvas** rather than only running one-off `bash` tool commands. The flow:\n\n1. **State the scenario + knobs in chat** (mandatory rule above) and, for feed-backed channels,\n   resolve the real version first with `get-aspire-channel-version.sh` so the title and env are\n   accurate.\n2. Build the CLI once (`dotnet build src\u002FAspire.Cli\u002FAspire.Cli.csproj -p:SkipNativeBuild=true`),\n   or let `emulate-aspire-cli.sh` build it.\n3. `open_canvas` with `canvasId: \"terminal\"` and a descriptive `title` (e.g.\n   `aspire (emulating daily 13.5.0-preview.1.NNNNN.N)`); pick a stable `instanceId` per scenario\n   so re-opening focuses the same panel. Open a **separate** instance per identity so the user\n   can keep, say, a `stable` and a `daily` terminal side by side.\n4. Drive it with the `send_terminal_input` action (input must be an **object**, e.g.\n   `{\"input\": \"aspire --version\"}`; a trailing Enter is added by default). The fastest setup is a\n   single `source .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh \u003Cchannel>` line;\n   otherwise send the `export ASPIRE_CLI_*` lines and the `aspire() { dotnet \"\u003Cdll>\" \"$@\"; }`\n   function definition individually.\n5. Verify with `aspire --version`. `read_terminal_output` may be unavailable in some app\n   contexts (\"Terminal not found or not running\"); when it is, confirm the emulation\n   independently by running the same env + built `aspire.dll` through a normal `bash` tool call\n   and checking the banner + version match — the canvas keystrokes are still delivered for the\n   user.\n\nReuse `instanceId`s across turns so \"the daily terminal\" stays the same panel the user is looking at.\n\n## The scenario matrix\n\n| # | Scenario | Identity | `Aspire*` package source | How |\n|---|---|---|---|---|\n| 1 | Local build + locally built packages (local hive) | `local` | `~\u002F.aspire\u002Fhives\u002Flocal\u002Fpackages` **or** local `Shipping` dir | `.\u002Flocalhive.sh` (no env vars) — or `ASPIRE_CLI_PACKAGES=\u003CShipping>` |\n| 2 | PR build identity + locally built packages | `pr-\u003CN>` | local `Shipping` dir | `ASPIRE_CLI_CHANNEL=pr-\u003CN>` + `ASPIRE_CLI_PACKAGES=\u003CShipping>` |\n| 3 | PR build identity + CI-built packages, local CLI | `pr-\u003CN>` | `~\u002F.aspire\u002Fhives\u002Fpr-\u003CN>\u002Fpackages` | `get-aspire-cli-pr.sh --pr \u003CN>`, then `ASPIRE_CLI_CHANNEL=pr-\u003CN>` |\n| 4 | Latest daily, local CLI | `daily` | dnceng\u002Fdotnet9 daily feed | `ASPIRE_CLI_CHANNEL=daily` + `ASPIRE_CLI_VERSION` (+ `ASPIRE_CLI_COMMIT`) |\n| 5 | Staging, unstable version | `staging` | `darc-pub-microsoft-aspire-\u003Csha8>` feed (quality Both) | `ASPIRE_CLI_CHANNEL=staging` + prerelease `ASPIRE_CLI_VERSION` + `ASPIRE_CLI_COMMIT` |\n| 6 | Staging, stable version | `staging` | `darc-pub-microsoft-aspire-\u003Csha8>` feed (quality Both) | `ASPIRE_CLI_CHANNEL=staging` + stable-shaped `ASPIRE_CLI_VERSION` + `ASPIRE_CLI_COMMIT` |\n| 7 | Released build repro | `stable` | nuget.org | `ASPIRE_CLI_CHANNEL=stable` + released `ASPIRE_CLI_VERSION` |\n| 7b | Released repro + CLI+hosting fix spanning packages | `stable` | locally rebuilt `Shipping` dir | as 7 + `ASPIRE_CLI_PACKAGES=\u003Cclean-rebuilt-dir>` |\n\n### Scenario 1 — Local build + locally built packages\n\n`.\u002Flocalhive.sh [-c Release|Debug] [-n \u003Chive>]` packs NuGet packages into\n`artifacts\u002Fpackages\u002F\u003CConfig>\u002FShipping`, creates `~\u002F.aspire\u002Fhives\u002F\u003Chive>\u002Fpackages`, and installs\nthe CLI to `~\u002F.aspire\u002Fbin`. The installed CLI bakes a `local` identity and discovers the hive —\nno env vars needed.\n\nTo skip the hive copy and point a dev-tree CLI straight at the packed output:\n\n```bash\n.\u002Fbuild.sh --pack -c Release        # -> artifacts\u002Fpackages\u002FRelease\u002FShipping\nASPIRE_CLI_PACKAGES=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\n### Scenario 2 — PR build identity + locally built packages (agent builds the packages)\n\nYou (the agent) build the packages, then run the local CLI as the PR build:\n\n```bash\n.\u002Fbuild.sh --pack -c Release        # produces artifacts\u002Fpackages\u002FRelease\u002FShipping\n# Verify the Shipping dir is clean (one version per Aspire* package) before running.\nASPIRE_CLI_CHANNEL=pr-\u003CN> \\\nASPIRE_CLI_PACKAGES=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\n`ASPIRE_CLI_PACKAGES` wins over a same-named hive or PR-install channel, so the CLI resolves\n`Aspire*` from your freshly built packages while presenting a `pr-\u003CN>` identity.\n\n### Scenario 3 — PR build identity + CI-built packages, local CLI\n\nUse this to test something locally against a PR's **CI-built** packages without rebuilding them:\n\n```bash\neng\u002Fscripts\u002Fget-aspire-cli-pr.sh --pr \u003CN>     # populates ~\u002F.aspire\u002Fhives\u002Fpr-\u003CN>\u002Fpackages\nASPIRE_CLI_CHANNEL=pr-\u003CN> dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nNo `ASPIRE_CLI_PACKAGES` — the local CLI discovers `~\u002F.aspire\u002Fhives\u002Fpr-\u003CN>` by name because its\nidentity channel matches. (See `docs\u002Fdogfooding-pull-requests.md` and `eng\u002Fscripts\u002FREADME.md`.)\n\n### Scenario 4 — Latest daily, local CLI\n\n```bash\n# Fast path: resolves the real latest daily version, builds, defines `aspire`.\nsource .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh daily\n\n# Manual equivalent:\nASPIRE_CLI_CHANNEL=daily \\\nASPIRE_CLI_VERSION=\"$(.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh daily)\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nThe `daily` channel maps `Aspire*` to the dnceng `dotnet9` feed. Use the **real** daily version\nof the build you're emulating (the resolver gives it to you) so version pins and the skew\nwarning match what users saw. `ASPIRE_CLI_COMMIT` is optional here — daily resolves from the\nshared feed, not a SHA-specific darc feed.\n\n### Scenarios 5 & 6 — Staging (unstable vs stable version)\n\n```bash\n# 5 — unstable (prerelease-shaped) version -> quality Both\nASPIRE_CLI_CHANNEL=staging \\\nASPIRE_CLI_VERSION=13.4.0-preview.1.26280.6 \\\nASPIRE_CLI_COMMIT=\u003Cfull-commit-sha> \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n\n# 6 — stable-shaped version -> quality Both (the #17527 stabilizing-build scenario)\nASPIRE_CLI_CHANNEL=staging ASPIRE_CLI_VERSION=13.4.0 ASPIRE_CLI_COMMIT=\u003Cfull-commit-sha> \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nStaging feed provenance is derived from the commit: `darc-pub-microsoft-aspire-\u003Csha8>`. The\nchannel uses `Both` for either version shape because a stable-shaped build can still publish\nprerelease-only integrations alongside stable packages.\nAlternatively, `eng\u002Fscripts\u002Fdebug-staging.sh` \u002F `debug-stable.sh` exercise the same routing via\nthe legacy config keys — see `docs\u002Fcli-staging-validation.md`.\n\n### Scenario 7 — Released build repro\n\n```bash\n# Fast path: resolves the latest stable on nuget.org (override with --version for an older release).\nsource .agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh stable\n\n# Manual \u002F pin a specific release:\nASPIRE_CLI_CHANNEL=stable ASPIRE_CLI_VERSION=13.4.2 dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nThe `stable` channel maps `Aspire*` to nuget.org. Use the exact released version the bug was\nreported against (`get-aspire-channel-version.sh stable` gives the current latest).\n\n### Scenario 7b — Released repro with a fix spanning CLI **and** hosting packages\n\nWhen the fix touches packages too (e.g. `Aspire.Hosting.*`), rebuild those packages from the\ncurrent branch at the released version into a **clean** directory and layer them in:\n\n```bash\n.\u002Fbuild.sh --pack -c Release                  # rebuild packages from this branch's source\n# Stage exactly the packages you changed into a clean dir (or clean Shipping first).\nASPIRE_CLI_CHANNEL=stable \\\nASPIRE_CLI_VERSION=13.4.2 \\\nASPIRE_CLI_PACKAGES=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\" \\\n  dotnet run --project src\u002FAspire.Cli -- \u003Ccmd>\n```\n\nIdentity stays `stable`\u002F`13.4.2` while `Aspire*` resolves from your locally rebuilt packages, so\nyou can validate a CLI+hosting fix together before publishing anything.\n\n### Scenario 7c — All-local \"future release\" (version not yet on nuget.org)\n\nUse this to dry-run a not-yet-shipped release (e.g. emulate a future `13.5.0` stable build)\nentirely from locally built packages — templates and integrations both resolve from a local\ndirectory, nothing has to be published. This is the most self-contained scenario and the one the\nidentity-sidecar package-resolution fix specifically enables.\n\n```bash\n# 1. Build packages in the exact version shape you want to emulate.\n#    Stable shape (no prerelease suffix):\n.\u002Fbuild.sh --pack -c Release \u002Fp:VersionPrefix=13.5.0 \u002Fp:StabilizePackageVersion=true\n#    Prerelease shape instead: \u002Fp:VersionPrefix=13.5.0 \u002Fp:VersionSuffix=preview.1\nSTABLE_DIR=\"$PWD\u002Fartifacts\u002Fpackages\u002FRelease\u002FShipping\"   # clean: one version per Aspire* id\n\n# 2. (Buildability) Register the local dir as an AMBIENT NuGet source — see note below.\ndotnet nuget add source \"$STABLE_DIR\" --name local-emulated-stable\n\n# 3. Emulate the release. aspire new + aspire add now resolve 13.5.0 from the local dir.\nASPIRE_CLI_CHANNEL=stable ASPIRE_CLI_VERSION=13.5.0 ASPIRE_CLI_PACKAGES=\"$STABLE_DIR\" \\\n  dotnet run --project src\u002FAspire.Cli -- new aspire-starter --name MyApp --non-interactive\n```\n\n> **Turnkey alternative — `localhive --version`.** `.\u002Flocalhive.sh --version 13.5.0` (or\n> `.\\localhive.ps1 -Version 13.5.0`) packs the stable shape, populates `~\u002F.aspire\u002Fhives\u002Flocal\u002Fpackages`\n> with **only** the exact `13.5.0` packages, and installs the CLI — no manual `VersionPrefix`\u002F\n> `StabilizePackageVersion` flags and no stale-version cleanup needed. Add `--archive` to also produce a\n> portable `.tar.gz` for the E2E tests (below). You still set the three `ASPIRE_CLI_*` env vars (and the\n> ambient source for buildability) to emulate the release from that hive.\n>\n> **Fully turnkey with `-o DIR`.** `.\u002Flocalhive.sh --version 13.5.0 -o \u002Ftmp\u002Faspire-1350` writes a\n> self-contained portable layout (`bin\u002F`, `hives\u002Flocal\u002Fpackages\u002F`) **and** an `activate.sh`\n> (`localhive.ps1` writes `activate.ps1`). `source \u002Ftmp\u002Faspire-1350\u002Factivate.sh` puts the CLI on PATH,\n> exports the three `ASPIRE_CLI_*` vars (channel=stable, version=`13.5.0`, packages=the hive), sets a\n> **hermetic** `NUGET_PACKAGES` (see the cache hazard below), and drops you into a `work\u002F` dir — a\n> one-command emulated stable session.\n\n> **⚠️ NuGet global-cache pollution when rebuilding a FIXED stable version.** NuGet's global packages\n> folder (`~\u002F.nuget\u002Fpackages\u002F\u003Cid>\u002F\u003Cversion>\u002F`) caches **extracted** packages keyed by the version\n> string. When you emulate a *fixed* stable version like `13.5.0` and then **rebuild** it, a stale\n> `13.5.0` left in that shared cache by an earlier build **silently shadows** the freshly built one —\n> same version string, different content — because restore never re-extracts from your local hive. The\n> stale `Aspire.AppHost.Sdk\u002F13.5.0` can then inject a prerelease version floor (e.g.\n> `Version=\">= 13.5.0-dogfood.…\"`); NuGet picks the lowest version satisfying that floor and restore\n> **drifts** to a stray cached prerelease (e.g. `13.5.0-pr.17781`) instead of your stable packages —\n> visible as `NU1603` warnings and a `project.assets.json` bound to the prerelease. **Remedy:** isolate\n> the cache per emulation with a hermetic `NUGET_PACKAGES` (e.g. `export NUGET_PACKAGES=\u002Ftmp\u002Faspire-1350\u002F.nuget-packages`).\n> `localhive … -o DIR`'s generated `activate.sh`\u002F`activate.ps1` does this for you. CI is unaffected\n> (fresh containers start with an empty cache); this only bites local iterative rebuilds.\n\n> **Automated coverage.** `EmulatedLocalReleaseBuildTests` (C# + TypeScript) exercises this exact\n> scenario end-to-end: it consumes a `localhive --version \u003CX.Y.Z> --archive` archive, emulates the\n> stable identity with `ASPIRE_CLI_PACKAGES` pointed at the hive, and asserts `aspire new`\u002F`aspire add`\n> resolve the future-only version locally. The tests skip unless given a stable-shaped local archive, so\n> they add zero cost to default CI. See `.agents\u002Fskills\u002Fcli-e2e-testing\u002FSKILL.md`.\n\n**Package\u002Ftemplate resolution now honors `ASPIRE_CLI_PACKAGES` for *any* emulated channel name.**\nHistorically the CLI only searched the local-packages channel when its name looked like a\nlocal build (`local`\u002F`pr-\u003CN>`\u002F`run-\u003CN>`); emulating `stable`\u002F`staging`\u002F`daily` silently fell back\nto nuget.org for `aspire new`\u002F`aspire add`. The CLI now recognizes a channel as locally backed by\nits **mappings** (an `Aspire*` mapping pointing at an existing directory), not its name, so the\noverride works under every emulated identity.\n\n> **⚠️ Buildability needs an _ambient_ NuGet source (step 2).** A real `stable` build deliberately\n> drops **no** per-project `NuGet.config` (it relies on nuget.org being an ambient source). When\n> you emulate `stable` with a *local* version that isn't on nuget.org, the apphost still won't\n> **build** unless the local dir is reachable: MSBuild resolves the `Aspire.AppHost.Sdk` **before**\n> restore and reads only `NuGet.config` sources (it ignores `RestoreAdditionalProjectSources` and\n> `ASPIRE_CLI_PACKAGES`). So `aspire new` will scaffold the project (templates come from the local\n> dir), but `aspire add`\u002F`aspire run` fail with `Could not resolve SDK \"Aspire.AppHost.Sdk\u002F13.5.0\"`\n> until you add the local dir as an ambient source (`dotnet nuget add source`, a user\u002Fparent-level\n> `NuGet.config`, etc.). This mirrors how real stable relies on an ambient nuget.org — the local\n> dir is the emulated ambient feed. `aspire add` itself still drops a project `NuGet.config` for the\n> `dotnet add package` restore; the ambient source is only needed for the SDK-resolution build step.\n> Remove the source when done: `dotnet nuget remove source local-emulated-stable`.\n\n## ⚠️ `ASPIRE_CLI_PACKAGES` cleanliness caveat (fail-fast)\n\nA flat directory feed has no \"latest stable vs latest prerelease\" semantics: if the same\n`Aspire*` package id appears with **more than one version**, NuGet would silently resolve the\nhighest and mask the version you meant to test. The CLI therefore **fails fast** with:\n\n> The Aspire CLI packages override directory '\u003Cdir>' contains more than one version of the same\n> Aspire package... Clean the directory so each `Aspire*` package appears exactly once.\n> Conflicts: Aspire.Hosting (13.4.1, 13.4.2).\n\nThis commonly bites because **`.\u002Flocalhive.sh` auto-generates a fresh `local.YYYYMMDD.tHHmmss`\nversion each run and accumulates them in `artifacts\u002Fpackages\u002F\u003CConfig>\u002FShipping`**. Before\npointing `ASPIRE_CLI_PACKAGES` at `Shipping`, clean stale `.nupkg` files (or repack fresh) so\neach `Aspire*` id has exactly one version. The directory must also exist (missing → fail-fast).\n\n## Reproduce → fix → validate loop\n\n1. Identify the reported build (channel + version + commit) and which scenario row it maps to.\n2. **State the scenario and exact knobs in chat** (mandatory section above).\n3. Reproduce the bug with the local CLI under emulation.\n4. Fix on the current branch.\n5. Re-run the same emulated command and confirm the fix; keep the env vars identical so the\n   before\u002Fafter is apples-to-apples.\n\n## References (don't duplicate — link to these)\n\n- `get-aspire-channel-version.{sh,ps1}` + `emulate-aspire-cli.{sh,ps1}` (next to this file) —\n  resolve the version to emulate and one-line scenario setup; see \"Helper scripts\" above.\n- `docs\u002Fspecs\u002Fcli-identity-sidecar.md` — identity resolution design, sidecar schema, the full\n  list of `ASPIRE_CLI_*` overrides including `ASPIRE_CLI_PACKAGES`.\n- `docs\u002Fcli-staging-validation.md` — staging\u002Fstable feed routing and the `debug-staging.sh` \u002F\n  `debug-stable.sh` recipes.\n- `docs\u002Fdogfooding-pull-requests.md` + `eng\u002Fscripts\u002FREADME.md` — installing PR builds with\n  `get-aspire-cli-pr.sh`.\n- `localhive.sh` (repo root) — build packages + CLI + hive locally.\n",{"name":5,"description":7},"main","cec61ac9b795bbfd9913f0c7196689b0d7a215d7",".agents\u002Fskills\u002Fcli-channel-debugging",1039,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire","https:\u002F\u002Faspire.dev","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-15 00:32:23",{"source":8,"skillName":5,"commands":58,"prompt":68,"zipAvailable":69},[59,62,65],{"tool":60,"command":61},"npx","npx skills add microsoft\u002Faspire --skill cli-channel-debugging",{"tool":63,"command":64},"bunx","bunx skills add microsoft\u002Faspire --skill cli-channel-debugging",{"tool":66,"command":67},"pnpm","pnpm dlx skills add microsoft\u002Faspire --skill cli-channel-debugging","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-channel-debugging\u002FSKILL.md",true,[71,77,81,85],{"path":72,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":75,"sourceHtmlUrl":76},"emulate-aspire-cli.ps1","SCRIPT","脚本",4191,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.ps1",{"path":78,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":79,"sourceHtmlUrl":80},"emulate-aspire-cli.sh",5691,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-channel-debugging\u002Femulate-aspire-cli.sh",{"path":82,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":83,"sourceHtmlUrl":84},"get-aspire-channel-version.ps1",5159,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.ps1",{"path":86,"resourceType":73,"resourceTypeDesc":74,"sizeBytes":87,"sourceHtmlUrl":88},"get-aspire-channel-version.sh",5403,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fcli-channel-debugging\u002Fget-aspire-channel-version.sh",[90,125,150,163,181,206],{"skillNo":91,"name":92,"nameZh":6,"description":93,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":94,"categories":95,"keywords":109,"publishedAt":42},"01M6FKZQPMA7VRA0PRBZRDFJTX","vscode-extension","Use when investigating, developing, debugging, testing, or reviewing Aspire VS Code extension behavior under extension\u002F, including extension UI, command, debugger, RPC, DCP, MCP, and CLI-integration issues or features.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fvscode-extension\u002FSKILL.md",[96,101,104],{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000008","测试与质量","SCENARIO","使用场景",{"categoryNo":102,"categoryName":103,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000023","Skill与智能体开发",{"categoryNo":105,"categoryName":106,"taxonomyType":107,"taxonomyTypeDesc":108},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[110,111,112,113,114,21,39,20,115,116,117,118,119,120,121,122,123,124,24],"vscode","vscode extension","extension","testing","MCP","code","issues","rpc","ui","integration","debugger","command","behavior","use","features",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":134,"publishedAt":42},"01M6FKZJG81XP80SVWFBJVMDWN","update-container-images","Updates Docker container image tags used by Aspire hosting integrations. Queries registries for newer tags, uses LLM to determine version-compatible updates, and applies changes. Use this when asked to update container image versions.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fupdate-container-images\u002FSKILL.md",[131],{"categoryNo":132,"categoryName":133,"taxonomyType":99,"taxonomyTypeDesc":100},"01JBSEEDCAT000000000000016","图像与多媒体",[135,136,137,138,139,140,141,39,142,123,143,144,145,146,147,148,149,24],"container images","update","container","images","update container images","image","docker","integrations","version","hosting","queries","tags","updates","for","changes",{"skillNo":151,"name":152,"nameZh":6,"description":153,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":154,"categories":155,"keywords":157,"publishedAt":42},"01M6FKZDY1MY0QA62EYSDG5NHW","test-management","Quarantines or disables flaky\u002Fproblematic tests using the QuarantineTools utility","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Ftest-management\u002FSKILL.md",[156],{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},[158,159,160,161,162],"test","management","test management","tests","utility",{"skillNo":164,"name":165,"nameZh":6,"description":166,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":167,"categories":168,"keywords":169,"publishedAt":42},"01M6FKZAQ428JX8F6NSA19XBQJ","startup-perf","Measures Aspire startup profiling with CLI self-profile capture and dashboard export traces.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fstartup-perf\u002FSKILL.md",[],[170,171,172,21,173,39,174,175,176,177,178,179,180],"perf","startup","startup perf","dashboard","profiling","capture","profile","export","self","with","traces",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":187,"publishedAt":42},"01M6FKZ4W4J0ET0Q0C2Z30HYRV","reviewing-aspire-architecture","Use only when the user explicitly requests a deep Aspire architectural or pattern review of an existing PR or diff, or when a generic reviewer escalates a named Aspire-domain question it cannot resolve. Do not use for ordinary review, implementation, debugging, explanation, or design discussion—even when a PR is referenced—and never select it from changed file paths alone.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Freviewing-aspire-architecture\u002FSKILL.md",[],[188,39,189,190,191,38,20,192,193,194,195,123,196,197,198,199,200,201,202,203,148,204,205,24],"architecture","reviewing aspire architecture","design","review","file","select","reviewer","question","diff","never","only","do","domain","pattern","deep","paths","Existing","generic",{"skillNo":207,"name":208,"nameZh":6,"description":209,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":210,"categories":211,"keywords":213,"publishedAt":42},"01M6FKYZ44BEPJNV8VQ0X73CZR","pr-testing","Use when asked to test a microsoft\u002Faspire pull request, including CLI, hosting, dashboard, component, template, and VS Code extension changes. Also covers testing PRs that change CI infrastructure — GitHub Actions (workflows, actions, gh-aw agentic workflows, CI scripts under .github\u002F and eng\u002F) and Azure DevOps pipelines (eng\u002Fpipelines, eng\u002Fcommon).","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Faspire\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fpr-testing\u002FSKILL.md",[212],{"categoryNo":97,"categoryName":98,"taxonomyType":99,"taxonomyTypeDesc":100},[113,38,214,21,215,216,173,217,218,219,220,221,39,222,115,223,224,225,226,227,123,228,144,229,112,230,149,231],"pr testing","github","agentic","workflows","change","component","agentic workflows","azure devops","infrastructure","actions","ci","github actions","template","common","devops","pipelines","scripts","prs"]