docs: complete CLI documentation sync

- pkg search: add --pattern, --type, --refresh, --limit, --org flags
- sdk: remove generate (use core build sdk), keep only diff/validate
- vm run: add --ssh-port, --name, fix defaults
- TODO.md: all gaps resolved

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

docs/cmd/TODO.md

@@ -1,21 +1,5 @@
 # Documentation TODO
 
-Commands and flags found in CLI but missing from documentation.
+All CLI commands are documented. No gaps found.
 
-## Missing Flags
+Last verified: 2026-01-29
-
-### core pkg search
-
-- `--refresh` - Bypass cache and fetch fresh data
-- `--type` - Filter by type in name (mod, services, plug, website)
-
-### core vm run
-
-- `--ssh-port` - SSH port for exec commands (default: 2222)
-
-## Discrepancies
-
-### core sdk
-
-- Docs describe `core sdk generate` command but CLI only has `core sdk diff` and `core sdk validate`
-- SDK generation is actually at `core build sdk`, not `core sdk generate`

docs/cmd/pkg/search/index.md

@@ -1,40 +1,48 @@
-# core pkg search & core pkg install
+# core pkg search
-
-Search GitHub for repositories and install them locally.
-
-## core pkg search
 
 Search GitHub for repositories matching a pattern.
 
+Uses `gh` CLI for authenticated search. Results are cached for 1 hour.
+
+## Usage
+
 ```bash
-core pkg search <pattern> [flags]
+core pkg search [flags]
 ```
 
-### Flags
+## Flags
 
 | Flag | Description |
 |------|-------------|
-| `--org` | Search within a specific organization |
+| `--pattern` | Repo name pattern (* for wildcard) |
-| `--limit` | Maximum results (default: 10) |
+| `--org` | GitHub organization (default: host-uk) |
-| `--language` | Filter by programming language |
+| `--type` | Filter by type in name (mod, services, plug, website) |
+| `--limit` | Max results (default: 50) |
+| `--refresh` | Bypass cache and fetch fresh data |
 
-### Examples
+## Examples
 
 ```bash
-# Search by pattern
+# List all host-uk repos
-core pkg search "cli tool"
+core pkg search
 
-# Search within organization
+# Search for core-* repos
-core pkg search --org host-uk
+core pkg search --pattern "core-*"
 
-# Search with language filter
+# Search different org
-core pkg search --org host-uk --language go
+core pkg search --org mycompany
 
-# Search all core-* repos
+# Filter by type
-core pkg search "core-" --org host-uk
+core pkg search --type services
+
+# Bypass cache
+core pkg search --refresh
+
+# Combine filters
+core pkg search --pattern "core-*" --type mod --limit 20
 ```
 
-### Output
+## Output
 
 ```
 Found 5 repositories:
@@ -52,39 +60,7 @@ Found 5 repositories:
     ★ 8  Dockerfile  Updated 3 days ago
 ```
 
-## core pkg install
+## Authentication
-
-Clone a repository from GitHub.
-
-```bash
-core pkg install <repo> [flags]
-```
-
-### Flags
-
-| Flag | Description |
-|------|-------------|
-| `--path` | Destination directory (default: current dir) |
-| `--branch` | Clone specific branch |
-| `--depth` | Shallow clone depth |
-
-### Examples
-
-```bash
-# Install by full name
-core pkg install host-uk/core
-
-# Install to specific path
-core pkg install host-uk/core --path ~/Code/host-uk
-
-# Install specific branch
-core pkg install host-uk/core --branch dev
-
-# Shallow clone
-core pkg install host-uk/core --depth 1
-```
-
-### Authentication
 
 Uses GitHub CLI (`gh`) authentication. Ensure you're logged in:
 
