wyvrnpm 2.0.4 → 2.3.2

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.0.1** — Last updated to reflect the v2 build-profile system.
+> **README version: 2.1.0** — Adds CMake toolchain generation, the `wyvrnpm build` command, declarative compatibility, and `--build=missing` source-build.
 
 ---
 
@@ -40,10 +40,13 @@ wyvrnpm configure profile detect
 # 4. Install dependencies (resolved against your build profile)
 wyvrnpm install
 
-# 5. Publish your package (uses the active profile automatically)
+# 5. Configure and build via the generated CMake preset
+wyvrnpm build
+
+# 6. Publish your package (uses the active profile automatically)
 wyvrnpm publish
 
-# 6. (Optional) Link local packages for development
+# 7. (Optional) Link local packages for development
 cd ../my-local-lib && wyvrnpm link
 cd ../my-app && wyvrnpm link my-local-lib
 ```
@@ -112,7 +115,14 @@ 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 matched first by exact profile hash; if no exact match is found, the tool looks for a compatible build (same OS + arch, any compiler), then falls back to the v1 legacy path.
+**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 removed from the default path. It remains reachable for one release cycle via `WYVRNPM_ALLOW_LOOSE_COMPAT=1` and prints a deprecation warning.
 
 ```bash
 # Use configured sources and the default build profile
@@ -128,6 +138,9 @@ wyvrnpm install --source https://pkg.example.com/cpp
 wyvrnpm install \
   --source https://primary.example.com/cpp \
   --source https://mirror.example.com/cpp
+
+# Build any missing binary from source
+wyvrnpm install --build=missing
 ```
 
 **Options**
@@ -136,6 +149,7 @@ wyvrnpm install \
 |---|---|---|
 | `--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. |
@@ -143,6 +157,66 @@ wyvrnpm install \
 
 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.
+
+---
+
+### `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
+
+# 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
+
+# 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`). |
+| `--target` / `-t` | *(all)* | Specific CMake target to build. |
+| `--verbose` / `-v` | `false` | Pass `--verbose` to `cmake --build`. |
+| `--clean` | `false` | Remove the build directory before configuring. |
+| `--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`
@@ -221,9 +295,19 @@ build/
 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/`). |
+
 ---
 
 ### `wyvrnpm link`
@@ -434,6 +518,101 @@ wyvrnpm configure profile delete msvc_release
 
 ---
 
+## 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:
@@ -649,7 +828,365 @@ Fields use PascalCase. `Dependencies` is an array — transitive dependencies ar
 
 **`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` and an optional `settings` 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.
+**`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"
+  }
+}
+```
+
+### 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.
+
+---
+
+## 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`).
+
+### 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
+
+`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.
+
+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 mytoken
+```
+
+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.
 
 ---
 
@@ -687,6 +1224,103 @@ Locked versions always take priority over transitive requests. A warning is prin
 
 ---
 
+## 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
+```
+
+### 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.