From ed8b61cc5bc0b730c492d734236e657e0da50e05 Mon Sep 17 00:00:00 2001 From: "user.email" Date: Sun, 15 Mar 2026 13:17:03 +0000 Subject: [PATCH] docs: add all .core/ config files to configuration reference Added workspace.yaml, work.yaml, git.yaml, kb.yaml, test.yaml, and manifest.yaml documentation. Added quick reference table with scope, package, and discovery pattern for all 12 config file types. Expanded directory structure to show user/workspace/project scopes. Co-Authored-By: Virgil --- docs/go/configuration.md | 219 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 213 insertions(+), 6 deletions(-) diff --git a/docs/go/configuration.md b/docs/go/configuration.md index deabb68..2976eef 100644 --- a/docs/go/configuration.md +++ b/docs/go/configuration.md @@ -1,15 +1,60 @@ # Configuration -Core uses `.core/` directory for project 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) ## Directory Structure ``` -.core/ -├── release.yaml # Release configuration -├── build.yaml # Build configuration (optional) -├── php.yaml # PHP configuration (optional) -└── linuxkit/ # LinuxKit templates +~/.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 ├── server.yml └── dev.yml ``` @@ -298,6 +343,168 @@ 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