core/go
8
0
Fork 0
generated from lthn/LEM
Code Issues 5 Pull requests 1 Projects Releases Packages Wiki Activity Actions

docs: remove stale CLI/ecosystem docs, keep framework-only content

Browse source 
Massive cleanup after module extraction sprint. core/go is now a pure
DI framework — docs should reflect that, not document CLI commands.

- Delete 130+ CLI command/example docs (already in core/cli)
- Delete 6 obsolete pkg-batch*-analysis.md files
- Delete plans/, skill/, static/, mcp/ (moved to correct repos)
- Rewrite index.md for DI framework (not CLI)
- Fix PACKAGE_STANDARDS.md: framework.* → core.* references
- Fix log.md: correct framework integration example

Remaining docs: index.md, pkg/PACKAGE_STANDARDS.md, pkg/log.md

Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider 2026-03-06 14:24:35 +00:00
parent 4f6209f590
commit f71f4c7d66
139 changed files with 78 additions and 22463 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

100
docs/cmd/ai/example.md
View file

@ -1,100 +0,0 @@
# AI Examples
## Workflow Example
Complete task management workflow:
```bash
# 1. List available tasks
core ai tasks --status pending
# 2. Auto-select and claim a task
core ai task --auto --claim
# 3. Work on the task...
# 4. Update progress
core ai task:update abc123 --progress 75
# 5. Commit with task reference
core ai task:commit abc123 -m 'implement feature'
# 6. Create PR
core ai task:pr abc123
# 7. Mark complete
core ai task:complete abc123 --output 'Feature implemented and PR created'
```
## Task Filtering
```bash
# By status
core ai tasks --status pending
core ai tasks --status in_progress
# By priority
core ai tasks --priority critical
core ai tasks --priority high
# By labels
core ai tasks --labels bug,urgent
# Combined filters
core ai tasks --status pending --priority high --labels bug
```
## Task Updates
```bash
# Change status
core ai task:update abc123 --status in_progress
core ai task:update abc123 --status blocked
# Update progress
core ai task:update abc123 --progress 25
core ai task:update abc123 --progress 50 --notes 'Halfway done'
core ai task:update abc123 --progress 100
```
## Git Integration
```bash
# Commit with task reference
core ai task:commit abc123 -m 'add authentication'
# With scope
core ai task:commit abc123 -m 'fix login' --scope auth
# Commit and push
core ai task:commit abc123 -m 'complete feature' --push
# Create PR
core ai task:pr abc123
# Draft PR
core ai task:pr abc123 --draft
# PR with labels
core ai task:pr abc123 --labels 'enhancement,ready-for-review'
# PR to different base
core ai task:pr abc123 --base develop
```
## Configuration
### Environment Variables
```env
AGENTIC_TOKEN=your-api-token
AGENTIC_BASE_URL=https://agentic.example.com
```
### ~/.core/agentic.yaml
```yaml
token: your-api-token
base_url: https://agentic.example.com
default_project: my-project
```

262
docs/cmd/ai/index.md
View file

