@camaradesuk/git-worktree-tools 1.6.0 → 1.7.0

package/README.md

@@ -8,12 +8,14 @@ Cross-platform CLI tools for git worktree workflow management. Create PRs with d
 
 ## Features
 
-- **Cross-platform**: Works natively on Windows, macOS, and Linux (no bash/WSL required)
-- **Smart State Detection**: Intelligently handles 10+ git scenarios (uncommitted changes, local commits, existing branches, etc.)
-- **PR + Worktree Workflow**: Create PRs and dedicated worktrees in one command
-- **Shared Repos**: Automatically create worktrees in related repositories
-- **Config Syncing**: Share gitignored config files (.env, .vscode, etc.) between worktrees via hard links
-- **Configurable**: Per-repo settings via `.worktreerc`
+- **Unified CLI** — Single `wt` command with interactive menu or subcommands
+- **Cross-platform** — Works natively on Windows, macOS, and Linux (no bash/WSL required)
+- **Smart State Detection** — Intelligently handles 10+ git scenarios (uncommitted changes, local commits, existing branches, etc.)
+- **PR + Worktree Workflow** — Create PRs and dedicated worktrees in one command
+- **Config Syncing** — Share gitignored config files (.env, .vscode, etc.) between worktrees via hard links
+- **Three-Tier Configuration** — Global, repo, and local config with JSON schema validation
+- **Structured Logging** — Configurable log levels with file output support
+- **AI Tool Integration** — JSON output mode and programmatic API for AI agents
 
 ## Installation
 
@@ -30,60 +32,83 @@ npm install -g @camaradesuk/git-worktree-tools
 ## Quick Start
 
 ```bash
-# Using the unified wt command (recommended)
-wt new "Add user authentication feature"  # Create PR with worktree
-wt list                                    # List worktrees
-wt clean                                   # Clean up merged/closed PRs
-wt link                                    # Manage shared config files
-wt state --json                            # Query git state
-wt config init                             # Configure settings
-
-# Or use individual commands directly
-newpr "Add user authentication feature"
-lswt
-cleanpr
-wtlink
-wtstate --json
-wtconfig init
+# Interactive menu (recommended for exploration)
+wt
+
+# Create a new PR with worktree
+wt new "Add user authentication feature"
+
+# List worktrees with interactive selection
+wt list
+
+# Clean up merged/closed PRs
+wt clean
+
+# Initialize configuration
+wt init
 ```
 
-## Commands
+---
 
-### wt (Unified Command)
+## The `wt` Command
 
-The `wt` command provides a single entry point for all git-worktree-tools functionality:
+The unified `wt` command provides access to all git-worktree-tools functionality through an interactive menu or subcommands.
+
+### Interactive Mode
+
+Run `wt` without arguments to launch the interactive menu:
 
 ```bash
-wt <command> [options]
+wt
 ```
 
+The menu provides guided workflows for:
+
+- Creating new PRs (from description, existing PR, or current branch)
+- Listing and navigating worktrees
+- Cleaning up merged/closed PR worktrees
+- Managing config file linking
+- Viewing git state
+- Editing configuration
+
+### Subcommands
+
 | Command              | Alias    | Description                         |
 | -------------------- | -------- | ----------------------------------- |
+| `wt`                 | -        | Interactive main menu               |
 | `wt new <desc>`      | `wt n`   | Create a new PR with worktree       |
 | `wt list`            | `wt ls`  | List worktrees with PR status       |
 | `wt clean [pr]`      | `wt c`   | Clean up merged/closed PR worktrees |
 | `wt link [cmd]`      | `wt l`   | Manage gitignored files via links   |
 | `wt state`           | `wt s`   | Query git worktree state            |
 | `wt config [cmd]`    | `wt cfg` | Configuration management            |
+| `wt init`            | -        | Initialize configuration            |
 | `wt completion <sh>` | -        | Generate shell completion scripts   |
 
-All subcommands accept the same options as their standalone equivalents. For example:
+### Global Options
 
 ```bash
-wt new "Add feature" --draft    # Same as: newpr "Add feature" --draft
-wt list --json                  # Same as: lswt --json
-wt clean --all                  # Same as: cleanpr --all
+wt -v               # Verbose output (debug level)
+wt -vv              # Very verbose (trace level)
+wt --debug          # Debug output
+wt -q, --quiet      # Suppress non-essential output
+wt --log-file FILE  # Write logs to file
 ```
 
