Completed another review pass, making more improvements

skills/vcpkg/SKILL.md

@@ -38,6 +38,12 @@ If the user is working inside **Visual Studio** (not VS Code), prefer using the
 
 If the user has a standalone vcpkg installation and prefers to use that instead, respect their preference.
 
+### Shell Environment Variable Syntax
+
+When examples require environment variables, use shell-appropriate syntax:
+- PowerShell: `$env:VARIABLE = "value"`
+- Bash/Zsh: `export VARIABLE=value`
+
 ---
 
 ## Project Setup
@@ -128,18 +134,10 @@ vcpkg install zlib:arm64-windows
 
 In manifest mode, set the triplet via CMake:
 ```console
-cmake -B build -DVCPKG_TARGET_TRIPLET=x64-linux -DCMAKE_TOOLCHAIN_FILE=[vcpkg root]/scripts/buildsystems/vcpkg.cmake
+cmake -B build -DVCPKG_TARGET_TRIPLET=x64-linux -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
 ```
 
-Or set the environment variable:
+Or set the default triplet via environment variable (using the shell syntax above): `VCPKG_DEFAULT_TRIPLET=x64-linux`.
-
-```powershell
-$env:VCPKG_DEFAULT_TRIPLET = "x64-linux"
-```
-
-```bash
-export VCPKG_DEFAULT_TRIPLET=x64-linux
-```
 
 ### Bulk-Adding Multiple Dependencies
 
@@ -162,13 +160,9 @@ Then run `vcpkg install` (manifest mode) or the above command to install all at
 Place test-only dependencies under an opt-in feature. The `"host"` field is reserved for build tools that must run on the host architecture:
 ```json
 {
-  "dependencies": [
+  "dependencies": ["fmt"],
-    "fmt",
-    "spdlog"
-  ],
   "features": {
     "tests": {
-      "description": "Build tests",
       "dependencies": ["gtest"]
     }
   }
@@ -183,40 +177,30 @@ Activate with: `vcpkg install --x-feature=tests` or in CMake: `-DVCPKG_MANIFEST_
 
 ### Setting Versions for Individual Dependencies
 
-In `vcpkg.json`, prefer using `"version>="` as a minimum version constraint over overrides. Example:
+Prefer `"version>="` for minimum-version constraints:
 ```json
 {
-  "dependencies": [
+  "dependencies": [{ "name": "fmt", "version>=": "10.2.0" }],
-    {
-      "name": "fmt",
-      "version>=": "10.2.0"
-    }
-  ],
   "builtin-baseline": "<commit-sha>"
 }
 ```
 
-If the user insists on hard-coding a version and is okay dealing with ABI compatibility issues manually, use overrides instead:
+Use `overrides` only when a hard pin is required:
 ```json
 {
   "dependencies": ["fmt"],
-  "overrides": [
+  "overrides": [{ "name": "fmt", "version": "10.2.0" }],
-    {
-      "name": "fmt",
-      "version": "10.2.0"
-    }
-  ],
   "builtin-baseline": "<commit-sha>"
 }
 ```
 
-The `builtin-baseline` is **very important** when using versioning. Suggest baselines at minimum as a way to set all library versions to a known-good state, and use overrides only when necessary.
+Always include `builtin-baseline` when using versioning.
 
 **Key points:**
-- `overrides` takes precedence over all version constraints, including transitive ones
+- `overrides` take precedence over all version constraints, including transitive ones.
-- You **must** have a `builtin-baseline` set for overrides to work
+- `builtin-baseline` is required for overrides.
-- The version must exist in the selected vcpkg registry's version database; an override may select a version older than the baseline version
+- Overrides can pin versions older than the baseline if that version exists in the selected registry's versions database.
-- Use `vcpkg x-history zlib` to see available versions
+- Use `vcpkg x-history <port>` to inspect available versions.
 
 ---
 
@@ -229,12 +213,8 @@ vcpkg install <packages>:arm64-linux
 ```
 
 Or set the triplet in CMake:
-```powershell
+```console
-cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
+cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake
-```
-
-```bash
-cmake -B build -DVCPKG_TARGET_TRIPLET=arm64-linux -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake
 ```
 
 You may need a cross-compilation toolchain installed (e.g., `aarch64-linux-gnu-gcc`).
@@ -246,39 +226,16 @@ vcpkg install <packages>:arm64-windows
 
 ### Building for Android (NDK)
 
-1. Set environment variables:
+1. Install packages:
-```powershell
-$env:ANDROID_NDK_HOME = "C:\path\to\ndk"
-$env:VCPKG_DEFAULT_TRIPLET = "arm64-android"
-```
-
-```bash
-export ANDROID_NDK_HOME=/path/to/ndk
-export VCPKG_DEFAULT_TRIPLET=arm64-android
-```
-
-2. Install packages:
 ```console
 vcpkg install <packages>:arm64-android
 ```
 
 Available Android triplets: `arm-neon-android`, `arm64-android`, `x86-android`, `x64-android`
 
