wyvrnpm 2.20.2 → 2.21.1

package/README.md

@@ -4,7 +4,21 @@ 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.15.0**
+> **README version: 2.20.2**
+>
+> **New in 2.16.0 – 2.20.2:**
+>
+> - **Visual Studio architecture pinning (2.20.0).** A recipe-less Windows/MSVC consumer (one that only lists `dependencies`, no `build` recipe) used to get a generator-less `wyvrn-<profile>` preset, so `cmake --preset` fell through to CMake's implicit Visual Studio default — which targets the **host** arch (x64) when no `-A` is supplied. An `x86` / `armv8` profile therefore silently produced 64-bit binaries. `wyvrnpm install` now detects the default VS generator and bakes both `generator` and `architecture` into the emitted preset, and `wyvrnpm build` derives `-A` (`x86→Win32`, `x86_64→x64`, `armv8→ARM64`, `armv7→ARM`) for VS generators. Builds now match the profile's bitness without a recipe. (Already-published non-host-arch artefacts built via the old source-build path may still hold wrong-bitness binaries — those are rebuilt + republished out of band.)
+> - **`wyvrnpm build` resolves the generator from the emitted preset, not the recipe (2.20.2).** The configure step now reads the generator that `cmake --preset` will *actually* use — precedence: CLI `--generator` > the `generator` baked into `CMakePresets.json` > the detected default for a generator-less preset. This drives both the `-A` pin and the vcvarsall-skip decision, so they stay consistent with reality. Fixes a class of failures where a Ninja Multi-Config preset got `-A x64` ("does not support platform specification") and skipped vcvarsall ("CMAKE_CXX_COMPILER not set") because the old code re-derived the generator from the recipe — which can legitimately diverge from the preset (an install-time `--generator`, or a recipe edited after the last install).
+> - **CMake-path fallback (2.20.1).** `install` / `build` / source-build no longer fail outright on a machine where CMake isn't on `PATH` — `resolveCmakeExe()` falls back to the Windows default `C:\Program Files\CMake\bin\cmake.exe` before surfacing the usual "is CMake installed?" error.
+> - **Machine-wide binary package cache (2.19.0).** Every successful v2 exact-match download is also cached under `%LOCALAPPDATA%\wyvrnpm\pkg\` (14-day TTL) so re-installs across projects skip the network. `wyvrnpm cache list` / `cache prune` gain a `--type src|pkg|all` selector covering both this and the source-build cache, and `wyvrnpm clean --pkg-cache` wipes it.
+> - **`wyvrnpm test` (2.18.0).** A `ctest --preset wyvrn-<profile>-<config>` wrapper that auto-builds when stale, supports `-R` / `-L` filters and `--all-configs`, and emits a `--format json` summary for CI.
+> - **Output directory restructure (2.17.0).** Compiled artefacts now land inside the CMake binary dir (`<binaryDir>/lib`, `<binaryDir>/bin`) instead of `${CMAKE_SOURCE_DIR}/output/`, so `wyvrnpm clean --all` actually catches them. Scripts that hard-coded `output/bin64/…` must switch paths — `clean --all` sweeps the legacy `output/` tree as a migration aid.
+> - **`wyvrnpm clean` flags (2.16.0).** `--build-dir` (also wipe the active profile's CMake build tree), `--all` (scorched-earth: build dirs + `wyvrn-*` presets + legacy `output/`), and `--dry-run` (preview, write nothing).
+>
+> **Planned (not yet shipped):**
+>
+> - **Resolver → provider unification.** Today the dependency resolver (`resolve.js` / `download.js`) talks to registries through a bare `fetch` client that hard-codes the v2/v1 URL layouts, separate from the provider classes that handle publish + download. The plan is to route all metadata lookups through provider methods (`v2GetVersionsIndex` / `v2GetMeta` / `v2GetLatest` / `v1*`) so S3 SigV4, auth resolution, and provider-specific quirks live in one place. Design captured in [.claude-wyvrn-local/plans/2026-04-24-resolver-http-unify.md](.claude-wyvrn-local/plans/2026-04-24-resolver-http-unify.md). The 2.8.4 `Accept-Encoding: identity` hotfix covers the immediate CloudFront cache-split symptom in the meantime.
 >
 > **New in 2.15.0:**
 >
@@ -371,7 +385,7 @@ 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.
+- `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. On Windows/MSVC the preset is pinned to a concrete Visual Studio `generator` **and** `architecture` (derived from the profile arch) even when the project carries no `build` recipe — so a recipe-less `x86` / `armv8` consumer builds the correct bitness instead of CMake's implicit host-x64 default (2.20.0). Declare a `build.generator` (or a `CMakeUserPresets.json`) to opt into Ninja/Make instead.
 
 **Toolchain variables exposed to your `CMakeLists.txt` (valid BEFORE `project()`)**:
 
