From 654f8df1adbf573a3c557be8accff57874ba62cc Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Thu, 29 Jan 2026 19:59:49 +0000
Subject: [PATCH] docs: add guides and fix documentation issues
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

New documentation:
- getting-started.md: installation, first build, first release
- troubleshooting.md: common errors and fixes
- workflows.md: end-to-end task sequences
- glossary.md: term definitions
- migration.md: upgrading from legacy tools

Fixes:
- Command examples: core dev task* → core ai task*
- CI flag: --were-go-for-launch → --we-are-go-for-launch
- Setup commands: core health → core dev health
- Installation: circular core go install reference
- Cross-references: broken fragment links

Improvements:
- Added complete repos.yaml documentation
- Added comprehensive environment variables reference
- Added multiple installation methods (go install, binary, source)
- Moved TODO.md to docs/.internal/

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 .claude/skills/core/SKILL.md    |  12 +-
 cmd/ci/commands.go              |   2 +-
 docs/{cmd => .internal}/TODO.md |   0
 docs/cmd/dev/example.md         |  28 +--
 docs/cmd/dev/work/index.md      |   2 +-
 docs/cmd/index.md               |   4 +-
 docs/cmd/setup/index.md         |   7 +-
 docs/configuration.md           | 142 +++++++++++++-
 docs/getting-started.md         | 191 ++++++++++++++++++
 docs/glossary.md                | 112 +++++++++++
 docs/index.md                   |  25 ++-
 docs/migration.md               | 233 ++++++++++++++++++++++
 docs/troubleshooting.md         | 332 +++++++++++++++++++++++++++++++
 docs/workflows.md               | 334 ++++++++++++++++++++++++++++++++
 14 files changed, 1387 insertions(+), 37 deletions(-)
 rename docs/{cmd => .internal}/TODO.md (100%)
 create mode 100644 docs/getting-started.md
 create mode 100644 docs/glossary.md
 create mode 100644 docs/migration.md
 create mode 100644 docs/troubleshooting.md
 create mode 100644 docs/workflows.md

diff --git a/.claude/skills/core/SKILL.md b/.claude/skills/core/SKILL.md
index 9a6c4b75..4d5454ca 100644
--- a/.claude/skills/core/SKILL.md
+++ b/.claude/skills/core/SKILL.md
@@ -28,7 +28,7 @@ The `core` command provides a unified interface for Go/Wails development, multi-
 | Build for targets | `core build --targets linux/amd64,darwin/arm64` | Cross-compile |
 | Build SDK | `core build sdk` | Generate API clients from OpenAPI |
 | Preview release | `core ci` | Dry-run publish (safe default) |
-| Publish release | `core ci --were-go-for-launch` | Actually publish artifacts |
+| Publish release | `core ci --we-are-go-for-launch` | Actually publish artifacts |
 | Check environment | `core doctor` | Verify tools installed |
 | Multi-repo status | `core dev health` | Quick summary across repos |
 | Multi-repo workflow | `core dev work` | Status + commit + push |
@@ -82,12 +82,12 @@ core build sdk
 core ci                          # Dry-run: shows what would be published
 
 # Step 3: Actually publish (explicit flag required)
-core ci --were-go-for-launch     # Actually publish to targets
-core ci --were-go-for-launch --draft       # Publish as draft
-core ci --were-go-for-launch --prerelease  # Publish as prerelease
+core ci --we-are-go-for-launch     # Actually publish to targets
+core ci --we-are-go-for-launch --draft       # Publish as draft
+core ci --we-are-go-for-launch --prerelease  # Publish as prerelease
 ```
 
-**Why safe by default?** `core ci` always does a dry-run unless you explicitly say `--were-go-for-launch`.
+**Why safe by default?** `core ci` always does a dry-run unless you explicitly say `--we-are-go-for-launch`.
 
 ```bash
 # Release workflow utilities
@@ -562,7 +562,7 @@ Go project?
   └── Build: core build [--targets <os/arch>]
   └── Build SDK: core build sdk
   └── Preview publish: core ci
-  └── Publish: core ci --were-go-for-launch
+  └── Publish: core ci --we-are-go-for-launch
 
 PHP/Laravel project?
   └── Start dev: core php dev [--https]
diff --git a/cmd/ci/commands.go b/cmd/ci/commands.go
index 49062587..819df247 100644
--- a/cmd/ci/commands.go
+++ b/cmd/ci/commands.go
@@ -5,7 +5,7 @@
 //   - S3-compatible storage
 //   - Custom endpoints
 //
-// Safe by default: runs in dry-run mode unless --were-go-for-launch is specified.
+// Safe by default: runs in dry-run mode unless --we-are-go-for-launch is specified.
 // Configuration via .core/release.yaml.
 package ci
 
