wyvrnpm 2.1.0 → 2.4.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.4.0** — Highlights since 2.1.0: `wyvrnpm add <name>` for dependency authoring, `HeaderOnlyLib` packages that survive cross-arch `find_package()`, `WYVRN_ARCH_SUFFIX` + the `WYVRN_APPLY_ARCH_SUFFIX(<target>)` helper so x64/x86 artefacts coexist on disk, `wyvrnpm build --generator / -G` to swap CMake generators from the CLI, package `options`, version ranges (`^`, `~`, explicit comparators), `--format=json` output, and `--upload-built` to warm the registry with source-built artefacts.
 
 ---
 
@@ -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
 ```
@@ -109,6 +112,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.
@@ -164,6 +203,25 @@ 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.
+
+```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 +247,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 +272,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`. |
@@ -518,6 +581,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:
@@ -733,7 +891,97 @@ 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`)
 
@@ -932,6 +1180,77 @@ wyvrnpm clean --build-cache
 
 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.
+
 ---
 
 ## Lock File (wyvrn.lock)

package/bin/wyvrn.js

@@ -3,13 +3,16 @@
 'use strict';
 
 const yargs     = require('yargs');
-const init      = require('../src/commands/init');
-const install   = require('../src/commands/install');
-const clean     = require('../src/commands/clean');
-const publish   = require('../src/commands/publish');
-const configure = require('../src/commands/configure');
-const profile   = require('../src/commands/profile');
-const build     = require('../src/commands/build');
+const init         = require('../src/commands/init');
+const add          = require('../src/commands/add');
+const install      = require('../src/commands/install');
+const clean        = require('../src/commands/clean');
+const publish      = require('../src/commands/publish');
+const configure    = require('../src/commands/configure');
+const profile      = require('../src/commands/profile');
+const build        = require('../src/commands/build');
+const show         = require('../src/commands/show');
+const installSkill = require('../src/commands/install-skill');
 const { link, unlink } = require('../src/commands/link');
 
 yargs
@@ -33,6 +36,34 @@ yargs
     (argv) => init(argv),
   )
 
+  // ── add ───────────────────────────────────────────────────────────────────
+  .command(
+    'add <packages...>',
+    'Add dependencies to wyvrn.json. Without @version, resolves latest and writes "^<latest>"; ' +
+    'with @version, writes the given string verbatim. Does not run install.',
+    (y) => {
+      y
+        .positional('packages', {
+          type: 'string',
+          array: true,
+          describe: 'One or more <name>[@<version>] specs',
+        })
+        .option('source', {
+          alias: 's',
+          type: 'string',
+          description: 'Base URL of a package source for `latest` lookup (can be repeated)',
+          array: true,
+        })
+        .option('platform', {
+          type: 'string',
+          description: 'v1 legacy platform path (used as fallback when looking up latest)',
+          choices: ['win_x64', 'win_x86', 'linux_x64', 'linux_x86', 'osx_x64', 'osx_arm64'],
+          default: 'win_x64',
+        });
+    },
+    (argv) => add(argv),
+  )
+
   // ── install ───────────────────────────────────────────────────────────────
   .command(
     'install',
@@ -58,6 +89,36 @@ yargs
             'Resolution mode when no exact profile match exists. ' +
             'never=fail; missing=build from source (pending phase 3); always=rebuild (pending phase 3)',
         })
+        .option('option', {
+          alias: 'o',
+          type: 'string',
+          array: true,
+          description:
+            'Override a package option. Repeatable. Format: <pkg>:<name>=<value>. ' +
+            'Example: -o zlib:minizip=false -o OpenSSL:fips=true',
+        })
+        .option('upload-built', {
+          type: 'boolean',
+          default: false,
+          description:
+            'After successful --build=missing, upload each source-built artefact ' +
+            'back to the registry under the active profileHash so the next consumer ' +
+            'gets a direct download. Requires write credentials for the upload source.',
+        })
+        .option('upload-source', {
+          type: 'string',
+          description:
+            'Destination for --upload-built (URL or configured publish-source name). ' +
+            'Defaults to the first configured publish source.',
+        })
+        .option('aws-profile', {
+          type: 'string',
+          description: 'AWS SSO profile for --upload-built when uploading to S3',
+        })
+        .option('token', {
+          type: 'string',
+          description: 'Bearer token for --upload-built when uploading to HTTP',
+        })
         .option('platform', {
           type: 'string',
           description: 'v1 legacy platform path (used as fallback if v2 not found)',
@@ -68,9 +129,20 @@ yargs
           type: 'number',
           description: 'HTTP timeout in seconds',
           default: 300,
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits a single JSON object on stdout; log lines go to stderr.',
         });
     },