-### newpr
+---
+
+## Commands Reference
+
+### wt new / newpr
 
 Create a new PR with an associated worktree.
 
 ```bash
-newpr "Description of the feature"
-newpr --branch my-feature "Feature description"
-newpr --pr 123  # Work on existing PR
-newpr --draft "WIP feature"
+wt new "Description of the feature"
+wt new --branch my-feature "Feature description"
+wt new --pr 123              # Work on existing PR
+wt new --draft "WIP feature"
+wt new --install --code      # Install deps and open editor
 ```
 
 **Smart State Handling**: The tool detects your current git state and offers appropriate options:
@@ -93,131 +118,56 @@ newpr --draft "WIP feature"
 - On a feature branch? Create PR for it or start new
 - Detached HEAD? Create branch from current commit or main
 
-### cleanpr
-
-Clean up worktrees for merged or closed PRs.
-
-```bash
-cleanpr           # Interactive cleanup
-cleanpr --all     # Clean all merged/closed automatically
-cleanpr --force   # Force remove even if not merged
-```
-
-### lswt
+### wt list / lswt
 
 List and manage git worktrees with an interactive interface.
 
 ```bash
-lswt                  # Interactive mode (default in terminal)
-lswt --no-interactive # List-only mode
-lswt --status         # Include PR status (requires gh cli)
-lswt --json           # Output as JSON for scripting
-lswt --verbose        # Show more details (commit hashes, full paths)
-lswt | cat            # Automatically uses list mode when piped
+wt list                   # Interactive mode (default in terminal)
+wt ls --no-interactive    # List-only mode
+wt ls --status            # Include PR status (requires gh cli)
+wt ls --json              # Output as JSON for scripting
+wt ls --verbose           # Show more details
 ```
 
-**Interactive mode** (enabled by default when running in a terminal):
-
-When running in a TTY terminal, `lswt` enters interactive mode where you can select a worktree and perform actions:
-
-| Shortcut | Action                                     |
-| -------- | ------------------------------------------ |
-| `e`      | Open in editor (VSCode or Cursor)          |
-| `t`      | Open terminal at worktree path             |
-| `p`      | Open PR in browser / Create PR from branch |
-| `d`      | Show worktree details                      |
-| `c`      | Copy path to clipboard                     |
-| `l`      | Link config files (via wtlink)             |
-| `r`      | Remove worktree (not available for main)   |
-| `q`      | Quit                                       |
-
-**Fuzzy search** — Press `/` to enter search mode and filter worktrees by:
-
-- Branch name (`dark-mode`, `feat/auth`)
-- PR number (`#42`, `42`)
-- PR title (`Add dark mode`)
-- PR state (`OPEN`, `MERGED`, `CLOSED`)
+**Interactive Mode Shortcuts**:
 
-The search uses fuzzy matching, so typing `dm` will match `dark-mode`. Press `Enter` to confirm the filter, `Escape` to cancel, or `Backspace` to edit.
+| Key | Action                                     |
+| --- | ------------------------------------------ |
+| `e` | Open in editor (VS Code or Cursor)         |
+| `t` | Open terminal at worktree path             |
+| `p` | Open PR in browser / Create PR from branch |
+| `d` | Show worktree details                      |
+| `c` | Copy path to clipboard                     |
+| `l` | Link config files (via wtlink)             |
+| `r` | Remove worktree (not available for main)   |
+| `/` | Fuzzy search worktrees                     |
+| `q` | Quit                                       |
 
-Use `--no-interactive` to disable interactive mode, or pipe output to automatically switch to list mode.
+### wt clean / cleanpr
 
-### wtlink
-
-Interactive CLI for managing configuration file links between git worktrees. Share config files while keeping build artifacts separate using hard links and a manifest file.
+Clean up worktrees for merged or closed PRs.
 
 ```bash
-wtlink                    # Interactive main menu
-wtlink manage             # Interactive file browser to select files to share
-wtlink link               # Create hard links based on manifest
-wtlink link ../my-app.pr42  # Link to specific worktree
-wtlink validate           # Verify manifest integrity
+wt clean              # Interactive cleanup
+wt clean --all        # Clean all merged/closed automatically
+wt clean --force      # Force remove even if not merged
+wt clean --dry-run    # Preview what would be cleaned
 ```
 
