docs: update package docblocks across all cmd/ packages

Add comprehensive package-level documentation to all CLI command packages:
- cmd/core.go, core_ci.go, core_dev.go: Main CLI entry points
- cmd/shared: Lipgloss styles and utility functions
- cmd/ai: AI agent task management and Claude integration
- cmd/dev: Multi-repo git workflows and GitHub integration
- cmd/build, cmd/ci: Build and release automation
- cmd/sdk: OpenAPI validation and compatibility
- cmd/go: Go development tools with enhanced output
- cmd/php: Laravel development, build, and deployment
- cmd/docs: Documentation sync across repos
- cmd/doctor: Environment validation
- cmd/test: Test runner with coverage
- cmd/pkg: GitHub package management
- cmd/setup: Workspace initialisation
- cmd/vm: LinuxKit VM management

Each docblock now describes:
- Package purpose and commands
- Key features and configuration
- Package naming notes where relevant (gocmd, testcmd)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

cmd/ai/agentic.go

@@ -1,4 +1,9 @@
-// Package ai provides AI agent tools and task management commands.
+// agentic.go implements task management commands for the core-agentic service.
+//
+// The agentic service provides a task queue for AI-assisted development.
+// Tasks can be listed, claimed, updated, and completed through these commands.
+// Git integration allows automatic commits and PR creation with task references.
+
 package ai
 
 import (

cmd/ai/commands.go

@@ -1,20 +1,34 @@
-// Package ai provides AI agent tools and task management commands.
+// Package ai provides AI agent task management and Claude Code integration.
+//
+// Commands:
+//   - tasks: List tasks from the agentic service
+//   - task: View, claim, or auto-select tasks
+//   - task:update: Update task status and progress
+//   - task:complete: Mark tasks as completed or failed
+//   - task:commit: Create commits with task references
+//   - task:pr: Create pull requests linked to tasks
+//   - claude: Claude Code CLI integration (planned)
 package ai
 
 import "github.com/leaanthony/clir"
 
 // AddCommands registers the 'ai' command and all subcommands.
 func AddCommands(app *clir.Cli) {
-	aiCmd := app.NewSubCommand("ai", "AI agent tools")
+	aiCmd := app.NewSubCommand("ai", "AI agent task management")
-	aiCmd.LongDescription("AI and agent-related tools for development.\n\n" +
+	aiCmd.LongDescription("Manage tasks from the core-agentic service for AI-assisted development.\n\n" +
 		"Commands:\n" +
-		"  claude    Claude Code integration\n" +
+		"  tasks          List tasks (filterable by status, priority, labels)\n" +
-		"  tasks     List available tasks\n" +
+		"  task           View task details or auto-select highest priority\n" +
-		"  task      Show/claim a specific task\n\n" +
+		"  task:update    Update task status or progress\n" +
-		"Task workflow:\n" +
+		"  task:complete  Mark task as completed or failed\n" +
+		"  task:commit    Create git commit with task reference\n" +
+		"  task:pr        Create GitHub PR linked to task\n" +
+		"  claude         Claude Code integration\n\n" +
+		"Workflow:\n" +
 		"  core ai tasks                      # List pending tasks\n" +
-		"  core ai task <id>          # View and claim a task\n" +
+		"  core ai task --auto --claim        # Auto-select and claim a task\n" +
-		"  core ai task:complete <id> # Mark task complete")
+		"  core ai task:commit <id> -m 'msg'  # Commit with task reference\n" +
+		"  core ai task:complete <id>         # Mark task done")
 
 	// Add Claude command
 	addClaudeCommand(aiCmd)

cmd/ci/commands.go

@@ -1,3 +1,12 @@
+// Package ci provides release publishing commands for CI/CD pipelines.
+//
+// Publishes pre-built artifacts from dist/ to configured targets:
+//   - GitHub Releases
+//   - S3-compatible storage
+//   - Custom endpoints
+//
+// Safe by default: runs in dry-run mode unless --were-go-for-launch is specified.
+// Configuration via .core/release.yaml.
 package ci
 
 import "github.com/leaanthony/clir"

cmd/core.go

@@ -1,3 +1,19 @@
+// Package cmd implements the core CLI application.
+//
+// The CLI provides commands for:
+//   - Multi-repo development workflows (dev)
+//   - AI agent task management (ai)
+//   - Go and PHP development tools (go, php)
+//   - Build and release automation (build, ci)
+//   - SDK validation and API compatibility (sdk)
+//   - Package and environment management (pkg, vm)
+//   - Documentation and testing (docs, test)
+//   - Environment health checks (doctor)
+//   - Repository setup and cloning (setup)
+//
+// Two build variants exist:
+//   - Default build: Full development toolset
+//   - CI build (-tags ci): Minimal release toolset
 package cmd
 
 import (
@@ -5,27 +21,28 @@ import (
 	"github.com/leaanthony/clir"
 )
 
-// Define some global lipgloss styles for a Tailwind dark theme
+// Terminal styles using Tailwind color palette.
 var (
+	// coreStyle is used for primary headings and the CLI name.
 	coreStyle = lipgloss.NewStyle().
-			Foreground(lipgloss.Color("#3b82f6")). // Tailwind blue-500
+			Foreground(lipgloss.Color("#3b82f6")). // blue-500
 			Bold(true)
 
+	// subPkgStyle is used for subcommand names and secondary headings.
 	subPkgStyle = lipgloss.NewStyle().
-			Foreground(lipgloss.Color("#e2e8f0")). // Tailwind gray-200
+			Foreground(lipgloss.Color("#e2e8f0")). // gray-200
 			Bold(true)
 
+	// linkStyle is used for URLs and clickable references.
 	linkStyle = lipgloss.NewStyle().
-			Foreground(lipgloss.Color("#3b82f6")). // Tailwind blue-500
+			Foreground(lipgloss.Color("#3b82f6")). // blue-500
 			Underline(true)
 )
 
-// Execute creates the root CLI application and runs it.
+// Execute initialises and runs the CLI application.
+// Commands are registered based on build tags (see core_ci.go and core_dev.go).
 func Execute() error {
 	app := clir.NewCli("core", "CLI tool for development and production", "0.1.0")
-
-	// Register commands based on build tags
 	registerCommands(app)
-
 	return app.Run()
 }

cmd/core_ci.go

@@ -1,5 +1,17 @@
 //go:build ci
 
+// core_ci.go registers commands for the minimal CI/release binary.
+//
+// Build with: go build -tags ci
+//
+// This variant includes only commands needed for CI pipelines:
+//   - build: Cross-platform compilation
+//   - ci: Release publishing
+//   - sdk: API compatibility checks
+//   - doctor: Environment verification
+//
+// Use this build to reduce binary size and attack surface in production.
+
 package cmd
 
 import (
@@ -10,14 +22,10 @@ import (
 	"github.com/leaanthony/clir"
 )
 
-// registerCommands adds only CI/release commands for the minimal binary.
+// registerCommands adds CI/release commands only.
-// Build with: go build -tags ci
 func registerCommands(app *clir.Cli) {
-	// CI/Release commands only - minimal attack surface
 	build.AddCommands(app)
 	ci.AddCommands(app)
 	sdk.AddCommands(app)
-
-	// Doctor for environment verification
 	doctor.AddCommands(app)
 }

cmd/core_dev.go

@@ -1,5 +1,24 @@
 //go:build !ci
 
+// core_dev.go registers commands for the full development binary.
+//
+// Build with: go build (default)
+//
+// This is the default build variant with all development tools:
+//   - dev: Multi-repo git workflows (commit, push, pull, sync)
+//   - ai: AI agent task management
+//   - go: Go module and build tools
+//   - php: Laravel/Composer development tools
+//   - build: Cross-platform compilation
+//   - ci: Release publishing
+//   - sdk: API compatibility checks
+//   - pkg: Package management
+//   - vm: LinuxKit VM management
+//   - docs: Documentation generation
+//   - setup: Repository cloning and setup
+//   - doctor: Environment health checks
+//   - test: Test runner with coverage
+
 package cmd
 
 import (
@@ -19,25 +38,24 @@ import (
 	"github.com/leaanthony/clir"
 )
 
-// registerCommands adds all commands for the full development binary.
+// registerCommands adds all development commands.
-// Build with: go build (default) or go build -tags dev
 func registerCommands(app *clir.Cli) {
-	// Dev workflow commands
+	// Multi-repo workflow
 	dev.AddCommands(app)
 
-	// AI/Agent commands
+	// AI agent tools
 	ai.AddCommands(app)
 
-	// Language-specific development tools
+	// Language tooling
 	gocmd.AddCommands(app)
 	php.AddCommands(app)
 
-	// CI/Release commands (also available in ci build)
+	// Build and release
 	build.AddCommands(app)
 	ci.AddCommands(app)
 	sdk.AddCommands(app)
 
-	// Package/environment management (dev only)
+	// Environment management
 	pkg.AddCommands(app)
 	vm.AddCommands(app)
 	docs.AddCommands(app)

cmd/dev/commands.go

@@ -1,7 +1,20 @@
 // Package dev provides multi-repo development workflow commands.
 //
-// Commands include git operations (work, commit, push, pull), GitHub
+// This package manages git operations across multiple repositories defined in
-// integration (issues, reviews, ci, impact), and dev environment management.
+// repos.yaml. It also provides GitHub integration and dev environment management.
+//
+// Commands:
+//   - work: Combined status, commit, and push workflow
+//   - health: Quick health check across all repos
+//   - commit: Claude-assisted commit message generation
+//   - push: Push repos with unpushed commits
+//   - pull: Pull repos that are behind remote
+//   - sync: Sync all repos with remote (pull + push)
+//   - issues: List GitHub issues across repos
+//   - reviews: List PRs needing review
+//   - ci: Check GitHub Actions CI status
+//   - impact: Analyse dependency impact of changes
+//   - install/boot/stop: Dev environment VM management
 package dev
 
 import "github.com/leaanthony/clir"
@@ -9,18 +22,27 @@ import "github.com/leaanthony/clir"
 // AddCommands registers the 'dev' command and all subcommands.
 func AddCommands(app *clir.Cli) {
 	devCmd := app.NewSubCommand("dev", "Multi-repo development workflow")
-	devCmd.LongDescription("Multi-repo git operations and GitHub integration.\n\n" +
+	devCmd.LongDescription("Manage multiple git repositories and GitHub integration.\n\n" +
+		"Uses repos.yaml to discover repositories. Falls back to scanning\n" +
+		"the current directory if no registry is found.\n\n" +
 		"Git Operations:\n" +
-		"  work      Multi-repo status, commit, push workflow\n" +
+		"  work      Combined status → commit → push workflow\n" +
-		"  health    Quick health check across repos\n" +
+		"  health    Quick repo health summary\n" +
-		"  commit    Claude-assisted commits\n" +
+		"  commit    Claude-assisted commit messages\n" +
 		"  push      Push repos with unpushed commits\n" +
-		"  pull      Pull repos that are behind\n\n" +
+		"  pull      Pull repos behind remote\n" +
-		"GitHub Integration:\n" +
+		"  sync      Sync all repos (pull + push)\n\n" +
+		"GitHub Integration (requires gh CLI):\n" +
 		"  issues    List open issues across repos\n" +
-		"  reviews   List PRs needing review\n" +
+		"  reviews   List PRs awaiting review\n" +
-		"  ci        Check CI status\n" +
+		"  ci        Check GitHub Actions status\n" +
-		"  impact    Show dependency impact")
+		"  impact    Analyse dependency impact\n\n" +
+		"Dev Environment:\n" +
+		"  install   Download dev environment image\n" +
+		"  boot      Start dev environment VM\n" +
+		"  stop      Stop dev environment VM\n" +
+		"  shell     Open shell in dev VM\n" +
+		"  status    Check dev VM status")
 
 	// Git operations
 	AddWorkCommand(devCmd)

cmd/docs/commands.go

@@ -1,3 +1,11 @@
+// Package docs provides documentation management commands for multi-repo workspaces.
+//
+// Commands:
+//   - list: Scan repos for README.md, CLAUDE.md, CHANGELOG.md, docs/
+//   - sync: Copy docs/ files from all repos to core-php/docs/packages/
+//
+// Works with repos.yaml to discover repositories and sync documentation
+// to a central location for unified documentation builds.
 package docs
 
 import "github.com/leaanthony/clir"

cmd/doctor/commands.go

@@ -1,3 +1,13 @@
+// Package doctor provides environment validation commands.
+//
+// Checks for:
+//   - Required tools: git, gh, php, composer, node
+//   - Optional tools: pnpm, claude, docker
+//   - GitHub access: SSH keys and CLI authentication
+//   - Workspace: repos.yaml presence and clone status
+//
+// Run before 'core setup' to ensure your environment is ready.
+// Provides platform-specific installation instructions for missing tools.
 package doctor
 
 import "github.com/leaanthony/clir"

cmd/go/commands.go

@@ -1,3 +1,17 @@
+// Package gocmd provides Go development commands with enhanced output.
+//
+// Note: Package named gocmd because 'go' is a reserved keyword.
+//
+// Commands:
+//   - test: Run tests with colour-coded coverage summary
+//   - cov: Run tests with detailed coverage reports (HTML, thresholds)
+//   - fmt: Format code using goimports or gofmt
+//   - lint: Run golangci-lint
+//   - install: Install binary to $GOPATH/bin
+//   - mod: Module management (tidy, download, verify, graph)
+//   - work: Workspace management (sync, init, use)
+//
+// Sets MACOSX_DEPLOYMENT_TARGET to suppress linker warnings on macOS.
 package gocmd
 
 import "github.com/leaanthony/clir"

cmd/php/commands.go

@@ -1,3 +1,30 @@
+// Package php provides Laravel/PHP development and deployment commands.
+//
+// Development Commands:
+//   - dev: Start Laravel environment (FrankenPHP, Vite, Horizon, Reverb, Redis)
+//   - logs: Stream unified service logs
+//   - stop: Stop all running services
+//   - status: Show service status
+//   - ssl: Setup SSL certificates with mkcert
+//
+// Build Commands:
+//   - build: Build Docker or LinuxKit image
+//   - serve: Run production container
+//   - shell: Open shell in running container
+//
+// Code Quality:
+//   - test: Run PHPUnit/Pest tests
+//   - fmt: Format code with Laravel Pint
+//   - analyse: Run PHPStan/Larastan static analysis
+//
+// Package Management:
+//   - packages link/unlink/update/list: Manage local Composer packages
+//
+// Deployment (Coolify):
+//   - deploy: Deploy to Coolify
+//   - deploy:status: Check deployment status
+//   - deploy:rollback: Rollback deployment
+//   - deploy:list: List recent deployments
 package php
 
 import "github.com/leaanthony/clir"

cmd/pkg/commands.go

@@ -1,3 +1,14 @@
+// Package pkg provides GitHub package management for host-uk repositories.
+//
+// Commands:
+//   - search: Search GitHub org for repos (cached for 1 hour)
+//   - install: Clone a repo from GitHub to packages/
+//   - list: List installed packages from repos.yaml
+//   - update: Pull latest changes for packages
+//   - outdated: Check which packages have unpulled commits
+//
+// Uses gh CLI for authenticated GitHub access. Results are cached in
+// .core/cache/ within the workspace directory.
 package pkg
 
 import "github.com/leaanthony/clir"

cmd/sdk/commands.go

@@ -1,3 +1,10 @@
+// Package sdk provides SDK validation and API compatibility commands.
+//
+// Commands:
+//   - diff: Check for breaking API changes between spec versions
+//   - validate: Validate OpenAPI spec syntax
+//
+// Configuration via .core/sdk.yaml. For SDK generation, use: core build sdk
 package sdk
 
 import "github.com/leaanthony/clir"

cmd/setup/commands.go

@@ -1,3 +1,14 @@
+// Package setup provides workspace initialisation commands.
+//
+// Clones all repositories defined in repos.yaml into the workspace.
+// Skips repos that already exist. Supports filtering by type.
+//
+// Flags:
+//   - --registry: Path to repos.yaml (auto-detected if not specified)
+//   - --only: Filter by repo type (foundation, module, product)
+//   - --dry-run: Preview what would be cloned
+//
+// Uses gh CLI with HTTPS when authenticated, falls back to SSH.
 package setup
 
 import "github.com/leaanthony/clir"

cmd/shared/styles.go

@@ -1,36 +1,51 @@
+// Package shared provides common utilities and styles for CLI commands.
+//
+// This package contains:
+//   - Terminal styling using lipgloss with Tailwind colours
+//   - Common helper functions (truncation, confirmation prompts)
+//   - Git and GitHub CLI utilities
 package shared
 
 import "github.com/charmbracelet/lipgloss"
 
-// Common styles used across multiple command packages.
+// Terminal styles using Tailwind colour palette.
+// These are shared across command packages for consistent output.
 var (
+	// RepoNameStyle highlights repository names (blue, bold).
 	RepoNameStyle = lipgloss.NewStyle().
 			Bold(true).
-			Foreground(lipgloss.Color("#3b82f6"))
+			Foreground(lipgloss.Color("#3b82f6")) // blue-500
 
+	// SuccessStyle indicates successful operations (green, bold).
 	SuccessStyle = lipgloss.NewStyle().
 			Bold(true).
-			Foreground(lipgloss.Color("#22c55e"))
+			Foreground(lipgloss.Color("#22c55e")) // green-500
 
+	// ErrorStyle indicates errors and failures (red, bold).
 	ErrorStyle = lipgloss.NewStyle().
 			Bold(true).
-			Foreground(lipgloss.Color("#ef4444"))
+			Foreground(lipgloss.Color("#ef4444")) // red-500
 
+	// WarningStyle indicates warnings and cautions (amber, bold).
 	WarningStyle = lipgloss.NewStyle().
 			Bold(true).
-			Foreground(lipgloss.Color("#f59e0b"))
+			Foreground(lipgloss.Color("#f59e0b")) // amber-500
 
+	// DimStyle for secondary/muted text (gray).
 	DimStyle = lipgloss.NewStyle().
-			Foreground(lipgloss.Color("#6b7280"))
+			Foreground(lipgloss.Color("#6b7280")) // gray-500
 
+	// ValueStyle for data values and output (light gray).
 	ValueStyle = lipgloss.NewStyle().
-			Foreground(lipgloss.Color("#e2e8f0"))
+			Foreground(lipgloss.Color("#e2e8f0")) // gray-200
 
+	// LinkStyle for URLs and clickable references (blue, underlined).
 	LinkStyle = lipgloss.NewStyle().
-			Foreground(lipgloss.Color("#3b82f6")).
+			Foreground(lipgloss.Color("#3b82f6")). // blue-500
 			Underline(true)
 
+	// HeaderStyle for section headers (light gray, bold).
 	HeaderStyle = lipgloss.NewStyle().
 			Bold(true).
-			Foreground(lipgloss.Color("#e2e8f0"))
+			Foreground(lipgloss.Color("#e2e8f0")) // gray-200
 )

cmd/shared/utils.go

@@ -8,12 +8,15 @@ import (
 	"time"
 )
 
+// GhAuthenticated checks if the GitHub CLI is authenticated.
+// Returns true if 'gh auth status' indicates a logged-in user.
 func GhAuthenticated() bool {
 	cmd := exec.Command("gh", "auth", "status")
 	output, _ := cmd.CombinedOutput()
 	return strings.Contains(string(output), "Logged in")
 }
 
+// Truncate shortens a string to max characters, adding "..." if truncated.
 func Truncate(s string, max int) string {
 	if len(s) <= max {
 		return s
@@ -21,6 +24,8 @@ func Truncate(s string, max int) string {
 	return s[:max-3] + "..."
 }
 
+// Confirm prompts the user for yes/no confirmation.
+// Returns true if the user enters "y" or "yes" (case-insensitive).
 func Confirm(prompt string) bool {
 	fmt.Printf("%s [y/N] ", prompt)
 	var response string
@@ -29,6 +34,8 @@ func Confirm(prompt string) bool {
 	return response == "y" || response == "yes"
 }
 
+// FormatAge formats a time as a human-readable age string.
+// Examples: "5m ago", "2h ago", "3d ago", "1w ago", "2mo ago"
 func FormatAge(t time.Time) string {
 	d := time.Since(t)
 	if d < time.Hour {
@@ -46,6 +53,8 @@ func FormatAge(t time.Time) string {
 	return fmt.Sprintf("%dmo ago", int(d.Hours()/(24*30)))
 }
 
+// GitClone clones a GitHub repository to the specified path.
+// Prefers 'gh repo clone' if authenticated, falls back to SSH.
 func GitClone(ctx context.Context, org, repo, path string) error {
 	if GhAuthenticated() {
 		httpsURL := fmt.Sprintf("https://github.com/%s/%s.git", org, repo)
@@ -59,6 +68,7 @@ func GitClone(ctx context.Context, org, repo, path string) error {
 			return fmt.Errorf("%s", errStr)
 		}
 	}
+	// Fall back to SSH clone
 	cmd := exec.CommandContext(ctx, "git", "clone", fmt.Sprintf("git@github.com:%s/%s.git", org, repo), path)
 	output, err := cmd.CombinedOutput()
 	if err != nil {

cmd/test/commands.go

@@ -1,3 +1,14 @@
+// Package testcmd provides Go test running commands with enhanced output.
+//
+// Note: Package named testcmd to avoid conflict with Go's test package.
+//
+// Features:
+//   - Colour-coded pass/fail/skip output
+//   - Per-package coverage breakdown with --coverage
+//   - JSON output for CI/agents with --json
+//   - Filters linker warnings on macOS
+//
+// Flags: --verbose, --coverage, --short, --pkg, --run, --race, --json
 package testcmd
 
 import "github.com/leaanthony/clir"

cmd/vm/commands.go

@@ -1,3 +1,15 @@
+// Package vm provides LinuxKit virtual machine management commands.
+//
+// Commands:
+//   - run: Run a VM from image (.iso, .qcow2, .vmdk, .raw) or template
+//   - ps: List running VMs
+//   - stop: Stop a running VM
+//   - logs: View VM logs
+//   - exec: Execute command in VM via SSH
+//   - templates: Manage LinuxKit templates (list, build)
+//
+// Uses qemu or hyperkit depending on system availability.
+// Templates are built from YAML definitions and can include variables.
 package vm
 
 import "github.com/leaanthony/clir"