-    (argv) => install(argv),
+    (argv) => install({
+      ...argv,
+      uploadBuilt:  argv['upload-built'],
+      uploadSource: argv['upload-source'],
+      awsProfile:   argv['aws-profile'],
+    }),
   )
 
   // ── build ─────────────────────────────────────────────────────────────────
@@ -113,6 +185,13 @@ yargs
           default: false,
           description: 'Remove the build directory before configuring',
         })
+        .option('generator', {
+          alias: 'G',
+          type: 'string',
+          description:
+            'Override the preset\'s CMake generator (e.g. "Visual Studio 17 2022", "Ninja", "Ninja Multi-Config"). ' +
+            'CMake locks the generator into the build-dir cache, so pair this with --clean when switching generators.',
+        })
         .option('install', {
           type: 'boolean',
           default: false,
@@ -155,13 +234,60 @@ yargs
     'clean',
     'Remove downloaded packages and lock file. --build-cache also wipes the machine-wide source-build cache.',
     (y) => {
-      y.option('build-cache', {
-        type: 'boolean',
-        default: false,
-        description: 'Also remove the source-build cache under %LOCALAPPDATA%\\wyvrnpm\\bc\\',
-      });
+      y
+        .option('build-cache', {
+          type: 'boolean',
+          default: false,
+          description: 'Also remove the source-build cache under %LOCALAPPDATA%\\wyvrnpm\\bc\\',
+        })
+        .option('uploaded-built', {
+          type: 'boolean',
+          default: false,
+          description:
+            'Wipe only the local record of artefacts uploaded via --upload-built ' +
+            '(the .uploaded-to.json sidecars in the build cache). Does not touch ' +
+            'the registry, the artefact zips, or wyvrn_internal/.',
+        });
     },
-    (argv) => clean({ ...argv, buildCache: argv['build-cache'] }),
+    (argv) => clean({
+      ...argv,
+      buildCache:     argv['build-cache'],
+      uploadedBuilt:  argv['uploaded-built'],
+    }),
+  )
+
+  // ── show ──────────────────────────────────────────────────────────────────
+  .command(
+    'show <pkg>',
+    'Display registry metadata for a package. Surfaces `uploadedBy` so consumer uploads can be told apart from author publishes.',
+    (y) => {
+      y
+        .positional('pkg', {
+          type: 'string',
+          description: 'Spec: <name>[@<version>[@<profileHash>]]',
+        })
+        .option('source', {
+          alias: 's',
+          type: 'string',
+          array: true,
+          description: 'Source URL(s) to query; defaults to configured install sources',
+        })
+        .option('aws-profile', {
+          type: 'string',
+          description: 'AWS SSO profile for S3 sources',
+        })
+        .option('token', {
+          type: 'string',
+          description: 'Bearer token for HTTP sources',
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits a single JSON object on stdout; log lines go to stderr.',
+        });
+    },
+    (argv) => show({ ...argv, awsProfile: argv['aws-profile'] }),
   )
 
   // ── publish ───────────────────────────────────────────────────────────────
@@ -200,6 +326,20 @@ yargs
           description: 'Overwrite an existing published version',
           default: false,
         })
+        .option('option', {
+          alias: 'o',
+          type: 'string',
+          array: true,
+          description:
+            'Override an option value at publish time. Repeatable. ' +
+            'Format: <pkg>:<name>=<value> (pkg must match the package being published).',
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits a single JSON object on stdout; log lines go to stderr.',
+        })
         ;
     },
     (argv) => publish({ ...argv, awsProfile: argv['aws-profile'] }),
@@ -365,6 +505,19 @@ yargs
     (argv) => unlink(argv),
   )
 
+  // ── install-skill ─────────────────────────────────────────────────────────
+  .command(
+    'install-skill',
+    'Install the bundled wyvrnpm Agent Skill into Claude Code (~/.claude/skills/wyvrnpm/)',
+    (y) => {
+      y
+        .option('claude',  { type: 'boolean', description: 'Install for Claude Code',            default: false })
+        .option('force',   { type: 'boolean', description: 'Overwrite an existing installation', default: false })
+        .option('dry-run', { type: 'boolean', description: 'Report actions without writing',     default: false });
+    },
+    (argv) => installSkill(argv),
+  )
+
   .demandCommand(1)
   .strict()
   .help()