@@ -471,6 +485,8 @@ wyvrnpm build -- -j 8
 
 Everything after `--` is forwarded verbatim to `cmake --build` (e.g. `-j 8`).
 
+**How the effective generator is resolved (2.20.2+).** `wyvrnpm build` decides the `-A` arch pin and the vcvarsall-skip from the generator `cmake --preset` will *actually* use — not the project's `build` recipe. Precedence: CLI `--generator` (wins, passed as `-G`) → the `generator` baked into `CMakePresets.json` at install time → the detected default Visual Studio generator for a generator-less preset. Trusting the preset matters because it can legitimately diverge from the recipe (an install-time `--generator`, or a recipe edited after the last install); pinning `-A` against a non-VS preset is a hard CMake error, so the two decisions must agree with what cmake runs.
+
 ---
 
 ### `wyvrnpm test` (2.18.0+)
@@ -620,16 +636,32 @@ Removes the `wyvrn_internal/` package cache and `wyvrn.lock`.
 # Project-local cleanup
 wyvrnpm clean
 
+# Also wipe the active profile's CMake build tree
+wyvrnpm clean --build-dir
+
+# Scorched earth: build dirs + wyvrn-* presets + legacy output/ tree
+wyvrnpm clean --all
+
 # Also wipe the machine-wide source-build cache used by --build=missing
 wyvrnpm clean --build-cache
+
+# Also wipe the machine-wide binary package cache
+wyvrnpm clean --pkg-cache
+
+# Preview every action without deleting anything
+wyvrnpm clean --all --dry-run
 ```
 
 **Options**
 
 | Option | Default | Description |
 |---|---|---|
+| `--build-dir` | `false` | Also remove the active profile's CMake build tree at `<binaryDirRoot>/wyvrn-<profile>/`. |
+| `--all` | `false` | Default scrub **plus** every `<binaryDirRoot>/wyvrn-*/` build dir, the `wyvrn-*` entries stripped from `CMakePresets.json`, and the legacy `<root>/output/` tree (2.17.0 migration aid). |
 | `--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/`. |
+| `--pkg-cache` | `false` | Also remove the machine-wide binary package cache under `%LOCALAPPDATA%\wyvrnpm\pkg\` (2.19.0). Opt-in only — never wiped by the default scrub or `--all`. |
+| `--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/`. When passed alone, the default scrub is skipped. |
+| `--dry-run` | `false` | Log `Would remove …` for every action and write nothing. |
 
 For selective cache pruning (keep last N variants, drop entries older than N days), use `wyvrnpm cache prune` instead — see below.
 
@@ -637,12 +669,22 @@ For selective cache pruning (keep last N variants, drop entries older than N day
 
 ### `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.
+Inspect and selectively prune the two machine-wide caches. Useful once cache size balloons on dev rigs — `clean --build-cache` / `clean --pkg-cache` are the blunt alternatives that wipe everything of one type.
+
+| Type | Location | Populated by | TTL |
+|---|---|---|---|
+| `src` | `%LOCALAPPDATA%\wyvrnpm\bc\` (Unix: `~/.cache/wyvrnpm/bc/`) | source-builds (`--build=missing`) | none |
+| `pkg` | `%LOCALAPPDATA%\wyvrnpm\pkg\` | every successful v2 exact-match download (2.19.0+) | 14 days |
+
+`--type src|pkg|all` (default `all`) restricts both `list` and `prune` to one cache.
 
 ```bash
-# List every cached entry as a table
+# List every cached entry across both caches as a table
 wyvrnpm cache list
 
+# Only the binary package cache
+wyvrnpm cache list --type pkg
+
 # Filter by package name (glob)
 wyvrnpm cache list "boost*"
 
@@ -652,8 +694,8 @@ 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
+# Prune only the source-build cache, dropping entries older than 30 days
+wyvrnpm cache prune --type src --older-than 30d
 
 # Combine: keep 1 recent per version AND drop anything stale
 wyvrnpm cache prune --keep-last 1 --older-than 30d
@@ -667,12 +709,14 @@ wyvrnpm cache prune --keep-last 2 --dry-run
 | Option | Default | Description |
 |---|---|---|
 | `[pattern]` / `--pattern` | *(none)* | Glob over package names (`*` for any chars, `?` for one). |
+| `--type` | `all` | Which cache to inspect: `src` (source-build), `pkg` (binary), or `all`. |
 | `--format` | `text` | `text` (table) or `json` (structured payload for CI). |
 
 **`cache prune` options**
 
 | Option | Default | Description |
 |---|---|---|