diff --git a/docs/cmd/TODO.md b/docs/.internal/TODO.md
similarity index 100%
rename from docs/cmd/TODO.md
rename to docs/.internal/TODO.md
diff --git a/docs/cmd/dev/example.md b/docs/cmd/dev/example.md
index 8d235ae8..da75b5e1 100644
--- a/docs/cmd/dev/example.md
+++ b/docs/cmd/dev/example.md
@@ -79,46 +79,46 @@ core dev impact core-php
 
 ```bash
 # List tasks
-core dev tasks
+core ai tasks
 
 # Filter by status and priority
-core dev tasks --status pending --priority high
+core ai tasks --status pending --priority high
 
 # Filter by labels
-core dev tasks --labels bug,urgent
+core ai tasks --labels bug,urgent
 
 # Show task details
-core dev task abc123
+core ai task abc123
 
 # Auto-select highest priority task
-core dev task --auto
+core ai task --auto
 
 # Claim a task
-core dev task abc123 --claim
+core ai task abc123 --claim
 
 # Update task status
-core dev task:update abc123 --status in_progress
+core ai task:update abc123 --status in_progress
 
 # Add progress notes
-core dev task:update abc123 --progress 50 --notes 'Halfway done'
+core ai task:update abc123 --progress 50 --notes 'Halfway done'
 
 # Complete a task
-core dev task:complete abc123 --output 'Feature implemented'
+core ai task:complete abc123 --output 'Feature implemented'
 
 # Mark as failed
-core dev task:complete abc123 --failed --error 'Build failed'
+core ai task:complete abc123 --failed --error 'Build failed'
 
 # Commit with task reference
-core dev task:commit abc123 -m 'add user authentication'
+core ai task:commit abc123 -m 'add user authentication'
 
 # Commit with scope and push
-core dev task:commit abc123 -m 'fix login bug' --scope auth --push
+core ai task:commit abc123 -m 'fix login bug' --scope auth --push
 
 # Create PR for task
-core dev task:pr abc123
+core ai task:pr abc123
 
 # Create draft PR with labels
-core dev task:pr abc123 --draft --labels 'enhancement,needs-review'
+core ai task:pr abc123 --draft --labels 'enhancement,needs-review'
 ```
 
 ## Service API Management
diff --git a/docs/cmd/dev/work/index.md b/docs/cmd/dev/work/index.md
index 6e8ccea3..454fe22b 100644
--- a/docs/cmd/dev/work/index.md
+++ b/docs/cmd/dev/work/index.md
@@ -283,7 +283,7 @@ core dev impact core-php
 
 ## Registry
 
