docs: add example.md files for all CLI commands

Each command directory now has both index.md (reference) and
example.md (usage examples and configuration samples).

Also adds exception for docs/cmd/build in .gitignore.

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

.gitignore

@@ -2,6 +2,7 @@ wails3
 build/
 !pkg/build
 !cmd/core-gui/build
+!docs/cmd/build
 cmd/core-gui/build/bin
 .task
 vendor/

docs/cmd/build/example.md

@@ -0,0 +1,83 @@
+# Build Examples
+
+## Quick Start
+
+```bash
+# Auto-detect and build
+core build
+
+# Build for specific platforms
+core build --targets linux/amd64,darwin/arm64
+
+# CI mode
+core build --ci
+```
+
+## Configuration
+
+`.core/build.yaml`:
+
+```yaml
+version: 1
+
+project:
+  name: myapp
+  binary: myapp
+
+build:
+  main: ./cmd/myapp
+  ldflags:
+    - -s -w
+    - -X main.version={{.Version}}
+
+targets:
+  - os: linux
+    arch: amd64
+  - os: linux
+    arch: arm64
+  - os: darwin
+    arch: arm64
+```
+
+## Cross-Platform Build
+
+```bash
+core build --targets linux/amd64,linux/arm64,darwin/arm64,windows/amd64
+```
+
+Output:
+```
+dist/
+├── myapp-linux-amd64.tar.gz
+├── myapp-linux-arm64.tar.gz
+├── myapp-darwin-arm64.tar.gz
+├── myapp-windows-amd64.zip
+└── CHECKSUMS.txt
+```
+
+## Code Signing
+
+```yaml
+sign:
+  enabled: true
+  gpg:
+    key: $GPG_KEY_ID
+  macos:
+    identity: "Developer ID Application: Your Name (TEAM_ID)"
+    notarize: true
+    apple_id: $APPLE_ID
+    team_id: $APPLE_TEAM_ID
+    app_password: $APPLE_APP_PASSWORD
+```
+
+## Docker Build
+
+```bash
+core build --type docker --image ghcr.io/myorg/myapp
+```
+
+## Wails Desktop App
+
+```bash
+core build --type wails --targets darwin/arm64,windows/amd64
+```

docs/cmd/build/index.md

