.forgejo/workflows/deploy.yml

@@ -1,39 +0,0 @@
-name: Build and Deploy
-
-on:
-  push:
-    branches: [main]
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-
-      - name: Install Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.12'
-
-      - name: Install Zensical
-        run: pip install zensical
-
-      - name: Build
-        run: zensical build
-
-      - name: Deploy to BunnyCDN
-        run: |
-          pip install s3cmd
-          cat > ~/.s3cfg <<EOCFG
-          [default]
-          access_key = $AWS_ACCESS_KEY_ID
-          secret_key = $AWS_SECRET_ACCESS_KEY
-          host_base = storage.bunnycdn.com
-          host_bucket = %(bucket)s.storage.bunnycdn.com
-          use_https = True
-          EOCFG
-          s3cmd sync site/ s3://core-help/ --delete-removed --acl-public
-        env:
-          AWS_ACCESS_KEY_ID: ${{ secrets.BUNNY_STORAGE_ZONE }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.BUNNY_STORAGE_KEY }}

.gitignore

@@ -1,5 +0,0 @@
-site/
-.cache/
-.DS_Store
-.core/
-.idea/

CLAUDE.md

@@ -1,57 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Documentation platform for the Core ecosystem (CLI, Go packages, PHP modules, MCP tools). Published at https://core.help. Two main components:
-
-1. **`docs/`** — Markdown source files (217+) with YAML frontmatter, organized by section (Go, PHP, TS, GUI, AI, Tools, Deploy, Publish)
-2. **`pkg/help/`** — Go library for help content management: parsing, search, HTTP serving, and static site generation
-
-## Common Commands
-
-```bash
-# Run all tests
-go test ./...
-
-# Run a single test
-go test ./pkg/help/ -run TestFunctionName
-
-# Run benchmarks
-go test ./pkg/help/ -bench .
-
-# Build the static documentation site (requires Python + zensical)
-pip install zensical
-zensical build
-```
-
-## Architecture: `pkg/help/`
-
-The Go help library is display-agnostic — it can serve HTML, expose a JSON API, or generate a static site from the same content.
-
-**Data flow:** Markdown files → `ParseTopic()` (parser.go) → `Topic` structs → `Catalog` (catalog.go) → consumed by Server, Search, or Generate.
-
-Key types and their roles:
-- **`Topic`/`Frontmatter`** (topic.go) — Data model. Topics have ID, title, content, sections, tags, related links, and sort order. Frontmatter is parsed from YAML `---` blocks.
-- **`Catalog`** (catalog.go) — Topic registry with `Add`, `Get`, `List`, `Search`. `LoadContentDir()` recursively loads `.md` files from a directory. `DefaultCatalog()` provides built-in starter topics.
-- **`searchIndex`** (search.go) — Full-text search with TF-IDF scoring, prefix matching, fuzzy matching, stemming (Porter stemmer in stemmer.go), and phrase detection. Title matches are boosted.
-- **`Server`** (server.go) — HTTP handler with HTML routes (`/`, `/topics/{id}`, `/search`) and JSON API routes (`/api/topics`, `/api/topics/{id}`, `/api/search`).
-- **`Generate*`** (generate.go) — Static site generator producing index, topic pages, 404, and `search-index.json` for client-side search.
-- **`Render*`/`Layout*`** (render.go, layout.go) — HTML rendering using `forge.lthn.ai/core/go-html` (HLCRF layout pattern with dark theme).
-- **`IngestHelp`** (ingest.go) — Converts Go CLI `--help` text output into structured `Topic` objects.
-
-## Site Configuration
-
-`zensical.toml` defines the doc site structure — navigation tree, theme settings, markdown extensions (admonition, mermaid, tabbed content, code highlighting). Zensical is a Python-based static site generator.
-
-## CI/CD
-
-Forgejo workflow (`.forgejo/workflows/deploy.yml`): on push to `main`, builds with `zensical build` and deploys the `site/` directory to BunnyCDN via s3cmd.
-
-## Conventions
-
-- License: EUPL-1.2 (SPDX headers in source files)
-- Go module: `forge.lthn.ai/core/docs`
-- Tests use `testify/assert` and `testify/require`
-- Markdown files use YAML frontmatter (`title`, `tags`, `related`, `order` fields)

build/cli/docs/index.md

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

build/go/configuration.md

@@ -1,60 +1,15 @@
 # Configuration
 
