@hashicorp/kits 0.1.6 → 0.1.8

package/README.md

@@ -5,356 +5,38 @@ 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)
+- [Install Scopes (Global vs Project)](#install-scopes-global-vs-project)
 - [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)
+- [Documentation Index](#documentation-index)
+- [CLI Commands (Summary)](#cli-commands-summary)
+- [Configuration and Formats](#configuration-and-formats)
 - [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.
-
-## Installation
-
-```bash
-# Run directly with npx (recommended)
-npx @hashicorp/kits install example-org/kits
-
-# Or install globally
-npm install -g @hashicorp/kits
-kits install example-org/kits
-```
-
-To validate kit repositories, use the built-in validate command:
-
-```bash
-npx @hashicorp/kits validate ./agent-kits
-npx @hashicorp/kits validate --commands example-org/kits
-```
+The Kit Installer is a CLI that discovers, validates, and installs AI agent kits into supported harnesses (Claude Code, Codex, Gemini CLI, GitHub Copilot, OpenCode). It supports local or remote kit repositories, manifest-driven installs, and scoped installation (global or project).
 
 ## Quick Start
 
 ```bash
-# Interactive installation - guides you through selection
+# Interactive install (prompts for scope + selection)
 npx @hashicorp/kits install example-org/kits
 
-# Install to global scope (user-level, available in all projects)
+# Non-interactive global install
 npx @hashicorp/kits install example-org/kits --global -y
 
-# Install to project scope (current directory only)
+# Project-scope install (current repo)
 npx @hashicorp/kits install example-org/kits --project -y
 
-# Install specific kit to specific harness
-npx @hashicorp/kits install example-org/kits \
-  -a claude-code \
-  -k terraform-development \
-  --global
-
-# List available kits without installing
+# List kits without installing
 npx @hashicorp/kits install example-org/kits -l
 
-# Check what would be installed (dry run)
-npx @hashicorp/kits install example-org/kits --global --dry-run
-```
-
-## Commands
-
-### Install
-
-Installs kits from a source repository or a manifest directory.
-
-```bash
-kits install <source> [options]
-```
-
-**Options:**
-
-| Flag | Description |
-|------|-------------|
-| `-a, --agent <name...>` | Target specific harness(es) |
-| `-k, --kit <name...>` | Install specific kit(s) |
-| `-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 (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 unless installing from `kits.json` (which defines scope).
-
-**Examples:**
-
-```bash
-# Interactive installation (prompts for scope selection)
-npx @hashicorp/kits install example-org/kits
-
-# Install to global scope (user-level)
-npx @hashicorp/kits install example-org/kits --global -y
-
-# Install to project scope (current directory)
-npx @hashicorp/kits install example-org/kits --project -y
-
-# Install to Claude Code only at global scope
-npx @hashicorp/kits install example-org/kits -a claude-code --global
-
-# Install specific kits at project scope
-npx @hashicorp/kits install example-org/kits \
-  -k terraform-development \
-  -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 \
-  --mcp-instance terraform-development:terraform=terraform-prod \
-  --global
-
-# Non-interactive with all options
-npx @hashicorp/kits install example-org/kits \
-  -a claude-code \
-  -k terraform-development \
-  --global \
-  -y
-
-# 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 .
-```
-
-#### Manifest-driven installs (kits.json)
-
-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:
-
-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"]
-}
-```
-
-Install using that manifest:
-
-```bash
-npx @hashicorp/kits install .
-```
-
-### Uninstall
-
-Removes installed kit instances.
-
-```bash
-kits uninstall <kit-name> [options]
-```
-
-**Options:**
-
-| Flag | Description |
-|------|-------------|
-| `-a, --agent <name...>` | Target specific harness(es) |
-| `-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.
-
-**Examples:**
-
-```bash
-# Interactive uninstall (prompts for scope selection)
-npx @hashicorp/kits uninstall terraform-development
-
-# Uninstall from global scope
-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
-```
-
-### Upgrade
-
-Checks for and applies primitive updates.
-
-```bash
-kits upgrade [options]
-```
-
-**Options:**
-
-| Flag | Description |
-|------|-------------|
-| `-s, --source <source>` | Kit repository source (defaults to lockfile sources) |
-| `-a, --agent <name...>` | Target specific harness(es) |
-| `-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).
-
-**Examples:**
-
-```bash
-# Check for available upgrades at global scope
-npx @hashicorp/kits upgrade --check --global
-
-# Check for available upgrades at project scope
-npx @hashicorp/kits upgrade --check --project
-
-# Interactive upgrade at global scope
-npx @hashicorp/kits upgrade -s example-org/kits --global
-
-# Upgrade all automatically at project scope
-npx @hashicorp/kits upgrade -s example-org/kits --project -y
-
-# Upgrade specific kit at global scope
-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
-
-Validate primitive files in a kit repository. Validators accept either a local path or GitHub shorthand (`org/repo[@ref]`).
-
-```bash
-# Validate an entire repository (all types)
+# Validate a repository
 npx @hashicorp/kits validate ./agent-kits
-
-# Validate commands in a GitHub repo
-npx @hashicorp/kits validate --commands example-org/kits
-
-# Validate skills at a specific ref
-npx @hashicorp/kits validate --skills example-org/kits@v1.2.3
-
-# Validate hook programs in a local path
-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-registry.json registry
-npx @hashicorp/kits validate --kits ./agent-kits
-```
-
-If you install the package globally, the validate command is available directly:
-
-```bash
-npm install -g @hashicorp/kits
-kits validate example-org/kits
-kits validate --skills example-org/kits@v1.2.3
-kits validate --subagents example-org/kits
-kits validate --hooks ./agent-kits
-kits validate --mcp ./agent-kits
-kits validate --kits ./agent-kits
-```
-
-### List
-
-Lists detected harnesses or installed kits.
-
-```bash
-kits list harnesses             # Show detected AI harnesses
-kits list kits                  # Show installed kits (both scopes)
-kits list kits --global         # Show global scope only
-kits list kits --project        # Show project scope only
-```
-
-When listing kits, results are grouped by scope. Use `--global` or `--project` to filter to a specific scope.
-
-### Info
-
-Shows information about a kit repository or specific kit.
-
-```bash
-kits info <source> [options]
-kits info <source> -k <kit-name>  # Specific kit info
 ```
 
 ## Supported Harnesses
@@ -364,397 +46,83 @@ kits info <source> -k <kit-name>  # Specific kit info
 | Claude Code | Yes | Yes | Yes | Yes | Yes |
 | Codex | Yes | Yes | No | Yes | No |
 | Gemini CLI | Yes | Experimental | Experimental | Yes | Yes |
-| GitHub Copilot | Partial | Yes | Yes | Yes | Limited |
+| GitHub Copilot | Project only | Yes | Yes | Yes | Limited (project only) |
 | OpenCode | Yes | Yes | Yes | Yes | Yes |
 
-## Installation Scopes
+## Install Scopes (Global vs Project)
 
 Kits can be installed at two scopes:
 
-### Global Scope (`--global`)
-
-Installs to user-level harness directories, making primitives available across all projects.
-
-| Harness | Primitives Directory | Config Location |
-|---------|---------------------|-----------------|
-| Claude Code | `~/.claude/commands/`, `~/.claude/skills/`, `~/.claude/agents/` | `~/.claude/settings.json`, `~/.claude.json` |
-| Codex | `~/.codex/prompts/`, `~/.codex/skills/` | `~/.codex/config.toml` |
-| Gemini CLI | `~/.gemini/commands/`, `~/.gemini/skills/` | `~/.gemini/settings.json` |
-| GitHub Copilot | `~/.copilot/prompts/`, `~/.copilot/skills/`, `~/.copilot/agents/` | `~/.copilot/config.json` |
-| OpenCode | `~/.config/opencode/commands/`, `~/.config/opencode/skills/`, `~/.config/opencode/agents/` | `~/.config/opencode/opencode.json` |
-
-### Project Scope (`--project`)
-
-Installs to repository-level harness directories, making primitives available only within that project. Project-scope installations can be committed to version control for team sharing.
-
-| Harness | Primitives Directory | Config Location |
-|---------|---------------------|-----------------|
-| Claude Code | `.claude/commands/`, `.claude/skills/`, `.claude/agents/` | `.claude/settings.json`, `.mcp.json` |
-| Codex | `.codex/skills/` | `.codex/config.toml` |
-| Gemini CLI | `.gemini/commands/`, `.gemini/skills/` | `.gemini/settings.json` |
-| GitHub Copilot | `.github/skills/`, `.github/agents/` | `.vscode/mcp.json` |
-| OpenCode | `.opencode/commands/`, `.opencode/skills/`, `.opencode/agents/` | `opencode.json` |
-
-### Scope Limitations
-
-Not all primitive types are available at project scope for all harnesses:
-
-| Harness | Commands | Skills | Subagents | MCP | Hooks |
-|---------|----------|--------|-----------|-----|-------|
-| Claude Code | Global + Project | Global + Project | Global + Project | Global + Project | Global + Project |
-| Codex | **Global only** | Global + Project | N/A | **Global only** | N/A |
-| Gemini CLI | Global + Project | Global + Project | Global + Project | Global + Project | Global + Project |
-| GitHub Copilot | Global + Project | Global + Project | Global + Project | Global + Project | Limited |
-| OpenCode | Global + Project | Global + Project | Global + Project | Global + Project | Global + Project |
-
-When a kit requires primitives that cannot be installed at project scope for a given harness, the installer will report this as a compatibility issue and suggest using `--global` instead.
-
-## Source Formats
-
-The installer supports multiple source formats:
-
-```bash
-# GitHub shorthand (org/repo)
-example-org/kits
-
-# GitHub with specific version/branch
-example-org/kits@v1.0.0
-example-org/kits@main
-
-# Local path (for development)
-./my-kits
-/absolute/path/to/kits
-~/path/to/kits
-```
-
-## Primitive Resolution
-
-Kits can reference primitives from a shared primitives library using version specs:
-
-```json
-{
-  "primitives": {
-    "commands": [
-      { "ref": "tf-plan@^1.0.0" },
-      { "ref": "tf-apply@~1.1.0" },
-      { "ref": "tf-validate@latest" }
-    ]
-  }
-}
-```
+- **Global** (`--global`): user-level installs (e.g., `~/.claude/`), available across projects.
+- **Project** (`--project`): repo-level installs (e.g., `.claude/`), scoped to the current project.
 
-The installer resolves these references at install time:
-- **SemVer ranges** (`^1.0.0`, `~1.2.0`): Resolved to highest matching version
-- **Exact versions** (`1.2.3`): Must match exactly
-- **`latest` keyword**: Resolved to highest available version
+**Scope limitations:** Some harnesses limit which primitives are supported at project scope. For example, Codex commands and MCP are global-only, and GitHub Copilot hooks are project-only.
 
-When multiple kits reference the same primitive, the installer deduplicates and selects the highest compatible version.
+Hook programs are stored in the kit hook store:
+- Global scope: `~/.agents/hooks/`
+- Project scope: `.agents/hooks/`
 
-## 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.
+Harness configs reference these hook program paths.
 
 ## Kits Manifest + Lock
 
-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/kits-lock.json` |
-| Project | `.agents/kits-lock.json` |
-
-This enables:
-- Uninstallation of kits
-- Upgrade checking for primitives
-- 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 |
-|------|---------|
-| 0 | Success |
-| 1 | Installation failed |
-| 2 | Invalid arguments |
-| 3 | Source not found or invalid |
-| 4 | No harnesses detected |
-| 5 | Kit not found |
-| 6 | Kit incompatible with all selected harnesses |
-| 7 | Primitive reference resolution failed |
-| 8 | Manifest read/write error |
-| 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
+Manifest-driven installs use `kits.json` to declare intent and `kits-lock.json` to record resolved versions.
 
-| Variable | Description |
-|----------|-------------|
-| `HTTP_PROXY` / `HTTPS_PROXY` | Proxy configuration for network requests |
+| Scope | Manifest | Lockfile |
+|-------|----------|----------|
+| Global | `~/.agents/kits.json` | `~/.agents/kits-lock.json` |
+| Project | `.agents/kits.json` | `.agents/kits-lock.json` |
 
-## Configuration
+The lockfile is the source of truth when its hash matches the manifest. It also records shared instance registries (`mcpInstances`, `hookInstances`).
 
-### Kit Repository Structure
+## Documentation Index
 
-A kit repository should have:
+More comprehensive docs live under `docs/`:
 
-```
-my-kits/
-├── kits-registry.json     # Kits registry (optional, enables multiple kits)
-├── primitives-registry.json # Shared primitives registry (optional)
-├── primitives/            # Shared primitive definitions
-│   ├── commands/
-│   ├── skills/
-│   └── ...
-└── kits/                  # Individual kit directories
-    ├── terraform-development/
-    │   ├── kit.json       # Kit definition
-    │   └── primitives/    # Kit-specific primitives
-    └── vault-operations/
-        ├── kit.json
-        └── primitives/
-```
-
-For single-kit repositories, place `kit.json` at the root.
-
-### Kit Definition (kit.json)
-
-```json
-{
-  "schemaVersion": "1.0.0",
-  "name": "terraform-development",
-  "version": "1.0.0",
-  "description": "Terraform development capabilities",
-  "products": ["terraform"],
-  "requires": {
-    "primitives": ["commands", "skills"]
-  },
-  "primitives": {
-    "commands": [
-      { "ref": "tf-plan@^1.0.0" },
-      { "name": "custom-cmd", "entrypoint": "./primitives/commands/custom-cmd.md" }
-    ],
-    "skills": [
-      { "name": "generate-hcl", "entrypoint": "./primitives/skills/generate-hcl" }
-    ]
-  }
-}
-```
-
-### Primitive Formats
-
-**Commands** (Markdown):
-```markdown
-# Command Name
+- CLI usage and options: [docs/cli](./docs/cli/README.md)
+- Manifests + lockfiles: [docs/manifests-lockfiles](./docs/manifests-lockfiles/README.md)
+- Primitives and resolution: [docs/primitives](./docs/primitives/README.md)
+- Hook programs and bindings: [docs/hooks](./docs/hooks/README.md)
+- Harness support + paths: [docs/harnesses](./docs/harnesses/README.md)
+- Validation and schemas: [docs/validation](./docs/validation/README.md)
+- Development + testing: [docs/development](./docs/development/README.md)
+- Troubleshooting: [docs/troubleshooting](./docs/troubleshooting/README.md)
 
-Description of what the command does.
+## CLI Commands (Summary)
 
-## Usage
-
-Instructions for using the command.
-
-## Examples
-
-Example usage scenarios.
-```
-
-**Skills** (Directory with SKILL.md):
-```
-my-skill/
-├── SKILL.md       # Main skill definition
-└── assets/        # Optional supporting files
-    └── template.hcl
-```
-
-**Subagents** (Markdown with YAML frontmatter):
-```markdown
----
-name: security-advisor
-description: Reviews Terraform configs for security issues
-model: "{{model:power}}"
-allowedTools:
-  - "{{tool:read}}"
-  - "{{tool:shell}}"
-disallowedTools: "{{tool:write}}"
-skills:
-  - generate-hcl
-hooks:
-  - ref: "pre-apply-validation@^1.0.0"
-    binding:
-      event: "tool.before"
-      matcher:
-        tools:
-          - shell
----
-
-# security-advisor
-
-<agent_role>
-You are a security-focused Terraform advisor...
-</agent_role>
+```bash
+kits install <source> [options]
+kits uninstall <kit-name> [options]
+kits upgrade [options]
+kits validate <path> [--commands|--skills|--subagents|--hooks|--mcp|--kits]
+kits list harnesses|kits
+kits info <source> [-k kit-name]
 ```
 
-Skill and subagent frontmatter `hooks` are supported by Claude Code only; other harnesses drop them during transformation.
+## Configuration and Formats
 
-### Model Templates
+- Kit repositories can be single-kit or multi-kit with registries.
+- Primitives may be shared or inline; versioned shared primitives live under `primitives/`.
+- Tool templates (`{{tool:...}}`) and model templates (`{{model:...}}`) are resolved by adapters.
 
-Skills and subagents can reference canonical model tiers in frontmatter:
-
-```yaml
-model: "{{model:fast}}"
-```
-
-Supported tiers: `fast`, `standard`, `power`, `auto`, `inherit`. Adapters map these to harness-specific model IDs (or omit the field if unsupported).
+See [docs/primitives](./docs/primitives/README.md) for detailed formats and examples.
 
 ## Development
 
-### Prerequisites
-
-- Node.js >= 18.0.0
-- npm >= 8.0.0
-
-### Setup
-
 ```bash
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Run tests
-npm test
-
-# Run tests with coverage
-npm test -- --coverage
-
-# Type check
 npm run typecheck
-
-# Lint
 npm run lint
-```
-
-### Testing Local Changes
-
-```bash
-# Build and link locally
-npm run build
-npm link
-
-# Test with local kit repository
-kits install ./path/to/local/kits
-
-# Or use directly without linking
-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 test
 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
-
-```
-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/      # kits.json intent
-│   ├── lockfile/      # kits-lock.json tracking
-│   └── core/          # Core types and utilities
-├── tests/             # Test files
-├── schemas/           # JSON schemas
-└── bin/               # CLI entrypoint
-```
+Integration tests require the devcontainer. See [docs/development](./docs/development/README.md).
 
 ## Troubleshooting
 
-### Common Issues
-
-**"No harnesses detected"**
-- Ensure at least one supported AI assistant is installed
-- Check that configuration files exist in expected locations
-
-**"Permission denied" errors**
-- Check file permissions on harness configuration directories
-- Ensure the AI assistant is not running during installation
-
-**"Source not found"**
-- Verify the source path or GitHub repository exists
-- Check network connectivity for remote sources
-
-**"Kit incompatible"**
-- The kit requires primitives not supported by the selected harness
-- Choose a compatible harness or different kit
-
-**"Scope required" (exit code 11)**
-- Non-interactive mode (`-y`) requires explicit scope selection
-- Add `--global` for user-level installation or `--project` for current directory
-- Example: `npx @hashicorp/kits install ... --global -y`
-
-**"Scope incompatible" for Codex**
-- Codex commands and MCP servers are global-only
-- 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:
-
-```bash
-npx @hashicorp/kits install example-org/kits --debug
-```
-
-Logs are written to `~/.config/agent-kit/debug.log`.
+Common issues and fixes are documented in [docs/troubleshooting](./docs/troubleshooting/README.md).
 
 ## License