@@ -0,0 +1,177 @@
+# core build
+
+Build Go, Wails, Docker, and LinuxKit projects with automatic project detection.
+
+## Subcommands
+
+| Command | Description |
+|---------|-------------|
+| [sdk](sdk/) | Generate API SDKs from OpenAPI |
+
+## Usage
+
+```bash
+core build [flags]
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--type` | Project type: `go`, `wails`, `docker`, `linuxkit` (auto-detected) |
+| `--targets` | Build targets: `linux/amd64,darwin/arm64,windows/amd64` |
+| `--output` | Output directory (default: `dist`) |
+| `--ci` | CI mode - non-interactive, fail fast |
+| `--image` | Docker image name (for docker builds) |
+| `--no-sign` | Skip code signing |
+| `--notarize` | Enable macOS notarization (requires Apple credentials) |
+
+## Examples
+
+### Go Project
+
+```bash
+# Auto-detect and build
+core build
+
+# Build for specific platforms
+core build --targets linux/amd64,linux/arm64,darwin/arm64
+
+# CI mode
+core build --ci
+```
+
+### Wails Project
+
+```bash
+# Build Wails desktop app
+core build --type wails
+
+# Build for all desktop platforms
+core build --type wails --targets darwin/amd64,darwin/arm64,windows/amd64,linux/amd64
+```
+
+### Docker Image
+
+```bash
+# Build Docker image
+core build --type docker
+
+# With custom image name
+core build --type docker --image ghcr.io/myorg/myapp
+```
+
+### LinuxKit Image
+
+```bash
+# Build LinuxKit ISO
+core build --type linuxkit
+```
+
+## Project Detection
+
+Core automatically detects project type based on files:
+
+| Files | Type |
+|-------|------|
+| `wails.json` | Wails |
+| `go.mod` | Go |
+| `Dockerfile` | Docker |
+| `composer.json` | PHP |
+| `package.json` | Node |
+
+## Output
+
+Build artifacts are placed in `dist/` by default:
+
+```
+dist/
+├── myapp-linux-amd64.tar.gz
+├── myapp-linux-arm64.tar.gz
+├── myapp-darwin-amd64.tar.gz
+├── myapp-darwin-arm64.tar.gz
+├── myapp-windows-amd64.zip
+└── CHECKSUMS.txt
+```
+
+## Configuration
+
+Optional `.core/build.yaml`:
+
+```yaml
+version: 1
+
+project:
+  name: myapp
+  binary: myapp
+
+build:
+  main: ./cmd/myapp
+  ldflags:
+    - -s -w
+    - -X main.version={{.Version}}
+
+targets:
+  - os: linux
+    arch: amd64
+  - os: linux
+    arch: arm64
+  - os: darwin
+    arch: arm64
+
+sign:
+  enabled: true
+  gpg:
+    key: $GPG_KEY_ID
+  macos:
+    identity: "Developer ID Application: Your Name (TEAM_ID)"
+    notarize: false
+    apple_id: $APPLE_ID
+    team_id: $APPLE_TEAM_ID
+    app_password: $APPLE_APP_PASSWORD
+```
+
+## Code Signing
+
+Core supports GPG signing for checksums and native code signing for macOS.
+
+### GPG Signing
+
+Signs `CHECKSUMS.txt` with a detached ASCII signature (`.asc`):
+
+```bash
+# Build with GPG signing (default if key configured)
+core build
+
+# Skip signing
+core build --no-sign
+```
+
+Users can verify:
+
+```bash
+gpg --verify CHECKSUMS.txt.asc CHECKSUMS.txt
+sha256sum -c CHECKSUMS.txt
+```
+
+### macOS Code Signing
+
+Signs Darwin binaries with your Developer ID and optionally notarizes with Apple:
+
+```bash
+# Build with codesign (automatic if identity configured)
+core build
+
+# Build with notarization (takes 1-5 minutes)
+core build --notarize
+```
+
+### Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `GPG_KEY_ID` | GPG key ID or fingerprint |
+| `CODESIGN_IDENTITY` | macOS Developer ID (fallback) |
+| `APPLE_ID` | Apple account email |
+| `APPLE_TEAM_ID` | Apple Developer Team ID |
+| `APPLE_APP_PASSWORD` | App-specific password for notarization |

docs/cmd/build/sdk/example.md

@@ -0,0 +1,56 @@
+# SDK Build Examples
+
+## Generate All SDKs
+
+```bash
+core build sdk
+```
+
+## Specific Language
+
+```bash
+core build sdk --lang typescript
+core build sdk --lang php
+core build sdk --lang go
+```
+
+## Custom Spec
+
+```bash
+core build sdk --spec ./api/openapi.yaml
+```
+
+## With Version
+
+```bash
+core build sdk --version v2.0.0
+```
+
+## Preview
+
+```bash
+core build sdk --dry-run
+```
+
+## Configuration
+
+`.core/sdk.yaml`:
+
+```yaml
+version: 1
+
+spec: ./api/openapi.yaml
+
+languages:
+  - name: typescript
+    output: sdk/typescript
+    package: "@myorg/api-client"
+
+  - name: php
+    output: sdk/php
+    namespace: MyOrg\ApiClient
+
+  - name: go
+    output: sdk/go
+    module: github.com/myorg/api-client-go
+```

docs/cmd/build/sdk/index.md

@@ -0,0 +1,27 @@
+# core build sdk
+
+Generate API SDKs from OpenAPI specifications.
+
+## Usage
+
+```bash
+core build sdk [flags]
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--spec` | Path to OpenAPI spec file |
+| `--lang` | Generate only this language |
+| `--version` | Version to embed |
+| `--dry-run` | Preview without generating |
+
+## Examples
+
+```bash
+core build sdk                      # Generate all
+core build sdk --lang typescript    # TypeScript only
+core build sdk --spec ./api.yaml    # Custom spec
+core build sdk --dry-run            # Preview
+```

docs/cmd/ci/changelog/example.md

