claudekit-cli 3.0.1 → 3.1.0

package/README.md

@@ -182,27 +182,46 @@ ck versions --all
 ### Diagnostics & Doctor
 
 ```bash
-# Check system dependencies, offer auto-installation
+# Full health check (default)
 ck doctor
 
-# Global installation check only
-ck doctor --global
+# Generate shareable diagnostic report (prompts for gist upload)
+ck doctor --report
 
-# Non-interactive mode (CI/CD)
-CI=true ck doctor
+# Auto-fix all fixable issues
+ck doctor --fix
 
-# Auth and access diagnostics
-ck diagnose
-ck diagnose --verbose
+# CI mode: no prompts, exit 1 on failures
+ck doctor --check-only
+
+# Machine-readable JSON output
+ck doctor --json
+
+# Combine flags
+ck doctor --check-only --json
 ```
 
-**Checks:**
-- Claude CLI (optional, v1.0.0+), Python (3.8.0+), pip, Node.js (16.0.0+), npm
-- Skills dependencies status
-- ClaudeKit setup (global and project)
-- Component counts
+**Health Checks:**
+- **System**: Node.js, npm, Python, pip, Claude CLI, git, gh CLI
+- **ClaudeKit**: Global/project installation, versions, skills
+- **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 `ck init --global` |
+| Missing skill deps | Install in skill directory |
+
+**Exit Codes:**
+- `0`: All checks pass or issues fixed
+- `1`: Failures detected (only with `--check-only`)
 
-**Auto-installation:** macOS (Homebrew), Linux (apt/dnf/pacman), Windows (PowerShell). Requires user confirmation in interactive mode.
+> **Note:** `ck diagnose` is deprecated. Use `ck doctor` instead.
 
 ### Uninstall
 
@@ -315,11 +334,8 @@ The CLI requires GitHub authentication to download releases from private reposit
 
 ### Quick Setup
 
-**Recommended: GitHub CLI**
+**Step 1: Install GitHub CLI**
 ```bash
-# Install & authenticate
-gh auth login
-
 # Windows
 winget install GitHub.cli
 
@@ -330,33 +346,47 @@ brew install gh
 sudo apt install gh
 ```
 
-**Alternative: Personal Access Token**
-1. Create token at [github.com/settings/tokens/new](https://github.com/settings/tokens/new?scopes=repo)
-2. Set environment variable:
-   ```bash
-   # Windows (permanent)
-   [System.Environment]::SetEnvironmentVariable("GITHUB_TOKEN", "ghp_TOKEN", [System.EnvironmentVariableTarget]::User)
+**Step 2: Authenticate with GitHub CLI**
+```bash
+gh auth login
+```
+
+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
 
-   # macOS/Linux (add to ~/.bashrc or ~/.zshrc)
-   export GITHUB_TOKEN=ghp_your_token_here
-   ```
+> **⚠️ 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 diagnostics to check for common issues:
+Run the doctor command to diagnose issues:
 
 ```bash
-ck doctor                # Check dependencies and offer installation
-ck diagnose              # Check authentication, access, releases
-ck new --verbose         # Enable detailed logging for ck new
-ck init --verbose        # Enable detailed logging for ck init
+# Interactive diagnostics
+ck doctor
+
+# Generate report for support
+ck doctor --report
+
+# CI/automation
+ck doctor --check-only --json
+
+# Verbose logging
+ck new --verbose
+ck init --verbose
 ```
 
 **Common Issues:**
-- **"Access denied"**: Accept GitHub repo invitation, verify `repo` scope
-- **"Authentication failed"**: Check token format (ghp_*), verify env var
-- **Token not persisting (Windows)**: Use `SetEnvironmentVariable` or `gh auth login`
-- **Need help**: Run `ck diagnose`, check logs, report at GitHub issues
+- **"Access denied"**: Run `ck doctor` to check auth, use `--fix` to auto-repair
+- **"Authentication failed"**: Run `ck 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 `ck doctor --fix` to reinstall skill dependencies
+- **Need help**: Run `ck doctor --report` and share the gist URL
 
 ## Available Kits
 
@@ -462,19 +492,19 @@ bun test
 ## FAQ
 
 **Q: Do I need GitHub CLI?**
-A: No, but recommended. Provides auto token management, OAuth security, one-time setup.
+A: Yes, GitHub CLI is required. ClaudeKit uses it exclusively for authentication with private repositories.
 
-**Q: What token scope needed?**
-A: `repo` scope for private repositories. Create at [github.com/settings/tokens/new](https://github.com/settings/tokens/new?scopes=repo).
+**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'.
 
 **Q: "Access denied" error?**
-A: Accept GitHub repo invitation, verify `repo` scope, wait 2-5min for permissions.
+A: Accept GitHub repo invitation, re-run `gh auth login` with web browser login, wait 2-5min for permissions.
 
-**Q: Token not persisting (Windows)?**
-A: Use `SetEnvironmentVariable` with `User` target, or `gh auth login`.
+**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.
 
 **Q: Is my token secure?**
-A: Yes. Tokens sanitized in logs, stored encrypted in OS keychain, never in plaintext.
+A: Yes. GitHub CLI manages tokens securely via OAuth, stored encrypted in OS keychain.
 
 ## License