craftdesk 0.2.0 → 0.4.0

package/README.md

@@ -1,42 +1,29 @@
 # CraftDesk CLI
 
-> **Dependency management for AI capabilities** - Install, manage, and version control your Claude Code skills, agents, commands, and hooks.
+> **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)
 
 ---
 
-## Table of Contents
-
-- [What is CraftDesk?](#what-is-craftdesk)
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-- [Command Reference](#command-reference)
-- [Dependency Sources](#dependency-sources)
-- [Multi-Registry Setup](#multi-registry-setup)
-- [Monorepo Support](#monorepo-support)
-- [craftdesk.json Reference](#craftdeskjson-reference)
-- [craftdesk.lock](#craftdesklock)
-- [CI/CD Integration](#cicd-integration)
-- [Troubleshooting](#troubleshooting)
-- [Development](#development)
-
----
-
 ## What is CraftDesk?
 
 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, and hooks** 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
 - **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
@@ -47,9 +34,9 @@ Think of it as:
 
 ---
 
-## Installation
+## Quick Start
 
-### Global Installation
+### Install CraftDesk
 
 ```bash
 npm install -g craftdesk
@@ -58,30 +45,10 @@ npm install -g craftdesk
 Verify installation:
 ```bash
 craftdesk --version
-# 0.2.0
-```
-
-### Local Development Setup
-
-Clone and link for development:
-
-```bash
-git clone https://github.com/mensfeld/craftdesk.git
-cd craftdesk
-npm install
-npm link
-craftdesk --version
+# 0.3.0
 ```
 
-### Requirements
-
-- Node.js >= 18.0.0
-- Git (for git dependencies)
-- npm or yarn
-
----
-
-## Quick Start
+**Requirements:** Node.js >= 18.0.0, Git, npm or yarn
 
 ### 1. Initialize a New Project
 
@@ -104,17 +71,17 @@ This creates a `craftdesk.json` file:
 ### 2. Add Dependencies
 
 ```bash
-# Add from GitHub (auto-converts web URLs)
-craftdesk add https://github.com/user/repo/blob/main/skill.md
+# Add a single skill file from GitHub (auto-converts web URLs)
+craftdesk add https://github.com/aviflombaum/rspec-rails-agents/blob/main/rspec-dry-agent.md
 
 # Add from git repository
-craftdesk add git+https://github.com/user/custom-agent.git
+craftdesk add git+https://github.com/aviflombaum/rspec-rails-agents.git
 
 # Add from monorepo subdirectory
-craftdesk add https://github.com/user/repo/tree/main/skills/auth
+craftdesk add https://github.com/technicalpickles/pickled-claude-plugins/tree/main/plugins/working-in-monorepos/skills/working-in-monorepos
 
 # Add with explicit type
-craftdesk add https://github.com/user/repo/blob/main/agent.md --type agent
+craftdesk add https://github.com/aviflombaum/rspec-rails-agents/blob/main/rspec-dry-agent.md --type agent
 ```
 
 ### 3. Install Everything
@@ -144,6 +111,40 @@ Total: 2 crafts installed
 
 ---
 
+## Table of Contents
+
+- [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)
+- [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)
+- [craftdesk.lock](#craftdesklock)
+- [CI/CD Integration](#cicd-integration)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+- [Documentation](#documentation)
+
+---
+
 ## Core Concepts
 
 ### Crafts
@@ -153,6 +154,221 @@ 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** - 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
+
+### 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
 
@@ -193,11 +409,31 @@ Records exact versions installed (like package-lock.json or Gemfile.lock):
 
 **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/
@@ -205,10 +441,195 @@ By default, crafts install to `.claude/` in your project:
 │   └── code-reviewer/
 ├── commands/
 │   └── deploy/
-└── hooks/
-    └── pre-commit/
+├── 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
@@ -221,7 +642,7 @@ Initialize a new craftdesk.json file.
 - `-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, or hook (default: "skill")
+- `-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")
@@ -280,7 +701,7 @@ Add a new dependency and install it immediately.
 - `-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)
+- `-t, --type <type>` - Specify craft type (skill, agent, command, hook, plugin, collection)
 
 **Examples:**
 
@@ -356,6 +777,253 @@ 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
+
+# Publish as private
+craftdesk publish --visibility private
+
+# 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
+
+---
+
+## Authentication
+
+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
+# 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 logout [options]`
+
+Remove stored authentication credentials.
+
+**Options:**
+- `-r, --registry <url>` - Registry URL (uses default from craftdesk.json if not specified)
+
+**Examples:**
+```bash
+# Logout from default registry
+craftdesk logout
+
+# Logout from specific registry
+craftdesk logout --registry https://private.company.com
+```
+
+---
+
+### `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:**
+```
+Logged in to https://craftdesk.ai as john (john@example.com)
+Organization: acme-corp
+```
+
+---
+
+### 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
 
 Available for all commands:
@@ -375,9 +1043,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
+
+# 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.
 
-### 1. GitHub URLs (Easiest)
+**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:
 
@@ -392,7 +1126,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:
 
@@ -423,26 +1157,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
+
+# 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
 
-Install multiple crafts from the same git repository using subdirectory paths:
+Multiple crafts from the same monorepo:
 
 ```json
 {
@@ -457,41 +1225,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
@@ -549,7 +1366,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 |
+| `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") |
@@ -761,11 +1578,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
@@ -778,22 +1630,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