@@ -0,0 +1,36 @@
+# CI Changelog Examples
+
+```bash
+core ci changelog
+```
+
+## Output
+
+```markdown
+## v1.2.0
+
+### Features
+- Add user authentication (#123)
+- Support dark mode (#124)
+
+### Bug Fixes
+- Fix memory leak in worker (#125)
+
+### Performance
+- Optimize database queries (#126)
+```
+
+## Configuration
+
+`.core/release.yaml`:
+
+```yaml
+changelog:
+  include:
+    - feat
+    - fix
+    - perf
+  exclude:
+    - chore
+    - docs
+```

docs/cmd/ci/init/example.md

@@ -0,0 +1,17 @@
+# CI Init Examples
+
+```bash
+core ci init
+```
+
+Creates `.core/release.yaml`:
+
+```yaml
+version: 1
+
+project:
+  name: myapp
+
+publishers:
+  - type: github
+```

docs/cmd/ci/version/example.md

@@ -0,0 +1,18 @@
+# CI Version Examples
+
+```bash
+core ci version
+```
+
+## Output
+
+```
+v1.2.0
+```
+
+## Version Resolution
+
+1. `--version` flag (if provided)
+2. Git tag on HEAD
+3. Latest git tag + increment
+4. `v0.0.1` (no tags)

docs/cmd/dev/work/example.md

@@ -0,0 +1,21 @@
+# Dev Work Examples
+
+```bash
+# Full workflow: status → commit → push
+core dev work
+
+# Status only
+core dev work --status
+```
+
+## Output
+
+```
+┌─────────────┬────────┬──────────┬─────────┐
+│ Repo        │ Branch │ Status   │ Behind  │
+├─────────────┼────────┼──────────┼─────────┤
+│ core-php    │ main   │ clean    │ 0       │
+│ core-tenant │ main   │ 2 files  │ 0       │
+│ core-admin  │ dev    │ clean    │ 3       │
+└─────────────┴────────┴──────────┴─────────┘
+```

docs/cmd/docs/example.md

@@ -0,0 +1,14 @@
+# Docs Examples
+
+## List
+
+```bash
+core docs list
+```
+
+## Sync
+
+```bash
+core docs sync
+core docs sync --target ./docs
+```

docs/cmd/doctor/example.md

@@ -0,0 +1,20 @@
+# Doctor Examples
+
+```bash
+core doctor
+```
+
+## Output
+
+```
+✓ go 1.25.0
+✓ git 2.43.0
+✓ gh 2.40.0
+✓ docker 24.0.7
+✓ task 3.30.0
+✓ golangci-lint 1.55.0
+✗ wails (not installed)
+✓ php 8.3.0
+✓ composer 2.6.0
+✓ node 20.10.0
+```

docs/cmd/go/cov/example.md

@@ -0,0 +1,18 @@
+# Go Coverage Examples
+
+```bash
+# Summary
+core go cov
+
+# HTML report
+core go cov --html
+
+# Open in browser
+core go cov --open
+
+# Fail if below threshold
+core go cov --threshold 80
+
+# Specific package
+core go cov --pkg ./pkg/release
+```

docs/cmd/go/fmt/example.md

@@ -0,0 +1,12 @@
+# Go Format Examples
+
+```bash
+# Check only
+core go fmt
+
+# Apply fixes
+core go fmt --fix
+
+# Show diff
+core go fmt --diff
+```

docs/cmd/go/install/example.md

@@ -0,0 +1,15 @@
+# Go Install Examples
+
+```bash
+# Auto-detect cmd/
+core go install
+
+# Specific path
+core go install ./cmd/myapp
+
+# Pure Go (no CGO)
+core go install --no-cgo
+
+# Verbose
+core go install -v
+```

docs/cmd/go/lint/example.md

@@ -0,0 +1,22 @@
+# Go Lint Examples
+
+```bash
+# Check
+core go lint
+
+# Auto-fix
+core go lint --fix
+```
+
+## Configuration
+
+`.golangci.yml`:
+
+```yaml
+linters:
+  enable:
+    - gofmt
+    - govet
+    - errcheck
+    - staticcheck
+```