-**Command options:**
-
-```bash
-# manage - Discover and manage the manifest
-wtlink manage                   # Interactive mode
-wtlink manage --non-interactive # Auto-add new files as commented
-wtlink manage --clean           # Remove stale entries automatically
-wtlink manage --dry-run         # Preview changes without writing
-wtlink manage --backup          # Create .wtlinkrc.bak before updating
+### wt link / wtlink
 
-# link - Create links between worktrees
-wtlink link [source] [dest]     # Link from source to destination
-wtlink link --dry-run           # Preview what would be linked
-wtlink link --type symbolic     # Use symlinks instead of hard links
-wtlink link --yes               # Skip confirmation prompts
+Interactive CLI for managing configuration file links between git worktrees.
 
-# validate - Check manifest integrity
-wtlink validate                 # Validate against current worktree
-wtlink validate ../other-wt     # Validate against specific source
+```bash
+wt link                       # Interactive main menu
+wt link manage                # Interactive file browser
+wt link link                  # Create hard links based on manifest
+wt link link ../my-app.pr42   # Link to specific worktree
+wt link validate              # Verify manifest integrity
 ```
 
-**How it works:**
-
-1. **Discover** — Scans for git-ignored files in your repository
-2. **Decide** — Interactive UI to categorize each file (link, track, or skip)
-3. **Link** — Creates hard links from main worktree to feature worktrees
-4. **Validate** — Ensures manifest entries exist and remain git-ignored
-
-**Interactive UI navigation:**
-
-| Key | Action                                           |
-| --- | ------------------------------------------------ |
-| ↑/↓ | Navigate file list                               |
-| ←/→ | Navigate into/out of folders (hierarchical view) |
-| A   | Mark as "Will Link" (added to manifest)          |
-| C   | Mark as "Track" (commented in manifest)          |
-| S   | Mark as "Skip" (not in manifest)                 |
-| 0   | Toggle showing undecided items                   |
-| 1   | Toggle showing "Will Link" items                 |
-| 2   | Toggle showing "Track" items                     |
-| 3   | Toggle showing "Skip" items                      |
-| V   | Toggle hierarchical/flat view                    |
-| ?   | Show help                                        |
-| Q   | Save and quit                                    |
-| X   | Cancel without saving                            |
-
-**Folder operations:** Actions on folders apply to all files inside. The UI shows a breakdown of child states for each folder.
-
-**Safety confirmations:** Before linking, the tool shows source and destination worktrees with their branch names and warns about potentially dangerous operations:
-
-- **Yellow warning** — Source is not on a base branch (main/master/develop). This is unusual since config files should typically flow from main to feature branches.
-- **Red warning** — Destination is a base branch. This would overwrite your main worktree's config files, which is usually not intended.
-
-The tool recognizes `main`, `master`, and `develop` as base branches. Use `--yes` to skip these confirmations if you're sure about your operation.
-
-**Conflict detection:** When linking, if a file already exists at the destination with different content, you'll be prompted to:
-
-- **Replace** — Delete destination and create link
-- **Ignore** — Keep destination file as-is
-- **Remove** — Remove entry from manifest
-
-**Manifest format (`.wtlinkrc`):**
-
-The manifest lives in your repository root and tracks which files to share:
+**Manifest format (`.wtlink`):**
 
 ```text
 .vscode/settings.json
@@ -227,237 +177,123 @@ The manifest lives in your repository root and tracks which files to share:
 ```
 
 - Active entries (no `#`) are hard-linked between worktrees
-- Commented entries (`#`) are tracked but not currently linked
-- Files marked "Skip" are not added to the manifest at all
+- Commented entries (`#`) are tracked but not linked
 
 **Best practices:**
 
-✅ **Good candidates for linking:**
-
-- `.vscode/settings.json`, `.editorconfig` — Editor config
-- `.env.local`, `.env.development` — Local environment variables
-- `certificates/`, `credentials/` — Local dev certificates
-
-❌ **Not suitable for linking:**
+- **Good for linking:** `.vscode/settings.json`, `.editorconfig`, `.env.local`, certificates
+- **Not for linking:** `node_modules/`, `dist/`, `build/`, `.git/`
 