@@ -93,20 +69,7 @@ gh auth status
 gh auth login  # if not authenticated
 ```
 
-## Workflow Example
-
-```bash
-# Find repositories
-core pkg search --org host-uk
-
-# Install one
-core pkg install host-uk/core-php --path ~/Code/host-uk
-
-# Check setup
-core doctor
-```
-
 ## See Also
 
+- [pkg install](../) - Clone a package from GitHub
 - [setup command](../../setup/) - Clone all repos from registry
-- [doctor command](../../doctor/) - Check environment

docs/cmd/sdk/index.md

@@ -1,6 +1,8 @@
 # core sdk
 
-Generate typed API clients from OpenAPI specifications.
+SDK validation and API compatibility tools.
+
+To generate SDKs, use: `core build sdk`
 
 ## Usage
 
@@ -12,46 +14,8 @@ core sdk <command> [flags]
 
 | Command | Description |
 |---------|-------------|
-| `generate` | Generate SDKs from OpenAPI spec |
-| `validate` | Validate OpenAPI spec |
 | `diff` | Check for breaking API changes |
-
+| `validate` | Validate OpenAPI spec |
-## sdk generate
-
-Generate typed API clients for multiple languages.
-
-```bash
-core sdk generate [flags]
-```
-
-### Flags
-
-| Flag | Description |
-|------|-------------|
-| `--spec` | Path to OpenAPI spec file (auto-detected) |
-| `--lang` | Generate only this language |
-
-### Examples
-
-```bash
-# Generate all configured SDKs
-core sdk generate
-
-# Generate only TypeScript SDK
-core sdk generate --lang typescript
-
-# Use specific spec file
-core sdk generate --spec api/openapi.yaml
-```
-
-### Supported Languages
-
-| Language | Generator |
-|----------|-----------|
-| TypeScript | openapi-generator (typescript-fetch) |
-| Python | openapi-generator (python) |
-| Go | openapi-generator (go) |
-| PHP | openapi-generator (php) |
 
 ## sdk validate
 
@@ -109,48 +73,22 @@ core sdk diff --base old-api.yaml --spec new-api.yaml
 - Removed required fields
 - Changed response types
 
-## Release Integration
+## SDK Generation
 
-SDKs can be generated before publishing a release:
+SDK generation is handled by `core build sdk`, not this command.
 
 ```bash
-# Generate all configured SDKs
+# Generate SDKs
-core sdk generate
+core build sdk
 
-# Then publish the release
+# Generate specific language
-core ci --were-go-for-launch
+core build sdk --lang typescript
+
+# Preview without writing
+core build sdk --dry-run
 ```
 
-See [ci command](../ci/) for release details.
+See [build sdk](../build/sdk/) for generation details.
-
-## Configuration
-
-Configure SDK generation in `.core/release.yaml`:
-
-```yaml
-sdk:
-  # OpenAPI spec path (auto-detected if not set)
-  spec: api/openapi.yaml
-
-  # Languages to generate
-  languages:
-    - typescript
-    - python
-    - go
-    - php
-
-  # Output directory
-  output: sdk
-
-  # Package naming
-  package:
-    name: my-api-sdk
-
-  # Breaking change detection
-  diff:
-    enabled: true
-    fail_on_breaking: false  # Warn but continue
-```
 
 ## Spec Auto-Detection
 
@@ -162,24 +100,7 @@ Core looks for OpenAPI specs in this order:
 4. `docs/openapi.yaml` / `docs/openapi.json`
 5. Laravel Scramble endpoint (`/docs/api.json`)
 
-## Output Structure
+## See Also
 
-Generated SDKs are placed in language-specific directories:
+- [build sdk](../build/sdk/) - Generate SDKs from OpenAPI
-
+- [ci command](../ci/) - Release workflow
-```
-sdk/
-├── typescript/
-│   ├── src/
-│   ├── package.json
-│   └── tsconfig.json
-├── python/
-│   ├── my_api_sdk/
-│   ├── setup.py
-│   └── requirements.txt
-├── go/
-│   ├── client.go
-│   └── go.mod
-└── php/
-    ├── src/
-    └── composer.json
-```

docs/cmd/vm/index.md

@@ -34,9 +34,11 @@ core vm run --template <name> [flags]
 |------|-------------|
 | `--template` | Use a template instead of image file |
 | `--var` | Set template variable (KEY=value) |
-| `--memory` | Memory in MB (default: 4096) |
+| `--name` | Name for the container |
-| `--cpus` | CPU count (default: 4) |
+| `--memory` | Memory in MB (default: 1024) |
-| `-d` | Run in background |
+| `--cpus` | CPU count (default: 1) |
+| `--ssh-port` | SSH port for exec commands (default: 2222) |
+| `-d` | Run in detached mode (background) |
 
 ## vm ps