-These commands use `repos.yaml` to know which repos to manage. See [Configuration](example.md#registry) for format.
+These commands use `repos.yaml` to know which repos to manage. See [repos.yaml](../../../configuration.md#reposyaml) for format.
 
 Use `core setup` to clone all repos from the registry.
 
diff --git a/docs/cmd/index.md b/docs/cmd/index.md
index d6d6430e..fce31835 100644
--- a/docs/cmd/index.md
+++ b/docs/cmd/index.md
@@ -23,7 +23,9 @@ Unified interface for Go/PHP development, multi-repo management, and deployment.
 ## Installation
 
 ```bash
-core go install
+go install github.com/host-uk/core/cmd/core@latest
 ```
 
 Verify: `core doctor`
+
+See [Getting Started](../getting-started.md) for all installation options.
diff --git a/docs/cmd/setup/index.md b/docs/cmd/setup/index.md
index b46c5eaa..d07121f6 100644
--- a/docs/cmd/setup/index.md
+++ b/docs/cmd/setup/index.md
@@ -191,16 +191,17 @@ Core looks for `repos.yaml` in:
 
 ```bash
 # Check workspace health
-core health
+core dev health
 
 # Full workflow (status + commit + push)
-core work
+core dev work
 
 # Build the project
 core build
 
 # Run tests
-core test
+core go test    # Go projects
+core php test   # PHP projects
 ```
 
 ---
diff --git a/docs/configuration.md b/docs/configuration.md
index 84e79011..deabb687 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -205,14 +205,148 @@ files:
         port: 8080
 ```
 
+## repos.yaml
+
+Package registry for multi-repo workspaces:
+
+```yaml
+# Organisation name (used for GitHub URLs)
+org: host-uk
+
+# Base path for cloning (default: current directory)
+base_path: .
+
+# Default settings for all repos
+defaults:
+  ci: github
+  license: EUPL-1.2
+  branch: main
+
+# Repository definitions
+repos:
+  # Foundation packages (no dependencies)
+  core-php:
+    type: foundation
+    description: Foundation framework
+
+  core-devops:
+    type: foundation
+    description: Development environment
+    clone: false  # Skip during setup (already exists)
+
+  # Module packages (depend on foundation)
+  core-tenant:
+    type: module
+    depends_on: [core-php]
+    description: Multi-tenancy module
+
+  core-admin:
+    type: module
+    depends_on: [core-php, core-tenant]
+    description: Admin panel
+
+  core-api:
+    type: module
+    depends_on: [core-php]
+    description: REST API framework
+
+  # Product packages (user-facing applications)
+  core-bio:
+    type: product
+    depends_on: [core-php, core-tenant]
+    description: Link-in-bio product
+    domain: bio.host.uk.com
+
+  core-social:
+    type: product
+    depends_on: [core-php, core-tenant]
+    description: Social scheduling
+    domain: social.host.uk.com
+
+  # Templates
+  core-template:
+    type: template
+    description: Starter template for new projects
+```
+
+### repos.yaml Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `org` | Yes | GitHub organisation name |
+| `base_path` | No | Directory for cloning (default: `.`) |
+| `defaults` | No | Default settings applied to all repos |
+| `repos` | Yes | Map of repository definitions |
+
+### Repository Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `type` | Yes | `foundation`, `module`, `product`, or `template` |
+| `description` | No | Human-readable description |
+| `depends_on` | No | List of package dependencies |
+| `clone` | No | Set `false` to skip during setup |
+| `domain` | No | Production domain (for products) |
+| `branch` | No | Override default branch |
+
+### Package Types
+
+| Type | Description | Dependencies |
+|------|-------------|--------------|
+| `foundation` | Core framework packages | None |
+| `module` | Reusable modules | Foundation packages |
+| `product` | User-facing applications | Foundation + modules |
+| `template` | Starter templates | Any |
+
+---
+
 ## Environment Variables
 
+Complete reference of environment variables used by Core CLI.
+
+### Authentication
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `GITHUB_TOKEN` | `core ci`, `core dev` | GitHub API authentication |
+| `ANTHROPIC_API_KEY` | `core ai`, `core dev claude` | Claude API key |
+| `AGENTIC_TOKEN` | `core ai task*` | Agentic API authentication |
+| `AGENTIC_BASE_URL` | `core ai task*` | Agentic API endpoint |
+
+### Publishing
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `NPM_TOKEN` | `core ci` (npm publisher) | npm registry auth token |
+| `CHOCOLATEY_API_KEY` | `core ci` (chocolatey publisher) | Chocolatey API key |
+| `DOCKER_USERNAME` | `core ci` (docker publisher) | Docker registry username |
+| `DOCKER_PASSWORD` | `core ci` (docker publisher) | Docker registry password |
+
+### Deployment
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `COOLIFY_URL` | `core php deploy` | Coolify server URL |
+| `COOLIFY_TOKEN` | `core php deploy` | Coolify API token |
+| `COOLIFY_APP_ID` | `core php deploy` | Production application ID |
+| `COOLIFY_STAGING_APP_ID` | `core php deploy --staging` | Staging application ID |
+
+### Build
+
+| Variable | Used By | Description |
+|----------|---------|-------------|
+| `CGO_ENABLED` | `core build`, `core go *` | Enable/disable CGO (default: 0) |
+| `GOOS` | `core build` | Target operating system |
+| `GOARCH` | `core build` | Target architecture |
+
+### Configuration Paths
+
 | Variable | Description |
 |----------|-------------|
-| `GITHUB_TOKEN` | GitHub authentication (via gh CLI) |
-| `NPM_TOKEN` | npm publish token |
-| `CHOCOLATEY_API_KEY` | Chocolatey publish key |
-| `COOLIFY_TOKEN` | Coolify deployment token |
+| `CORE_CONFIG` | Override config directory (default: `~/.core/`) |
+| `CORE_REGISTRY` | Override repos.yaml path |
+
+---
 
 ## Defaults
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 00000000..ad374abf
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,191 @@
+# Getting Started
+
+This guide walks you through installing Core and running your first build.
+
+## Prerequisites
+
+Before installing Core, ensure you have:
+
+| Tool | Minimum Version | Check Command |
+|------|-----------------|---------------|
+| Go | 1.23+ | `go version` |
+| Git | 2.30+ | `git --version` |
+
+Optional (for specific features):
+
+| Tool | Required For | Install |
+|------|--------------|---------|
+| `gh` | GitHub integration (`core dev issues`, `core dev reviews`) | [cli.github.com](https://cli.github.com) |
+| Docker | Container builds | [docker.com](https://docker.com) |
+| `task` | Task automation | `go install github.com/go-task/task/v3/cmd/task@latest` |
+
+## Installation
+
+### Option 1: Go Install (Recommended)
+
+```bash
+# Install latest release
+go install github.com/host-uk/core/cmd/core@latest
+
+# Verify installation
+core doctor
+```
+
+If `core: command not found`, add Go's bin directory to your PATH:
+
+```bash
+export PATH="$PATH:$(go env GOPATH)/bin"
+```
+
+### Option 2: Download Binary
+
+Download pre-built binaries from [GitHub Releases](https://github.com/host-uk/core/releases):
+
+```bash
+# macOS (Apple Silicon)
+curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-darwin-arm64
+chmod +x core
+sudo mv core /usr/local/bin/
+
+# macOS (Intel)
+curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-darwin-amd64
+chmod +x core
+sudo mv core /usr/local/bin/
+
+# Linux (x86_64)
+curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-linux-amd64
+chmod +x core
+sudo mv core /usr/local/bin/
+```
+
+### Option 3: Build from Source
+
+```bash
+# Clone repository
+git clone https://github.com/host-uk/core.git
+cd core
+
+# Build with Task (recommended)
+task cli:build
+# Binary at ./bin/core
+
+# Or build with Go directly
+CGO_ENABLED=0 go build -o core ./cmd/core/
+sudo mv core /usr/local/bin/
+```
+
+## Your First Build
+
+### 1. Navigate to a Go Project
+
+```bash
+cd ~/Code/my-go-project
+```
+
+### 2. Initialise Configuration
+
+```bash
+core setup
+```
+
+This detects your project type and creates configuration files in `.core/`:
+- `build.yaml` - Build settings
+- `release.yaml` - Release configuration
+- `test.yaml` - Test commands
+
+### 3. Build
+
+```bash
+core build
+```
+
+Output appears in `dist/`:
+
+```
+dist/
+├── my-project-darwin-arm64.tar.gz
+├── my-project-linux-amd64.tar.gz
+└── CHECKSUMS.txt
+```
+
+### 4. Cross-Compile (Optional)
+
+```bash
+core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64
+```
+
+## Your First Release
+
+Releases are **safe by default** - Core runs in dry-run mode unless you explicitly confirm.
+
+### 1. Preview
+
+```bash
+core ci
+```
+
+This shows what would be published without actually publishing.
+
+### 2. Publish
+
+```bash
+core ci --we-are-go-for-launch
+```
+
+This creates a GitHub release with your built artifacts.
+
+## Multi-Repo Workflow
+
+If you work with multiple repositories (like the host-uk ecosystem):
+
+### 1. Clone All Repositories
+
+```bash
+mkdir host-uk && cd host-uk
+core setup
+```
+
+Select packages in the interactive wizard.
+
+### 2. Check Status
+
+```bash
+core dev health
+# Output: "18 repos │ clean │ synced"
+```
+
+### 3. Work Across Repos
+
+```bash
+core dev work --status    # See status table
+core dev work             # Commit and push all dirty repos
+```
+
+## Next Steps
+
+| Task | Command | Documentation |
+|------|---------|---------------|
+| Run tests | `core go test` | [go/test](cmd/go/test/) |
+| Format code | `core go fmt --fix` | [go/fmt](cmd/go/fmt/) |
+| Lint code | `core go lint` | [go/lint](cmd/go/lint/) |
+| PHP development | `core php dev` | [php](cmd/php/) |
+| View all commands | `core --help` | [cmd](cmd/) |
+
+## Getting Help
+
+```bash
+# Check environment
+core doctor
+
+# Command help
+core <command> --help
+
+# Full documentation
+https://github.com/host-uk/core/tree/main/docs
+```
+
+## See Also
+
+- [Configuration](configuration.md) - All config options
+- [Workflows](workflows.md) - Common task sequences
+- [Troubleshooting](troubleshooting.md) - When things go wrong
diff --git a/docs/glossary.md b/docs/glossary.md
new file mode 100644
index 00000000..ea9d280f
--- /dev/null
+++ b/docs/glossary.md
@@ -0,0 +1,112 @@
+# Glossary
+
+Definitions of terms used throughout Core CLI documentation.
+
+## A
+
+### Artifact
+A file produced by a build, typically a binary, archive, or checksum file. Artifacts are stored in the `dist/` directory and published during releases.
+
+## C
+
+### CGO
+Go's mechanism for calling C code. Core disables CGO by default (`CGO_ENABLED=0`) to produce statically-linked binaries that don't depend on system libraries.
+
+### Changelog
+Automatically generated list of changes between releases, created from conventional commit messages. Configure in `.core/release.yaml`.
+
+### Conventional Commits
+A commit message format: `type(scope): description`. Types include `feat`, `fix`, `docs`, `chore`. Core uses this to generate changelogs.
+
+## D
+
+### Dry-run
+A mode where commands show what they would do without actually doing it. `core ci` runs in dry-run mode by default for safety.
+
+## F
+
+### Foundation Package
+A core package with no dependencies on other packages. Examples: `core-php`, `core-devops`. These form the base of the dependency tree.
+
+### FrankenPHP
+A modern PHP application server used by `core php dev`. Combines PHP with Caddy for high-performance serving.
+
+## G
+
+### `gh`
+The GitHub CLI tool. Required for commands that interact with GitHub: `core dev issues`, `core dev reviews`, `core dev ci`.
+
+## L
+
+### LinuxKit
+A toolkit for building lightweight, immutable Linux distributions. Core can build LinuxKit images via `core build --type linuxkit`.
+
+## M
+
+### Module (Go)
+A collection of Go packages with a `go.mod` file. Core's Go commands operate on modules.
+
+### Module (Package)
+A host-uk package that depends on foundation packages. Examples: `core-tenant`, `core-admin`. Compare with **Foundation Package** and **Product**.
+
+## P
+
+### Package
+An individual repository in the host-uk ecosystem. Packages are defined in `repos.yaml` and managed with `core pkg` commands.
+
+### Package Index
+The `repos.yaml` file that lists all packages in a workspace. Contains metadata like dependencies, type, and description.
+
+### Product
+A user-facing application package. Examples: `core-bio`, `core-social`. Products depend on foundation and module packages.
+
+### Publisher
+A release target configured in `.core/release.yaml`. Types include `github`, `docker`, `npm`, `homebrew`, `linuxkit`.
+
+## R
+
+### Registry (Docker/npm)
+A remote repository for container images or npm packages. Core can publish to registries during releases.
+
+### `repos.yaml`
+The package index file defining all repositories in a workspace. Used by multi-repo commands like `core dev work`.
+
+## S
+
+### SDK
+Software Development Kit. Core can generate API client SDKs from OpenAPI specs via `core build sdk`.
+
+## T
+
+### Target
+A build target specified as `os/arch`, e.g., `linux/amd64`, `darwin/arm64`. Use `--targets` flag to specify.
+
+## W
+
+### Wails
+A framework for building desktop applications with Go backends and web frontends. Core detects Wails projects and uses appropriate build commands.
+
+### Workspace (Go)
+A Go 1.18+ feature for working with multiple modules simultaneously. Managed via `core go work` commands.
+
+### Workspace (Multi-repo)
+A directory containing multiple packages from `repos.yaml`. Created via `core setup` and managed with `core dev` commands.
+
+## Symbols
+
+### `.core/`
+Directory containing project configuration files:
+- `build.yaml` - Build settings
+- `release.yaml` - Release targets
+- `test.yaml` - Test configuration
+- `linuxkit/` - LinuxKit templates
+
+### `--we-are-go-for-launch`
+Flag to disable dry-run mode and actually publish a release. Named as a deliberate friction to prevent accidental releases.
+
+---
+
+## See Also
+
+- [Configuration](configuration.md) - Config file reference
+- [Getting Started](getting-started.md) - First-time setup
diff --git a/docs/index.md b/docs/index.md
index 6df3d5f9..83f647e8 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,14 +5,18 @@ Core is a unified CLI for the host-uk ecosystem - build, release, and deploy Go,
 ## Installation
 
 ```bash
-# From any Go project
-core go install github.com/host-uk/core/cmd/core
-
-# Or standard go install
+# Via Go (recommended)
 go install github.com/host-uk/core/cmd/core@latest
+
+# Or download binary from releases
+curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-$(go env GOOS)-$(go env GOARCH)
+chmod +x core && sudo mv core /usr/local/bin/
+
+# Verify
+core doctor
 ```
 
-Verify: `core doctor`
+See [Getting Started](getting-started.md) for all installation options including building from source.
 
 ## Command Reference
 
@@ -47,7 +51,7 @@ core build --targets linux/amd64,darwin/arm64
 
 # Release (dry-run by default)
 core ci                   # Preview release
-core ci --were-go-for-launch  # Actually publish
+core ci --we-are-go-for-launch  # Actually publish
 
 # Multi-repo workflow
 core dev work             # Status + commit + push
@@ -71,10 +75,17 @@ Core uses `.core/` directory for project configuration:
 
 And `repos.yaml` in workspace root for multi-repo management.
 
+## Guides
+
+- [Getting Started](getting-started.md) - Installation and first steps
+- [Workflows](workflows.md) - Common task sequences
+- [Troubleshooting](troubleshooting.md) - When things go wrong
+- [Migration](migration.md) - Moving from legacy tools
+
 ## Reference
 
 - [Configuration](configuration.md) - All config options
-- [Examples](examples/) - Sample configurations
+- [Glossary](glossary.md) - Term definitions
 
 ## Claude Code Skill
 
diff --git a/docs/migration.md b/docs/migration.md
new file mode 100644
index 00000000..e5c46069
--- /dev/null
+++ b/docs/migration.md
@@ -0,0 +1,233 @@
+# Migration Guide
+
+Migrating from legacy scripts and tools to Core CLI.
+
+## From push-all.sh
+
+The `push-all.sh` script has been replaced by `core dev` commands.
+
+| Legacy | Core CLI | Notes |
+|--------|----------|-------|
+| `./push-all.sh --status` | `core dev work --status` | Status table |
+| `./push-all.sh --commit` | `core dev commit` | Commit dirty repos |
+| `./push-all.sh` | `core dev work` | Full workflow |
+
+### Quick Migration
+
+```bash
+# Instead of
+./push-all.sh --status
+
+# Use
+core dev work --status
+```
+
+### New Features
+
+Core CLI adds features not available in the legacy script:
+
+```bash
+# Quick health summary
+core dev health
+# Output: "18 repos │ clean │ synced"
+
+# Pull repos that are behind
+core dev pull
+
+# GitHub integration
+core dev issues      # List open issues
+core dev reviews     # List PRs needing review
+core dev ci          # Check CI status
+
+# Dependency analysis
+core dev impact core-php  # What depends on core-php?
+```
+
+---
+
+## From Raw Go Commands
+
+Core wraps Go commands with enhanced defaults and output.
+
+| Raw Command | Core CLI | Benefits |
+|-------------|----------|----------|
+| `go test ./...` | `core go test` | Filters warnings, sets CGO_ENABLED=0 |
+| `go test -coverprofile=...` | `core go cov` | HTML reports, thresholds |
+| `gofmt -w .` | `core go fmt --fix` | Uses goimports if available |
+| `golangci-lint run` | `core go lint` | Consistent interface |
+| `go build` | `core build` | Cross-compile, sign, archive |
+
+### Why Use Core?
+
+```bash
+# Raw go test shows linker warnings on macOS
+go test ./...
+# ld: warning: -no_pie is deprecated...
+
+# Core filters noise
+core go test
+# PASS (clean output)
+```
+
+### Environment Setup
+
+Core automatically sets:
+- `CGO_ENABLED=0` - Static binaries
+- `MACOSX_DEPLOYMENT_TARGET=26.0` - Suppress macOS warnings
+- Colour output for coverage reports
+
+---
+
+## From Raw PHP Commands
+
+Core orchestrates Laravel development services.
+
+| Raw Command | Core CLI | Benefits |
+|-------------|----------|----------|
+| `php artisan serve` | `core php dev` | Adds Vite, Horizon, Reverb, Redis |
+| `./vendor/bin/pest` | `core php test` | Auto-detects test runner |
+| `./vendor/bin/pint` | `core php fmt --fix` | Consistent interface |
+| Manual Coolify deploy | `core php deploy` | Tracked, scriptable |
+
+### Development Server Comparison
+
+```bash
+# Raw: Start each service manually
+php artisan serve &
+npm run dev &
+php artisan horizon &
+php artisan reverb:start &
+
+# Core: One command
+core php dev
+# Starts all services, shows unified logs
+```
+
+---
+
+## From goreleaser
+
+Core's release system is simpler than goreleaser for host-uk projects.
+
+| goreleaser | Core CLI |
+|------------|----------|
+| `.goreleaser.yaml` | `.core/release.yaml` |
+| `goreleaser release --snapshot` | `core ci` (dry-run) |
+| `goreleaser release` | `core ci --we-are-go-for-launch` |
+
+### Configuration Migration
+
+**goreleaser:**
+```yaml
+builds:
+  - main: ./cmd/app
+    goos: [linux, darwin, windows]
+    goarch: [amd64, arm64]
+
+archives:
+  - format: tar.gz
+    files: [LICENSE, README.md]
+
+release:
+  github:
+    owner: host-uk
+    name: app
+```
+
+**Core:**
+```yaml
+version: 1
+
+project:
+  name: app
+  repository: host-uk/app
+
+targets:
+  - os: linux
+    arch: amd64
+  - os: darwin
+    arch: arm64
+
+publishers:
+  - type: github
+```
+
+### Key Differences
+
+1. **Separate build and release** - Core separates `core build` from `core ci`
+2. **Safe by default** - `core ci` is dry-run unless `--we-are-go-for-launch`
+3. **Simpler config** - Fewer options, sensible defaults
+
+---
+
+## From Manual Git Operations
+
+Core automates multi-repo git workflows.
+
+| Manual | Core CLI |
+|--------|----------|
+| `cd repo1 && git status && cd ../repo2 && ...` | `core dev work --status` |
+| Check each repo for uncommitted changes | `core dev health` |
+| Commit each repo individually | `core dev commit` |
+| Push each repo individually | `core dev push` |
+
+### Example: Committing Across Repos
+
+**Manual:**
+```bash
+cd core-php
+git add -A
+git commit -m "feat: add feature"
+cd ../core-tenant
+git add -A
+git commit -m "feat: use new feature"
+# ... repeat for each repo
+```
+
+**Core:**
+```bash
+core dev commit
+# Interactive: reviews changes, suggests messages
+# Adds Co-Authored-By automatically
+```
+
+---
+
+## Deprecated Commands
+
+These commands have been removed or renamed:
+
+| Deprecated | Replacement | Version |
+|------------|-------------|---------|
+| `core sdk generate` | `core build sdk` | v0.5.0 |
+| `core dev task*` | `core ai task*` | v0.8.0 |
+| `core release` | `core ci` | v0.6.0 |
+
+---
+
+## Version Compatibility
+
+| Core Version | Go Version | Breaking Changes |
+|--------------|------------|------------------|
+| v1.0.0+ | 1.23+ | Stable API |
+| v0.8.0 | 1.22+ | Task commands moved to `ai` |
+| v0.6.0 | 1.22+ | Release command renamed to `ci` |
+| v0.5.0 | 1.21+ | SDK generation moved to `build sdk` |
+
+---
+
+## Getting Help
+
+If you encounter issues during migration:
+
+1. Check [Troubleshooting](troubleshooting.md)
+2. Run `core doctor` to verify setup
+3. Use `--help` on any command: `core dev work --help`
+
+---
+
+## See Also
+
+- [Getting Started](getting-started.md) - Fresh installation
+- [Workflows](workflows.md) - Common task sequences
+- [Configuration](configuration.md) - Config file reference
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 00000000..c075f3a8
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,332 @@
+# Troubleshooting
+
+Common issues and how to resolve them.
+
+## Installation Issues
+
+### "command not found: core"
+
+**Cause:** Go's bin directory is not in your PATH.
+
+**Fix:**
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export PATH="$PATH:$(go env GOPATH)/bin"
+
+# Then reload
+source ~/.bashrc  # or ~/.zshrc
+```
+
+### "go: module github.com/host-uk/core: no matching versions"
+
+**Cause:** Go module proxy hasn't cached the latest version yet.
+
+**Fix:**
+
+```bash
+# Bypass proxy
+GOPROXY=direct go install github.com/host-uk/core/cmd/core@latest
+```
+
+---
+
+## Build Issues
+
+### "no Go files in..."
+
+**Cause:** Core couldn't find a main package to build.
+
+**Fix:**
+
+1. Check you're in the correct directory
+2. Ensure `.core/build.yaml` has the correct `main` path:
+
+```yaml
+project:
+  main: ./cmd/myapp  # Path to main package
+```
+
+### "CGO_ENABLED=1 but no C compiler"
+
+**Cause:** Build requires CGO but no C compiler is available.
+
+**Fix:**
+
+```bash
+# Option 1: Disable CGO (if not needed)
+core build  # Core disables CGO by default
+
+# Option 2: Install a C compiler
+# macOS
+xcode-select --install
+
+# Ubuntu/Debian
+sudo apt install build-essential
+
+# Windows
+# Install MinGW or use WSL
+```
+
+### Build succeeds but binary doesn't run
+
+**Cause:** Built for wrong architecture.
+
+**Fix:**
+
+```bash
+# Check what you built
+file dist/myapp-*
+
+# Build for your current platform
+core build --targets $(go env GOOS)/$(go env GOARCH)
+```
+
+---
+
+## Release Issues
+
+### "dry-run mode, use --we-are-go-for-launch to publish"
+
+**This is expected behaviour.** Core runs in dry-run mode by default for safety.
+
+**To actually publish:**
+
+```bash
+core ci --we-are-go-for-launch
+```
+
+### "failed to create release: 401 Unauthorized"
+
+**Cause:** GitHub token missing or invalid.
+
+**Fix:**
+
+```bash
+# Authenticate with GitHub CLI
+gh auth login
+
+# Or set token directly
+export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
+```
+
+### "no artifacts found in dist/"
+
+**Cause:** You need to build before releasing.
+
+**Fix:**
+
+```bash
+# Build first
+core build
+
+# Then release
+core ci --we-are-go-for-launch
+```
+
+### "tag already exists"
+
+**Cause:** Trying to release a version that's already been released.
+
+**Fix:**
+
+1. Update version in your code/config
+2. Or delete the existing tag (if intentional):
+
+```bash
+git tag -d v1.0.0
+git push origin :refs/tags/v1.0.0
+```
+
+---
+
+## Multi-Repo Issues
+
+### "repos.yaml not found"
+
+**Cause:** Core can't find the package registry.
+
+**Fix:**
+
+Core looks for `repos.yaml` in:
+1. Current directory
+2. Parent directories (walking up to root)
+3. `~/Code/host-uk/repos.yaml`
+4. `~/.config/core/repos.yaml`
+
+Either:
+- Run commands from a directory with `repos.yaml`
+- Use `--registry /path/to/repos.yaml`
+- Run `core setup` to bootstrap a new workspace
+
+### "failed to clone: Permission denied (publickey)"
+
+**Cause:** SSH key not configured for GitHub.
+
+**Fix:**
+
+```bash
+# Check SSH connection
+ssh -T git@github.com
+
+# If that fails, add your key
+ssh-add ~/.ssh/id_ed25519
+
+# Or configure SSH
+# See: https://docs.github.com/en/authentication/connecting-to-github-with-ssh
+```
+
+### "repository not found" during setup
+
+**Cause:** You don't have access to the repository, or it doesn't exist.
+
+**Fix:**
+
+1. Check you're authenticated: `gh auth status`
+2. Verify the repo exists and you have access
+3. For private repos, ensure your token has `repo` scope
+
+---
+
+## GitHub Integration Issues
+
+### "gh: command not found"
+
+**Cause:** GitHub CLI not installed.
+
+**Fix:**
+
+```bash
+# macOS
+brew install gh
+
+# Ubuntu/Debian
+sudo apt install gh
+
+# Windows
+winget install GitHub.cli
+
+# Then authenticate
+gh auth login
+```
+
+### "core dev issues" shows nothing
+
+**Possible causes:**
+
+1. No open issues exist
+2. Not authenticated with GitHub
+3. Not in a directory with `repos.yaml`
+
+**Fix:**
+
+```bash
+# Check auth
+gh auth status
+
+# Check you're in a workspace
+ls repos.yaml
+
+# Show all issues including closed
+core dev issues --all
+```
+
+---
+
+## PHP Issues
+
+### "frankenphp: command not found"
+
+**Cause:** FrankenPHP not installed.
+
+**Fix:**
+
+```bash
+# macOS
+brew install frankenphp
+
+# Or use Docker
+core php dev --docker
+```
+
+### "core php dev" exits immediately
+
+**Cause:** Usually a port conflict or missing dependency.
+
+**Fix:**
+
+```bash
+# Check if port 8000 is in use
+lsof -i :8000
+
+# Try a different port
+core php dev --port 9000
+
+# Check logs for errors
+core php logs
+```
+
+---
+
+## Performance Issues
+
+### Commands are slow
+
+**Possible causes:**
+
+1. Large number of repositories
+2. Network latency to GitHub
+3. Go module downloads
+
+**Fix:**
+
+```bash
+# For multi-repo commands, use health for quick check
+core dev health  # Fast summary
+
+# Instead of
+core dev work --status  # Full table (slower)
+
+# Pre-download Go modules
+go mod download
+```
+
+---
+
+## Getting More Help
+
+### Enable Verbose Output
+
+Most commands support `-v` or `--verbose`:
+
+```bash
+core build -v
+core go test -v
+```
+
+### Check Environment
+
+```bash
+core doctor
+```
+
+This verifies all required tools are installed and configured.
+
+### Report Issues
+
+If you've found a bug:
+
+1. Check existing issues: https://github.com/host-uk/core/issues
+2. Create a new issue with:
+   - Core version (`core --version`)
+   - OS and architecture (`go env GOOS GOARCH`)
+   - Command that failed
+   - Full error output
+
+---
+
+## See Also
+
+- [Getting Started](getting-started.md) - Installation and first steps
+- [Configuration](configuration.md) - Config file reference
+- [doctor](cmd/doctor/) - Environment verification
diff --git a/docs/workflows.md b/docs/workflows.md
new file mode 100644
index 00000000..96b0c9f7
--- /dev/null
+++ b/docs/workflows.md
@@ -0,0 +1,334 @@
+# Workflows
+
+Common end-to-end workflows for Core CLI.
+
+## Go Project: Build and Release
+
+Complete workflow from code to GitHub release.
+
+```bash
+# 1. Run tests
+core go test
+
+# 2. Check coverage
+core go cov --threshold 80
+
+# 3. Format and lint
+core go fmt --fix
+core go lint
+
+# 4. Build for all platforms
+core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64
+
+# 5. Preview release (dry-run)
+core ci
+
+# 6. Publish
+core ci --we-are-go-for-launch
+```
+
+**Output structure:**
+
+```
+dist/
+├── myapp-darwin-arm64.tar.gz
+├── myapp-linux-amd64.tar.gz
+├── myapp-linux-arm64.tar.gz
+├── myapp-windows-amd64.zip
+└── CHECKSUMS.txt
+```
+
+---
+
+## PHP Project: Development to Deployment
+
+Local development through to production deployment.
+
+```bash
+# 1. Start development environment
+core php dev
+
+# 2. Run tests (in another terminal)
+core php test --parallel
+
+# 3. Check code quality
+core php fmt --fix
+core php analyse
+
+# 4. Deploy to staging
+core php deploy --staging --wait
+
+# 5. Verify staging
+# (manual testing)
+
+# 6. Deploy to production
+core php deploy --wait
+
+# 7. Monitor
+core php deploy:status
+```
+
+**Rollback if needed:**
+
+```bash
+core php deploy:rollback
+```
+
+---
+
+## Multi-Repo: Daily Workflow
+
+Working across the host-uk monorepo.
+
+### Morning: Sync Everything
+
+```bash
+# Quick health check
+core dev health
+
+# Pull all repos that are behind
+core dev pull --all
+
+# Check for issues assigned to you
+core dev issues --assignee @me
+```
+
+### During Development
+
+```bash
+# Work on code...
+
+# Check status across all repos
+core dev work --status
+
+# Commit changes (Claude-assisted messages)
+core dev commit
+
+# Push when ready
+core dev push
+```
+
+### End of Day
+
+```bash
+# Full workflow: status → commit → push
+core dev work
+
+# Check CI status
+core dev ci
+
+# Review any failed builds
+core dev ci --failed
+```
+
+---
+
+## New Developer: Environment Setup
+
+First-time setup for a new team member.
+
+```bash
+# 1. Verify prerequisites
+core doctor
+
+# 2. Create workspace directory
+mkdir ~/Code/host-uk && cd ~/Code/host-uk
+
+# 3. Bootstrap workspace (interactive)
+core setup
+
+# 4. Select packages in wizard
+# Use arrow keys, space to select, enter to confirm
+
+# 5. Verify setup
+core dev health
+
+# 6. Start working
+core dev work --status
+```
+
+---
+
+## CI Pipeline: Automated Build
+
+Example GitHub Actions workflow.
+
+```yaml
+# .github/workflows/release.yml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+
+      - name: Install Core
+        run: go install github.com/host-uk/core/cmd/core@latest
+
+      - name: Build
+        run: core build --ci
+
+      - name: Release
+        run: core ci --we-are-go-for-launch
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+---
+
+## SDK Generation: API Client Updates
+
+Generate SDK clients when API changes.
+
+```bash
+# 1. Validate OpenAPI spec
+core sdk validate
+
+# 2. Check for breaking changes
+core sdk diff --base v1.0.0
+
+# 3. Generate SDKs
+core build sdk
+
+# 4. Review generated code
+git diff
+
+# 5. Commit if satisfied
+git add -A && git commit -m "chore: regenerate SDK clients"
+```
+
+---
+
+## Dependency Update: Cross-Repo Change
+
+When updating a shared package like `core-php`.
+
+```bash
+# 1. Make changes in core-php
+cd ~/Code/host-uk/core-php
+# ... edit code ...
+
+# 2. Run tests
+core go test  # or core php test
+
+# 3. Check what depends on core-php
+core dev impact core-php
+
+# Output:
+# core-tenant (direct)
+# core-admin (via core-tenant)
+# core-api (direct)
+# ...
+
+# 4. Commit core-php changes
+core dev commit
+
+# 5. Update dependent packages
+cd ~/Code/host-uk
+for pkg in core-tenant core-admin core-api; do
+  cd $pkg
+  composer update host-uk/core-php
+  core php test
+  cd ..
+done
+
+# 6. Commit all updates
+core dev work
+```
+
+---
+
+## Hotfix: Emergency Production Fix
+
+Fast path for critical fixes.
+
+```bash
+# 1. Create hotfix branch
+git checkout -b hotfix/critical-bug main
+
+# 2. Make fix
+# ... edit code ...
+
+# 3. Test
+core go test --run TestCriticalPath
+
+# 4. Build
+core build
+
+# 5. Preview release
+core ci --prerelease
+
+# 6. Publish hotfix
+core ci --we-are-go-for-launch --prerelease
+
+# 7. Merge back to main
+git checkout main
+git merge hotfix/critical-bug
+git push
+```
+
+---
+
+## Documentation: Sync Across Repos
+
+Keep documentation synchronised.
+
+```bash
+# 1. List all docs
+core docs list
+
+# 2. Sync to central location
+core docs sync --output ./docs-site
+
+# 3. Review changes
+git diff docs-site/
+
+# 4. Commit
+git add docs-site/
+git commit -m "docs: sync from packages"
+```
+
+---
+
+## Troubleshooting: Failed Build
+
+When a build fails.
+
+```bash
+# 1. Check environment
+core doctor
+
+# 2. Clean previous artifacts
+rm -rf dist/
+
+# 3. Verbose build
+core build -v
+
+# 4. If Go-specific issues
+core go mod tidy
+core go mod verify
+
+# 5. Check for test failures
+core go test -v
+
+# 6. Review configuration
+cat .core/build.yaml
+```
+
+---
+
+## See Also
+
+- [Getting Started](getting-started.md) - First-time setup
+- [Troubleshooting](troubleshooting.md) - When things go wrong
+- [Configuration](configuration.md) - Config file reference