wyvrnpm 2.3.2 → 2.8.1

package/README.md

@@ -4,7 +4,7 @@ A simple, private C++ package manager that works with any static file hosting pr
 
 There is no central registry. You control where packages are hosted.
 
-> **README version: 2.1.0** — Adds CMake toolchain generation, the `wyvrnpm build` command, declarative compatibility, and `--build=missing` source-build.
+> **README version: 2.8.1** — 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, and a raft of security hardening (Zip Slip, MSVC arch allow-list). Full list in `claude/EVALUATION.md`.
 
 ---
 
@@ -37,16 +37,19 @@ wyvrnpm configure add-source --kind publish --name default  --url s3://my-bucket
 # 3. Detect and save your build environment as the default profile
 wyvrnpm configure profile detect
 
-# 4. Install dependencies (resolved against your build profile)
+# 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
 
-# 5. Configure and build via the generated CMake preset
+# 6. Configure and build via the generated CMake preset
 wyvrnpm build
 
-# 6. Publish your package (uses the active profile automatically)
+# 7. Publish your package (uses the active profile automatically)
 wyvrnpm publish
 
-# 7. (Optional) Link local packages for development
+# 8. (Optional) Link local packages for development
 cd ../my-local-lib && wyvrnpm link
 cd ../my-app && wyvrnpm link my-local-lib
 ```
@@ -94,6 +97,37 @@ 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
@@ -109,6 +143,42 @@ wyvrnpm init --root ./my-project
 
 ---
 
+### `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 install`
 
 Resolves the full dependency graph and downloads all packages.
@@ -122,7 +192,7 @@ Resolves the full dependency graph and downloads all packages.
 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 removed from the default path. It remains reachable for one release cycle via `WYVRNPM_ALLOW_LOOSE_COMPAT=1` and prints a deprecation warning.
+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
@@ -141,6 +211,13 @@ wyvrnpm install \
 
 # 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**
@@ -154,6 +231,8 @@ wyvrnpm install --build=missing
 | `--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.
 
@@ -164,6 +243,35 @@ After download, `install` also generates:
 - `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`
@@ -189,6 +297,10 @@ 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
@@ -210,6 +322,7 @@ wyvrnpm build -- -j 8
 | `--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`. |
@@ -240,7 +353,9 @@ wyvrnpm publish --source default
 # Explicit destination URL
 wyvrnpm publish --source s3://my-bucket/packages --aws-profile my-sso
 
-# HTTP server with token auth
+# 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
@@ -262,6 +377,7 @@ wyvrnpm publish --force
 | `--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). |
@@ -307,6 +423,130 @@ wyvrnpm clean --build-cache
 | 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. |
+
+**CLAUDE.md §9 note for contributors:** the tested path for deploying a locally-edited skill is `node scripts/repack-skill.js && node bin/wyvrn.js install-skill --claude --force` — never `rm -rf` + `cp -r`.
 
 ---
 
@@ -460,7 +700,8 @@ wyvrnpm configure add-source \
 | `--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). |
+| `--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`
 
@@ -862,6 +1103,56 @@ Example:
 }
 ```
 
+### 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.
@@ -956,6 +1247,169 @@ On Windows with MSVC and a non-Visual-Studio generator (Ninja, Make), `vcvarsall
 
 ---
 
+## 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.
@@ -1010,16 +1464,6 @@ When multiple published builds satisfy the consumer's profile, the winner is pic
 
 The chosen candidate is logged along with a per-field summary (e.g. `compiler.cppstd 20→23 (lte), compiler.runtime=dynamic`).
 
-### Legacy loose fallback
-
-The pre-2.1 "same OS + arch, any compiler" fallback is removed from the default resolution path. For one release cycle it remains reachable via an env var:
-
-```bash
-WYVRNPM_ALLOW_LOOSE_COMPAT=1 wyvrnpm install
-```
-
-This prints a deprecation warning every time it fires and will be removed in the next minor release. Prefer adding a real `compatibility` block to affected packages, or rebuilding with `--build=missing`.
-
 ---
 
 ## Source Builds
@@ -1081,6 +1525,8 @@ Source builds are cached machine-wide, keyed by `(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.
@@ -1130,7 +1576,7 @@ 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 mytoken
+wyvrnpm install --build=missing --upload-built --token-env WYVRN_HTTP_TOKEN
 ```
 
 Semantics: