@chiendt/ack-cli 1.0.0-dev.1 → 1.0.1

package/README.md

@@ -1,566 +1,143 @@
-# AckKit Config UI
+# ACK CLI
 
-Command-line tool and web dashboard for managing AckKit projects.
+`ack` is the command-line tool for bootstrapping, updating, and managing **AckKit** projects — curated kits of Claude Code skills, agents, commands, and hooks.
 
-**Version**: 1.17.0
+[![npm](https://img.shields.io/npm/v/@chiendt/ack-cli.svg)](https://www.npmjs.com/package/@chiendt/ack-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
 
-## Overview
+---
 
-AckKit Config UI (`ack`) provides both CLI and web dashboard for managing AckKit projects. It is built with Bun, TypeScript, and React for development, while the published CLI runs on plain Node.js so end users do not need Bun installed.
+## What you get
 
-**Key Features:**
-- **CLI Commands (16)**: new, init, config, projects, setup, skills, agents, commands, migrate, doctor, versions, update, uninstall, watch, content, easter-egg
-- **Web Dashboard**: Interactive React UI via `ack config ui` for configuration and project management
-- **Hook Diagnostics Dashboard**: Inspect recent Claude hook activity and failures from `ack config` across global and project scopes
-- **Projects Registry**: Centralized registry at `~/.ack/projects.json` with file locking
-- **Skill Installation**: Install AckKit skills to other coding agents (Cursor, Codex, etc.)
-- **Multi-tier Authentication**: gh CLI → env vars → keychain → prompt fallback
-- **Smart Merging**: Conflict detection with user customization preservation
-- **Skills Migration**: Auto-detects and migrates skills structure changes
-- **Offline Installation**: From local archives or directories
-- **Security**: Path traversal protection, symlink validation, UNC path protection
-- **Cross-Platform**: macOS, Linux, Windows with platform-specific optimizations
-- **Update Notifications**: Intelligent 7-day cache for version checks
-
-## Documentation
-
-Comprehensive documentation in `/docs`:
-
-- **[Codebase Summary](./docs/codebase-summary.md)** - Overview, structure, key components
-- **[Project Overview & PDR](./docs/project-overview-pdr.md)** - Requirements, features, roadmap
-- **[System Architecture](./docs/system-architecture.md)** - Architecture diagrams, data flow
-- **[Reconciliation Architecture](./docs/reconciliation-architecture.md)** - `ack migrate` RECONCILE → EXECUTE → REPORT design
-- **[Code Standards](./docs/code-standards.md)** - Coding conventions, best practices
-- **[Project Roadmap](./docs/project-roadmap.md)** - Release timeline, feature status
-- **[Deployment Guide](./docs/deployment-guide.md)** - Release procedures
-- **[ck watch](./docs/ck-watch.md)** - GitHub issue monitoring daemon
-- **[ck content](./docs/ck-content.md)** - Automated content generation from git activity
-
-## Prerequisites
-
-Before using ACK CLI, you need to:
-
-1. **Purchase a AckKit Starter Kit** from [AckKit.cc](https://AckKit.cc)
-2. **Get Repository Access**: After purchase, you'll receive access to the private GitHub repository containing your kit
-3. **Create a GitHub Personal Access Token** (PAT) with `repo` scope to download releases
-
-Without a purchased kit and repository access, the CLI will not be able to download any project templates.
+- **One command to bootstrap** a Claude-ready project from a kit (engineer, QA, marketing).
+- **Idempotent installs and updates** — your customizations are preserved across upgrades.
+- **Web dashboard** for managing skills, agents, commands, and hooks (`ack config ui`).
+- **Multi-provider migration** — move config between Claude Code, Cursor, Codex, Gemini CLI, and more.
+- **Built-in doctor** with auto-fix for the most common setup problems.
 
 ## Installation
 
-The ACK CLI is published on npm at [npmjs.com/package/@chiendt/ack-cli](https://www.npmjs.com/package/@chiendt/ack-cli).
-
-End-user runtime note: global installs from `npm`, `pnpm`, `yarn`, or `bun` all execute the packaged Node.js CLI. Bun is optional for users and only needed for local ACK CLI development workflows.
-
-### Using npm (Recommended)
+The CLI is published on npm at [`@chiendt/ack-cli`](https://www.npmjs.com/package/@chiendt/ack-cli). Pick one:
 
 ```bash
 npm install -g @chiendt/ack-cli
-```
-
-### Using Bun
-
-```bash
-bun add -g @chiendt/ack-cli
-```
-
-### Using Yarn
-
-```bash
-yarn global add @chiendt/ack-cli
-```
-
-### Using pnpm
-
-```bash
 pnpm add -g @chiendt/ack-cli
+yarn global add @chiendt/ack-cli
+bun  add -g @chiendt/ack-cli
 ```
 
-After installation, verify it's working:
+Verify:
 
 ```bash
 ack --version
 ```
 
-## Usage
-
-### Discoverability Quick Start
-
-```bash
-# Top-level command discovery
-ack --help
-
-# Open config dashboard immediately
-ack config
+> **Requirements:** Node.js ≥ 18, [GitHub CLI](https://cli.github.com/) (`gh`) for kit downloads.
 
-# Expose the dashboard intentionally to your LAN/Tailscale
-ack config --host 0.0.0.0 --no-open
-
-# Command-level help (recommended)
-ack config --help
-ack skills --help
-ack agents --help
-ack commands --help
-ack migrate --help
-```
-
-### Config Dashboard Access
-
-By default, `ack config` binds the dashboard to `127.0.0.1` for local-only access.
+## Authentication
 
-Use `--host` when you intentionally want remote access from another device on the same trusted network:
+AckKit kits live in private GitHub repos. Authenticate once with the GitHub CLI:
 
 ```bash
-# Bind to all interfaces
-ack config --host 0.0.0.0 --no-open
-
-# Bind to a specific interface or hostname
-ack config --host 100.88.12.4 --no-open
-ack config --host dashboard.local --no-open
+gh auth login
+# choose: GitHub.com → HTTPS → Login with a web browser
 ```
 
-The dashboard still enforces same-origin browser access. Remote access works when you open the UI from the same host/origin that reaches the server, instead of relying on a hardcoded IP allowlist.
+> Don't use *"Paste an authentication token"* — OAuth via web browser is the supported path. The CLI reads `gh`'s token automatically; tokens are stored in your OS keychain.
 
-### Create New Project
+## Quick start
 
 ```bash
-# Interactive mode
-ack new
-
-# With options
-ack new --dir my-project --kit engineer
-
-# Show beta versions
-ack new --beta
-
-# With exclude patterns
-ack new --exclude "*.log" --exclude "temp/**"
-
-# Optional packages (OpenCode, Gemini)
-ack new --opencode --gemini
-
-# Install skills dependencies (Python, Node packages, system tools)
-ack new --install-skills
-
-# Command prefix (/ck: namespace to avoid conflicts)
-ack new --prefix
-
-# Offline installation (from local archive or directory)
-ack new --archive ~/downloads/engineer-v1.16.0.zip
-ack new --kit-path ~/extracted-kit/
-
-# Direct repo downloads are also supported
-ack new --archive ~/downloads/AckKit-engineer-main.zip
-ack new --kit-path ~/downloads/AckKit-engineer-main/
-```
+# Bootstrap a new project from a kit
+ack new --kit engineer
 
-**Flags:**
-- `--install-skills`: Auto-install Python packages, system tools (FFmpeg, ImageMagick), Node.js packages
-- `--prefix`: Move commands to /ck: namespace (/plan → /ck:plan)
-- `--beta`: Show pre-release versions in selection
-- `--opencode/--gemini`: Install optional packages
-- `--archive <path>`: Use local archive (zip/tar.gz) instead of downloading
-- `--kit-path <path>`: Use local kit directory instead of downloading
-
-`--archive` and `--kit-path` both accept direct repo downloads with a single wrapper directory, including GitHub "Download ZIP" archives and extracted repo folders that still contain `AckKit-engineer-main/` or similar at the top level.
-
-### Initialize or Update Project
-
-**Note:** Run from project root.
-
-```bash
-# Interactive mode
+# Initialize / update an existing project
 ack init
 
-# Non-interactive mode with sensible defaults
-ack init --yes
-ack init -y
-
-# Combine with other flags
-ack init -g --kit engineer -y
-
-# With options
-ack init --kit engineer --beta
-
-# Global mode (platform-specific paths)
-ack init --global
-
-# Fresh installation (⚠️ DESTRUCTIVE - removes ALL customizations)
-ack init --fresh
-
-# With exclude patterns and prefix
-ack init --exclude "*.local" --prefix
-
-# Offline installation (from local archive or directory)
-ack init --archive ~/downloads/engineer-v1.16.0.zip
-ack init --kit-path ~/extracted-kit/
-
-# Direct repo downloads are also supported
-ack init --archive ~/downloads/AckKit-engineer-main.zip
-ack init --kit-path ~/downloads/AckKit-engineer-main/
-```
-
-**Flags:**
-- `--yes/-y`: Non-interactive mode with sensible defaults (skip all prompts)
-- `--global/-g`: Use platform-specific config (macOS/Linux: ~/.claude, Windows: %USERPROFILE%\.claude)
-- `--fresh`: Clean reinstall, removes .claude directory (requires "yes" confirmation)
-- `--beta`: Show pre-release versions
-- `--prefix`: Apply /ck: namespace to commands
-- `--archive <path>`: Use local archive (zip/tar.gz) instead of downloading
-- `--kit-path <path>`: Use local kit directory instead of downloading
-
-`--archive` and `--kit-path` both accept direct repo downloads with a single wrapper directory, including GitHub "Download ZIP" archives and extracted repo folders that still contain `AckKit-engineer-main/` or similar at the top level.
-
-**Default Behavior with `-y` Flag:**
-
-| Prompt | Default |
-|--------|---------|
-| Select AckKit | engineer (first option) |
-| Target directory | Current directory (`.`) |
-| Version selection | Latest stable release |
-| Google Gemini setup | Skip |
-| Other optional features | Skip |
-
-### Update CLI
-
-Keep the ACK CLI up to date:
-
-```bash
-# Check for CLI updates
-ack update --check
-
-# Update to latest version
-ack update
-
-# Update to specific version
-ack update --version 1.17.0
-
-# Update to beta / skip confirmation
-ack update --beta
-ack update --yes
-```
-
-The CLI notifies you when updates are available via `ack --version`.
-
-**Skills Migration:**
-- Auto-detects structure changes (flat → categorized)
-- Preserves customizations (SHA-256 hashing)
-- Creates backup before migration
-- Rollback on failure
-
-### List Available Versions
-
-```bash
-# Show all available versions for all kits
-ack versions
-
-# Filter by specific kit
-ack versions --kit engineer
-ack versions --kit marketing
-
-# Show more versions (default: 30)
-ack versions --limit 50
-
-# Include prereleases and drafts
-ack versions --all
-```
-
-### Diagnostics & Doctor
-
-```bash
-# Full health check (default)
-ack doctor
-
-# Verbose mode with execution timing and command details
-ack doctor --verbose
-
-# Generate shareable diagnostic report (prompts for gist upload)
-ack doctor --report
+# Open the web dashboard
+ack config
 
-# Auto-fix all fixable issues
+# Health check + auto-fix
 ack doctor --fix
-
-# CI mode: no prompts, exit 1 on failures
-ack doctor --check-only
-
-# Machine-readable JSON output
-ack doctor --json
-
-# Combine flags
-ack doctor --verbose --check-only --json
-ack doctor --verbose --fix
 ```
 
-**Health Checks:**
-- **System**: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
-- **AckKit**: Global/project installation, versions, skills, skill listing budget, duplicate skill inventory
-- **Auth**: GitHub CLI authentication, repository access
-- **Project**: package.json, node_modules, lock files
-- **Modules**: Dynamic skill dependency resolution
-
-**Auto-Fix Capabilities:**
-| Issue | Fix Action |
-|-------|------------|
-| Missing dependencies | Install via package manager |
-| Missing gh auth | Run `gh auth login` |
-| Corrupted node_modules | Reinstall dependencies |
-| Missing global install | Run `ack init --global` |
-| Missing skill deps | Install in skill directory |
-| Missing/low Engineer skill listing budget | Ensure computed `skillListingBudgetFraction` and a valid AckKit-recommended `skillListingMaxDescChars` ceiling in project settings |
+Run `ack --help` for the full command list, or `ack <command> --help` for any one. The full machine-readable command reference is at [`docs/cli-reference.md`](./docs/cli-reference.md).
 
-`ack doctor` never writes `skillOverrides`, hides skills, or deletes duplicate skills automatically. It reports existing `skillOverrides` and inventory issues so all active project/global skills can stay user-invocable while listing pressure is managed through 200k-context-floor project settings and bounded descriptions.
+## Available kits
 
-**Exit Codes:**
-- `0`: All checks pass or issues fixed
-- `1`: Failures detected (only with `--check-only`)
+| Kit         | Slash prefix | Repo                              | Description                                                |
+|-------------|--------------|-----------------------------------|------------------------------------------------------------|
+| `engineer`  | `/ck:`       | `chiendt1108/ack-engineer`        | Engineering toolkit for building with Claude               |
+| `marketing` | `/mkt:`      | `chiendt1108/claudekit-marketing` | Content automation: campaigns, social, analytics           |
+| `fqc-qa`    | `/fqc:`      | `chiendt1108/ack-fqc-qa`          | QA: test design, debugging, security, scenario coverage    |
 
-> **Note:** `ack diagnose` is deprecated. Use `ack doctor` instead.
+Kits are sold as part of [AckKit](https://AckKit.cc). Use `ack versions --kit <name>` to see released versions.
 
-### Uninstall
+## Common workflows
 
-Remove AckKit installations from your system:
+### Create a project
 
 ```bash
-ack uninstall              # Interactive mode - prompts for scope and confirmation
-ack uninstall --local      # Uninstall only local installation (current project)
-ack uninstall --global     # Uninstall only global installation (~/.claude/)
-ack uninstall -g --kit marketing  # Remove only global Marketing kit
-ack uninstall -l -y        # Local only, skip confirmation
-ack uninstall -g -y        # Global only, skip confirmation
-ack uninstall --yes        # Non-interactive - skip confirmation (for scripts)
+ack new                           # interactive
+ack new --kit engineer --yes      # non-interactive
+ack new --kit fqc-qa --prefix qa  # custom slash prefix → /qa:
 ```
 
-**Scope Selection:**
-- When both local and global installations exist, you'll be prompted to choose:
-  - **Local only**: Remove from current project (`.claude/`)
-  - **Global only**: Remove from user directory (`~/.claude/`)
-  - **Both**: Remove all AckKit installations
-- When multiple kits are installed in the selected scope, interactive uninstall prompts for:
-  - **Marketing kit only** or **Engineer kit only**: Remove one kit and preserve the other
-  - **All AckKit kits**: Remove the full selected installation scope
-- Use `--local` or `--global` flags to skip the prompt
-- Use `--kit engineer` or `--kit marketing` to skip the kit prompt
-
-**What it does:**
-- Detects local `.claude` directory in current project
-- Detects global `~/.claude` AckKit installation
-- Shows paths before deletion
-- Requires confirmation (unless `--yes` flag)
-- Removes AckKit subdirectories (`commands/`, `agents/`, `skills/`, `workflows/`, `hooks/`, `metadata.json`)
-- **Preserves user configs** like `settings.json`, `settings.local.json`, and `CLAUDE.md`
-
-**Note:** Only removes valid AckKit installations (with metadata.json). Regular `.claude` directories from Claude Desktop are not affected.
-
-### Watch GitHub Issues (`ack watch`)
-
-Autonomous daemon that monitors GitHub issues, analyzes them with Claude, generates plans, and creates PRs.
+### Update an existing project
 
 ```bash
-# Start watching (single repo)
-ack watch
-
-# Dry-run mode (no posts/PRs)
-ack watch --dry-run
-
-# Custom poll interval (ms)
-ack watch --interval 60000
-
-# Force restart (clear state)
-ack watch --force
-
-# Verbose logging
-ack watch --verbose
+ack init               # update to latest, preserve your customizations
+ack init --fresh       # ⚠️ destructive: wipe and reinstall
 ```
 
-**Features:** issue lifecycle management (10 statuses), Claude-powered brainstorming/planning, automatic PR creation, rate limiting (persisted across restarts), maintainer reply filtering, processedIssues TTL, optional git worktree isolation per issue, multi-repo support, graceful shutdown.
+`--fresh` is destructive. `--force` is **not** a fresh install — it only skips prompts.
 
-**Config:** `.ck.json` under `watch` key. See [docs/ck-watch.md](./docs/ck-watch.md) for full configuration reference.
-
-### Content Generation (`ack content`)
-
-Daemon that scans git activity (commits, PRs, tags), generates social media content with Claude, and publishes to X/Twitter and Facebook.
+### Update the CLI itself
 
 ```bash
-# Interactive setup wizard
-ack content setup
-
-# Start daemon
-ack content start
-
-# Check status
-ack content status
-
-# View logs
-ack content logs
-
-# Queue manual content
-ack content queue
-
-# Review workflow
-ack content approve <id>
-ack content reject <id>
-
-# Dry-run / verbose
-ack content start --dry-run
-ack content start --verbose
+ack update --check          # check for newer CLI
+ack update                  # install latest stable
+ack update --dev            # install latest @dev prerelease
 ```
 
-**Features:** 11-phase pipeline (scan → filter → classify → context → create → validate → review → photo → publish → engage → analyze), noise filtering, context caching (24h TTL), content validation, photo generation, 3 review modes (auto/manual/hybrid), quiet hours scheduling, engagement tracking, SQLite database, platform-specific adapters.
-
-**Config:** `.ck.json` under `content` key. See [docs/ck-content.md](./docs/ck-content.md) for full configuration reference.
-
-### Other Commands
+### Health check
 
 ```bash
-# Show CLI version (shows local + global kit versions)
-ack --version
-
-# Show help
-ack --help
-ack -h
-
-# Command-specific help
-ack new --help
-ack init --help
-ack config --help
-ack skills --help
-ack versions --help
+ack doctor              # full health check
+ack doctor --fix        # auto-repair fixable issues
+ack doctor --report     # generate a shareable gist
+ack doctor --json       # machine-readable output
 ```
 
-### Debugging
+### Migrate config to another agent
 
 ```bash
-ack new --verbose              # Enable verbose logging
-ack new --verbose --log-file debug.log  # Save to file
-ACK_VERBOSE=1 ack new   # Via environment variable
+ack migrate --dry-run   # preview the migration plan
+ack migrate             # apply it (interactive conflict resolution)
 ```
 
-### Cache Configuration
-
-Release data is cached locally to improve performance. You can configure the cache TTL:
+Supported providers: Claude Code, Cursor, Codex, Gemini CLI, Windsurf, Amp, Antigravity, OpenCode, OpenHands, Droid, Roo, Kilo. See [`docs/reconciliation-architecture.md`](./docs/reconciliation-architecture.md) for the RECONCILE → EXECUTE → REPORT design.
 
-```bash
-# Set custom cache TTL (in seconds, default: 3600 = 1 hour)
-CK_CACHE_TTL=7200 ack versions    # Cache for 2 hours
-CK_CACHE_TTL=0 ack versions       # Disable caching (always fetch fresh)
-
-# Permanent configuration (add to ~/.bashrc or ~/.zshrc)
-export CK_CACHE_TTL=1800         # 30 minutes
-```
-
-**Cache Location:** `~/.ack/cache/releases/`
-
-### Update Notifications
-
-The `ack --version` command checks for newer versions of your installed AckKit and displays a notification if an update is available. The check is cached for 7 days to minimize API calls.
-
-**Disable Update Notifications:**
-```bash
-# Set environment variable to disable
-NO_UPDATE_NOTIFIER=1 ack --version
-
-# Windows (permanent)
-[System.Environment]::SetEnvironmentVariable("NO_UPDATE_NOTIFIER", "1", [System.EnvironmentVariableTarget]::User)
-
-# macOS/Linux (add to ~/.bashrc or ~/.zshrc)
-export NO_UPDATE_NOTIFIER=1
-```
-
-**Cache Location:** `~/.ack/cache/version-check.json` (Windows: `%USERPROFILE%\.AckKit\cache\`)
-
-## Authentication
-
-The CLI requires GitHub authentication to download releases from private repositories.
-
-### Authentication Flow
-
-```
-┌─────────────────────────────────────────────────┐
-│          Multi-Tier Authentication               │
-│                                                  │
-│  1. GitHub CLI (gh auth token)                  │
-│       ↓ (if not available)                       │
-│  2. Environment Variables (GITHUB_TOKEN)        │
-│       ↓ (if not set)                             │
-│  3. Config File (~/.ack/config.json)      │
-│       ↓ (if not found)                           │
-│  4. OS Keychain (secure storage)                │
-│       ↓ (if not stored)                          │
-│  5. User Prompt (with save option)              │
-└─────────────────────────────────────────────────┘
-```
-
-### Quick Setup
-
-**Step 1: Install GitHub CLI**
-```bash
-# Windows
-winget install GitHub.cli
-
-# macOS
-brew install gh
-
-# Linux
-sudo apt install gh
-```
+### Uninstall
 
-**Step 2: Authenticate with GitHub CLI**
 ```bash
-gh auth login
+ack uninstall            # interactive — pick scope and kits
+ack uninstall --local    # remove project install only
+ack uninstall --global   # remove ~/.claude install only
 ```
 
-When prompted, follow these steps:
-1. Select **GitHub.com**
-2. Select **HTTPS** (or SSH if preferred)
-3. Authenticate Git? → **Yes**
-4. Select **Login with a web browser** (⚠️ recommended)
-5. Copy the one-time code shown
-6. Press Enter to open browser and paste the code
-7. Authorize GitHub CLI
-
-> **⚠️ Important**: Select "Login with a web browser" - do NOT use "Paste an authentication token" as PAT authentication is no longer supported for accessing private repositories.
-
-## Troubleshooting
-
-Run the doctor command to diagnose issues:
+## Web dashboard
 
 ```bash
-# Interactive diagnostics
-ack doctor
-
-# Generate report for support
-ack doctor --report
-
-# CI/automation
-ack doctor --check-only --json
-
-# Verbose logging
-ack new --verbose
-ack init --verbose
+ack config              # http://localhost:3456
+ack config --host 0.0.0.0   # expose on LAN
 ```
 
-**Common Issues:**
-- **"Access denied"**: Run `ack doctor` to check auth, use `--fix` to auto-repair
-- **"Authentication failed"**: Run `ack doctor --fix` to re-authenticate, or manually run `gh auth login` (select 'Login with a web browser')
-- **"GitHub CLI not authenticated"**: Run `gh auth login` and select 'Login with a web browser' (NOT 'Paste token')
-- **Module errors**: Run `ack doctor --fix` to reinstall skill dependencies
-- **Need help**: Run `ack doctor --report` and share the gist URL
-
-## Available Kits
-
-AckKit offers premium starter kits available for purchase at [AckKit.cc](https://AckKit.cc):
+The dashboard lets you browse and toggle skills, agents, commands, and hooks; inspect recent Claude hook activity; and run migrations interactively.
 
-| Kit | Slash prefix | Repo | Description |
-|------|--------------|------|-------------|
-| `engineer` | `/ck:` | `chiendt1108/ack-engineer` | Engineering toolkit for building with Claude |
-| `marketing` | `/mkt:` | `claudekit/claudekit-marketing` | Content automation: campaigns, social media, analytics |
-| `fqc-qa` | `/fqc:` | `chiendt1108/ack-fqc-qa` | QA kit: test design, debugging, security, scenario coverage |
+## Per-project layout
 
-Each kit ships with its own slash-command namespace. When `--prefix` is applied, the kit's commands are reorganized under `.claude/commands/{prefix}/` and slash references inside files are rewritten to `/{prefix}:...`.
-
-### Per-project layout override
-
-A user project can pin where the kit installs files via its `package.json`:
+Override where a kit installs files via `package.json`:
 
 ```json
 {
@@ -571,144 +148,66 @@ A user project can pin where the kit installs files via its `package.json`:
 }
 ```
 
-(The legacy `claudekit` field is no longer recognized.)
-
-## Configuration
-
-Configuration is stored in `~/.ack/config.json`:
-
-```json
-{
-  "github": {
-    "token": "stored_in_keychain"
-  },
-  "defaults": {
-    "kit": "engineer",
-    "dir": "."
-  }
-}
-```
-
-## Protected Files
+## Protected files
 
-The following file patterns are protected and will not be overwritten during updates:
+The following are never overwritten by `ack init` or updates:
 
 - `.env`, `.env.local`, `.env.*.local`
 - `*.key`, `*.pem`, `*.p12`
-- `node_modules/**`, `.git/**`
-- `dist/**`, `build/**`
+- `node_modules/**`, `.git/**`, `dist/**`, `build/**`
 
-## Excluding Files
-
-Use `--exclude` flag with glob patterns to skip files:
+Add your own patterns with `--exclude`:
 
 ```bash
-ack new --exclude "*.log" --exclude "temp/**"
-ack update --exclude "node_modules/**" --exclude "dist/**"
-```
-
-**Patterns:** `*` (any chars), `**` (recursive), `?` (single char), `[abc]`, `{a,b}`
-**Restrictions:** No absolute paths, no path traversal (..), 1-500 chars
-**Note:** User patterns are ADDED to default protected patterns
-
-### Custom .claude Files & Skills Migration
-
-**Custom File Preservation:**
-The CLI automatically preserves your custom `.claude/` files during updates:
-
-- Custom slash commands
-- Personal workflows
-- Project-specific configurations
-- Any other custom files in `.claude/` directory
-
-**Skills Directory Migration:**
-Automatic migration when structure changes (flat → categorized):
-
-- **Detection**: Manifest-based + heuristic fallback
-- **Customizations**: SHA-256 hash comparison detects modifications
-- **Safety**: Backup before migration, rollback on failure
-- **Preservation**: All customizations preserved during migration
-- **Interactive**: Prompts for confirmation (can skip in CI/CD)
-
-**Example Migration:**
-```
-Before (flat):
-  .claude/skills/
-    ├── gemini-vision/
-    ├── postgresql-psql/
-    └── cloudflare-dns/
-
-After (categorized):
-  .claude/skills/
-    ├── ai-multimodal/
-    │   └── gemini-vision/
-    ├── databases/
-    │   └── postgresql-psql/
-    └── devops/
-        └── cloudflare-dns/
+ack init --exclude "*.log" --exclude "vendor/**"
 ```
 
-Customizations in any skill are detected and preserved automatically.
-
 ## Development
 
-See [Development Guide](./docs/codebase-summary.md) for:
-- Project structure (modular domain-driven architecture)
-- Build & compilation (`bun run build`, `bun run compile`)
-- Testing & type checking
-- Code standards & linting
-
-**Architecture Highlights:**
-- **Modular design**: 122 focused modules (target: <100 lines each)
-- **Facade pattern**: Each domain exposes public API via facade
-- **Phase handlers**: Complex commands use orchestrator + phase handlers
-- **Self-documenting names**: kebab-case file names describe purpose
-
-**Quick Start:**
 ```bash
+git clone https://github.com/chiendt1108/ack-cli.git
+cd ack-cli
 bun install
-bun run dev new --kit engineer
+bun run dev new --kit engineer    # run locally without installing globally
 bun test
-# Optional: run expensive CLI integration tests explicitly
-bun run test:integration
+bun run ci:local                  # full quality gate (matches GitHub Actions)
 ```
 
-## E2E Tests
-
-Playwright E2E tests cover the `ack migrate` dashboard (3 scenarios). Tests run against the local dev server and use API mocking — no real filesystem state is modified.
+See [`CLAUDE.md`](./CLAUDE.md) for the contributor guide, [`docs/codebase-summary.md`](./docs/codebase-summary.md) for architecture, and [`docs/code-standards.md`](./docs/code-standards.md) for conventions.
 
-**Prerequisites:** Node 18+ or Bun 1.0+, Chromium (installed automatically).
-
-```bash
-# One-time browser setup (if not already installed)
-./node_modules/.bin/playwright install chromium
+## Documentation
 
-# Run all E2E specs
-bun run test:e2e
+| Doc | Topic |
+|-----|-------|
+| [`docs/cli-reference.md`](./docs/cli-reference.md)                       | Full command + flag reference |
+| [`docs/codebase-summary.md`](./docs/codebase-summary.md)                 | Architecture & module map |
+| [`docs/system-architecture.md`](./docs/system-architecture.md)           | Design diagrams, data flow |
+| [`docs/reconciliation-architecture.md`](./docs/reconciliation-architecture.md) | `ack migrate` internals |
+| [`docs/deployment-guide.md`](./docs/deployment-guide.md)                 | Release & publishing |
+| [`docs/project-roadmap.md`](./docs/project-roadmap.md)                   | Roadmap & release timeline |
 
-# Interactive UI mode (watch + trace viewer)
-bun run test:e2e:ui
-```
+## Troubleshooting
 
-Note: The dev server starts automatically via `bun run dashboard:dev`. CI wiring is a separate follow-up (local-only for now).
+| Symptom | First step |
+|---------|------------|
+| `Access denied` / kit download fails              | `ack doctor --fix` |
+| `GitHub CLI not authenticated`                    | `gh auth login` (web browser flow) |
+| Module / dependency errors                        | `ack doctor --fix` |
+| Want a sharable diagnostic                        | `ack doctor --report` |
+| Skill not appearing after install                 | Check `~/.ack/projects.json`, then `ack config` |
 
 ## FAQ
 
-**Q: Do I need GitHub CLI?**
-A: Yes, GitHub CLI is required. AckKit uses it exclusively for authentication with private repositories.
+**Do I need GitHub CLI?** Yes — `gh` is the only supported auth path; tokens are stored in your OS keychain.
 
-**Q: How do I authenticate?**
-A: Run `gh auth login`, select 'Login with a web browser', complete OAuth in browser. Do NOT use 'Paste an authentication token'.
+**Can I use a Personal Access Token?** No. PAT-paste auth was removed. Use `gh auth login` with the web browser flow.
 
-**Q: "Access denied" error?**
-A: Accept GitHub repo invitation, re-run `gh auth login` with web browser login, wait 2-5min for permissions.
+**Will updating overwrite my custom skills/commands?** No. Custom files in `.claude/` are detected (SHA-256 hash comparison) and preserved. Use `--fresh` if you want a clean reinstall.
 
-**Q: "GitHub CLI not authenticated" error?**
-A: Run `gh auth login` and select 'Login with a web browser' (NOT 'Paste token'). PAT authentication is no longer supported.
+**Where is my config stored?** `~/.ack/config.json`, with the GitHub token in the OS keychain. The projects registry is at `~/.ack/projects.json`.
 
-**Q: Is my token secure?**
-A: Yes. GitHub CLI manages tokens securely via OAuth, stored encrypted in OS keychain.
+**How do I get help?** `ack doctor --report` produces a shareable gist URL. Or open an issue at [github.com/chiendt1108/ack-cli/issues](https://github.com/chiendt1108/ack-cli/issues).
 
 ## License
 
-MIT
+[MIT](./LICENSE)

package/cli-manifest.json

@@ -1,6 +1,6 @@
 {
-	"version": "1.0.0-dev.1",
-	"generatedAt": "2026-05-17T08:49:49.583Z",
+	"version": "1.0.1",
+	"generatedAt": "2026-05-17T09:48:49.771Z",
 	"commands": {
 		"agents": {
 			"name": "agents",

package/dist/index.js

@@ -63692,7 +63692,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@chiendt/ack-cli",
-    version: "1.0.0-dev.1",
+    version: "1.0.1",
     description: "ACK CLI - tool for bootstrapping and updating ACK kits (Claude Code agent kits)",
     type: "module",
     repository: {
@@ -76375,6 +76375,76 @@ var init_ownership_display = __esm(() => {
   import_picocolors25 = __toESM(require_picocolors(), 1);
 });
 
+// src/ui/node_modules/picocolors/picocolors.js
+var require_picocolors2 = __commonJS((exports, module) => {
+  var p2 = process || {};
+  var argv = p2.argv || [];
+  var env3 = p2.env || {};
+  var isColorSupported = !(!!env3.NO_COLOR || argv.includes("--no-color")) && (!!env3.FORCE_COLOR || argv.includes("--color") || p2.platform === "win32" || (p2.stdout || {}).isTTY && env3.TERM !== "dumb" || !!env3.CI);
+  var formatter = (open6, close, replace = open6) => (input) => {
+    let string = "" + input, index = string.indexOf(close, open6.length);
+    return ~index ? open6 + replaceClose(string, close, replace, index) + close : open6 + string + close;
+  };
+  var replaceClose = (string, close, replace, index) => {
+    let result = "", cursor = 0;
+    do {
+      result += string.substring(cursor, index) + replace;
+      cursor = index + close.length;
+      index = string.indexOf(close, cursor);
+    } while (~index);
+    return result + string.substring(cursor);
+  };
+  var createColors = (enabled = isColorSupported) => {
+    let f4 = enabled ? formatter : () => String;
+    return {
+      isColorSupported: enabled,
+      reset: f4("\x1B[0m", "\x1B[0m"),
+      bold: f4("\x1B[1m", "\x1B[22m", "\x1B[22m\x1B[1m"),
+      dim: f4("\x1B[2m", "\x1B[22m", "\x1B[22m\x1B[2m"),
+      italic: f4("\x1B[3m", "\x1B[23m"),
+      underline: f4("\x1B[4m", "\x1B[24m"),
+      inverse: f4("\x1B[7m", "\x1B[27m"),
+      hidden: f4("\x1B[8m", "\x1B[28m"),
+      strikethrough: f4("\x1B[9m", "\x1B[29m"),
+      black: f4("\x1B[30m", "\x1B[39m"),
+      red: f4("\x1B[31m", "\x1B[39m"),
+      green: f4("\x1B[32m", "\x1B[39m"),
+      yellow: f4("\x1B[33m", "\x1B[39m"),
+      blue: f4("\x1B[34m", "\x1B[39m"),
+      magenta: f4("\x1B[35m", "\x1B[39m"),
+      cyan: f4("\x1B[36m", "\x1B[39m"),
+      white: f4("\x1B[37m", "\x1B[39m"),
+      gray: f4("\x1B[90m", "\x1B[39m"),
+      bgBlack: f4("\x1B[40m", "\x1B[49m"),
+      bgRed: f4("\x1B[41m", "\x1B[49m"),
+      bgGreen: f4("\x1B[42m", "\x1B[49m"),
+      bgYellow: f4("\x1B[43m", "\x1B[49m"),
+      bgBlue: f4("\x1B[44m", "\x1B[49m"),
+      bgMagenta: f4("\x1B[45m", "\x1B[49m"),
+      bgCyan: f4("\x1B[46m", "\x1B[49m"),
+      bgWhite: f4("\x1B[47m", "\x1B[49m"),
+      blackBright: f4("\x1B[90m", "\x1B[39m"),
+      redBright: f4("\x1B[91m", "\x1B[39m"),
+      greenBright: f4("\x1B[92m", "\x1B[39m"),
+      yellowBright: f4("\x1B[93m", "\x1B[39m"),
+      blueBright: f4("\x1B[94m", "\x1B[39m"),
+      magentaBright: f4("\x1B[95m", "\x1B[39m"),
+      cyanBright: f4("\x1B[96m", "\x1B[39m"),
+      whiteBright: f4("\x1B[97m", "\x1B[39m"),
+      bgBlackBright: f4("\x1B[100m", "\x1B[49m"),
+      bgRedBright: f4("\x1B[101m", "\x1B[49m"),
+      bgGreenBright: f4("\x1B[102m", "\x1B[49m"),
+      bgYellowBright: f4("\x1B[103m", "\x1B[49m"),
+      bgBlueBright: f4("\x1B[104m", "\x1B[49m"),
+      bgMagentaBright: f4("\x1B[105m", "\x1B[49m"),
+      bgCyanBright: f4("\x1B[106m", "\x1B[49m"),
+      bgWhiteBright: f4("\x1B[107m", "\x1B[49m")
+    };
+  };
+  module.exports = createColors();
+  module.exports.createColors = createColors;
+});
+
 // src/commands/watch/phases/implementation-git-helpers.ts
 import { spawn as spawn5 } from "node:child_process";
 async function getCurrentBranch2(cwd2) {
@@ -104994,7 +105064,7 @@ import { basename as basename28, join as join142, resolve as resolve49 } from "n
 init_logger();
 
 // src/ui/ack-cli-design/tokens.ts
-var import_picocolors27 = __toESM(require_picocolors(), 1);
+var import_picocolors27 = __toESM(require_picocolors2(), 1);
 import { homedir as homedir48, platform as platform12 } from "node:os";
 import { resolve as resolve48, win32 } from "node:path";
 var PANEL_MIN_WIDTH = 60;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chiendt/ack-cli",
-	"version": "1.0.0-dev.1",
+	"version": "1.0.1",
 	"description": "ACK CLI - tool for bootstrapping and updating ACK kits (Claude Code agent kits)",
 	"type": "module",
 	"repository": {