docs/cmd/go/mod/example.md

@@ -0,0 +1,15 @@
+# Go Module Examples
+
+```bash
+# Tidy
+core go mod tidy
+
+# Download
+core go mod download
+
+# Verify
+core go mod verify
+
+# Graph
+core go mod graph
+```

docs/cmd/go/test/example.md

@@ -0,0 +1,27 @@
+# Go Test Examples
+
+```bash
+# All tests
+core go test
+
+# Specific package
+core go test --pkg ./pkg/core
+
+# Specific test
+core go test --run TestHash
+
+# With coverage
+core go test --coverage
+
+# Race detection
+core go test --race
+
+# Short tests only
+core go test --short
+
+# Verbose
+core go test -v
+
+# JSON output (CI)
+core go test --json
+```

docs/cmd/pkg/example.md

@@ -0,0 +1,36 @@
+# Package Examples
+
+## Search
+
+```bash
+core pkg search core-
+core pkg search api
+core pkg search --org myorg
+```
+
+## Install
+
+```bash
+core pkg install core-api
+core pkg install host-uk/core-api
+```
+
+## List
+
+```bash
+core pkg list
+core pkg list --format json
+```
+
+## Update
+
+```bash
+core pkg update
+core pkg update core-api
+```
+
+## Outdated
+
+```bash
+core pkg outdated
+```

docs/cmd/pkg/search/example.md

@@ -0,0 +1,23 @@
+# Package Search Examples
+
+```bash
+# Find all core-* packages
+core pkg search core-
+
+# Search term
+core pkg search api
+
+# Different org
+core pkg search --org myorg query
+```
+
+## Output
+
+```
+┌──────────────┬─────────────────────────────┐
+│ Package      │ Description                 │
+├──────────────┼─────────────────────────────┤
+│ core-api     │ REST API framework          │
+│ core-auth    │ Authentication utilities    │
+└──────────────┴─────────────────────────────┘
+```

docs/cmd/sdk/example.md

@@ -0,0 +1,35 @@
+# SDK Examples
+
+## Validate
+
+```bash
+core sdk validate
+core sdk validate --spec ./api.yaml
+```
+
+## Diff
+
+```bash
+# Compare with tag
+core sdk diff --base v1.0.0
+
+# Compare files
+core sdk diff --base ./old-api.yaml --spec ./new-api.yaml
+```
+
+## Output
+
+```
+Breaking changes detected:
+
+- DELETE /users/{id}/profile
+  Endpoint removed
+
+- PATCH /users/{id}
+  Required field 'email' added
+
+Non-breaking changes:
+
++ POST /users/{id}/avatar
+  New endpoint added
+```

docs/cmd/setup/example.md

@@ -0,0 +1,29 @@
+# Setup Examples
+
+```bash
+# Clone all repos
+core setup
+
+# Specific directory
+core setup --dir ~/Code/host-uk
+
+# Use SSH
+core setup --ssh
+```
+
+## Configuration
+
+`repos.yaml`:
+
+```yaml
+org: host-uk
+repos:
+  core-php:
+    type: package
+  core-tenant:
+    type: package
+    depends: [core-php]
+  core-admin:
+    type: package
+    depends: [core-php, core-tenant]
+```

docs/cmd/test/example.md

@@ -0,0 +1,8 @@
+# Test Examples
+
+**Note:** Prefer `core go test` or `core php test` instead.
+
+```bash
+core test
+core test --coverage
+```

docs/cmd/vm/templates/example.md

@@ -0,0 +1,34 @@
+# VM Templates Examples
+
+## List
+
+```bash
+core vm templates
+```
+
+## Show
+
+```bash
+core vm templates show core-dev
+```
+
+## Variables
+
+```bash
+core vm templates vars core-dev
+```
+
+## Output
+
+```
+Variables for core-dev:
+  SSH_KEY      (required)  SSH public key
+  MEMORY       (optional)  Memory in MB (default: 4096)
+  CPUS         (optional)  CPU count (default: 4)
+```
+
+## Using Templates
+
+```bash
+core vm run --template core-dev --var SSH_KEY="ssh-rsa AAAA..."
+```