@hashicorp/kits 0.1.4 → 0.1.5

package/README.md

@@ -2,6 +2,46 @@
 
 Install AI agent kits into your favorite coding assistants.
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Commands](#commands)
+  - [Install](#install)
+    - [Manifest-driven installs (kits.json)](#manifest-driven-installs-kitsjson)
+  - [Uninstall](#uninstall)
+  - [Upgrade](#upgrade)
+  - [Validate](#validate)
+  - [List](#list)
+  - [Info](#info)
+- [Supported Harnesses](#supported-harnesses)
+- [Installation Scopes](#installation-scopes)
+  - [Global Scope (`--global`)](#global-scope---global)
+  - [Project Scope (`--project`)](#project-scope---project)
+  - [Scope Limitations](#scope-limitations)
+- [Source Formats](#source-formats)
+- [Primitive Resolution](#primitive-resolution)
+- [File vs Configuration Primitives](#file-vs-configuration-primitives)
+- [Kits Manifest + Lock](#kits-manifest--lock)
+- [Exit Codes](#exit-codes)
+- [Environment Variables](#environment-variables)
+- [Configuration](#configuration)
+  - [Kit Repository Structure](#kit-repository-structure)
+  - [Kit Definition (kit.json)](#kit-definition-kitjson)
+  - [Primitive Formats](#primitive-formats)
+  - [Model Templates](#model-templates)
+- [Development](#development)
+  - [Prerequisites](#prerequisites)
+  - [Setup](#setup)
+  - [Testing Local Changes](#testing-local-changes)
+  - [Integration Tests (Devcontainer)](#integration-tests-devcontainer)
+  - [Project Structure](#project-structure)
+- [Troubleshooting](#troubleshooting)
+  - [Common Issues](#common-issues)
+  - [Debug Mode](#debug-mode)
+- [License](#license)
+
 ## Overview
 
 The Kit Installer is a CLI tool that discovers, validates, and installs AI agent kits from kit repositories into various AI coding assistant harnesses. It supports multiple harnesses including Claude Code, Codex, Gemini CLI, GitHub Copilot, and OpenCode.
@@ -53,7 +93,7 @@ npx @hashicorp/kits install example-org/kits --global --dry-run
 
 ### Install
 
-Installs kits from a source repository.
+Installs kits from a source repository or a manifest directory.
 
 ```bash
 kits install <source> [options]
@@ -65,18 +105,22 @@ kits install <source> [options]
 |------|-------------|
 | `-a, --agent <name...>` | Target specific harness(es) |
 | `-k, --kit <name...>` | Install specific kit(s) |
-| `-g, --global` | Install to global scope (user-level, available in all projects) |
-| `-p, --project` | Install to project scope (current directory only) |
+| `-g, --global` | Use global scope (user-level, available in all projects) |
+| `-p, --project` | Use project scope (current directory only) |
+| `--alias <name>` | Install a single kit using an alternate instance name |
 | `-e, --env <KEY=VALUE>` | Set environment variable for MCP servers (repeatable; nonsensitive only) |
-| `--mcp-instance <KIT:NAME=VALUE>` | Override MCP instance name for a specific kit (repeatable) |
+| `--mcp-instance <KIT:NAME=VALUE>` | Override MCP instance name (repeatable; KIT is the kit instance name) |
 | `-l, --list` | List available kits without installing |
 | `-y, --yes` | Non-interactive mode, accept defaults |
+| `--ci` | Require a matching kits-lock.json when installing from kits.json |
+| `--ignore-lock` | Ignore kits-lock.json and resolve directly from kits.json |
+| `--overwrite` | Overwrite existing kit instances when names collide |
 | `--dry-run` | Show what would be installed |
 | `--json` | Output results as JSON |
 | `-v, --verbose` | Enable verbose logging |
 | `--debug` | Enable debug logging to `~/.config/agent-kit/debug.log` |
 
-**Note:** In non-interactive mode (`-y`), one of `--global` or `--project` is required.
+**Note:** In non-interactive mode (`-y`), one of `--global` or `--project` is required unless installing from `kits.json` (which defines scope).
 
 **Examples:**
 
@@ -99,6 +143,12 @@ npx @hashicorp/kits install example-org/kits \
   -k vault-operations \
   --project
 
+# Install a kit with an alias (instance name)
+npx @hashicorp/kits install example-org/kits \
+  -k terraform-development \
+  --alias terraform-dev \
+  --project
+
 # Override MCP instance name for a specific kit
 npx @hashicorp/kits install example-org/kits \
   -k terraform-development \
@@ -114,26 +164,46 @@ npx @hashicorp/kits install example-org/kits \
 
 # Install from local directory (for development)
 npx @hashicorp/kits install ./my-kits -a claude-code --project
+
+# Install from a kits.json manifest in the current repo
+npx @hashicorp/kits install .
 ```
 
-## Integration Tests (Devcontainer)
+#### Manifest-driven installs (kits.json)
 
-The integration suite runs the real CLI against the local `test-kits/` repository using non-interactive JSON output. It is intended to run inside the devcontainer so harness CLIs are available and filesystem isolation is preserved.
+If `<source>` points at a directory or a `kits.json` file, the installer will
+look for a manifest and use it as the installation intent:
 
-```bash
-npm run test:integration
+1. `<source>/.agents/kits.json`
+2. `<source>/kits.json`
+3. `<source>` itself if it is `kits.json`
+
+The manifest determines scope, sources, and optional harness selection. When
+`kits.json` is present, the installer writes a corresponding `kits-lock.json`
+and records a hash of the manifest to keep the two in sync.
+
+Example manifest (`.agents/kits.json`):
+
+```json
+{
+  "schemaVersion": "1.0.0",
+  "scope": "project",
+  "sources": [
+    { "source": "example-org/kits", "kits": ["terraform-development"] }
+  ],
+  "harnesses": ["claude-code"]
+}
 ```
 
-Integration tests are organized by intent under `tests/integration/`:
-- `cli/` for CLI command behavior
-- `primitives/` for primitive-specific scenarios
-- `harnesses/` for harness-specific scenarios
-- `scopes/` for scope-specific scenarios
-- `validators/` for validator binaries (using `test-kits/fixtures/invalid/`)
+Install using that manifest:
+
+```bash
+npx @hashicorp/kits install .
+```
 
 ### Uninstall
 
-Removes installed kits.
+Removes installed kit instances.
 
 ```bash
 kits uninstall <kit-name> [options]
@@ -144,9 +214,13 @@ kits uninstall <kit-name> [options]
 | Flag | Description |
 |------|-------------|
 | `-a, --agent <name...>` | Target specific harness(es) |
-| `-g, --global` | Uninstall from global scope |
-| `-p, --project` | Uninstall from project scope |
+| `-g, --global` | Use global scope |
+| `-p, --project` | Use project scope |
+| `--alias <name>` | Target a specific kit instance name (installAs) |
+| `--all` | Uninstall all instances that match the kit name |
 | `-y, --yes` | Non-interactive mode |
+| `--lock-only` | Uninstall using kits-lock.json only (do not modify kits.json) |
+| `--dry-run` | Show what would be uninstalled |
 | `--json` | Output results as JSON |
 
 **Note:** In non-interactive mode (`-y`), one of `--global` or `--project` is required.
@@ -163,6 +237,9 @@ npx @hashicorp/kits uninstall terraform-development --global -y
 # Uninstall from project scope
 npx @hashicorp/kits uninstall terraform-development --project -y
 
+# Uninstall a specific kit instance (alias)
+npx @hashicorp/kits uninstall terraform-development --alias terraform-dev --project -y
+
 # Uninstall from specific harness at global scope
 npx @hashicorp/kits uninstall terraform-development -a claude-code --global -y
 ```
@@ -179,13 +256,17 @@ kits upgrade [options]
 
 | Flag | Description |
 |------|-------------|
-| `-s, --source <source>` | Kit repository source |
+| `-s, --source <source>` | Kit repository source (defaults to lockfile sources) |
 | `-a, --agent <name...>` | Target specific harness(es) |
-| `-k, --kit <name...>` | Upgrade specific kit(s) only |
-| `-g, --global` | Upgrade global scope installations (required) |
-| `-p, --project` | Upgrade project scope installations (required) |
+| `-k, --kit <name...>` | Upgrade specific kit(s) by canonical name |
+| `--alias <name>` | Upgrade a specific kit instance name |
+| `--all` | Upgrade all kit instances for the selected kit(s) |
+| `-g, --global` | Use global scope (required) |
+| `-p, --project` | Use project scope (required) |
 | `-c, --check` | Check for updates without installing |
 | `-y, --yes` | Non-interactive mode |
+| `--dry-run` | Alias for `--check` |
+| `--save` | Update kits.json source refs to match upgraded lockfile |
 | `--json` | Output results as JSON |
 
 **Note:** Unlike install, upgrade always requires `--global` or `--project` (no TUI prompt).
@@ -210,6 +291,12 @@ npx @hashicorp/kits upgrade \
   -s example-org/kits \
   -k terraform-development \
   --global
+
+# Upgrade a specific kit instance
+npx @hashicorp/kits upgrade \
+  --alias terraform-dev \
+  --global \
+  --check
 ```
 
 ### Validate
@@ -232,7 +319,7 @@ npx @hashicorp/kits validate --hooks ./agent-kits
 # Validate MCP configs in a local path
 npx @hashicorp/kits validate --mcp ./agent-kits
 
-# Validate kit definitions and kits.json registry
+# Validate kit definitions and kits-registry.json registry
 npx @hashicorp/kits validate --kits ./agent-kits
 ```
 
@@ -363,14 +450,36 @@ The installer resolves these references at install time:
 
 When multiple kits reference the same primitive, the installer deduplicates and selects the highest compatible version.
 
-## Installation Manifest
+## File vs Configuration Primitives
+
+Primitives install in two different ways, and the installer treats them differently:
+
+**File-based primitives** are copied into harness-specific directories. These include
+commands, skills, subagents, and hook programs. The harness discovers them by scanning
+its filesystem paths, so installs/uninstalls are direct file operations.
+
+**Configuration-based primitives** are merged into harness configuration files. These
+include MCP server definitions and hook bindings. The installer updates config files
+and tracks instance hashes in `kits-lock.json` so it can safely upgrade or remove
+entries later without clobbering unrelated settings.
+
+## Kits Manifest + Lock
 
-The installer tracks installations in scope-specific manifest files:
+The installer reads declarative kits manifests (`kits.json`) and records resolved installs in lockfiles (`kits-lock.json`).
+
+Manifests are scope-specific:
 
 | Scope | Manifest Location |
+|-------|-------------------|
+| Global | `~/.agents/kits.json` |
+| Project | `.agents/kits.json` |
+
+Lockfiles are scope-specific:
+
+| Scope | Lockfile Location |
 |-------|------------------|
-| Global | `~/.agents/manifest.json` |
-| Project | `.agents/manifest.json` |
+| Global | `~/.agents/kits-lock.json` |
+| Project | `.agents/kits-lock.json` |
 
 This enables:
 - Uninstallation of kits
@@ -378,6 +487,14 @@ This enables:
 - Conflict detection
 - Scope isolation (global and project installations are tracked separately)
 
+Behavior notes:
+- When `kits.json` exists and its hash matches the lockfile metadata, the
+  lockfile is the authoritative source of resolved versions.
+- `--ci` requires a matching lockfile and fails fast if out of sync.
+- `--ignore-lock` ignores `kits-lock.json` and resolves directly from `kits.json`.
+- `uninstall`/`upgrade` will fail if `kits.json` exists but is out of sync with
+  the lockfile (use `install` to reconcile, or `uninstall --lock-only`).
+
 ## Exit Codes
 
 | Code | Meaning |
@@ -394,6 +511,9 @@ This enables:
 | 9 | No upgrades available |
 | 10 | User cancelled |
 | 11 | Scope required (non-interactive mode without `--global` or `--project`) |
+| 12 | Required env var missing |
+| 13 | Sensitive env var provided via `--env` |
+| 14 | Lockfile out of sync with kits.json |
 
 ## Environment Variables
 
@@ -409,8 +529,8 @@ A kit repository should have:
 
 ```
 my-kits/
-├── kits.json              # Kit registry (optional, enables multiple kits)
-├── primitives.json        # Shared primitives registry (optional)
+├── kits-registry.json     # Kits registry (optional, enables multiple kits)
+├── primitives-registry.json # Shared primitives registry (optional)
 ├── primitives/            # Shared primitive definitions
 │   ├── commands/
 │   ├── skills/
@@ -554,20 +674,36 @@ npm link
 kits install ./path/to/local/kits
 
 # Or use directly without linking
-npx ts-node src/cli/index.ts install ./path/to/local/kits
+node bin/kits.js install ./path/to/local/kits
+```
+
+### Integration Tests (Devcontainer)
+
+The integration suite runs the real CLI against the local `test-kits/` repository using non-interactive JSON output. It is intended to run inside the devcontainer so harness CLIs are available and filesystem isolation is preserved.
+
+```bash
+npm run test:integration
 ```
 
+Integration tests are organized by intent under `tests/integration/`:
+- `cli/` for CLI command behavior
+- `primitives/` for primitive-specific scenarios
+- `harnesses/` for harness-specific scenarios
+- `scopes/` for scope-specific scenarios
+- `validators/` for validator binaries (using `test-kits/fixtures/invalid/`)
+
 ### Project Structure
 
 ```
-agent-kit-cli/
+kits/
 ├── src/
 │   ├── cli/           # CLI commands (install, uninstall, upgrade, etc.)
 │   ├── tui/           # Terminal UI components
 │   ├── adapters/      # Harness adapters (claude-code, codex, etc.)
 │   ├── discovery/     # Kit discovery and source fetching
 │   ├── resolution/    # Primitive reference resolution
-│   ├── manifest/      # Installation manifest management
+│   ├── manifest/      # kits.json intent
+│   ├── lockfile/      # kits-lock.json tracking
 │   └── core/          # Core types and utilities
 ├── tests/             # Test files
 ├── schemas/           # JSON schemas
@@ -604,6 +740,11 @@ agent-kit-cli/
 - Use `--global` to install kits requiring these primitives to Codex
 - Or install to other harnesses that support project scope
 
+**"Lockfile out of sync" (exit code 14)**
+- A `kits.json` exists but the lockfile hash does not match
+- Run `kits install <source>` to reconcile
+- Or use `kits uninstall --lock-only` to bypass manifest updates
+
 ### Debug Mode
 
 Enable debug logging for detailed output:

package/dist/adapters/base-adapter.d.ts

@@ -131,7 +131,7 @@ export declare abstract class BaseAdapter implements KitAdapter {
     /**
      * Check if a kit is compatible with this harness at the given scope.
      *
-     * @param kit - Kit definition to check
+     * @param kit - Kit manifest to check
      * @param scope - Installation scope (defaults to "global")
      */
     checkCompatibility(kit: KitManifest, scope?: InstallationScope): CompatibilityResult;
@@ -184,7 +184,7 @@ export declare abstract class BaseAdapter implements KitAdapter {
      *
      * Subclasses should override for harness-specific config handling.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/base-adapter.js

@@ -55,7 +55,7 @@ export class BaseAdapter {
     /**
      * Check if a kit is compatible with this harness at the given scope.
      *
-     * @param kit - Kit definition to check
+     * @param kit - Kit manifest to check
      * @param scope - Installation scope (defaults to "global")
      */
     checkCompatibility(kit, scope) {
@@ -481,7 +481,7 @@ export class BaseAdapter {
      *
      * Subclasses should override for harness-specific config handling.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/claude-code/index.d.ts

@@ -134,7 +134,7 @@ export declare class ClaudeCodeAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/claude-code/index.js

@@ -292,7 +292,7 @@ export class ClaudeCodeAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/codex/index.d.ts

@@ -140,7 +140,7 @@ export declare class CodexAdapter extends BaseAdapter {
      * Codex only needs MCP configuration updates (no hooks support).
      * MCP is only supported at global scope.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/codex/index.js

@@ -204,7 +204,7 @@ export class CodexAdapter extends BaseAdapter {
      * Codex only needs MCP configuration updates (no hooks support).
      * MCP is only supported at global scope.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/gemini-cli/index.d.ts

@@ -138,7 +138,7 @@ export declare class GeminiCliAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/gemini-cli/index.js

@@ -267,7 +267,7 @@ export class GeminiCliAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/github-copilot/index.d.ts

@@ -159,7 +159,7 @@ export declare class GithubCopilotAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/github-copilot/index.js

@@ -275,7 +275,7 @@ export class GithubCopilotAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/opencode/index.d.ts

@@ -135,7 +135,7 @@ export declare class OpencodeAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/adapters/opencode/index.js

@@ -223,7 +223,7 @@ export class OpencodeAdapter extends BaseAdapter {
     /**
      * Update harness configuration for MCP servers and hooks.
      *
-     * @param kit - Kit definition
+     * @param kit - Kit manifest
      * @param resolvedPrimitives - Resolved primitives to install
      * @param dryRun - If true, don't actually write files
      * @param completedOps - Array to track completed operations for rollback

package/dist/cli/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAySH;;GAEG;AACH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA6TH;;GAEG;AACH,wBAAsB,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,CAKzC"}

package/dist/cli/index.js

@@ -30,9 +30,9 @@ const cliVersion = getCliVersion();
  * Returns [globalOption, projectOption] that conflict with each other.
  */
 function createScopeOptions() {
-    const globalOption = new Option("-g, --global", "Install globally (user-level, available in all projects)")
+    const globalOption = new Option("-g, --global", "Use global scope (user-level, available in all projects)")
         .conflicts("project");
-    const projectOption = new Option("-p, --project", "Install at project scope (repository-level, version-controllable)")
+    const projectOption = new Option("-p, --project", "Use project scope (repository-level, version-controllable)")
         .conflicts("global");
     return [globalOption, projectOption];
 }
@@ -63,7 +63,7 @@ function collectEnv(value, previous) {
 /**
  * Collect --mcp-instance flags into a nested object.
  *
- * Parses KIT:NAME=VALUE format strings into a record keyed by kit name.
+ * Parses KIT:NAME=VALUE format strings into a record keyed by kit instance name.
  */
 function collectMcpInstance(value, previous) {
     const equalsIndex = value.indexOf("=");
@@ -102,15 +102,19 @@ program
 const [installGlobalOpt, installProjectOpt] = createScopeOptions();
 program
     .command("install <source>")
-    .description("Install kits from a repository")
+    .description("Install kits from a repository or kits.json manifest")
     .addOption(installGlobalOpt)
     .addOption(installProjectOpt)
     .option("-a, --agent <name...>", "Target specific harness(es)")
     .option("-k, --kit <name...>", "Install specific kit(s)")
+    .option("--alias <name>", "Install the kit using an alternate instance name (single kit only)")
     .option("-e, --env <KEY=VALUE>", "Set environment variable for MCP servers (repeatable)", collectEnv, {})
-    .option("--mcp-instance <KIT:NAME=VALUE>", "Override MCP instance name (repeatable)", collectMcpInstance, {})
+    .option("--mcp-instance <KIT:NAME=VALUE>", "Override MCP instance name (repeatable, KIT is instance name)", collectMcpInstance, {})
     .option("-l, --list", "List available kits without installing")
     .option("-y, --yes", "Non-interactive mode, accept defaults")
+    .option("--ci", "Strict lockfile install (requires kits.json + kits-lock.json)")
+    .option("--ignore-lock", "Ignore kits-lock.json and resolve from kits.json intent")
+    .option("--overwrite", "Overwrite existing kit instances when names collide")
     .option("--dry-run", "Show what would be installed without changes")
     .option("--json", "Output results as JSON")
     .option("-v, --verbose", "Enable verbose logging")
@@ -119,9 +123,13 @@ program
     const options = {
         agent: allOpts["agent"],
         kit: allOpts["kit"],
+        alias: allOpts["alias"],
         list: allOpts["list"],
         yes: allOpts["yes"],
         dryRun: allOpts["dryRun"],
+        ci: allOpts["ci"],
+        ignoreLock: allOpts["ignoreLock"],
+        overwrite: allOpts["overwrite"],
         json: allOpts["json"],
         debug: allOpts["debug"],
         verbose: allOpts["verbose"],
@@ -137,11 +145,14 @@ program
 const [uninstallGlobalOpt, uninstallProjectOpt] = createScopeOptions();
 program
     .command("uninstall <kit-name>")
-    .description("Uninstall a kit")
+    .description("Uninstall a kit instance")
     .addOption(uninstallGlobalOpt)
     .addOption(uninstallProjectOpt)
     .option("-a, --agent <name...>", "Target specific harness(es)")
+    .option("--alias <name>", "Target a specific kit instance name (installAs)")
+    .option("--all", "Uninstall all instances that match the kit name")
     .option("-y, --yes", "Non-interactive mode")
+    .option("--lock-only", "Remove from lockfile only (do not modify kits.json)")
     .option("--dry-run", "Show what would be uninstalled without changes")
     .option("--json", "Output results as JSON")
     .option("-v, --verbose", "Enable verbose logging")
@@ -149,8 +160,11 @@ program
     const allOpts = command.optsWithGlobals();
     const options = {
         agent: allOpts["agent"],
+        alias: allOpts["alias"],
+        all: allOpts["all"],
         yes: allOpts["yes"],
         dryRun: allOpts["dryRun"],
+        lockOnly: allOpts["lockOnly"],
         json: allOpts["json"],
         debug: allOpts["debug"],
         verbose: allOpts["verbose"],
@@ -167,11 +181,14 @@ program
     .description("Check for and apply primitive upgrades")
     .addOption(upgradeGlobalOpt)
     .addOption(upgradeProjectOpt)
-    .option("-s, --source <source>", "Kit repository source")
+    .option("-s, --source <source>", "Kit repository source (defaults to lockfile sources)")
     .option("-a, --agent <name...>", "Target specific harness(es)")
-    .option("-k, --kit <name...>", "Upgrade specific kit(s) only")
+    .option("-k, --kit <name...>", "Upgrade specific kit(s) by canonical name")
+    .option("--alias <name>", "Upgrade a specific kit instance name")
+    .option("--all", "Upgrade all kit instances for the selected kit(s)")
     .option("-c, --check", "Check for updates without installing")
     .option("--dry-run", "Show what would be upgraded without changes (alias for --check)")
+    .option("--save", "Update kits.json source refs to match upgraded lockfile")
     .option("-y, --yes", "Non-interactive mode, upgrade all available")
     .option("--json", "Output results as JSON")
     .option("-v, --verbose", "Enable verbose logging")
@@ -181,8 +198,11 @@ program
         source: allOpts["source"],
         agent: allOpts["agent"],
         kit: allOpts["kit"],
+        alias: allOpts["alias"],
+        all: allOpts["all"],
         check: allOpts["check"],
         dryRun: allOpts["dryRun"],
+        save: allOpts["save"],
         yes: allOpts["yes"],
         json: allOpts["json"],
         debug: allOpts["debug"],
@@ -241,7 +261,7 @@ program
     .option("--commands", "Validate command primitives")
     .option("--skills", "Validate skill primitives")
     .option("--subagents", "Validate subagent primitives")
-    .option("--kits", "Validate kit definitions and kits.json registry")
+    .option("--kits", "Validate kit definitions and kits-registry.json registry")
     .option("--hooks", "Validate hook programs and kit hook bindings")
     .option("--mcp", "Validate MCP server configs")
     .option("--json", "Output results as JSON")