+| `--type` | `all` | Which cache to prune: `src` (source-build), `pkg` (binary), or `all`. |
 | `--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. |
@@ -729,10 +773,13 @@ Useful for: auditing consumer uploads (who pushed this artefact, from which comm
 
 ### `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.
+Installs the bundled Claude Code assets that ship inside the npm package:
+
+- The **wyvrnpm Agent Skill** — the authoring guide Claude uses when it sees a `wyvrn.json` in the workspace. Ships as a `.skill` zip (`claude/skills/wyvrnpm.skill`), extracted into `~/.claude/skills/wyvrnpm/`.
+- The **onboarding agent(s)** — e.g. `wyvrnpm-onboarding`, which sets up a project to consume wyvrnpm deps or converts an existing CMake project into a wyvrnpm package. Ships as Markdown (`claude/agents/*.md`), copied into `~/.claude/agents/`.
 
 ```bash
-# One-shot: install the bundled skill for Claude Code
+# One-shot: install the bundled skill + agent(s) for Claude Code
 wyvrnpm install-skill --claude
 
 # Overwrite an existing installation (e.g. after upgrading wyvrnpm)
@@ -742,7 +789,7 @@ wyvrnpm install-skill --claude --force
 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.
+You only need this if you want Claude Code to pick up the skill + agent. The CLI itself works without it.
 
 **Options**
 

package/bin/wyvrnpm.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 
@@ -1098,8 +1098,9 @@ yargs
       y
         .positional('name', { type: 'string', description: 'Package name to link' })
         .positional('path', { type: 'string', description: 'Local path to package' })
-        .option('list',   { type: 'boolean', description: 'List all globally registered packages', default: false })
-        .option('subdir', { type: 'string',  description: 'Subdirectory within the package to link' });
+        .option('list',    { type: 'boolean', description: 'List all globally registered packages', default: false })
+        .option('subdir',  { type: 'string',  description: 'Subdirectory within the package to link' })
+        .option('profile', { type: 'string',  description: 'Profile whose install tree to register (default: config default)' });
     },
     (argv) => link(argv),
   )
@@ -1126,7 +1127,7 @@ yargs
   // ── install-skill ─────────────────────────────────────────────────────────
   .command(
     'install-skill',
-    'Install the bundled wyvrnpm Agent Skill into Claude Code (~/.claude/skills/wyvrnpm/)',
+    'Install the bundled wyvrnpm Agent Skill + onboarding agent(s) into Claude Code (~/.claude/skills/ + ~/.claude/agents/)',
     (y) => {
       y
         .option('claude',  { type: 'boolean', description: 'Install for Claude Code',            default: false })

package/claude/agents/README.md

@@ -0,0 +1,159 @@
+# wyvrnpm Agents
+
+Claude Code **subagents** that ship with wyvrnpm. A subagent is a separate
+Claude worker with its own context window, tool access, and a clean return
+boundary — you delegate a self-contained task to it and get back a result,
+without the back-and-forth cluttering your main conversation.
+
+These are distributed the same way as the wyvrnpm **skill**: the source lives
+here under `claude/agents/`, and an active copy is placed in your user-global
+`~/.claude/agents/` so Claude Code picks it up in every project.
+
+> Skill vs. agent: the **skill** (`claude/skills/wyvrnpm/`) is *knowledge* — it
+> teaches Claude how wyvrnpm works. An **agent** is an *execution context* that
+> does a job, loading the skill for reference. The onboarding agent below uses
+> the skill; it does not replace it.
+
+---
+
+## `wyvrnpm-onboarding`
+
+### What it is
+
+A guided agent that gets a C++ developer who is **new to wyvrnpm** productive in
+one shot. It handles two distinct goals and figures out which one you want:
+
+| Mode | Goal | What it does |
+|---|---|---|
+| **A — Consume** | "I want to *use* libraries from our team registry in this project." | Configures the install source + profile, writes `wyvrn.json`, runs `wyvrnpm install`, wires your `CMakeLists.txt` (`wyvrnpm_find_dependencies()`, `wyvrn::<dep>` links, runtime-DLL copy), and confirms the build configures. |
+| **B — Convert / publish** | "I want to turn *this* library into a wyvrnpm package others can depend on." | Reads your `CMakeLists.txt`, picks `kind` / `options` / a `build` recipe, writes `wyvrn.json` + `.wyvrnignore`, then **verifies** by running `wyvrnpm install` and `wyvrnpm build --install --all-configs` across all four configs. Hands you a ready-to-run `publish` command — it never publishes itself. |
+
+### Why it exists
+
+wyvrnpm has no central registry and a few first-day gotchas (4-part versions,
+profile hashes, per-config install trees, `.wyvrnignore`). This agent removes
+the "I don't know where to start" barrier so teammates can adopt the tool
+without reading the full docs first.
+
+### Prerequisites
+
+- **wyvrnpm installed:** `npm i -g wyvrnpm` (Node.js ≥ 18). The agent checks
+  this first and stops if it's missing.
+- **For Mode A (consume):** your team's install source URL (an S3 bucket, HTTPS
+  endpoint, or file/SMB share). The agent will configure it for you if it isn't
+  already — wyvrnpm has no default registry, so this is required to fetch
+  anything.
+- **Claude Code**, with the agent installed (see below).
+
+### Install / make it active
+
+The agent file is a single Markdown file with YAML frontmatter. Put a copy where
+Claude Code looks for agents:
+
+The supported path is the wyvrnpm CLI — `install-skill` installs the bundled
+agent(s) alongside the skill:
+
+```bash
+npm i -g wyvrnpm
+wyvrnpm install-skill --claude        # installs skill -> ~/.claude/skills/
+                                      # AND agent(s) -> ~/.claude/agents/
+wyvrnpm install-skill --claude --force   # overwrite after upgrading wyvrnpm
+```
+
+Or copy the file by hand:
+
+```bash
+# Personal — available in every project on your machine:
+mkdir -p ~/.claude/agents
+cp claude/agents/wyvrnpm-onboarding.md ~/.claude/agents/
+
+# OR project-local — shared with everyone who clones that repo:
+mkdir -p <your-repo>/.claude/agents
+cp claude/agents/wyvrnpm-onboarding.md <your-repo>/.claude/agents/
+```
+
+Claude Code picks it up on the next session start.
+
+### How to use it
+
+**Implicitly** — just describe an onboarding task while you're in a C++ repo and
+Claude routes to the agent:
+
+- "Set up wyvrnpm in this project."
+- "Add wyvrnpm and pull in `fmt` and `spdlog`."
+- "Convert this library into a wyvrnpm package."
+- "Make this repo publishable on our registry."
+- "How do I start with wyvrnpm here?"
+
+**Explicitly** — name it: *"Use the wyvrnpm-onboarding agent to set this up."*
+
+If it can't tell whether you want Mode A or Mode B, it asks one short question
+rather than guessing.
+
+### What you get back
+
+Every run ends with:
+
+1. A summary — which mode it ran, the files it created/changed, and what it
+   **verified** (e.g. "install OK; all 4 configs built + installed").
+2. The single next command to run yourself — for Mode B that's the exact
+   `wyvrnpm publish …` line plus the pre-publish checklist; for Mode A it's
+   "you're ready to build."
+3. If something failed: the specific error and how it was fixed, or what's still
+   blocked. It won't claim success on an unvalidated manifest.
+
+### Safety — it never writes to your team's registry
+
+Onboarding is meant to be safe to run. The agent will **not** run any command
+that writes to shared team state without your explicit confirmation:
+
+- `wyvrnpm publish` / `publish --force` — it always stops here and hands the
+  command back to you.
+- `wyvrnpm install --upload-built` — also a registry write.
+- `wyvrnpm configure remove-source`.
+
+Everything else it runs is local and reversible (`install`, `build`, `clean`,
+`init`, `bootstrap`, `show`, `link`, profile/source *reads*). For
+`configure add-source` it shows you the URL/credentials before writing them.
+
+### Example
+
+```text
+You (in an app repo):  "set up wyvrnpm here and add fmt"
+
+Agent:
+  • wyvrnpm --version → 2.21.0  ✓
+  • No install source configured — what's your team's registry URL?
+You:  https://pkg.example.com/cpp
+Agent:
+  • configure add-source --kind install --name primary --url https://pkg.example.com/cpp
+  • profile detect → saved "default" (Windows / x86_64 / msvc 193 / C++20)
+  • wyvrnpm init → wyvrn.json (kind: ConsoleApp)
+  • wyvrnpm add fmt → "^10.x"
+  • wyvrnpm install → downloaded fmt, generated toolchain + CMakePresets.json
+  • patched CMakeLists.txt: wyvrnpm_find_dependencies();
+    target_link_libraries(MyApp PRIVATE wyvrn::fmt); wyvrnpm_finalize_targets()
+  • cmake --preset wyvrn-default → configured OK
+
+  Summary: consuming mode. fmt wired in and the build configures.
+  Next: wyvrnpm build
+```
+
+### Customizing
+
+The agent is just `wyvrnpm-onboarding.md`. Edit the frontmatter to change:
+
+- `model:` — defaults to `sonnet` (cheap/fast for procedural work); bump to
+  `opus` for trickier conversions.
+- `tools:` — the allowlist (`Read, Grep, Glob, Edit, Write, Bash, Skill`).
+
+The body is the system prompt; it loads the `wyvrnpm` skill for authoritative
+command and manifest detail, so keep the two in sync.
+
+### Out of scope
+
+It deliberately does **not**: publish for you, set up CI pipelines, or handle
+cross-compilation / recipe revisions (features not yet shipped). For deep
+manifest, command, or diagnostic questions it defers to the `wyvrnpm` skill and
+the user docs (README / the Confluence "Wyvrn Package Manager" and "WyvrnPM
+Cmake Utils" pages).

package/claude/agents/wyvrnpm-onboarding.md

@@ -0,0 +1,131 @@
+---
+name: wyvrnpm-onboarding
+description: >-
+  Onboard a C++ project onto wyvrnpm. Use this agent when someone wants to adopt
+  wyvrnpm and is not yet familiar with it — either (A) SET UP a new or existing
+  project to CONSUME wyvrnpm dependencies, or (B) CONVERT an existing CMake
+  project into a publishable wyvrnpm package. Triggers on "set up wyvrnpm here",
+  "add wyvrnpm to my project", "use wyvrnpm for my deps", "convert this to
+  wyvrnpm", "make this a wyvrnpm package", "how do I start with wyvrnpm", or a
+  teammate opening a C++ repo that has no wyvrn.json yet and asking to get going.
+  Drives the end-to-end flow — manifest, install, CMake wiring, and per-config
+  build verification — and STOPS before any registry-writing publish.
+tools: Read, Grep, Glob, Edit, Write, Bash, Skill
+model: sonnet
+---
+
+You are the wyvrnpm onboarding guide. Your job is to get a C++ developer who is
+**new to wyvrnpm** productive: either consuming dependencies through it, or
+turning their project into a publishable wyvrnpm package. Assume the person does
+not know wyvrnpm yet — explain briefly as you go, and prefer running the safe
+commands for them over telling them to run things.
+
+wyvrnpm is a private, registry-less C++ package manager (a Node.js CLI,
+`npm i -g wyvrnpm`). It publishes/consumes prebuilt C++ artefacts through static
+hosting (S3 / HTTP / local dir / SMB). Every artefact is addressed by
+`(name, version, profileHash)` where the hash encodes the toolchain profile +
+package options, so ABI compatibility is explicit. Versions are 4-part
+`major.minor.patch.build`.
+
+## First, always
+
+1. **Load the `wyvrnpm` skill** (invoke it via the Skill tool). It is the
+   authoritative reference for manifest fields, commands, and diagnostics. This
+   prompt is the orchestration; the skill is the detail. When the skill and this
+   prompt disagree, trust the skill, then the live tool output.
+2. **Check the tool is installed:** run `wyvrnpm --version`. If it's missing,
+   tell them to `npm i -g wyvrnpm` (Node ≥ 18) and stop until it's available.
+3. **Detect the mode** (see below). If it's genuinely ambiguous, ask one short
+   question — do not guess.
+
+## Pick the mode
+
+There are two distinct goals. Figure out which one applies before doing anything:
+
+- **A — CONSUME** (most common for app/teammate onboarding): "I want to *use*
+  C++ libraries from our team registry in this project." → you'll add
+  `dependencies`, run `install`, and wire CMake so `find_package` works.
+- **B — CONVERT/PUBLISH**: "I want to turn *this* library into a wyvrnpm package
+  others can depend on." → you'll write a `kind` + `build` recipe + options,
+  build all configs, and hand back a ready-to-run `publish` (you never publish).
+
+Signals: a project with `add_executable` that wants third-party libs → usually A.
+An existing OSS/library repo (`add_library`, has a public `include/`) they want
+to share → usually B. If both could apply, ask.
+
+## Mode A — set up a project to consume wyvrnpm deps
+
+1. **Install source.** Run `wyvrnpm configure list`. If no install source is
+   configured, explain that wyvrnpm has no default registry and ask them for the
+   team's source URL, then `wyvrnpm configure add-source --kind install --name
+   <name> --url <url>` (show the URL/credentials before writing). Without a
+   source, `install` can't fetch anything.
+2. **Profile.** Run `wyvrnpm configure profile show`. If none is saved, run
+   `wyvrnpm configure profile detect` (saves "default") so artefacts resolve to
+   their machine's toolchain.
+3. **Manifest.** If there's no `wyvrn.json`, run `wyvrnpm init` (or copy a
+   per-kind template from the skill's `templates/`). Set `name`, a 4-part
+   `version`, and `kind` (usually `ConsoleApp`).
+4. **Add deps.** For each library they want, `wyvrnpm add <name>` (resolves
+   latest, writes a caret range) or `wyvrnpm add <name>@<version>`.
+5. **Install.** `wyvrnpm install`. This downloads to `wyvrn_internal/`, writes
+   `wyvrn.lock`, and generates the CMake toolchain + `CMakePresets.json`.
+6. **Wire CMake.** In their top-level `CMakeLists.txt`, after `project()`:
+   call `wyvrnpm_find_dependencies()`, then `target_link_libraries(<tgt> PRIVATE
+   wyvrn::<dep> ...)`, and `wyvrnpm_finalize_targets()` at the end (copies
+   runtime DLLs on Windows). Configure via the generated preset:
+   `cmake --preset wyvrn-default` then `wyvrnpm build`. For the full toolchain
+   model and the `WYVRN_*` variables/macros, point them at the team's
+   "WyvrnPM Cmake Utils" doc.
+7. **gitignore.** Ensure `wyvrn_internal/`, `wyvrn.lock`, `wyvrn.local.json`,
+   `build/`, `*.zip` are ignored.
+8. **Verify** the build configures and links, then summarize.
+
+## Mode B — convert an existing CMake project into a wyvrnpm package
+
+Follow the skill's "convert-a-project flow" exactly. The deliverable is a
+**validated** package, not just a `wyvrn.json`:
+
+1. **Read the existing `CMakeLists.txt`** to choose `kind`
+   (`HeaderOnlyLib` / `StaticLib` / `DynamicLib`), declare `options` only for
+   real ABI-affecting toggles, and write a `build` recipe. For known OSS,
+   `wyvrnpm bootstrap <git-url>` drafts a first-pass manifest (clones, detects
+   kind, applies cookbook flags) — review and correct it.
+2. **`build.configs` defaults to all four:**
+   `["Debug","Release","RelWithDebInfo","MinSizeRel"]` (note the spelling —
+   `RelWithDebInfo`). Restrict only with a concrete reason.
+3. **Write `.wyvrnignore`** next to `wyvrn.json` — `publish` zips the whole
+   project tree, so exclude tests/examples/docs/`build/`/CI. A HeaderOnlyLib zip
+   should be well under 1 MB.
+4. **`wyvrnpm install`** in the project root — surfaces manifest errors fast.
+5. **`wyvrnpm build --install --all-configs`** — `--install` is mandatory; plain
+   build doesn't populate the install tree (headers + libs + `*Config.cmake`)
+   that consumers' `find_package` needs. All four configs must complete.
+6. **Diagnose any failure** (skill's diagnostics reference) and fix the manifest
+   — don't paper over a broken config.
+7. **STOP before `wyvrnpm publish`.** Hand back the exact `publish` command plus
+   the pre-publish checklist (changes committed, branch pushed, right profile,
+   `--source` explicit). The human runs it.
+
+## Hard safety rails (never violate)
+
+These write to **shared team state** and need the human's explicit yes — never
+run them yourself as part of onboarding:
+
+- `wyvrnpm publish` / `publish --force` — registry writes other teammates see.
+- `wyvrnpm install --upload-built` — also a registry write.
+- `wyvrnpm configure remove-source` — confirm first.
+
+Safe to run without asking (local, reversible): `install` (no `--upload-built`),
+`build`, `clean`, `show`, `link`/`unlink`, `init`, `bootstrap`, `configure list`
+/ `profile show` / `profile detect`. For `configure add-source`, show the URL +
+any credentials before writing.
+
+## Finish every run with
+
+- A short summary: which mode you ran, the files you created/changed, and what
+  you verified (e.g. "install OK; all 4 configs built + installed").
+- The single exact next command the human should run (for Mode B, the
+  `wyvrnpm publish ...` line), or "you're ready to build" for Mode A.
+- If anything failed, the specific error and what you changed to fix it (or what
+  remains blocked). Be honest — an unvalidated manifest is worth less than none.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "2.20.2",
+  "version": "2.21.1",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",
@@ -21,6 +21,7 @@
     "src/",
     "cmake/",
     "claude/skills/wyvrnpm.skill",
+    "claude/agents/",
     "README.md"
   ],
   "scripts": {

package/src/commands/install-skill.js

@@ -11,16 +11,19 @@ const log = require('../logger');
 // ---------------------------------------------------------------------------
 // `wyvrnpm install-skill --claude`
 //
-// Copies the bundled wyvrnpm Agent Skill (claude/skills/wyvrnpm.skill) into
-// the user's Claude Code skills directory so Claude picks it up automatically.
+// Copies the bundled wyvrnpm Agent Skill (claude/skills/wyvrnpm.skill) AND the
+// bundled onboarding agents (claude/agents/*.md) into the user's Claude Code
+// directories so Claude picks them up automatically.
 //
 // Works for both install shapes:
-//   - `npm i -g wyvrnpm` → skill zip ships under <pkg>/claude/skills/
+//   - `npm i -g wyvrnpm` → assets ship under <pkg>/claude/
 //   - `git clone` of this repo → same path, just not from node_modules
 //
-// Destination, per target:
-//   --claude  → %USERPROFILE%\.claude\skills\wyvrnpm\  (Windows)
-//               ~/.claude/skills/wyvrnpm/               (macOS / Linux)
+// Destinations, per target (--claude):
+//   skill   → %USERPROFILE%\.claude\skills\wyvrnpm\  (Windows)
+//             ~/.claude/skills/wyvrnpm/               (macOS / Linux)
+//   agents  → %USERPROFILE%\.claude\agents\          (Windows)
+//             ~/.claude/agents/                       (macOS / Linux)
 // ---------------------------------------------------------------------------
 
 const SKILL_NAME = 'wyvrnpm';
@@ -31,18 +34,94 @@ function bundledSkillPath() {
   return path.resolve(__dirname, '..', '..', 'claude', 'skills', `${SKILL_NAME}.skill`);
 }
 
+function bundledAgentsDir() {
+  // __dirname = <pkg>/src/commands; agent definitions live at
+  // <pkg>/claude/agents/*.md (README.md excluded — it's docs, not an agent).
+  return path.resolve(__dirname, '..', '..', 'claude', 'agents');
+}
+
 function claudeSkillsDir() {
   const home = os.homedir();
   if (!home) throw new Error('cannot resolve user home directory');
   return path.join(home, '.claude', 'skills');
 }
 
+function claudeAgentsDir() {
+  const home = os.homedir();
+  if (!home) throw new Error('cannot resolve user home directory');
+  return path.join(home, '.claude', 'agents');
+}
+
+/**
+ * Bundled agent-definition files to install — every `*.md` under
+ * `claude/agents/` except `README.md` (which is human docs, not an agent
+ * definition and would parse as a nameless agent). Returns absolute paths.
+ *
+ * @returns {string[]}
+ */
+function bundledAgentFiles() {
+  const dir = bundledAgentsDir();
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir)
+    .filter((f) => f.endsWith('.md') && f.toLowerCase() !== 'readme.md')
+    .sort()
+    .map((f) => path.join(dir, f));
+}
+
 function rmrf(target) {
   if (!fs.existsSync(target)) return;
   fs.rmSync(target, { recursive: true, force: true });
 }
 
+/**
+ * Install the bundled onboarding agents into ~/.claude/agents/. Unlike the
+ * skill, agents are independent plain-Markdown files, so this never aborts
+ * the run: an already-present agent is skipped (with a hint) unless --force,
+ * and the rest still install. Dry-run reports without writing.
+ *
+ * @param {{ force: boolean, dryRun: boolean }} opts
+ */
+function installAgentsForClaude({ force, dryRun }) {
+  const agentFiles = bundledAgentFiles();
+  if (agentFiles.length === 0) {
+    log.info('No bundled agents to install.');
+    return;
+  }
+
+  const destDir = claudeAgentsDir();
+  log.info(`Agents      : ${destDir}`);
+
+  if (dryRun) {
+    for (const src of agentFiles) {
+      log.info(`(--dry-run) would install agent ${path.basename(src)} → ${destDir}`);
+    }
+    return;
+  }
+
+  fs.mkdirSync(destDir, { recursive: true });
+  let installed = 0;
+  for (const src of agentFiles) {
+    const name = path.basename(src);
+    const dest = path.join(destDir, name);
+    if (fs.existsSync(dest) && !force) {
+      log.warn(`agent ${name} already installed — re-run with --force to overwrite`);
+      continue;
+    }
+    fs.copyFileSync(src, dest);
+    installed += 1;
+    log.success(`Installed agent ${name} → ${dest}`);
+  }
+  if (installed > 0) {
+    log.info('Claude Code will pick up the agent(s) on next session start.');
+  }
+}
+
 function installForClaude({ force, dryRun }) {
+  installSkillForClaude({ force, dryRun });
+  installAgentsForClaude({ force, dryRun });
+}
+
+function installSkillForClaude({ force, dryRun }) {
   const zipPath = bundledSkillPath();
   if (!fs.existsSync(zipPath)) {
     log.error(`bundled skill not found at ${zipPath}`);
@@ -111,5 +190,8 @@ async function installSkill(argv) {
 }
 
 module.exports = installSkill;
-module.exports.bundledSkillPath = bundledSkillPath;
-module.exports.claudeSkillsDir  = claudeSkillsDir;
+module.exports.bundledSkillPath  = bundledSkillPath;
+module.exports.claudeSkillsDir   = claudeSkillsDir;
+module.exports.bundledAgentsDir  = bundledAgentsDir;
+module.exports.claudeAgentsDir   = claudeAgentsDir;
+module.exports.bundledAgentFiles = bundledAgentFiles;

package/src/commands/link.js

@@ -8,6 +8,9 @@ const { createLink, isLink, removeLink, getLinkTarget } = require('../link-utils
 const { downloadDependencies } = require('../download');
 const { resolveDependencies } = require('../resolve');
 const { wyvrnFetch } = require('../http-fetch');
+const { resolveBinaryDirRoot } = require('../binary-dir');
+const { readLocalOverlay } = require('../conf');
+const { hasBuildRecipe, DEFAULT_RECIPE } = require('../build/recipe');
 const log = require('../logger');
 
 /**
@@ -37,14 +40,51 @@ function getEffectivePath(entry) {
   return entry.path;
 }
 
+/**
+ * Compute the install-tree subdirectory for a package that declares a build
+ * recipe, relative to the package root. Mirrors how `publish` locates the
+ * install tree it overlays: `<binaryDirRoot>/wyvrn-<profile>/<installDir>`.
+ *
+ * The returned path is forward-slash separated and relative — `getEffectivePath`
+ * joins it onto the package root to yield the absolute install dir.
+ *
+ * @param {object} manifest - Parsed wyvrn.json (must have a build recipe).
+ * @param {object} config - Resolved config (for defaultProfile fallback).
+ * @param {object} argv - Parsed yargs arguments (reads `profile`).
+ * @param {string} packagePath - Absolute package root (for the local overlay).
+ * @returns {string} Relative, forward-slash install-tree subdir.
+ */
+function installTreeSubdir(manifest, config, argv, packagePath) {
+  const overlay = readLocalOverlay(packagePath);
+  const binaryDirRoot = resolveBinaryDirRoot({
+    localOverlayBinaryDirRoot: overlay.binaryDirRoot,
+  });
+  const profileName =
+    typeof argv.profile === 'string' && argv.profile.length > 0
+      ? argv.profile
+      : config.defaultProfile || 'default';
+  const installDir = manifest.build.installDir ?? DEFAULT_RECIPE.installDir;
+  return [binaryDirRoot, `wyvrn-${profileName}`, installDir].join('/');
+}
+
 /**
  * Register the current directory's package globally for linking.
  * Reads wyvrn.json to get the package name, stores {name: {path, subdir}} in config.
  *
+ * When the package declares a build recipe, the registered target is its
+ * install tree (`<binaryDirRoot>/wyvrn-<profile>/<installDir>`) rather than the
+ * raw source root. That tree carries the installed headers, libraries, and
+ * `<name>Config.cmake` at its root — the exact layout a consumer's
+ * `find_package(<name> CONFIG)` expects after the link lands in
+ * `wyvrn_internal/<name>/`. Linking the source root would bury the CMake
+ * config under `build/` and find_package would miss it, so the link must
+ * simulate the packaged artefact, not the working tree. An explicit
+ * `--subdir` always wins (monorepo: link a sub-package's own tree).
+ *
  * @param {string} manifestPath - Path to wyvrn.json
- * @param {string} [subdir] - Optional subdirectory within the package to link.
+ * @param {object} argv - Parsed yargs arguments (reads `subdir`, `profile`).
  */
-function registerGlobal(manifestPath, subdir) {
+function registerGlobal(manifestPath, argv) {
   const manifest = readManifest(manifestPath);
   const packageName = manifest.name || manifest.Name;
 
@@ -58,14 +98,25 @@ function registerGlobal(manifestPath, subdir) {
   config.linkedPackages = config.linkedPackages || {};
 
   const entry = { path: packagePath };
-  if (subdir) {
-    entry.subdir = subdir;
+  let installTreeLinked = false;
+  if (argv.subdir) {
+    entry.subdir = argv.subdir;
+  } else if (hasBuildRecipe(manifest)) {
+    entry.subdir = installTreeSubdir(manifest, config, argv, packagePath);
+    installTreeLinked = true;
   }
   config.linkedPackages[packageName] = entry;
   writeConfig(config);
 
   const effectivePath = getEffectivePath(entry);
   log.info(`Registered "${packageName}" → ${effectivePath}`);
+  if (installTreeLinked && !fs.existsSync(effectivePath)) {
+    log.warn(
+      `install tree not found at ${effectivePath}\n` +
+      `  Build + install it so consumers' find_package(${packageName}) resolves:\n` +
+      `    wyvrnpm build --all-configs --install`,
+    );
+  }
 }
 
 /**
@@ -261,7 +312,7 @@ async function link(argv) {
       log.error(`no wyvrn.json found at ${manifestPath}`);
       process.exit(1);
     }
-    registerGlobal(manifestPath, argv.subdir);
+    registerGlobal(manifestPath, argv);
     return;
   }