-Core uses `.core/` directory for project configuration. Config files are auto-discovered — commands need zero arguments.
-
-## Quick Reference
-
-| File | Scope | Package | Purpose |
-|------|-------|---------|---------|
-| `~/.core/config.yaml` | User | go-config | Global settings (Viper) |
-| `.core/build.yaml` | Project | go-build | Build targets, flags, signing |
-| `.core/release.yaml` | Project | go-build | Publishers, changelog, SDK gen |
-| `.core/php.yaml` | Project | go-build | PHP/Laravel dev, test, deploy |
-| `.core/test.yaml` | Project | go-container | Named test commands |
-| `.core/manifest.yaml` | App | go-scm | Providers, daemons, permissions |
-| `.core/workspace.yaml` | Workspace | agent | Active package, paths |
-| `.core/repos.yaml` | Workspace | go-scm | Repo registry + dependencies |
-| `.core/work.yaml` | Workspace | go-scm | Sync policy, agent heartbeat |
-| `.core/git.yaml` | Machine | go-scm | Local git state (gitignored) |
-| `.core/kb.yaml` | Workspace | go-scm | Wiki mirror, Qdrant search |
-| `.core/linuxkit/*.yml` | Project | go-container | VM templates |
-
-**Scopes:**
-
-- **User** (`~/.core/`) — global settings, persists across all projects
-- **Project** (`{repo}/.core/`) — per-repository config, checked into git
-- **Workspace** (`{workspace}/.core/`) — multi-repo workspace config, checked into git
-- **Machine** (`{workspace}/.core/`) — per-machine state, gitignored
-
-**Discovery patterns:**
-
-- **Fixed path** — `build.yaml`, `release.yaml`, `test.yaml`, `manifest.yaml`
-- **Walk-up** — `workspace.yaml`, `repos.yaml` (search current dir → parents → home)
-- **Direct load** — `work.yaml`, `git.yaml`, `kb.yaml` (from workspace root)
+Core uses `.core/` directory for project configuration.
 
 ## Directory Structure
 
 ```
-~/.core/                      # User-level (global)
-├── config.yaml               # Global settings
-├── plugins/                  # Plugin discovery
-├── known_hosts               # SSH known hosts
-└── linuxkit/                 # User LinuxKit templates
-
-{workspace}/.core/            # Workspace-level (shared)
-├── workspace.yaml            # Active package, paths
-├── repos.yaml                # Repository registry
-├── work.yaml                 # Sync policy, agent heartbeat
-├── git.yaml                  # Machine-local git state (gitignored)
-└── kb.yaml                   # Knowledge base config
-
-{project}/.core/              # Project-level (per-repo)
-├── build.yaml                # Build configuration
-├── release.yaml              # Release configuration
-├── php.yaml                  # PHP/Laravel configuration
-├── test.yaml                 # Test commands
-├── manifest.yaml             # Application manifest
-└── linuxkit/                 # LinuxKit templates
+.core/
+├── release.yaml      # Release configuration
+├── build.yaml        # Build configuration (optional)
+├── php.yaml          # PHP configuration (optional)
+└── linuxkit/         # LinuxKit templates
     ├── server.yml
     └── dev.yml
 ```
@@ -343,168 +298,6 @@ repos:
 | `product` | User-facing applications | Foundation + modules |
 | `template` | Starter templates | Any |
 
-## workspace.yaml
-
-Workspace-level configuration. Discovered by walking up from CWD.
-
-```yaml
-version: 1
-
-# Active package for unified commands
-active: core-php
-
-# Default package types for setup
-default_only:
-  - foundation
-  - module
-
-# Paths
-packages_dir: ./packages
-
-# Workspace settings
-settings:
-  suggest_core_commands: true
-  show_active_in_prompt: true
-```
-
-**Package:** `forge.lthn.ai/core/agent` · **Discovery:** walk-up from CWD
-
-## work.yaml
-
-Team sync policy. Checked into git (shared across team).
-
-```yaml
-version: 1
-
-sync:
-  interval: 5m
-  auto_pull: true
-  auto_push: false
-  clone_missing: true
-
-agent:
-  heartbeat_interval: 30s
-  stale_after: 10m
-  overlap_warning: true
-
-triggers:
-  on_activate: sync
-  on_commit: push
-  scheduled: "*/5 * * * *"
-```
-
-**Package:** `forge.lthn.ai/core/go-scm/repos` · **Discovery:** `{workspaceRoot}/.core/work.yaml`
-
-## git.yaml
-
-Machine-local git state. **Gitignored** — not shared across machines.
-
-```yaml
-version: 1
-
-repos:
-  core-php:
-    branch: main
-    remote: origin
-    last_pull: "2026-03-15T10:00:00Z"
-    last_push: "2026-03-15T09:45:00Z"
-    ahead: 0
-    behind: 0
-  core-tenant:
-    branch: main
-    remote: origin
-    last_pull: "2026-03-15T10:00:00Z"
-
-agent:
-  name: cladius
-  last_heartbeat: "2026-03-15T10:05:00Z"
-```
-
-**Package:** `forge.lthn.ai/core/go-scm/repos` · **Discovery:** `{workspaceRoot}/.core/git.yaml`
-
-## kb.yaml
-
-Knowledge base configuration. Controls wiki mirroring and vector search.
-
-```yaml
-version: 1
-
-wiki:
-  enabled: true
-  directory: kb          # Relative to .core/
-  remote: "ssh://git@forge.lthn.ai:2223/core/wiki.git"
-
-search:
-  qdrant:
-    host: qdrant.lthn.sh
-    port: 6334
-    collection: openbrain
-  ollama:
-    url: http://ollama.lthn.sh
-    model: embeddinggemma
-  top_k: 10
-```
-
-**Package:** `forge.lthn.ai/core/go-scm/repos` · **Discovery:** `{workspaceRoot}/.core/kb.yaml`
-
-## test.yaml
-
-Named test commands per project. Auto-detected if not present.
-
-```yaml
-version: 1
-
-commands:
-  unit:
-    run: composer test -- --filter=Unit
-    env:
-      APP_ENV: testing
-  integration:
-    run: composer test -- --filter=Integration
-    env:
-      APP_ENV: testing
-      DB_DATABASE: test_db
-  all:
-    run: composer test
-```
-
-**Auto-detection chain** (if no `test.yaml`): `composer.json` → `package.json` → `go.mod` → `pytest` → `Taskfile`
-
-**Package:** `forge.lthn.ai/core/go-container/devenv` · **Discovery:** `{projectDir}/.core/test.yaml`
-
-## manifest.yaml
-
-Application manifest for providers, daemons, and permissions. Supports ed25519 signature verification.
-
-```yaml
-version: 1
-
-app:
-  name: my-provider
-  namespace: my-provider
-  description: Custom service provider
-
-providers:
-  - namespace: my-provider
-    port: 9900
-    binary: ./bin/my-provider
-    args: ["serve"]
-    elements:
-      - tag: my-provider-panel
-        source: /assets/my-provider.js
-
-daemons:
-  - name: worker
-    command: ./bin/worker
-    restart: always
-
-permissions:
-  - net.listen
-  - fs.read
-```
-
-**Package:** `forge.lthn.ai/core/go-scm/manifest` · **Discovery:** `{appRoot}/.core/manifest.yaml`
-
 ---
 
 ## Environment Variables