-3. In CMake:
+2. In CMake:
-```powershell
+```console
-cmake -B build `
+cmake -B build -DCMAKE_TOOLCHAIN_FILE=<vcpkg-root>/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=arm64-android -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=<android-ndk>/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a -DANDROID_PLATFORM=android-24
-  -DCMAKE_TOOLCHAIN_FILE=$env:VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake `
-  -DVCPKG_TARGET_TRIPLET=arm64-android `
-  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$env:ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake `
-  -DANDROID_ABI=arm64-v8a `
-  -DANDROID_PLATFORM=android-24
 ```
 
-```bash
+For expanded CI and shell-specific examples, see `references/ci.md`.
-cmake -B build \
-  -DCMAKE_TOOLCHAIN_FILE=$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake \
-  -DVCPKG_TARGET_TRIPLET=arm64-android \
-  -DVCPKG_CHAINLOAD_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
-  -DANDROID_ABI=arm64-v8a \
-  -DANDROID_PLATFORM=android-24
-```

skills/vcpkg/references/ci.md

@@ -21,6 +21,18 @@ $env:VCPKG_BINARY_SOURCES = "clear;nuget,https://nuget.pkg.github.com/your-org/i
 ```bash
 export VCPKG_BINARY_SOURCES="clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite"
 ```
+For GitHub Packages, also configure NuGet authentication (for example via `GITHUB_TOKEN` in CI or a PAT/credential provider for local development). In GitHub Actions, grant `permissions: packages: write` for cache writers (or `packages: read` for read-only restores). Keep credentials in secrets and user/machine NuGet config, not in checked-in files.
+
+**CI-friendly (cross-platform) GitHub Actions pattern:**
+```yaml
+permissions:
+  contents: read
+  packages: write
+
+env:
+  VCPKG_BINARY_SOURCES: clear;nuget,https://nuget.pkg.github.com/your-org/index.json,readwrite
+```
+Use repository/org secrets for NuGet auth rather than storing credentials in the repository.
 
 **Local filesystem:**
 ```powershell
@@ -30,21 +42,7 @@ $env:VCPKG_BINARY_SOURCES = "clear;files,C:\vcpkg-cache,readwrite"
 export VCPKG_BINARY_SOURCES="clear;files,/var/tmp/vcpkg-cache,readwrite"
 ```
 
-**Sharing between CI and local dev:** Use the same remote cache (Azure Blob or NuGet feed) in both environments. CI writes (`readwrite`), developers read (`read`):
+**Sharing between CI and local dev:** Use the same remote cache source in both environments and switch only the final mode token: CI uses `readwrite`, developers use `read`.
-```powershell
-# CI (writes cache)
-$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,readwrite"
-
-# Developer (reads cache)
-$env:VCPKG_BINARY_SOURCES = "clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$env:AZURE_STORAGE_SAS_TOKEN,read"
-```
-```bash
-# CI (writes cache)
-export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$AZURE_STORAGE_SAS_TOKEN,readwrite"
-
-# Developer (reads cache)
-export VCPKG_BINARY_SOURCES="clear;x-azblob,https://myaccount.blob.core.windows.net/cache,$AZURE_STORAGE_SAS_TOKEN,read"
-```
 
 ---
 

skills/vcpkg/references/troubleshooting.md

@@ -76,35 +76,17 @@ vcpkg install curl[ssl,ssh] --recurse   # permits rebuilding with the new featur
 ### Cleaning the vcpkg Cache
 
 ```powershell
-# Remove build trees (intermediate build files)
-Remove-Item -Recurse -Force <vcpkg-root>\buildtrees
-
-# Remove downloaded archives
-Remove-Item -Recurse -Force <vcpkg-root>\downloads
-
-# Remove installed packages (classic mode only)
-Remove-Item -Recurse -Force <vcpkg-root>\installed
-
 # Remove all package build artifacts
 vcpkg x-clean
 
-# In manifest mode, remove the local vcpkg_installed directory
+# Optional: remove local cache/install directories
-Remove-Item -Recurse -Force .\vcpkg_installed
+Remove-Item -Recurse -Force <vcpkg-root>\buildtrees,<vcpkg-root>\downloads,<vcpkg-root>\installed,.\vcpkg_installed
 ```
 
 ```bash
-# Remove build trees (intermediate build files)
-rm -rf <vcpkg-root>/buildtrees
-
-# Remove downloaded archives
-rm -rf <vcpkg-root>/downloads
-
-# Remove installed packages (classic mode only)
-rm -rf <vcpkg-root>/installed
-
 # Remove all package build artifacts
 vcpkg x-clean
 
-# In manifest mode, remove the local vcpkg_installed directory
+# Optional: remove local cache/install directories
-rm -rf vcpkg_installed/
+rm -rf <vcpkg-root>/buildtrees <vcpkg-root>/downloads <vcpkg-root>/installed ./vcpkg_installed
 ```