wyvrnpm 2.11.0 → 2.12.3

package/README.md

@@ -1,1905 +1,1914 @@
-# wyvrnpm
-
-A simple, private C++ package manager that works with any static file hosting provider — Amazon S3, a plain HTTP/HTTPS server, a local directory, or an SMB/UNC network share.
-
-There is no central registry. You control where packages are hosted.
-
-> **README version: 2.8.3** — Highlights since 2.4.0: non-ABI build-time `conf` block (CMake cache variables via recipe / team profile / `wyvrn.local.json` / CLI `--conf`), per-package `source` pin for multi-source defense, profile inheritance via `extends`, pattern-based `settingsOverrides` (`boost*: {...}`), `wyvrnpm cache list` / `cache prune` for selective source-build-cache cleanup, `install --dry-run` (JSON plan without side effects), `install --build=always` to force source-rebuild, `--token-env` for CI credentials, CloudFront/WAF-compatible HTTP provider (sends `User-Agent`, surfaces non-404 errors), publish preserves dependency ranges verbatim with lock snapshot moved to informational `publishedLock`, and a raft of security hardening (Zip Slip, MSVC arch allow-list). Full list in `claude/EVALUATION.md`.
-
----
-
-## Install
-
-```bash
-npm install -g wyvrnpm
-```
-
-Requires Node.js >= 18.
-
-For S3 publishing, also install the AWS SDK:
-
-```bash
-npm install -g @aws-sdk/client-s3 @aws-sdk/credential-providers
-```
-
----
-
-## Quick Start
-
-```bash
-# 1. Initialise a manifest in your project
-wyvrnpm init
-
-# 2. Configure your package sources once
-wyvrnpm configure add-source --kind install --name corp-s3 --url s3://my-bucket/packages --profile my-sso
-wyvrnpm configure add-source --kind publish --name default  --url s3://my-bucket/packages --profile my-sso
-
-# 3. Detect and save your build environment as the default profile
-wyvrnpm configure profile detect
-
-# 4. Add dependencies (resolves latest from your configured sources)
-wyvrnpm add zlib fmt@^10.0.0
-
-# 5. Install dependencies (resolved against your build profile)
-wyvrnpm install
-
-# 6. Configure and build via the generated CMake preset
-wyvrnpm build
-
-# 7. Publish your package (uses the active profile automatically)
-wyvrnpm publish
-
-# 8. (Optional) Link local packages for development
-cd ../my-local-lib && wyvrnpm link
-cd ../my-app && wyvrnpm link my-local-lib
-```
-
----
-
-## Build Profiles
-
-v2 introduces **build profiles** — named snapshots of your build environment (OS, architecture, compiler, C++ standard, runtime linkage). Each published binary is tagged with a profile hash so installs can resolve the correct prebuilt binary automatically.
-
-Profile fields mirror Conan 2.0 settings:
-
-| Field | Example values |
-|---|---|
-| `os` | `Windows` `Linux` `Macos` |
-| `arch` | `x86_64` `x86` `armv8` |
-| `compiler` | `msvc` `gcc` `clang` `apple-clang` |
-| `compiler.version` | `193` `13` `17` |
-| `compiler.cppstd` | `14` `17` `20` `23` |
-| `compiler.runtime` | `dynamic` `static` *(MSVC only)* |
-
-Profiles are stored in the platform config directory:
-
-| Platform | Path |
-|---|---|
-| Windows | `%LOCALAPPDATA%\wyvrnpm\profiles\` |
-| Linux / macOS | `~/.config/wyvrnpm/profiles/` |
-
-### Typical profile workflow
-
-```bash
-# Auto-detect your current environment and save it as "default"
-wyvrnpm configure profile detect
-
-# Or save under a specific name (e.g. for a release build with static runtime)
-wyvrnpm configure profile detect --name release
-wyvrnpm configure profile set --name release --runtime static
-
-# List all saved profiles (* marks the default)
-wyvrnpm configure profile list
-
-# Switch the default profile
-wyvrnpm configure profile set-default release
-```
-
-Once a default profile is saved, `install` and `publish` use it automatically — no flags required.
-
-### Profile inheritance — `extends` (2.8.0+)
-
-Teams often end up with a small fleet of near-duplicate profiles (`windows-msvc-debug`, `windows-msvc-release`, `windows-msvc-x86`, …) that drift over time. A profile can inherit from another via `extends`:
-
-```json
-{
-  "extends": "windows-msvc-base",
-  "compiler.cppstd": "23"
-}
-```
-
-Or from multiple parents (later entries override earlier):
-
-```json
-{
-  "extends": ["windows-base", "team-defaults"],
-  "compiler.runtime": "static"
-}
-```
-
-Rules:
-
-- `[settings]` fields merge per-key — child wins.
-- The `conf` block (if present) merges per-leaf — child overrides single keys without dropping siblings.
-- Overlay value `null` explicitly unsets a parent field (Conan's `None` semantics).
-- Inheritance cycles are detected and fail with the full trail (`alpha → beta → alpha`).
-- Missing parent names fail fast — no silent drop.
-- `extends` itself is stripped from the resolved profile and is **not** folded into `profileHash`, so `{ "extends": "base" }` with no overrides hashes byte-identically to `base`.
-
-`wyvrnpm configure profile show <name>` prints the raw `extends:` chain alongside the resolved `[settings]` so you can inspect inheritance without grepping JSON.
-
----
-
-## Commands
-
-### `wyvrnpm init`
-
-Creates a `wyvrn.json` manifest in the current directory.
-
-```bash
-wyvrnpm init
-wyvrnpm init --root ./my-project
-```
-
----
-
-### `wyvrnpm bootstrap`
-
-Scaffolds a first-draft `wyvrn.json` for an open-source C++ library so it can be packaged into your wyvrnpm registry with a single review pass instead of hand-writing a manifest from scratch. Clones the upstream git repo, detects `name` / `version` / `kind` from the checkout, applies known-library CMake flag hints (skip tests, skip examples, flip install gates), and prints a TODO report for everything a machine can't decide for you.
-
-Designed for batch-converting a list of forked upstreams (fmt, spdlog, zlib, Catch2, etc.) into your private registry.
-
-```bash
-# Typical single-repo conversion
-wyvrnpm bootstrap https://github.com/fmtlib/fmt.git --dest ./pkgs/fmt
-cd ./pkgs/fmt                           # review wyvrn.json, settle TODOs
-wyvrnpm install
-wyvrnpm build --install --all-configs
-wyvrnpm publish --source team-s3
-
-# Override the derived name / version / kind
-wyvrnpm bootstrap https://github.com/nlohmann/json.git \
-    --dest ./pkgs/nlohmann-json \
-    --name nlohmann-json \
-    --kind HeaderOnlyLib
-
-# Work on a directory you already cloned
-wyvrnpm bootstrap --no-clone --dest ./pkgs/fmt --force
-
-# Preview without writing — TODO report only
-wyvrnpm bootstrap https://github.com/google/re2.git --dest /tmp/re2 --dry-run
-
-# Batch driver — one shell loop, no wyvrnpm subcommand needed
-while read url; do
-  wyvrnpm bootstrap "$url" --dest "./pkgs/$(basename "$url" .git)" --force
-done < urls.txt
-# then review, build, and publish each in a loop of your own
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `<url>` positional | *(required)* | Upstream git URL. Accepts HTTPS or SSH form. |
-| `--dest <dir>` | `basename(url)` | Destination directory for the clone. |
-| `--ref <ref>` | *(remote HEAD)* | Clone at a specific branch / tag / SHA. |
-| `--name` | *(from URL)* | Override the derived package name. |
-| `--pkg-version` | *(nearest git tag)* | Override the version. Named oddly so yargs doesn't confuse it with the built-in `--version`. |
-| `--kind` | *(auto-detect)* | Force `ConsoleApp` / `StaticLib` / `DynamicLib` / `HeaderOnlyLib` / etc. |
-| `--description` | *(TODO placeholder)* | One-line description written into `wyvrn.json`. |
-| `--no-clone` | `false` | Skip the clone step; operate on an already-populated `--dest`. |
-| `--shallow` | `false` | `--depth 1` clone. Faster, but git tag detection degrades — pair with `--pkg-version` when using this. |
-| `--dry-run` | `false` | Print the proposed manifest + TODOs; don't write `wyvrn.json`. |
-| `--force` | `false` | Overwrite an existing destination and/or `wyvrn.json`. |
-| `--format` | `text` | Output format: `text` (human) or `json` (CI — one object on stdout). |
-
-The cookbook of per-library hints lives in [src/bootstrap/cookbook.js](src/bootstrap/cookbook.js). Current coverage is ~30 popular libraries (fmt, spdlog, nlohmann/json, yaml-cpp, zlib, Catch2, lz4, brotli, hiredis, redis-plus-plus, GLM, SQLiteCpp, re2, …). Adding a new entry is a two-line change — submit a PR.
-
-The patterns bootstrap detects (header-only with INTERFACE target, standard CMake static lib, CMake with wyvrnpm dep, ABI-option'd lib, non-CMake upstream) are catalogued in the bundled Agent Skill at [claude/skills/wyvrnpm/references/oss-conversion-patterns.md](claude/skills/wyvrnpm/references/oss-conversion-patterns.md) — Claude reads it when you ask "how do I convert X to a wyvrnpm package?".
-
----
-
-### `wyvrnpm add`
-
-Adds one or more dependencies to `wyvrn.json` without downloading them. Useful when you know the package name but not the latest version.
-
-- **Bare name** — resolves `latest.json` from your configured install sources and writes `"^<latest>"` (caret range, major-pinned).
-- **`name@<version>`** — writes the given string verbatim. Accepts exact pins (`1.2.3.4`), caret/tilde ranges (`^1.2.3.4`, `~1.2.3.4`), and explicit comparators (`>=1.80.0 <2.0.0`).
-
-If the dependency is already listed, it is replaced. When the prior entry was an object (`{ version, settings, options }`), the `settings` and `options` are preserved — only the version field is updated.
-
-`add` does **not** run install. Chain `wyvrnpm install` afterwards to download.
-
-```bash
-# Resolve latest, write "^<latest>"
-wyvrnpm add zlib
-
-# Pin exactly
-wyvrnpm add zlib@1.3.0.0
-
-# Use a caret / tilde / comparator range
-wyvrnpm add fmt@^10.0.0
-wyvrnpm add boost@">=1.80.0 <2.0.0"
-
-# Multiple in one call
-wyvrnpm add zlib fmt@10.2.0.0 spdlog
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--source` / `-s` | *(config)* | Base URL used for the `latest` lookup. Repeat for multiple. |
-| `--platform` | `win_x64` | v1 legacy platform sub-path (used as a fallback during `latest` lookup). |
-| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
-
----
-
-### `wyvrnpm version`
-
-Read, set, or partially update the top-level `version` field in `wyvrn.json`. Designed for CI/CD — bumps the build component from a pipeline variable, prints the result for capture, and never touches git (CI pipelines own tagging and commits).
-
-- **Bare** — prints the current version on stdout, naked (no `[wyvrn]` prefix), so `VER=$(wyvrnpm version)` works straight away.
-- **Full set** — `wyvrnpm version 1.2.3.4` writes the value verbatim. Strict 4-part `x.y.z.b` validation; leading zeros and 3-part semver are rejected.
-- **Component flags** — `--major / --minor / --patch / --build N` replace one component while leaving the others alone. Combine flags freely (`--minor 3 --build 0`).
-- Positional and component flags are mutually exclusive — pick a mode.
-
-```bash
-# Read the current version (CI capture)
-VER=$(wyvrnpm version)
-
-# Inject the build number from a pipeline variable
-wyvrnpm version --build "$BUILD_ID"
-
-# Cut a minor release — reset the build component to 0
-wyvrnpm version --minor 3 --build 0
-
-# Set a full version verbatim
-wyvrnpm version 2.0.0.0
-
-# CI-friendly capture
-wyvrnpm version --build "$BUILD_ID" --format json
-# {"command":"version","previous":"1.2.3.4","version":"1.2.3.99","written":true,...}
-
-# Preview without writing
-wyvrnpm version --build 99 --dry-run
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `<newVersion>` positional | — | Full 4-part version (e.g. `1.2.3.4`). Mutex with `--major/--minor/--patch/--build`. |
-| `--major` | — | Replace the 1st component. |
-| `--minor` | — | Replace the 2nd component. |
-| `--patch` | — | Replace the 3rd component. |
-| `--build` | — | Replace the 4th component (typical CI use). |
-| `--dry-run` | `false` | Compute and print the proposed version without writing. |
-| `--format` | `text` | Output format: `text` (human) or `json` (CI — single object on stdout). |
-| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
-
----
-
-### `wyvrnpm install`
-
-Resolves the full dependency graph and downloads all packages.
-
-**Source priority:** CLI `--source` values are used if provided. If omitted, sources are loaded from the [configuration file](#configuration-file).
-
-**Profile resolution:** `--profile` selects the named build profile. If omitted, `config.defaultProfile` is used, falling back to `"default"`. v2 binaries are resolved in this order:
-
-1. **Exact profile-hash match** — the preferred path.
-2. **Declarative compatibility** — each published build may advertise a `compatibility` block (e.g. "compatible with any `msvc.version ≥ 193` on `Windows/x86_64`"). The best compatible candidate is picked deterministically.
-3. **Source build** (with `--build=missing`) — clones the package's source at the published `gitSha`, resolves its own dependencies, invokes CMake through the shared toolchain generator, and caches the result under `%LOCALAPPDATA%\wyvrnpm\bc\`. On Windows/MSVC with a Ninja or Make generator, `vcvarsall.bat` is auto-activated.
-4. **v1 legacy path** — only when no v2 entry exists for the package at all.
-
-The pre-2.1 "same OS + arch, any compiler" loose fallback is no longer available. Publish a build for your profile, add a declarative `compatibility` block to the recipe, or rerun with `--build=missing` to source-build.
-
-```bash
-# Use configured sources and the default build profile
-wyvrnpm install
-
-# Use a specific named profile
-wyvrnpm install --profile release
-
-# Override with explicit sources
-wyvrnpm install --source https://pkg.example.com/cpp
-
-# Multiple sources — tried in order, first to respond wins
-wyvrnpm install \
-  --source https://primary.example.com/cpp \
-  --source https://mirror.example.com/cpp
-
-# Build any missing binary from source
-wyvrnpm install --build=missing
-
-# Force every dep to be rebuilt from source (debugging / reproducibility check)
-wyvrnpm install --build=always
-
-# Print the resolved install plan WITHOUT downloading (CI-friendly with --format=json)
-wyvrnpm install --dry-run
-wyvrnpm install --dry-run --format=json
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--source` / `-s` | *(config)* | Base URL of a package source. Repeat for multiple. Overrides config when provided. |
-| `--profile` / `-p` | *(config / "default")* | Named build profile to use for v2 binary resolution. |
-| `--build` | `never` | Resolution mode when no exact or compatible profile match exists: `never` fails; `missing` clones and builds the package from its published `gitRepo@gitSha`; `always` rebuilds even when a binary exists. |
-| `--platform` | `win_x64` | v1 legacy platform sub-path (used as a fallback when no v2 binary is found). |
-| `--timeout` | `300` | HTTP request timeout in seconds. |
-| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
-| `--root` | `./` | Project root (packages extracted to `{root}/wyvrn_internal/`). |
-| `--dry-run` | `false` | Run the resolver + profile/options math, print the install plan, and exit. No download, no `wyvrn.lock`, no `wyvrn_internal/`, no toolchain. Combine with `--format=json` for CI ingestion (payload carries `command: "install-dry-run"`). |
-| `--conf` | — | Non-ABI build-time override. Repeatable. Format: `<namespace.leaf>=<value>` — e.g. `--conf cmake.cache.CHROMA_ENABLE_TEST=ON`. Layered: CLI > `wyvrn.local.json` > named-profile `conf` > recipe. Does **not** fold into `profileHash`. See [Build-time configuration (`conf`)](#build-time-configuration-conf). |
-
-Packages are extracted to `wyvrn_internal/{name}/`. A `wyvrn.lock` file is written alongside the manifest recording the exact resolved versions, profile, and per-package SHA256. On subsequent installs the lock file pins all previously resolved versions — only newly added dependencies are resolved fresh.
-
-After download, `install` also generates:
-
-- `wyvrn_internal/wyvrn_toolchain.cmake` — CMake toolchain pointing at the resolved packages.
-- `wyvrn_internal/wyvrn_deps.cmake` — post-`project()` include for `find_package()` wiring and runtime DLL copy.
-- `wyvrn_internal/wyvrn_profile.json` — snapshot of the active build profile.
-- `CMakePresets.json` (or `CMakeUserPresets.json` if the project root file is user-owned) with a `wyvrn-<profile>` configure preset. Presets for other profiles are preserved so multiple profiles coexist.
-
-**Toolchain variables exposed to your `CMakeLists.txt` (valid BEFORE `project()`)**:
-
-| Variable | Value |
-|---|---|
-| `WYVRN_PROFILE_NAME` / `WYVRN_PROFILE_HASH` | Active profile name + 16-char hash |
-| `WYVRN_PROFILE_OS` / `WYVRN_PROFILE_ARCH` | OS + architecture from the profile |
-| `WYVRN_PROFILE_COMPILER` / `WYVRN_PROFILE_COMPILER_VERSION` | Compiler identity |
-| `WYVRN_PROFILE_CPPSTD` / `WYVRN_PROFILE_RUNTIME` | C++ standard + MSVC runtime linkage |
-| `WYVRN_ARCH_SUFFIX` | `"64"` for 64-bit arches, `"32"` for 32-bit, empty for unmapped. Derived at toolchain-generation time so it's usable before `project()` — unlike `CMAKE_SIZEOF_VOID_P`. |
-
-The optional helper `WYVRN_APPLY_ARCH_SUFFIX(<target> [BASE_NAME <name>])` from the bundled `macros.cmake` applies the suffix to a target's `OUTPUT_NAME` so x64 and x86 builds of the same library coexist on disk without overwriting each other. Target linkage (`target_link_libraries`) is unaffected — only the produced filename changes.
-
-The bundled `variables.cmake` also suffixes the consumer's own output directories with `WYVRN_ARCH_SUFFIX` so multi-arch builds from one source tree don't clobber each other:
-
-| Profile arch | Archive/library dir | Runtime (DLL/EXE) dir |
-|---|---|---|
-| `x86_64` / `armv8` | `output/lib64/` | `output/bin64/<CONFIG>/` |
-| `x86` / `armv7` | `output/lib/` | `output/bin/<CONFIG>/` |
-| unmapped | `output/lib/` | `output/bin/<CONFIG>/` |
-
-Prior to `2.5.0` the runtime directory was always `output/bin/<CONFIG>/` regardless of arch — a multi-arch consumer building x64 then x86 would silently overwrite the first arch's DLLs. Scripts that hard-code `output/bin/…` expecting x64 payloads need to switch to `output/bin64/…` after upgrading.
-
-```cmake
-project(String CXX)
-add_library(String STATIC ...)
-WYVRN_APPLY_ARCH_SUFFIX(String)                 # → String64.lib / String32.lib
-WYVRN_APPLY_ARCH_SUFFIX(String BASE_NAME my-str) # → my-str64.lib / my-str32.lib
-```
-
----
-
-### `wyvrnpm build`
-
-Configures and builds the project through the wyvrnpm-generated CMake preset. Auto-runs `install` first if `wyvrn_toolchain.cmake` is missing or `wyvrn.lock` is newer than it.
-
-```bash
-# Configure + build with the default profile's preset (wyvrn-default)
-wyvrnpm build
-
-# Build Debug, verbose compiler output
-wyvrnpm build --config Debug --verbose
-
-# Build multiple configs in one go — configure runs once, build loops per config
-wyvrnpm build --config Debug,Release --install
-
-# Build every config the recipe declares (recipe's build.configs, or all four
-# canonical configs if no recipe is present). Pairs naturally with --install.
-wyvrnpm build --all-configs --install
-
-# Use a specific profile's preset
-wyvrnpm build --profile release
-
-# Explicit preset name (overrides profile-derived default)
-wyvrnpm build --preset wyvrn-release
-
-# Build a single target
-wyvrnpm build --target my-lib
-
-# Wipe the build directory first
-wyvrnpm build --clean
-
-# Override the preset's generator (pair with --clean when switching generators)
-wyvrnpm build --clean --generator "Visual Studio 17 2022"
-wyvrnpm build --clean -G "Ninja Multi-Config"
-
-# Build, then install to the CMake install prefix
-wyvrnpm build --install
-wyvrnpm build --install --install-prefix C:\out\stage
-
-# Skip the auto-install step
-wyvrnpm build --no-auto-install
-
-# Pass extra args through to cmake --build
-wyvrnpm build -- -j 8
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--preset` / `-P` | `wyvrn-<profile>` | CMake configure preset name. |
-| `--profile` / `-p` | *(config / "default")* | Build profile — determines the default preset name. |
-| `--config` / `-c` | `Release` | Build configuration (`Debug` \| `Release` \| `RelWithDebInfo` \| `MinSizeRel`). Comma-separated to build multiple in one invocation (e.g. `Debug,Release`) — configure runs once, build (+ `--install`) loops per config. |
-| `--all-configs` | `false` | Build every config from the recipe's `build.configs` (or all four canonical configs when no recipe is present). Takes precedence over `--config`. |
-| `--target` / `-t` | *(all)* | Specific CMake target to build. |
-| `--verbose` / `-v` | `false` | Pass `--verbose` to `cmake --build`. |
-| `--clean` | `false` | Remove the build directory before configuring. |
-| `--generator` / `-G` | *(from preset)* | Override the CMake generator used at configure time (e.g. `"Visual Studio 17 2022"`, `"Ninja"`, `"Ninja Multi-Config"`). CMake bakes the generator into the cache, so pair with `--clean` when switching. When the effective generator is Visual Studio, `-A <platform>` is auto-derived from the profile's arch (`x86→Win32`, `x86_64→x64`, `armv8→ARM64`, `armv7→ARM`) so VS doesn't silently default to x64 on 32-bit profiles. |
-| `--install` | `false` | Run `cmake --install` after a successful build. |
-| `--install-prefix` | *(baked in)* | Override `CMAKE_INSTALL_PREFIX` for `--install` without reconfiguring. |
-| `--auto-install` | `true` | Auto-run `wyvrnpm install` when the toolchain is stale. Disable with `--no-auto-install`. |
-| `--source` / `-s` | *(config)* | Package sources — passed through to `install` when auto-installing. |
-
-Everything after `--` is forwarded verbatim to `cmake --build` (e.g. `-j 8`).
-
----
-
-### `wyvrnpm publish`
-
-Zips the project directory and uploads `wyvrn.json` + `wyvrn.zip` to the destination source, tagged with the active build profile.
-
-**Source priority:** CLI `--source` is used if provided (as a URL/URI or a configured source name). If omitted, the first configured publish source is used.
-
-**Profile:** `--profile` selects the named build profile to publish under. If omitted, `config.defaultProfile` is used, falling back to `"default"`. The profile hash is included in the upload path so multiple builds of the same version (different compilers, runtimes, etc.) can coexist.
-
-```bash
-# Use configured source and default profile
-wyvrnpm publish
-
-# Use a specific profile
-wyvrnpm publish --profile release
-
-# Reference a configured source by name
-wyvrnpm publish --source default
-
-# Explicit destination URL
-wyvrnpm publish --source s3://my-bucket/packages --aws-profile my-sso
-
-# HTTP server with token auth (CI-preferred: --token-env avoids argv leakage)
-wyvrnpm publish --source https://pkg.corp.com --token-env WYVRN_HTTP_TOKEN
-# Equivalent for interactive use; --token lands in shell history / ps output
-wyvrnpm publish --source https://pkg.corp.com --token mytoken
-
-# Local directory or SMB share
-wyvrnpm publish --source \\fileserver\packages
-wyvrnpm publish --source /mnt/packages
-
-# Publish build artifacts from a specific directory
-wyvrnpm publish --path ./dist
-
-# Overwrite an existing build (same version + profile hash)
-wyvrnpm publish --force
-
-# Dry-run — show the upload plan without touching the registry
-wyvrnpm publish --dry-run
-wyvrnpm publish --dry-run --format json | jq '.wouldOverwrite, .plan'
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--source` / `-s` | *(config)* | Destination URL/URI or configured source name. |
-| `--profile` / `-p` | *(config / "default")* | Named build profile to publish under. |
-| `--aws-profile` | *(config)* | AWS SSO profile for S3 authentication. |
-| `--token` | *(config)* | Bearer token for HTTP server authentication. |
-| `--token-env` | *(config)* | Name of an env var holding the bearer token. Preferred for CI — the literal value never lands in `argv` or shell history. |
-| `--path` | `.` | Directory to zip and publish. |
-| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
-| `--force` / `-f` | `false` | Overwrite an existing published version (same version + profile hash). |
-| `--dry-run` | `false` | Run every step (profile, options, zip, SHA256, `v2Exists` check) and print the upload plan, but skip the provider write. An existing published version is reported as a warning (not an error) so the full plan still prints. Pair with `--format json` to gate CI on `wouldOverwrite`. |
-
-During publish the tool also:
-- reads `wyvrn.lock` to pin locked dependency versions into the uploaded manifest
-- captures the current git commit SHA and remote URL as metadata
-- computes a SHA256 of the zip and stores it in the upload metadata
-
----
-
-### `.wyvrnignore`
-
-Place a `.wyvrnignore` file in the directory being published to exclude files from the zip. Uses the same glob syntax as `.gitignore`:
-
-```
-# Build artefacts that shouldn't ship
-build/
-*.obj
-*.pdb
-
-# Anchored to root with leading /
-/CMakeCache.txt
-/CMakeFiles/
-```
-
----
-
-### `wyvrnpm clean`
-
-Removes the `wyvrn_internal/` package cache and `wyvrn.lock`.
-
-```bash
-# Project-local cleanup
-wyvrnpm clean
-
-# Also wipe the machine-wide source-build cache used by --build=missing
-wyvrnpm clean --build-cache
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--build-cache` | `false` | Also remove the source-build cache under `%LOCALAPPDATA%\wyvrnpm\bc\` (Unix: `~/.cache/wyvrnpm/bc/`). |
-| `--uploaded-built` | `false` | Wipe only the local record of what this machine has uploaded via `--upload-built` (the `.uploaded-to.json` sidecars). Does **not** touch the registry, the artefacts, or `wyvrn_internal/`. |
-
-For selective cache pruning (keep last N variants, drop entries older than N days), use `wyvrnpm cache prune` instead — see below.
-
----
-
-### `wyvrnpm cache` (2.8.0+)
-
-Inspect and selectively prune the machine-wide source-build cache at `%LOCALAPPDATA%\wyvrnpm\bc\` (Unix: `~/.cache/wyvrnpm/bc/`). Useful once `--upload-built` adoption balloons cache size on dev rigs — `clean --build-cache` is the blunt alternative that wipes everything.
-
-```bash
-# List every cached entry as a table
-wyvrnpm cache list
-
-# Filter by package name (glob)
-wyvrnpm cache list "boost*"
-
-# Machine-readable output for CI
-wyvrnpm cache list --format json
-
-# Keep the 2 most-recently-touched variants per (name, version)
-wyvrnpm cache prune --keep-last 2
-
-# Drop entries older than 30 days
-wyvrnpm cache prune --older-than 30d
-
-# Combine: keep 1 recent per version AND drop anything stale
-wyvrnpm cache prune --keep-last 1 --older-than 30d
-
-# Preview — print what would be removed, delete nothing
-wyvrnpm cache prune --keep-last 2 --dry-run
-```
-
-**`cache list` options**
-
-| Option | Default | Description |
-|---|---|---|
-| `[pattern]` / `--pattern` | *(none)* | Glob over package names (`*` for any chars, `?` for one). |
-| `--format` | `text` | `text` (table) or `json` (structured payload for CI). |
-
-**`cache prune` options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--keep-last <N>` | *(none)* | Retain the N most-recently-touched entries **per (name, version) group**. A four-profile rig keeping-last-2 still retains the two newest profile variants of each version. |
-| `--older-than <dur>` | *(none)* | Remove entries whose mtime is older than the threshold. Format: `<number><unit>`, unit ∈ `s` / `m` / `h` / `d` (e.g. `30d`, `72h`). |
-| `--pattern <glob>` | *(none)* | Restrict scope to package names matching the glob. |
-| `--dry-run` | `false` | Print what would be removed without deleting. |
-
-At least one of `--keep-last` / `--older-than` is required — calling `prune` bare errors out with a pointer to `clean --build-cache` (the nuke-everything path).
-
----
-
-### `wyvrnpm show`
-
-Read-only registry-metadata inspector. Given `<name>[@<version>[@<profileHash>]]`, queries the first configured install source that knows the package (override with `--source`) and prints what's published.
-
-```bash
-# Index of every published version (one HTTP round trip per source)
-wyvrnpm show zlib
-
-# Narrow to one version — fans out a per-profile query so uploadedBy,
-# compatibility, and declared options show up per build
-wyvrnpm show zlib@1.3.0.0
-
-# Narrow to one specific build
-wyvrnpm show zlib@1.3.0.0@a1b2c3d4e5f60718
-
-# Pick the source explicitly (skips install-source lookup order)
-wyvrnpm show zlib@1.3.0.0 --source s3://team-pkgs
-
-# Machine-readable for CI ingestion
-wyvrnpm show zlib@1.3.0.0 --format json
-```
-
-What gets surfaced per profile:
-
-- **origin** — `author-publish` vs `consumer-upload` (derived from whether the manifest carries an `uploadedBy` block).
-- **uploadedBy** — when set, the consumer-upload provenance (`kind`, `builtFromGit`, `builtFromSha`, `uploadedAt`, `wyvrnpmVersion`).
-- **compatibility** — the recipe's declarative compat block, if any.
-- **declaredOptions** — the author-declared `options` map from the recipe.
-- **resolvedOptions** — the resolved option values that produced this profile's `profileHash`.
-- **publishedConf** — recipe + CLI `--conf` the publisher captured (informational; doesn't affect resolution).
-- **signature** — when PLAN-SIGNING phase 1 ships, signer identity; absent today.
-
-Useful for: auditing consumer uploads (who pushed this artefact, from which commit), spotting profile drift between two consumers, verifying a package's declared options before adding it to a recipe.
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `pkg` *(positional)* | *(required)* | `<name>[@<version>[@<profileHash>]]` |
-| `--source` / `-s` | *(first configured install source)* | URL or configured source name. Repeatable. |
-| `--format` | `text` | `text` or `json` (see [Shape — `show`](#shape--show) below). |
-| `--token` / `--token-env` / `--aws-profile` | | Auth forwarded to the provider the same way `install` does. |
-
----
-
-### `wyvrnpm install-skill`
-
-Installs the bundled wyvrnpm Agent Skill — the authoring guide Claude Code uses when it sees a `wyvrn.json` in the workspace. Ships as a `.skill` zip inside the npm package (`claude/skills/wyvrnpm.skill`) and is extracted into `~/.claude/skills/wyvrnpm/` on demand.
-
-```bash
-# One-shot: install the bundled skill for Claude Code
-wyvrnpm install-skill --claude
-
-# Overwrite an existing installation (e.g. after upgrading wyvrnpm)
-wyvrnpm install-skill --claude --force
-
-# Preview without writing
-wyvrnpm install-skill --claude --dry-run
-```
-
-You only need this if you want Claude Code to pick up the skill. The CLI itself works without it.
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--claude` | `false` | Install for Claude Code (extracts to `~/.claude/skills/wyvrnpm/` + writes the `.skill` zip alongside). Required — present so a future `--cursor` / `--vscode` target can slot in without CLI churn. |
-| `--force` | `false` | Overwrite an existing skill install. Without it, the command refuses to clobber. |
-| `--dry-run` | `false` | Print the destination paths and intended actions without writing. |
-
----
-
-### `wyvrnpm link`
-
-Links a local package for development, similar to `npm link`. This allows you to test packages from local source directories without publishing to the registry.
-
-#### Register a package globally
-
-Run `wyvrnpm link` in a package directory to register it for linking:
-
-```bash
-cd C:\Dev\my-library
-wyvrnpm link
-# [wyvrn] Registered "my-library" -> C:\Dev\my-library
-```
-
-For CMake packages where the installable content is in a subdirectory:
-
-```bash
-cd C:\Dev\my-cmake-lib
-wyvrnpm link --subdir output/install
-# [wyvrn] Registered "my-cmake-lib" -> C:\Dev\my-cmake-lib\output\install
-```
-
-#### Link a package into your project
-
-Link a globally registered package:
-
-```bash
-cd C:\Projects\my-app
-wyvrnpm link my-library
-# [wyvrn] Linked: my-library -> C:\Dev\my-library
-```
-
-Or link directly from a path (skip global registration):
-
-```bash
-wyvrnpm link my-library C:\Dev\my-library
-wyvrnpm link my-library C:\Dev\my-library --subdir output/install
-```
-
-#### List registered packages
-
-```bash
-wyvrnpm link --list
-# [wyvrn] Globally registered packages:
-#   my-library -> C:\Dev\my-library
-#   my-cmake-lib -> C:\Dev\my-cmake-lib\output\install [subdir: output/install]
-```
-
-**Options**
-
-| Option | Description |
-|---|---|
-| `--list` | List all globally registered packages. |
-| `--subdir` | Subdirectory within the package to link (e.g., `output/install` for CMake packages). |
-
-**How it works:**
-- Creates a symlink (Unix) or junction (Windows) in `wyvrn_internal/`
-- Junctions on Windows don't require admin rights
-- Linked packages are recorded in `wyvrn.lock` with a `linked:` prefix
-- `wyvrnpm install` automatically skips downloading linked packages
-
----
-
-### `wyvrnpm unlink`
-
-Removes a linked package from the current project.
-
-```bash
-wyvrnpm unlink my-library
-# [wyvrn] Unlinked: my-library
-```
-
-To unlink and re-download from the registry:
-
-```bash
-wyvrnpm unlink my-library --restore
-# [wyvrn] Unlinked: my-library
-# [wyvrn] Downloading: my-library@1.0.0.0
-```
-
-**Options**
-
-| Option | Default | Description |
-|---|---|---|
-| `--restore` | `false` | Re-download the package from registry after unlinking. |
-| `--source` | *(config)* | Package source for `--restore`. |
-| `--platform` | `win_x64` | Target platform for v1 fallback when using `--restore`. |
-
----
-
-### `wyvrnpm configure`
-
-Manages the [configuration file](#configuration-file). All sub-commands read and write `config.json` in the platform config directory.
-
-#### `wyvrnpm configure list`
-
-Prints all configured sources.
-
-```
-Config: C:\Users\you\AppData\Local\wyvrnpm\config.json
-
-Install Sources:
-  corp-s3              s3://my-bucket/packages  [profile: my-sso]
-  fallback             https://pkg.corp.com      [token: ***]
-
-Publish Sources:
-  default              s3://my-bucket/packages  [profile: my-sso]
-```
-
-#### `wyvrnpm configure add-source`
-
-Adds a new source or updates an existing one with the same name.
-
-```bash
-# S3 with AWS SSO profile (install)
-wyvrnpm configure add-source \
-  --kind install \
-  --name corp-s3 \
-  --url s3://my-bucket/packages \
-  --profile my-sso-profile
-
-# HTTPS server with token auth (install)
-wyvrnpm configure add-source \
-  --kind install \
-  --name fallback \
-  --url https://pkg.corp.com \
-  --token mytoken
-
-# Local or SMB path (no auth required)
-wyvrnpm configure add-source \
-  --kind install \
-  --name local \
-  --url \\fileserver\packages
-
-# Publish destination
-wyvrnpm configure add-source \
-  --kind publish \
-  --name default \
-  --url s3://my-bucket/packages \
-  --profile my-sso-profile
-```
-
-**Options**
-
-| Option | Required | Description |
-|---|---|---|
-| `--kind` | Yes | `install` or `publish`. |
-| `--name` | Yes | Unique name for this source. |
-| `--url` | Yes | Destination URL, URI, or file path. |
-| `--profile` | No | AWS SSO profile (S3 sources). |
-| `--token` | No | Bearer token (HTTP sources). Persisted in plaintext in `config.json` — prefer `--token-env` for CI and shared setups. |
-| `--token-env` | No | Name of an env var whose value is the bearer token. Only the **name** lands in `config.json`; the value is resolved fresh on every `wyvrnpm` call. |
-
-#### `wyvrnpm configure remove-source`
-
-Removes a source by name.
-
-```bash
-wyvrnpm configure remove-source --kind install --name fallback
-wyvrnpm configure remove-source --kind publish --name default
-```
-
-#### `wyvrnpm configure profile`
-
-Manages named build profiles stored in the profiles directory.
-
-```bash
-# Auto-detect the current build environment and save it
-wyvrnpm configure profile detect
-wyvrnpm configure profile detect --name msvc_release --dry-run
-
-# List all saved profiles (* = default)
-wyvrnpm configure profile list
-
-# Show a saved profile
-wyvrnpm configure profile show
-wyvrnpm configure profile show --name msvc_release
-
-# Manually set individual fields in a profile
-wyvrnpm configure profile set --name msvc_release --runtime static --cppstd 20
-
-# Change which profile is the default
-wyvrnpm configure profile set-default msvc_release
-
-# Delete a profile
-wyvrnpm configure profile delete msvc_release
-```
-
-**`configure profile detect` options**
-
-| Option | Description |
-|---|---|
-| `--name` / `-n` | Profile name to save to (default: `"default"`). |
-| `--dry-run` | Print detected values without saving. |
-
-**`configure profile set` options**
-
-| Option | Description |
-|---|---|
-| `--name` / `-n` | Profile name to update (default: `"default"`). |
-| `--os` | OS (`Windows` \| `Linux` \| `Macos`). |
-| `--arch` | Architecture (`x86_64` \| `x86` \| `armv8` \| ...). |
-| `--compiler` | Compiler (`msvc` \| `gcc` \| `clang` \| `apple-clang`). |
-| `--compiler-version` | Compiler version (`193` \| `13` \| `17` \| ...). |
-| `--cppstd` | C++ standard (`14` \| `17` \| `20` \| `23`). |
-| `--runtime` | Runtime linkage (`static` \| `dynamic`). |
-
----
-
-## JSON output (`--format json`)
-
-`install`, `publish`, and `show` accept `--format json` to emit a single machine-readable JSON object on stdout. Log lines (`[wyvrn]` prefix) move to **stderr** in this mode, so stdout is reserved exclusively for the JSON payload — no scraping required.
-
-```bash
-wyvrnpm install --format json > install-result.json
-wyvrnpm publish --format json 2>/dev/null           # swallow logs, keep JSON
-wyvrnpm show zlib@1.3.0.0 --format json | jq '.versions["1.3.0.0"].profiles[].origin'
-```
-
-### Shape — `install`
-
-```json
-{
-  "command": "install",
-  "wyvrnpmVersion": "2.2.1",
-  "profile": { "os": "Windows", "arch": "x86_64", "compiler": "msvc", "compiler.version": "193", "compiler.cppstd": "23", "compiler.runtime": "dynamic" },
-  "profileName": "default",
-  "profileHash": "bf341c08af0aee2d",
-  "packages": [
-    {
-      "name": "zlib",
-      "version": "1.3.0.0",
-      "versionRange": "^1.3.0.0",
-      "profileHash": "a1b2c3d4e5f60718",
-      "options": { "shared": false, "minizip": true },
-      "contentSha256": "…",
-      "gitSha": "…",
-      "resolvedFrom": "v2"
-    }
-  ],
-  "lockFile": "/abs/path/to/wyvrn.lock",
-  "uploadSummary": { "uploaded": 0, "skipped": 0, "failed": 0 }
-}
-```
-
-- `versionRange` is `null` when the user pinned an exact version.
-- `options` is `null` for packages that declare no options.
-- `uploadSummary` is `null` unless `--upload-built` was passed.
-- `packages` is sorted by name.
-
-### Shape — `publish`
-
-```json
-{
-  "command": "publish",
-  "wyvrnpmVersion": "2.2.1",
-  "name": "zlib",
-  "version": "1.3.0.0",
-  "profileHash": "a1b2c3d4e5f60718",
-  "source": "s3://team-pkgs",
-  "contentSha256": "…",
-  "options": { "shared": false, "minizip": true },
-  "gitSha": "…",
-  "gitRepo": "…",
-  "publishedAt": "2026-04-21T12:34:56.789Z"
-}
-```
-
-### Shape — `show`
-
-```json
-{
-  "command": "show",
-  "wyvrnpmVersion": "2.2.1",
-  "source": "s3://team-pkgs",
-  "package": "zlib",
-  "latest": "1.3.0.0",
-  "versions": {
-    "1.3.0.0": {
-      "source": { "gitRepo": "…", "gitSha": "…" },
-      "profiles": [
-        {
-          "profileHash": "a1b2c3d4e5f60718",
-          "contentSha256": "…",
-          "publishedAt": "…",
-          "buildSettings": { "os": "Windows", "...": "...", "options": { "minizip": true } },
-          "origin": "author-publish",
-          "uploadedBy": null,
-          "compatibility": { "compiler.cppstd": "lte" },
-          "declaredOptions": { "minizip": { "default": true, "allowed": [true, false] } }
-        }
-      ]
-    }
-  }
-}
-```
-
-- `origin` is `"author-publish"` | `"consumer-source-build"` | `null` (the last when the summary view can't tell without a deep fetch).
-- Bare-name queries (`wyvrnpm show zlib --format json`) skip the per-profile deep fetch; `origin`, `uploadedBy`, `compatibility`, `declaredOptions` are `null` for each profile.
-
-Exit codes and error behaviour are identical to text mode. Fatal errors leave stdout empty rather than emitting partial JSON.
-
----
-
-## Configuration File
-
-wyvrnpm stores persistent configuration in a `config.json` file:
-
-| Platform | Path |
-|---|---|
-| Windows | `%LOCALAPPDATA%\wyvrnpm\config.json` |
-| Linux / macOS | `~/.config/wyvrnpm/config.json` |
-
-**Example config.json**
-
-```json
-{
-  "defaultProfile": "default",
-  "installSources": [
-    {
-      "name": "corp-s3",
-      "url": "s3://my-bucket/packages",
-      "profile": "my-sso-profile"
-    },
-    {
-      "name": "fallback",
-      "url": "https://pkg.corp.com",
-      "token": "mytoken"
-    }
-  ],
-  "publishSources": [
-    {
-      "name": "default",
-      "url": "s3://my-bucket/packages",
-      "profile": "my-sso-profile"
-    }
-  ],
-  "linkedPackages": {
-    "my-library": { "path": "C:\\Dev\\my-library" },
-    "my-cmake-lib": { "path": "C:\\Dev\\my-cmake-lib", "subdir": "output/install" }
-  }
-}
-```
-
-The `defaultProfile` field sets which named build profile is used when `--profile` is not provided on the CLI.
-
-The `linkedPackages` field stores globally registered packages for `wyvrnpm link`. Each entry maps a package name to its local path and optional subdirectory.
-
-**CLI options always take priority over config.** Config values are only used when the corresponding CLI option is not provided.
-
----
-
-## Publish Providers
-
-wyvrnpm uses a provider architecture to support different destination types. The correct provider is selected automatically based on the source URL format.
-
-| Provider | Detected from | Auth |
-|---|---|---|
-| **S3** | `s3://` URI, or S3 HTTPS endpoint | `--aws-profile` (AWS SSO) |
-| **HTTP** | `http://` or `https://` | `--token` (Bearer) |
-| **File** | Local path or UNC/SMB share | none |
-
-### S3 Provider
-
-Accepts any of these source formats:
-
-```
-s3://bucket-name/optional/prefix
-https://bucket-name.s3.amazonaws.com/prefix
-https://bucket-name.s3.us-east-1.amazonaws.com/prefix
-https://s3.amazonaws.com/bucket-name/prefix
-https://s3.us-east-1.amazonaws.com/bucket-name/prefix
-```
-
-Authentication uses AWS SSO via `--aws-profile`. If no profile is given, the default AWS credential chain is used.
-
-### HTTP Provider
-
-Accepts `http://` and `https://` URLs. Uploads files via HTTP `PUT`. Optionally authenticates with a Bearer token via `--token`.
-
-### File Provider
-
-Accepts local directory paths and SMB/UNC network shares. Files are copied with no authentication required.
-
-```
-/absolute/unix/path
-./relative/path
-C:\Windows\path
-\\server\share\path
-//server/share/path
-file:///absolute/path
-```
-
-### Adding a Custom Provider
-
-1. Create `src/providers/myprovider.js` extending `BaseProvider`:
-
-```js
-'use strict';
-const BaseProvider = require('./base');
-
-class MyProvider extends BaseProvider {
-  static canHandle(source) {
-    return source.startsWith('myscheme://');
-  }
-
-  static get providerName() { return 'MyProvider'; }
-
-  async v2Publish(files, options) {
-    // files.manifest — path to wyvrn.json
-    // files.zip      — path to wyvrn.zip
-    // options.source, options.name, options.version, options.profileHash
-    // options.contentSha256, options.gitSha, options.gitRepo
-    // options.buildSettings, options.lockedDependencies
-  }
-
-  async v2Exists(options) {
-    // Return true if this version+profileHash already exists
-    return false;
-  }
-}
-
-module.exports = MyProvider;
-```
-
-2. Register it in `src/providers/index.js`:
-
-```js
-const MyProvider = require('./myprovider');
-
-const PROVIDERS = [
-  S3Provider,
-  HttpProvider,
-  FileProvider,
-  MyProvider,   // add here
-];
-```
-
----
-
-## Registry Layout
-
-### v2 layout (current)
-
-Packages published by v2 tooling are stored under a `v2/` prefix, with the profile hash as a sub-directory:
-
-```
-{source}/v2/{name}/{version}/{profileHash}/wyvrn.json   <- package manifest + metadata
-{source}/v2/{name}/{version}/{profileHash}/wyvrn.zip    <- package archive
-{source}/v2/{name}/versions.json                        <- version index
-{source}/v2/{name}/latest.json                          <- latest version pointer
-```
-
-The profile hash is a 16-character SHA256 prefix computed from the build profile fields. This allows multiple compiler/platform variants of the same version to coexist in the same registry.
-
-**Example (S3):**
-
-```
-s3://my-bucket/packages/v2/OpenSSL/3.0.0.0/a1b2c3d4e5f60718/wyvrn.json
-s3://my-bucket/packages/v2/OpenSSL/3.0.0.0/a1b2c3d4e5f60718/wyvrn.zip
-```
-
-### v1 layout (legacy)
-
-v2 tooling also dual-publishes to the v1 path so that older clients can still consume packages:
-
-```
-{source}/{platform}/{name}/{version}/wyvrn.json
-{source}/{platform}/{name}/{version}/wyvrn.zip
-```
-
-**Example (HTTP):**
-
-```
-https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.json
-https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.zip
-```
-
-The tool also falls back to `razer.json` / `razer.zip` for legacy compatibility.
-
-### Package manifest (wyvrn.json hosted on source)
-
-```json
-{
-  "Name": "OpenSSL",
-  "Version": "3.0.0.0",
-  "Description": "TLS/SSL toolkit",
-  "Dependencies": [
-    { "Name": "zlib", "Version": "1.3.0.0" }
-  ]
-}
-```
-
-Fields use PascalCase. `Dependencies` is an array — transitive dependencies are resolved automatically.
-
----
-
-## Project Manifest (wyvrn.json)
-
-```json
-{
-  "name": "my-app",
-  "version": "1.0.0.0",
-  "description": "My C++ application",
-  "kind": "ConsoleApp",
-  "dependencies": {
-    "OpenSSL": "3.0.0.0",
-    "zlib": {
-      "version": "1.3.0.0",
-      "settings": {
-        "compiler.runtime": "static"
-      }
-    }
-  }
-}
-```
-
-**`kind` values:** `ConsoleApp`, `StaticLib`, `DynamicLib`, `HeaderOnlyLib`, `WebApp`, `Utility`, `Service`, `TestProject`
-
-**`dependencies`** can be either a plain version string (`"major.minor.patch.build"`) or an object with `version`, an optional `settings` map, and an optional `options` map. The `settings` map overrides individual build profile fields for that specific dependency — useful when a dependency must be consumed with a different runtime linkage or C++ standard than your default profile. The `options` map is covered in the next section.
-
-### Version ranges
-
-The `version` field accepts ranges in addition to exact versions and the `"latest"` tag:
-
-| Spec | Meaning |
-|---|---|
-| `"1.2.3.4"` | exact — must match byte-identically |
-| `"latest"` | resolves to whatever `latest.json` points at |
-| `"^1.2.3.4"` | major-pinned — `>= 1.2.3.4` and `< 2.0.0.0` |
-| `"~1.2.3.4"` | minor-pinned — `>= 1.2.3.4` and `< 1.3.0.0` |
-| `">=1.2.3.4 <2.0.0.0"` | explicit comparators — space-separated, supports `>=`, `>`, `<=`, `<`, `=` |
-
-Ranges resolve at install time against each source's `versions.json`. wyvrnpm picks the **highest version** that satisfies the range. The resolved exact version is pinned into `wyvrn.lock` alongside the original range string, so re-installs are byte-reproducible — ranges are only re-evaluated when the lock file's entry for that dependency is removed.
-
-**Error handling:**
-
-- **No version satisfies the range** → strict failure with every published version listed so you can see what's available.
-- **Conflicting ranges across the graph** (direct consumer wants `^1.x` but a transitive wants `^2.x`) → precise error naming both contributors and their ranges.
-- **Malformed range string** → fail fast with a cheat-sheet of supported syntaxes.
-
-Example:
-
-```json
-{
-  "dependencies": {
-    "OpenSSL": "^3.0.0.0",
-    "zlib":    "~1.3.0.0",
-    "boost":   ">=1.80.0.0 <2.0.0.0"
-  }
-}
-```
-
-### Per-dependency source pin (2.8.0+)
-
-When you have more than one configured install source (e.g. a primary S3 bucket plus a mirror), you can pin a security-sensitive dep to its canonical source by name:
-
-```json
-{
-  "dependencies": {
-    "OpenSSL": {
-      "version": "3.0.0.0",
-      "source":  "primary-s3"
-    }
-  }
-}
-```
-
-`"primary-s3"` must match a `name` from `wyvrnpm configure list`; an unknown name fails install with exit code 1 rather than silently fanning out. The pin closes two common multi-source holes:
-
-- **Mirror shadowing.** A package accidentally published to the mirror can't substitute for the primary's copy.
-- **Dependency confusion.** A squatter on a secondary source can't poison the build.
-
-Pins are direct-only — they don't cascade to the pinned package's own transitive deps. CLI `--source` overrides config entirely, so on a run with `--source`, any manifest pin is ignored with a warning rather than an error. The lockfile records `source: "<name>"` on pinned entries so reviewers can spot at a glance that the artefact came from the declared source; absent on non-pinned entries so pre-2.8.0 locks remain byte-identical.
-
-### Pattern-based `settingsOverrides` (2.8.0+)
-
-When many deps need the same settings override — every `boost-*` family member needing `compiler.cppstd: "17"`, or every `*-debug` variant needing `compiler.runtime: "static"` — declare the pattern at the top level of the manifest instead of copy-pasting per dep:
-
-```json
-{
-  "dependencies": {
-    "boost-filesystem": "1.80.0.0",
-    "boost-system":     "1.80.0.0",
-    "boost-thread":     "1.80.0.0",
-    "zlib":             "1.3.0.0"
-  },
-  "settingsOverrides": {
-    "boost*":  { "compiler.cppstd":  "17" },
-    "*-debug": { "compiler.runtime": "static" }
-  }
-}
-```
-
-Rules:
-
-- Keys are globs — `*` matches any chars, `?` matches exactly one, literal names work too. Both ends are anchored (no substring match unless you add `*` on either side).
-- Values accept the same keys as profile overrides: `os`, `arch`, `compiler`, `compiler.version`, `compiler.cppstd`, `compiler.runtime`. Unknown keys fail install with a clear error.
-- More-specific patterns win: literal `"boost-filesystem"` beats `"boost*"`, which beats `"*"`.
-- A literal per-dep `settings` block inside `dependencies` still wins over any pattern. Use that for the one dep that deviates from the family rule.
-
-Each matching pattern shifts that dep's `profileHash`, so different settings produce distinct registry artefacts — identical semantics to literal per-dep `settings`.
-
-### Package options (`options`)
-
-A library author can declare **options** — compile-time feature toggles that change the produced binary's ABI. Examples: `shared` (shared vs static library), `minizip` (zlib's minizip support), `fips` (OpenSSL's FIPS mode). Each option produces a distinct `profileHash`, so every option combination gets its own artefact on the registry.
-
-**Author side — declare in the recipe's `wyvrn.json`:**
-
-```json
-{
-  "name": "zlib",
-  "version": "1.3.0.0",
-  "options": {
-    "shared":  { "default": false, "allowed": [true, false] },
-    "minizip": { "default": true,  "allowed": [true, false] },
-    "api":     { "default": "default", "allowed": ["default", "legacy"] }
-  },
-  "build": {
-    "configure": [
-      "-DBUILD_SHARED_LIBS=${options.shared}",
-      "-DZLIB_BUILD_MINIZIP=${options.minizip}",
-      "-DZLIB_API_MODE=${options.api}"
-    ]
-  }
-}
-```
-
-Rules for the declaration:
-
-- Option names must match `/^[a-z][a-z0-9_-]*$/`.
-- Each option needs `default` + `allowed`. `default` must be a member of `allowed`.
-- `allowed` values are `boolean` or `string`. No integers, no lists.
-- `${options.<name>}` tokens in `build.configure` / `build.buildArgs` are expanded at source-build time. Booleans expand to `ON`/`OFF`; strings expand verbatim. A typo (`${options.fips}` with no `fips` declared) is a hard error — it will not silently reach CMake.
-
-**Consumer side — override per dependency:**
-
-```json
-{
-  "dependencies": {
-    "zlib": {
-      "version": "1.3.0.0",
-      "options": { "minizip": false }
-    }
-  }
-}
-```
-
-**Consumer side — override via CLI (precedence: CLI > wyvrn.json > recipe defaults):**
-
-```bash
-wyvrnpm install -o zlib:minizip=false -o zlib:shared=true
-wyvrnpm publish -o zlib:minizip=false          # publishing a specific variant
-```
-
-Option overrides are validated against the recipe's `allowed` list at resolve time; unknown option names surface a "did you mean?" suggestion.
-
-**What happens on the registry.** Options fold into `profileHash`, so `zlib@1.3.0.0` with `minizip=true` and `zlib@1.3.0.0` with `minizip=false` are two distinct artefacts at two different URLs — same version, different hashes. `wyvrnpm show zlib@1.3.0.0` lists all published variants and prints each one's resolved options.
-
-**Backward compatibility.** Packages that do not declare an `options` block hash byte-identically to how they did before options existed. No registry migration required.
-
-### Source-build recipe (`build`)
-
-A library package may include an optional `build` section that tells `wyvrnpm install --build=missing` how to rebuild it from source. Only `system: "cmake"` is supported today.
-
-```json
-{
-  "name": "zlib",
-  "version": "1.3.0.0",
-  "kind": "StaticLib",
-  "build": {
-    "system":       "cmake",
-    "generator":    ["Ninja", "Visual Studio 17 2022"],
-    "configs":      ["Release", "Debug"],
-    "configure":    ["-DZLIB_BUILD_EXAMPLES=OFF"],
-    "buildArgs":    ["--parallel"],
-    "installDir":   "install",
-    "sourceSubdir": "."
-  }
-}
-```
-
-| Field | Default | Description |
-|---|---|---|
-| `system` | `cmake` | Build system. Only `cmake` is supported. |
-| `generator` | *(CMake default)* | Single generator (`"Ninja"`) or an array tried in order — first available wins. |
-| `configs` | `["Debug","Release","RelWithDebInfo","MinSizeRel"]` | CMake configurations to build and install. |
-| `configure` | `[]` | Extra args appended to `cmake` at configure time. |
-| `buildArgs` | `[]` | Extra args appended to `cmake --build`. |
-| `installDir` | `install` | Install prefix relative to the binary dir. |
-| `sourceSubdir` | `.` | Where `CMakeLists.txt` lives relative to the clone root. |
-| `requiredTools` | `[]` | Tools that must be on `PATH` before the build starts (fail-fast check). |
-
-On Windows with MSVC and a non-Visual-Studio generator (Ninja, Make), `vcvarsall.bat` is auto-activated for the spawned CMake process — no need to launch from a Developer Prompt.
-
----
-
-## Build-time configuration (`conf`)
-
-`conf` is wyvrnpm's channel for **non-ABI** build-time knobs — CMake cache variables, feature toggles that change `add_subdirectory()` but not the public binary, and (in future phases) other build-tool settings. It is a deliberate sibling of `options`, with the opposite hashing property:
-
-| | `options` (F1) | `conf` (this section) |
-|---|---|---|
-| Folds into `profileHash`? | Yes — every combination is a distinct registry artefact. | **No.** Informational only; two builds with different `conf` still share the same `profileHash`. |
-| Typical use | `shared`/`minizip`/`fips` — things that genuinely change the binary. | `CHROMA_ENABLE_TEST`, `BUILD_DOCS`, `CMAKE_EXPORT_COMPILE_COMMANDS` — things that don't. |
-| Consumer can override? | Yes (per-dep `options` in `wyvrn.json` or `-o pkg:name=val` on CLI). | Yes (recipe → named-profile `conf` → `wyvrn.local.json` → `--conf`, in that precedence). |
-
-Phase 1 (2.6.0+) supports a single namespace: `cmake.cache.<VAR>`. It flows into the generated `CMakePresets.json`'s `cacheVariables`.
-
-### The four layers
-
-```
-  highest   CLI     --conf cmake.cache.X=ON
-    │       ─────
-    │    local     wyvrn.local.json              (per-developer, gitignored)
-    │       ─────
-    │  profile    named-profile JSON.conf       (team-shared, checked-in)
-    │       ─────
-    │   recipe    wyvrn.json.conf               (author defaults)
-    ▼       ─────
-  lowest    (nothing — key absent)
-```
-
-**Per-leaf override, not per-branch replace.** A CLI `--conf cmake.cache.FOO=ON` on top of a recipe setting `BAR=OFF` yields both keys — it does not discard `BAR`. Any omitted layer is equivalent to an empty map at that position — a project with no `wyvrn.local.json` and no profile `conf` merges recipe + CLI exactly as phase 1.
-
-### Recipe-level defaults
-
-Authors can declare defaults on their package:
-
-```json
-{
-  "name": "ChromaSDK",
-  "version": "2.5.0.0",
-  "conf": {
-    "cmake": {
-      "cache": {
-        "CHROMA_ENABLE_TEST":     "OFF",
-        "CHROMA_ENABLE_EXAMPLES": "OFF",
-        "CHROMA_LOG_LEVEL":       "WARNING"
-      }
-    }
-  }
-}
-```
-
-`true`/`false` in the JSON are normalised to CMake `"ON"`/`"OFF"`; numbers are stringified; strings pass through.
-
-### Per-developer overlay — `wyvrn.local.json`
-
-Drop a `wyvrn.local.json` next to `wyvrn.json` for per-machine overrides. `wyvrnpm init` scaffolds a `.gitignore` entry for new projects; existing projects get a one-line nudge on `wyvrnpm install` when the file is present but not ignored.
-
-```json
-{
-  "conf": {
-    "cmake": {
-      "cache": {
-        "CHROMA_ENABLE_TEST":            "ON",
-        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
-      }
-    }
-  }
-}
-```
-
-Phase 1 accepts **only** the top-level key `conf` in this file — `dependencies` / `options` / anything else is a hard error, forecloseing the silent-inert footgun where a user writes `{ "dependencies": {...} }` expecting local dep overrides. Phase 2 will widen the allow-list.
-
-### Team-shared overlay — named-profile `conf` (phase 2, 2.7.0+)
-
-When every developer on a team would end up with the same `wyvrn.local.json`, check that shared policy into the named profile instead. A saved profile (e.g. `%LOCALAPPDATA%\wyvrnpm\profiles\team-default.json`) may carry an optional top-level `conf` block alongside its `[settings]`:
-
-```json
-{
-  "os": "Windows",
-  "arch": "x86_64",
-  "compiler": "msvc",
-  "compiler.version": "193",
-  "compiler.cppstd": "20",
-  "compiler.runtime": "dynamic",
-  "conf": {
-    "cmake": {
-      "cache": {
-        "CHROMA_ENABLE_SANITIZERS":    "OFF",
-        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
-      }
-    }
-  }
-}
-```
-
-Edit via the `configure profile set` convenience (repeatable, same `KEY=VAL` / bare-`KEY` / `KEY=` syntax as the other CLI sinks):
-
-```bash
-wyvrnpm configure profile set --name team-default --conf cmake.cache.CMAKE_EXPORT_COMPILE_COMMANDS=ON
-wyvrnpm configure profile set --name team-default --conf cmake.cache.LEGACY_FLAG=     # clears it
-```
-
-Profile `conf` layers **between recipe and local**: a project's `wyvrn.local.json` (the individual override) still wins over team defaults, and CLI `--conf` still wins over everything. The distinction Conan makes between the `[conf]` block in a profile and the `-c` CLI flag maps directly onto this precedence.
-
-Profile `conf` is **non-ABI**: adding or changing keys inside it does NOT shift `profileHash`, so switching a team policy between `ENABLE_SANITIZERS=ON` and `=OFF` does not invalidate already-downloaded artefacts. The invariant is locked in by `tests/profile-hash.test.js`.
-
-Auto-detected profiles (when no on-disk profile file exists) never inject a `conf` layer — detection is about `[settings]` only.
-
-### CLI — ad-hoc, one invocation
-
-```bash
-# Single toggle
-wyvrnpm build --conf cmake.cache.CHROMA_ENABLE_TEST=ON
-
-# Repeatable
-wyvrnpm build \
-  --conf cmake.cache.CHROMA_ENABLE_TEST=ON \
-  --conf cmake.cache.BUILD_DOCS=OFF
-
-# Bare KEY is sugar for KEY=ON (CMake -D convention)
-wyvrnpm build --conf cmake.cache.CHROMA_ENABLE_TEST
-
-# KEY= (empty RHS) clears a value inherited from a lower layer
-wyvrnpm build --conf cmake.cache.CHROMA_ENABLE_TEST=
-
-# Also honoured on install and publish (publish records it as
-# `publishedConf` on the uploaded manifest — informational metadata
-# that `wyvrnpm show` surfaces).
-wyvrnpm install --conf cmake.cache.CHROMA_ENABLE_TEST=ON
-wyvrnpm publish --conf cmake.cache.BUILD_DOCS=OFF
-```
-
-`--conf` on `wyvrnpm build` passes through to `cmake --preset` as `-D` / `-U` overrides **for that invocation only** — it does not regenerate `CMakePresets.json`. Persistent per-machine overrides belong in `wyvrn.local.json`; `wyvrnpm install` regenerates the preset deterministically with the overlay applied.
-
-### Lockfile semantics
-
-`wyvrn.lock` gains an informational `effectiveConf` block after each install:
-
-```json
-{
-  "wyvrnVersion": 2,
-  "profileHash":  "a1b2c3d4e5f60718",
-  "effectiveConf": {
-    "cmake": { "cache": { "CHROMA_ENABLE_TEST": "ON" } }
-  },
-  "packages": { ... }
-}
-```
-
-This is diagnostic only — changing `conf` between installs shows up as a lockfile diff but never causes a relock or version change. Conf drift is a legitimate review signal, not an error.
-
-### Source-build boundary
-
-When `--build=missing` or `--build=always` source-builds a dependency, **only that dep's own recipe `conf`** flows into its CMake invocation. The root project's merged conf (including `wyvrn.local.json`, named-profile `conf`, and CLI `--conf`) never reaches a dep's source-build. This preserves cross-consumer reproducibility — two developers source-building the same `(name, version, profileHash)` produce the same binary regardless of their local overlays or team profile, which is load-bearing for `--upload-built`.
-
-### Why this isn't `build.configure`
-
-Existing authors using `build.configure: ["-DFOO=ON", "-DBAR=OFF"]` keep working unchanged. But `build.configure` has two weaknesses `conf` fixes:
-
-1. **All-or-nothing.** A consumer can't disable one flag without overriding the whole array.
-2. **Opaque strings.** `"-DFOO=ON"` is parsed at configure time, not at manifest load.
-
-Recipe authors writing new packages should prefer `conf.cmake.cache.FOO=ON` for cache variables and keep `build.configure` for non-cache args like `-G`, `-T`, or `-A`. Setting the same KEY in both `build.configure` (`-DKEY=...`) AND `conf.cmake.cache.KEY` is a recipe-normalise error — pick one route.
-
----
-
-## Compatibility Rules
-
-Publishers declare an optional `compatibility` block in a package's `wyvrn.json`. It tells wyvrnpm which profile fields must match the consumer's profile exactly, and which may legitimately differ without breaking ABI. When no exact `profileHash` match exists on the registry, `install` evaluates this block against every published build for the requested `(name, version)` and picks the best compatible candidate.
-
-### Block format
-
-Each field maps to a mode — either as a string shorthand or an object:
-
-```json
-{
-  "name": "zlib",
-  "version": "1.3.0.0",
-  "compatibility": {
-    "compiler.cppstd":  "lte",
-    "compiler.runtime": "exact",
-    "compiler.version": "exact-or-newer"
-  }
-}
-```
-
-Object form is accepted too (`{ "mode": "lte" }`) and leaves room for future per-field options.
-
-### Supported modes
-
-| Mode | Meaning |
-|---|---|
-| `exact` | Package and consumer values must be equal. |
-| `any` | Field is ignored for compatibility purposes. |
-| `lte` | Package value ≤ consumer value — e.g. a `cppstd=20` package is usable by a `cppstd=23` consumer. |
-| `gte` | Package value ≥ consumer value (symmetry; rarely useful). |
-| `exact-or-newer` | Same as `lte` at MVP — kept as a distinct name because it reads naturally for compiler-version fields. |
-
-**Defaults:**
-
-- Any field not listed is treated as `exact`.
-- `os` and `arch` are **always `exact`** regardless of what the block says. Cross-OS / cross-arch binaries are never ABI-compatible.
-
-### Where to author it
-
-The block lives in the **source** `wyvrn.json` (the one you commit). It is read at publish time and written into the uploaded manifest. If the source `wyvrn.json` has no `compatibility` block, `wyvrnpm publish` injects a conservative default (all fields `exact`) so existing packages behave strict-by-default.
-
-Consumers never author compatibility — it is a property of the published package.
-
-### Tiebreaker
-
-When multiple published builds satisfy the consumer's profile, the winner is picked deterministically:
-
-1. Prefer the candidate whose `compiler` matches the consumer's.
-2. Prefer the highest numeric `compiler.version`.
-3. Prefer the candidate whose `compiler.runtime` matches the consumer's.
-4. Fall back to the lexicographically earliest `profileHash`.
-
-The chosen candidate is logged along with a per-field summary (e.g. `compiler.cppstd 20→23 (lte), compiler.runtime=dynamic`).
-
----
-
-## Source Builds
-
-`wyvrnpm install --build=missing` clones a package's source at its published `gitSha` and builds it locally when no prebuilt binary matches (exact or compatible) the consumer's profile. This is the Conan-2.0 `--build=missing` parity feature.
-
-### When it fires
-
-1. You run `wyvrnpm install --build=missing`.
-2. For each dependency, wyvrnpm tries `v2 exact → v2 compat` first.
-3. If neither hits, it looks up `gitRepo` + `gitSha` from **any** existing build of the same `(name, version)` on the registry (they are equal across profiles for a given version).
-4. It clones, resolves the package's own transitive deps, invokes CMake through the shared toolchain generator, zips the install dir, and treats the result as a v2 download.
-
-If the package has no prior publish on the registry at all, there is no `gitSha` to clone — source-build fails fast with a clear error. Source-builds cascade transitively: if package A needs source-build and depends on package B which also needs source-build, both are built.
-
-### Authoring the `build` recipe
-
-Libraries that want to be source-buildable declare a `build` section in their own `wyvrn.json`. See [Project Manifest §Source-build recipe](#source-build-recipe-build) for the field list. Only `system: "cmake"` is supported today.
-
-### Generator fallback
-
-`build.generator` accepts either a string or an array:
-
-| Form | Behaviour |
-|---|---|
-| `"Ninja"` | Strict — fails if Ninja is not available. |
-| `["Ninja", "Visual Studio 17 2022"]` | Tried in order — first available wins. Unknown entries are trusted (CMake decides at configure time). |
-| *(omitted)* | Uses CMake's platform default. |
-
-### MSVC environment auto-activation (Windows)
-
-On Windows, when **all** of the following hold:
-
-- `profile.compiler === "msvc"`
-- The chosen generator is **not** a Visual Studio generator (e.g. Ninja, Make)
-- `cl.exe` is not on `PATH`
-
-…wyvrnpm locates Visual Studio via `vswhere.exe`, runs `vcvarsall.bat <arch>` in a sub-shell, captures the resulting environment, and uses it for the CMake spawn. You do not need to launch from a Developer Prompt.
-
-Arch mapping follows the active profile:
-
-| `profile.arch` | `vcvarsall` arg |
-|---|---|
-| `x86_64` | `x64` |
-| `x86` | `x86` |
-| `armv8` | `arm64` |
-| `armv7` | `arm` |
-
-VS generators skip this path entirely — MSBuild resolves MSVC itself.
-
-### Cache
-
-Source builds are cached machine-wide, keyed by `(name, version, profileHash)`:
-
-| Platform | Path |
-|---|---|
-| Windows | `%LOCALAPPDATA%\wyvrnpm\bc\{name}-{version}-{profileHash}\` |
-| Linux / macOS | `~/.cache/wyvrnpm/bc/{name}-{version}-{profileHash}/` |
-
-Re-running `install --build=missing` with the same inputs short-circuits to the cached artefact. The cache root is deliberately shallow (`bc/`, not `build-cache/`) to keep nested CMake paths under Windows' 260-char limit.
-
-`--build=always` (2.5.0+) ignores every registry-binary path — exact-match, compat-match, and any already-extracted `wyvrn_internal/{name}/` — and forces a source-build for every dep. Useful for debugging whether a registry binary differs from what the current source tree would produce, or for reproducibility verification. The build-cache short-circuit still applies: re-running `--build=always` with unchanged inputs completes in seconds.
-
-Clone behaviour is tri-tier:
-
-1. **Shallow-SHA fetch** (`git fetch origin <sha> --depth=1`) — fastest; works when the git server allows it.
-2. **Full fetch** — falls back to a full `git clone --tags` when the server rejects shallow-SHA (older Bitbucket installs disable `uploadpack.allowReachableSHA1InWant`).
-3. **Rebuild from scratch** — if the cached clone is broken, wipes and retries.
-
-After every clone/fetch, wyvrnpm runs `git cat-file -e <sha>^{commit}` to verify the SHA is actually reachable. If it is not, the error points at the likely cause: the publisher forgot to push before running `wyvrnpm publish`.
-
-### Publish-time guard
-
-To catch the unpushed-commit case before consumers hit it, `wyvrnpm publish` checks whether the current `HEAD` is reachable from any remote branch or tag and warns if it is not:
-
-```
-[wyvrn] warn: git SHA abc1234 is not on origin — source-build consumers will fail until pushed
-```
-
-The warning does **not** block publishing.
-
-### Header-only libraries
-
-`kind: "HeaderOnlyLib"` packages still need a `build` section and a CMake `install()` rule that copies headers. There is no fast-path that zips the source tree directly — consumers get exactly what the `install()` step produces, same as any other kind.
-
-### Clearing the cache
-
-```bash
-# Remove the project-local cache (wyvrn_internal/ + wyvrn.lock)
-wyvrnpm clean
-
-# Also wipe the machine-wide source-build cache
-wyvrnpm clean --build-cache
-```
-
-### Credentials for private repos
-
-wyvrnpm uses your ambient git configuration (SSH keys, credential helpers, Windows Credential Manager). It does not manage git credentials itself. If `git clone <gitRepo>` works from your shell, source-build works.
-
-### Upload back to the registry (`--upload-built`)
-
-`--build=missing` warms *your* cache. `--build=missing --upload-built` warms the *team's* cache: after a successful source-build, the freshly-zipped artefact is pushed back to the registry under the consumer's `profileHash`, so the next teammate on the same profile gets a direct v2 download.
-
-```bash
-# Build missing artefacts locally AND publish them back under your profile.
-wyvrnpm install --build=missing --upload-built
-
-# Override the upload destination (URL or configured publish-source name).
-wyvrnpm install --build=missing --upload-built --upload-source team-s3
-
-# Upload auth is resolved in order: CLI flag → named-source config → first configured publish source.
-wyvrnpm install --build=missing --upload-built --aws-profile my-sso
-wyvrnpm install --build=missing --upload-built --token-env WYVRN_HTTP_TOKEN
-```
-
-Semantics:
-
-- **Opt-in.** Nothing uploads unless `--upload-built` is passed. Requires `--build=missing`.
-- **Skip if exists.** If `(name, version, profileHash)` already lives on the upload source, the upload is a silent no-op. A consumer cannot overwrite an existing artefact; use `wyvrnpm publish --force` from the source repo for that.
-- **`latest.json` is untouched.** A consumer upload is a new `profileHash` of an existing version, not a new version release.
-- **Upload failures never break the install.** The consumer already has a working `wyvrn_internal/` on disk — a broken upload is logged as a warning and the install continues.
-- **Provenance.** Uploaded manifests carry a small `uploadedBy` block so maintainers can tell consumer builds apart from author publishes:
-
-  ```json
-  {
-    "uploadedBy": {
-      "kind":           "source-build",
-      "profileHash":    "a1b2c3d4e5f60718",
-      "builtFromGit":   "https://github.com/madler/zlib",
-      "builtFromSha":   "abcdef01...",
-      "uploadedAt":     "2026-04-21T12:34:56.789Z",
-      "wyvrnpmVersion": "2.1.0"
-    }
-  }
-  ```
-
-  Absence of `uploadedBy` means the artefact was published by the author via `wyvrnpm publish`.
-
-At the end of an install with `--upload-built`, a one-line summary is printed:
-
-```
-[wyvrn] upload-built summary: 2 artefacts uploaded, 1 skipped (already existed), 0 failed
-```
-
-**Trust model.** Registry write auth is the gate — only consumers with credentials for the upload destination can upload at all. The same `v2Publish` path is used as `wyvrnpm publish`, so the resulting artefact is byte-identical in layout. SHA256 verification on the download side protects against in-transit tampering. Uploading deliberately opts into "your machine's build of this package is trusted by everyone else on this profile" — use CI with clean toolchains rather than developer workstations if you care about reproducibility.
-
-#### Auditing consumer uploads (`wyvrnpm show`)
-
-Maintainers can list every build of a package and tell author-published artefacts apart from consumer uploads:
-
-```bash
-wyvrnpm show zlib                      # all versions + their profile hashes
-wyvrnpm show zlib@1.3.0.0              # every profile for that version, with origin + builtFromSha
-wyvrnpm show zlib@1.3.0.0@a1b2c3d4...  # one specific build, full metadata
-```
-
-With a version specified, `show` fetches each build's `wyvrn.json` and reports `author publish` or `consumer upload (source-build)` alongside the relevant `uploadedBy` fields. Sources default to the configured install sources; override with `--source <url>`.
-
-#### Forgetting uploads (`clean --uploaded-built`)
-
-Each successful upload writes a `.uploaded-to.json` sidecar alongside the cached artefact under `%LOCALAPPDATA%\wyvrnpm\bc\{name}-{version}-{profileHash}\`. It records destination, timestamp, and SHA — purely informational, nothing reads it during install.
-
-To wipe just those local records (no effect on the registry, the artefact zips, or `wyvrn_internal/`):
-
-```bash
-wyvrnpm clean --uploaded-built
-```
-
-This is a privacy / local-audit cleanup knob — `clean --build-cache` already removes sidecars as a side effect of nuking the cache.
-
----
-
-## Lock File (wyvrn.lock)
-
-The v2 lock file records the full build profile alongside the resolved packages:
-
-```json
-{
-  "wyvrnVersion": 2,
-  "generatedAt": "2025-01-01T00:00:00.000Z",
-  "platform": "win_x64",
-  "profileName": "default",
-  "profile": {
-    "os": "Windows",
-    "arch": "x86_64",
-    "compiler": "msvc",
-    "compiler.version": "193",
-    "compiler.cppstd": "20",
-    "compiler.runtime": "dynamic"
-  },
-  "profileHash": "a1b2c3d4e5f60718",
-  "packages": {
-    "OpenSSL": {
-      "version": "3.0.0.0",
-      "profileHash": "a1b2c3d4e5f60718",
-      "contentSha256": "abc123...",
-      "gitSha": "def456..."
-    }
-  }
-}
-```
-
-Locked versions always take priority over transitive requests. A warning is printed for every version conflict detected.
-
----
-
-## CMake Integration
-
-`wyvrnpm install` emits a ready-to-use CMake toolchain alongside the downloaded packages. Most projects only need to run:
-
-```bash
-wyvrnpm install
-wyvrnpm build
-```
-
-…which is equivalent to:
-
-```bash
-cmake --preset wyvrn-default
-cmake --build build/wyvrn-default --config Release
-```
-
-**Generated files (inside the project)**
-
-| Path | Purpose |
-|---|---|
-| `wyvrn_internal/wyvrn_toolchain.cmake` | Toolchain file — sets `CMAKE_PREFIX_PATH`, compiler/runtime, and standards from the active profile. Include via the preset or `-DCMAKE_TOOLCHAIN_FILE=…`. |
-| `wyvrn_internal/wyvrn_deps.cmake` | Include **after** `project()` (e.g. `include(${CMAKE_BINARY_DIR}/../wyvrn_internal/wyvrn_deps.cmake)`). Wires `find_package()` calls and defines `wyvrnpm_finalize_targets(<tgt>…)` for runtime DLL copy next to your executable. |
-| `wyvrn_internal/wyvrn_profile.json` | Snapshot of the profile the toolchain was generated against. |
-| `CMakePresets.json` / `CMakeUserPresets.json` | `wyvrn-<profile>` configure preset. Regenerating preserves other profiles' presets. |
-
-**Bundled CMake utilities** (shipped in the npm tarball under `cmake/`) are auto-included by `wyvrn_toolchain.cmake`:
-
-| File | Provides |
-|---|---|
-| `cpp.cmake` | C++ standard defaults (guarded — toolchain wins). |
-| `variables.cmake` | Platform detection (`WYVRN_PLATFORM_WIN`, …) and compiler flags. |
-| `options.cmake` | Feature toggles (`WYVRN_ENABLE_LOG`, …). |
-| `functions.cmake` | `SETUP_LIBRARY` / `SETUP_EXE` plus HAL source-collection helpers. |
-| `macros.cmake` | `WYVRN_INSTALL_MODULE`, `WYVRN_CONFIGURE_VERSION_HEADER`. |
-
-**Minimal `CMakeLists.txt`:**
-
-```cmake
-cmake_minimum_required(VERSION 3.21)
-project(my-app CXX)
-
-include(${CMAKE_SOURCE_DIR}/wyvrn_internal/wyvrn_deps.cmake)
-
-add_executable(my-app src/main.cpp)
-target_link_libraries(my-app PRIVATE OpenSSL::SSL zlib::zlib)
-
-wyvrnpm_finalize_targets(my-app)   # copies runtime DLLs next to the .exe
-```
-
----
-
-## Installing Build Artifacts (`wyvrnpm build --install`)
-
-`wyvrnpm build --install` runs `cmake --install <binaryDir>` after a successful build, invoking every `install()` rule in your `CMakeLists.txt`. This is the step that produces a redistributable layout (headers + libs + runtime files in a tidy tree) rather than the raw CMake build directory.
-
-### Typical use
-
-```bash
-# Configure, build, and install to the default prefix (baked in at configure time)
-wyvrnpm build --install
-
-# Override the install prefix without reconfiguring
-wyvrnpm build --install --install-prefix C:\out\stage
-
-# Install a specific config
-wyvrnpm build --install --config Debug
-
-# Install multiple configs in one invocation — configure runs once,
-# build + install loops per config. Before 2.9.0 this required two
-# separate `wyvrnpm build --install ...` invocations.
-wyvrnpm build --install --config Debug,Release
-
-# Install every config declared in the recipe's build.configs
-# (or all four canonical configs when no recipe is present).
-wyvrnpm build --install --all-configs
-```
-
-### What it does, in order
-
-1. **Staleness check** — if `wyvrn_internal/wyvrn_toolchain.cmake` is missing or `wyvrn.lock` is newer than it, auto-runs `wyvrnpm install` first. Disable with `--no-auto-install`.
-2. **Optional clean** — `--clean` wipes the build directory before configuring.
-3. **Configure** — `cmake --preset wyvrn-<profile>` (or the value of `--preset`).
-4. **Build** — `cmake --build <binaryDir> --config <config>`.
-5. **Install** — `cmake --install <binaryDir> --config <config> [--prefix <install-prefix>]`.
-
-### `--auto-install` vs `--install`
-
-These two flags are easy to confuse — they control unrelated things:
-
-| Flag | What it does | When it runs |
-|---|---|---|
-| `--auto-install` *(default: on)* | Runs `wyvrnpm install` if the toolchain is stale. Disable with `--no-auto-install`. | **Before** configure. |
-| `--install` *(default: off)* | Runs `cmake --install` after a successful build. | **After** build. |
-
-### `--install-prefix`
-
-CMake bakes `CMAKE_INSTALL_PREFIX` into the build cache at configure time. Passing `--install-prefix` at install time uses `cmake --install --prefix <path>` to override the baked value **without** re-running configure — cheaper than a full reconfigure when you only want to stage to a different location.
-
-If you omit `--install-prefix`, the baked default is used. The baked default comes from the generated preset, typically under `build/wyvrn-<profile>/install`.
-
-### Permissions
-
-Installing to a system path (`/usr/local`, `C:\Program Files`) requires the usual elevated permissions — wyvrnpm does not auto-elevate. For staging or packaging, point `--install-prefix` at a writable user directory instead.
-
----
-
-## Version Conflict Resolution
-
-When the dependency graph requires the same package at multiple versions, the highest version wins. If a `wyvrn.lock` exists, locked versions always take priority over any conflicting transitive request. A warning is printed for every conflict detected.
-
----
-
-## Ignoring generated files
-
-Add the following to your `.gitignore`:
-
-```
-wyvrn_internal/
-wyvrn.lock
-*.zip
-```
+# wyvrnpm
+
+A simple, private C++ package manager that works with any static file hosting provider — Amazon S3, a plain HTTP/HTTPS server, a local directory, or an SMB/UNC network share.
+
+There is no central registry. You control where packages are hosted.
+
+> **README version: 2.12.3** — Highlights since 2.8.3: profile's `compiler.cppstd` is now authoritative for the toolchain — `CMAKE_CXX_STANDARD` is set unconditionally before `project()` and `cpp.cmake` no longer touches it post-`project()`, so a `-DCMAKE_CXX_STANDARD=23` on the cmake CLI cannot defeat a `cppstd=20` profile; `wyvrnpm install` exits non-zero on partial failure (sha256-mismatch, extract-failed, no-exact-match, source-build-failed, not-found) and prints a per-dep failure summary instead of misreporting "Done — N installed"; streaming publish via `archiver` (handles >2 GiB artefacts that `adm-zip` choked on — e.g. gRPC's `RelWithDebInfo` static libs); `--build-dir <path>` + `wyvrn.local.json:binaryDirRoot` to sidestep `build/` case-insensitive-FS collisions on repos with a Bazel/Buck `BUILD` file at the root (gRPC, …); `wyvrnpm version` to read / set / partially update the top-level `version` field from CI pipelines (`wyvrnpm version --build "$BUILD_ID"`); `wyvrnpm bootstrap <git-url>` to scaffold a first-draft `wyvrn.json` for OSS C++ libraries (fmt, spdlog, zlib, …) with cookbook-driven defaults; `wyvrnpm publish --dry-run` (npm-style preview of the upload plan, plus `wouldOverwrite` flag in `--format json`); `wyvrnpm build --config Debug,Release` / `--all-configs` to build multiple configurations from a single configure; resolver hardened against the CloudFront brotli-vs-identity cache split (resolved a class of bugs where `show` listed a freshly-published version that `install` claimed didn't exist). Full list in `claude/EVALUATION.md`.
+
+---
+
+## Install
+
+```bash
+npm install -g wyvrnpm
+```
+
+Requires Node.js >= 18.
+
+For S3 publishing, also install the AWS SDK:
+
+```bash
+npm install -g @aws-sdk/client-s3 @aws-sdk/credential-providers
+```
+
+---
+
+## Quick Start
+
+```bash
+# 1. Initialise a manifest in your project
+wyvrnpm init
+
+# 2. Configure your package sources once
+wyvrnpm configure add-source --kind install --name corp-s3 --url s3://my-bucket/packages --profile my-sso
+wyvrnpm configure add-source --kind publish --name default  --url s3://my-bucket/packages --profile my-sso
+
+# 3. Detect and save your build environment as the default profile
+wyvrnpm configure profile detect
+
+# 4. Add dependencies (resolves latest from your configured sources)
+wyvrnpm add zlib fmt@^10.0.0
+
+# 5. Install dependencies (resolved against your build profile)
+wyvrnpm install
+
+# 6. Configure and build via the generated CMake preset
+wyvrnpm build
+
+# 7. Publish your package (uses the active profile automatically)
+wyvrnpm publish
+
+# 8. (Optional) Link local packages for development
+cd ../my-local-lib && wyvrnpm link
+cd ../my-app && wyvrnpm link my-local-lib
+```
+
+---
+
+## Build Profiles
+
+v2 introduces **build profiles** — named snapshots of your build environment (OS, architecture, compiler, C++ standard, runtime linkage). Each published binary is tagged with a profile hash so installs can resolve the correct prebuilt binary automatically.
+
+Profile fields mirror Conan 2.0 settings:
+
+| Field | Example values |
+|---|---|
+| `os` | `Windows` `Linux` `Macos` |
+| `arch` | `x86_64` `x86` `armv8` |
+| `compiler` | `msvc` `gcc` `clang` `apple-clang` |
+| `compiler.version` | `193` `13` `17` |
+| `compiler.cppstd` | `14` `17` `20` `23` |
+| `compiler.runtime` | `dynamic` `static` *(MSVC only)* |
+
+Profiles are stored in the platform config directory:
+
+| Platform | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\wyvrnpm\profiles\` |
+| Linux / macOS | `~/.config/wyvrnpm/profiles/` |
+
+### Typical profile workflow
+
+```bash
+# Auto-detect your current environment and save it as "default"
+wyvrnpm configure profile detect
+
+# Or save under a specific name (e.g. for a release build with static runtime)
+wyvrnpm configure profile detect --name release
+wyvrnpm configure profile set --name release --runtime static
+
+# List all saved profiles (* marks the default)
+wyvrnpm configure profile list
+
+# Switch the default profile
+wyvrnpm configure profile set-default release
+```
+
+Once a default profile is saved, `install` and `publish` use it automatically — no flags required.
+
+### Profile inheritance — `extends` (2.8.0+)
+
+Teams often end up with a small fleet of near-duplicate profiles (`windows-msvc-debug`, `windows-msvc-release`, `windows-msvc-x86`, …) that drift over time. A profile can inherit from another via `extends`:
+
+```json
+{
+  "extends": "windows-msvc-base",
+  "compiler.cppstd": "23"
+}
+```
+
+Or from multiple parents (later entries override earlier):
+
+```json
+{
+  "extends": ["windows-base", "team-defaults"],
+  "compiler.runtime": "static"
+}
+```
+
+Rules:
+
+- `[settings]` fields merge per-key — child wins.
+- The `conf` block (if present) merges per-leaf — child overrides single keys without dropping siblings.
+- Overlay value `null` explicitly unsets a parent field (Conan's `None` semantics).
+- Inheritance cycles are detected and fail with the full trail (`alpha → beta → alpha`).
+- Missing parent names fail fast — no silent drop.
+- `extends` itself is stripped from the resolved profile and is **not** folded into `profileHash`, so `{ "extends": "base" }` with no overrides hashes byte-identically to `base`.
+
+`wyvrnpm configure profile show <name>` prints the raw `extends:` chain alongside the resolved `[settings]` so you can inspect inheritance without grepping JSON.
+
+---
+
+## Commands
+
+### `wyvrnpm init`
+
+Creates a `wyvrn.json` manifest in the current directory.
+
+```bash
+wyvrnpm init
+wyvrnpm init --root ./my-project
+```
+
+---
+
+### `wyvrnpm bootstrap`
+
+Scaffolds a first-draft `wyvrn.json` for an open-source C++ library so it can be packaged into your wyvrnpm registry with a single review pass instead of hand-writing a manifest from scratch. Clones the upstream git repo, detects `name` / `version` / `kind` from the checkout, applies known-library CMake flag hints (skip tests, skip examples, flip install gates), and prints a TODO report for everything a machine can't decide for you.
+
+Designed for batch-converting a list of forked upstreams (fmt, spdlog, zlib, Catch2, etc.) into your private registry.
+
+```bash
+# Typical single-repo conversion
+wyvrnpm bootstrap https://github.com/fmtlib/fmt.git --dest ./pkgs/fmt
+cd ./pkgs/fmt                           # review wyvrn.json, settle TODOs
+wyvrnpm install
+wyvrnpm build --install --all-configs
+wyvrnpm publish --source team-s3
+
+# Override the derived name / version / kind
+wyvrnpm bootstrap https://github.com/nlohmann/json.git \
+    --dest ./pkgs/nlohmann-json \
+    --name nlohmann-json \
+    --kind HeaderOnlyLib
+
+# Work on a directory you already cloned
+wyvrnpm bootstrap --no-clone --dest ./pkgs/fmt --force
+
+# Preview without writing — TODO report only
+wyvrnpm bootstrap https://github.com/google/re2.git --dest /tmp/re2 --dry-run
+
+# Batch driver — one shell loop, no wyvrnpm subcommand needed
+while read url; do
+  wyvrnpm bootstrap "$url" --dest "./pkgs/$(basename "$url" .git)" --force
+done < urls.txt
+# then review, build, and publish each in a loop of your own
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `<url>` positional | *(required)* | Upstream git URL. Accepts HTTPS or SSH form. |
+| `--dest <dir>` | `basename(url)` | Destination directory for the clone. |
+| `--ref <ref>` | *(remote HEAD)* | Clone at a specific branch / tag / SHA. |
+| `--name` | *(from URL)* | Override the derived package name. |
+| `--pkg-version` | *(nearest git tag)* | Override the version. Named oddly so yargs doesn't confuse it with the built-in `--version`. |
+| `--kind` | *(auto-detect)* | Force `ConsoleApp` / `StaticLib` / `DynamicLib` / `HeaderOnlyLib` / etc. |
+| `--description` | *(TODO placeholder)* | One-line description written into `wyvrn.json`. |
+| `--no-clone` | `false` | Skip the clone step; operate on an already-populated `--dest`. |
+| `--shallow` | `false` | `--depth 1` clone. Faster, but git tag detection degrades — pair with `--pkg-version` when using this. |
+| `--dry-run` | `false` | Print the proposed manifest + TODOs; don't write `wyvrn.json`. |
+| `--force` | `false` | Overwrite an existing destination and/or `wyvrn.json`. |
+| `--format` | `text` | Output format: `text` (human) or `json` (CI — one object on stdout). |
+
+The cookbook of per-library hints lives in [src/bootstrap/cookbook.js](src/bootstrap/cookbook.js). Current coverage is ~30 popular libraries (fmt, spdlog, nlohmann/json, yaml-cpp, zlib, Catch2, lz4, brotli, hiredis, redis-plus-plus, GLM, SQLiteCpp, re2, …). Adding a new entry is a two-line change — submit a PR.
+
+The patterns bootstrap detects (header-only with INTERFACE target, standard CMake static lib, CMake with wyvrnpm dep, ABI-option'd lib, non-CMake upstream) are catalogued in the bundled Agent Skill at [claude/skills/wyvrnpm/references/oss-conversion-patterns.md](claude/skills/wyvrnpm/references/oss-conversion-patterns.md) — Claude reads it when you ask "how do I convert X to a wyvrnpm package?".
+
+---
+
+### `wyvrnpm add`
+
+Adds one or more dependencies to `wyvrn.json` without downloading them. Useful when you know the package name but not the latest version.
+
+- **Bare name** — resolves `latest.json` from your configured install sources and writes `"^<latest>"` (caret range, major-pinned).
+- **`name@<version>`** — writes the given string verbatim. Accepts exact pins (`1.2.3.4`), caret/tilde ranges (`^1.2.3.4`, `~1.2.3.4`), and explicit comparators (`>=1.80.0 <2.0.0`).
+
+If the dependency is already listed, it is replaced. When the prior entry was an object (`{ version, settings, options }`), the `settings` and `options` are preserved — only the version field is updated.
+
+`add` does **not** run install. Chain `wyvrnpm install` afterwards to download.
+
+```bash
+# Resolve latest, write "^<latest>"
+wyvrnpm add zlib
+
+# Pin exactly
+wyvrnpm add zlib@1.3.0.0
+
+# Use a caret / tilde / comparator range
+wyvrnpm add fmt@^10.0.0
+wyvrnpm add boost@">=1.80.0 <2.0.0"
+
+# Multiple in one call
+wyvrnpm add zlib fmt@10.2.0.0 spdlog
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--source` / `-s` | *(config)* | Base URL used for the `latest` lookup. Repeat for multiple. |
+| `--platform` | `win_x64` | v1 legacy platform sub-path (used as a fallback during `latest` lookup). |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+
+---
+
+### `wyvrnpm version`
+
+Read, set, or partially update the top-level `version` field in `wyvrn.json`. Designed for CI/CD — bumps the build component from a pipeline variable, prints the result for capture, and never touches git (CI pipelines own tagging and commits).
+
+- **Bare** — prints the current version on stdout, naked (no `[wyvrn]` prefix), so `VER=$(wyvrnpm version)` works straight away.
+- **Full set** — `wyvrnpm version 1.2.3.4` writes the value verbatim. Strict 4-part `x.y.z.b` validation; leading zeros and 3-part semver are rejected.
+- **Component flags** — `--major / --minor / --patch / --build N` replace one component while leaving the others alone. Combine flags freely (`--minor 3 --build 0`).
+- Positional and component flags are mutually exclusive — pick a mode.
+
+```bash
+# Read the current version (CI capture)
+VER=$(wyvrnpm version)
+
+# Inject the build number from a pipeline variable
+wyvrnpm version --build "$BUILD_ID"
+
+# Cut a minor release — reset the build component to 0
+wyvrnpm version --minor 3 --build 0
+
+# Set a full version verbatim
+wyvrnpm version 2.0.0.0
+
+# CI-friendly capture
+wyvrnpm version --build "$BUILD_ID" --format json
+# {"command":"version","previous":"1.2.3.4","version":"1.2.3.99","written":true,...}
+
+# Preview without writing
+wyvrnpm version --build 99 --dry-run
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `<newVersion>` positional | — | Full 4-part version (e.g. `1.2.3.4`). Mutex with `--major/--minor/--patch/--build`. |
+| `--major` | — | Replace the 1st component. |
+| `--minor` | — | Replace the 2nd component. |
+| `--patch` | — | Replace the 3rd component. |
+| `--build` | — | Replace the 4th component (typical CI use). |
+| `--dry-run` | `false` | Compute and print the proposed version without writing. |
+| `--format` | `text` | Output format: `text` (human) or `json` (CI — single object on stdout). |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+
+---
+
+### `wyvrnpm install`
+
+Resolves the full dependency graph and downloads all packages.
+
+**Source priority:** CLI `--source` values are used if provided. If omitted, sources are loaded from the [configuration file](#configuration-file).
+
+**Profile resolution:** `--profile` selects the named build profile. If omitted, `config.defaultProfile` is used, falling back to `"default"`. v2 binaries are resolved in this order:
+
+1. **Exact profile-hash match** — the preferred path.
+2. **Declarative compatibility** — each published build may advertise a `compatibility` block (e.g. "compatible with any `msvc.version ≥ 193` on `Windows/x86_64`"). The best compatible candidate is picked deterministically.
+3. **Source build** (with `--build=missing`) — clones the package's source at the published `gitSha`, resolves its own dependencies, invokes CMake through the shared toolchain generator, and caches the result under `%LOCALAPPDATA%\wyvrnpm\bc\`. On Windows/MSVC with a Ninja or Make generator, `vcvarsall.bat` is auto-activated.
+4. **v1 legacy path** — only when no v2 entry exists for the package at all.
+
+The pre-2.1 "same OS + arch, any compiler" loose fallback is no longer available. Publish a build for your profile, add a declarative `compatibility` block to the recipe, or rerun with `--build=missing` to source-build.
+
+```bash
+# Use configured sources and the default build profile
+wyvrnpm install
+
+# Use a specific named profile
+wyvrnpm install --profile release
+
+# Override with explicit sources
+wyvrnpm install --source https://pkg.example.com/cpp
+
+# Multiple sources — tried in order, first to respond wins
+wyvrnpm install \
+  --source https://primary.example.com/cpp \
+  --source https://mirror.example.com/cpp
+
+# Build any missing binary from source
+wyvrnpm install --build=missing
+
+# Force every dep to be rebuilt from source (debugging / reproducibility check)
+wyvrnpm install --build=always
+
+# Print the resolved install plan WITHOUT downloading (CI-friendly with --format=json)
+wyvrnpm install --dry-run
+wyvrnpm install --dry-run --format=json
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--source` / `-s` | *(config)* | Base URL of a package source. Repeat for multiple. Overrides config when provided. |
+| `--profile` / `-p` | *(config / "default")* | Named build profile to use for v2 binary resolution. |
+| `--build` | `never` | Resolution mode when no exact or compatible profile match exists: `never` fails; `missing` clones and builds the package from its published `gitRepo@gitSha`; `always` rebuilds even when a binary exists. |
+| `--platform` | `win_x64` | v1 legacy platform sub-path (used as a fallback when no v2 binary is found). |
+| `--timeout` | `300` | HTTP request timeout in seconds. |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+| `--root` | `./` | Project root (packages extracted to `{root}/wyvrn_internal/`). |
+| `--dry-run` | `false` | Run the resolver + profile/options math, print the install plan, and exit. No download, no `wyvrn.lock`, no `wyvrn_internal/`, no toolchain. Combine with `--format=json` for CI ingestion (payload carries `command: "install-dry-run"`). |
+| `--conf` | — | Non-ABI build-time override. Repeatable. Format: `<namespace.leaf>=<value>` — e.g. `--conf cmake.cache.CHROMA_ENABLE_TEST=ON`. Layered: CLI > `wyvrn.local.json` > named-profile `conf` > recipe. Does **not** fold into `profileHash`. See [Build-time configuration (`conf`)](#build-time-configuration-conf). |
+| `--build-dir` | `build` | Project-relative subdir for the generated preset's `binaryDir` (`${sourceDir}/<root>/wyvrn-<profile>`). Use when the repo has a `BUILD` Bazel/Buck file at root that collides with `build/` on case-insensitive filesystems (gRPC, …). Persistent override: set `binaryDirRoot` in `wyvrn.local.json`. Validated — must be relative, no `..` segments. |
+
+Packages are extracted to `wyvrn_internal/{name}/`. A `wyvrn.lock` file is written alongside the manifest recording the exact resolved versions, profile, and per-package SHA256. On subsequent installs the lock file pins all previously resolved versions — only newly added dependencies are resolved fresh.
+
+After download, `install` also generates:
+
+- `wyvrn_internal/wyvrn_toolchain.cmake` — CMake toolchain pointing at the resolved packages.
+- `wyvrn_internal/wyvrn_deps.cmake` — post-`project()` include for `find_package()` wiring and runtime DLL copy.
+- `wyvrn_internal/wyvrn_profile.json` — snapshot of the active build profile.
+- `CMakePresets.json` (or `CMakeUserPresets.json` if the project root file is user-owned) with a `wyvrn-<profile>` configure preset. Presets for other profiles are preserved so multiple profiles coexist.
+
+**Toolchain variables exposed to your `CMakeLists.txt` (valid BEFORE `project()`)**:
+
+| Variable | Value |
+|---|---|
+| `WYVRN_PROFILE_NAME` / `WYVRN_PROFILE_HASH` | Active profile name + 16-char hash |
+| `WYVRN_PROFILE_OS` / `WYVRN_PROFILE_ARCH` | OS + architecture from the profile |
+| `WYVRN_PROFILE_COMPILER` / `WYVRN_PROFILE_COMPILER_VERSION` | Compiler identity |
+| `WYVRN_PROFILE_CPPSTD` / `WYVRN_PROFILE_RUNTIME` | C++ standard + MSVC runtime linkage |
+| `WYVRN_ARCH_SUFFIX` | `"64"` for 64-bit arches, `"32"` for 32-bit, empty for unmapped. Derived at toolchain-generation time so it's usable before `project()` — unlike `CMAKE_SIZEOF_VOID_P`. |
+
+The optional helper `WYVRN_APPLY_ARCH_SUFFIX(<target> [BASE_NAME <name>])` from the bundled `macros.cmake` applies the suffix to a target's `OUTPUT_NAME` so x64 and x86 builds of the same library coexist on disk without overwriting each other. Target linkage (`target_link_libraries`) is unaffected — only the produced filename changes.
+
+The bundled `variables.cmake` also suffixes the consumer's own output directories with `WYVRN_ARCH_SUFFIX` so multi-arch builds from one source tree don't clobber each other:
+
+| Profile arch | Archive/library dir | Runtime (DLL/EXE) dir |
+|---|---|---|
+| `x86_64` / `armv8` | `output/lib64/` | `output/bin64/<CONFIG>/` |
+| `x86` / `armv7` | `output/lib/` | `output/bin/<CONFIG>/` |
+| unmapped | `output/lib/` | `output/bin/<CONFIG>/` |
+
+Prior to `2.5.0` the runtime directory was always `output/bin/<CONFIG>/` regardless of arch — a multi-arch consumer building x64 then x86 would silently overwrite the first arch's DLLs. Scripts that hard-code `output/bin/…` expecting x64 payloads need to switch to `output/bin64/…` after upgrading.
+
+```cmake
+project(String CXX)
+add_library(String STATIC ...)
+WYVRN_APPLY_ARCH_SUFFIX(String)                 # → String64.lib / String32.lib
+WYVRN_APPLY_ARCH_SUFFIX(String BASE_NAME my-str) # → my-str64.lib / my-str32.lib
+```
+
+---
+
+### `wyvrnpm build`
+
+Configures and builds the project through the wyvrnpm-generated CMake preset. Auto-runs `install` first if `wyvrn_toolchain.cmake` is missing or `wyvrn.lock` is newer than it.
+
+```bash
+# Configure + build with the default profile's preset (wyvrn-default)
+wyvrnpm build
+
+# Build Debug, verbose compiler output
+wyvrnpm build --config Debug --verbose
+
+# Build multiple configs in one go — configure runs once, build loops per config
+wyvrnpm build --config Debug,Release --install
+
+# Build every config the recipe declares (recipe's build.configs, or all four
+# canonical configs if no recipe is present). Pairs naturally with --install.
+wyvrnpm build --all-configs --install
+
+# Use a specific profile's preset
+wyvrnpm build --profile release
+
+# Explicit preset name (overrides profile-derived default)
+wyvrnpm build --preset wyvrn-release
+
+# Build a single target
+wyvrnpm build --target my-lib
+
+# Wipe the build directory first
+wyvrnpm build --clean
+
+# Override the preset's generator (pair with --clean when switching generators)
+wyvrnpm build --clean --generator "Visual Studio 17 2022"
+wyvrnpm build --clean -G "Ninja Multi-Config"
+
+# Build, then install to the CMake install prefix
+wyvrnpm build --install
+wyvrnpm build --install --install-prefix C:\out\stage
+
+# Skip the auto-install step
+wyvrnpm build --no-auto-install
+
+# Pass extra args through to cmake --build
+wyvrnpm build -- -j 8
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--preset` / `-P` | `wyvrn-<profile>` | CMake configure preset name. |
+| `--profile` / `-p` | *(config / "default")* | Build profile — determines the default preset name. |
+| `--config` / `-c` | `Release` | Build configuration (`Debug` \| `Release` \| `RelWithDebInfo` \| `MinSizeRel`). Comma-separated to build multiple in one invocation (e.g. `Debug,Release`) — configure runs once, build (+ `--install`) loops per config. |
+| `--all-configs` | `false` | Build every config from the recipe's `build.configs` (or all four canonical configs when no recipe is present). Takes precedence over `--config`. |
+| `--target` / `-t` | *(all)* | Specific CMake target to build. |
+| `--verbose` / `-v` | `false` | Pass `--verbose` to `cmake --build`. |
+| `--clean` | `false` | Remove the build directory before configuring. |
+| `--generator` / `-G` | *(from preset)* | Override the CMake generator used at configure time (e.g. `"Visual Studio 17 2022"`, `"Ninja"`, `"Ninja Multi-Config"`). CMake bakes the generator into the cache, so pair with `--clean` when switching. When the effective generator is Visual Studio, `-A <platform>` is auto-derived from the profile's arch (`x86→Win32`, `x86_64→x64`, `armv8→ARM64`, `armv7→ARM`) so VS doesn't silently default to x64 on 32-bit profiles. |
+| `--install` | `false` | Run `cmake --install` after a successful build. |
+| `--install-prefix` | *(baked in)* | Override `CMAKE_INSTALL_PREFIX` for `--install` without reconfiguring. |
+| `--auto-install` | `true` | Auto-run `wyvrnpm install` when the toolchain is stale. Disable with `--no-auto-install`. |
+| `--source` / `-s` | *(config)* | Package sources — passed through to `install` when auto-installing. |
+| `--build-dir` | `build` | Project-relative subdir for the build tree. Must match the value used at `wyvrnpm install` time — the baked preset is the source of truth for `binaryDir`. Persist via `wyvrn.local.json:binaryDirRoot` so install + build agree without repeating the flag. See [Per-developer overlay](#per-developer-overlay--wyvrnlocaljson). |
+
+Everything after `--` is forwarded verbatim to `cmake --build` (e.g. `-j 8`).
+
+---
+
+### `wyvrnpm publish`
+
+Zips the project directory and uploads `wyvrn.json` + `wyvrn.zip` to the destination source, tagged with the active build profile.
+
+**Source priority:** CLI `--source` is used if provided (as a URL/URI or a configured source name). If omitted, the first configured publish source is used.
+
+**Profile:** `--profile` selects the named build profile to publish under. If omitted, `config.defaultProfile` is used, falling back to `"default"`. The profile hash is included in the upload path so multiple builds of the same version (different compilers, runtimes, etc.) can coexist.
+
+```bash
+# Use configured source and default profile
+wyvrnpm publish
+
+# Use a specific profile
+wyvrnpm publish --profile release
+
+# Reference a configured source by name
+wyvrnpm publish --source default
+
+# Explicit destination URL
+wyvrnpm publish --source s3://my-bucket/packages --aws-profile my-sso
+
+# HTTP server with token auth (CI-preferred: --token-env avoids argv leakage)
+wyvrnpm publish --source https://pkg.corp.com --token-env WYVRN_HTTP_TOKEN
+# Equivalent for interactive use; --token lands in shell history / ps output
+wyvrnpm publish --source https://pkg.corp.com --token mytoken
+
+# Local directory or SMB share
+wyvrnpm publish --source \\fileserver\packages
+wyvrnpm publish --source /mnt/packages
+
+# Publish build artifacts from a specific directory
+wyvrnpm publish --path ./dist
+
+# Overwrite an existing build (same version + profile hash)
+wyvrnpm publish --force
+
+# Dry-run — show the upload plan without touching the registry
+wyvrnpm publish --dry-run
+wyvrnpm publish --dry-run --format json | jq '.wouldOverwrite, .plan'
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--source` / `-s` | *(config)* | Destination URL/URI or configured source name. |
+| `--profile` / `-p` | *(config / "default")* | Named build profile to publish under. |
+| `--aws-profile` | *(config)* | AWS SSO profile for S3 authentication. |
+| `--token` | *(config)* | Bearer token for HTTP server authentication. |
+| `--token-env` | *(config)* | Name of an env var holding the bearer token. Preferred for CI — the literal value never lands in `argv` or shell history. |
+| `--path` | `.` | Directory to zip and publish. |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+| `--force` / `-f` | `false` | Overwrite an existing published version (same version + profile hash). |
+| `--dry-run` | `false` | Run every step (profile, options, zip, SHA256, `v2Exists` check) and print the upload plan, but skip the provider write. An existing published version is reported as a warning (not an error) so the full plan still prints. Pair with `--format json` to gate CI on `wouldOverwrite`. |
+
+During publish the tool also:
+- reads `wyvrn.lock` to pin locked dependency versions into the uploaded manifest
+- captures the current git commit SHA and remote URL as metadata
+- computes a SHA256 of the zip and stores it in the upload metadata
+
+---
+
+### `.wyvrnignore`
+
+Place a `.wyvrnignore` file in the directory being published to exclude files from the zip. Uses the same glob syntax as `.gitignore`:
+
+```
+# Build artefacts that shouldn't ship
+build/
+*.obj
+*.pdb
+
+# Anchored to root with leading /
+/CMakeCache.txt
+/CMakeFiles/
+```
+
+---
+
+### `wyvrnpm clean`
+
+Removes the `wyvrn_internal/` package cache and `wyvrn.lock`.
+
+```bash
+# Project-local cleanup
+wyvrnpm clean
+
+# Also wipe the machine-wide source-build cache used by --build=missing
+wyvrnpm clean --build-cache
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--build-cache` | `false` | Also remove the source-build cache under `%LOCALAPPDATA%\wyvrnpm\bc\` (Unix: `~/.cache/wyvrnpm/bc/`). |
+| `--uploaded-built` | `false` | Wipe only the local record of what this machine has uploaded via `--upload-built` (the `.uploaded-to.json` sidecars). Does **not** touch the registry, the artefacts, or `wyvrn_internal/`. |
+
+For selective cache pruning (keep last N variants, drop entries older than N days), use `wyvrnpm cache prune` instead — see below.
+
+---
+
+### `wyvrnpm cache` (2.8.0+)
+
+Inspect and selectively prune the machine-wide source-build cache at `%LOCALAPPDATA%\wyvrnpm\bc\` (Unix: `~/.cache/wyvrnpm/bc/`). Useful once `--upload-built` adoption balloons cache size on dev rigs — `clean --build-cache` is the blunt alternative that wipes everything.
+
+```bash
+# List every cached entry as a table
+wyvrnpm cache list
+
+# Filter by package name (glob)
+wyvrnpm cache list "boost*"
+
+# Machine-readable output for CI
+wyvrnpm cache list --format json
+
+# Keep the 2 most-recently-touched variants per (name, version)
+wyvrnpm cache prune --keep-last 2
+
+# Drop entries older than 30 days
+wyvrnpm cache prune --older-than 30d
+
+# Combine: keep 1 recent per version AND drop anything stale
+wyvrnpm cache prune --keep-last 1 --older-than 30d
+
+# Preview — print what would be removed, delete nothing
+wyvrnpm cache prune --keep-last 2 --dry-run
+```
+
+**`cache list` options**
+
+| Option | Default | Description |
+|---|---|---|
+| `[pattern]` / `--pattern` | *(none)* | Glob over package names (`*` for any chars, `?` for one). |
+| `--format` | `text` | `text` (table) or `json` (structured payload for CI). |
+
+**`cache prune` options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--keep-last <N>` | *(none)* | Retain the N most-recently-touched entries **per (name, version) group**. A four-profile rig keeping-last-2 still retains the two newest profile variants of each version. |
+| `--older-than <dur>` | *(none)* | Remove entries whose mtime is older than the threshold. Format: `<number><unit>`, unit ∈ `s` / `m` / `h` / `d` (e.g. `30d`, `72h`). |
+| `--pattern <glob>` | *(none)* | Restrict scope to package names matching the glob. |
+| `--dry-run` | `false` | Print what would be removed without deleting. |
+
+At least one of `--keep-last` / `--older-than` is required — calling `prune` bare errors out with a pointer to `clean --build-cache` (the nuke-everything path).
+
+---
+
+### `wyvrnpm show`
+
+Read-only registry-metadata inspector. Given `<name>[@<version>[@<profileHash>]]`, queries the first configured install source that knows the package (override with `--source`) and prints what's published.
+
+```bash
+# Index of every published version (one HTTP round trip per source)
+wyvrnpm show zlib
+
+# Narrow to one version — fans out a per-profile query so uploadedBy,
+# compatibility, and declared options show up per build
+wyvrnpm show zlib@1.3.0.0
+
+# Narrow to one specific build
+wyvrnpm show zlib@1.3.0.0@a1b2c3d4e5f60718
+
+# Pick the source explicitly (skips install-source lookup order)
+wyvrnpm show zlib@1.3.0.0 --source s3://team-pkgs
+
+# Machine-readable for CI ingestion
+wyvrnpm show zlib@1.3.0.0 --format json
+```
+
+What gets surfaced per profile:
+
+- **origin** — `author-publish` vs `consumer-upload` (derived from whether the manifest carries an `uploadedBy` block).
+- **uploadedBy** — when set, the consumer-upload provenance (`kind`, `builtFromGit`, `builtFromSha`, `uploadedAt`, `wyvrnpmVersion`).
+- **compatibility** — the recipe's declarative compat block, if any.
+- **declaredOptions** — the author-declared `options` map from the recipe.
+- **resolvedOptions** — the resolved option values that produced this profile's `profileHash`.
+- **publishedConf** — recipe + CLI `--conf` the publisher captured (informational; doesn't affect resolution).
+- **signature** — when PLAN-SIGNING phase 1 ships, signer identity; absent today.
+
+Useful for: auditing consumer uploads (who pushed this artefact, from which commit), spotting profile drift between two consumers, verifying a package's declared options before adding it to a recipe.
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `pkg` *(positional)* | *(required)* | `<name>[@<version>[@<profileHash>]]` |
+| `--source` / `-s` | *(first configured install source)* | URL or configured source name. Repeatable. |
+| `--format` | `text` | `text` or `json` (see [Shape — `show`](#shape--show) below). |
+| `--token` / `--token-env` / `--aws-profile` | | Auth forwarded to the provider the same way `install` does. |
+
+---
+
+### `wyvrnpm install-skill`
+
+Installs the bundled wyvrnpm Agent Skill — the authoring guide Claude Code uses when it sees a `wyvrn.json` in the workspace. Ships as a `.skill` zip inside the npm package (`claude/skills/wyvrnpm.skill`) and is extracted into `~/.claude/skills/wyvrnpm/` on demand.
+
+```bash
+# One-shot: install the bundled skill for Claude Code
+wyvrnpm install-skill --claude
+
+# Overwrite an existing installation (e.g. after upgrading wyvrnpm)
+wyvrnpm install-skill --claude --force
+
+# Preview without writing
+wyvrnpm install-skill --claude --dry-run
+```
+
+You only need this if you want Claude Code to pick up the skill. The CLI itself works without it.
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--claude` | `false` | Install for Claude Code (extracts to `~/.claude/skills/wyvrnpm/` + writes the `.skill` zip alongside). Required — present so a future `--cursor` / `--vscode` target can slot in without CLI churn. |
+| `--force` | `false` | Overwrite an existing skill install. Without it, the command refuses to clobber. |
+| `--dry-run` | `false` | Print the destination paths and intended actions without writing. |
+
+---
+
+### `wyvrnpm link`
+
+Links a local package for development, similar to `npm link`. This allows you to test packages from local source directories without publishing to the registry.
+
+#### Register a package globally
+
+Run `wyvrnpm link` in a package directory to register it for linking:
+
+```bash
+cd C:\Dev\my-library
+wyvrnpm link
+# [wyvrn] Registered "my-library" -> C:\Dev\my-library
+```
+
+For CMake packages where the installable content is in a subdirectory:
+
+```bash
+cd C:\Dev\my-cmake-lib
+wyvrnpm link --subdir output/install
+# [wyvrn] Registered "my-cmake-lib" -> C:\Dev\my-cmake-lib\output\install
+```
+
+#### Link a package into your project
+
+Link a globally registered package:
+
+```bash
+cd C:\Projects\my-app
+wyvrnpm link my-library
+# [wyvrn] Linked: my-library -> C:\Dev\my-library
+```
+
+Or link directly from a path (skip global registration):
+
+```bash
+wyvrnpm link my-library C:\Dev\my-library
+wyvrnpm link my-library C:\Dev\my-library --subdir output/install
+```
+
+#### List registered packages
+
+```bash
+wyvrnpm link --list
+# [wyvrn] Globally registered packages:
+#   my-library -> C:\Dev\my-library
+#   my-cmake-lib -> C:\Dev\my-cmake-lib\output\install [subdir: output/install]
+```
+
+**Options**
+
+| Option | Description |
+|---|---|
+| `--list` | List all globally registered packages. |
+| `--subdir` | Subdirectory within the package to link (e.g., `output/install` for CMake packages). |
+
+**How it works:**
+- Creates a symlink (Unix) or junction (Windows) in `wyvrn_internal/`
+- Junctions on Windows don't require admin rights
+- Linked packages are recorded in `wyvrn.lock` with a `linked:` prefix
+- `wyvrnpm install` automatically skips downloading linked packages
+
+---
+
+### `wyvrnpm unlink`
+
+Removes a linked package from the current project.
+
+```bash
+wyvrnpm unlink my-library
+# [wyvrn] Unlinked: my-library
+```
+
+To unlink and re-download from the registry:
+
+```bash
+wyvrnpm unlink my-library --restore
+# [wyvrn] Unlinked: my-library
+# [wyvrn] Downloading: my-library@1.0.0.0
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--restore` | `false` | Re-download the package from registry after unlinking. |
+| `--source` | *(config)* | Package source for `--restore`. |
+| `--platform` | `win_x64` | Target platform for v1 fallback when using `--restore`. |
+
+---
+
+### `wyvrnpm configure`
+
+Manages the [configuration file](#configuration-file). All sub-commands read and write `config.json` in the platform config directory.
+
+#### `wyvrnpm configure list`
+
+Prints all configured sources.
+
+```
+Config: C:\Users\you\AppData\Local\wyvrnpm\config.json
+
+Install Sources:
+  corp-s3              s3://my-bucket/packages  [profile: my-sso]
+  fallback             https://pkg.corp.com      [token: ***]
+
+Publish Sources:
+  default              s3://my-bucket/packages  [profile: my-sso]
+```
+
+#### `wyvrnpm configure add-source`
+
+Adds a new source or updates an existing one with the same name.
+
+```bash
+# S3 with AWS SSO profile (install)
+wyvrnpm configure add-source \
+  --kind install \
+  --name corp-s3 \
+  --url s3://my-bucket/packages \
+  --profile my-sso-profile
+
+# HTTPS server with token auth (install)
+wyvrnpm configure add-source \
+  --kind install \
+  --name fallback \
+  --url https://pkg.corp.com \
+  --token mytoken
+
+# Local or SMB path (no auth required)
+wyvrnpm configure add-source \
+  --kind install \
+  --name local \
+  --url \\fileserver\packages
+
+# Publish destination
+wyvrnpm configure add-source \
+  --kind publish \
+  --name default \
+  --url s3://my-bucket/packages \
+  --profile my-sso-profile
+```
+
+**Options**
+
+| Option | Required | Description |
+|---|---|---|
+| `--kind` | Yes | `install` or `publish`. |
+| `--name` | Yes | Unique name for this source. |
+| `--url` | Yes | Destination URL, URI, or file path. |
+| `--profile` | No | AWS SSO profile (S3 sources). |
+| `--token` | No | Bearer token (HTTP sources). Persisted in plaintext in `config.json` — prefer `--token-env` for CI and shared setups. |
+| `--token-env` | No | Name of an env var whose value is the bearer token. Only the **name** lands in `config.json`; the value is resolved fresh on every `wyvrnpm` call. |
+
+#### `wyvrnpm configure remove-source`
+
+Removes a source by name.
+
+```bash
+wyvrnpm configure remove-source --kind install --name fallback
+wyvrnpm configure remove-source --kind publish --name default
+```
+
+#### `wyvrnpm configure profile`
+
+Manages named build profiles stored in the profiles directory.
+
+```bash
+# Auto-detect the current build environment and save it
+wyvrnpm configure profile detect
+wyvrnpm configure profile detect --name msvc_release --dry-run
+
+# List all saved profiles (* = default)
+wyvrnpm configure profile list
+
+# Show a saved profile
+wyvrnpm configure profile show
+wyvrnpm configure profile show --name msvc_release
+
+# Manually set individual fields in a profile
+wyvrnpm configure profile set --name msvc_release --runtime static --cppstd 20
+
+# Change which profile is the default
+wyvrnpm configure profile set-default msvc_release
+
+# Delete a profile
+wyvrnpm configure profile delete msvc_release
+```
+
+**`configure profile detect` options**
+
+| Option | Description |
+|---|---|
+| `--name` / `-n` | Profile name to save to (default: `"default"`). |
+| `--dry-run` | Print detected values without saving. |
+
+**`configure profile set` options**
+
+| Option | Description |
+|---|---|
+| `--name` / `-n` | Profile name to update (default: `"default"`). |
+| `--os` | OS (`Windows` \| `Linux` \| `Macos`). |
+| `--arch` | Architecture (`x86_64` \| `x86` \| `armv8` \| ...). |
+| `--compiler` | Compiler (`msvc` \| `gcc` \| `clang` \| `apple-clang`). |
+| `--compiler-version` | Compiler version (`193` \| `13` \| `17` \| ...). |
+| `--cppstd` | C++ standard (`14` \| `17` \| `20` \| `23`). |
+| `--runtime` | Runtime linkage (`static` \| `dynamic`). |
+
+---
+
+## JSON output (`--format json`)
+
+`install`, `publish`, and `show` accept `--format json` to emit a single machine-readable JSON object on stdout. Log lines (`[wyvrn]` prefix) move to **stderr** in this mode, so stdout is reserved exclusively for the JSON payload — no scraping required.
+
+```bash
+wyvrnpm install --format json > install-result.json
+wyvrnpm publish --format json 2>/dev/null           # swallow logs, keep JSON
+wyvrnpm show zlib@1.3.0.0 --format json | jq '.versions["1.3.0.0"].profiles[].origin'
+```
+
+### Shape — `install`
+
+```json
+{
+  "command": "install",
+  "wyvrnpmVersion": "2.2.1",
+  "profile": { "os": "Windows", "arch": "x86_64", "compiler": "msvc", "compiler.version": "193", "compiler.cppstd": "23", "compiler.runtime": "dynamic" },
+  "profileName": "default",
+  "profileHash": "bf341c08af0aee2d",
+  "packages": [
+    {
+      "name": "zlib",
+      "version": "1.3.0.0",
+      "versionRange": "^1.3.0.0",
+      "profileHash": "a1b2c3d4e5f60718",
+      "options": { "shared": false, "minizip": true },
+      "contentSha256": "…",
+      "gitSha": "…",
+      "resolvedFrom": "v2"
+    }
+  ],
+  "lockFile": "/abs/path/to/wyvrn.lock",
+  "uploadSummary": { "uploaded": 0, "skipped": 0, "failed": 0 }
+}
+```
+
+- `versionRange` is `null` when the user pinned an exact version.
+- `options` is `null` for packages that declare no options.
+- `uploadSummary` is `null` unless `--upload-built` was passed.
+- `packages` is sorted by name.
+
+### Shape — `publish`
+
+```json
+{
+  "command": "publish",
+  "wyvrnpmVersion": "2.2.1",
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "profileHash": "a1b2c3d4e5f60718",
+  "source": "s3://team-pkgs",
+  "contentSha256": "…",
+  "options": { "shared": false, "minizip": true },
+  "gitSha": "…",
+  "gitRepo": "…",
+  "publishedAt": "2026-04-21T12:34:56.789Z"
+}
+```
+
+### Shape — `show`
+
+```json
+{
+  "command": "show",
+  "wyvrnpmVersion": "2.2.1",
+  "source": "s3://team-pkgs",
+  "package": "zlib",
+  "latest": "1.3.0.0",
+  "versions": {
+    "1.3.0.0": {
+      "source": { "gitRepo": "…", "gitSha": "…" },
+      "profiles": [
+        {
+          "profileHash": "a1b2c3d4e5f60718",
+          "contentSha256": "…",
+          "publishedAt": "…",
+          "buildSettings": { "os": "Windows", "...": "...", "options": { "minizip": true } },
+          "origin": "author-publish",
+          "uploadedBy": null,
+          "compatibility": { "compiler.cppstd": "lte" },
+          "declaredOptions": { "minizip": { "default": true, "allowed": [true, false] } }
+        }
+      ]
+    }
+  }
+}
+```
+
+- `origin` is `"author-publish"` | `"consumer-source-build"` | `null` (the last when the summary view can't tell without a deep fetch).
+- Bare-name queries (`wyvrnpm show zlib --format json`) skip the per-profile deep fetch; `origin`, `uploadedBy`, `compatibility`, `declaredOptions` are `null` for each profile.
+
+Exit codes and error behaviour are identical to text mode. Fatal errors leave stdout empty rather than emitting partial JSON.
+
+---
+
+## Configuration File
+
+wyvrnpm stores persistent configuration in a `config.json` file:
+
+| Platform | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\wyvrnpm\config.json` |
+| Linux / macOS | `~/.config/wyvrnpm/config.json` |
+
+**Example config.json**
+
+```json
+{
+  "defaultProfile": "default",
+  "installSources": [
+    {
+      "name": "corp-s3",
+      "url": "s3://my-bucket/packages",
+      "profile": "my-sso-profile"
+    },
+    {
+      "name": "fallback",
+      "url": "https://pkg.corp.com",
+      "token": "mytoken"
+    }
+  ],
+  "publishSources": [
+    {
+      "name": "default",
+      "url": "s3://my-bucket/packages",
+      "profile": "my-sso-profile"
+    }
+  ],
+  "linkedPackages": {
+    "my-library": { "path": "C:\\Dev\\my-library" },
+    "my-cmake-lib": { "path": "C:\\Dev\\my-cmake-lib", "subdir": "output/install" }
+  }
+}
+```
+
+The `defaultProfile` field sets which named build profile is used when `--profile` is not provided on the CLI.
+
+The `linkedPackages` field stores globally registered packages for `wyvrnpm link`. Each entry maps a package name to its local path and optional subdirectory.
+
+**CLI options always take priority over config.** Config values are only used when the corresponding CLI option is not provided.
+
+---
+
+## Publish Providers
+
+wyvrnpm uses a provider architecture to support different destination types. The correct provider is selected automatically based on the source URL format.
+
+| Provider | Detected from | Auth |
+|---|---|---|
+| **S3** | `s3://` URI, or S3 HTTPS endpoint | `--aws-profile` (AWS SSO) |
+| **HTTP** | `http://` or `https://` | `--token` (Bearer) |
+| **File** | Local path or UNC/SMB share | none |
+
+### S3 Provider
+
+Accepts any of these source formats:
+
+```
+s3://bucket-name/optional/prefix
+https://bucket-name.s3.amazonaws.com/prefix
+https://bucket-name.s3.us-east-1.amazonaws.com/prefix
+https://s3.amazonaws.com/bucket-name/prefix
+https://s3.us-east-1.amazonaws.com/bucket-name/prefix
+```
+
+Authentication uses AWS SSO via `--aws-profile`. If no profile is given, the default AWS credential chain is used.
+
+### HTTP Provider
+
+Accepts `http://` and `https://` URLs. Uploads files via HTTP `PUT`. Optionally authenticates with a Bearer token via `--token`.
+
+### File Provider
+
+Accepts local directory paths and SMB/UNC network shares. Files are copied with no authentication required.
+
+```
+/absolute/unix/path
+./relative/path
+C:\Windows\path
+\\server\share\path
+//server/share/path
+file:///absolute/path
+```
+
+### Adding a Custom Provider
+
+1. Create `src/providers/myprovider.js` extending `BaseProvider`:
+
+```js
+'use strict';
+const BaseProvider = require('./base');
+
+class MyProvider extends BaseProvider {
+  static canHandle(source) {
+    return source.startsWith('myscheme://');
+  }
+
+  static get providerName() { return 'MyProvider'; }
+
+  async v2Publish(files, options) {
+    // files.manifest — path to wyvrn.json
+    // files.zip      — path to wyvrn.zip
+    // options.source, options.name, options.version, options.profileHash
+    // options.contentSha256, options.gitSha, options.gitRepo
+    // options.buildSettings, options.lockedDependencies
+  }
+
+  async v2Exists(options) {
+    // Return true if this version+profileHash already exists
+    return false;
+  }
+}
+
+module.exports = MyProvider;
+```
+
+2. Register it in `src/providers/index.js`:
+
+```js
+const MyProvider = require('./myprovider');
+
+const PROVIDERS = [
+  S3Provider,
+  HttpProvider,
+  FileProvider,
+  MyProvider,   // add here
+];
+```
+
+---
+
+## Registry Layout
+
+### v2 layout (current)
+
+Packages published by v2 tooling are stored under a `v2/` prefix, with the profile hash as a sub-directory:
+
+```
+{source}/v2/{name}/{version}/{profileHash}/wyvrn.json   <- package manifest + metadata
+{source}/v2/{name}/{version}/{profileHash}/wyvrn.zip    <- package archive
+{source}/v2/{name}/versions.json                        <- version index
+{source}/v2/{name}/latest.json                          <- latest version pointer
+```
+
+The profile hash is a 16-character SHA256 prefix computed from the build profile fields. This allows multiple compiler/platform variants of the same version to coexist in the same registry.
+
+**Example (S3):**
+
+```
+s3://my-bucket/packages/v2/OpenSSL/3.0.0.0/a1b2c3d4e5f60718/wyvrn.json
+s3://my-bucket/packages/v2/OpenSSL/3.0.0.0/a1b2c3d4e5f60718/wyvrn.zip
+```
+
+### v1 layout (legacy)
+
+v2 tooling also dual-publishes to the v1 path so that older clients can still consume packages:
+
+```
+{source}/{platform}/{name}/{version}/wyvrn.json
+{source}/{platform}/{name}/{version}/wyvrn.zip
+```
+
+**Example (HTTP):**
+
+```
+https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.json
+https://pkg.corp.com/win_x64/OpenSSL/3.0.0.0/wyvrn.zip
+```
+
+The tool also falls back to `razer.json` / `razer.zip` for legacy compatibility.
+
+### Package manifest (wyvrn.json hosted on source)
+
+```json
+{
+  "Name": "OpenSSL",
+  "Version": "3.0.0.0",
+  "Description": "TLS/SSL toolkit",
+  "Dependencies": [
+    { "Name": "zlib", "Version": "1.3.0.0" }
+  ]
+}
+```
+
+Fields use PascalCase. `Dependencies` is an array — transitive dependencies are resolved automatically.
+
+---
+
+## Project Manifest (wyvrn.json)
+
+```json
+{
+  "name": "my-app",
+  "version": "1.0.0.0",
+  "description": "My C++ application",
+  "kind": "ConsoleApp",
+  "dependencies": {
+    "OpenSSL": "3.0.0.0",
+    "zlib": {
+      "version": "1.3.0.0",
+      "settings": {
+        "compiler.runtime": "static"
+      }
+    }
+  }
+}
+```
+
+**`kind` values:** `ConsoleApp`, `StaticLib`, `DynamicLib`, `HeaderOnlyLib`, `WebApp`, `Utility`, `Service`, `TestProject`
+
+**`dependencies`** can be either a plain version string (`"major.minor.patch.build"`) or an object with `version`, an optional `settings` map, and an optional `options` map. The `settings` map overrides individual build profile fields for that specific dependency — useful when a dependency must be consumed with a different runtime linkage or C++ standard than your default profile. The `options` map is covered in the next section.
+
+### Version ranges
+
+The `version` field accepts ranges in addition to exact versions and the `"latest"` tag:
+
+| Spec | Meaning |
+|---|---|
+| `"1.2.3.4"` | exact — must match byte-identically |
+| `"latest"` | resolves to whatever `latest.json` points at |
+| `"^1.2.3.4"` | major-pinned — `>= 1.2.3.4` and `< 2.0.0.0` |
+| `"~1.2.3.4"` | minor-pinned — `>= 1.2.3.4` and `< 1.3.0.0` |
+| `">=1.2.3.4 <2.0.0.0"` | explicit comparators — space-separated, supports `>=`, `>`, `<=`, `<`, `=` |
+
+Ranges resolve at install time against each source's `versions.json`. wyvrnpm picks the **highest version** that satisfies the range. The resolved exact version is pinned into `wyvrn.lock` alongside the original range string, so re-installs are byte-reproducible — ranges are only re-evaluated when the lock file's entry for that dependency is removed.
+
+**Error handling:**
+
+- **No version satisfies the range** → strict failure with every published version listed so you can see what's available.
+- **Conflicting ranges across the graph** (direct consumer wants `^1.x` but a transitive wants `^2.x`) → precise error naming both contributors and their ranges.
+- **Malformed range string** → fail fast with a cheat-sheet of supported syntaxes.
+
+Example:
+
+```json
+{
+  "dependencies": {
+    "OpenSSL": "^3.0.0.0",
+    "zlib":    "~1.3.0.0",
+    "boost":   ">=1.80.0.0 <2.0.0.0"
+  }
+}
+```
+
+### Per-dependency source pin (2.8.0+)
+
+When you have more than one configured install source (e.g. a primary S3 bucket plus a mirror), you can pin a security-sensitive dep to its canonical source by name:
+
+```json
+{
+  "dependencies": {
+    "OpenSSL": {
+      "version": "3.0.0.0",
+      "source":  "primary-s3"
+    }
+  }
+}
+```
+
+`"primary-s3"` must match a `name` from `wyvrnpm configure list`; an unknown name fails install with exit code 1 rather than silently fanning out. The pin closes two common multi-source holes:
+
+- **Mirror shadowing.** A package accidentally published to the mirror can't substitute for the primary's copy.
+- **Dependency confusion.** A squatter on a secondary source can't poison the build.
+
+Pins are direct-only — they don't cascade to the pinned package's own transitive deps. CLI `--source` overrides config entirely, so on a run with `--source`, any manifest pin is ignored with a warning rather than an error. The lockfile records `source: "<name>"` on pinned entries so reviewers can spot at a glance that the artefact came from the declared source; absent on non-pinned entries so pre-2.8.0 locks remain byte-identical.
+
+### Pattern-based `settingsOverrides` (2.8.0+)
+
+When many deps need the same settings override — every `boost-*` family member needing `compiler.cppstd: "17"`, or every `*-debug` variant needing `compiler.runtime: "static"` — declare the pattern at the top level of the manifest instead of copy-pasting per dep:
+
+```json
+{
+  "dependencies": {
+    "boost-filesystem": "1.80.0.0",
+    "boost-system":     "1.80.0.0",
+    "boost-thread":     "1.80.0.0",
+    "zlib":             "1.3.0.0"
+  },
+  "settingsOverrides": {
+    "boost*":  { "compiler.cppstd":  "17" },
+    "*-debug": { "compiler.runtime": "static" }
+  }
+}
+```
+
+Rules:
+
+- Keys are globs — `*` matches any chars, `?` matches exactly one, literal names work too. Both ends are anchored (no substring match unless you add `*` on either side).
+- Values accept the same keys as profile overrides: `os`, `arch`, `compiler`, `compiler.version`, `compiler.cppstd`, `compiler.runtime`. Unknown keys fail install with a clear error.
+- More-specific patterns win: literal `"boost-filesystem"` beats `"boost*"`, which beats `"*"`.
+- A literal per-dep `settings` block inside `dependencies` still wins over any pattern. Use that for the one dep that deviates from the family rule.
+
+Each matching pattern shifts that dep's `profileHash`, so different settings produce distinct registry artefacts — identical semantics to literal per-dep `settings`.
+
+### Package options (`options`)
+
+A library author can declare **options** — compile-time feature toggles that change the produced binary's ABI. Examples: `shared` (shared vs static library), `minizip` (zlib's minizip support), `fips` (OpenSSL's FIPS mode). Each option produces a distinct `profileHash`, so every option combination gets its own artefact on the registry.
+
+**Author side — declare in the recipe's `wyvrn.json`:**
+
+```json
+{
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "options": {
+    "shared":  { "default": false, "allowed": [true, false] },
+    "minizip": { "default": true,  "allowed": [true, false] },
+    "api":     { "default": "default", "allowed": ["default", "legacy"] }
+  },
+  "build": {
+    "configure": [
+      "-DBUILD_SHARED_LIBS=${options.shared}",
+      "-DZLIB_BUILD_MINIZIP=${options.minizip}",
+      "-DZLIB_API_MODE=${options.api}"
+    ]
+  }
+}
+```
+
+Rules for the declaration:
+
+- Option names must match `/^[a-z][a-z0-9_-]*$/`.
+- Each option needs `default` + `allowed`. `default` must be a member of `allowed`.
+- `allowed` values are `boolean` or `string`. No integers, no lists.
+- `${options.<name>}` tokens in `build.configure` / `build.buildArgs` are expanded at source-build time. Booleans expand to `ON`/`OFF`; strings expand verbatim. A typo (`${options.fips}` with no `fips` declared) is a hard error — it will not silently reach CMake.
+
+**Consumer side — override per dependency:**
+
+```json
+{
+  "dependencies": {
+    "zlib": {
+      "version": "1.3.0.0",
+      "options": { "minizip": false }
+    }
+  }
+}
+```
+
+**Consumer side — override via CLI (precedence: CLI > wyvrn.json > recipe defaults):**
+
+```bash
+wyvrnpm install -o zlib:minizip=false -o zlib:shared=true
+wyvrnpm publish -o zlib:minizip=false          # publishing a specific variant
+```
+
+Option overrides are validated against the recipe's `allowed` list at resolve time; unknown option names surface a "did you mean?" suggestion.
+
+**What happens on the registry.** Options fold into `profileHash`, so `zlib@1.3.0.0` with `minizip=true` and `zlib@1.3.0.0` with `minizip=false` are two distinct artefacts at two different URLs — same version, different hashes. `wyvrnpm show zlib@1.3.0.0` lists all published variants and prints each one's resolved options.
+
+**Backward compatibility.** Packages that do not declare an `options` block hash byte-identically to how they did before options existed. No registry migration required.
+
+### Source-build recipe (`build`)
+
+A library package may include an optional `build` section that tells `wyvrnpm install --build=missing` how to rebuild it from source. Only `system: "cmake"` is supported today.
+
+```json
+{
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "kind": "StaticLib",
+  "build": {
+    "system":       "cmake",
+    "generator":    ["Ninja", "Visual Studio 17 2022"],
+    "configs":      ["Release", "Debug"],
+    "configure":    ["-DZLIB_BUILD_EXAMPLES=OFF"],
+    "buildArgs":    ["--parallel"],
+    "installDir":   "install",
+    "sourceSubdir": "."
+  }
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `system` | `cmake` | Build system. Only `cmake` is supported. |
+| `generator` | *(CMake default)* | Single generator (`"Ninja"`) or an array tried in order — first available wins. |
+| `configs` | `["Debug","Release","RelWithDebInfo","MinSizeRel"]` | CMake configurations to build and install. |
+| `configure` | `[]` | Extra args appended to `cmake` at configure time. |
+| `buildArgs` | `[]` | Extra args appended to `cmake --build`. |
+| `installDir` | `install` | Install prefix relative to the binary dir. |
+| `sourceSubdir` | `.` | Where `CMakeLists.txt` lives relative to the clone root. |
+| `requiredTools` | `[]` | Tools that must be on `PATH` before the build starts (fail-fast check). |
+
+On Windows with MSVC and a non-Visual-Studio generator (Ninja, Make), `vcvarsall.bat` is auto-activated for the spawned CMake process — no need to launch from a Developer Prompt.
+
+---
+
+## Build-time configuration (`conf`)
+
+`conf` is wyvrnpm's channel for **non-ABI** build-time knobs — CMake cache variables, feature toggles that change `add_subdirectory()` but not the public binary, and (in future phases) other build-tool settings. It is a deliberate sibling of `options`, with the opposite hashing property:
+
+| | `options` (F1) | `conf` (this section) |
+|---|---|---|
+| Folds into `profileHash`? | Yes — every combination is a distinct registry artefact. | **No.** Informational only; two builds with different `conf` still share the same `profileHash`. |
+| Typical use | `shared`/`minizip`/`fips` — things that genuinely change the binary. | `CHROMA_ENABLE_TEST`, `BUILD_DOCS`, `CMAKE_EXPORT_COMPILE_COMMANDS` — things that don't. |
+| Consumer can override? | Yes (per-dep `options` in `wyvrn.json` or `-o pkg:name=val` on CLI). | Yes (recipe → named-profile `conf` → `wyvrn.local.json` → `--conf`, in that precedence). |
+
+Phase 1 (2.6.0+) supports a single namespace: `cmake.cache.<VAR>`. It flows into the generated `CMakePresets.json`'s `cacheVariables`.
+
+### The four layers
+
+```
+  highest   CLI     --conf cmake.cache.X=ON
+    │       ─────
+    │    local     wyvrn.local.json              (per-developer, gitignored)
+    │       ─────
+    │  profile    named-profile JSON.conf       (team-shared, checked-in)
+    │       ─────
+    │   recipe    wyvrn.json.conf               (author defaults)
+    ▼       ─────
+  lowest    (nothing — key absent)
+```
+
+**Per-leaf override, not per-branch replace.** A CLI `--conf cmake.cache.FOO=ON` on top of a recipe setting `BAR=OFF` yields both keys — it does not discard `BAR`. Any omitted layer is equivalent to an empty map at that position — a project with no `wyvrn.local.json` and no profile `conf` merges recipe + CLI exactly as phase 1.
+
+### Recipe-level defaults
+
+Authors can declare defaults on their package:
+
+```json
+{
+  "name": "ChromaSDK",
+  "version": "2.5.0.0",
+  "conf": {
+    "cmake": {
+      "cache": {
+        "CHROMA_ENABLE_TEST":     "OFF",
+        "CHROMA_ENABLE_EXAMPLES": "OFF",
+        "CHROMA_LOG_LEVEL":       "WARNING"
+      }
+    }
+  }
+}
+```
+
+`true`/`false` in the JSON are normalised to CMake `"ON"`/`"OFF"`; numbers are stringified; strings pass through.
+
+### Per-developer overlay — `wyvrn.local.json`
+
+Drop a `wyvrn.local.json` next to `wyvrn.json` for per-machine overrides. `wyvrnpm init` scaffolds a `.gitignore` entry for new projects; existing projects get a one-line nudge on `wyvrnpm install` when the file is present but not ignored.
+
+```json
+{
+  "conf": {
+    "cmake": {
+      "cache": {
+        "CHROMA_ENABLE_TEST":            "ON",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+      }
+    }
+  },
+  "binaryDirRoot": "cmake-out"
+}
+```
+
+Top-level allow-list: `conf` (build-time knobs — see above) and `binaryDirRoot` (build-tree subdir — see below). Anything else is a hard error, foreclosing the silent-inert footgun where a user writes `{ "dependencies": {...} }` expecting local dep overrides.
+
+**`binaryDirRoot`** (`2.12.0+`) — overrides the default `build/` subdir the generated preset configures into. The preset's `binaryDir` becomes `${sourceDir}/<binaryDirRoot>/wyvrn-<profile>`; `wyvrnpm build` mirrors the same value so `cmake --build <dir>` lands at the matching path. CLI flag `--build-dir <path>` is the one-shot equivalent (CI, ad-hoc); the overlay is the persistent answer for repos that always need the override.
+
+Why this exists: repos with a `BUILD` Bazel/Buck file at the root collide with `build/` on case-insensitive filesystems (Windows NTFS, default macOS HFS+) — `cmake` cannot create a `build/wyvrn-default` subdirectory because Windows' filesystem treats `BUILD` (the Bazel file) and `build` (the wanted directory) as the same name. **gRPC** is the canonical case. Setting `binaryDirRoot: "cmake-out"` sidesteps the collision entirely.
+
+Validation: must be a relative path, no absolute / drive-letter prefixes, no `..` segments, no empty value. Backslashes normalise to forward slashes; trailing separators stripped. Lockfile / `profileHash` / published artefacts are unaffected — the value is read at install time only and never written to the registry.
+
+### Team-shared overlay — named-profile `conf` (phase 2, 2.7.0+)
+
+When every developer on a team would end up with the same `wyvrn.local.json`, check that shared policy into the named profile instead. A saved profile (e.g. `%LOCALAPPDATA%\wyvrnpm\profiles\team-default.json`) may carry an optional top-level `conf` block alongside its `[settings]`:
+
+```json
+{
+  "os": "Windows",
+  "arch": "x86_64",
+  "compiler": "msvc",
+  "compiler.version": "193",
+  "compiler.cppstd": "20",
+  "compiler.runtime": "dynamic",
+  "conf": {
+    "cmake": {
+      "cache": {
+        "CHROMA_ENABLE_SANITIZERS":    "OFF",
+        "CMAKE_EXPORT_COMPILE_COMMANDS": "ON"
+      }
+    }
+  }
+}
+```
+
+Edit via the `configure profile set` convenience (repeatable, same `KEY=VAL` / bare-`KEY` / `KEY=` syntax as the other CLI sinks):
+
+```bash
+wyvrnpm configure profile set --name team-default --conf cmake.cache.CMAKE_EXPORT_COMPILE_COMMANDS=ON
+wyvrnpm configure profile set --name team-default --conf cmake.cache.LEGACY_FLAG=     # clears it
+```
+
+Profile `conf` layers **between recipe and local**: a project's `wyvrn.local.json` (the individual override) still wins over team defaults, and CLI `--conf` still wins over everything. The distinction Conan makes between the `[conf]` block in a profile and the `-c` CLI flag maps directly onto this precedence.
+
+Profile `conf` is **non-ABI**: adding or changing keys inside it does NOT shift `profileHash`, so switching a team policy between `ENABLE_SANITIZERS=ON` and `=OFF` does not invalidate already-downloaded artefacts. The invariant is locked in by `tests/profile-hash.test.js`.
+
+Auto-detected profiles (when no on-disk profile file exists) never inject a `conf` layer — detection is about `[settings]` only.
+
+### CLI — ad-hoc, one invocation
+
+```bash
+# Single toggle
+wyvrnpm build --conf cmake.cache.CHROMA_ENABLE_TEST=ON
+
+# Repeatable
+wyvrnpm build \
+  --conf cmake.cache.CHROMA_ENABLE_TEST=ON \
+  --conf cmake.cache.BUILD_DOCS=OFF
+
+# Bare KEY is sugar for KEY=ON (CMake -D convention)
+wyvrnpm build --conf cmake.cache.CHROMA_ENABLE_TEST
+
+# KEY= (empty RHS) clears a value inherited from a lower layer
+wyvrnpm build --conf cmake.cache.CHROMA_ENABLE_TEST=
+
+# Also honoured on install and publish (publish records it as
+# `publishedConf` on the uploaded manifest — informational metadata
+# that `wyvrnpm show` surfaces).
+wyvrnpm install --conf cmake.cache.CHROMA_ENABLE_TEST=ON
+wyvrnpm publish --conf cmake.cache.BUILD_DOCS=OFF
+```
+
+`--conf` on `wyvrnpm build` passes through to `cmake --preset` as `-D` / `-U` overrides **for that invocation only** — it does not regenerate `CMakePresets.json`. Persistent per-machine overrides belong in `wyvrn.local.json`; `wyvrnpm install` regenerates the preset deterministically with the overlay applied.
+
+### Lockfile semantics
+
+`wyvrn.lock` gains an informational `effectiveConf` block after each install:
+
+```json
+{
+  "wyvrnVersion": 2,
+  "profileHash":  "a1b2c3d4e5f60718",
+  "effectiveConf": {
+    "cmake": { "cache": { "CHROMA_ENABLE_TEST": "ON" } }
+  },
+  "packages": { ... }
+}
+```
+
+This is diagnostic only — changing `conf` between installs shows up as a lockfile diff but never causes a relock or version change. Conf drift is a legitimate review signal, not an error.
+
+### Source-build boundary
+
+When `--build=missing` or `--build=always` source-builds a dependency, **only that dep's own recipe `conf`** flows into its CMake invocation. The root project's merged conf (including `wyvrn.local.json`, named-profile `conf`, and CLI `--conf`) never reaches a dep's source-build. This preserves cross-consumer reproducibility — two developers source-building the same `(name, version, profileHash)` produce the same binary regardless of their local overlays or team profile, which is load-bearing for `--upload-built`.
+
+### Why this isn't `build.configure`
+
+Existing authors using `build.configure: ["-DFOO=ON", "-DBAR=OFF"]` keep working unchanged. But `build.configure` has two weaknesses `conf` fixes:
+
+1. **All-or-nothing.** A consumer can't disable one flag without overriding the whole array.
+2. **Opaque strings.** `"-DFOO=ON"` is parsed at configure time, not at manifest load.
+
+Recipe authors writing new packages should prefer `conf.cmake.cache.FOO=ON` for cache variables and keep `build.configure` for non-cache args like `-G`, `-T`, or `-A`. Setting the same KEY in both `build.configure` (`-DKEY=...`) AND `conf.cmake.cache.KEY` is a recipe-normalise error — pick one route.
+
+---
+
+## Compatibility Rules
+
+Publishers declare an optional `compatibility` block in a package's `wyvrn.json`. It tells wyvrnpm which profile fields must match the consumer's profile exactly, and which may legitimately differ without breaking ABI. When no exact `profileHash` match exists on the registry, `install` evaluates this block against every published build for the requested `(name, version)` and picks the best compatible candidate.
+
+### Block format
+
+Each field maps to a mode — either as a string shorthand or an object:
+
+```json
+{
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "compatibility": {
+    "compiler.cppstd":  "lte",
+    "compiler.runtime": "exact",
+    "compiler.version": "exact-or-newer"
+  }
+}
+```
+
+Object form is accepted too (`{ "mode": "lte" }`) and leaves room for future per-field options.
+
+### Supported modes
+
+| Mode | Meaning |
+|---|---|
+| `exact` | Package and consumer values must be equal. |
+| `any` | Field is ignored for compatibility purposes. |
+| `lte` | Package value ≤ consumer value — e.g. a `cppstd=20` package is usable by a `cppstd=23` consumer. |
+| `gte` | Package value ≥ consumer value (symmetry; rarely useful). |
+| `exact-or-newer` | Same as `lte` at MVP — kept as a distinct name because it reads naturally for compiler-version fields. |
+
+**Defaults:**
+
+- Any field not listed is treated as `exact`.
+- `os` and `arch` are **always `exact`** regardless of what the block says. Cross-OS / cross-arch binaries are never ABI-compatible.
+
+### Where to author it
+
+The block lives in the **source** `wyvrn.json` (the one you commit). It is read at publish time and written into the uploaded manifest. If the source `wyvrn.json` has no `compatibility` block, `wyvrnpm publish` injects a conservative default (all fields `exact`) so existing packages behave strict-by-default.
+
+Consumers never author compatibility — it is a property of the published package.
+
+### Tiebreaker
+
+When multiple published builds satisfy the consumer's profile, the winner is picked deterministically:
+
+1. Prefer the candidate whose `compiler` matches the consumer's.
+2. Prefer the highest numeric `compiler.version`.
+3. Prefer the candidate whose `compiler.runtime` matches the consumer's.
+4. Fall back to the lexicographically earliest `profileHash`.
+
+The chosen candidate is logged along with a per-field summary (e.g. `compiler.cppstd 20→23 (lte), compiler.runtime=dynamic`).
+
+---
+
+## Source Builds
+
+`wyvrnpm install --build=missing` clones a package's source at its published `gitSha` and builds it locally when no prebuilt binary matches (exact or compatible) the consumer's profile. This is the Conan-2.0 `--build=missing` parity feature.
+
+### When it fires
+
+1. You run `wyvrnpm install --build=missing`.
+2. For each dependency, wyvrnpm tries `v2 exact → v2 compat` first.
+3. If neither hits, it looks up `gitRepo` + `gitSha` from **any** existing build of the same `(name, version)` on the registry (they are equal across profiles for a given version).
+4. It clones, resolves the package's own transitive deps, invokes CMake through the shared toolchain generator, zips the install dir, and treats the result as a v2 download.
+
+If the package has no prior publish on the registry at all, there is no `gitSha` to clone — source-build fails fast with a clear error. Source-builds cascade transitively: if package A needs source-build and depends on package B which also needs source-build, both are built.
+
+### Authoring the `build` recipe
+
+Libraries that want to be source-buildable declare a `build` section in their own `wyvrn.json`. See [Project Manifest §Source-build recipe](#source-build-recipe-build) for the field list. Only `system: "cmake"` is supported today.
+
+### Generator fallback
+
+`build.generator` accepts either a string or an array:
+
+| Form | Behaviour |
+|---|---|
+| `"Ninja"` | Strict — fails if Ninja is not available. |
+| `["Ninja", "Visual Studio 17 2022"]` | Tried in order — first available wins. Unknown entries are trusted (CMake decides at configure time). |
+| *(omitted)* | Uses CMake's platform default. |
+
+### MSVC environment auto-activation (Windows)
+
+On Windows, when **all** of the following hold:
+
+- `profile.compiler === "msvc"`
+- The chosen generator is **not** a Visual Studio generator (e.g. Ninja, Make)
+- `cl.exe` is not on `PATH`
+
+…wyvrnpm locates Visual Studio via `vswhere.exe`, runs `vcvarsall.bat <arch>` in a sub-shell, captures the resulting environment, and uses it for the CMake spawn. You do not need to launch from a Developer Prompt.
+
+Arch mapping follows the active profile:
+
+| `profile.arch` | `vcvarsall` arg |
+|---|---|
+| `x86_64` | `x64` |
+| `x86` | `x86` |
+| `armv8` | `arm64` |
+| `armv7` | `arm` |
+
+VS generators skip this path entirely — MSBuild resolves MSVC itself.
+
+### Cache
+
+Source builds are cached machine-wide, keyed by `(name, version, profileHash)`:
+
+| Platform | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\wyvrnpm\bc\{name}-{version}-{profileHash}\` |
+| Linux / macOS | `~/.cache/wyvrnpm/bc/{name}-{version}-{profileHash}/` |
+
+Re-running `install --build=missing` with the same inputs short-circuits to the cached artefact. The cache root is deliberately shallow (`bc/`, not `build-cache/`) to keep nested CMake paths under Windows' 260-char limit.
+
+`--build=always` (2.5.0+) ignores every registry-binary path — exact-match, compat-match, and any already-extracted `wyvrn_internal/{name}/` — and forces a source-build for every dep. Useful for debugging whether a registry binary differs from what the current source tree would produce, or for reproducibility verification. The build-cache short-circuit still applies: re-running `--build=always` with unchanged inputs completes in seconds.
+
+Clone behaviour is tri-tier:
+
+1. **Shallow-SHA fetch** (`git fetch origin <sha> --depth=1`) — fastest; works when the git server allows it.
+2. **Full fetch** — falls back to a full `git clone --tags` when the server rejects shallow-SHA (older Bitbucket installs disable `uploadpack.allowReachableSHA1InWant`).
+3. **Rebuild from scratch** — if the cached clone is broken, wipes and retries.
+
+After every clone/fetch, wyvrnpm runs `git cat-file -e <sha>^{commit}` to verify the SHA is actually reachable. If it is not, the error points at the likely cause: the publisher forgot to push before running `wyvrnpm publish`.
+
+### Publish-time guard
+
+To catch the unpushed-commit case before consumers hit it, `wyvrnpm publish` checks whether the current `HEAD` is reachable from any remote branch or tag and warns if it is not:
+
+```
+[wyvrn] warn: git SHA abc1234 is not on origin — source-build consumers will fail until pushed
+```
+
+The warning does **not** block publishing.
+
+### Header-only libraries
+
+`kind: "HeaderOnlyLib"` packages still need a `build` section and a CMake `install()` rule that copies headers. There is no fast-path that zips the source tree directly — consumers get exactly what the `install()` step produces, same as any other kind.
+
+### Clearing the cache
+
+```bash
+# Remove the project-local cache (wyvrn_internal/ + wyvrn.lock)
+wyvrnpm clean
+
+# Also wipe the machine-wide source-build cache
+wyvrnpm clean --build-cache
+```
+
+### Credentials for private repos
+
+wyvrnpm uses your ambient git configuration (SSH keys, credential helpers, Windows Credential Manager). It does not manage git credentials itself. If `git clone <gitRepo>` works from your shell, source-build works.
+
+### Upload back to the registry (`--upload-built`)
+
+`--build=missing` warms *your* cache. `--build=missing --upload-built` warms the *team's* cache: after a successful source-build, the freshly-zipped artefact is pushed back to the registry under the consumer's `profileHash`, so the next teammate on the same profile gets a direct v2 download.
+
+```bash
+# Build missing artefacts locally AND publish them back under your profile.
+wyvrnpm install --build=missing --upload-built
+
+# Override the upload destination (URL or configured publish-source name).
+wyvrnpm install --build=missing --upload-built --upload-source team-s3
+
+# Upload auth is resolved in order: CLI flag → named-source config → first configured publish source.
+wyvrnpm install --build=missing --upload-built --aws-profile my-sso
+wyvrnpm install --build=missing --upload-built --token-env WYVRN_HTTP_TOKEN
+```
+
+Semantics:
+
+- **Opt-in.** Nothing uploads unless `--upload-built` is passed. Requires `--build=missing`.
+- **Skip if exists.** If `(name, version, profileHash)` already lives on the upload source, the upload is a silent no-op. A consumer cannot overwrite an existing artefact; use `wyvrnpm publish --force` from the source repo for that.
+- **`latest.json` is untouched.** A consumer upload is a new `profileHash` of an existing version, not a new version release.
+- **Upload failures never break the install.** The consumer already has a working `wyvrn_internal/` on disk — a broken upload is logged as a warning and the install continues.
+- **Provenance.** Uploaded manifests carry a small `uploadedBy` block so maintainers can tell consumer builds apart from author publishes:
+
+  ```json
+  {
+    "uploadedBy": {
+      "kind":           "source-build",
+      "profileHash":    "a1b2c3d4e5f60718",
+      "builtFromGit":   "https://github.com/madler/zlib",
+      "builtFromSha":   "abcdef01...",
+      "uploadedAt":     "2026-04-21T12:34:56.789Z",
+      "wyvrnpmVersion": "2.1.0"
+    }
+  }
+  ```
+
+  Absence of `uploadedBy` means the artefact was published by the author via `wyvrnpm publish`.
+
+At the end of an install with `--upload-built`, a one-line summary is printed:
+
+```
+[wyvrn] upload-built summary: 2 artefacts uploaded, 1 skipped (already existed), 0 failed
+```
+
+**Trust model.** Registry write auth is the gate — only consumers with credentials for the upload destination can upload at all. The same `v2Publish` path is used as `wyvrnpm publish`, so the resulting artefact is byte-identical in layout. SHA256 verification on the download side protects against in-transit tampering. Uploading deliberately opts into "your machine's build of this package is trusted by everyone else on this profile" — use CI with clean toolchains rather than developer workstations if you care about reproducibility.
+
+#### Auditing consumer uploads (`wyvrnpm show`)
+
+Maintainers can list every build of a package and tell author-published artefacts apart from consumer uploads:
+
+```bash
+wyvrnpm show zlib                      # all versions + their profile hashes
+wyvrnpm show zlib@1.3.0.0              # every profile for that version, with origin + builtFromSha
+wyvrnpm show zlib@1.3.0.0@a1b2c3d4...  # one specific build, full metadata
+```
+
+With a version specified, `show` fetches each build's `wyvrn.json` and reports `author publish` or `consumer upload (source-build)` alongside the relevant `uploadedBy` fields. Sources default to the configured install sources; override with `--source <url>`.
+
+#### Forgetting uploads (`clean --uploaded-built`)
+
+Each successful upload writes a `.uploaded-to.json` sidecar alongside the cached artefact under `%LOCALAPPDATA%\wyvrnpm\bc\{name}-{version}-{profileHash}\`. It records destination, timestamp, and SHA — purely informational, nothing reads it during install.
+
+To wipe just those local records (no effect on the registry, the artefact zips, or `wyvrn_internal/`):
+
+```bash
+wyvrnpm clean --uploaded-built
+```
+
+This is a privacy / local-audit cleanup knob — `clean --build-cache` already removes sidecars as a side effect of nuking the cache.
+
+---
+
+## Lock File (wyvrn.lock)
+
+The v2 lock file records the full build profile alongside the resolved packages:
+
+```json
+{
+  "wyvrnVersion": 2,
+  "generatedAt": "2025-01-01T00:00:00.000Z",
+  "platform": "win_x64",
+  "profileName": "default",
+  "profile": {
+    "os": "Windows",
+    "arch": "x86_64",
+    "compiler": "msvc",
+    "compiler.version": "193",
+    "compiler.cppstd": "20",
+    "compiler.runtime": "dynamic"
+  },
+  "profileHash": "a1b2c3d4e5f60718",
+  "packages": {
+    "OpenSSL": {
+      "version": "3.0.0.0",
+      "profileHash": "a1b2c3d4e5f60718",
+      "contentSha256": "abc123...",
+      "gitSha": "def456..."
+    }
+  }
+}
+```
+
+Locked versions always take priority over transitive requests. A warning is printed for every version conflict detected.
+
+---
+
+## CMake Integration
+
+`wyvrnpm install` emits a ready-to-use CMake toolchain alongside the downloaded packages. Most projects only need to run:
+
+```bash
+wyvrnpm install
+wyvrnpm build
+```
+
+…which is equivalent to:
+
+```bash
+cmake --preset wyvrn-default
+cmake --build build/wyvrn-default --config Release
+```
+
+**Generated files (inside the project)**
+
+| Path | Purpose |
+|---|---|
+| `wyvrn_internal/wyvrn_toolchain.cmake` | Toolchain file — sets `CMAKE_PREFIX_PATH`, compiler/runtime, and standards from the active profile. Include via the preset or `-DCMAKE_TOOLCHAIN_FILE=…`. |
+| `wyvrn_internal/wyvrn_deps.cmake` | Include **after** `project()` (e.g. `include(${CMAKE_BINARY_DIR}/../wyvrn_internal/wyvrn_deps.cmake)`). Wires `find_package()` calls and defines `wyvrnpm_finalize_targets(<tgt>…)` for runtime DLL copy next to your executable. |
+| `wyvrn_internal/wyvrn_profile.json` | Snapshot of the profile the toolchain was generated against. |
+| `CMakePresets.json` / `CMakeUserPresets.json` | `wyvrn-<profile>` configure preset. Regenerating preserves other profiles' presets. |
+
+**Bundled CMake utilities** (shipped in the npm tarball under `cmake/`) are auto-included by `wyvrn_toolchain.cmake`:
+
+| File | Provides |
+|---|---|
+| `cpp.cmake` | Post-`project()` C++ language defaults. `CMAKE_CXX_STANDARD` is owned by the toolchain (set unconditionally from `profile.compiler.cppstd` before `project()` — a `-DCMAKE_CXX_STANDARD=…` on the cmake CLI cannot override it). |
+| `variables.cmake` | Platform detection (`WYVRN_PLATFORM_WIN`, …) and compiler flags. |
+| `options.cmake` | Feature toggles (`WYVRN_ENABLE_LOG`, …). |
+| `functions.cmake` | `SETUP_LIBRARY` / `SETUP_EXE` plus HAL source-collection helpers. |
+| `macros.cmake` | `WYVRN_INSTALL_MODULE`, `WYVRN_CONFIGURE_VERSION_HEADER`. |
+
+**Minimal `CMakeLists.txt`:**
+
+```cmake
+cmake_minimum_required(VERSION 3.21)
+project(my-app CXX)
+
+include(${CMAKE_SOURCE_DIR}/wyvrn_internal/wyvrn_deps.cmake)
+
+add_executable(my-app src/main.cpp)
+target_link_libraries(my-app PRIVATE OpenSSL::SSL zlib::zlib)
+
+wyvrnpm_finalize_targets(my-app)   # copies runtime DLLs next to the .exe
+```
+
+---
+
+## Installing Build Artifacts (`wyvrnpm build --install`)
+
+`wyvrnpm build --install` runs `cmake --install <binaryDir>` after a successful build, invoking every `install()` rule in your `CMakeLists.txt`. This is the step that produces a redistributable layout (headers + libs + runtime files in a tidy tree) rather than the raw CMake build directory.
+
+### Typical use
+
+```bash
+# Configure, build, and install to the default prefix (baked in at configure time)
+wyvrnpm build --install
+
+# Override the install prefix without reconfiguring
+wyvrnpm build --install --install-prefix C:\out\stage
+
+# Install a specific config
+wyvrnpm build --install --config Debug
+
+# Install multiple configs in one invocation — configure runs once,
+# build + install loops per config. Before 2.9.0 this required two
+# separate `wyvrnpm build --install ...` invocations.
+wyvrnpm build --install --config Debug,Release
+
+# Install every config declared in the recipe's build.configs
+# (or all four canonical configs when no recipe is present).
+wyvrnpm build --install --all-configs
+```
+
+### What it does, in order
+
+1. **Staleness check** — if `wyvrn_internal/wyvrn_toolchain.cmake` is missing or `wyvrn.lock` is newer than it, auto-runs `wyvrnpm install` first. Disable with `--no-auto-install`.
+2. **Optional clean** — `--clean` wipes the build directory before configuring.
+3. **Configure** — `cmake --preset wyvrn-<profile>` (or the value of `--preset`).
+4. **Build** — `cmake --build <binaryDir> --config <config>`.
+5. **Install** — `cmake --install <binaryDir> --config <config> [--prefix <install-prefix>]`.
+
+### `--auto-install` vs `--install`
+
+These two flags are easy to confuse — they control unrelated things:
+
+| Flag | What it does | When it runs |
+|---|---|---|
+| `--auto-install` *(default: on)* | Runs `wyvrnpm install` if the toolchain is stale. Disable with `--no-auto-install`. | **Before** configure. |
+| `--install` *(default: off)* | Runs `cmake --install` after a successful build. | **After** build. |
+
+### `--install-prefix`
+
+CMake bakes `CMAKE_INSTALL_PREFIX` into the build cache at configure time. Passing `--install-prefix` at install time uses `cmake --install --prefix <path>` to override the baked value **without** re-running configure — cheaper than a full reconfigure when you only want to stage to a different location.
+
+If you omit `--install-prefix`, the baked default is used. The baked default comes from the generated preset, typically under `build/wyvrn-<profile>/install`.
+
+### Permissions
+
+Installing to a system path (`/usr/local`, `C:\Program Files`) requires the usual elevated permissions — wyvrnpm does not auto-elevate. For staging or packaging, point `--install-prefix` at a writable user directory instead.
+
+---
+
+## Version Conflict Resolution
+
+When the dependency graph requires the same package at multiple versions, the highest version wins. If a `wyvrn.lock` exists, locked versions always take priority over any conflicting transitive request. A warning is printed for every conflict detected.
+
+---
+
+## Ignoring generated files
+
+Add the following to your `.gitignore`:
+
+```
+wyvrn_internal/
+wyvrn.lock
+*.zip
+```