-- `node_modules/` — Use [pnpm](https://pnpm.io) for shared dependencies instead
-- `dist/`, `build/` — Build artifacts should be separate per worktree
-- `.git/` — Never link git internals
+See [wtlink documentation](#wtlink-details) for full details.
 
-### wtstate
+### wt state / wtstate
 
-Query the current git state for AI agents and automation. Returns structured information about the repository state, available actions, and recommended next steps.
+Query the current git state for AI agents and automation.
 
 ```bash
-wtstate              # Human-readable output
-wtstate --json       # Machine-readable JSON output
-wtstate --verbose    # Include file lists and commit details
-wtstate --base dev   # Specify base branch (default: main)
+wt state              # Human-readable output
+wt state --json       # Machine-readable JSON output
+wt state --verbose    # Include file lists and commit details
+wt state --base dev   # Specify base branch
 ```
 
 **JSON output includes:**
 
-- `scenario` — Current git state scenario (e.g., `main_staged_same`, `branch_with_changes`)
-- `scenarioDescription` — Human-readable description
-- `currentBranch` — Current branch name (null if detached HEAD)
-- `baseBranch` — Base branch for comparison
+- `scenario` — Git state scenario (e.g., `main_staged_same`)
+- `currentBranch` — Current branch name
 - `worktreeType` — Type: `main_worktree`, `pr_worktree`, or `other`
-- `hasChanges`, `hasStagedChanges`, `hasUnstagedChanges` — Change flags
-- `localCommits` — List of local commits not in origin
 - `availableActions` — Actions available for this scenario
 - `recommendedAction` — Suggested action to take
 
-### wtconfig
+### wt config
 
-Configuration management with an interactive setup wizard.
+Configuration management with interactive editing.
 
 ```bash
-wtconfig init           # Run interactive setup wizard
-wtconfig show           # Show current configuration
-wtconfig set <key> <val> # Set a configuration value
-wtconfig get <key>      # Get a configuration value
-wtconfig edit           # Open config in default editor
-wtconfig validate       # Validate configuration
+wt config              # Interactive config editor
+wt cfg init            # Run setup wizard (alias for wt init)
+wt cfg show            # Show current configuration
+wt cfg set key value   # Set a configuration value
+wt cfg get key         # Get a configuration value
+wt cfg edit            # Open config in default editor
+wt cfg validate        # Validate configuration
+wt cfg schema          # Show JSON schema URL
 ```
 
-**Setup wizard detects:**
-
-- Operating system and installed tools
-- Git configuration (version, user, email)
-- GitHub CLI authentication
-- Available AI tools (Claude Code, Gemini CLI, Ollama)
-- Package manager (npm, pnpm, yarn, bun)
-- IDE availability (VS Code, Cursor)
-
-**Configuration locations:**
-
-- **Global:** `~/.worktreerc` (applies to all repos)
-- **Repository:** `.worktreerc` or `.worktreerc.json` (repo-specific)
+### wt init
 
-Repository config overrides global settings.
-
-**Example AI workflow:**
+Initialize git-worktree-tools configuration.
 
 ```bash
-# 1. Query state
-STATE=$(wtstate --json)
-
-# 2. Extract recommended action
-ACTION=$(echo $STATE | jq -r '.data.recommendedAction')
-
-# 3. Execute with chosen action
-newpr "Add feature" --non-interactive --action=$ACTION --json
+wt init            # Interactive initialization
+wt init --local    # Create local config (gitignored)
+wt init --global   # Create global config
+wt init --force    # Overwrite existing config
 ```
 
-## AI Tool Integration
-
-All commands support `--json` for machine-readable output, enabling integration with AI CLI tools like Claude Code, Gemini CLI, and Codex.
+---
 
-> **Comprehensive Guide:** See [docs/AI-TOOLING.md](docs/AI-TOOLING.md) for detailed documentation including programmatic API, error codes, lifecycle hooks, and integration examples.
-
-### Quick Start for AI Agents
+## Configuration
 
-The recommended workflow is a three-step "look before you leap" pattern:
+git-worktree-tools uses a three-tier configuration system:
 
-```bash
-# 1. Query current git state
-STATE=$(wtstate --json)
-
-# 2. Extract recommended action
-ACTION=$(echo $STATE | jq -r '.data.recommendedAction')
+| Level  | File                                       | Purpose              | Git Status |
+| ------ | ------------------------------------------ | -------------------- | ---------- |
+| Local  | `.worktreerc.local`                        | Personal overrides   | gitignored |
+| Repo   | `.worktreerc` or `.worktreerc.json`        | Shared team settings | committed  |
+| Global | `~/.config/git-worktree-tools/config.json` | User-wide defaults   | N/A        |
 
-# 3. Execute with the chosen action
-newpr "Add feature X" --non-interactive --action=$ACTION --json
-```
+**Merge order:** defaults ← global ← repo ← local
 
-### Non-Interactive Mode
+### Creating Configuration
 
 ```bash
-# Create PR without prompts
-newpr "Feature X" --non-interactive --json
-newpr "Fix bug" --non-interactive --action=commit_staged --json
+# Interactive setup (recommended)
+wt init
 
-# Clean PRs with dry-run preview
-cleanpr --all --dry-run --json
-cleanpr --all --json
-
-# Link configs without prompts
-wtlink link --yes --json
+# Or create specific configs
+wt init --global   # User-wide defaults
+wt init --local    # Personal repo overrides
 ```
 
-### JSON Output Schema
-
-All commands return consistent JSON:
-
-```typescript
-interface CommandResult<T> {
-  success: boolean; // Whether the command succeeded
-  command: string; // Command name (e.g., "newpr", "cleanpr")
-  timestamp: string; // ISO 8601 timestamp
-  data?: T; // Command-specific data (on success)
-  error?: {
-    // Error details (on failure)
-    code: string; // Machine-readable error code
-    message: string; // Human-readable message
-  };
-  warnings?: string[]; // Non-fatal warnings
-}
-```
-
-### Structured Error Codes
-
-Error codes enable programmatic error handling:
-
-| Code                   | Description                  |
-| ---------------------- | ---------------------------- |
-| `NOT_GIT_REPO`         | Not inside a git repository  |
-| `GH_NOT_AUTHENTICATED` | GitHub CLI not authenticated |
-| `INVALID_ACTION`       | Invalid action for scenario  |
-| `HOOK_FAILED`          | Lifecycle hook failed        |
-| `USER_CANCELLED`       | Operation cancelled          |
-| `PR_CREATE_FAILED`     | Failed to create PR          |
-
-See [docs/AI-TOOLING.md](docs/AI-TOOLING.md#structured-error-codes) for the complete list.
-
-### Available Actions for `--action` Flag
-
-| Action                       | Description                                |
-| ---------------------------- | ------------------------------------------ |
-| `empty_commit`               | Create empty initial commit                |
-| `commit_staged`              | Commit staged changes to new branch        |
-| `commit_all`                 | Stage all and commit to new branch         |
-| `stash_and_empty`            | Stash changes, create empty commit         |
-| `use_commits`                | Use local commits (branch from HEAD)       |
-| `push_then_branch`           | Push to main first, then create branch     |
-| `use_commits_and_commit_all` | Include commits + commit uncommitted       |
-| `use_commits_and_stash`      | Include commits, stash uncommitted         |
-| `create_pr_for_branch`       | Create PR for existing branch              |
-| `pr_for_branch_commit_all`   | Create PR for branch, commit changes first |
-| `pr_for_branch_stash`        | Create PR for branch, stash changes        |
-| `branch_from_detached`       | Create branch from detached HEAD           |
-
-### Programmatic API
-
-For deeper integration, use the programmatic API:
-
-```typescript
-import {
-  queryState,
-  listWorktrees,
-  cleanWorktrees,
-  createPr,
-} from '@camaradesuk/git-worktree-tools';
-
-// Query git state
-const state = queryState({ baseBranch: 'main' });
-if (state.success) {
-  console.log(`Scenario: ${state.data.scenario}`);
-  console.log(`Recommended: ${state.data.recommendedAction}`);
-}
-
-// Create PR
-const result = await createPr({
-  description: 'Add dark mode',
-  action: 'commit_staged',
-  draft: true,
-});
-```
-
-See [docs/AI-TOOLING.md](docs/AI-TOOLING.md#programmatic-api) for complete API documentation.
-
-## Configuration
-
-Create a `.worktreerc` file in your repository root, or use `wtconfig init` to generate one interactively:
+### Example Configuration
 
 ```json
 {
+  "$schema": "https://unpkg.com/@camaradesuk/git-worktree-tools/schemas/worktreerc.schema.json",
   "baseBranch": "main",
   "draftPr": true,
   "branchPrefix": "feat",
+  "preferredEditor": "vscode",
   "ai": {
     "provider": "auto",
     "branchName": true,
     "prDescription": true
   },
   "hooks": {
-    "post-worktree": "npm install"
+    "post-worktree": ["npm install", "code ."]
+  },
+  "logging": {
+    "level": "info"
   }
 }
 ```
 
-### Options
-
-| Option            | Type     | Default               | Description                                                |
-| ----------------- | -------- | --------------------- | ---------------------------------------------------------- |
-| `sharedRepos`     | string[] | `[]`                  | Sibling repos to also create worktrees for                 |
-| `baseBranch`      | string   | `"main"`              | Base branch for new PRs                                    |
-| `draftPr`         | boolean  | `false`               | Create PRs as drafts by default                            |
-| `worktreePattern` | string   | `"{repo}.pr{number}"` | Worktree directory naming pattern                          |
-| `worktreeParent`  | string   | `".."`                | Parent directory for worktrees                             |
-| `branchPrefix`    | string   | `"feat"`              | Prefix for auto-generated branch names                     |
-| `preferredEditor` | string   | `"vscode"`            | Editor for lswt interactive: "vscode", "cursor", or "auto" |
-| `ai`              | object   | `{}`                  | AI content generation settings (see below)                 |
-| `hooks`           | object   | `{}`                  | Lifecycle hook commands (see below)                        |
+### Configuration Options
+
+| Option            | Type     | Default               | Description                                 |
+| ----------------- | -------- | --------------------- | ------------------------------------------- |
+| `baseBranch`      | string   | `"main"`              | Base branch for new PRs                     |
+| `draftPr`         | boolean  | `false`               | Create PRs as drafts by default             |
+| `worktreePattern` | string   | `"{repo}.pr{number}"` | Worktree directory naming pattern           |
+| `worktreeParent`  | string   | `".."`                | Parent directory for worktrees              |
+| `branchPrefix`    | string   | `"feat"`              | Prefix for auto-generated branch names      |
+| `sharedRepos`     | string[] | `[]`                  | Sibling repos to also create worktrees for  |
+| `preferredEditor` | string   | `"vscode"`            | Editor: `"vscode"`, `"cursor"`, or `"auto"` |
+| `syncPatterns`    | string[] | `[]`                  | Patterns to sync between worktrees          |
+| `ai`              | object   | `{}`                  | AI content generation settings              |
+| `hooks`           | object   | `{}`                  | Lifecycle hook commands                     |
+| `logging`         | object   | `{}`                  | Logging configuration                       |
 
 ### AI Content Generation
 
@@ -466,19 +302,20 @@ Enable AI-powered content generation for branch names and PR descriptions:
 ```json
 {
   "ai": {
-    "provider": "auto", // "auto" | "claude" | "gemini" | "openai" | "ollama" | "none"
-    "branchName": true, // Generate smart branch names from description
-    "prTitle": true, // Generate PR titles
-    "prDescription": true // Generate PR descriptions from changes
+    "provider": "auto",
+    "branchName": true,
+    "prTitle": true,
+    "prDescription": true,
+    "commitMessage": true
   }
 }
 ```
 
-When `provider` is `"auto"`, the tool detects available AI tools in order: Claude Code → Gemini CLI → Ollama → OpenAI API.
+**Providers:** `"auto"` (detects available tools), `"claude"`, `"gemini"`, `"openai"`, `"ollama"`, `"none"`
 
 ### Lifecycle Hooks
 
-Run custom commands at various points in the `newpr` workflow:
+Run custom commands at various points in the workflow:
 
 ```json
 {
@@ -487,110 +324,106 @@ Run custom commands at various points in the `newpr` workflow:
     "post-pr": ["echo 'PR created!'", "./notify-team.sh"],
     "pre-branch": {
       "command": "npm test",
-      "failOnError": true
+      "failOnError": true,
+      "timeout": 60000
     }
   }
 }
 ```
 
-**Available hooks:**
+**Available hooks:** `pre-analyze`, `post-analyze`, `pre-branch`, `post-branch`, `pre-commit`, `post-commit`, `pre-push`, `post-push`, `pre-pr`, `post-pr`, `pre-worktree`, `post-worktree`, `cleanup`
 
-| Hook            | Description               | Critical |
-| --------------- | ------------------------- | -------- |
-| `pre-analyze`   | Before git state analysis | Yes      |
-| `post-analyze`  | After state analysis      | No       |
-| `pre-branch`    | Before branch creation    | Yes      |
-| `post-branch`   | After branch creation     | No       |
-| `pre-commit`    | Before initial commit     | Yes      |
-| `post-commit`   | After initial commit      | No       |
-| `pre-push`      | Before push to origin     | Yes      |
-| `post-push`     | After push to origin      | No       |
-| `pre-pr`        | Before PR creation        | Yes      |
-| `post-pr`       | After PR creation         | No       |
-| `pre-worktree`  | Before worktree creation  | Yes      |
-| `post-worktree` | After worktree creation   | No       |
-| `cleanup`       | On error (for rollback)   | No       |
+**Hook context variables** (environment variables):
 
-**Critical hooks** abort the workflow if they fail. Non-critical hooks show a warning but continue.
+| Variable           | Description       |
+| ------------------ | ----------------- |
+| `WT_BRANCH_NAME`   | New branch name   |
+| `WT_PR_NUMBER`     | PR number         |
+| `WT_PR_URL`        | PR URL            |
+| `WT_WORKTREE_PATH` | New worktree path |
+| `WT_REPO_ROOT`     | Main repo root    |
+| `WT_BASE_BRANCH`   | Base branch       |
+| `WT_DESCRIPTION`   | PR description    |
 
-**Hook definition formats:**
+### Logging Configuration
 
 ```json
 {
-  "hooks": {
-    // Simple command
-    "post-worktree": "npm install",
-
-    // Multiple commands (run in sequence)
-    "post-pr": ["echo 'Done!'", "./scripts/notify.sh"],
-
-    // Complex definition
-    "pre-commit": {
-      "command": "npm test",
-      "timeout": 60000,
-      "failOnError": true,
-      "if": "exists:package.json"
-    }
+  "logging": {
+    "level": "info",
+    "logFile": "/path/to/logfile.log"
   }
 }
 ```
 
-**Hook context variables** (available as environment variables):
+**Levels:** `silent`, `error`, `warn`, `info`, `debug`, `trace`
 
-| Variable           | Description        |
-| ------------------ | ------------------ |
-| `WT_BRANCH_NAME`   | New branch name    |
-| `WT_PR_NUMBER`     | PR number          |
-| `WT_PR_URL`        | PR URL             |
-| `WT_WORKTREE_PATH` | New worktree path  |
-| `WT_REPO_ROOT`     | Main repo root     |
-| `WT_BASE_BRANCH`   | Base branch (main) |
-| `WT_DESCRIPTION`   | PR description     |
+CLI flags override config: `-v` (debug), `-vv` (trace), `-q` (silent), `--log-file`
 
-> **Note:** File syncing between worktrees is managed by `wtlink` using its own `.wtlinkrc` manifest. See the [wtlink section](#wtlink) for details.
+---
 
-## Example Workflow
+## AI Tool Integration
+
+All commands support `--json` for machine-readable output, enabling integration with AI CLI tools.
+
+### Quick Start for AI Agents
 
 ```bash
-# Start in your main repo
-cd ~/projects/my-app
+# 1. Query current git state
+STATE=$(wt state --json)
 
-# Create a new feature PR
-newpr "Add dark mode support"
-# → Creates branch: feat/add-dark-mode-support-xyz123
-# → Creates PR: #42
-# → Creates worktree: ~/projects/my-app.pr42
-# → Switches to worktree
+# 2. Extract recommended action
+ACTION=$(echo $STATE | jq -r '.data.recommendedAction')
 
-# Work on the feature in the dedicated worktree
-# ... make changes, commit, push ...
+# 3. Execute with the chosen action
+wt new "Add feature X" --non-interactive --action=$ACTION --json
+```
 
-# Need to work on another feature? No problem!
-cd ~/projects/my-app
-newpr "Fix login bug"
-# → Creates another worktree: ~/projects/my-app.pr43
+### Non-Interactive Mode
 
-# List your worktrees
-lswt
-# WORKTREE              BRANCH                         PR     STATUS
-# ~/projects/my-app     main                           -      -
-# ~/projects/my-app.pr42 feat/add-dark-mode-xyz123  #42    open
-# ~/projects/my-app.pr43 feat/fix-login-bug-abc456  #43    open
+```bash
+wt new "Feature" --non-interactive --json
+wt clean --all --json
+wt link link --yes --json
+```
 
-# After PRs are merged, clean up
-cleanpr
-# → Removes worktrees for merged PRs
-# → Deletes local branches
+### JSON Response Schema
+
+```typescript
+interface CommandResult<T> {
+  success: boolean;
+  command: string;
+  timestamp: string;
+  data?: T;
+  error?: { code: string; message: string };
+  warnings?: string[];
+}
+```
+
+### Programmatic API
+
+```typescript
+import { queryState, createPr, listWorktrees } from '@camaradesuk/git-worktree-tools';
+
+const state = queryState({ baseBranch: 'main' });
+const result = await createPr({
+  description: 'Add dark mode',
+  action: 'commit_staged',
+  draft: true,
+});
 ```
 
+See [docs/AI-TOOLING.md](docs/AI-TOOLING.md) for comprehensive AI integration documentation including error codes, available actions, and integration examples.
+
+---
+
 ## Shell Completion
 
-Enable tab completion for `wt` commands in your shell:
+Enable tab completion for `wt` commands:
 
 ### Bash
 
 ```bash
-# Add to ~/.bashrc
 wt completion bash >> ~/.bashrc
 source ~/.bashrc
 ```
@@ -598,13 +431,9 @@ source ~/.bashrc
 ### Zsh
 
 ```bash
-# Create completion directory and add completion
 mkdir -p ~/.zsh/completions
 wt completion zsh > ~/.zsh/completions/_wt
-
-# Add to ~/.zshrc (if not already present)
-fpath=(~/.zsh/completions $fpath)
-autoload -Uz compinit && compinit
+# Add to ~/.zshrc: fpath=(~/.zsh/completions $fpath)
 ```
 
 ### Fish
@@ -613,35 +442,95 @@ autoload -Uz compinit && compinit
 wt completion fish > ~/.config/fish/completions/wt.fish
 ```
 
-After setup, you can tab-complete commands and options:
+---
+
+## wtlink Details
+
+The `wtlink` command provides an interactive TUI for managing configuration file links.
+
+### Interactive UI Navigation
+
+| Key | Action                                           |
+| --- | ------------------------------------------------ |
+| ↑/↓ | Navigate file list                               |
+| ←/→ | Navigate into/out of folders (hierarchical view) |
+| A   | Mark as "Will Link" (added to manifest)          |
+| C   | Mark as "Track" (commented in manifest)          |
+| S   | Mark as "Skip" (not in manifest)                 |
+| 0-3 | Toggle filter visibility                         |
+| V   | Toggle hierarchical/flat view                    |
+| ?   | Show help                                        |
+| Q   | Save and quit                                    |
+| X   | Cancel without saving                            |
+
+### Command Options
 
 ```bash
-wt <TAB>           # Shows: new, list, clean, link, state, config, completion
-wt new --<TAB>     # Shows: --pr, --draft, --json, --non-interactive, --action
-wt list --<TAB>    # Shows: --verbose, --json, --no-status, --no-interactive
+# manage - Discover and manage the manifest
+wtlink manage                   # Interactive mode
+wtlink manage --non-interactive # Auto-add new files as commented
+wtlink manage --clean           # Remove stale entries
+wtlink manage --dry-run         # Preview changes
+
+# link - Create links between worktrees
+wtlink link [source] [dest]     # Link from source to destination
+wtlink link --dry-run           # Preview what would be linked
+wtlink link --type symbolic     # Use symlinks instead of hard links
+wtlink link --yes               # Skip confirmation prompts
+
+# validate - Check manifest integrity
+wtlink validate                 # Validate against current worktree
 ```
 
+---
+
+## Example Workflow
+
+```bash
+# Start in your main repo
+cd ~/projects/my-app
+
+# Create a new feature PR
+wt new "Add dark mode support"
+# → Creates branch: feat/add-dark-mode-support-xyz123
+# → Creates PR: #42
+# → Creates worktree: ~/projects/my-app.pr42
+# → Runs post-worktree hooks (npm install, etc.)
+
+# Work on the feature in the dedicated worktree
+# ... make changes, commit, push ...
+
+# Need another feature? No problem!
+cd ~/projects/my-app
+wt new "Fix login bug"
+# → Creates worktree: ~/projects/my-app.pr43
+
+# List your worktrees
+wt list
+# Interactive selection with PR status
+
+# After PRs are merged, clean up
+wt clean
+# → Removes worktrees for merged PRs
+# → Deletes local branches
+```
+
+---
+
 ## Development
 
 ```bash
-# Clone the repo
 git clone https://github.com/camaradesuk/git-worktree-tools.git
 cd git-worktree-tools
-
-# Install dependencies
 npm install
-
-# Build
 npm run build
-
-# Test
 npm test
-
-# Link for local development
-npm link
+npm link  # For local development
 ```
 
-See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed local development instructions, including how to test CLI commands without affecting your global install.
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for detailed development instructions.
+
+---
 
 ## License