craftdesk 0.3.0 → 0.5.0

package/README.md

@@ -2,9 +2,10 @@
 
 > **Dependency management for AI capabilities** - Install, manage, and version control your Claude Code skills, agents, commands, hooks, and plugins.
 
-The official command-line interface for managing CraftDesk AI capabilities. Similar to npm for JavaScript or bundler for Ruby, CraftDesk CLI provides a complete package management solution for AI-powered development tools.
+The command-line interface for managing your Coding AI capabilities. Similar to npm for JavaScript or bundler for Ruby, CraftDesk CLI provides a complete package management solution for AI-powered development tools.
 
 [![npm version](https://img.shields.io/npm/v/craftdesk.svg)](https://www.npmjs.com/package/craftdesk)
+[![CI](https://github.com/mensfeld/craftdesk/actions/workflows/ci.yml/badge.svg)](https://github.com/mensfeld/craftdesk/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
@@ -13,12 +14,17 @@ The official command-line interface for managing CraftDesk AI capabilities. Simi
 
 CraftDesk is a package manager for AI capabilities used in Claude Code and other AI development environments. It allows you to:
 
-- **Install AI skills, agents, commands, hooks, and plugins** from git repositories
+- **Install AI skills, agents, commands, hooks, plugins, and collections** from git repositories or registries
+- **Collections** - Curate and share groups of related crafts that work together
+- **Plugin system** - Bundle multiple crafts with automatic dependency resolution
+- **Multi-agent sync** - Share skills across multiple AI assistants (Claude, Cursor, Windsurf, etc.)
 - **Lock versions** for reproducible environments across teams
-- **Manage dependencies** with automatic transitive resolution
+- **Manage dependencies** with automatic recursive installation
 - **Support monorepos** with subdirectory extraction
 - **Auto-convert GitHub URLs** - paste any GitHub URL (tree/blob)
 - **Direct file references** - install single files from repositories
+- **Settings integration** - Automatic registration in `.claude/settings.json`
+- **MCP server support** - Configure Model Context Protocol servers via plugins
 
 Think of it as:
 - **npm** for Node.js → **CraftDesk** for AI capabilities
@@ -40,7 +46,7 @@ npm install -g craftdesk
 Verify installation:
 ```bash
 craftdesk --version
-# 0.2.0
+# 0.3.0
 ```
 
 **Requirements:** Node.js >= 18.0.0, Git, npm or yarn
@@ -111,7 +117,27 @@ Total: 2 crafts installed
 - [What is CraftDesk?](#what-is-craftdesk)
 - [Quick Start](#quick-start)
 - [Core Concepts](#core-concepts)
+  - [Crafts](#crafts)
+  - [Collections](#collections)
+- [Plugin System](#plugin-system)
 - [Command Reference](#command-reference)
+  - [init](#craftdesk-init-options)
+  - [install](#craftdesk-install-options)
+  - [add](#craftdesk-add-craft-options)
+  - [remove](#craftdesk-remove-craft)
+  - [list](#craftdesk-list-options)
+  - [search](#craftdesk-search-query-options)
+  - [info](#craftdesk-info-craft)
+  - [outdated](#craftdesk-outdated)
+  - [update](#craftdesk-update-craft)
+  - [publish](#craftdesk-publish-options)
+- [Embedded/Local Skills](#embeddedlocal-skills)
+  - [embed](#craftdesk-embed-name-options)
+  - [unembed](#craftdesk-unembed-name-options)
+- [Authentication](#authentication)
+  - [login](#craftdesk-login-options)
+  - [logout](#craftdesk-logout-options)
+  - [whoami](#craftdesk-whoami-options)
 - [Dependency Sources](#dependency-sources)
 - [Monorepo Support](#monorepo-support)
 - [craftdesk.json Reference](#craftdeskjson-reference)
@@ -119,6 +145,7 @@ Total: 2 crafts installed
 - [CI/CD Integration](#cicd-integration)
 - [Troubleshooting](#troubleshooting)
 - [Development](#development)
+- [Documentation](#documentation)
 
 ---
 
@@ -131,7 +158,618 @@ A **craft** is any AI capability:
 - **Agent** - Autonomous task executor (e.g., code-reviewer, test-runner)
 - **Command** - Slash command (e.g., /deploy, /analyze)
 - **Hook** - Event handler (e.g., pre-commit, post-install)
-- **Plugin** - Extended functionality or tool integration (e.g., mcp-server, custom-tools)
+- **Plugin** - Bundle of multiple crafts with dependencies and MCP server configuration
+- **Collection** - Curated group of related crafts that work together (e.g., rails-enterprise-stack)
+
+### Format Conversion
+
+**Convert CraftDesk crafts to other AI editor formats** for cross-platform use.
+
+**Supported Formats:**
+- **Cursor** - Modern `.mdc` format in `.cursor/rules/` directory
+- **Cursor Legacy** - Plain text `.cursorrules` format
+- **Continue.dev** - Prompt and rule files in `.continue/prompts/` and `.continue/rules/`
+
+**Why convert formats?**
+- **Use any AI editor** - Write once, deploy to Cursor, Continue, Windsurf, etc.
+- **Team flexibility** - Developers can use their preferred editors
+- **Maximum reach** - Distribute crafts to wider audience
+- **No lock-in** - Not tied to single platform
+
+**Basic Usage:**
+
+```bash
+# Convert a craft to Cursor format
+craftdesk convert ./my-craft --to cursor
+
+# Convert to Continue.dev format
+craftdesk convert ./my-craft --to continue
+
+# Convert to legacy .cursorrules
+craftdesk convert ./my-craft --to cursor-legacy
+
+# Convert all installed crafts
+craftdesk convert --all --to cursor --output .cursor/rules
+
+# List available formats
+craftdesk convert --list-formats
+```
+
+**Example: Rails Skill → Cursor**
+
+Your `SKILL.md`:
+```markdown
+---
+name: ruby-on-rails
+description: Ruby on Rails development
+---
+
+## Instructions
+Expert knowledge of Rails framework...
+
+## Best Practices
+- Use Strong Parameters
+- Follow RESTful conventions
+```
+
+Converted to `.cursor/rules/ruby-on-rails.mdc`:
+```markdown
+---
+description: Ruby on Rails development
+globs:
+  - "**/*.rb"
+  - "**/*.erb"
+  - "**/*.haml"
+alwaysApply: true
+---
+
+# Ruby On Rails
+
+## Overview
+Expert knowledge of Rails framework...
+
+## Best Practices
+- Use Strong Parameters
+- Follow RESTful conventions
+```
+
+**Advanced Options:**
+
+```bash
+# Merge modes
+craftdesk convert --to cursor --merge-mode skip      # Skip existing files
+craftdesk convert --to cursor --merge-mode append    # Append to existing
+craftdesk convert --to cursor --merge-mode overwrite # Overwrite (default)
+
+# Custom output directory
+craftdesk convert --to cursor --output /custom/path
+
+# Convert specific craft type
+craftdesk convert .claude/skills/ruby-rails --to continue
+```
+
+**What Gets Converted:**
+
+| Section | Cursor | Continue |
+|---------|--------|----------|
+| Instructions | ✓ Overview | ✓ Context |
+| Code Patterns | ✓ Code Patterns | ✓ Patterns to Follow |
+| Examples | ✓ Examples | ✓ Examples |
+| Best Practices | ✓ Best Practices | ✓ Best Practices |
+| Pitfalls | ✓ Mistakes to Avoid | ✓ Mistakes to Avoid |
+| Workflows | ✓ Common Workflows | ✓ Step-by-Step Workflows |
+
+**Language-Specific Features:**
+
+Cursor converter automatically infers file globs based on content:
+- **Ruby/Rails** → `**/*.rb`, `**/*.erb`, config files
+- **TypeScript** → `**/*.ts`, `**/*.tsx`
+- **Python** → `**/*.py`
+- **JavaScript** → `**/*.js`, `**/*.jsx`
+- **And more...** (Go, Rust, PHP, Java, etc.)
+
+Continue converter generates:
+- **Prompts** (invokable with `/`) - for manual use
+- **Rules** (automatic) - applied to all matching files
+
+**CI/CD Integration:**
+
+```yaml
+# .github/workflows/convert-crafts.yml
+name: Convert Crafts to Multiple Formats
+on: [push]
+jobs:
+  convert:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install CraftDesk
+        run: npm install -g craftdesk
+      - name: Convert to Cursor
+        run: craftdesk convert --all --to cursor --output dist/cursor
+      - name: Convert to Continue
+        run: craftdesk convert --all --to continue --output dist/continue
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v2
+        with:
+          name: converted-crafts
+          path: dist/
+```
+
+**Tips:**
+
+1. **Test conversions** - Always verify converted files work in target editor
+2. **Preserve originals** - Keep SKILL.md as source of truth
+3. **Update together** - Convert after each craft update
+4. **Version control** - Commit both source and converted formats
+
+### Multi-Agent Sync
+
+**Share skills across multiple AI coding assistants** - Sync your crafts to Claude Code, Cursor, Windsurf, Continue.dev, and more with automatic copy management and drift detection.
+
+**Why use multi-agent sync?**
+- **Single source of truth** - Maintain skills in one location (`.claude/skills/`)
+- **Cross-editor compatibility** - Use the same skills in Claude, Cursor, Windsurf, etc.
+- **Team flexibility** - Developers can use their preferred AI assistant
+- **Automatic sync** - Install once, sync everywhere
+- **Drift detection** - SHA-256 checksums detect modifications
+- **Windows compatible** - Copy-based (no symlinks required)
+
+**Quick Start:**
+
+```bash
+# 1. Interactive setup (recommended)
+craftdesk setup-multi-agent
+
+# 2. Detect available AI assistants
+craftdesk detect-agents
+
+# 3. Sync all crafts to configured agents
+craftdesk sync
+
+# 4. Verify sync status (check for drift)
+craftdesk verify
+```
+
+**Configuration:**
+
+Add to your `craftdesk.json`:
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "ruby-expert": "^1.0.0"
+  },
+  "multiAgent": {
+    "enabled": true,
+    "canonical": ".claude",
+    "targets": [
+      ".claude/skills",
+      ".cursor/skills",
+      ".windsurf/skills"
+    ],
+    "autoSync": true
+  }
+}
+```
+
+**How it works:**
+
+1. **Canonical Location** - Skills are installed to `.claude/skills/` (source of truth)
+2. **Target Directories** - Copies are created in `.cursor/skills/`, `.windsurf/skills/`, etc.
+3. **Checksum Tracking** - Each copy has a `.craftdesk-checksum` file (SHA-256)
+4. **Drift Detection** - `craftdesk verify` compares checksums to detect modifications
+5. **Re-sync** - `craftdesk sync` updates all copies from canonical
+
+**Example Workflow:**
+
+```bash
+# Install a new skill
+craftdesk add git+https://github.com/user/ruby-expert.git
+
+# Skills auto-sync to all agents (if autoSync: true)
+# ✓ Installed to .claude/skills/ruby-expert
+# ✓ Synced to .cursor/skills/ruby-expert
+# ✓ Synced to .windsurf/skills/ruby-expert
+
+# Verify everything is in sync
+craftdesk verify
+# ✅ All 3 craft(s) are in sync!
+
+# Later, check for drift
+craftdesk verify
+# ⚠️  ruby-expert
+#   Out of sync: .cursor/skills/ruby-expert (modified)
+
+# Re-sync to fix drift
+craftdesk sync --craft ruby-expert
+# ✅ Synced ruby-expert to 3 location(s)
+```
+
+**Supported AI Assistants:**
+
+| Assistant | Directory | Auto-Detected |
+|-----------|-----------|---------------|
+| **Claude Code** | `.claude/skills/` | ✅ Always enabled (canonical) |
+| **Cursor** | `.cursor/skills/` | ✅ Yes |
+| **Windsurf** | `.windsurf/skills/` | ✅ Yes |
+| **Continue.dev** | `.continue/skills/` | ✅ Yes |
+| **Generic .agents** | `.agents/skills/` | ✅ Yes |
+
+**Commands:**
+
+```bash
+# Setup wizard (interactive)
+craftdesk setup-multi-agent
+
+# Detect AI assistants in project
+craftdesk detect-agents
+craftdesk detect-agents --verbose
+craftdesk detect-agents --format json
+
+# Sync all crafts to all targets
+craftdesk sync
+craftdesk sync --craft ruby-expert       # Sync specific craft
+craftdesk sync --dry-run                 # Preview changes
+craftdesk sync --force                   # Force re-sync
+
+# Verify sync status
+craftdesk verify
+craftdesk verify --craft ruby-expert     # Verify specific craft
+craftdesk verify --verbose               # Show checksums
+craftdesk verify --format json           # JSON output
+```
+
+**Best Practices:**
+
+1. **Use canonical as source of truth** - Always edit skills in `.claude/skills/`
+2. **Enable autoSync** - New installs automatically sync to all agents
+3. **Run verify regularly** - Check for drift, especially in teams
+4. **Sync after manual edits** - If you edit a skill, run `craftdesk sync`
+5. **Commit canonical only** - Add target directories to `.gitignore`
+
+**gitignore Example:**
+
+```gitignore
+# Only track canonical location
+.cursor/skills/*
+.windsurf/skills/*
+.continue/skills/*
+
+# Track canonical
+!.claude/skills/
+```
+
+**Why copy instead of symlinks?**
+
+We use copy-based sync instead of symlinks for maximum compatibility:
+- ✅ **Windows compatible** - No admin privileges or Developer Mode required
+- ✅ **Git-friendly** - No `core.symlinks` complications
+- ✅ **Reliable** - Works consistently across all platforms
+- ✅ **Simple** - Easy to understand and debug
+- ✅ **Verifiable** - Checksums detect any modifications
+
+---
+
+### Embedded/Local Skills
+
+**Commit project-specific skills to your repository** alongside managed dependencies for a hybrid approach to skill management.
+
+**What are embedded skills?**
+
+Embedded skills are local, project-specific AI capabilities that are:
+- ✅ **Committed to git** - Part of your repository, versioned with your code
+- ✅ **Project-specific** - Custom skills unique to your project
+- ✅ **Team-shared** - Distributed via `git clone` (not `craftdesk install`)
+- ✅ **Auto-synced** - Sync to other AI assistants with multi-agent support
+- ⚠️ **Not managed** - No version updates via `craftdesk update`
+
+**When to embed vs. manage:**
+
+| Use Case | Embedded | Managed (dependencies) |
+|----------|----------|------------------------|
+| Project-specific business logic | ✅ | ❌ |
+| Custom team workflows | ✅ | ❌ |
+| Proprietary domain knowledge | ✅ | ❌ |
+| Shared/reusable skills | ❌ | ✅ |
+| Skills that need updates | ❌ | ✅ |
+| Skills from registry/git repos | ❌ | ✅ |
+
+**Quick Start:**
+
+```bash
+# 1. Create a local skill manually
+mkdir -p .claude/skills/my-project-skill
+cat > .claude/skills/my-project-skill/SKILL.md <<EOF
+---
+skill: my-project-skill
+version: 1.0.0
+---
+# My Project Skill
+
+Project-specific knowledge about our custom architecture...
+EOF
+
+# 2. Register it as embedded
+craftdesk embed my-project-skill
+
+# 3. Commit to git
+git add .claude/skills/my-project-skill craftdesk.json
+git commit -m "Add my-project-skill as embedded skill"
+
+# Team members get it via git clone (not craftdesk install!)
+```
+
+**Configuration:**
+
+Your `craftdesk.json` tracks embedded skills separately from dependencies:
+
+```json
+{
+  "name": "my-project",
+  "version": "1.0.0",
+  "dependencies": {
+    "ruby-expert": "^1.0.0",    // Managed, from registry
+    "postgres-expert": "^2.0.0"  // Managed, from git
+  },
+  "embedded": [
+    "my-project-skill",           // Embedded, committed to git
+    "team-coding-standards"       // Embedded, team-specific
+  ]
+}
+```
+
+**How .gitignore works:**
+
+CraftDesk automatically generates `.claude/skills/.gitignore` to:
+- ✅ **Ignore managed skills** - Not committed (installed via `craftdesk install`)
+- ✅ **Allow embedded skills** - Committed with your code
+- ✅ **Track orphans** - Skills not in either list (commented warnings)
+
+Example generated `.gitignore`:
+
+```gitignore
+# Auto-generated by CraftDesk - DO NOT EDIT
+# This file is managed automatically based on craftdesk.json and craftdesk.lock
+
+# Managed dependencies (from craftdesk.lock)
+# These are installed via `craftdesk install` and should not be committed
+postgres-expert/
+ruby-expert/
+
+# Embedded/local skills (committed to git)
+# These are project-specific and should be committed
+# NOT ignored: my-project-skill/
+# NOT ignored: team-coding-standards/
+
+# Untracked (not in craftdesk.json or craftdesk.lock)
+# Add these to dependencies or embedded list, or delete them
+# orphaned-old-skill/
+```
+
+**Commands:**
+
+#### `craftdesk embed <name> [options]`
+
+Register a skill as embedded (committed to git).
+
+**Options:**
+- `--type <type>` - Craft type: skill, agent, command, hook (default: skill)
+- `--skip-sync` - Skip multi-agent sync after embedding
+
+**Examples:**
+
+```bash
+# Embed a skill
+craftdesk embed my-local-skill
+
+# Embed an agent
+craftdesk embed my-automation-agent --type agent
+
+# Embed without syncing to other agents
+craftdesk embed team-workflow --skip-sync
+```
+
+**What happens:**
+1. ✅ Adds skill to `craftdesk.json` `embedded` array
+2. ✅ Updates `.claude/skills/.gitignore` to allow the skill
+3. ✅ Syncs to other AI assistants (if multi-agent enabled)
+
+**Requirements:**
+- Skill directory must exist (`.claude/skills/my-local-skill/`)
+- Cannot embed a managed dependency (remove from `dependencies` first)
+- Cannot embed the same skill twice
+
+---
+
+#### `craftdesk unembed <name> [options]`
+
+Unregister an embedded skill (no longer committed).
+
+**Options:**
+- `--remove` - Also delete the skill files from disk
+
+**Examples:**
+
+```bash
+# Unembed a skill (files remain on disk)
+craftdesk unembed my-local-skill
+
+# Unembed and delete files
+craftdesk unembed old-skill --remove
+```
+
+**What happens:**
+1. ✅ Removes skill from `craftdesk.json` `embedded` array
+2. ✅ Updates `.claude/skills/.gitignore` (skill becomes orphaned)
+3. ⚠️ Skill files remain unless `--remove` is used
+
+**After unembedding:**
+- Skill becomes "orphaned" (commented in `.gitignore`)
+- Manually delete files or re-embed it
+- Or add it to `dependencies` to manage it
+
+---
+
+**Workflow Examples:**
+
+**1. Create and embed a new skill:**
+
+```bash
+# Create skill directory and file
+mkdir -p .claude/skills/deployment-guide
+cat > .claude/skills/deployment-guide/SKILL.md <<'EOF'
+---
+skill: deployment-guide
+version: 1.0.0
+---
+# Deployment Guide
+
+Our custom deployment process...
+EOF
+
+# Embed it
+craftdesk embed deployment-guide
+
+# Commit
+git add .claude/skills/deployment-guide craftdesk.json
+git commit -m "Add deployment-guide skill"
+```
+
+**2. Convert managed skill to embedded:**
+
+```bash
+# You have: ruby-expert@1.0.0 (from registry)
+# You want: Modify it and commit to your repo
+
+# 1. Remove from dependencies
+craftdesk remove ruby-expert
+
+# 2. Skill files are now orphaned (but still on disk)
+
+# 3. Embed it
+craftdesk embed ruby-expert
+
+# 4. Commit your customized version
+git add .claude/skills/ruby-expert craftdesk.json
+git commit -m "Embed ruby-expert with custom modifications"
+```
+
+**3. List and identify embedded skills:**
+
+```bash
+craftdesk list
+
+# Output shows embedded badge:
+# 📚 Skills:
+#   ruby-expert@1.0.0
+#   postgres-expert@2.0.0
+#   my-project-skill@1.0.0 📌 (embedded)
+#   team-workflow@1.0.0 📌 (embedded)
+```
+
+**4. Team collaboration:**
+
+```bash
+# Developer A: Creates and embeds skill
+craftdesk embed new-feature-guide
+git add .claude/skills/new-feature-guide craftdesk.json .claude/skills/.gitignore
+git commit -m "Add new-feature-guide"
+git push
+
+# Developer B: Pulls and gets skill automatically
+git pull
+# ✅ Skill is ready to use (no craftdesk install needed!)
+
+# Multi-agent sync works too (if enabled)
+craftdesk verify
+# ✅ new-feature-guide synced to .cursor/skills/
+# ✅ new-feature-guide synced to .windsurf/skills/
+```
+
+**Best Practices:**
+
+1. **Use embedded for project-specific knowledge** - Custom workflows, business logic, proprietary info
+2. **Use managed for reusable skills** - Generic skills that can be shared across projects
+3. **Always commit .gitignore** - CraftDesk auto-generates it, keep it in git
+4. **Document embedded skills** - Add README explaining their purpose
+5. **Version embedded skills** - Update version in skill frontmatter when modified
+6. **Verify multi-agent sync** - Run `craftdesk verify` after embedding
+
+---
+
+### Collections
+
+**Collections** are crafts that group related capabilities together. Instead of installing 6 individual crafts, install one collection that includes all of them.
+
+**Why use collections?**
+- **Faster onboarding** - One command installs complete workflows
+- **Curated quality** - Experts bundle best-of-breed tools
+- **Consistent stacks** - Teams share identical setups
+- **Versioned together** - Dependencies tested to work together
+
+**Example: Rails Enterprise Stack**
+
+Create a collection in `craftdesk.json`:
+```json
+{
+  "name": "rails-enterprise-stack",
+  "version": "1.0.0",
+  "type": "collection",
+  "description": "Complete Rails enterprise development setup",
+  "dependencies": {
+    "ruby-on-rails": "^7.0.0",
+    "rspec-testing": "^3.12.0",
+    "rubocop-linter": "^1.50.0",
+    "sidekiq-background-jobs": "^7.0.0",
+    "postgresql-expert": "^15.0.0",
+    "devise-auth": "^4.9.0"
+  }
+}
+```
+
+**Installing a collection:**
+```bash
+craftdesk add git+https://github.com/company/rails-enterprise-stack.git
+```
+
+**What happens:**
+1. CraftDesk reads the collection's `craftdesk.json`
+2. Recursively resolves all 6 dependencies
+3. Installs the collection + all dependencies
+4. Creates lockfile tracking everything
+
+**Result:** 7 crafts installed (collection + 6 dependencies)
+
+**How collections work:**
+
+Collections leverage CraftDesk's **recursive dependency resolution**. When you install a craft with dependencies, CraftDesk:
+1. Clones the repository
+2. Reads `craftdesk.json`
+3. Adds all dependencies to the resolution queue
+4. Recursively resolves transitive dependencies
+5. Installs everything with a single lockfile
+
+This means **any craft with dependencies acts as a collection** - the `type: "collection"` field just improves discoverability in the registry.
+
+**Nested collections:**
+
+Collections can depend on other collections:
+```json
+{
+  "name": "full-stack-rails",
+  "type": "collection",
+  "dependencies": {
+    "rails-enterprise-stack": "^1.0.0",  // Another collection!
+    "frontend-tooling": "^2.1.0",        // Another collection!
+    "docker-deployment": "^1.5.0"
+  }
+}
+```
+
+CraftDesk handles arbitrary nesting depth with circular dependency detection.
 
 ### Manifest File: craftdesk.json
 
@@ -170,169 +808,800 @@ Records exact versions installed (like package-lock.json or Gemfile.lock):
 }
 ```
 
-**Always commit this file to version control!**
+**Always commit this file to version control!**
+
+### Security: Checksum Verification
+
+CraftDesk automatically verifies the integrity of downloaded packages:
+
+- **Registry packages**: SHA-256 checksums are computed when you first add a craft and stored in `craftdesk.lock`
+- **Subsequent installs**: The downloaded file is verified against the stored checksum before extraction
+- **MITM protection**: Prevents tampering during download by detecting any modifications
+- **Git packages**: Git commit hashes serve as checksums - stored in the lockfile and verified during clone
+
+**What happens on checksum mismatch:**
+```
+Error: Checksum verification failed for john/rails-api@2.1.0.
+Expected: a1b2c3d4e5f6...
+This may indicate a corrupted download or a security issue.
+Try running 'craftdesk install --no-lockfile' to re-resolve dependencies.
+```
+
+The lockfile contains SHA-256 hashes that ensure reproducible and secure installations across all team members.
+
+### Install Directory
+
+By default, crafts install to `.claude/` in your project:
+```
+.claude/
+├── settings.json           # Plugin configuration (auto-generated)
+├── skills/
+│   ├── ruby-on-rails/
+│   └── postgres-expert/
+├── agents/
+│   └── code-reviewer/
+├── commands/
+│   └── deploy/
+├── hooks/
+│   └── pre-commit/
+└── plugins/                # Flat plugin installation
+    ├── company-rails-plugin/
+    │   ├── plugin.json
+    │   ├── PLUGIN.md
+    │   └── skills/...
+    └── my-skill-plugin/    # Wrapped skill
+```
+
+---
+
+## Plugin System
+
+**New in v0.3.0**: CraftDesk now supports a comprehensive plugin system for bundling multiple crafts with automatic dependency management.
+
+### What are Plugins?
+
+Plugins allow you to:
+- **Bundle multiple crafts** (skills, agents, commands, hooks) together
+- **Declare dependencies** that are automatically installed
+- **Configure MCP servers** (Model Context Protocol) for external tools
+- **Share configurations** and related files as a cohesive package
+- **Wrap individual crafts** as plugins for better organization
+
+### Installing Plugins
+
+```bash
+# Install a plugin from registry
+craftdesk add company/rails-standards-plugin
+
+# What happens automatically:
+# 1. Plugin is installed to .claude/plugins/company-rails-standards-plugin/
+# 2. Dependencies are resolved and auto-installed
+# 3. Plugin is registered in .claude/settings.json
+# 4. MCP server is configured (if provided)
+# 5. Plugin tree is added to craftdesk.lock
+```
+
+**Example Output**:
+```
+Adding company/rails-standards-plugin...
+Found company/rails-standards-plugin@2.1.0
+Installing company/rails-standards-plugin...
+Plugin detected - resolving dependencies...
+Resolved 3 total dependencies
+Installing plugin dependency: john/rspec-testing...
+✓ Resolved john/rspec-testing@1.5.3
+Installing plugin dependency: jane/postgres-toolkit...
+✓ Resolved jane/postgres-toolkit@3.2.1
+✓ Installed company/rails-standards-plugin@2.1.0
+Craft added successfully!
+```
+
+### Plugin Structure
+
+A plugin contains a `plugin.json` manifest:
+
+```json
+{
+  "name": "company-rails-plugin",
+  "version": "2.1.0",
+  "type": "plugin",
+  "description": "Rails development standards",
+  "author": "company",
+  "components": {
+    "skills": ["coding-standards", "rails-best-practices"],
+    "agents": ["standards-enforcer"],
+    "commands": ["check-standards"]
+  },
+  "dependencies": {
+    "john/rspec-testing": "^1.5.0",
+    "jane/postgres-toolkit": "^3.2.0"
+  },
+  "mcp": {
+    "type": "stdio",
+    "command": "/usr/bin/rails-standards-mcp",
+    "args": ["--config", ".claude/plugins/company-rails-plugin/config.json"]
+  }
+}
+```
+
+### Automatic Dependency Resolution
+
+When you install a plugin, **all dependencies are automatically installed**:
+
+```bash
+$ craftdesk add company/rails-plugin
+
+# Installs dependency tree:
+# company/rails-plugin (direct)
+#   ├── john/rspec-testing (dependency)
+#   └── jane/postgres-toolkit (dependency)
+#     └── jane/sql-helpers (nested dependency)
+```
+
+All dependencies are:
+- ✅ Downloaded from their respective sources (registry/git)
+- ✅ Installed to appropriate directories
+- ✅ Verified with integrity checksums
+- ✅ Marked as dependencies in lockfile
+- ✅ Registered in `.claude/settings.json`
+
+### Wrapping Individual Crafts
+
+Convert any skill, agent, command, or hook into a plugin:
+
+```bash
+craftdesk add my-skill --as-plugin
+```
+
+**What happens**:
+1. Original craft installed to `.claude/skills/my-skill/`
+2. Plugin wrapper created at `.claude/plugins/my-skill-plugin/`
+3. `plugin.json` and `PLUGIN.md` auto-generated
+4. Craft files copied to plugin structure
+5. Registered in settings as wrapped plugin
+
+**Use cases**:
+- Add MCP server to existing skill
+- Bundle configuration with craft
+- Prepare for publishing to marketplace
+- Enable/disable craft from Claude Code UI
+
+### Plugin Tree Visualization
+
+View your plugin dependency tree:
+
+```bash
+$ craftdesk list
+
+my-project@1.0.0
+
+🔌 Plugins:
+  company/rails-standards@2.1.0
+    ├── john/rspec-testing@1.5.3
+    └── jane/postgres-toolkit@3.2.1
+  my-skill-plugin@1.0.0
+
+📚 Skills:
+  standalone-skill@1.0.0
+
+Total: 5 crafts installed
+```
+
+### Removing Plugins with Dependencies
+
+CraftDesk prevents accidental removal of required dependencies:
+
+```bash
+$ craftdesk remove john/rspec-testing
+
+Warning: john/rspec-testing is required by:
+  - company/rails-standards@2.1.0
+
+Use --force to remove anyway
+```
+
+Force removal:
+```bash
+craftdesk remove john/rspec-testing --force
+```
+
+### Settings Integration
+
+Plugins are automatically registered in `.claude/settings.json`:
+
+```json
+{
+  "version": "1.0.0",
+  "plugins": {
+    "company-rails-plugin": {
+      "name": "company-rails-plugin",
+      "version": "2.1.0",
+      "enabled": true,
+      "installPath": "plugins/company-rails-plugin",
+      "dependencies": ["john-rspec-testing", "jane-postgres-toolkit"],
+      "mcp": {
+        "type": "stdio",
+        "command": "/usr/bin/rails-standards-mcp",
+        "args": ["--config", ".claude/plugins/company-rails-plugin/config.json"]
+      }
+    }
+  }
+}
+```
+
+**For complete details**, see [DEPENDENCY_MANAGEMENT.md](./DEPENDENCY_MANAGEMENT.md)
+
+---
+
+## Command Reference
+
+### `craftdesk init [options]`
+
+Initialize a new craftdesk.json file.
+
+**Options:**
+- `-y, --yes` - Skip prompts and use defaults
+- `-n, --name <name>` - Project name (default: directory name)
+- `-v, --version <version>` - Project version (default: "1.0.0")
+- `-t, --type <type>` - Project type: skill, agent, command, hook, plugin, or collection (default: "skill")
+- `-d, --description <desc>` - Project description
+- `-a, --author <author>` - Author name
+- `-l, --license <license>` - License (default: "MIT")
+
+**Examples:**
+```bash
+# Interactive initialization
+craftdesk init
+
+# Quick init with defaults
+craftdesk init -y
+
+# Specify options
+craftdesk init --name my-skill --type skill --author "Your Name"
+```
+
+---
+
+### `craftdesk install [options]`
+
+Install all dependencies from craftdesk.json.
+
+**Options:**
+- `--no-lockfile` - Ignore craftdesk.lock and re-resolve dependencies
+- `--production` - Skip devDependencies
+
+**Examples:**
+```bash
+# Install all dependencies
+craftdesk install
+
+# Or use the alias
+craftdesk i
+
+# Production install (skip dev dependencies)
+craftdesk install --production
+
+# Force re-resolve (ignore lockfile)
+craftdesk install --no-lockfile
+```
+
+**What it does:**
+1. Reads craftdesk.json
+2. Uses craftdesk.lock if present (ensures reproducibility)
+3. Resolves dependencies (registry + git sources)
+4. Installs to .claude/ directory
+5. Updates/creates craftdesk.lock
+
+---
+
+### `craftdesk add <craft> [options]`
+
+Add a new dependency and install it immediately.
+
+**Options:**
+- `-D, --save-dev` - Save as devDependency
+- `-O, --save-optional` - Save as optionalDependency
+- `-E, --save-exact` - Save exact version (no ^ or ~)
+- `-t, --type <type>` - Specify craft type (skill, agent, command, hook, plugin, collection)
+
+**Examples:**
+
+```bash
+# GitHub web URLs (auto-converted)
+craftdesk add https://github.com/user/repo/blob/main/skill.md
+craftdesk add https://github.com/user/repo/tree/main/skills/auth
+
+# With explicit type
+craftdesk add https://github.com/user/repo/blob/main/agent.md --type agent
+
+# Git dependencies (manual format)
+craftdesk add git+https://github.com/user/repo.git
+craftdesk add git+https://github.com/user/repo.git#develop
+craftdesk add git+https://github.com/user/repo.git#v2.0.0
+
+# Direct file reference
+craftdesk add git+https://github.com/user/repo.git#main#file:skill.md
+
+# Subdirectory (monorepo)
+craftdesk add git+https://github.com/company/monorepo.git#main#path:skills/auth
+```
+
+---
+
+### `craftdesk remove <craft>`
+
+Remove a dependency from craftdesk.json and the filesystem.
+
+**Examples:**
+```bash
+craftdesk remove my-skill
+craftdesk remove my-agent
+```
+
+---
+
+### `craftdesk list [options]`
+
+List installed crafts.
+
+**Options:**
+- `--tree` - Show dependency tree
+- `--depth <n>` - Limit tree depth
+- `--json` - Output as JSON
+
+**Examples:**
+```bash
+# Simple list
+craftdesk list
+
+# Show dependency tree
+craftdesk list --tree
+
+# Limit tree depth
+craftdesk list --tree --depth 2
+
+# JSON output (for scripts)
+craftdesk list --json
+```
+
+**Example output:**
+```
+my-project@1.0.0
+
+Installed crafts:
+  • my-skill@main (skill)
+  • code-reviewer@v2.0.1 (agent)
+  • postgres-expert@main (skill)
+
+Total: 3 crafts installed
+```
+
+---
+
+### `craftdesk search <query> [options]`
+
+Search for crafts in the registry.
+
+**Options:**
+- `-t, --type <type>` - Filter by type (skill, agent, command, hook, plugin, collection)
+
+**Examples:**
+```bash
+# Search for crafts
+craftdesk search kafka
+
+# Search for skills only
+craftdesk search rails --type skill
+
+# Search for plugins
+craftdesk search standards --type plugin
+```
+
+**Example output:**
+```
+Search results for "kafka":
+
+  john/kafka-processing@2.1.0 (skill)
+    Expert knowledge for processing Kafka messages
+
+  jane/kafka-agent@1.5.3 (agent)
+    Autonomous agent for Kafka stream management
+
+Found 2 crafts
+```
+
+---
+
+### `craftdesk info <craft>`
+
+Display detailed information about a craft from the registry.
+
+**Examples:**
+```bash
+# Get info about a craft
+craftdesk info john/rails-api
+
+# Get info about a specific version
+craftdesk info john/rails-api@2.1.0
+```
+
+**Example output:**
+```
+john/rails-api@2.1.0
+
+  Description: Rails API development best practices
+  Type:        skill
+  Author:      john
+  License:     MIT
+  Downloads:   1,234
+
+  Versions:
+    2.1.0 (latest)
+    2.0.0
+    1.5.0
+
+  Dependencies:
+    jane/postgres-toolkit: ^1.0.0
+```
+
+---
+
+### `craftdesk outdated`
+
+Check for outdated dependencies that have newer versions available.
+
+**Examples:**
+```bash
+# Check all dependencies
+craftdesk outdated
+```
+
+**Example output:**
+```
+Checking for outdated dependencies...
+
+Outdated crafts:
+
+  john/rails-api
+    Current: 2.0.0
+    Latest:  2.1.0
+    Type:    skill
+
+  jane/postgres-toolkit
+    Current: 1.2.0
+    Latest:  1.5.0
+    Type:    skill
+
+2 outdated crafts found
+Run 'craftdesk update' to update all, or 'craftdesk update <craft>' to update specific crafts.
+```
+
+---
+
+### `craftdesk update [craft]`
+
+Update dependencies to their latest compatible versions.
+
+**Examples:**
+```bash
+# Update all outdated dependencies
+craftdesk update
+
+# Update a specific craft
+craftdesk update john/rails-api
+```
+
+**What it does:**
+1. Checks for newer versions in the registry
+2. Downloads and installs updates
+3. Updates craftdesk.lock with new versions
+4. Verifies checksums for security
+
+---
+
+### `craftdesk publish [options]`
+
+Publish a craft to the registry.
+
+**Options:**
+- `--visibility <level>` - Set visibility: public, private, or organization (default: public)
+
+**Examples:**
+```bash
+# Publish the current craft
+craftdesk publish
 
-### Install Directory
+# Publish as private
+craftdesk publish --visibility private
 
-By default, crafts install to `.claude/` in your project:
-```
-.claude/
-├── skills/
-│   ├── ruby-on-rails/
-│   └── postgres-expert/
-├── agents/
-│   └── code-reviewer/
-├── commands/
-│   └── deploy/
-└── hooks/
-    └── pre-commit/
+# Publish to organization only
+craftdesk publish --visibility organization
 ```
 
+**Prerequisites:**
+- Must be logged in (`craftdesk login`)
+- Must have a valid `craftdesk.json` in current directory
+- Craft files must exist (SKILL.md, AGENT.md, etc.)
+
+**What it does:**
+1. Reads craftdesk.json for metadata
+2. Collects all craft files
+3. Creates a new version on the registry
+4. Publishes with specified visibility
+
 ---
 
-## Command Reference
+### `craftdesk setup-multi-agent [options]`
 
-### `craftdesk init [options]`
+Interactive wizard to configure multi-agent sync.
 
-Initialize a new craftdesk.json file.
+**Options:**
+- `--auto-sync` - Enable automatic sync on install/update
+- `--skip-sync` - Skip initial sync after setup
+
+**Examples:**
+```bash
+# Interactive setup (recommended)
+craftdesk setup-multi-agent
+
+# Setup with auto-sync enabled
+craftdesk setup-multi-agent --auto-sync
+
+# Setup without initial sync
+craftdesk setup-multi-agent --skip-sync
+```
+
+**What it does:**
+1. Detects AI coding assistants in your project
+2. Lets you choose which agents to sync to
+3. Updates `craftdesk.json` with multiAgent configuration
+4. Optionally performs initial sync of existing crafts
+
+---
+
+### `craftdesk detect-agents [options]`
+
+Detect AI coding assistants installed in the project.
 
 **Options:**
-- `-y, --yes` - Skip prompts and use defaults
-- `-n, --name <name>` - Project name (default: directory name)
-- `-v, --version <version>` - Project version (default: "1.0.0")
-- `-t, --type <type>` - Project type: skill, agent, command, hook, or plugin (default: "skill")
-- `-d, --description <desc>` - Project description
-- `-a, --author <author>` - Author name
-- `-l, --license <license>` - License (default: "MIT")
+- `-v, --verbose` - Show detailed detection information
+- `-f, --format <format>` - Output format: text or json (default: text)
 
 **Examples:**
 ```bash
-# Interactive initialization
-craftdesk init
+# Detect agents
+craftdesk detect-agents
 
-# Quick init with defaults
-craftdesk init -y
+# Verbose output
+craftdesk detect-agents --verbose
 
-# Specify options
-craftdesk init --name my-skill --type skill --author "Your Name"
+# JSON output for scripting
+craftdesk detect-agents --format json
+```
+
+**Example output:**
+```
+🔍 AI Coding Assistant Detection
+
+Detected Agents:
+  ✓ Claude Code
+    Directory: .claude/skills
+    Status: ✅ Enabled
+
+  ○ Cursor
+    Directory: .cursor/skills
+    Status: ⚪ Available
+
+Summary:
+  Detected: 2 agent(s)
+  Enabled: 1 agent(s)
+
+💡 Tip:
+  You have multiple agents but sync is only enabled for one.
+  Run `craftdesk setup-multi-agent` to sync across all agents.
 ```
 
 ---
 
-### `craftdesk install [options]`
+### `craftdesk sync [options]`
 
-Install all dependencies from craftdesk.json.
+Sync crafts to all configured AI agents.
 
 **Options:**
-- `--no-lockfile` - Ignore craftdesk.lock and re-resolve dependencies
-- `--production` - Skip devDependencies
+- `-c, --craft <name>` - Sync specific craft by name
+- `-f, --force` - Force sync even if checksums match
+- `--dry-run` - Show what would be synced without making changes
 
 **Examples:**
 ```bash
-# Install all dependencies
-craftdesk install
+# Sync all crafts
+craftdesk sync
 
-# Or use the alias
-craftdesk i
+# Sync specific craft
+craftdesk sync --craft ruby-expert
 
-# Production install (skip dev dependencies)
-craftdesk install --production
+# Dry run (preview changes)
+craftdesk sync --dry-run
 
-# Force re-resolve (ignore lockfile)
-craftdesk install --no-lockfile
+# Force sync
+craftdesk sync --force
 ```
 
 **What it does:**
-1. Reads craftdesk.json
-2. Uses craftdesk.lock if present (ensures reproducibility)
-3. Resolves dependencies (registry + git sources)
-4. Installs to .claude/ directory
-5. Updates/creates craftdesk.lock
+1. Reads multiAgent configuration from craftdesk.json
+2. Copies crafts from canonical location to all targets
+3. Calculates and stores SHA-256 checksums
+4. Reports sync status for each location
+
+**Example output:**
+```
+✅ Synced 5 craft(s)
+
+✓ ruby-expert: 3 location(s)
+✓ python-expert: 3 location(s)
+✓ postgres-expert: 3 location(s)
+✓ docker-expert: 3 location(s)
+✓ git-expert: 3 location(s)
+
+Summary:
+  Total synced: 15 location(s)
+```
 
 ---
 
-### `craftdesk add <craft> [options]`
+### `craftdesk verify [options]`
 
-Add a new dependency and install it immediately.
+Verify sync status of crafts across AI agents using checksum validation.
 
 **Options:**
-- `-D, --save-dev` - Save as devDependency
-- `-O, --save-optional` - Save as optionalDependency
-- `-E, --save-exact` - Save exact version (no ^ or ~)
-- `-t, --type <type>` - Specify craft type (skill, agent, command, hook, plugin)
+- `-c, --craft <name>` - Verify specific craft by name
+- `-v, --verbose` - Show detailed checksum information
+- `-f, --format <format>` - Output format: text or json (default: text)
 
 **Examples:**
-
 ```bash
-# GitHub web URLs (auto-converted)
-craftdesk add https://github.com/user/repo/blob/main/skill.md
-craftdesk add https://github.com/user/repo/tree/main/skills/auth
+# Verify all crafts
+craftdesk verify
 
-# With explicit type
-craftdesk add https://github.com/user/repo/blob/main/agent.md --type agent
+# Verify specific craft
+craftdesk verify --craft ruby-expert
 
-# Git dependencies (manual format)
-craftdesk add git+https://github.com/user/repo.git
-craftdesk add git+https://github.com/user/repo.git#develop
-craftdesk add git+https://github.com/user/repo.git#v2.0.0
+# Verbose output with checksums
+craftdesk verify --verbose
 
-# Direct file reference
-craftdesk add git+https://github.com/user/repo.git#main#file:skill.md
+# JSON output
+craftdesk verify --format json
+```
 
-# Subdirectory (monorepo)
-craftdesk add git+https://github.com/company/monorepo.git#main#path:skills/auth
+**What it does:**
+1. Reads multiAgent configuration
+2. Calculates SHA-256 checksums for all copies
+3. Compares checksums to detect drift
+4. Reports which copies are in sync vs. out of sync
+
+**Example output (in sync):**
+```
+🔍 Sync Status: All Crafts
+
+Summary:
+  Total crafts: 5
+  In sync: 5
+  Out of sync: 0
+
+✅ All 5 craft(s) are in sync!
+```
+
+**Example output (drift detected):**
+```
+🔍 Sync Status: All Crafts
+
+Summary:
+  Total crafts: 5
+  In sync: 4
+  Out of sync: 1
+
+❌ Out of Sync (1):
+
+  ruby-expert
+    ⚠️  .cursor/skills/ruby-expert (modified)
+
+💡 Run `craftdesk sync` to fix all issues
 ```
 
 ---
 
-### `craftdesk remove <craft>`
+## Authentication
 
-Remove a dependency from craftdesk.json and the filesystem.
+CraftDesk supports authenticated access to private registries.
+
+### `craftdesk login [options]`
+
+Authenticate with a registry using an API token.
+
+**Options:**
+- `-r, --registry <url>` - Registry URL (uses default from craftdesk.json if not specified)
 
 **Examples:**
 ```bash
-craftdesk remove my-skill
-craftdesk remove my-agent
+# Login to default registry
+craftdesk login
+
+# Login to a specific registry
+craftdesk login --registry https://private.company.com
 ```
 
+**How it works:**
+1. Prompts for your API token
+2. Verifies the token with the registry
+3. Stores credentials in `~/.craftdesk/config.json`
+4. Token is used for subsequent registry operations
+
+**Getting an API token:**
+- Log in to your CraftDesk registry web interface
+- Navigate to Settings → API Tokens
+- Generate a new token
+
 ---
 
-### `craftdesk list [options]`
+### `craftdesk logout [options]`
 
-List installed crafts.
+Remove stored authentication credentials.
 
 **Options:**
-- `--tree` - Show dependency tree
-- `--depth <n>` - Limit tree depth
-- `--json` - Output as JSON
+- `-r, --registry <url>` - Registry URL (uses default from craftdesk.json if not specified)
 
 **Examples:**
 ```bash
-# Simple list
-craftdesk list
+# Logout from default registry
+craftdesk logout
 
-# Show dependency tree
-craftdesk list --tree
+# Logout from specific registry
+craftdesk logout --registry https://private.company.com
+```
 
-# Limit tree depth
-craftdesk list --tree --depth 2
+---
 
-# JSON output (for scripts)
-craftdesk list --json
+### `craftdesk whoami [options]`
+
+Display the currently logged-in user.
+
+**Options:**
+- `-r, --registry <url>` - Registry URL (uses default from craftdesk.json if not specified)
+
+**Examples:**
+```bash
+# Check current user
+craftdesk whoami
+
+# Check user for specific registry
+craftdesk whoami --registry https://private.company.com
 ```
 
 **Example output:**
 ```
-my-project@1.0.0
+Logged in to https://craftdesk.ai as john (john@example.com)
+Organization: acme-corp
+```
 
-Installed crafts:
-  • my-skill@main (skill)
-  • code-reviewer@v2.0.1 (agent)
-  • postgres-expert@main (skill)
+---
 
-Total: 3 crafts installed
+### Environment Variable Authentication
+
+For CI/CD environments, you can use environment variables instead of `craftdesk login`:
+
+```bash
+# For a registry named "company-private" in craftdesk.json
+export CRAFTDESK_AUTH_COMPANY_PRIVATE=your_api_token_here
+
+# For the default registry
+export CRAFTDESK_AUTH_LOCALHOST_3000=your_api_token_here
+
+# The variable name is derived from the registry URL:
+# https://example.com -> CRAFTDESK_AUTH_EXAMPLE_COM
 ```
 
+Environment variables take precedence over stored credentials.
+
 ---
 
 ### Global Options
@@ -354,9 +1623,75 @@ craftdesk init --help
 
 ## Dependency Sources
 
-CraftDesk currently supports Git dependencies. Registry support is under development.
+CraftDesk supports both registry and git dependencies.
+
+### 1. Registry Dependencies (CraftDesk Web API)
+
+Install crafts from the CraftDesk registry using `author/name` format:
+
+```bash
+# Search for crafts
+craftdesk search kafka
+
+# Get information about a craft
+craftdesk info john/rails-api
 
-### 1. GitHub URLs (Easiest)
+# Add from registry
+craftdesk add john/rails-api
+craftdesk add john/rails-api@^2.1.0
+
+# Add with specific version
+craftdesk add jane/postgres-expert@1.2.0
+```
+
+**Registry format in craftdesk.json:**
+
+```json
+{
+  "dependencies": {
+    "john/rails-api": "^2.1.0",
+    "jane/kafka-processing": "~1.5.2",
+    "team/postgres-admin": "latest"
+  },
+  "registries": {
+    "default": {
+      "url": "http://localhost:3000"
+    }
+  }
+}
+```
+
+**Important:** You must configure your registry URL in `craftdesk.json` to use registry-based crafts. Git-based dependencies (GitHub URLs) work without any registry configuration.
+
+**Private Registry Authentication:**
+
+For private registries, set authentication tokens via environment variables:
+
+```bash
+# For a registry named "company-private" in craftdesk.json
+export CRAFTDESK_AUTH_COMPANY_PRIVATE=your_token_here
+
+# For default registry
+export CRAFTDESK_AUTH_DEFAULT=your_token_here
+```
+
+Example `craftdesk.json` with private registry:
+
+```json
+{
+  "registries": {
+    "default": {
+      "url": "https://your-registry.com"
+    },
+    "company-private": {
+      "url": "https://private.company.com",
+      "scope": "@company"
+    }
+  }
+}
+```
+
+### 2. GitHub URLs (Easiest for Git)
 
 Simply paste any GitHub URL - it auto-converts to the correct format:
 
@@ -371,7 +1706,7 @@ craftdesk add https://github.com/user/repo/blob/main/agent.md
 craftdesk add https://github.com/user/repo
 ```
 
-### 2. Git Dependencies
+### 3. Git Dependencies
 
 From git repositories:
 
@@ -402,26 +1737,60 @@ From git repositories:
 - `path` - Subdirectory within repo (for monorepos)
 - `file` - Direct file path (for single-file crafts)
 
-### 3. Registry Dependencies (Coming Soon)
+---
 
-> **Note:** Registry support is currently under development. A self-hosted registry server will be available soon.
+## Monorepo Support
 
-Future registry format:
+CraftDesk has **full support for monorepo workflows**, allowing you to install crafts from subdirectories within a repository. This is perfect for teams maintaining multiple related crafts in one repository.
 
-```json
-{
-  "dependencies": {
-    "ruby-on-rails": "^7.0.0",
-    "@company/internal-skill": "^2.0.0"
-  }
-}
+### Quick Start: Auto-Converting GitHub URLs
+
+The easiest way to install from monorepos is to **paste GitHub web URLs directly**:
+
+```bash
+# Subdirectory from monorepo - just paste the GitHub URL!
+craftdesk add https://github.com/company/monorepo/tree/main/skills/auth
+
+# Single file from monorepo
+craftdesk add https://github.com/company/monorepo/blob/main/skills/auth/SKILL.md
+
+# Works with any branch or tag
+craftdesk add https://github.com/company/monorepo/tree/v2.0.0/packages/deployer
 ```
 
----
+CraftDesk automatically converts these to the correct git syntax and extracts only the specified subdirectory or file.
 
-## Monorepo Support
+### Git URL Syntax
+
+For more control, use explicit git URL syntax with path or file specifiers:
+
+```bash
+# Subdirectory with branch
+craftdesk add git+https://github.com/company/monorepo.git#main#path:skills/auth
 
-Install multiple crafts from the same git repository using subdirectory paths:
+# Subdirectory with tag
+craftdesk add git+https://github.com/company/monorepo.git#v2.0.0#path:packages/deployer
+
+# Subdirectory with commit hash
+craftdesk add git+https://github.com/company/monorepo.git#abc123def#path:skills/auth
+
+# Single file with branch
+craftdesk add git+https://github.com/company/monorepo.git#main#file:skills/auth/SKILL.md
+
+# Just path (uses default branch)
+craftdesk add git+https://github.com/company/monorepo.git#path:skills/auth
+```
+
+**Syntax breakdown:**
+- `#main` - Branch name
+- `#v2.0.0` - Git tag
+- `#abc123def` - Commit hash (full 40-char)
+- `#path:skills/auth` - Subdirectory to extract
+- `#file:skill.md` - Single file to extract
+
+### Using in craftdesk.json
+
+Multiple crafts from the same monorepo:
 
 ```json
 {
@@ -436,41 +1805,90 @@ Install multiple crafts from the same git repository using subdirectory paths:
       "tag": "v3.2.0",
       "path": "agents/processor"
     },
-    "report-generator": {
+    "deploy-script": {
       "git": "https://github.com/company/ai-crafts-monorepo.git",
       "tag": "v3.2.0",
-      "path": "skills/reporting"
+      "file": "scripts/deploy.md"
     }
   }
 }
 ```
 
-**Benefits:**
-- Single git repository for multiple crafts
-- Version them together with git tags
-- Each craft installs independently
-- Efficient cloning (repo cached during resolution)
+**Each craft can:**
+- Use different subdirectories (`path`)
+- Reference single files (`file`)
+- Use the same or different tags/branches
+- Be versioned independently or together
+
+### Benefits
+
+✅ **Single repository** for multiple related crafts
+✅ **Version together** using git tags (or independently with branches)
+✅ **Efficient cloning** - repository is cloned once and reused
+✅ **Clear organization** - keep related crafts together
+✅ **Atomic updates** - update all crafts by changing the tag
+✅ **Works with private repos** - standard git authentication
+
+### Monorepo Structure Example
 
-**Monorepo structure example:**
 ```
 ai-crafts-monorepo/
 ├── skills/
 │   ├── auth/
 │   │   ├── craftdesk.json
 │   │   └── SKILL.md
+│   ├── database/
+│   │   ├── craftdesk.json
+│   │   └── SKILL.md
 │   └── reporting/
 │       ├── craftdesk.json
 │       └── SKILL.md
 ├── agents/
-│   └── processor/
+│   ├── code-reviewer/
+│   │   ├── craftdesk.json
+│   │   └── AGENT.md
+│   └── test-runner/
 │       ├── craftdesk.json
 │       └── AGENT.md
-└── commands/
-    └── deploy/
-        ├── craftdesk.json
-        └── COMMAND.md
+├── commands/
+│   └── deploy/
+│       ├── craftdesk.json
+│       └── COMMAND.md
+└── scripts/
+    ├── setup.md
+    └── deploy.md
 ```
 
+### Lockfile Tracking
+
+CraftDesk lockfile tracks the exact subdirectory and commit:
+
+```json
+{
+  "crafts": {
+    "auth-handler": {
+      "git": "https://github.com/company/monorepo.git",
+      "tag": "v3.2.0",
+      "commit": "abc123def456...",
+      "path": "skills/auth",
+      "type": "skill",
+      "version": "3.2.0"
+    }
+  }
+}
+```
+
+This ensures **reproducible installations** - the exact subdirectory from the exact commit is always installed.
+
+### Real-World Example
+
+```bash
+# Install from technicalpickles' monorepo
+craftdesk add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/working-in-monorepos/skills/working-in-monorepos
+```
+
+This installs only the `working-in-monorepos` skill from the deeply nested monorepo structure.
+
 ---
 
 ## craftdesk.json Reference
@@ -528,7 +1946,7 @@ Complete specification of the craftdesk.json format:
 |-------|------|----------|-------------|
 | `name` | string | Yes | Craft name (lowercase, no spaces) |
 | `version` | string | Yes | Semantic version (e.g., "1.0.0") |
-| `type` | string | No | Craft type: skill, agent, command, hook, plugin |
+| `type` | string | No | Craft type: skill, agent, command, hook, plugin, collection |
 | `description` | string | No | Short description |
 | `author` | string | No | Author name and email |
 | `license` | string | No | License identifier (e.g., "MIT") |
@@ -740,11 +2158,46 @@ npm test
 
 ### Publishing
 
+CraftDesk uses automated NPM publishing via GitHub Actions with provenance attestation.
+
+**Quick release:**
+```bash
+./scripts/release.sh patch   # 0.3.0 → 0.3.1
+./scripts/release.sh minor   # 0.3.0 → 0.4.0
+./scripts/release.sh major   # 0.3.0 → 1.0.0
+```
+
+The script will:
+1. Bump version in package.json
+2. Prompt you to update CHANGELOG.md
+3. Commit and push changes
+4. Create GitHub release
+5. GitHub Actions automatically publishes to NPM with provenance
+
+**Manual process:**
 ```bash
 npm version patch
-npm publish
+git add package.json CHANGELOG.md
+git commit -m "Bump to 0.3.1"
+git push
+gh release create v0.3.1 --title "v0.3.1" --generate-notes
 ```
 
+See [NPM_PUBLISHING_GUIDE.md](./NPM_PUBLISHING_GUIDE.md) for complete setup instructions.
+
+---
+
+## Documentation
+
+### Core Documentation
+- **[README.md](./README.md)** - This file, general overview and quick start
+- **[DEPENDENCY_MANAGEMENT.md](./DEPENDENCY_MANAGEMENT.md)** - Complete guide to dependency management
+- **[PLUGIN_IMPLEMENTATION_COMPLETE.md](./PLUGIN_IMPLEMENTATION_COMPLETE.md)** - Plugin system implementation details
+
+### Additional Resources
+- **[Package.json](./package.json)** - Project metadata and scripts
+- **[TypeScript Source](./src/)** - Full source code
+
 ---
 
 ## License
@@ -757,22 +2210,46 @@ MIT
 
 - **Repository**: [https://github.com/mensfeld/craftdesk](https://github.com/mensfeld/craftdesk)
 - **Issues**: [https://github.com/mensfeld/craftdesk/issues](https://github.com/mensfeld/craftdesk/issues)
-- **Registry** (Coming Soon): Self-hosted registry server under development
+- **Registry**: Self-hosted registry server available at [CraftDesk Web](../web)
 
 ---
 
 ## Roadmap
 
+### Completed (v0.3.0)
 - ✅ Git dependency support
 - ✅ GitHub URL auto-conversion
 - ✅ Direct file references
 - ✅ Monorepo support
 - ✅ Lockfile-based version control
-- 🚧 Self-hosted registry server (in development)
-- 🚧 Private registry authentication
-- 🚧 Dependency conflict resolution
-- 🚧 Semantic versioning for registry packages
+- ✅ Self-hosted registry server support
+- ✅ ZIP archive extraction for registry crafts
+- ✅ **Plugin system** with dependency management
+- ✅ **Auto-install plugin dependencies** (recursive)
+- ✅ **Settings integration** (.claude/settings.json)
+- ✅ **MCP server configuration** via plugins
+- ✅ **Craft wrapping** (--as-plugin flag)
+- ✅ **Plugin tree visualization**
+- ✅ **Dependency removal protection**
+- ✅ SHA-256 checksum verification (MITM protection)
+- ✅ Registry search and info commands
+- ✅ `craftdesk publish` command
+- ✅ `craftdesk outdated` command
+- ✅ `craftdesk update` command
+- ✅ **Authentication system** (login/logout/whoami)
+- ✅ **Private registry authentication** (token-based)
+- ✅ **Environment variable auth** (CI/CD support)
+- ✅ Semantic versioning for registry packages
+
+### Planned
+- 🔲 Plugin marketplace/directory
+- 🔲 `craftdesk validate <plugin>` command
+- 🔲 Multiple dependency versions support
+- 🔲 Peer dependency warnings
+- 🔲 Persistent download cache
+- 🔲 Offline installation mode
+- 🔲 Interactive dependency conflict resolution
 
 ---
 
-Made for the AI development community
+Made for the AI development community