@ -1,262 +0,0 @@
# core ai
AI agent task management and Claude Code integration.
## Task Management Commands
| Command | Description |
|---------|-------------|
| `tasks` | List available tasks from core-agentic |
| `task` | View task details or auto-select |
| `task:update` | Update task status or progress |
| `task:complete` | Mark task as completed or failed |
| `task:commit` | Create git commit with task reference |
| `task:pr` | Create GitHub PR linked to task |
## Claude Integration
| Command | Description |
|---------|-------------|
| `claude run` | Run Claude Code in current directory |
| `claude config` | Manage Claude configuration |
---
## Configuration
Task commands load configuration from:
1. Environment variables (`AGENTIC_TOKEN`, `AGENTIC_BASE_URL`)
2. `.env` file in current directory
3. `~/.core/agentic.yaml`
---
## ai tasks
List available tasks from core-agentic.
```bash
core ai tasks [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--status` | Filter by status (`pending`, `in_progress`, `completed`, `blocked`) |
| `--priority` | Filter by priority (`critical`, `high`, `medium`, `low`) |
| `--labels` | Filter by labels (comma-separated) |
| `--project` | Filter by project |
| `--limit` | Max number of tasks to return (default: 20) |
### Examples
```bash
# List all pending tasks
core ai tasks
# Filter by status and priority
core ai tasks --status pending --priority high
# Filter by labels
core ai tasks --labels bug,urgent
```
---
## ai task
View task details or auto-select a task.
```bash
core ai task [task-id] [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--auto` | Auto-select highest priority pending task |
| `--claim` | Claim the task after showing details |
| `--context` | Show gathered context for AI collaboration |
### Examples
```bash
# Show task details
core ai task abc123
# Show and claim
core ai task abc123 --claim
# Show with context
core ai task abc123 --context
# Auto-select highest priority pending task
core ai task --auto
```
---
## ai task:update
Update a task's status, progress, or notes.
```bash
core ai task:update <task-id> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--status` | New status (`pending`, `in_progress`, `completed`, `blocked`) |
| `--progress` | Progress percentage (0-100) |
| `--notes` | Notes about the update |
### Examples
```bash
# Set task to in progress
core ai task:update abc123 --status in_progress
# Update progress with notes
core ai task:update abc123 --progress 50 --notes 'Halfway done'
```
---
## ai task:complete
Mark a task as completed with optional output and artifacts.
```bash
core ai task:complete <task-id> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--output` | Summary of the completed work |
| `--failed` | Mark the task as failed |
| `--error` | Error message if failed |
### Examples
```bash
# Complete successfully
core ai task:complete abc123 --output 'Feature implemented'
# Mark as failed
core ai task:complete abc123 --failed --error 'Build failed'
```
---
## ai task:commit
Create a git commit with a task reference and co-author attribution.
```bash
core ai task:commit <task-id> [flags]
```
Commit message format:
```
feat(scope): description
Task: #123
Co-Authored-By: Claude <noreply@anthropic.com>
```
### Flags
| Flag | Description |
|------|-------------|
| `-m`, `--message` | Commit message (without task reference) |
| `--scope` | Scope for the commit type (e.g., `auth`, `api`, `ui`) |
| `--push` | Push changes after committing |
### Examples
```bash
# Commit with message
core ai task:commit abc123 --message 'add user authentication'
# With scope
core ai task:commit abc123 -m 'fix login bug' --scope auth
# Commit and push
core ai task:commit abc123 -m 'update docs' --push
```
---
## ai task:pr
Create a GitHub pull request linked to a task.
```bash
core ai task:pr <task-id> [flags]
```
Requires the GitHub CLI (`gh`) to be installed and authenticated.
### Flags
| Flag | Description |
|------|-------------|
| `--title` | PR title (defaults to task title) |
| `--base` | Base branch (defaults to main) |
| `--draft` | Create as draft PR |
| `--labels` | Labels to add (comma-separated) |
### Examples
```bash
# Create PR with defaults
core ai task:pr abc123
# Custom title
core ai task:pr abc123 --title 'Add authentication feature'
# Draft PR with labels
core ai task:pr abc123 --draft --labels 'enhancement,needs-review'
# Target different base branch
core ai task:pr abc123 --base develop
```
---
## ai claude
Claude Code integration commands.
### ai claude run
Run Claude Code in the current directory.
```bash
core ai claude run
```
### ai claude config
Manage Claude configuration.
```bash
core ai claude config
```
---
## Workflow Example
See [Workflow Example](example.md#workflow-example) for a complete task management workflow.
## See Also
- [dev](../dev/) - Multi-repo workflow commands
- [Claude Code documentation](https://claude.ai/code)

83
docs/cmd/build/example.md
View file

@ -1,83 +0,0 @@
# 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
```

176
docs/cmd/build/index.md
View file

@ -1,176 +0,0 @@
# core build
Build Go, Wails, Docker, and LinuxKit projects with automatic project detection.
## Subcommands
| Command | Description |
|---------|-------------|
| [sdk](sdk/) | Generate API SDKs from OpenAPI |
| `from-path` | Build from a local directory |
| `pwa` | Build from a live PWA URL |
## Usage
```bash
core build [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--type` | Project type: `go`, `wails`, `docker`, `linuxkit`, `taskfile` (auto-detected) |
| `--targets` | Build targets: `linux/amd64,darwin/arm64,windows/amd64` |
| `--output` | Output directory (default: `dist`) |
| `--ci` | CI mode - minimal output with JSON artifact list at the end |
| `--image` | Docker image name (for docker builds) |
| `--config` | Config file path (for linuxkit: YAML config, for docker: Dockerfile) |
| `--format` | Output format for linuxkit (iso-bios, qcow2-bios, raw, vmdk) |
| `--push` | Push Docker image after build (default: false) |
| `--archive` | Create archives (tar.gz for linux/darwin, zip for windows) - default: true |
| `--checksum` | Generate SHA256 checksums and CHECKSUMS.txt - default: true |
| `--no-sign` | Skip all 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
# Build and push to registry
core build --type docker --image ghcr.io/myorg/myapp --push
```
### LinuxKit Image
```bash
# Build LinuxKit ISO
core build --type linuxkit
# Build with specific format
core build --type linuxkit --config linuxkit.yml --format qcow2-bios
```
## Project Detection
Core automatically detects project type based on files:
| Files | Type |
|-------|------|
| `wails.json` | Wails |
| `go.mod` | Go |
| `Dockerfile` | Docker |
| `Taskfile.yml` | Taskfile |
| `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` - see [Configuration](example.md#configuration) for examples.
## 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 |
## Building from PWAs and Static Sites
### Build from Local Directory
Build a desktop app from static web application files:
```bash
core build from-path --path ./dist
```
### Build from Live PWA
Build a desktop app from a live Progressive Web App URL:
```bash
core build pwa --url https://example.com
```

56
docs/cmd/build/sdk/example.md
View file

@ -1,56 +0,0 @@
# 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
```

27
docs/cmd/build/sdk/index.md
View file

@ -1,27 +0,0 @@
# core build sdk
Generate typed API clients from OpenAPI specifications. Supports TypeScript, Python, Go, and PHP.
## Usage
```bash
core build sdk [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--spec` | Path to OpenAPI spec file |
| `--lang` | Generate only this language (typescript, python, go, php) |
| `--version` | Version to embed in generated SDKs |
| `--dry-run` | Show what would be generated without writing files |
## 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
```

36
docs/cmd/ci/changelog/example.md
View file

@ -1,36 +0,0 @@
# 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
```

28
docs/cmd/ci/changelog/index.md
View file

@ -1,28 +0,0 @@
# core ci changelog
Generate changelog from conventional commits.
## Usage
```bash
core ci changelog
```
## Output
Generates markdown changelog from git commits since last tag:
```markdown
## v1.2.0
### Features
- Add user authentication (#123)
- Support dark mode (#124)
### Bug Fixes
- Fix memory leak in worker (#125)
```
## Configuration
See [configuration.md](../../../configuration.md) for changelog configuration options.

90
docs/cmd/ci/example.md
View file

@ -1,90 +0,0 @@
# CI Examples
## Quick Start
```bash
# Build first
core build
# Preview release
core ci
# Publish
core ci --we-are-go-for-launch
```
## Configuration
`.core/release.yaml`:
```yaml
version: 1
project:
name: myapp
repository: host-uk/myapp
publishers:
- type: github
```
## Publisher Examples
### GitHub + Docker
```yaml
publishers:
- type: github
- type: docker
registry: ghcr.io
image: host-uk/myapp
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
```
### Full Stack (GitHub + npm + Homebrew)
```yaml
publishers:
- type: github
- type: npm
package: "@host-uk/myapp"
access: public
- type: homebrew
tap: host-uk/homebrew-tap
```
### LinuxKit Image
```yaml
publishers:
- type: linuxkit
config: .core/linuxkit/server.yml
formats:
- iso
- qcow2
platforms:
- linux/amd64
- linux/arm64
```
## Changelog Configuration
```yaml
changelog:
include:
- feat
- fix
- perf
exclude:
- chore
- docs
- test
```

79
docs/cmd/ci/index.md
View file

@ -1,79 +0,0 @@
# core ci
Publish releases to GitHub, Docker, npm, Homebrew, and more.
**Safety:** Dry-run by default. Use `--we-are-go-for-launch` to actually publish.
## Subcommands
| Command | Description |
|---------|-------------|
| [init](init/) | Initialize release config |
| [changelog](changelog/) | Generate changelog |
| [version](version/) | Show determined version |
## Usage
```bash
core ci [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--we-are-go-for-launch` | Actually publish (default is dry-run) |
| `--version` | Override version |
| `--draft` | Create as draft release |
| `--prerelease` | Mark as prerelease |
## Examples
```bash
# Preview what would be published (safe)
core ci
# Actually publish
core ci --we-are-go-for-launch
# Publish as draft
core ci --we-are-go-for-launch --draft
# Publish as prerelease
core ci --we-are-go-for-launch --prerelease
```
## Workflow
Build and publish are **separated** to prevent accidents:
```bash
# Step 1: Build artifacts
core build
core build sdk
# Step 2: Preview (dry-run by default)
core ci
# Step 3: Publish (explicit flag required)
core ci --we-are-go-for-launch
```
## Publishers
See [Publisher Examples](example.md#publisher-examples) for configuration.
| Type | Target |
|------|--------|
| `github` | GitHub Releases |
| `docker` | Container registries |
| `linuxkit` | LinuxKit images |
| `npm` | npm registry |
| `homebrew` | Homebrew tap |
| `scoop` | Scoop bucket |
| `aur` | Arch User Repository |
| `chocolatey` | Chocolatey |
## Changelog
Auto-generated from conventional commits. See [Changelog Configuration](example.md#changelog-configuration).

17
docs/cmd/ci/init/example.md
View file

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

11
docs/cmd/ci/init/index.md
View file

@ -1,11 +0,0 @@
# core ci init
Initialize release configuration.
## Usage
```bash
core ci init
```
Creates `.core/release.yaml` with default configuration. See [Configuration](../example.md#configuration) for output format.

18
docs/cmd/ci/version/example.md
View file

@ -1,18 +0,0 @@
# 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)

21
docs/cmd/ci/version/index.md
View file

@ -1,21 +0,0 @@
# core ci version
Show the determined release version.
## Usage
```bash
core ci version
```
## Output
```
v1.2.0
```
Version is determined from:
1. `--version` flag (if provided)
2. Git tag on HEAD
3. Latest git tag + increment
4. `v0.0.1` (if no tags exist)

61
docs/cmd/dev/ci/index.md
View file

@ -1,61 +0,0 @@
# core dev ci
Check CI status across all repositories.
Fetches GitHub Actions workflow status for all repos. Shows latest run status for each repo. Requires the `gh` CLI to be installed and authenticated.
## Usage
```bash
core dev ci [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--branch` | Filter by branch (default: main) |
| `--failed` | Show only failed runs |
## Examples
```bash
# Check CI status for all repos
core dev ci
# Check specific branch
core dev ci --branch develop
# Show only failures
core dev ci --failed
```
## Output
```
core-php ✓ passing 2m ago
core-tenant ✓ passing 5m ago
core-admin ✗ failed 12m ago
core-api ⏳ running now
core-bio ✓ passing 1h ago
```
## Status Icons
| Symbol | Meaning |
|--------|---------|
| `✓` | Passing |
| `✗` | Failed |
| `⏳` | Running |
| `-` | No runs |
## Requirements
- GitHub CLI (`gh`) must be installed
- Must be authenticated: `gh auth login`
## See Also
- [issues command](../issues/) - List open issues
- [reviews command](../reviews/) - List PRs needing review

46
docs/cmd/dev/commit/index.md
View file

@ -1,46 +0,0 @@
# core dev commit
Claude-assisted commits across repositories.
Uses Claude to create commits for dirty repos. Shows uncommitted changes and invokes Claude to generate commit messages.
## Usage
```bash
core dev commit [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--all` | Commit all dirty repos without prompting |
## Examples
```bash
# Interactive commit (prompts for each repo)
core dev commit
# Commit all dirty repos automatically
core dev commit --all
# Use specific registry
core dev commit --registry ~/projects/repos.yaml
```
## How It Works
1. Scans all repositories for uncommitted changes
2. For each dirty repo:
- Shows the diff
- Invokes Claude to generate a commit message
- Creates the commit with `Co-Authored-By: Claude`
3. Reports success/failure for each repo
## See Also
- [health command](../health/) - Check repo status
- [push command](../push/) - Push commits after committing
- [work command](../work/) - Full workflow (status + commit + push)

203
docs/cmd/dev/example.md
View file

@ -1,203 +0,0 @@
# Dev Examples
## Multi-Repo Workflow
```bash
# Quick status
core dev health
# Detailed breakdown
core dev health --verbose
# Full workflow
core dev work
# Status only
core dev work --status
# Commit and push
core dev work --commit
# Commit dirty repos
core dev commit
# Commit all without prompting
core dev commit --all
# Push unpushed
core dev push
# Push without confirmation
core dev push --force
# Pull behind repos
core dev pull
# Pull all repos
core dev pull --all
```
## GitHub Integration
```bash
# Open issues
core dev issues
# Filter by assignee
core dev issues --assignee @me
# Limit results
core dev issues --limit 5
# PRs needing review
core dev reviews
# All PRs including drafts
core dev reviews --all
# Filter by author
core dev reviews --author username
# CI status
core dev ci
# Only failed runs
core dev ci --failed
# Specific branch
core dev ci --branch develop
```
## Dependency Analysis
```bash
# What depends on core-php?
core dev impact core-php
```
## Task Management
```bash
# List tasks
core ai tasks
# Filter by status and priority
core ai tasks --status pending --priority high
# Filter by labels
core ai tasks --labels bug,urgent
# Show task details
core ai task abc123
# Auto-select highest priority task
core ai task --auto
# Claim a task
core ai task abc123 --claim
# Update task status
core ai task:update abc123 --status in_progress
# Add progress notes
core ai task:update abc123 --progress 50 --notes 'Halfway done'
# Complete a task
core ai task:complete abc123 --output 'Feature implemented'
# Mark as failed
core ai task:complete abc123 --failed --error 'Build failed'
# Commit with task reference
core ai task:commit abc123 -m 'add user authentication'
# Commit with scope and push
core ai task:commit abc123 -m 'fix login bug' --scope auth --push
# Create PR for task
core ai task:pr abc123
# Create draft PR with labels
core ai task:pr abc123 --draft --labels 'enhancement,needs-review'
```
## Service API Management
```bash
# Synchronize public service APIs
core dev sync
# Or using the api command
core dev api sync
```
## Dev Environment
```bash
# First time setup
core dev install
core dev boot
# Open shell
core dev shell
# Mount and serve
core dev serve
# Run tests
core dev test
# Sandboxed Claude
core dev claude
```
## Configuration
### repos.yaml
```yaml
org: host-uk
repos:
core-php:
type: package
description: Foundation framework
core-tenant:
type: package
depends: [core-php]
```
### ~/.core/config.yaml
```yaml
version: 1
images:
source: auto # auto | github | registry | cdn
cdn:
url: https://images.example.com/core-devops
github:
repo: host-uk/core-images
registry:
image: ghcr.io/host-uk/core-devops
```
### .core/test.yaml
```yaml
version: 1
commands:
- name: unit
run: vendor/bin/pest --parallel
- name: types
run: vendor/bin/phpstan analyse
- name: lint
run: vendor/bin/pint --test
env:
APP_ENV: testing
DB_CONNECTION: sqlite
```

52
docs/cmd/dev/health/index.md
View file

@ -1,52 +0,0 @@
# core dev health
Quick health check across all repositories.
Shows a summary of repository health: total repos, dirty repos, unpushed commits, etc.
## Usage
```bash
core dev health [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--verbose` | Show detailed breakdown |
## Examples
```bash
# Quick health summary
core dev health
# Detailed breakdown
core dev health --verbose
# Use specific registry
core dev health --registry ~/projects/repos.yaml
```
## Output
```
18 repos │ 2 dirty │ 1 ahead │ all synced
```
With `--verbose`:
```
Repos: 18
Dirty: 2 (core-php, core-admin)
Ahead: 1 (core-tenant)
Behind: 0
Synced: ✓
```
## See Also
- [work command](../work/) - Full workflow (status + commit + push)
- [commit command](../commit/) - Claude-assisted commits

65
docs/cmd/dev/impact/index.md
View file

@ -1,65 +0,0 @@
# core dev impact
Show impact of changing a repository.
Analyses the dependency graph to show which repos would be affected by changes to the specified repo.
## Usage
```bash
core dev impact <repo-name> [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
## Examples
```bash
# Show what depends on core-php
core dev impact core-php
# Show what depends on core-tenant
core dev impact core-tenant
```
## Output
```
Impact of changes to core-php:
Direct dependents (5):
core-tenant
core-admin
core-api
core-mcp
core-commerce
Indirect dependents (12):
core-bio (via core-tenant)
core-social (via core-tenant)
core-analytics (via core-tenant)
core-notify (via core-tenant)
core-trust (via core-tenant)
core-support (via core-tenant)
core-content (via core-tenant)
core-developer (via core-tenant)
core-agentic (via core-mcp)
...
Total: 17 repos affected
```
## Use Cases
- Before making breaking changes, see what needs updating
- Plan release order based on dependency graph
- Understand the ripple effect of changes
## See Also
- [health command](../health/) - Quick repo status
- [setup command](../../setup/) - Clone repos with dependencies

388
docs/cmd/dev/index.md
View file

@ -1,388 +0,0 @@
# core dev
Multi-repo workflow and portable development environment.
## Multi-Repo Commands
| Command | Description |
|---------|-------------|
| [work](work/) | Full workflow: status + commit + push |
| `health` | Quick health check across repos |
| `commit` | Claude-assisted commits |
| `push` | Push repos with unpushed commits |
| `pull` | Pull repos that are behind |
| `issues` | List open issues |
| `reviews` | List PRs needing review |
| `ci` | Check CI status |
| `impact` | Show dependency impact |
| `api` | Tools for managing service APIs |
| `sync` | Synchronize public service APIs |
## Task Management Commands
> **Note:** Task management commands have moved to [`core ai`](../ai/).
| Command | Description |
|---------|-------------|
| [`ai tasks`](../ai/) | List available tasks from core-agentic |
| [`ai task`](../ai/) | Show task details or auto-select a task |
| [`ai task:update`](../ai/) | Update task status or progress |
| [`ai task:complete`](../ai/) | Mark a task as completed |
| [`ai task:commit`](../ai/) | Auto-commit changes with task reference |
| [`ai task:pr`](../ai/) | Create a pull request for a task |
## Dev Environment Commands
| Command | Description |
|---------|-------------|
| `install` | Download the core-devops image |
| `boot` | Start the environment |
| `stop` | Stop the environment |
| `status` | Show status |
| `shell` | Open shell |
| `serve` | Start dev server |
| `test` | Run tests |
| `claude` | Sandboxed Claude |
| `update` | Update image |
---
## Dev Environment Overview
Core DevOps provides a sandboxed, immutable development environment based on LinuxKit with 100+ embedded tools.
## Quick Start
```bash
# First time setup
core dev install
core dev boot
# Open shell
core dev shell
# Or mount current project and serve
core dev serve
```
## dev install
Download the core-devops image for your platform.
```bash
core dev install
```
Downloads the platform-specific dev environment image including Go, PHP, Node.js, Python, Docker, and Claude CLI. Downloads are cached at `~/.core/images/`.
### Examples
```bash
# Download image (auto-detects platform)
core dev install
```
## dev boot
Start the development environment.
```bash
core dev boot [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--memory` | Memory allocation in MB (default: 4096) |
| `--cpus` | Number of CPUs (default: 2) |
| `--fresh` | Stop existing and start fresh |
### Examples
```bash
# Start with defaults
core dev boot
# More resources
core dev boot --memory 8192 --cpus 4
# Fresh start
core dev boot --fresh
```
## dev shell
Open a shell in the running environment.
```bash
core dev shell [flags] [-- command]
```
Uses SSH by default, or serial console with `--console`.
### Flags
| Flag | Description |
|------|-------------|
| `--console` | Use serial console instead of SSH |
### Examples
```bash
# SSH into environment
core dev shell
# Serial console (for debugging)
core dev shell --console
# Run a command
core dev shell -- ls -la
```
## dev serve
Mount current directory and start the appropriate dev server.
```bash
core dev serve [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--port` | Port to expose (default: 8000) |
| `--path` | Subdirectory to serve |
### Auto-Detection
| Project | Server Command |
|---------|---------------|
| Laravel (`artisan`) | `php artisan octane:start` |
| Node (`package.json` with `dev` script) | `npm run dev` |
| PHP (`composer.json`) | `frankenphp php-server` |
| Other | `python -m http.server` |
### Examples
```bash
# Auto-detect and serve
core dev serve
# Custom port
core dev serve --port 3000
```
## dev test
Run tests inside the environment.
```bash
core dev test [flags] [-- custom command]
```
### Flags
| Flag | Description |
|------|-------------|
| `--name` | Run named test command from `.core/test.yaml` |
### Test Detection
Core auto-detects the test framework or uses `.core/test.yaml`:
1. `.core/test.yaml` - Custom config
2. `composer.json` → `composer test`
3. `package.json` → `npm test`
4. `go.mod` → `go test ./...`
5. `pytest.ini` → `pytest`
6. `Taskfile.yaml` → `task test`
### Examples
```bash
# Auto-detect and run tests
core dev test
# Run named test from config
core dev test --name integration
# Custom command
core dev test -- go test -v ./pkg/...
```
### Test Configuration
Create `.core/test.yaml` for custom test setup - see [Configuration](example.md#configuration) for examples.
## dev claude
Start a sandboxed Claude session with your project mounted.
```bash
core dev claude [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--model` | Model to use (`opus`, `sonnet`) |
| `--no-auth` | Don't forward any auth credentials |
| `--auth` | Selective auth forwarding (`gh`, `anthropic`, `ssh`, `git`) |
### What Gets Forwarded
By default, these are forwarded to the sandbox:
- `~/.anthropic/` or `ANTHROPIC_API_KEY`
- `~/.config/gh/` (GitHub CLI auth)
- SSH agent
- Git config (name, email)
### Examples
```bash
# Full auth forwarding (default)
core dev claude
# Use Opus model
core dev claude --model opus
# Clean sandbox
core dev claude --no-auth
# Only GitHub and Anthropic auth
core dev claude --auth gh,anthropic
```
### Why Use This?
- **Immutable base** - Reset anytime with `core dev boot --fresh`
- **Safe experimentation** - Claude can install packages, make mistakes
- **Host system untouched** - All changes stay in the sandbox
- **Real credentials** - Can still push code, create PRs
- **Full tooling** - 100+ tools available in the image
## dev status
Show the current state of the development environment.
```bash
core dev status
```
Output includes:
- Running/stopped state
- Resource usage (CPU, memory)
- Exposed ports
- Mounted directories
## dev update
Check for and apply updates.
```bash
core dev update [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--apply` | Download and apply the update |
### Examples
```bash
# Check for updates
core dev update
# Apply available update
core dev update --apply
```
## Embedded Tools
The core-devops image includes 100+ tools:
| Category | Tools |
|----------|-------|
| **AI/LLM** | claude, gemini, aider, ollama, llm |
| **VCS** | git, gh, glab, lazygit, delta, git-lfs |
| **Runtimes** | frankenphp, node, bun, deno, go, python3, rustc |
| **Package Mgrs** | composer, npm, pnpm, yarn, pip, uv, cargo |
| **Build** | task, make, just, nx, turbo |
| **Linting** | pint, phpstan, prettier, eslint, biome, golangci-lint, ruff |
| **Testing** | phpunit, pest, vitest, playwright, k6 |
| **Infra** | docker, kubectl, k9s, helm, terraform, ansible |
| **Databases** | sqlite3, mysql, psql, redis-cli, mongosh, usql |
| **HTTP/Net** | curl, httpie, xh, websocat, grpcurl, mkcert, ngrok |
| **Data** | jq, yq, fx, gron, miller, dasel |
| **Security** | age, sops, cosign, trivy, trufflehog, vault |
| **Files** | fd, rg, fzf, bat, eza, tree, zoxide, broot |
| **Editors** | nvim, helix, micro |
## Configuration
Global config in `~/.core/config.yaml` - see [Configuration](example.md#configuration) for examples.
## Image Storage
Images are stored in `~/.core/images/`:
```
~/.core/
├── config.yaml
└── images/
├── core-devops-darwin-arm64.qcow2
├── core-devops-linux-amd64.qcow2
└── manifest.json
```
## Multi-Repo Commands
See the [work](work/) page for detailed documentation on multi-repo commands.
### dev ci
Check GitHub Actions workflow status across all repos.
```bash
core dev ci [flags]
```
#### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--branch` | Filter by branch (default: main) |
| `--failed` | Show only failed runs |
Requires the `gh` CLI to be installed and authenticated.
### dev api
Tools for managing service APIs.
```bash
core dev api sync
```
Synchronizes the public service APIs with their internal implementations.
### dev sync
Alias for `core dev api sync`. Synchronizes the public service APIs with their internal implementations.
```bash
core dev sync
```
This command scans the `pkg` directory for services and ensures that the top-level public API for each service is in sync with its internal implementation. It automatically generates the necessary Go files with type aliases.
## See Also
- [work](work/) - Multi-repo workflow commands (`core dev work`, `core dev health`, etc.)
- [ai](../ai/) - Task management commands (`core ai tasks`, `core ai task`, etc.)

57
docs/cmd/dev/issues/index.md
View file

@ -1,57 +0,0 @@
# core dev issues
List open issues across all repositories.
Fetches open issues from GitHub for all repos in the registry. Requires the `gh` CLI to be installed and authenticated.
## Usage
```bash
core dev issues [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--assignee` | Filter by assignee (use `@me` for yourself) |
| `--limit` | Max issues per repo (default 10) |
## Examples
```bash
# List all open issues
core dev issues
# Show issues assigned to you
core dev issues --assignee @me
# Limit to 5 issues per repo
core dev issues --limit 5
# Filter by specific assignee
core dev issues --assignee username
```
## Output
```
core-php (3 issues)
#42 Add retry logic to HTTP client bug
#38 Update documentation for v2 API docs
#35 Support custom serializers enhancement
core-tenant (1 issue)
#12 Workspace isolation bug bug, critical
```
## Requirements
- GitHub CLI (`gh`) must be installed
- Must be authenticated: `gh auth login`
## See Also
- [reviews command](../reviews/) - List PRs needing review
- [ci command](../ci/) - Check CI status

47
docs/cmd/dev/pull/index.md
View file

@ -1,47 +0,0 @@
# core dev pull
Pull updates across all repositories.
Pulls updates for all repos. By default only pulls repos that are behind. Use `--all` to pull all repos.
## Usage
```bash
core dev pull [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--all` | Pull all repos, not just those behind |
## Examples
```bash
# Pull only repos that are behind
core dev pull
# Pull all repos
core dev pull --all
# Use specific registry
core dev pull --registry ~/projects/repos.yaml
```
## Output
```
Pulling 2 repo(s) that are behind:
✓ core-php (3 commits)
✓ core-tenant (1 commit)
Done: 2 pulled
```
## See Also
- [push command](../push/) - Push local commits
- [health command](../health/) - Check sync status
- [work command](../work/) - Full workflow

52
docs/cmd/dev/push/index.md
View file

@ -1,52 +0,0 @@
# core dev push
Push commits across all repositories.
Pushes unpushed commits for all repos. Shows repos with commits to push and confirms before pushing.
## Usage
```bash
core dev push [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--force` | Skip confirmation prompt |
## Examples
```bash
# Push with confirmation
core dev push
# Push without confirmation
core dev push --force
# Use specific registry
core dev push --registry ~/projects/repos.yaml
```
## Output
```
3 repo(s) with unpushed commits:
core-php: 2 commit(s)
core-admin: 1 commit(s)
core-tenant: 1 commit(s)
Push all? [y/N] y
✓ core-php
✓ core-admin
✓ core-tenant
```
## See Also
- [commit command](../commit/) - Create commits before pushing
- [pull command](../pull/) - Pull updates from remote
- [work command](../work/) - Full workflow (status + commit + push)

61
docs/cmd/dev/reviews/index.md
View file

@ -1,61 +0,0 @@
# core dev reviews
List PRs needing review across all repositories.
Fetches open PRs from GitHub for all repos in the registry. Shows review status (approved, changes requested, pending). Requires the `gh` CLI to be installed and authenticated.
## Usage
```bash
core dev reviews [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--all` | Show all PRs including drafts |
| `--author` | Filter by PR author |
## Examples
```bash
# List PRs needing review
core dev reviews
# Include draft PRs
core dev reviews --all
# Filter by author
core dev reviews --author username
```
## Output
```
core-php (2 PRs)
#45 feat: Add caching layer ✓ approved @alice
#43 fix: Memory leak in worker ⏳ pending @bob
core-admin (1 PR)
#28 refactor: Extract components ✗ changes @charlie
```
## Review Status
| Symbol | Meaning |
|--------|---------|
| `✓` | Approved |
| `⏳` | Pending review |
| `✗` | Changes requested |
## Requirements
- GitHub CLI (`gh`) must be installed
- Must be authenticated: `gh auth login`
## See Also
- [issues command](../issues/) - List open issues
- [ci command](../ci/) - Check CI status

33
docs/cmd/dev/work/example.md
View file

@ -1,33 +0,0 @@
# 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 │
└─────────────┴────────┴──────────┴─────────┘
```
## Registry
```yaml
repos:
- name: core
path: ./core
url: https://forge.lthn.ai/core/cli
- name: core-php
path: ./core-php
url: https://forge.lthn.ai/core/cli-php
```

293
docs/cmd/dev/work/index.md
View file

@ -1,293 +0,0 @@
# core dev work
Multi-repo git operations for managing the host-uk organization.
## Overview
The `core dev work` command and related subcommands help manage multiple repositories in the host-uk ecosystem simultaneously.
## Commands
| Command | Description |
|---------|-------------|
| `core dev work` | Full workflow: status + commit + push |
| `core dev work --status` | Status table only |
| `core dev work --commit` | Use Claude to commit dirty repos |
| `core dev health` | Quick health check across all repos |
| `core dev commit` | Claude-assisted commits across repos |
| `core dev push` | Push commits across all repos |
| `core dev pull` | Pull updates across all repos |
| `core dev issues` | List open issues across all repos |
| `core dev reviews` | List PRs needing review |
| `core dev ci` | Check CI status across all repos |
| `core dev impact` | Show impact of changing a repo |
## core dev work
Manage git status, commits, and pushes across multiple repositories.
```bash
core dev work [flags]
```
Reads `repos.yaml` to discover repositories and their relationships. Shows status, optionally commits with Claude, and pushes changes.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--status` | Show status only, don't push |
| `--commit` | Use Claude to commit dirty repos before pushing |
### Examples
```bash
# Full workflow
core dev work
# Status only
core dev work --status
# Commit and push
core dev work --commit
```
## core dev health
Quick health check showing summary of repository health across all repos.
```bash
core dev health [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--verbose` | Show detailed breakdown |
Output shows:
- Total repos
- Dirty repos
- Unpushed commits
- Repos behind remote
### Examples
```bash
# Quick summary
core dev health
# Detailed breakdown
core dev health --verbose
```
## core dev issues
List open issues across all repositories.
```bash
core dev issues [flags]
```
Fetches open issues from GitHub for all repos in the registry. Requires the `gh` CLI to be installed and authenticated.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--assignee` | Filter by assignee (use `@me` for yourself) |
| `--limit` | Max issues per repo (default: 10) |
### Examples
```bash
# List all open issues
core dev issues
# Filter by assignee
core dev issues --assignee @me
# Limit results
core dev issues --limit 5
```
## core dev reviews
List pull requests needing review across all repos.
```bash
core dev reviews [flags]
```
Fetches open PRs from GitHub for all repos in the registry. Shows review status (approved, changes requested, pending). Requires the `gh` CLI to be installed and authenticated.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--all` | Show all PRs including drafts |
| `--author` | Filter by PR author |
### Examples
```bash
# List PRs needing review
core dev reviews
# Show all PRs including drafts
core dev reviews --all
# Filter by author
core dev reviews --author username
```
## core dev commit
Create commits across repos with Claude assistance.
```bash
core dev commit [flags]
```
Uses Claude to create commits for dirty repos. Shows uncommitted changes and invokes Claude to generate commit messages.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--all` | Commit all dirty repos without prompting |
### Examples
```bash
# Commit with prompts
core dev commit
# Commit all automatically
core dev commit --all
```
## core dev push
Push commits across all repos.
```bash
core dev push [flags]
```
Pushes unpushed commits for all repos. Shows repos with commits to push and confirms before pushing.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--force` | Skip confirmation prompt |
### Examples
```bash
# Push with confirmation
core dev push
# Skip confirmation
core dev push --force
```
## core dev pull
Pull updates across all repos.
```bash
core dev pull [flags]
```
Pulls updates for all repos. By default only pulls repos that are behind. Use `--all` to pull all repos.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--all` | Pull all repos, not just those behind |
### Examples
```bash
# Pull repos that are behind
core dev pull
# Pull all repos
core dev pull --all
```
## core dev ci
Check GitHub Actions workflow status across all repos.
```bash
core dev ci [flags]
```
Fetches GitHub Actions workflow status for all repos. Shows latest run status for each repo. Requires the `gh` CLI to be installed and authenticated.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
| `--branch` | Filter by branch (default: main) |
| `--failed` | Show only failed runs |
### Examples
```bash
# Show CI status for all repos
core dev ci
# Show only failed runs
core dev ci --failed
# Check specific branch
core dev ci --branch develop
```
## core dev impact
Show the impact of changing a repository.
```bash
core dev impact <repo> [flags]
```
Analyzes the dependency graph to show which repos would be affected by changes to the specified repo.
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to `repos.yaml` (auto-detected if not specified) |
### Examples
```bash
# Show impact of changing core-php
core dev impact core-php
```
## Registry
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.
## See Also
- [setup command](../../setup/) - Clone repos from registry
- [search command](../../pkg/search/) - Find and install repos

14
docs/cmd/docs/example.md
View file

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

110
docs/cmd/docs/index.md
View file

@ -1,110 +0,0 @@
# core docs
Documentation management across repositories.
## Usage
```bash
core docs <command> [flags]
```
## Commands
| Command | Description |
|---------|-------------|
| `list` | List documentation across repos |
| `sync` | Sync documentation to output directory |
## docs list
Show documentation coverage across all repos.
```bash
core docs list [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml |
### Output
```
Repo README CLAUDE CHANGELOG docs/
──────────────────────────────────────────────────────────────────────
core ✓ ✓ — 12 files
core-php ✓ ✓ ✓ 8 files
core-images ✓ — — —
Coverage: 3 with docs, 0 without
```
## docs sync
Sync documentation from all repos to an output directory.
```bash
core docs sync [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml |
| `--output` | Output directory (default: ./docs-build) |
| `--dry-run` | Show what would be synced |
### Output Structure
```
docs-build/
└── packages/
├── core/
│ ├── index.md # from README.md
│ ├── claude.md # from CLAUDE.md
│ ├── changelog.md # from CHANGELOG.md
│ ├── build.md # from docs/build.md
│ └── ...
└── core-php/
├── index.md
└── ...
```
### Example
```bash
# Preview what will be synced
core docs sync --dry-run
# Sync to default output
core docs sync
# Sync to custom directory
core docs sync --output ./site/content
```
## What Gets Synced
For each repo, the following files are collected:
| Source | Destination |
|--------|-------------|
| `README.md` | `index.md` |
| `CLAUDE.md` | `claude.md` |
| `CHANGELOG.md` | `changelog.md` |
| `docs/*.md` | `*.md` |
## Integration with core.help
The synced docs are used to build https://core.help:
1. Run `core docs sync --output ../core-php/docs/packages`
2. VitePress builds the combined documentation
3. Deploy to core.help
## See Also
- [Configuration](../../configuration.md) - Project configuration

20
docs/cmd/doctor/example.md
View file

@ -1,20 +0,0 @@
# 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
```

81
docs/cmd/doctor/index.md
View file

@ -1,81 +0,0 @@
# core doctor
Check your development environment for required tools and configuration.
## Usage
```bash
core doctor [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--verbose` | Show detailed version information |
## What It Checks
### Required Tools
| Tool | Purpose |
|------|---------|
| `git` | Version control |
| `go` | Go compiler |
| `gh` | GitHub CLI |
### Optional Tools
| Tool | Purpose |
|------|---------|
| `node` | Node.js runtime |
| `docker` | Container runtime |
| `wails` | Desktop app framework |
| `qemu` | VM runtime for LinuxKit |
| `gpg` | Code signing |
| `codesign` | macOS signing (macOS only) |
### Configuration
- Git user name and email
- GitHub CLI authentication
- Go workspace setup
## Output
```
Core Doctor
===========
Required:
[OK] git 2.43.0
[OK] go 1.23.0
[OK] gh 2.40.0
Optional:
[OK] node 20.10.0
[OK] docker 24.0.7
[--] wails (not installed)
[OK] qemu 8.2.0
[OK] gpg 2.4.3
[OK] codesign (available)
Configuration:
[OK] git user.name: Your Name
[OK] git user.email: you@example.com
[OK] gh auth status: Logged in
All checks passed!
```
## Exit Codes
| Code | Meaning |
|------|---------|
| 0 | All required checks passed |
| 1 | One or more required checks failed |
## See Also
- [setup command](../setup/) - Clone repos from registry
- [dev](../dev/) - Development environment

18
docs/cmd/go/cov/example.md
View file

@ -1,18 +0,0 @@
# 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
```

28
docs/cmd/go/cov/index.md
View file

@ -1,28 +0,0 @@
# core go cov
Generate coverage report with thresholds.
## Usage
```bash
core go cov [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--pkg` | Package to test (default: `./...`) |
| `--html` | Generate HTML coverage report |
| `--open` | Generate and open HTML report in browser |
| `--threshold` | Minimum coverage percentage (exit 1 if below) |
## Examples
```bash
core go cov # Summary
core go cov --html # HTML report
core go cov --open # Open in browser
core go cov --threshold 80 # Fail if < 80%
core go cov --pkg ./pkg/release # Specific package
```

89
docs/cmd/go/example.md
View file

@ -1,89 +0,0 @@
# Go Examples
## Testing
```bash
# Run 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
```
## Coverage
```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
```
## Formatting
```bash
# Check
core go fmt
# Fix
core go fmt --fix
# Show diff
core go fmt --diff
```
## Linting
```bash
# Check
core go lint
# Auto-fix
core go lint --fix
```
## Installing
```bash
# Auto-detect cmd/
core go install
# Specific path
core go install ./cmd/myapp
# Pure Go (no CGO)
core go install --no-cgo
```
## Module Management
```bash
core go mod tidy
core go mod download
core go mod verify
core go mod graph
```
## Workspace
```bash
core go work sync
core go work init
core go work use ./pkg/mymodule
```

12
docs/cmd/go/fmt/example.md
View file

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

25
docs/cmd/go/fmt/index.md
View file

@ -1,25 +0,0 @@
# core go fmt
Format Go code using goimports or gofmt.
## Usage
```bash
core go fmt [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--fix` | Fix formatting in place |
| `--diff` | Show diff of changes |
| `--check` | Check only, exit 1 if not formatted |
## Examples
```bash
core go fmt # Check formatting
core go fmt --fix # Fix formatting
core go fmt --diff # Show diff
```

15
docs/cmd/go/index.md
View file

@ -1,15 +0,0 @@
# core go
Go development tools with enhanced output and environment setup.
## Subcommands
| Command | Description |
|---------|-------------|
| [test](test/) | Run tests with coverage |
| [cov](cov/) | Run tests with coverage report |
| [fmt](fmt/) | Format Go code |
| [lint](lint/) | Run golangci-lint |
| [install](install/) | Install Go binary |
| [mod](mod/) | Module management |
| [work](work/) | Workspace management |

15
docs/cmd/go/install/example.md
View file

@ -1,15 +0,0 @@
# 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
```

25
docs/cmd/go/install/index.md
View file

@ -1,25 +0,0 @@
# core go install
Install Go binary with auto-detection.
## Usage
```bash
core go install [path] [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--no-cgo` | Disable CGO |
| `-v` | Verbose |
## Examples
```bash
core go install # Install current module
core go install ./cmd/core # Install specific path
core go install --no-cgo # Pure Go (no C dependencies)
core go install -v # Verbose output
```

22
docs/cmd/go/lint/example.md
View file

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

22
docs/cmd/go/lint/index.md
View file

@ -1,22 +0,0 @@
# core go lint
Run golangci-lint.
## Usage
```bash
core go lint [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--fix` | Fix issues automatically |
## Examples
```bash
core go lint # Check
core go lint --fix # Auto-fix
```

29
docs/cmd/go/mod/download/index.md
View file

@ -1,29 +0,0 @@
# core go mod download
Download modules to local cache.
Wrapper around `go mod download`. Downloads all dependencies to the module cache.
## Usage
```bash
core go mod download
```
## What It Does
- Downloads all modules in go.mod to `$GOPATH/pkg/mod`
- Useful for pre-populating cache for offline builds
- Validates checksums against go.sum
## Examples
```bash
# Download all dependencies
core go mod download
```
## See Also
- [tidy](../tidy/) - Clean up go.mod
- [verify](../verify/) - Verify checksums

15
docs/cmd/go/mod/example.md
View file

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

44
docs/cmd/go/mod/graph/index.md
View file

@ -1,44 +0,0 @@
# core go mod graph
Print module dependency graph.
Wrapper around `go mod graph`. Outputs the module dependency graph in text form.
## Usage
```bash
core go mod graph
```
## What It Does
- Prints module dependencies as pairs
- Each line shows: `module@version dependency@version`
- Useful for understanding dependency relationships
## Examples
```bash
# Print dependency graph
core go mod graph
# Find who depends on a specific module
core go mod graph | grep "some/module"
# Visualise with graphviz
core go mod graph | dot -Tpng -o deps.png
```
## Output
```
forge.lthn.ai/core/cli github.com/stretchr/testify@v1.11.1
github.com/stretchr/testify@v1.11.1 github.com/davecgh/go-spew@v1.1.2
github.com/stretchr/testify@v1.11.1 github.com/pmezard/go-difflib@v1.0.1
...
```
## See Also
- [tidy](../tidy/) - Clean up go.mod
- [dev impact](../../../dev/impact/) - Show repo dependency impact

21
docs/cmd/go/mod/index.md
View file

@ -1,21 +0,0 @@
# core go mod
Module management.
## Subcommands
| Command | Description |
|---------|-------------|
| `tidy` | Add missing and remove unused modules |
| `download` | Download modules to local cache |
| `verify` | Verify dependencies |
| `graph` | Print module dependency graph |
## Examples
```bash
core go mod tidy
core go mod download
core go mod verify
core go mod graph
```

29
docs/cmd/go/mod/tidy/index.md
View file

@ -1,29 +0,0 @@
# core go mod tidy
Add missing and remove unused modules.
Wrapper around `go mod tidy`. Ensures go.mod and go.sum are in sync with the source code.
## Usage
```bash
core go mod tidy
```
## What It Does
- Adds missing module requirements
- Removes unused module requirements
- Updates go.sum with checksums
## Examples
```bash
# Tidy the current module
core go mod tidy
```
## See Also
- [download](../download/) - Download modules
- [verify](../verify/) - Verify dependencies

41
docs/cmd/go/mod/verify/index.md
View file

@ -1,41 +0,0 @@
# core go mod verify
Verify dependencies have not been modified.
Wrapper around `go mod verify`. Checks that dependencies in the module cache match their checksums in go.sum.
## Usage
```bash
core go mod verify
```
## What It Does
- Verifies each module in the cache
- Compares against go.sum checksums
- Reports any tampering or corruption
## Examples
```bash
# Verify all dependencies
core go mod verify
```
## Output
```
all modules verified
```
Or if verification fails:
```
github.com/example/pkg v1.2.3: dir has been modified
```
## See Also
- [download](../download/) - Download modules
- [tidy](../tidy/) - Clean up go.mod

27
docs/cmd/go/test/example.md
View file

@ -1,27 +0,0 @@
# 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
```

31
docs/cmd/go/test/index.md
View file

@ -1,31 +0,0 @@
# core go test
Run Go tests with coverage and filtered output.
## Usage
```bash
core go test [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--pkg` | Package to test (default: `./...`) |
| `--run` | Run only tests matching regexp |
| `--short` | Run only short tests |
| `--race` | Enable race detector |
| `--coverage` | Show detailed per-package coverage |
| `--json` | Output JSON results |
| `-v` | Verbose output |
## Examples
```bash
core go test # All tests
core go test --pkg ./pkg/core # Specific package
core go test --run TestHash # Specific test
core go test --coverage # With coverage
core go test --race # Race detection
```

19
docs/cmd/go/work/index.md
View file

@ -1,19 +0,0 @@
# core go work
Go workspace management commands.
## Subcommands
| Command | Description |
|---------|-------------|
| `sync` | Sync go.work with modules |
| `init` | Initialize go.work |
| `use` | Add module to workspace |
## Examples
```bash
core go work sync # Sync workspace
core go work init # Initialize workspace
core go work use ./pkg/mymodule # Add module to workspace
```

40
docs/cmd/go/work/init/index.md
View file

@ -1,40 +0,0 @@
# core go work init
Initialize a Go workspace.
Wrapper around `go work init`. Creates a new go.work file in the current directory.
## Usage
```bash
core go work init
```
## What It Does
- Creates a go.work file
- Automatically adds current module if go.mod exists
- Enables multi-module development
## Examples
```bash
# Initialize workspace
core go work init
# Then add more modules
core go work use ./pkg/mymodule
```
## Generated File
```go
go 1.25
use .
```
## See Also
- [use](../use/) - Add module to workspace
- [sync](../sync/) - Sync workspace

35
docs/cmd/go/work/sync/index.md
View file

@ -1,35 +0,0 @@
# core go work sync
Sync go.work with modules.
Wrapper around `go work sync`. Synchronises the workspace's build list back to the workspace modules.
## Usage
```bash
core go work sync
```
## What It Does
- Updates each module's go.mod to match the workspace build list
- Ensures all modules use compatible dependency versions
- Run after adding new modules or updating dependencies
## Examples
```bash
# Sync workspace
core go work sync
```
## When To Use
- After running `go get` to update a dependency
- After adding a new module with `core go work use`
- When modules have conflicting dependency versions
## See Also
- [init](../init/) - Initialize workspace
- [use](../use/) - Add module to workspace

46
docs/cmd/go/work/use/index.md
View file

@ -1,46 +0,0 @@
# core go work use
Add module to workspace.
Wrapper around `go work use`. Adds one or more modules to the go.work file.
## Usage
```bash
core go work use [paths...]
```
## What It Does
- Adds specified module paths to go.work
- Auto-discovers modules if no paths given
- Enables developing multiple modules together
## Examples
```bash
# Add a specific module
core go work use ./pkg/mymodule
# Add multiple modules
core go work use ./pkg/one ./pkg/two
# Auto-discover and add all modules
core go work use
```
## Auto-Discovery
When called without arguments, scans for go.mod files and adds all found modules:
```bash
core go work use
# Added ./pkg/build
# Added ./pkg/repos
# Added ./cmd/core
```
## See Also
- [init](../init/) - Initialize workspace
- [sync](../sync/) - Sync workspace

31
docs/cmd/index.md
View file

@ -1,31 +0,0 @@
# Core CLI
Unified interface for Go/PHP development, multi-repo management, and deployment.
## Commands
| Command | Description |
|---------|-------------|
| [ai](ai/) | AI agent task management and Claude integration |
| [go](go/) | Go development tools |
| [php](php/) | Laravel/PHP development tools |
| [build](build/) | Build projects |
| [ci](ci/) | Publish releases |
| [sdk](sdk/) | SDK validation and compatibility |
| [dev](dev/) | Multi-repo workflow + dev environment |
| [pkg](pkg/) | Package management |
| [vm](vm/) | LinuxKit VM management |
| [docs](docs/) | Documentation management |
| [setup](setup/) | Clone repos from registry |
| [doctor](doctor/) | Check environment |
| [test](test/) | Run Go tests with coverage |
## Installation
```bash
go install forge.lthn.ai/core/cli/cmd/core@latest
```
Verify: `core doctor`
See [Getting Started](../getting-started.md) for all installation options.

111
docs/cmd/php/example.md
View file

@ -1,111 +0,0 @@
# PHP Examples
## Development
```bash
# Start all services
core php dev
# With HTTPS
core php dev --https
# Skip services
core php dev --no-vite --no-horizon
```
## Testing
```bash
# Run all
core php test
# Parallel
core php test --parallel
# With coverage
core php test --coverage
# Filter
core php test --filter UserTest
```
## Code Quality
```bash
# Format
core php fmt --fix
# Static analysis
core php analyse --level 9
```
## Deployment
```bash
# Production
core php deploy
# Staging
core php deploy --staging
# Wait for completion
core php deploy --wait
# Check status
core php deploy:status
# Rollback
core php deploy:rollback
```
## Configuration
### .env
```env
COOLIFY_URL=https://coolify.example.com
COOLIFY_TOKEN=your-api-token
COOLIFY_APP_ID=production-app-id
COOLIFY_STAGING_APP_ID=staging-app-id
```
### .core/php.yaml
```yaml
version: 1
dev:
domain: myapp.test
ssl: true
services:
- frankenphp
- vite
- horizon
- reverb
- redis
deploy:
coolify:
server: https://coolify.example.com
project: my-project
```
## Package Linking
```bash
# Link local packages
core php packages link ../my-package
# Update linked
core php packages update
# Unlink
core php packages unlink my-package
```
## SSL Setup
```bash
core php ssl
core php ssl --domain myapp.test
```

413
docs/cmd/php/index.md
View file

@ -1,413 +0,0 @@
# core php
Laravel/PHP development tools with FrankenPHP.
## Commands
### Development
| Command | Description |
|---------|-------------|
| [`dev`](#php-dev) | Start development environment |
| [`logs`](#php-logs) | View service logs |
| [`stop`](#php-stop) | Stop all services |
| [`status`](#php-status) | Show service status |
| [`ssl`](#php-ssl) | Setup SSL certificates with mkcert |
### Build & Production
| Command | Description |
|---------|-------------|
| [`build`](#php-build) | Build Docker or LinuxKit image |
| [`serve`](#php-serve) | Run production container |
| [`shell`](#php-shell) | Open shell in running container |
### Code Quality
| Command | Description |
|---------|-------------|
| [`test`](#php-test) | Run PHP tests (PHPUnit/Pest) |
| [`fmt`](#php-fmt) | Format code with Laravel Pint |
| [`analyse`](#php-analyse) | Run PHPStan static analysis |
### Package Management
| Command | Description |
|---------|-------------|
| [`packages link`](#php-packages-link) | Link local packages by path |
| [`packages unlink`](#php-packages-unlink) | Unlink packages by name |
| [`packages update`](#php-packages-update) | Update linked packages |
| [`packages list`](#php-packages-list) | List linked packages |
### Deployment (Coolify)
| Command | Description |
|---------|-------------|
| [`deploy`](#php-deploy) | Deploy to Coolify |
| [`deploy:status`](#php-deploystatus) | Show deployment status |
| [`deploy:rollback`](#php-deployrollback) | Rollback to previous deployment |
| [`deploy:list`](#php-deploylist) | List recent deployments |
---
## php dev
Start the Laravel development environment with all detected services.
```bash
core php dev [flags]
```
### Services Orchestrated
- **FrankenPHP/Octane** - HTTP server (port 8000, HTTPS on 443)
- **Vite** - Frontend dev server (port 5173)
- **Laravel Horizon** - Queue workers
- **Laravel Reverb** - WebSocket server (port 8080)
- **Redis** - Cache and queue backend (port 6379)
### Flags
| Flag | Description |
|------|-------------|
| `--no-vite` | Skip Vite dev server |
| `--no-horizon` | Skip Laravel Horizon |
| `--no-reverb` | Skip Laravel Reverb |
| `--no-redis` | Skip Redis server |
| `--https` | Enable HTTPS with mkcert |
| `--domain` | Domain for SSL certificate (default: from APP_URL) |
| `--port` | FrankenPHP port (default: 8000) |
### Examples
```bash
# Start all detected services
core php dev
# With HTTPS
core php dev --https
# Skip optional services
core php dev --no-horizon --no-reverb
```
---
## php logs
Stream unified logs from all running services.
```bash
core php logs [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--follow` | Follow log output |
| `--service` | Specific service (frankenphp, vite, horizon, reverb, redis) |
---
## php stop
Stop all running Laravel services.
```bash
core php stop
```
---
## php status
Show the status of all Laravel services and project configuration.
```bash
core php status
```
---
## php ssl
Setup local SSL certificates using mkcert.
```bash
core php ssl [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--domain` | Domain for certificate (default: from APP_URL or localhost) |
---
## php build
Build a production-ready container image.
```bash
core php build [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--type` | Build type: `docker` (default) or `linuxkit` |
| `--name` | Image name (default: project directory name) |
| `--tag` | Image tag (default: latest) |
| `--platform` | Target platform (e.g., linux/amd64, linux/arm64) |
| `--dockerfile` | Path to custom Dockerfile |
| `--output` | Output path for LinuxKit image |
| `--format` | LinuxKit format: qcow2 (default), iso, raw, vmdk |
| `--template` | LinuxKit template name (default: server-php) |
| `--no-cache` | Build without cache |
### Examples
```bash
# Build Docker image
core php build
# With custom name and tag
core php build --name myapp --tag v1.0
# Build LinuxKit image
core php build --type linuxkit
```
---
## php serve
Run a production container.
```bash
core php serve [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--name` | Docker image name (required) |
| `--tag` | Image tag (default: latest) |
| `--container` | Container name |
| `--port` | HTTP port (default: 80) |
| `--https-port` | HTTPS port (default: 443) |
| `-d` | Run in detached mode |
| `--env-file` | Path to environment file |
### Examples
```bash
core php serve --name myapp
core php serve --name myapp -d
core php serve --name myapp --port 8080
```
---
## php shell
Open an interactive shell in a running container.
```bash
core php shell <container-id>
```
---
## php test
Run PHP tests using PHPUnit or Pest.
```bash
core php test [flags]
```
Auto-detects Pest if `tests/Pest.php` exists.
### Flags
| Flag | Description |
|------|-------------|
| `--parallel` | Run tests in parallel |
| `--coverage` | Generate code coverage |
| `--filter` | Filter tests by name pattern |
| `--group` | Run only tests in specified group |
### Examples
```bash
core php test
core php test --parallel --coverage
core php test --filter UserTest
```
---
## php fmt
Format PHP code using Laravel Pint.
```bash
core php fmt [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--fix` | Auto-fix formatting issues |
| `--diff` | Show diff of changes |
---
## php analyse
Run PHPStan or Larastan static analysis.
```bash
core php analyse [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--level` | PHPStan analysis level (0-9) |
| `--memory` | Memory limit (e.g., 2G) |
---
## php packages link
Link local PHP packages for development.
```bash
core php packages link <path> [<path>...]
```
Adds path repositories to composer.json with symlink enabled.
---
## php packages unlink
Remove linked packages from composer.json.
```bash
core php packages unlink <name> [<name>...]
```
---
## php packages update
Update linked packages via Composer.
```bash
core php packages update [<name>...]
```
---
## php packages list
List all locally linked packages.
```bash
core php packages list
```
---
## php deploy
Deploy the PHP application to Coolify.
```bash
core php deploy [flags]
```
### Configuration
Requires environment variables in `.env`:
```
COOLIFY_URL=https://coolify.example.com
COOLIFY_TOKEN=your-api-token
COOLIFY_APP_ID=production-app-id
COOLIFY_STAGING_APP_ID=staging-app-id
```
### Flags
| Flag | Description |
|------|-------------|
| `--staging` | Deploy to staging environment |
| `--force` | Force deployment even if no changes detected |
| `--wait` | Wait for deployment to complete |
---
## php deploy:status
Show the status of a deployment.
```bash
core php deploy:status [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--staging` | Check staging environment |
| `--id` | Specific deployment ID |
---
## php deploy:rollback
Rollback to a previous deployment.
```bash
core php deploy:rollback [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--staging` | Rollback staging environment |
| `--id` | Specific deployment ID to rollback to |
| `--wait` | Wait for rollback to complete |
---
## php deploy:list
List recent deployments.
```bash
core php deploy:list [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--staging` | List staging deployments |
| `--limit` | Number of deployments (default: 10) |
---
## Configuration
Optional `.core/php.yaml` - see [Configuration](example.md#configuration) for examples.

36
docs/cmd/pkg/example.md
View file

@ -1,36 +0,0 @@
# 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
```

144
docs/cmd/pkg/index.md
View file

@ -1,144 +0,0 @@
# core pkg
Package management for host-uk repositories.
## Usage
```bash
core pkg <command> [flags]
```
## Commands
| Command | Description |
|---------|-------------|
| [`search`](#pkg-search) | Search GitHub for packages |
| [`install`](#pkg-install) | Clone a package from GitHub |
| [`list`](#pkg-list) | List installed packages |
| [`update`](#pkg-update) | Update installed packages |
| [`outdated`](#pkg-outdated) | Check for outdated packages |
---
## pkg search
Search GitHub for host-uk packages.
```bash
core pkg search [flags]
```
Results are cached for 1 hour in `.core/cache/`.
### Flags
| Flag | Description |
|------|-------------|
| `--org` | GitHub organisation (default: host-uk) |
| `--pattern` | Repo name pattern (* for wildcard) |
| `--type` | Filter by type in name (mod, services, plug, website) |
| `--limit` | Max results (default: 50) |
| `--refresh` | Bypass cache and fetch fresh data |
### Examples
```bash
# List all repos in org
core pkg search
# Search for core-* repos
core pkg search --pattern 'core-*'
# Search different org
core pkg search --org mycompany
# Bypass cache
core pkg search --refresh
```
---
## pkg install
Clone a package from GitHub.
```bash
core pkg install <org/repo> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--dir` | Target directory (default: ./packages or current dir) |
| `--add` | Add to repos.yaml registry |
### Examples
```bash
# Clone to packages/
core pkg install host-uk/core-php
# Clone to custom directory
core pkg install host-uk/core-tenant --dir ./packages
# Clone and add to registry
core pkg install host-uk/core-admin --add
```
---
## pkg list
List installed packages from repos.yaml.
```bash
core pkg list
```
Shows installed status (✓) and description for each package.
---
## pkg update
Pull latest changes for installed packages.
```bash
core pkg update [<name>...] [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--all` | Update all packages |
### Examples
```bash
# Update specific package
core pkg update core-php
# Update all packages
core pkg update --all
```
---
## pkg outdated
Check which packages have unpulled commits.
```bash
core pkg outdated
```
Fetches from remote and shows packages that are behind.
---
## See Also
- [setup](../setup/) - Clone all repos from registry
- [dev work](../dev/work/) - Multi-repo workflow

23
docs/cmd/pkg/search/example.md
View file

@ -1,23 +0,0 @@
# 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 │
└──────────────┴─────────────────────────────┘
```

75
docs/cmd/pkg/search/index.md
View file

@ -1,75 +0,0 @@
# 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 [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--pattern` | Repo name pattern (* for wildcard) |
| `--org` | GitHub organization (default: host-uk) |
| `--type` | Filter by type in name (mod, services, plug, website) |
| `--limit` | Max results (default: 50) |
| `--refresh` | Bypass cache and fetch fresh data |
## Examples
```bash
# List all host-uk repos
core pkg search
# Search for core-* repos
core pkg search --pattern "core-*"
# Search different org
core pkg search --org mycompany
# Filter by type
core pkg search --type services
# Bypass cache
core pkg search --refresh
# Combine filters
core pkg search --pattern "core-*" --type mod --limit 20
```
## Output
```
Found 5 repositories:
host-uk/core
Go CLI for the host-uk ecosystem
★ 42 Go Updated 2 hours ago
host-uk/core-php
PHP/Laravel packages for Core
★ 18 PHP Updated 1 day ago
host-uk/core-images
Docker and LinuxKit images
★ 8 Dockerfile Updated 3 days ago
```
## Authentication
Uses GitHub CLI (`gh`) authentication. Ensure you're logged in:
```bash
gh auth status
gh auth login # if not authenticated
```
## See Also
- [pkg install](../) - Clone a package from GitHub
- [setup command](../../setup/) - Clone all repos from registry

35
docs/cmd/sdk/example.md
View file

@ -1,35 +0,0 @@
# 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
```

106
docs/cmd/sdk/index.md
View file

@ -1,106 +0,0 @@
# core sdk
SDK validation and API compatibility tools.
To generate SDKs, use: `core build sdk`
## Usage
```bash
core sdk <command> [flags]
```
## Commands
| Command | Description |
|---------|-------------|
| `diff` | Check for breaking API changes |
| `validate` | Validate OpenAPI spec |
## sdk validate
Validate an OpenAPI specification file.
```bash
core sdk validate [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--spec` | Path to OpenAPI spec file (auto-detected) |
### Examples
```bash
# Validate detected spec
core sdk validate
# Validate specific file
core sdk validate --spec api/openapi.yaml
```
## sdk diff
Check for breaking changes between API versions.
```bash
core sdk diff [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `--base` | Base spec version (git tag or file path) |
| `--spec` | Current spec file (auto-detected) |
### Examples
```bash
# Compare against previous release
core sdk diff --base v1.0.0
# Compare two files
core sdk diff --base old-api.yaml --spec new-api.yaml
```
### Breaking Changes Detected
- Removed endpoints
- Changed parameter types
- Removed required fields
- Changed response types
## SDK Generation
SDK generation is handled by `core build sdk`, not this command.
```bash
# Generate SDKs
core build sdk
# Generate specific language
core build sdk --lang typescript
# Preview without writing
core build sdk --dry-run
```
See [build sdk](../build/sdk/) for generation details.
## Spec Auto-Detection
Core looks for OpenAPI specs in this order:
1. Path specified in config (`sdk.spec`)
2. `openapi.yaml` / `openapi.json`
3. `api/openapi.yaml` / `api/openapi.json`
4. `docs/openapi.yaml` / `docs/openapi.json`
5. Laravel Scramble endpoint (`/docs/api.json`)
## See Also
- [build sdk](../build/sdk/) - Generate SDKs from OpenAPI
- [ci command](../ci/) - Release workflow

293
docs/cmd/setup/example.md
View file

@ -1,293 +0,0 @@
# Setup Examples
## Clone from Registry
```bash
# Clone all repos defined in repos.yaml
core setup
# Preview what would be cloned
core setup --dry-run
# Only foundation packages
core setup --only foundation
# Multiple types
core setup --only foundation,module
# Use specific registry file
core setup --registry ~/projects/repos.yaml
```
## Bootstrap New Workspace
```bash
# In an empty directory - bootstraps in place
mkdir my-workspace && cd my-workspace
core setup
# Shows interactive wizard to select packages:
# ┌─────────────────────────────────────────────┐
# │ Select packages to clone │
# │ Use space to select, enter to confirm │
# │ │
# │ ── Foundation (core framework) ── │
# │ ☑ core-php Foundation framework │
# │ ☑ core-tenant Multi-tenancy module │
# │ │
# │ ── Products (applications) ── │
# │ ☐ core-bio Link-in-bio product │
# │ ☐ core-social Social scheduling │
# └─────────────────────────────────────────────┘
# Non-interactive: clone all packages
core setup --all
# Create workspace in subdirectory
cd ~/Code
core setup --name my-project
# CI mode: fully non-interactive
core setup --all --name ci-test
```
## Setup Single Repository
```bash
# In a git repo without .core/ configuration
cd ~/Code/my-go-project
core setup
# Shows choice dialog:
# ┌─────────────────────────────────────────────┐
# │ Setup options │
# │ You're in a git repository. What would you │
# │ like to do? │
# │ │
# │ ● Setup this repo (create .core/ config) │
# │ ○ Create a new workspace (clone repos) │
# └─────────────────────────────────────────────┘
# Preview generated configuration
core setup --dry-run
# Output:
# → Setting up repository configuration
#
# ✓ Detected project type: go
# → Also found: (none)
#
# → Would create:
# /Users/you/Code/my-go-project/.core/build.yaml
#
# Configuration preview:
# version: 1
# project:
# name: my-go-project
# description: Go application
# main: ./cmd/my-go-project
# binary: my-go-project
# ...
```
## Configuration Files
### repos.yaml (Workspace Registry)
```yaml
org: host-uk
base_path: .
defaults:
ci: github
license: EUPL-1.2
branch: main
repos:
core-php:
type: foundation
description: Foundation framework
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-bio:
type: product
depends_on: [core-php, core-tenant]
description: Link-in-bio product
domain: bio.host.uk.com
core-devops:
type: foundation
clone: false # Already exists, skip cloning
```
### .core/build.yaml (Repository Config)
Generated for Go projects:
```yaml
version: 1
project:
name: my-project
description: Go application
main: ./cmd/my-project
binary: my-project
build:
cgo: false
flags:
- -trimpath
ldflags:
- -s
- -w
env: []
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
sign:
enabled: false
```
Generated for Wails projects:
```yaml
version: 1
project:
name: my-app
description: Wails desktop application
main: .
binary: my-app
targets:
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
- os: linux
arch: amd64
```
### .core/release.yaml (Release Config)
Generated for Go projects:
```yaml
version: 1
project:
name: my-project
repository: owner/my-project
changelog:
include:
- feat
- fix
- perf
- refactor
exclude:
- chore
- docs
- style
- test
publishers:
- type: github
draft: false
prerelease: false
```
### .core/test.yaml (Test Config)
Generated for Go projects:
```yaml
version: 1
commands:
- name: unit
run: go test ./...
- name: coverage
run: go test -coverprofile=coverage.out ./...
- name: race
run: go test -race ./...
env:
CGO_ENABLED: "0"
```
Generated for PHP projects:
```yaml
version: 1
commands:
- name: unit
run: vendor/bin/pest --parallel
- name: types
run: vendor/bin/phpstan analyse
- name: lint
run: vendor/bin/pint --test
env:
APP_ENV: testing
DB_CONNECTION: sqlite
```
Generated for Node.js projects:
```yaml
version: 1
commands:
- name: unit
run: npm test
- name: lint
run: npm run lint
- name: typecheck
run: npm run typecheck
env:
NODE_ENV: test
```
## Workflow Examples
### New Developer Setup
```bash
# Clone the workspace
mkdir host-uk && cd host-uk
core setup
# Select packages in wizard, then:
core health # Check all repos are healthy
core doctor # Verify environment
```
### CI Pipeline Setup
```bash
# Non-interactive full clone
core setup --all --name workspace
# Or with specific packages
core setup --only foundation,module --name workspace
```
### Adding Build Config to Existing Repo
```bash
cd my-existing-project
core setup # Choose "Setup this repo"
# Edit .core/build.yaml as needed
core build # Build the project
```

213
docs/cmd/setup/index.md
View file

@ -1,213 +0,0 @@
# core setup
Clone repositories from registry or bootstrap a new workspace.
## Overview
The `setup` command operates in three modes:
1. **Registry mode** - When `repos.yaml` exists nearby, clones repositories into packages/
2. **Bootstrap mode** - When no registry exists, clones `core-devops` first, then presents an interactive wizard to select packages
3. **Repo setup mode** - When run in a git repo root, offers to create `.core/build.yaml` configuration
## Usage
```bash
core setup [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--registry` | Path to repos.yaml (auto-detected if not specified) |
| `--dry-run` | Show what would be cloned without cloning |
| `--only` | Only clone repos of these types (comma-separated: foundation,module,product) |
| `--all` | Skip wizard, clone all packages (non-interactive) |
| `--name` | Project directory name for bootstrap mode |
| `--build` | Run build after cloning |
---
## Registry Mode
When `repos.yaml` is found nearby (current directory or parents), setup clones all defined repositories:
```bash
# In a directory with repos.yaml
core setup
# Preview what would be cloned
core setup --dry-run
# Only clone foundation packages
core setup --only foundation
# Multiple types
core setup --only foundation,module
```
In registry mode with a TTY, an interactive wizard allows you to select which packages to clone. Use `--all` to skip the wizard and clone everything.
---
## Bootstrap Mode
When no `repos.yaml` exists, setup enters bootstrap mode:
```bash
# In an empty directory - bootstraps workspace in place
mkdir my-project && cd my-project
core setup
# In a non-empty directory - creates subdirectory
cd ~/Code
core setup --name my-workspace
# Non-interactive: clone all packages
core setup --all --name ci-test
```
Bootstrap mode:
1. Detects if current directory is empty
2. If not empty, prompts for project name (or uses `--name`)
3. Clones `core-devops` (contains `repos.yaml`)
4. Loads the registry from core-devops
5. Shows interactive package selection wizard (unless `--all`)
6. Clones selected packages
7. Optionally runs build (with `--build`)
---
## Repo Setup Mode
When run in a git repository root (without `repos.yaml`), setup offers two choices:
1. **Setup Working Directory** - Creates `.core/build.yaml` based on detected project type
2. **Create Package** - Creates a subdirectory and clones packages there
```bash
cd ~/Code/my-go-project
core setup
# Output:
# >> This directory is a git repository
# > Setup Working Directory
# Create Package (clone repos into subdirectory)
```
Choosing "Setup Working Directory" detects the project type and generates configuration:
| Detected File | Project Type |
|---------------|--------------|
| `wails.json` | Wails |
| `go.mod` | Go |
| `composer.json` | PHP |
| `package.json` | Node.js |
Creates three config files in `.core/`:
| File | Purpose |
|------|---------|
| `build.yaml` | Build targets, flags, output settings |
| `release.yaml` | Changelog format, GitHub release config |
| `test.yaml` | Test commands, environment variables |
Also auto-detects GitHub repo from git remote for release config.
See [Configuration Files](example.md#configuration-files) for generated config examples.
---
## Interactive Wizard
When running in a terminal (TTY), the setup command presents an interactive multi-select wizard:
- Packages are grouped by type (foundation, module, product, template)
- Use arrow keys to navigate
- Press space to select/deselect packages
- Type to filter the list
- Press enter to confirm selection
The wizard is skipped when:
- `--all` flag is specified
- Not running in a TTY (e.g., CI pipelines)
- `--dry-run` is specified
---
## Examples
### Clone from Registry
```bash
# Clone all repos (interactive wizard)
core setup
# Clone all repos (non-interactive)
core setup --all
# Preview without cloning
core setup --dry-run
# Only foundation packages
core setup --only foundation
```
### Bootstrap New Workspace
```bash
# Interactive bootstrap in empty directory
mkdir workspace && cd workspace
core setup
# Non-interactive with all packages
core setup --all --name my-project
# Bootstrap and run build
core setup --all --name my-project --build
```
---
## Registry Format
The registry file (`repos.yaml`) defines repositories. See [Configuration Files](example.md#configuration-files) for format.
---
## Finding Registry
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`
---
## After Setup
```bash
# Check workspace health
core dev health
# Full workflow (status + commit + push)
core dev work
# Build the project
core build
# Run tests
core go test # Go projects
core php test # PHP projects
```
---
## See Also
- [dev work](../dev/work/) - Multi-repo operations
- [build](../build/) - Build projects
- [doctor](../doctor/) - Check environment

8
docs/cmd/test/example.md
View file

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

74
docs/cmd/test/index.md
View file

@ -1,74 +0,0 @@
# core test
Run Go tests with coverage reporting.
Sets `MACOSX_DEPLOYMENT_TARGET=26.0` to suppress linker warnings on macOS.
## Usage
```bash
core test [flags]
```
## Flags
| Flag | Description |
|------|-------------|
| `--coverage` | Show detailed per-package coverage |
| `--json` | Output JSON for CI/agents |
| `--pkg` | Package pattern to test (default: ./...) |
| `--race` | Enable race detector |
| `--run` | Run only tests matching this regex |
| `--short` | Skip long-running tests |
| `--verbose` | Show test output as it runs |
## Examples
```bash
# Run all tests with coverage summary
core test
# Show test output as it runs
core test --verbose
# Detailed per-package coverage
core test --coverage
# Test specific packages
core test --pkg ./pkg/...
# Run specific test by name
core test --run TestName
# Run tests matching pattern
core test --run "Test.*Good"
# Skip long-running tests
core test --short
# Enable race detector
core test --race
# Output JSON for CI/agents
core test --json
```
## JSON Output
With `--json`, outputs structured results:
```json
{
"passed": 14,
"failed": 0,
"skipped": 0,
"coverage": 75.1,
"exit_code": 0,
"failed_packages": []
}
```
## See Also
- [go test](../go/test/) - Go-specific test options
- [go cov](../go/cov/) - Coverage reports

52
docs/cmd/vm/example.md
View file

@ -1,52 +0,0 @@
# VM Examples
## Running VMs
```bash
# Run image
core vm run server.iso
# Detached with resources
core vm run -d --memory 4096 --cpus 4 server.iso
# From template
core vm run --template core-dev --var SSH_KEY="ssh-rsa AAAA..."
```
## Management
```bash
# List running
core vm ps
# Include stopped
core vm ps -a
# Stop
core vm stop abc123
# View logs
core vm logs abc123
# Follow logs
core vm logs -f abc123
# Execute command
core vm exec abc123 ls -la
# Shell
core vm exec abc123 /bin/sh
```
## Templates
```bash
# List
core vm templates
# Show content
core vm templates show core-dev
# Show variables
core vm templates vars core-dev
```

163
docs/cmd/vm/index.md
View file

@ -1,163 +0,0 @@
# core vm
LinuxKit VM management.
LinuxKit VMs are lightweight, immutable VMs built from YAML templates.
They run using qemu or hyperkit depending on your system.
## Usage
```bash
core vm <command> [flags]
```
## Commands
| Command | Description |
|---------|-------------|
| [`run`](#vm-run) | Run a LinuxKit image or template |
| [`ps`](#vm-ps) | List running VMs |
| [`stop`](#vm-stop) | Stop a VM |
| [`logs`](#vm-logs) | View VM logs |
| [`exec`](#vm-exec) | Execute command in VM |
| [templates](templates/) | Manage LinuxKit templates |
---
## vm run
Run a LinuxKit image or build from a template.
```bash
core vm run <image> [flags]
core vm run --template <name> [flags]
```
Supported image formats: `.iso`, `.qcow2`, `.vmdk`, `.raw`
### Flags
| Flag | Description |
|------|-------------|
| `--template` | Run from a LinuxKit template (build + run) |
| `--var` | Template variable in KEY=VALUE format (repeatable) |
| `--name` | Name for the container |
| `--memory` | Memory in MB (default: 1024) |
| `--cpus` | CPU count (default: 1) |
| `--ssh-port` | SSH port for exec commands (default: 2222) |
| `-d` | Run in detached mode (background) |
### Examples
```bash
# Run from image file
core vm run image.iso
# Run detached with more resources
core vm run -d image.qcow2 --memory 2048 --cpus 4
# Run from template
core vm run --template core-dev --var SSH_KEY="ssh-rsa AAAA..."
# Multiple template variables
core vm run --template server-php --var SSH_KEY="..." --var DOMAIN=example.com
```
---
## vm ps
List running VMs.
```bash
core vm ps [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `-a` | Show all (including stopped) |
### Output
```
ID NAME IMAGE STATUS STARTED PID
abc12345 myvm ...core-dev.qcow2 running 5m 12345
```
---
## vm stop
Stop a running VM by ID or name.
```bash
core vm stop <id>
```
Supports partial ID matching.
### Examples
```bash
# Full ID
core vm stop abc12345678
# Partial ID
core vm stop abc1
```
---
## vm logs
View VM logs.
```bash
core vm logs <id> [flags]
```
### Flags
| Flag | Description |
|------|-------------|
| `-f` | Follow log output |
### Examples
```bash
# View logs
core vm logs abc12345
# Follow logs
core vm logs -f abc1
```
---
## vm exec
Execute a command in a running VM via SSH.
```bash
core vm exec <id> <command...>
```
### Examples
```bash
# List files
core vm exec abc12345 ls -la
# Open shell
core vm exec abc1 /bin/sh
```
---
## See Also
- [templates](templates/) - Manage LinuxKit templates
- [build](../build/) - Build LinuxKit images
- [dev](../dev/) - Dev environment management

53
docs/cmd/vm/templates/example.md
View file

@ -1,53 +0,0 @@
# 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..."
```
## Template Format
`.core/linuxkit/myserver.yml`:
```yaml
kernel:
image: linuxkit/kernel:5.15
cmdline: "console=tty0"
init:
- linuxkit/init:v1.0.0
services:
- name: sshd
image: linuxkit/sshd:v1.0.0
- name: myapp
image: ghcr.io/myorg/myapp:latest
```

124
docs/cmd/vm/templates/index.md
View file

@ -1,124 +0,0 @@
# core vm templates
Manage LinuxKit templates for container images.
## Usage
```bash
core vm templates [command]
```
## Commands
| Command | Description |
|---------|-------------|
| `list` | List available templates |
| `show` | Show template details |
| `vars` | Show template variables |
## templates list
List all available LinuxKit templates.
```bash
core vm templates list
```
### Output
```
Available Templates:
core-dev
Full development environment with 100+ tools
Platforms: linux/amd64, linux/arm64
server-php
FrankenPHP production server
Platforms: linux/amd64, linux/arm64
edge-node
Minimal edge deployment
Platforms: linux/amd64, linux/arm64
```
## templates show
Show details of a specific template.
```bash
core vm templates show <name>
```
### Example
```bash
core vm templates show core-dev
```
Output:
```
Template: core-dev
Description: Full development environment with 100+ tools
Platforms:
- linux/amd64
- linux/arm64
Formats:
- iso
- qcow2
Services:
- sshd
- docker
- frankenphp
Size: ~1.8GB
```
## templates vars
Show variables defined by a template.
```bash
core vm templates vars <name>
```
### Example
```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)
```
## Template Locations
Templates are searched in order:
1. `.core/linuxkit/` - Project-specific
2. `~/.core/templates/` - User templates
3. Built-in templates
## Creating Templates
Create a LinuxKit YAML in `.core/linuxkit/`. See [Template Format](example.md#template-format) for examples.
Run with:
```bash
core vm run --template myserver
```
## See Also
- [vm command](../) - Run LinuxKit images
- [build command](../../build/) - Build LinuxKit images

380
docs/configuration.md
View file

@ -1,380 +0,0 @@
# Configuration
Core uses `.core/` directory for project configuration.
## Directory Structure
```
.core/
├── release.yaml # Release configuration
├── build.yaml # Build configuration (optional)
├── php.yaml # PHP configuration (optional)
└── linuxkit/ # LinuxKit templates
├── server.yml
└── dev.yml
```
## release.yaml
Full release configuration reference:
```yaml
version: 1
project:
name: myapp
repository: myorg/myapp
build:
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
publishers:
# GitHub Releases (required - others reference these artifacts)
- type: github
prerelease: false
draft: false
# npm binary wrapper
- type: npm
package: "@myorg/myapp"
access: public # or "restricted"
# Homebrew formula
- type: homebrew
tap: myorg/homebrew-tap
formula: myapp
official:
enabled: false
output: dist/homebrew
# Scoop manifest (Windows)
- type: scoop
bucket: myorg/scoop-bucket
official:
enabled: false
output: dist/scoop
# AUR (Arch Linux)
- type: aur
maintainer: "Name <email>"
# Chocolatey (Windows)
- type: chocolatey
push: false # true to publish
# Docker multi-arch
- type: docker
registry: ghcr.io
image: myorg/myapp
dockerfile: Dockerfile
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
build_args:
VERSION: "{{.Version}}"
# LinuxKit images
- type: linuxkit
config: .core/linuxkit/server.yml
formats:
- iso
- qcow2
- docker
platforms:
- linux/amd64
- linux/arm64
changelog:
include:
- feat
- fix
- perf
- refactor
exclude:
- chore
- docs
- style
- test
- ci
```
## build.yaml
Optional build configuration:
```yaml
version: 1
project:
name: myapp
binary: myapp
build:
main: ./cmd/myapp
env:
CGO_ENABLED: "0"
flags:
- -trimpath
ldflags:
- -s -w
- -X main.version={{.Version}}
- -X main.commit={{.Commit}}
targets:
- os: linux
arch: amd64
- os: darwin
arch: arm64
```
## php.yaml
PHP/Laravel configuration:
```yaml
version: 1
dev:
domain: myapp.test
ssl: true
port: 8000
services:
- frankenphp
- vite
- horizon
- reverb
- redis
test:
parallel: true
coverage: true
thresholds:
statements: 40
branches: 35
deploy:
coolify:
server: https://coolify.example.com
project: my-project
environment: production
```
## LinuxKit Templates
LinuxKit YAML configuration:
```yaml
kernel:
image: linuxkit/kernel:6.6
cmdline: "console=tty0 console=ttyS0"
init:
- linuxkit/init:latest
- linuxkit/runc:latest
- linuxkit/containerd:latest
- linuxkit/ca-certificates:latest
onboot:
- name: sysctl
image: linuxkit/sysctl:latest
services:
- name: dhcpcd
image: linuxkit/dhcpcd:latest
- name: sshd
image: linuxkit/sshd:latest
- name: myapp
image: myorg/myapp:latest
capabilities:
- CAP_NET_BIND_SERVICE
files:
- path: /etc/myapp/config.yaml
contents: |
server:
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 |
|----------|-------------|
| `CORE_CONFIG` | Override config directory (default: `~/.core/`) |
| `CORE_REGISTRY` | Override repos.yaml path |
---
## Defaults
If no configuration exists, sensible defaults are used:
- **Targets**: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64, windows/amd64
- **Publishers**: GitHub only
- **Changelog**: feat, fix, perf, refactor included
## Logging
Logging can be configured to rotate and retain logs automatically.
Default retention policy:
- **Max Size**: 100 MB
- **Max Backups**: 5
- **Max Age**: 28 days
Example configuration:
```yaml
level: info
rotation:
filename: "app.log"
max_size: 100 # megabytes
max_backups: 5 # number of old log files to retain
max_age: 28 # days to keep old log files
```

457
docs/ecosystem.md
View file

@ -1,457 +0,0 @@
# Core Go Ecosystem
The Core Go ecosystem is a set of 19 standalone Go modules that form the infrastructure backbone for the host-uk platform and the Lethean network. All modules are hosted under the `forge.lthn.ai/core/` organisation. Each module has its own repository, independent versioning, and a `docs/` directory.
The CLI framework documented in the rest of this site (`forge.lthn.ai/core/cli`) is one node in this graph. The satellite packages listed here are separate repositories that the CLI imports or that stand alone as libraries.
---
## Module Index
| Package | Module Path | Managed By |
|---------|-------------|-----------|
| [go-inference](#go-inference) | `forge.lthn.ai/core/go-inference` | Virgil |
| [go-mlx](#go-mlx) | `forge.lthn.ai/core/go-mlx` | Virgil |
| [go-rocm](#go-rocm) | `forge.lthn.ai/core/go-rocm` | Charon |
| [go-ml](#go-ml) | `forge.lthn.ai/core/go-ml` | Virgil |
| [go-ai](#go-ai) | `forge.lthn.ai/core/go-ai` | Virgil |
| [go-agentic](#go-agentic) | `forge.lthn.ai/core/go-agentic` | Charon |
| [go-rag](#go-rag) | `forge.lthn.ai/core/go-rag` | Charon |
| [go-i18n](#go-i18n) | `forge.lthn.ai/core/go-i18n` | Virgil |
| [go-html](#go-html) | `forge.lthn.ai/core/go-html` | Charon |
| [go-crypt](#go-crypt) | `forge.lthn.ai/core/go-crypt` | Virgil |
| [go-scm](#go-scm) | `forge.lthn.ai/core/go-scm` | Charon |
| [go-p2p](#go-p2p) | `forge.lthn.ai/core/go-p2p` | Charon |
| [go-devops](#go-devops) | `forge.lthn.ai/core/go-devops` | Virgil |
| [go-help](#go-help) | `forge.lthn.ai/core/go-help` | Charon |
| [go-ratelimit](#go-ratelimit) | `forge.lthn.ai/core/go-ratelimit` | Charon |
| [go-session](#go-session) | `forge.lthn.ai/core/go-session` | Charon |
| [go-store](#go-store) | `forge.lthn.ai/core/go-store` | Charon |
| [go-ws](#go-ws) | `forge.lthn.ai/core/go-ws` | Charon |
| [go-webview](#go-webview) | `forge.lthn.ai/core/go-webview` | Charon |
---
## Dependency Graph
The graph below shows import relationships. An arrow `A → B` means A imports B.
```
go-inference (no dependencies — foundation contract)
↑
├── go-mlx (CGO, Apple Silicon Metal GPU)
├── go-rocm (AMD ROCm, llama-server subprocess)
└── go-ml (scoring engine, backends, orchestrator)
↑
└── go-ai (MCP hub, 49 tools)
↑
└── go-agentic (service lifecycle, allowances)
go-rag (Qdrant + Ollama, standalone)
↑
└── go-ai
go-i18n (grammar engine, standalone; Phase 2a imports go-mlx)
go-crypt (standalone)
↑
├── go-p2p (UEPS wire protocol)
└── go-scm (AgentCI dispatch)
go-store (SQLite KV, standalone)
↑
├── go-ratelimit (sliding window limiter)
├── go-session (transcript parser)
└── go-agentic
go-ws (WebSocket hub, standalone)
↑
└── go-ai
go-webview (CDP client, standalone)
↑
└── go-ai
go-html (DOM compositor, standalone)
go-help (help catalogue, standalone)
go-devops (Ansible, build, infrastructure — imports go-scm)
```
The CLI framework (`forge.lthn.ai/core/cli`) has internal equivalents of several of these packages (`pkg/rag`, `pkg/ws`, `pkg/webview`, `pkg/i18n`) that were developed in parallel. The satellite packages are the canonical standalone versions intended for use outside the CLI binary.
---
## Package Descriptions
### go-inference
**Module:** `forge.lthn.ai/core/go-inference`
Zero-dependency interface package that defines the common contract for all inference backends in the ecosystem:
- `TextModel` — the top-level model interface (`Generate`, `Stream`, `Close`)
- `Backend` — hardware/runtime abstraction (Metal, ROCm, CPU, remote)
- `Token` — streaming token type with metadata
No concrete implementations live here. Any package that needs to call inference without depending on a specific hardware library imports `go-inference` and receives an implementation at runtime.
---
### go-mlx
**Module:** `forge.lthn.ai/core/go-mlx`
Native Metal GPU inference for Apple Silicon using CGO bindings to `mlx-c` (the C API for Apple's MLX framework). Implements the `go-inference` interfaces.
Build requirements:
- macOS 13+ (Ventura) on Apple Silicon
- `mlx-c` installed (`brew install mlx`)
- CGO enabled: `CGO_CFLAGS` and `CGO_LDFLAGS` must reference the mlx-c headers and library
Features:
- Loads GGUF and MLX-format models
- Streaming token generation directly on GPU
- Quantised model support (Q4, Q8)
- Phase 4 backend abstraction in progress — will allow hot-swapping backends at runtime
Local path: `/Users/snider/Code/go-mlx`
---
### go-rocm
**Module:** `forge.lthn.ai/core/go-rocm`
AMD ROCm GPU inference for Linux. Rather than using CGO, this package manages a `llama-server` subprocess (from llama.cpp) compiled with ROCm support and communicates over its HTTP API.
Features:
- Subprocess lifecycle management (start, health-check, restart on crash)
- OpenAI-compatible HTTP client wrapping llama-server's API
- Implements `go-inference` interfaces
- Targeted at the homelab RX 7800 XT running Ubuntu 24.04
Managed by Charon (Linux homelab).
---
### go-ml
**Module:** `forge.lthn.ai/core/go-ml`
Scoring engine, backend registry, and agent orchestration layer. The hub that connects models from `go-mlx`, `go-rocm`, and future backends into a unified interface.
Features:
- Backend registry: register multiple inference backends, select by capability
- Scoring pipeline: evaluate model outputs against rubrics
- Agent orchestrator: coordinate multi-step inference tasks
- ~3.5K LOC
---
### go-ai
**Module:** `forge.lthn.ai/core/go-ai`
MCP (Model Context Protocol) server hub with 49 registered tools. Acts as the primary facade for AI capabilities in the ecosystem.
Features:
- 49 MCP tools covering file operations, RAG, metrics, process management, WebSocket, and CDP/webview
- Imports `go-ml`, `go-rag`, `go-mlx`
- Can run as stdio MCP server or TCP MCP server
- AI usage metrics recorded to JSONL
Run the MCP server:
```bash
# stdio (for Claude Desktop / Claude Code)
core mcp serve
# TCP
MCP_ADDR=:9000 core mcp serve
```
---
### go-agentic
**Module:** `forge.lthn.ai/core/go-agentic`
Service lifecycle and allowance management for autonomous agents. Handles:
- Agent session tracking and state persistence
- Allowance system: budget constraints on tool calls, token usage, and wall-clock time
- Integration with `go-store` for persistence
- REST client for the PHP `core-agentic` backend
Managed by Charon.
---
### go-rag
**Module:** `forge.lthn.ai/core/go-rag`
Retrieval-Augmented Generation pipeline using Qdrant for vector storage and Ollama for embeddings.
Features:
- `ChunkMarkdown`: semantic splitting by H2 headers and paragraphs with overlap
- `Ingest`: crawl a directory of Markdown files, embed, and store in Qdrant
- `Query`: semantic search returning ranked `QueryResult` slices
- `FormatResultsContext`: formats results as XML tags for LLM prompt injection
- Clients: `QdrantClient` and `OllamaClient` wrapping their respective Go SDKs
Managed by Charon.
---
### go-i18n
**Module:** `forge.lthn.ai/core/go-i18n`
Grammar engine for natural-language generation. Goes beyond key-value lookup tables to handle pluralisation, verb conjugation, past tense, gerunds, and semantic sentence construction ("Subject verbed object").
Features:
- `T(key, args...)` — main translation function
- `S(noun, value)` — semantic subject with grammatical context
- Language rules defined in JSON; algorithmic fallbacks for irregular verbs
- **GrammarImprint**: a linguistic hash (reversal of the grammar engine) used as a semantic fingerprint — part of the Lethean identity verification stack
- Phase 2a (imports `go-mlx` for language model-assisted reversal) currently blocked on `go-mlx` Phase 4
Local path: `/Users/snider/Code/go-i18n`
---
### go-html
**Module:** `forge.lthn.ai/core/go-html`
HLCRF DOM compositor — a programmatic HTML/DOM construction library targeting both server-side rendering and WASM (browser).
HLCRF stands for Header, Left, Content, Right, Footer — the region layout model used throughout the CLI's terminal UI and web rendering layer.
Features:
- Composable region-based layout (mirrors the terminal `Composite` in `pkg/cli`)
- WASM build target: runs in the browser without JavaScript
- Used by the LEM Chat UI and web SDK generation
Managed by Charon.
---
### go-crypt
**Module:** `forge.lthn.ai/core/go-crypt`
Cryptographic primitives, authentication, and trust policy enforcement.
Features:
- Password hashing (Argon2id with tuned parameters)
- Symmetric encryption (ChaCha20-Poly1305, AES-GCM)
- Key derivation (HKDF, Scrypt)
- OpenPGP challenge-response authentication
- Trust policies: define and evaluate access rules
- Foundation for the UEPS (User-controlled Encryption Policy System) wire protocol in `go-p2p`
---
### go-scm
**Module:** `forge.lthn.ai/core/go-scm`
Source control management and CI integration, including the AgentCI dispatch system.
Features:
- Forgejo and Gitea API clients (typed wrappers)
- GitHub integration via the `gh` CLI
- `AgentCI`: dispatches AI work items to agent runners over SSH using Charm stack libraries (`soft-serve`, `keygen`, `melt`, `wishlist`)
- PR lifecycle management: create, review, merge, label
- JSONL job journal for audit trails
Managed by Charon.
---
### go-p2p
**Module:** `forge.lthn.ai/core/go-p2p`
Peer-to-peer mesh networking implementing the UEPS (User-controlled Encryption Policy System) wire protocol.
Features:
- UEPS: consent-gated TLV frames with Ed25519 consent tokens and an Intent-Broker
- Peer discovery and mesh routing
- Encrypted relay transport
- Integration with `go-crypt` for all cryptographic operations
This is a core component of the Lethean Web3 network layer.
Managed by Charon (Linux homelab).
---
### go-devops
**Module:** `forge.lthn.ai/core/go-devops`
Infrastructure automation, build tooling, and release pipeline utilities, intended as a standalone library form of what the Core CLI provides as commands.
Features:
- Ansible-lite engine (native Go SSH playbook execution)
- LinuxKit image building and VM lifecycle
- Multi-target binary build and release
- Integration with `go-scm` for repository operations
---
### go-help
**Module:** `forge.lthn.ai/core/go-help`
Embedded documentation catalogue with full-text search and an optional HTTP server for serving help content.
Features:
- YAML-frontmatter Markdown topic parsing
- In-memory reverse index with title/heading/body scoring
- Snippet extraction with keyword highlighting
- `HTTP server` mode: serve the catalogue as a documentation site
- Used by the `core pkg search` command and the `pkg/help` package inside the CLI
Managed by Charon.
---
### go-ratelimit
**Module:** `forge.lthn.ai/core/go-ratelimit`
Sliding-window rate limiter with a SQLite persistence backend.
Features:
- Token bucket and sliding-window algorithms
- SQLite backend via `go-store` for durable rate state across restarts
- HTTP middleware helper
- Used by `go-ai` and `go-agentic` to enforce per-agent API quotas
Managed by Charon.
---
### go-session
**Module:** `forge.lthn.ai/core/go-session`
Claude Code JSONL transcript parser and visualisation toolkit (standalone version of `pkg/session` inside the CLI).
Features:
- `ParseTranscript(path)`: reads `.jsonl` session files and reconstructs tool use timelines
- `ListSessions(dir)`: scans a Claude projects directory for session files
- `Search(dir, query)`: full-text search across sessions
- `RenderHTML(sess, path)`: single-file HTML visualisation
- `RenderMP4(sess, path)`: terminal video replay via VHS
Managed by Charon.
---
### go-store
**Module:** `forge.lthn.ai/core/go-store`
SQLite-backed key-value store with reactive change notification.
Features:
- `Get`, `Set`, `Delete`, `List` over typed keys
- `Watch(key, handler)`: register a callback that fires on change
- `OnChange(handler)`: subscribe to all changes
- Used by `go-ratelimit`, `go-session`, and `go-agentic` for lightweight persistence
Managed by Charon.
---
### go-ws
**Module:** `forge.lthn.ai/core/go-ws`
WebSocket hub with channel-based subscriptions and an optional Redis pub/sub bridge for multi-instance deployments.
Features:
- Hub pattern: central registry of connected clients
- Channel routing: `SendToChannel(topic, msg)` delivers only to subscribers
- Redis bridge: publish messages from one instance, receive on all
- HTTP handler: `hub.Handler()` for embedding in any Go HTTP server
- `SendProcessOutput(id, line)`: convenience method for streaming process logs
Managed by Charon.
---
### go-webview
**Module:** `forge.lthn.ai/core/go-webview`
Chrome DevTools Protocol (CDP) client for browser automation, testing, and AI-driven web interaction (standalone version of `pkg/webview` inside the CLI).
Features:
- Navigation, click, type, screenshot
- `Evaluate(script)`: arbitrary JavaScript execution with result capture
- Console capture and filtering
- Angular-aware helpers: `WaitForAngular()`, `GetNgModel(selector)`
- `ActionSequence`: chain interactions into a single call
- Used by `go-ai` to expose browser tools to MCP agents
Managed by Charon.
---
## Forge Repository Paths
All repositories are hosted at `forge.lthn.ai` (Forgejo). SSH access uses port 2223:
```
ssh://git@forge.lthn.ai:2223/core/go-inference.git
ssh://git@forge.lthn.ai:2223/core/go-mlx.git
ssh://git@forge.lthn.ai:2223/core/go-rocm.git
ssh://git@forge.lthn.ai:2223/core/go-ml.git
ssh://git@forge.lthn.ai:2223/core/go-ai.git
ssh://git@forge.lthn.ai:2223/core/go-agentic.git
ssh://git@forge.lthn.ai:2223/core/go-rag.git
ssh://git@forge.lthn.ai:2223/core/go-i18n.git
ssh://git@forge.lthn.ai:2223/core/go-html.git
ssh://git@forge.lthn.ai:2223/core/go-crypt.git
ssh://git@forge.lthn.ai:2223/core/go-scm.git
ssh://git@forge.lthn.ai:2223/core/go-p2p.git
ssh://git@forge.lthn.ai:2223/core/go-devops.git
ssh://git@forge.lthn.ai:2223/core/go-help.git
ssh://git@forge.lthn.ai:2223/core/go-ratelimit.git
ssh://git@forge.lthn.ai:2223/core/go-session.git
ssh://git@forge.lthn.ai:2223/core/go-store.git
ssh://git@forge.lthn.ai:2223/core/go-ws.git
ssh://git@forge.lthn.ai:2223/core/go-webview.git
```
HTTPS authentication is not available on Forge. Always use SSH remotes.
---
## Go Workspace Setup
The satellite packages can be used together in a Go workspace. After cloning the repositories you need:
```bash
go work init
go work use ./go-inference ./go-mlx ./go-rag ./go-ai # add as needed
go work sync
```
The CLI repository already uses a Go workspace that includes `cmd/core-gui`, `cmd/bugseti`, and `cmd/examples/*`.
---
## See Also
- [index.md](index.md) — Main documentation hub
- [getting-started.md](getting-started.md) — CLI installation
- [configuration.md](configuration.md) — `repos.yaml` registry format

83
docs/examples/build-cpp.yaml
View file

@ -1,83 +0,0 @@
# Example: C++ Build Configuration
# CMake + Conan 2 project using host-uk/build system
version: 1
project:
name: my-cpp-project
type: cpp
description: "A C++ application"
cpp:
standard: 17
build_type: Release
static: false
# Conan package manager
conan:
version: "2.21.0"
requires:
- zlib/1.3.1
- boost/1.85.0
- openssl/3.2.0
tool_requires:
- cmake/3.31.9
options:
boost/*:without_test: true
registry:
url: http://forge.snider.dev:4000/api/packages/host-uk/conan
remote: conan_build
# CMake settings
cmake:
minimum_version: "3.16"
variables:
USE_CCACHE: "ON"
presets:
- conan-release
- conan-debug
# Optional project-specific build options
options:
testnet: false
# Cross-compilation targets
targets:
- os: linux
arch: x86_64
profile: gcc-linux-x86_64
- os: linux
arch: arm64
profile: gcc-linux-armv8
- os: darwin
arch: arm64
profile: apple-clang-armv8
- os: darwin
arch: x86_64
profile: apple-clang-x86_64
- os: windows
arch: x86_64
profile: msvc-194-x86_64
# Packaging
package:
generators:
- TGZ
- ZIP
vendor: host-uk
contact: developers@lethean.io
website: https://lt.hn
# Docker output
docker:
dockerfile: .core/build/docker/Dockerfile
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
build_args:
BUILD_THREADS: auto
BUILD_STATIC: "0"
BUILD_TYPE: Release

42
docs/examples/build-docker-go.yaml
View file

@ -1,42 +0,0 @@
# Example: Go + Docker Build Configuration
# Build Go binary then containerize
version: 1
project:
name: myservice
binary: myservice
# First: build Go binary
build:
main: ./cmd/myservice
env:
CGO_ENABLED: "0"
GOOS: linux
ldflags:
- -s -w
- -X main.version={{.Version}}
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
# Then: build Docker image with the binary
docker:
dockerfile: Dockerfile
registry: ghcr.io
image: myorg/myservice
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
# Dockerfile should COPY the built binary:
#
# FROM alpine:latest
# COPY myservice /usr/local/bin/myservice
# ENTRYPOINT ["/usr/local/bin/myservice"]

40
docs/examples/build-docker.yaml
View file

@ -1,40 +0,0 @@
# Example: Docker Build Configuration
# Multi-arch container image
version: 1
project:
name: myservice
type: docker
docker:
dockerfile: Dockerfile
context: .
registry: ghcr.io
image: myorg/myservice
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
- "{{.Version}}-alpine"
build_args:
APP_VERSION: "{{.Version}}"
BUILD_DATE: "{{.Date}}"
labels:
org.opencontainers.image.source: https://github.com/myorg/myservice
org.opencontainers.image.description: My Service
org.opencontainers.image.licenses: MIT
# Optional: build stage target
target: production
# Optional: cache settings
cache:
from: type=gha
to: type=gha,mode=max

121
docs/examples/build-full.yaml
View file

@ -1,121 +0,0 @@
# Example: Full Build Configuration
# All available options
version: 1
project:
name: myapp
binary: myapp
type: auto # auto, go, wails, docker, linuxkit, php
build:
# Go build settings
main: ./cmd/myapp
# Environment variables
env:
CGO_ENABLED: "0"
GOFLAGS: "-mod=readonly"
# Build flags
flags:
- -trimpath
- -v
# Linker flags
ldflags:
- -s -w
- -X main.version={{.Version}}
- -X main.commit={{.Commit}}
- -X main.date={{.Date}}
- -X main.builtBy=core
# Build tags
tags:
- production
- netgo
# Build targets
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: linux
arch: "386"
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
- os: windows
arch: arm64
- os: freebsd
arch: amd64
# Wails configuration (if type: wails)
wails:
frontend: ./frontend
install_cmd: install
build_cmd: build
dev_cmd: dev
# Docker configuration (if type: docker or docker output enabled)
docker:
dockerfile: Dockerfile
context: .
registry: ghcr.io
image: myorg/myapp
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
build_args:
VERSION: "{{.Version}}"
labels:
org.opencontainers.image.source: https://github.com/myorg/myapp
target: production
cache:
from: type=gha
to: type=gha,mode=max
# LinuxKit configuration (if type: linuxkit)
linuxkit:
config: .core/linuxkit/server.yml
formats:
- iso
- qcow2
- docker
platforms:
- linux/amd64
- linux/arm64
# Archive settings
archive:
format: tar.gz
format_windows: zip
name: "{{.Project}}-{{.Version}}-{{.OS}}-{{.Arch}}"
files:
- LICENSE
- README.md
- CHANGELOG.md
strip_parent: true
# Checksum settings
checksum:
algorithm: sha256
file: checksums.txt
# Hooks
hooks:
pre_build:
- go generate ./...
- go mod tidy
post_build:
- echo "Build complete"
# Output directory
output: dist

39
docs/examples/build-go-cli.yaml
View file

@ -1,39 +0,0 @@
# Example: Go CLI Build Configuration
# Cross-platform CLI tool
version: 1
project:
name: mycli
binary: mycli
build:
main: ./cmd/mycli
env:
CGO_ENABLED: "0"
flags:
- -trimpath
ldflags:
- -s -w
- -X main.version={{.Version}}
- -X main.commit={{.Commit}}
- -X main.date={{.Date}}
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
archive:
format: tar.gz
format_windows: zip
files:
- LICENSE
- README.md

23
docs/examples/build-go-library.yaml
View file

@ -1,23 +0,0 @@
# Example: Go Library Build Configuration
# No binary output, just validation and testing
version: 1
project:
name: mylib
type: library # No binary build
build:
# Library-specific settings
env:
CGO_ENABLED: "0"
# Test configuration
test:
race: true
cover: true
packages:
- ./...
# No targets needed for library
# targets: []

46
docs/examples/build-go-wails.yaml
View file

@ -1,46 +0,0 @@
# Example: Wails Desktop App Build Configuration
# Cross-platform desktop application with web frontend
version: 1
project:
name: myapp
binary: myapp
build:
main: .
env:
CGO_ENABLED: "1" # Required for Wails
ldflags:
- -s -w
- -X main.version={{.Version}}
# Wails-specific configuration
wails:
frontend: ./frontend
# Auto-detects: npm, pnpm, yarn, bun
install_cmd: install
build_cmd: build
targets:
# Desktop platforms only
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
- os: linux
arch: amd64
# Platform-specific packaging
package:
darwin:
- dmg
- app
windows:
- nsis
- zip
linux:
- tar.gz
- appimage

33
docs/examples/build-linuxkit.yaml
View file

@ -1,33 +0,0 @@
# Example: LinuxKit Build Configuration
# Immutable Linux images
version: 1
project:
name: myserver
type: linuxkit
linuxkit:
config: .core/linuxkit/server.yml
formats:
- iso # Bootable ISO (BIOS/EFI)
- qcow2 # QEMU/KVM/Proxmox
- raw # Raw disk image
- vmdk # VMware
- docker # Docker-loadable tarball
platforms:
- linux/amd64
- linux/arm64
# Output naming
name: "{{.Project}}-{{.Version}}"
# The linuxkit config file (.core/linuxkit/server.yml) defines:
# - kernel version
# - init system
# - services to run
# - files to include
#
# See linuxkit-server.yml example

7
docs/examples/build-minimal.yaml
View file

@ -1,7 +0,0 @@
# Example: Minimal Build Configuration
# Auto-detects everything from project structure
version: 1
project:
name: myapp

51
docs/examples/build-multi-binary.yaml
View file

@ -1,51 +0,0 @@
# Example: Multi-Binary Build Configuration
# Multiple binaries from one repository
version: 1
project:
name: mytools
# Multiple build targets
builds:
- name: cli
binary: mytool
main: ./cmd/mytool
ldflags:
- -s -w
- -X main.version={{.Version}}
- name: server
binary: myserver
main: ./cmd/server
ldflags:
- -s -w
- -X main.version={{.Version}}
- name: worker
binary: myworker
main: ./cmd/worker
ldflags:
- -s -w
# Shared settings
build:
env:
CGO_ENABLED: "0"
flags:
- -trimpath
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: darwin
arch: arm64
# Archive includes all binaries
archive:
format: tar.gz
files:
- LICENSE
- README.md

50
docs/examples/build-php-laravel.yaml
View file

@ -1,50 +0,0 @@
# Example: PHP/Laravel Build Configuration
# FrankenPHP container with Laravel app
version: 1
project:
name: mylaravel
type: php
php:
version: "8.4"
# Composer settings
composer:
install_args:
- --no-dev
- --optimize-autoloader
- --no-interaction
# Frontend build
frontend:
enabled: true
build_cmd: "npm run build"
# Octane configuration
octane:
server: frankenphp
workers: auto
max_requests: 500
# Docker output
docker:
dockerfile: Dockerfile
registry: ghcr.io
image: myorg/mylaravel
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
build_args:
PHP_VERSION: "8.4"
# Optional: LinuxKit for immutable deployment
linuxkit:
config: .core/linuxkit/server-php.yml
formats:
- qcow2
- iso

29
docs/examples/linuxkit-docker.yml
View file

@ -1,29 +0,0 @@
# Example: LinuxKit Docker Format
# Build immutable container that loads with `docker load`
kernel:
image: linuxkit/kernel:6.6
cmdline: "console=tty0"
init:
- linuxkit/init:latest
- linuxkit/runc:latest
- linuxkit/containerd:latest
services:
- name: myservice
image: ghcr.io/myorg/myservice:latest
# Use in release.yaml:
#
# publishers:
# - type: linuxkit
# config: .core/linuxkit/docker-format.yml
# formats:
# - docker # Outputs .docker.tar
# platforms:
# - linux/amd64
# - linux/arm64
#
# Load the image:
# docker load < linuxkit-v1.0.0-amd64.docker.tar

51
docs/examples/linuxkit-server.yml
View file

@ -1,51 +0,0 @@
# Example: LinuxKit Server Configuration
# Minimal immutable Linux server with your application
kernel:
image: linuxkit/kernel:6.6
cmdline: "console=tty0 console=ttyS0"
init:
- linuxkit/init:latest
- linuxkit/runc:latest
- linuxkit/containerd:latest
- linuxkit/ca-certificates:latest
onboot:
- name: sysctl
image: linuxkit/sysctl:latest
- name: dhcpcd
image: linuxkit/dhcpcd:latest
services:
# SSH for management
- name: sshd
image: linuxkit/sshd:latest
binds:
- /etc/ssh/authorized_keys:/root/.ssh/authorized_keys
# Your application
- name: myapp
image: ghcr.io/myorg/myapp:latest
capabilities:
- CAP_NET_BIND_SERVICE
binds:
- /etc/myapp:/etc/myapp:ro
files:
# SSH authorized keys
- path: /etc/ssh/authorized_keys
mode: "0600"
contents: |
ssh-ed25519 AAAA... your-key
# Application config
- path: /etc/myapp/config.yaml
mode: "0644"
contents: |
server:
host: 0.0.0.0
port: 8080
database:
host: ${DB_HOST:-localhost}
port: ${DB_PORT:-5432}

68
docs/examples/publish-all.yaml
View file

@ -1,68 +0,0 @@
# Example: All Publishers Combined
# Use in .core/release.yaml publishers array
publishers:
# 1. GitHub - always first (others reference these artifacts)
- type: github
prerelease: false
draft: false
# 2. npm - JavaScript ecosystem
- type: npm
package: "@myorg/mycli"
access: public
# 3. Homebrew - macOS/Linux
- type: homebrew
tap: myorg/homebrew-tap
official:
enabled: true
output: dist/homebrew
# 4. Scoop - Windows
- type: scoop
bucket: myorg/scoop-bucket
official:
enabled: true
output: dist/scoop
# 5. AUR - Arch Linux
- type: aur
maintainer: "Your Name <your@email.com>"
# 6. Chocolatey - Windows enterprise
- type: chocolatey
push: false
# 7. Docker - Containers
- type: docker
registry: ghcr.io
image: myorg/mycli
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
# 8. LinuxKit - Immutable infrastructure
- type: linuxkit
config: .core/linuxkit/server.yml
formats:
- iso
- qcow2
- docker
platforms:
- linux/amd64
- linux/arm64
# Required environment variables:
# GITHUB_TOKEN - via gh CLI auth
# NPM_TOKEN - npm publish
# CHOCOLATEY_API_KEY - if push: true
#
# Required tools:
# gh - GitHub CLI
# npm - Node package manager
# docker - Docker with buildx
# linuxkit - LinuxKit CLI

28
docs/examples/publish-aur.yaml
View file

@ -1,28 +0,0 @@
# Example: AUR Publisher (Arch Linux)
# PKGBUILD generation and AUR push
type: aur
# Package name (will be suffixed with -bin)
package: mycli
# Maintainer info (required by AUR)
maintainer: "Your Name <your@email.com>"
# Generate files only (don't push to AUR)
official:
enabled: true
output: dist/aur
# Environment: SSH key for aur.archlinux.org
#
# Usage after publish:
# yay -S mycli-bin
# # or
# paru -S mycli-bin
#
# Generated files:
# - PKGBUILD
# - .SRCINFO
#
# Supports both x86_64 and aarch64

29
docs/examples/publish-chocolatey.yaml
View file

@ -1,29 +0,0 @@
# Example: Chocolatey Publisher (Windows)
# NuSpec package for Windows enterprise
type: chocolatey
# Package name
package: mycli
# Push to Chocolatey community repo
push: false # Set true to auto-publish
# Generate files only
official:
enabled: true
output: dist/chocolatey
# Environment: CHOCOLATEY_API_KEY required if push: true
#
# Usage after publish:
# choco install mycli
#
# Generated files:
# - mycli.nuspec
# - tools/chocolateyinstall.ps1
#
# Manual publish:
# cd dist/chocolatey
# choco pack
# choco push mycli.1.0.0.nupkg --source https://push.chocolatey.org/

38
docs/examples/publish-docker.yaml
View file

@ -1,38 +0,0 @@
# Example: Docker Publisher
# Multi-arch container images
type: docker
# Registry (default: ghcr.io)
registry: ghcr.io
# Image name
image: myorg/myapp
# Dockerfile path (default: Dockerfile)
dockerfile: Dockerfile
# Target platforms
platforms:
- linux/amd64
- linux/arm64
# Image tags
tags:
- latest
- "{{.Version}}"
- "{{.Version}}-alpine"
# Build arguments
build_args:
VERSION: "{{.Version}}"
BUILD_DATE: "{{.Date}}"
# Environment: Docker login to registry
#
# For ghcr.io:
# echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
#
# Usage after publish:
# docker pull ghcr.io/myorg/myapp:latest
# docker run ghcr.io/myorg/myapp:v1.0.0

14
docs/examples/publish-github.yaml
View file

@ -1,14 +0,0 @@
# Example: GitHub Releases Publisher
# Foundation publisher - others reference these artifacts
type: github
# Release settings
prerelease: false
draft: false
# Auto-detect from git tag, or override
# version: v1.0.0
# Auto-detect from git remote, or specify
# repository: myorg/myapp

29
docs/examples/publish-homebrew.yaml
View file

@ -1,29 +0,0 @@
# Example: Homebrew Publisher
# Formula generation and tap management
type: homebrew
# Your tap repository
tap: myorg/homebrew-tap
# Formula name (defaults to project name)
formula: mycli
# Generate files for official homebrew-core PR
official:
enabled: true
output: dist/homebrew
# Environment: Uses gh CLI authentication
#
# Usage after publish:
# brew tap myorg/tap
# brew install mycli
#
# Or directly:
# brew install myorg/tap/mycli
#
# Generated formula includes:
# - Multi-platform support (macOS Intel/ARM, Linux)
# - SHA256 checksums from GitHub release
# - Version from git tag

36
docs/examples/publish-linuxkit.yaml
View file

@ -1,36 +0,0 @@
# Example: LinuxKit Publisher
# Immutable Linux images uploaded to GitHub release
type: linuxkit
# LinuxKit YAML configuration
config: .core/linuxkit/server.yml
# Output formats
formats:
- iso # Bootable ISO (bare metal, VMs)
- qcow2 # QEMU/KVM/Proxmox
- raw # Raw disk image
- vmdk # VMware
- docker # Docker-loadable tarball
# Target platforms
platforms:
- linux/amd64
- linux/arm64
# Environment: linuxkit CLI installed
#
# Artifacts uploaded to GitHub release:
# - myapp-v1.0.0-amd64.iso
# - myapp-v1.0.0-amd64.qcow2
# - myapp-v1.0.0-amd64.docker.tar
# - myapp-v1.0.0-arm64.iso
# - ...
#
# Usage:
# # Boot ISO
# qemu-system-x86_64 -cdrom myapp-v1.0.0-amd64.iso -m 1024
#
# # Load Docker image
# docker load < myapp-v1.0.0-amd64.docker.tar

21
docs/examples/publish-npm.yaml
View file

@ -1,21 +0,0 @@
# Example: npm Publisher
# Binary wrapper pattern - downloads correct platform binary on install
type: npm
# Package name (scoped recommended)
package: "@myorg/mycli"
# Access level
access: public # or "restricted" for private
# Environment: NPM_TOKEN required
#
# Usage after publish:
# npm install -g @myorg/mycli
# npx @myorg/mycli --help
#
# The published package contains:
# - package.json
# - install.js (postinstall downloads binary)
# - bin/run.js (wrapper that executes binary)

23
docs/examples/publish-scoop.yaml
View file

@ -1,23 +0,0 @@
# Example: Scoop Publisher (Windows)
# JSON manifest for Windows package manager
type: scoop
# Your bucket repository
bucket: myorg/scoop-bucket
# Generate files for official scoop-main PR
official:
enabled: true
output: dist/scoop
# Environment: Uses gh CLI authentication
#
# Usage after publish:
# scoop bucket add myorg https://github.com/myorg/scoop-bucket
# scoop install mycli
#
# Generated manifest includes:
# - 64-bit and ARM64 Windows support
# - SHA256 checksums
# - Auto-update configuration

98
docs/examples/release-full.yaml
View file

@ -1,98 +0,0 @@
# Example: Full Release Configuration
# Complete configuration with all publishers
version: 1
project:
name: core
repository: host-uk/core
build:
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
- os: windows
arch: arm64
publishers:
# 1. GitHub Releases - always first, others reference these
- type: github
prerelease: false
draft: false
# 2. npm - JavaScript ecosystem
- type: npm
package: "@host-uk/core"
access: public
# 3. Homebrew - macOS/Linux
- type: homebrew
tap: host-uk/homebrew-tap
formula: core
# Generate files for official homebrew-core PR
official:
enabled: true
output: dist/homebrew
# 4. Scoop - Windows
- type: scoop
bucket: host-uk/scoop-bucket
# Generate files for official scoop-main PR
official:
enabled: true
output: dist/scoop
# 5. AUR - Arch Linux
- type: aur
maintainer: "Host UK <dev@host.uk.com>"
# 6. Chocolatey - Windows enterprise
- type: chocolatey
push: false # Manual review before push
# 7. Docker - Container deployment
- type: docker
registry: ghcr.io
image: host-uk/core
dockerfile: Dockerfile
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
- "{{.Version}}-alpine"
# 8. LinuxKit - Immutable infrastructure
- type: linuxkit
config: .core/linuxkit/core-server.yml
formats:
- iso # Bootable ISO for bare metal
- qcow2 # QEMU/KVM/Proxmox
- docker # Immutable container
platforms:
- linux/amd64
- linux/arm64
changelog:
include:
- feat # New features
- fix # Bug fixes
- perf # Performance improvements
- refactor # Code refactoring
- security # Security fixes
exclude:
- chore
- docs
- style
- test
- ci
- build

59
docs/examples/release-go-cli.yaml
View file

@ -1,59 +0,0 @@
# Example: Go CLI Release Configuration
# Publishes to GitHub, npm, Homebrew, Scoop, AUR, and Chocolatey
version: 1
project:
name: mycli
repository: myorg/mycli
build:
targets:
- os: linux
arch: amd64
- os: linux
arch: arm64
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
publishers:
# GitHub Releases - foundation for all other publishers
- type: github
prerelease: false
draft: false
# npm - binary wrapper pattern
# Users install via: npm install -g @myorg/mycli
- type: npm
package: "@myorg/mycli"
access: public
# Homebrew - tap repository
# Users install via: brew install myorg/tap/mycli
- type: homebrew
tap: myorg/homebrew-tap
# Scoop - Windows package manager
# Users install via: scoop bucket add myorg https://github.com/myorg/scoop-bucket && scoop install mycli
- type: scoop
bucket: myorg/scoop-bucket
# AUR - Arch Linux User Repository
# Users install via: yay -S mycli-bin
- type: aur
maintainer: "Your Name <your@email.com>"
# Chocolatey - Windows enterprise
# Users install via: choco install mycli
- type: chocolatey
push: false # Set true to auto-publish
changelog:
include:
- feat
- fix
- perf

36
docs/examples/release-go-wails.yaml
View file

@ -1,36 +0,0 @@
# Example: Wails Desktop App Release Configuration
# Builds cross-platform desktop app and publishes to GitHub
version: 1
project:
name: myapp
repository: myorg/myapp
build:
targets:
- os: darwin
arch: amd64
- os: darwin
arch: arm64
- os: windows
arch: amd64
- os: linux
arch: amd64
publishers:
- type: github
prerelease: false
draft: true # Review before publishing
# Homebrew cask for macOS
- type: homebrew
tap: myorg/homebrew-tap
formula: myapp
changelog:
include:
- feat
- fix
- perf
- ui # Custom type for UI changes

11
docs/examples/release-minimal.yaml
View file

@ -1,11 +0,0 @@
# Example: Minimal Release Configuration
# Just GitHub releases with defaults
version: 1
project:
name: myapp
repository: myorg/myapp
publishers:
- type: github

51
docs/examples/release-official-repos.yaml
View file

@ -1,51 +0,0 @@
# Example: Generate Files for Official Repository PRs
# Creates files for PRs to homebrew-core, scoop-main, etc.
version: 1
project:
name: myapp
repository: myorg/myapp
publishers:
- type: github
# Generate formula for homebrew-core PR
# Output: dist/homebrew/myapp.rb
- type: homebrew
tap: myorg/homebrew-tap # Also push to own tap
official:
enabled: true
output: dist/homebrew
# Generate manifest for scoop-main PR
# Output: dist/scoop/myapp.json
- type: scoop
bucket: myorg/scoop-bucket # Also push to own bucket
official:
enabled: true
output: dist/scoop
# Generate files for AUR
# Output: dist/aur/PKGBUILD, dist/aur/.SRCINFO
- type: aur
maintainer: "Your Name <email>"
official:
enabled: true
output: dist/aur
# After release, submit PRs:
#
# Homebrew:
# cd homebrew-core
# cp ../myapp/dist/homebrew/myapp.rb Formula/m/myapp.rb
# git checkout -b myapp-1.0.0
# git add . && git commit -m "myapp 1.0.0 (new formula)"
# gh pr create
#
# Scoop:
# cd Main
# cp ../myapp/dist/scoop/myapp.json bucket/myapp.json
# git checkout -b myapp-1.0.0
# git add . && git commit -m "myapp: Add version 1.0.0"
# gh pr create

42
docs/examples/release-php-laravel.yaml
View file

@ -1,42 +0,0 @@
# Example: PHP/Laravel Release Configuration
# Builds Docker container and LinuxKit image
version: 1
project:
name: mylaravel
repository: myorg/mylaravel
publishers:
- type: github
prerelease: false
# Docker container for deployment
- type: docker
registry: ghcr.io
image: myorg/mylaravel
dockerfile: Dockerfile
platforms:
- linux/amd64
- linux/arm64
tags:
- latest
- "{{.Version}}"
build_args:
PHP_VERSION: "8.4"
APP_ENV: production
# LinuxKit for immutable server deployment
- type: linuxkit
config: .core/linuxkit/server-php.yml
formats:
- iso
- qcow2
platforms:
- linux/amd64
changelog:
include:
- feat
- fix
- security

43
docs/examples/sdk-full.yaml
View file

@ -1,43 +0,0 @@
# Example: Full SDK Configuration
# Generate typed API clients from OpenAPI specs
sdk:
# OpenAPI spec source (auto-detected if omitted)
spec: api/openapi.yaml
# Languages to generate
languages:
- typescript
- python
- go
- php
# Output directory (default: sdk/)
output: sdk/
# Package naming
package:
name: myapi
version: "{{.Version}}"
# Breaking change detection
diff:
enabled: true
fail_on_breaking: true # CI fails on breaking changes
# Optional: publish to monorepo
publish:
repo: myorg/sdks
path: packages/myapi
# Required tools (install one per language):
# TypeScript: npm i -g openapi-typescript-codegen (or Docker)
# Python: pip install openapi-python-client (or Docker)
# Go: go install github.com/oapi-codegen/oapi-codegen/v2/cmd/oapi-codegen@latest
# PHP: Docker required
#
# Usage:
# core sdk generate # Generate all configured languages
# core sdk generate --lang go # Generate single language
# core sdk diff --base v1.0.0 # Check for breaking changes
# core sdk validate # Validate spec

Some files were not shown because too many files have changed in this diff Show more