build/go/index.md

@@ -0,0 +1,98 @@
+# Core Go
+
+Core is a Go framework for the host-uk ecosystem - build, release, and deploy Go, Wails, PHP, and container workloads.
+
+## Installation
+
+```bash
+# Via Go (recommended)
+go install github.com/host-uk/core/cmd/core@latest
+
+# Or download binary from releases
+curl -Lo core https://github.com/host-uk/core/releases/latest/download/core-$(go env GOOS)-$(go env GOARCH)
+chmod +x core && sudo mv core /usr/local/bin/
+
+# Verify
+core doctor
+```
+
+See [Getting Started](getting-started.md) for all installation options including building from source.
+
+## Command Reference
+
+See [CLI](/build/cli/) for full command documentation.
+
+| Command | Description |
+|---------|-------------|
+| [go](/build/cli/go/) | Go development (test, fmt, lint, cov) |
+| [php](/build/cli/php/) | Laravel/PHP development |
+| [build](/build/cli/build/) | Build Go, Wails, Docker, LinuxKit projects |
+| [ci](/build/cli/ci/) | Publish releases (dry-run by default) |
+| [sdk](/build/cli/sdk/) | SDK generation and validation |
+| [dev](/build/cli/dev/) | Multi-repo workflow + dev environment |
+| [pkg](/build/cli/pkg/) | Package search and install |
+| [vm](/build/cli/vm/) | LinuxKit VM management |
+| [docs](/build/cli/docs/) | Documentation management |
+| [setup](/build/cli/setup/) | Clone repos from registry |
+| [doctor](/build/cli/doctor/) | Check development environment |
+
+## Quick Start
+
+```bash
+# Go development
+core go test              # Run tests
+core go test --coverage   # With coverage
+core go fmt               # Format code
+core go lint              # Lint code
+
+# Build
+core build                # Auto-detect and build
+core build --targets linux/amd64,darwin/arm64
+
+# Release (dry-run by default)
+core ci                   # Preview release
+core ci --we-are-go-for-launch  # Actually publish
+
+# Multi-repo workflow
+core dev work             # Status + commit + push
+core dev work --status    # Just show status
+
+# PHP development
+core php dev              # Start dev environment
+core php test             # Run tests
+```
+
+## Configuration
+
+Core uses `.core/` directory for project configuration:
+
+```
+.core/
+├── release.yaml    # Release targets and settings
+├── build.yaml      # Build configuration (optional)
+└── linuxkit/       # LinuxKit templates
+```
+
+And `repos.yaml` in workspace root for multi-repo management.
+
+## Guides
+
+- [Getting Started](getting-started.md) - Installation and first steps
+- [Workflows](workflows.md) - Common task sequences
+- [Troubleshooting](troubleshooting.md) - When things go wrong
+- [Migration](migration.md) - Moving from legacy tools
+
+## Reference
+
+- [Configuration](configuration.md) - All config options
+- [Glossary](glossary.md) - Term definitions
+
+## Claude Code Skill
+
+Install the skill to teach Claude Code how to use the Core CLI:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/host-uk/core/main/.claude/skills/core/install.sh | bash
+```
+
+See [skill/](skill/) for details.