diff --git a/.core/reference/RFC-025-AGENT-EXPERIENCE.md b/.core/reference/RFC-025-AGENT-EXPERIENCE.md
new file mode 100644
index 0000000..a18e6bb
--- /dev/null
+++ b/.core/reference/RFC-025-AGENT-EXPERIENCE.md
@@ -0,0 +1,588 @@
+# RFC-025: Agent Experience (AX) Design Principles
+
+- **Status:** Active
+- **Authors:** Snider, Cladius
+- **Date:** 2026-03-25
+- **Applies to:** All Core ecosystem packages (CoreGO, CorePHP, CoreTS, core-agent)
+
+## Abstract
+
+Agent Experience (AX) is a design paradigm for software systems where the primary code consumer is an AI agent, not a human developer. AX sits alongside User Experience (UX) and Developer Experience (DX) as the third era of interface design.
+
+This RFC establishes AX as a formal design principle for the Core ecosystem and defines the conventions that follow from it.
+
+## Motivation
+
+As of early 2026, AI agents write, review, and maintain the majority of code in the Core ecosystem. The original author has not manually edited code (outside of Core struct design) since October 2025. Code is processed semantically — agents reason about intent, not characters.
+
+Design patterns inherited from the human-developer era optimise for the wrong consumer:
+
+- **Short names** save keystrokes but increase semantic ambiguity
+- **Functional option chains** are fluent for humans but opaque for agents tracing configuration
+- **Error-at-every-call-site** produces 50% boilerplate that obscures intent
+- **Generic type parameters** force agents to carry type context that the runtime already has
+- **Panic-hiding conventions** (`Must*`) create implicit control flow that agents must special-case
+- **Raw exec.Command** bypasses Core primitives — untestable, no entitlement check, path traversal risk
+
+AX acknowledges this shift and provides principles for designing code, APIs, file structures, and conventions that serve AI agents as first-class consumers.
+
+## The Three Eras
+
+| Era | Primary Consumer | Optimises For | Key Metric |
+|-----|-----------------|---------------|------------|
+| UX | End users | Discoverability, forgiveness, visual clarity | Task completion time |
+| DX | Developers | Typing speed, IDE support, convention familiarity | Time to first commit |
+| AX | AI agents | Predictability, composability, semantic navigation | Correct-on-first-pass rate |
+
+AX does not replace UX or DX. End users still need good UX. Developers still need good DX. But when the primary code author and maintainer is an AI agent, the codebase should be designed for that consumer first.
+
+## Principles
+
+### 1. Predictable Names Over Short Names
+
+Names are tokens that agents pattern-match across languages and contexts. Abbreviations introduce mapping overhead.
+
+```
+Config not Cfg
+Service not Srv
+Embed not Emb
+Error not Err (as a subsystem name; err for local variables is fine)
+Options not Opts
+```
+
+**Rule:** If a name would require a comment to explain, it is too short.
+
+**Exception:** Industry-standard abbreviations that are universally understood (`HTTP`, `URL`, `ID`, `IPC`, `I18n`) are acceptable. The test: would an agent trained on any mainstream language recognise it without context?
+
+### 2. Comments as Usage Examples
+
+The function signature tells WHAT. The comment shows HOW with real values.
+
+```go
+// Entitled checks if an action is permitted.
+//
+// e := c.Entitled("process.run")
+// e := c.Entitled("social.accounts", 3)
+// if e.Allowed { proceed() }
+
+// WriteAtomic writes via temp file then rename (safe for concurrent readers).
+//
+// r := fs.WriteAtomic("/status.json", data)
+
+// Action registers or invokes a named callable.
+//
+// c.Action("git.log", handler) // register
+// c.Action("git.log").Run(ctx, opts) // invoke
+```
+
+**Rule:** If a comment restates what the type signature already says, delete it. If a comment shows a concrete usage with realistic values, keep it.
+
+**Rationale:** Agents learn from examples more effectively than from descriptions. A comment like "Run executes the setup process" adds zero information. A comment like `setup.Run(setup.Options{Path: ".", Template: "auto"})` teaches an agent exactly how to call the function.
+
+### 3. Path Is Documentation
+
+File and directory paths should be self-describing. An agent navigating the filesystem should understand what it is looking at without reading a README.
+
+```
+pkg/agentic/dispatch.go — agent dispatch logic
+pkg/agentic/handlers.go — IPC event handlers
+pkg/lib/task/bug-fix.yaml — bug fix plan template
+pkg/lib/persona/engineering/ — engineering personas
+flow/deploy/to/homelab.yaml — deploy TO the homelab
+template/dir/workspace/default/ — default workspace scaffold
+docs/RFC.md — authoritative API contract
+```
+
+**Rule:** If an agent needs to read a file to understand what a directory contains, the directory naming has failed.
+
+**Corollary:** The unified path convention (folder structure = HTTP route = CLI command = test path) is AX-native. One path, every surface.
+
+### 4. Templates Over Freeform
+
+When an agent generates code from a template, the output is constrained to known-good shapes. When an agent writes freeform, the output varies.
+
+```go
+// Template-driven — consistent output
+lib.ExtractWorkspace("default", targetDir, &lib.WorkspaceData{
+ Repo: "go-io", Branch: "dev", Task: "fix tests", Agent: "codex",
+})
+
+// Freeform — variance in output
+"write a workspace setup script that..."
+```
+
+**Rule:** For any code pattern that recurs, provide a template. Templates are guardrails for agents.
+
+**Scope:** Templates apply to file generation, workspace scaffolding, config generation, and commit messages. They do NOT apply to novel logic — agents should write business logic freeform with the domain knowledge available.
+
+### 5. Declarative Over Imperative
+
+Agents reason better about declarations of intent than sequences of operations.
+
+```yaml
+# Declarative — agent sees what should happen
+steps:
+ - name: build
+ flow: tools/docker-build
+ with:
+ context: "{{ .app_dir }}"
+ image_name: "{{ .image_name }}"
+
+ - name: deploy
+ flow: deploy/with/docker
+ with:
+ host: "{{ .host }}"
+```
+
+```go
+// Imperative — agent must trace execution
+cmd := exec.Command("docker", "build", "--platform", "linux/amd64", "-t", imageName, ".")
+cmd.Dir = appDir
+if err := cmd.Run(); err != nil {
+ return core.E("build", "docker build failed", err)
+}
+```
+
+**Rule:** Orchestration, configuration, and pipeline logic should be declarative (YAML/JSON). Implementation logic should be imperative (Go/PHP/TS). The boundary is: if an agent needs to compose or modify the logic, make it declarative.
+
+Core's `Task` is the Go-native declarative equivalent — a sequence of named Action steps:
+
+```go
+c.Task("deploy", core.Task{
+ Steps: []core.Step{
+ {Action: "docker.build"},
+ {Action: "docker.push"},
+ {Action: "deploy.ansible", Async: true},
+ },
+})
+```
+
+### 6. Core Primitives — Universal Types and DI
+
+Every component in the ecosystem registers with Core and communicates through Core's primitives. An agent processing any level of the tree sees identical shapes.
+
+#### Creating Core
+
+```go
+c := core.New(
+ core.WithOption("name", "core-agent"),
+ core.WithService(process.Register),
+ core.WithService(agentic.Register),
+ core.WithService(monitor.Register),
+ core.WithService(brain.Register),
+ core.WithService(mcp.Register),
+)
+c.Run() // or: if err := c.RunE(); err != nil { ... }
+```
+
+`core.New()` returns `*Core`. `WithService` registers a factory `func(*Core) Result`. Services auto-discover: name from package path, lifecycle from `Startable`/`Stoppable` (return `Result`). `HandleIPCEvents` is the one remaining magic method — auto-registered via reflection if the service implements it.
+
+#### Service Registration Pattern
+
+```go
+// Service factory — receives Core, returns Result
+func Register(c *core.Core) core.Result {
+ svc := &MyService{
+ ServiceRuntime: core.NewServiceRuntime(c, MyOptions{}),
+ }
+ return core.Result{Value: svc, OK: true}
+}
+```
+
+#### Core Subsystem Accessors
+
+| Accessor | Purpose |
+|----------|---------|
+| `c.Options()` | Input configuration |
+| `c.App()` | Application metadata (name, version) |
+| `c.Config()` | Runtime settings, feature flags |
+| `c.Data()` | Embedded assets (Registry[*Embed]) |
+| `c.Drive()` | Transport handles (Registry[*DriveHandle]) |
+| `c.Fs()` | Filesystem I/O (sandboxable) |
+| `c.Process()` | Managed execution (Action sugar) |
+| `c.API()` | Remote streams (protocol handlers) |
+| `c.Action(name)` | Named callable (register/invoke) |
+| `c.Task(name)` | Composed Action sequence |
+| `c.Entitled(name)` | Permission check |
+| `c.RegistryOf(n)` | Cross-cutting registry queries |
+| `c.Cli()` | CLI command framework |
+| `c.IPC()` | Message bus (ACTION, QUERY) |
+| `c.Log()` | Structured logging |
+| `c.Error()` | Panic recovery |
+| `c.I18n()` | Internationalisation |
+
+#### Primitive Types
+
+```go
+// Option — the atom
+core.Option{Key: "name", Value: "brain"}
+
+// Options — universal input
+opts := core.NewOptions(
+ core.Option{Key: "name", Value: "myapp"},
+ core.Option{Key: "port", Value: 8080},
+)
+opts.String("name") // "myapp"
+opts.Int("port") // 8080
+
+// Result — universal output
+core.Result{Value: svc, OK: true}
+```
+
+#### Named Actions — The Primary Communication Pattern
+
+Services register capabilities as named Actions. No direct function calls, no untyped dispatch — declare intent by name, invoke by name.
+
+```go
+// Register a capability during OnStartup
+c.Action("workspace.create", func(ctx context.Context, opts core.Options) core.Result {
+ name := opts.String("name")
+ path := core.JoinPath("/srv/workspaces", name)
+ return core.Result{Value: path, OK: true}
+})
+
+// Invoke by name — typed, inspectable, entitlement-checked
+r := c.Action("workspace.create").Run(ctx, core.NewOptions(
+ core.Option{Key: "name", Value: "alpha"},
+))
+
+// Check capability before calling
+if c.Action("process.run").Exists() { /* go-process is registered */ }
+
+// List all capabilities
+c.Actions() // ["workspace.create", "process.run", "brain.recall", ...]
+```
+
+#### Task Composition — Sequencing Actions
+
+```go
+c.Task("agent.completion", core.Task{
+ Steps: []core.Step{
+ {Action: "agentic.qa"},
+ {Action: "agentic.auto-pr"},
+ {Action: "agentic.verify"},
+ {Action: "agentic.poke", Async: true}, // doesn't block
+ },
+})
+```
+
+#### Anonymous Broadcast — Legacy Layer
+
+`ACTION` and `QUERY` remain for backwards-compatible anonymous dispatch. New code should prefer named Actions.
+
+```go
+// Broadcast — all handlers fire, type-switch to filter
+c.ACTION(messages.DeployCompleted{Env: "production"})
+
+// Query — first responder wins
+r := c.QUERY(countQuery{})
+```
+
+#### Process Execution — Use Core Primitives
+
+All external command execution MUST go through `c.Process()`, not raw `os/exec`. This makes process execution testable, gatable by entitlements, and managed by Core's lifecycle.
+
+```go
+// AX-native: Core Process primitive
+r := c.Process().RunIn(ctx, repoDir, "git", "log", "--oneline", "-20")
+if r.OK { output := r.Value.(string) }
+
+// Not AX: raw exec.Command — untestable, no entitlement, no lifecycle
+cmd := exec.Command("git", "log", "--oneline", "-20")
+cmd.Dir = repoDir
+out, err := cmd.Output()
+```
+
+**Rule:** If a package imports `os/exec`, it is bypassing Core's process primitive. The only package that should import `os/exec` is `go-process` itself.
+
+**Quality gate:** An agent reviewing a diff can mechanically check: does this import `os/exec`, `unsafe`, or `encoding/json` directly? If so, it bypassed a Core primitive.
+
+#### What This Replaces
+
+| Go Convention | Core AX | Why |
+|--------------|---------|-----|
+| `func With*(v) Option` | `core.WithOption(k, v)` | Named key-value is greppable; option chains require tracing |
+| `func Must*(v) T` | `core.Result` | No hidden panics; errors flow through Result.OK |
+| `func *For[T](c) T` | `c.Service("name")` | String lookup is greppable; generics require type context |
+| `val, err :=` everywhere | Single return via `core.Result` | Intent not obscured by error handling |
+| `exec.Command(...)` | `c.Process().Run(ctx, cmd, args...)` | Testable, gatable, lifecycle-managed |
+| `map[string]*T + mutex` | `core.Registry[T]` | Thread-safe, ordered, lockable, queryable |
+| untyped `any` dispatch | `c.Action("name").Run(ctx, opts)` | Named, typed, inspectable, entitlement-checked |
+
+### 7. Tests as Behavioural Specification
+
+Test names are structured data. An agent querying "what happens when dispatch fails?" should find the answer by scanning test names, not reading prose.
+
+```
+TestDispatch_DetectFinalStatus_Good — clean exit → completed
+TestDispatch_DetectFinalStatus_Bad — non-zero exit → failed
+TestDispatch_DetectFinalStatus_Ugly — BLOCKED.md overrides exit code
+```
+
+**Convention:** `Test{File}_{Function}_{Good|Bad|Ugly}`
+
+| Category | Purpose |
+|----------|---------|
+| `_Good` | Happy path — proves the contract works |
+| `_Bad` | Expected errors — proves error handling works |
+| `_Ugly` | Edge cases, panics, corruption — proves it doesn't blow up |
+
+**Rule:** Every testable function gets all three categories. Missing categories are gaps in the specification, detectable by scanning:
+
+```bash
+# Find under-tested functions
+for f in *.go; do
+ [[ "$f" == *_test.go ]] && continue
+ while IFS= read -r line; do
+ fn=$(echo "$line" | sed 's/func.*) //; s/(.*//; s/ .*//')
+ [[ -z "$fn" || "$fn" == register* ]] && continue
+ cap="${fn^}"
+ grep -q "_${cap}_Good\|_${fn}_Good" *_test.go || echo "$f: $fn missing Good"
+ grep -q "_${cap}_Bad\|_${fn}_Bad" *_test.go || echo "$f: $fn missing Bad"
+ grep -q "_${cap}_Ugly\|_${fn}_Ugly" *_test.go || echo "$f: $fn missing Ugly"
+ done < <(grep "^func " "$f")
+done
+```
+
+**Rationale:** The test suite IS the behavioural spec. `grep _TrackFailureRate_ *_test.go` returns three concrete scenarios — no prose needed. The naming convention makes the entire test suite machine-queryable. An agent dispatched to fix a function can read its tests to understand the full contract before making changes.
+
+**What this replaces:**
+
+| Convention | AX Test Naming | Why |
+|-----------|---------------|-----|
+| `TestFoo_works` | `TestFile_Foo_Good` | File prefix enables cross-file search |
+| Unnamed table tests | Explicit Good/Bad/Ugly | Categories are scannable without reading test body |
+| Coverage % as metric | Missing categories as metric | 100% coverage with only Good tests is a false signal |
+
+### 7b. Example Tests as AX TDD
+
+Go `Example` functions serve triple duty: they run as tests (count toward coverage), show in godoc (usage documentation), and seed user guide generation.
+
+```go
+// file: action_example_test.go
+
+func ExampleAction_Run() {
+ c := New()
+ c.Action("double", func(_ context.Context, opts Options) Result {
+ return Result{Value: opts.Int("n") * 2, OK: true}
+ })
+
+ r := c.Action("double").Run(context.Background(), NewOptions(
+ Option{Key: "n", Value: 21},
+ ))
+ Println(r.Value)
+ // Output: 42
+}
+```
+
+**AX TDD pattern:** Write the Example first — it defines how the API should feel. If the Example is awkward, the API is wrong. The Example IS the test, the documentation, and the design feedback loop.
+
+**Convention:** One `{source}_example_test.go` per source file. Every exported function should have at least one Example. The Example output comment makes it a verified test.
+
+**Quality gate:** A source file without a corresponding example file is missing documentation that compiles.
+
+### Operational Principles
+
+Principles 1-7 govern code design. Principles 8-10 govern how agents and humans work with the codebase.
+
+### 8. RFC as Domain Load
+
+An agent's first action in a session should be loading the repo's RFC.md. The full spec in context produces zero-correction sessions — every decision aligns with the design because the design is loaded.
+
+**Validated:** Loading core/go's RFC.md (42k tokens from a 500k token discovery session) at session start eliminated all course corrections. The spec is compressed domain knowledge that survives context compaction.
+
+**Rule:** Every repo that has non-trivial architecture should have a `docs/RFC.md`. The RFC is not documentation for humans — it's a context document for agents. It should be loadable in one read and contain everything needed to make correct decisions.
+
+### 9. Primitives as Quality Gates
+
+Core primitives become mechanical code review rules. An agent reviewing a diff checks:
+
+| Import | Violation | Use Instead |
+|--------|-----------|-------------|
+| `os` | Bypasses Fs/Env primitives | `c.Fs()`, `core.Env()`, `core.DirFS()`, `Fs.TempDir()` |
+| `os/exec` | Bypasses Process primitive | `c.Process().Run()` |
+| `io` | Bypasses stream primitives | `core.ReadAll()`, `core.WriteAll()`, `core.CloseStream()` |
+| `fmt` | Bypasses string/print primitives | `core.Println()`, `core.Sprintf()`, `core.Sprint()` |
+| `errors` | Bypasses error primitive | `core.NewError()`, `core.E()`, `core.Is()`, `core.As()` |
+| `log` | Bypasses logging | `core.Info()`, `core.Warn()`, `core.Error()`, `c.Log()` |
+| `encoding/json` | Bypasses Core serialisation | `core.JSONMarshal()`, `core.JSONUnmarshal()` |
+| `path/filepath` | Bypasses path security boundary | `core.Path()`, `core.JoinPath()`, `core.PathBase()` |
+| `unsafe` | Bypasses Fs sandbox | `Fs.NewUnrestricted()` |
+| `strings` | Bypasses string guardrails | `core.Contains()`, `core.Split()`, `core.Trim()`, etc. |
+
+**Rule:** If a diff introduces a disallowed import, it failed code review. The import list IS the quality gate. No subjective judgement needed — a weaker model can enforce this mechanically.
+
+### 10. Registration IS Capability, Entitlement IS Permission
+
+Two layers of permission, both declarative:
+
+```
+Registration = "this action EXISTS" → c.Action("process.run").Exists()
+Entitlement = "this Core is ALLOWED" → c.Entitled("process.run").Allowed
+```
+
+A sandboxed Core has no `process.run` registered — the action doesn't exist. A SaaS Core has it registered but entitlement-gated — the action exists but the workspace may not be allowed to use it.
+
+**Rule:** Never check permissions with `if` statements in business logic. Register capabilities as Actions. Gate them with Entitlements. The framework enforces both — `Action.Run()` checks both before executing.
+
+## Applying AX to Existing Patterns
+
+### File Structure
+
+```
+# AX-native: path describes content
+core/agent/
+├── cmd/core-agent/ # CLI entry point (minimal — just core.New + Run)
+├── pkg/agentic/ # Agent orchestration (dispatch, prep, verify, scan)
+├── pkg/brain/ # OpenBrain integration
+├── pkg/lib/ # Embedded templates, personas, flows
+├── pkg/messages/ # Typed IPC message definitions
+├── pkg/monitor/ # Agent monitoring + notifications
+├── pkg/setup/ # Workspace scaffolding + detection
+└── claude/ # Claude Code plugin definitions
+
+# Not AX: generic names requiring README
+src/
+├── lib/
+├── utils/
+└── helpers/
+```
+
+### Error Handling
+
+```go
+// AX-native: errors flow through Result, not call sites
+func Register(c *core.Core) core.Result {
+ svc := &MyService{ServiceRuntime: core.NewServiceRuntime(c, MyOpts{})}
+ return core.Result{Value: svc, OK: true}
+}
+
+// Not AX: errors dominate the code
+func Register(c *core.Core) (*MyService, error) {
+ svc, err := NewMyService(c)
+ if err != nil {
+ return nil, fmt.Errorf("create service: %w", err)
+ }
+ return svc, nil
+}
+```
+
+### Command Registration
+
+```go
+// AX-native: extracted methods, testable without CLI
+func (s *MyService) OnStartup(ctx context.Context) core.Result {
+ c := s.Core()
+ c.Command("issue/get", core.Command{Action: s.cmdIssueGet})
+ c.Command("issue/list", core.Command{Action: s.cmdIssueList})
+ c.Action("forge.issue.get", s.handleIssueGet)
+ return core.Result{OK: true}
+}
+
+func (s *MyService) cmdIssueGet(opts core.Options) core.Result {
+ // testable business logic — no closure, no CLI dependency
+}
+
+// Not AX: closures that can only be tested via CLI integration
+c.Command("issue/get", core.Command{
+ Action: func(opts core.Options) core.Result {
+ // 50 lines of untestable inline logic
+ },
+})
+```
+
+### Process Execution
+
+```go
+// AX-native: Core Process primitive, testable with mock handler
+func (s *MyService) getGitLog(repoPath string) string {
+ r := s.Core().Process().RunIn(context.Background(), repoPath, "git", "log", "--oneline", "-20")
+ if !r.OK { return "" }
+ return core.Trim(r.Value.(string))
+}
+
+// Not AX: raw exec.Command — untestable, no entitlement check, path traversal risk
+func (s *MyService) getGitLog(repoPath string) string {
+ cmd := exec.Command("git", "log", "--oneline", "-20")
+ cmd.Dir = repoPath // user-controlled path goes directly to OS
+ output, err := cmd.Output()
+ if err != nil { return "" }
+ return strings.TrimSpace(string(output))
+}
+```
+
+The AX-native version routes through `c.Process()` → named Action → entitlement check. The non-AX version passes user input directly to `os/exec` with no permission gate.
+
+### Permission Gating
+
+```go
+// AX-native: entitlement checked by framework, not by business logic
+c.Action("agentic.dispatch", func(ctx context.Context, opts core.Options) core.Result {
+ // Action.Run() already checked c.Entitled("agentic.dispatch")
+ // If we're here, we're allowed. Just do the work.
+ return dispatch(ctx, opts)
+})
+
+// Not AX: permission logic scattered through business code
+func handleDispatch(ctx context.Context, opts core.Options) core.Result {
+ if !isAdmin(ctx) && !hasPlan(ctx, "pro") {
+ return core.Result{Value: core.E("dispatch", "upgrade required", nil), OK: false}
+ }
+ // duplicate permission check in every handler
+}
+```
+
+## Compatibility
+
+AX conventions are valid, idiomatic Go/PHP/TS. They do not require language extensions, code generation, or non-standard tooling. An AX-designed codebase compiles, tests, and deploys with standard toolchains.
+
+The conventions diverge from community patterns (functional options, Must/For, etc.) but do not violate language specifications. This is a style choice, not a fork.
+
+## Adoption
+
+AX applies to all code in the Core ecosystem. core/go is fully migrated (v0.8.0). Consumer packages migrate via their RFCs.
+
+Priority for migrating a package:
+1. **Lifecycle** — `OnStartup`/`OnShutdown` return `Result`
+2. **Actions** — register capabilities as named Actions
+3. **Imports** — replace all 10 disallowed imports (Principle 9)
+4. **String ops** — `+` concat → `Concat()`, `path +` → `Path()`
+5. **Test naming** — `TestFile_Function_{Good,Bad,Ugly}`
+6. **Examples** — one `{source}_example_test.go` per source file
+7. **Comments** — every exported function has usage example (Principle 2)
+
+## Verification
+
+An agent auditing AX compliance checks:
+
+```bash
+# Disallowed imports (Principle 9)
+grep -rn '"os"\|"os/exec"\|"io"\|"fmt"\|"errors"\|"log"\|"encoding/json"\|"path/filepath"\|"unsafe"\|"strings"' *.go \
+ | grep -v _test.go
+
+# Test naming (Principle 7)
+grep "^func Test" *_test.go | grep -v "Test[A-Z][a-z]*_.*_\(Good\|Bad\|Ugly\)"
+
+# String concat (should use Concat/Path)
+grep -n '" + \| + "' *.go | grep -v _test.go | grep -v "//"
+
+# Untyped dispatch (should prefer named Actions)
+grep "RegisterTask\|PERFORM\|type Task any" *.go
+```
+
+If any check produces output, the code needs migration.
+
+## References
+
+- `core/go/docs/RFC.md` — CoreGO API contract (21 sections, reference implementation)
+- `core/go-process/docs/RFC.md` — Process consumer spec
+- `core/agent/docs/RFC.md` — Agent consumer spec
+- RFC-004 (Entitlements) — permission model ported to `c.Entitled()`
+- RFC-021 (Core Platform Architecture) — 7-layer stack, provider model
+- dAppServer unified path convention (2024) — path = route = command = test
+- Go Proverbs, Rob Pike (2015) — AX provides an updated lens
+
+## Changelog
+
+- 2026-03-25: v0.8.0 alignment — all examples match implemented API. Added Principles 8 (RFC as Domain Load), 9 (Primitives as Quality Gates), 10 (Registration + Entitlement). Updated subsystem table (Process, API, Action, Task, Entitled, RegistryOf). Process examples use `c.Process()` not old `process.RunWithOptions`. Removed PERFORM references.
+- 2026-03-19: Initial draft — 7 principles
diff --git a/.core/reference/app.go b/.core/reference/app.go
new file mode 100644
index 0000000..9fc1984
--- /dev/null
+++ b/.core/reference/app.go
@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Application identity for the Core framework.
+
+package core
+
+import (
+ "os"
+ "path/filepath"
+)
+
+// App holds the application identity and optional GUI runtime.
+//
+// app := core.App{}.New(core.NewOptions(
+// core.Option{Key: "name", Value: "Core CLI"},
+// core.Option{Key: "version", Value: "1.0.0"},
+// ))
+type App struct {
+ Name string
+ Version string
+ Description string
+ Filename string
+ Path string
+ Runtime any // GUI runtime (e.g., Wails App). Nil for CLI-only.
+}
+
+// New creates an App from Options.
+//
+// app := core.App{}.New(core.NewOptions(
+// core.Option{Key: "name", Value: "myapp"},
+// core.Option{Key: "version", Value: "1.0.0"},
+// ))
+func (a App) New(opts Options) App {
+ if name := opts.String("name"); name != "" {
+ a.Name = name
+ }
+ if version := opts.String("version"); version != "" {
+ a.Version = version
+ }
+ if desc := opts.String("description"); desc != "" {
+ a.Description = desc
+ }
+ if filename := opts.String("filename"); filename != "" {
+ a.Filename = filename
+ }
+ return a
+}
+
+// Find locates a program on PATH and returns a Result containing the App.
+// Uses os.Stat to search PATH directories — no os/exec dependency.
+//
+// r := core.App{}.Find("node", "Node.js")
+// if r.OK { app := r.Value.(*App) }
+func (a App) Find(filename, name string) Result {
+ // If filename contains a separator, check it directly
+ if Contains(filename, string(os.PathSeparator)) {
+ abs, err := filepath.Abs(filename)
+ if err != nil {
+ return Result{err, false}
+ }
+ if isExecutable(abs) {
+ return Result{&App{Name: name, Filename: filename, Path: abs}, true}
+ }
+ return Result{E("app.Find", Concat(filename, " not found"), nil), false}
+ }
+
+ // Search PATH
+ pathEnv := os.Getenv("PATH")
+ if pathEnv == "" {
+ return Result{E("app.Find", "PATH is empty", nil), false}
+ }
+ for _, dir := range Split(pathEnv, string(os.PathListSeparator)) {
+ candidate := filepath.Join(dir, filename)
+ if isExecutable(candidate) {
+ abs, err := filepath.Abs(candidate)
+ if err != nil {
+ continue
+ }
+ return Result{&App{Name: name, Filename: filename, Path: abs}, true}
+ }
+ }
+ return Result{E("app.Find", Concat(filename, " not found on PATH"), nil), false}
+}
+
+// isExecutable checks if a path exists and is executable.
+func isExecutable(path string) bool {
+ info, err := os.Stat(path)
+ if err != nil {
+ return false
+ }
+ // Regular file with at least one execute bit
+ return !info.IsDir() && info.Mode()&0111 != 0
+}
diff --git a/.core/reference/array.go b/.core/reference/array.go
new file mode 100644
index 0000000..ff085bb
--- /dev/null
+++ b/.core/reference/array.go
@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Generic slice operations for the Core framework.
+// Based on leaanthony/slicer, rewritten with Go 1.18+ generics.
+
+package core
+
+// Array is a typed slice with common operations.
+type Array[T comparable] struct {
+ items []T
+}
+
+// NewArray creates an empty Array.
+func NewArray[T comparable](items ...T) *Array[T] {
+ return &Array[T]{items: items}
+}
+
+// Add appends values.
+func (s *Array[T]) Add(values ...T) {
+ s.items = append(s.items, values...)
+}
+
+// AddUnique appends values only if not already present.
+func (s *Array[T]) AddUnique(values ...T) {
+ for _, v := range values {
+ if !s.Contains(v) {
+ s.items = append(s.items, v)
+ }
+ }
+}
+
+// Contains returns true if the value is in the slice.
+func (s *Array[T]) Contains(val T) bool {
+ for _, v := range s.items {
+ if v == val {
+ return true
+ }
+ }
+ return false
+}
+
+// Filter returns a new Array with elements matching the predicate.
+func (s *Array[T]) Filter(fn func(T) bool) Result {
+ filtered := &Array[T]{}
+ for _, v := range s.items {
+ if fn(v) {
+ filtered.items = append(filtered.items, v)
+ }
+ }
+ return Result{filtered, true}
+}
+
+// Each runs a function on every element.
+func (s *Array[T]) Each(fn func(T)) {
+ for _, v := range s.items {
+ fn(v)
+ }
+}
+
+// Remove removes the first occurrence of a value.
+func (s *Array[T]) Remove(val T) {
+ for i, v := range s.items {
+ if v == val {
+ s.items = append(s.items[:i], s.items[i+1:]...)
+ return
+ }
+ }
+}
+
+// Deduplicate removes duplicate values, preserving order.
+func (s *Array[T]) Deduplicate() {
+ seen := make(map[T]struct{})
+ result := make([]T, 0, len(s.items))
+ for _, v := range s.items {
+ if _, exists := seen[v]; !exists {
+ seen[v] = struct{}{}
+ result = append(result, v)
+ }
+ }
+ s.items = result
+}
+
+// Len returns the number of elements.
+func (s *Array[T]) Len() int {
+ return len(s.items)
+}
+
+// Clear removes all elements.
+func (s *Array[T]) Clear() {
+ s.items = nil
+}
+
+// AsSlice returns a copy of the underlying slice.
+func (s *Array[T]) AsSlice() []T {
+ if s.items == nil {
+ return nil
+ }
+ out := make([]T, len(s.items))
+ copy(out, s.items)
+ return out
+}
diff --git a/.core/reference/cli.go b/.core/reference/cli.go
new file mode 100644
index 0000000..5e4b9f7
--- /dev/null
+++ b/.core/reference/cli.go
@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Cli is the CLI surface layer for the Core command tree.
+//
+// c := core.New(core.WithOption("name", "myapp")).Value.(*Core)
+// c.Command("deploy", core.Command{Action: handler})
+// c.Cli().Run()
+package core
+
+import (
+ "io"
+ "os"
+)
+
+// CliOptions holds configuration for the Cli service.
+type CliOptions struct{}
+
+// Cli is the CLI surface for the Core command tree.
+type Cli struct {
+ *ServiceRuntime[CliOptions]
+ output io.Writer
+ banner func(*Cli) string
+}
+
+// Register creates a Cli service factory for core.WithService.
+//
+// core.New(core.WithService(core.CliRegister))
+func CliRegister(c *Core) Result {
+ cl := &Cli{output: os.Stdout}
+ cl.ServiceRuntime = NewServiceRuntime[CliOptions](c, CliOptions{})
+ return c.RegisterService("cli", cl)
+}
+
+// Print writes to the CLI output (defaults to os.Stdout).
+//
+// c.Cli().Print("hello %s", "world")
+func (cl *Cli) Print(format string, args ...any) {
+ Print(cl.output, format, args...)
+}
+
+// SetOutput sets the CLI output writer.
+//
+// c.Cli().SetOutput(os.Stderr)
+func (cl *Cli) SetOutput(w io.Writer) {
+ cl.output = w
+}
+
+// Run resolves os.Args to a command path and executes it.
+//
+// c.Cli().Run()
+// c.Cli().Run("deploy", "to", "homelab")
+func (cl *Cli) Run(args ...string) Result {
+ if len(args) == 0 {
+ args = os.Args[1:]
+ }
+
+ clean := FilterArgs(args)
+ c := cl.Core()
+
+ if c == nil || c.commands == nil {
+ if cl.banner != nil {
+ cl.Print(cl.banner(cl))
+ }
+ return Result{}
+ }
+
+ if c.commands.Len() == 0 {
+ if cl.banner != nil {
+ cl.Print(cl.banner(cl))
+ }
+ return Result{}
+ }
+
+ // Resolve command path from args
+ var cmd *Command
+ var remaining []string
+
+ for i := len(clean); i > 0; i-- {
+ path := JoinPath(clean[:i]...)
+ if r := c.commands.Get(path); r.OK {
+ cmd = r.Value.(*Command)
+ remaining = clean[i:]
+ break
+ }
+ }
+
+ if cmd == nil {
+ if cl.banner != nil {
+ cl.Print(cl.banner(cl))
+ }
+ cl.PrintHelp()
+ return Result{}
+ }
+
+ // Build options from remaining args
+ opts := NewOptions()
+ for _, arg := range remaining {
+ key, val, valid := ParseFlag(arg)
+ if valid {
+ if Contains(arg, "=") {
+ opts.Set(key, val)
+ } else {
+ opts.Set(key, true)
+ }
+ } else if !IsFlag(arg) {
+ opts.Set("_arg", arg)
+ }
+ }
+
+ if cmd.Action != nil {
+ return cmd.Run(opts)
+ }
+ return Result{E("core.Cli.Run", Concat("command \"", cmd.Path, "\" is not executable"), nil), false}
+}
+
+// PrintHelp prints available commands.
+//
+// c.Cli().PrintHelp()
+func (cl *Cli) PrintHelp() {
+ c := cl.Core()
+ if c == nil || c.commands == nil {
+ return
+ }
+
+ name := ""
+ if c.app != nil {
+ name = c.app.Name
+ }
+ if name != "" {
+ cl.Print("%s commands:", name)
+ } else {
+ cl.Print("Commands:")
+ }
+
+ c.commands.Each(func(path string, cmd *Command) {
+ if cmd.Hidden || (cmd.Action == nil && !cmd.IsManaged()) {
+ return
+ }
+ tr := c.I18n().Translate(cmd.I18nKey())
+ desc, _ := tr.Value.(string)
+ if desc == "" || desc == cmd.I18nKey() {
+ cl.Print(" %s", path)
+ } else {
+ cl.Print(" %-30s %s", path, desc)
+ }
+ })
+}
+
+// SetBanner sets the banner function.
+//
+// c.Cli().SetBanner(func(_ *core.Cli) string { return "My App v1.0" })
+func (cl *Cli) SetBanner(fn func(*Cli) string) {
+ cl.banner = fn
+}
+
+// Banner returns the banner string.
+func (cl *Cli) Banner() string {
+ if cl.banner != nil {
+ return cl.banner(cl)
+ }
+ c := cl.Core()
+ if c != nil && c.app != nil && c.app.Name != "" {
+ return c.app.Name
+ }
+ return ""
+}
diff --git a/.core/reference/command.go b/.core/reference/command.go
new file mode 100644
index 0000000..660f866
--- /dev/null
+++ b/.core/reference/command.go
@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Command is a DTO representing an executable operation.
+// Commands don't know if they're root, child, or nested — the tree
+// structure comes from composition via path-based registration.
+//
+// Register a command:
+//
+// c.Command("deploy", func(opts core.Options) core.Result {
+// return core.Result{"deployed", true}
+// })
+//
+// Register a nested command:
+//
+// c.Command("deploy/to/homelab", handler)
+//
+// Description is an i18n key — derived from path if omitted:
+//
+// "deploy" → "cmd.deploy.description"
+// "deploy/to/homelab" → "cmd.deploy.to.homelab.description"
+package core
+
+
+// CommandAction is the function signature for command handlers.
+//
+// func(opts core.Options) core.Result
+type CommandAction func(Options) Result
+
+// Command is the DTO for an executable operation.
+// Commands are declarative — they carry enough information for multiple consumers:
+// - core.Cli() runs the Action
+// - core/cli adds rich help, completion, man pages
+// - go-process wraps Managed commands with lifecycle (PID, health, signals)
+//
+// c.Command("serve", core.Command{
+// Action: handler,
+// Managed: "process.daemon", // go-process provides start/stop/restart
+// })
+type Command struct {
+ Name string
+ Description string // i18n key — derived from path if empty
+ Path string // "deploy/to/homelab"
+ Action CommandAction // business logic
+ Managed string // "" = one-shot, "process.daemon" = managed lifecycle
+ Flags Options // declared flags
+ Hidden bool
+ commands map[string]*Command // child commands (internal)
+}
+
+// I18nKey returns the i18n key for this command's description.
+//
+// cmd with path "deploy/to/homelab" → "cmd.deploy.to.homelab.description"
+func (cmd *Command) I18nKey() string {
+ if cmd.Description != "" {
+ return cmd.Description
+ }
+ path := cmd.Path
+ if path == "" {
+ path = cmd.Name
+ }
+ return Concat("cmd.", Replace(path, "/", "."), ".description")
+}
+
+// Run executes the command's action with the given options.
+//
+// result := cmd.Run(core.NewOptions(core.Option{Key: "target", Value: "homelab"}))
+func (cmd *Command) Run(opts Options) Result {
+ if cmd.Action == nil {
+ return Result{E("core.Command.Run", Concat("command \"", cmd.Path, "\" is not executable"), nil), false}
+ }
+ return cmd.Action(opts)
+}
+
+// IsManaged returns true if this command has a managed lifecycle.
+//
+// if cmd.IsManaged() { /* go-process handles start/stop */ }
+func (cmd *Command) IsManaged() bool {
+ return cmd.Managed != ""
+}
+
+// --- Command Registry (on Core) ---
+
+// CommandRegistry holds the command tree. Embeds Registry[*Command]
+// for thread-safe named storage with insertion order.
+type CommandRegistry struct {
+ *Registry[*Command]
+}
+
+// Command gets or registers a command by path.
+//
+// c.Command("deploy", Command{Action: handler})
+// r := c.Command("deploy")
+func (c *Core) Command(path string, command ...Command) Result {
+ if len(command) == 0 {
+ return c.commands.Get(path)
+ }
+
+ if path == "" || HasPrefix(path, "/") || HasSuffix(path, "/") || Contains(path, "//") {
+ return Result{E("core.Command", Concat("invalid command path: \"", path, "\""), nil), false}
+ }
+
+ // Check for duplicate executable command
+ if r := c.commands.Get(path); r.OK {
+ existing := r.Value.(*Command)
+ if existing.Action != nil || existing.IsManaged() {
+ return Result{E("core.Command", Concat("command \"", path, "\" already registered"), nil), false}
+ }
+ }
+
+ cmd := &command[0]
+ cmd.Name = pathName(path)
+ cmd.Path = path
+ if cmd.commands == nil {
+ cmd.commands = make(map[string]*Command)
+ }
+
+ // Preserve existing subtree when overwriting a placeholder parent
+ if r := c.commands.Get(path); r.OK {
+ existing := r.Value.(*Command)
+ for k, v := range existing.commands {
+ if _, has := cmd.commands[k]; !has {
+ cmd.commands[k] = v
+ }
+ }
+ }
+
+ c.commands.Set(path, cmd)
+
+ // Build parent chain — "deploy/to/homelab" creates "deploy" and "deploy/to" if missing
+ parts := Split(path, "/")
+ for i := len(parts) - 1; i > 0; i-- {
+ parentPath := JoinPath(parts[:i]...)
+ if !c.commands.Has(parentPath) {
+ c.commands.Set(parentPath, &Command{
+ Name: parts[i-1],
+ Path: parentPath,
+ commands: make(map[string]*Command),
+ })
+ }
+ parent := c.commands.Get(parentPath).Value.(*Command)
+ parent.commands[parts[i]] = cmd
+ cmd = parent
+ }
+
+ return Result{OK: true}
+}
+
+// Commands returns all registered command paths in registration order.
+//
+// paths := c.Commands()
+func (c *Core) Commands() []string {
+ if c.commands == nil {
+ return nil
+ }
+ return c.commands.Names()
+}
+
+// pathName extracts the last segment of a path.
+// "deploy/to/homelab" → "homelab"
+func pathName(path string) string {
+ parts := Split(path, "/")
+ return parts[len(parts)-1]
+}
diff --git a/.core/reference/config.go b/.core/reference/config.go
new file mode 100644
index 0000000..2f45f13
--- /dev/null
+++ b/.core/reference/config.go
@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Settings, feature flags, and typed configuration for the Core framework.
+
+package core
+
+import (
+ "sync"
+)
+
+// ConfigVar is a variable that can be set, unset, and queried for its state.
+type ConfigVar[T any] struct {
+ val T
+ set bool
+}
+
+// Get returns the current value.
+//
+// val := v.Get()
+func (v *ConfigVar[T]) Get() T { return v.val }
+
+// Set sets the value and marks it as explicitly set.
+//
+// v.Set(true)
+func (v *ConfigVar[T]) Set(val T) { v.val = val; v.set = true }
+
+// IsSet returns true if the value was explicitly set (distinguishes "set to false" from "never set").
+//
+// if v.IsSet() { /* explicitly configured */ }
+func (v *ConfigVar[T]) IsSet() bool { return v.set }
+
+// Unset resets to zero value and marks as not set.
+//
+// v.Unset()
+// v.IsSet() // false
+func (v *ConfigVar[T]) Unset() {
+ v.set = false
+ var zero T
+ v.val = zero
+}
+
+// NewConfigVar creates a ConfigVar with an initial value marked as set.
+//
+// debug := core.NewConfigVar(true)
+func NewConfigVar[T any](val T) ConfigVar[T] {
+ return ConfigVar[T]{val: val, set: true}
+}
+
+// ConfigOptions holds configuration data.
+type ConfigOptions struct {
+ Settings map[string]any
+ Features map[string]bool
+}
+
+func (o *ConfigOptions) init() {
+ if o.Settings == nil {
+ o.Settings = make(map[string]any)
+ }
+ if o.Features == nil {
+ o.Features = make(map[string]bool)
+ }
+}
+
+// Config holds configuration settings and feature flags.
+type Config struct {
+ *ConfigOptions
+ mu sync.RWMutex
+}
+
+// New initialises a Config with empty settings and features.
+//
+// cfg := (&core.Config{}).New()
+func (e *Config) New() *Config {
+ e.ConfigOptions = &ConfigOptions{}
+ e.ConfigOptions.init()
+ return e
+}
+
+// Set stores a configuration value by key.
+func (e *Config) Set(key string, val any) {
+ e.mu.Lock()
+ if e.ConfigOptions == nil {
+ e.ConfigOptions = &ConfigOptions{}
+ }
+ e.ConfigOptions.init()
+ e.Settings[key] = val
+ e.mu.Unlock()
+}
+
+// Get retrieves a configuration value by key.
+func (e *Config) Get(key string) Result {
+ e.mu.RLock()
+ defer e.mu.RUnlock()
+ if e.ConfigOptions == nil || e.Settings == nil {
+ return Result{}
+ }
+ val, ok := e.Settings[key]
+ if !ok {
+ return Result{}
+ }
+ return Result{val, true}
+}
+
+// String retrieves a string config value (empty string if missing).
+//
+// host := c.Config().String("database.host")
+func (e *Config) String(key string) string { return ConfigGet[string](e, key) }
+
+// Int retrieves an int config value (0 if missing).
+//
+// port := c.Config().Int("database.port")
+func (e *Config) Int(key string) int { return ConfigGet[int](e, key) }
+
+// Bool retrieves a bool config value (false if missing).
+//
+// debug := c.Config().Bool("debug")
+func (e *Config) Bool(key string) bool { return ConfigGet[bool](e, key) }
+
+// ConfigGet retrieves a typed configuration value.
+func ConfigGet[T any](e *Config, key string) T {
+ r := e.Get(key)
+ if !r.OK {
+ var zero T
+ return zero
+ }
+ typed, _ := r.Value.(T)
+ return typed
+}
+
+// --- Feature Flags ---
+
+// Enable activates a feature flag.
+//
+// c.Config().Enable("dark-mode")
+func (e *Config) Enable(feature string) {
+ e.mu.Lock()
+ if e.ConfigOptions == nil {
+ e.ConfigOptions = &ConfigOptions{}
+ }
+ e.ConfigOptions.init()
+ e.Features[feature] = true
+ e.mu.Unlock()
+}
+
+// Disable deactivates a feature flag.
+//
+// c.Config().Disable("dark-mode")
+func (e *Config) Disable(feature string) {
+ e.mu.Lock()
+ if e.ConfigOptions == nil {
+ e.ConfigOptions = &ConfigOptions{}
+ }
+ e.ConfigOptions.init()
+ e.Features[feature] = false
+ e.mu.Unlock()
+}
+
+// Enabled returns true if a feature flag is active.
+//
+// if c.Config().Enabled("dark-mode") { ... }
+func (e *Config) Enabled(feature string) bool {
+ e.mu.RLock()
+ defer e.mu.RUnlock()
+ if e.ConfigOptions == nil || e.Features == nil {
+ return false
+ }
+ return e.Features[feature]
+}
+
+// EnabledFeatures returns all active feature flag names.
+//
+// features := c.Config().EnabledFeatures()
+func (e *Config) EnabledFeatures() []string {
+ e.mu.RLock()
+ defer e.mu.RUnlock()
+ if e.ConfigOptions == nil || e.Features == nil {
+ return nil
+ }
+ var result []string
+ for k, v := range e.Features {
+ if v {
+ result = append(result, k)
+ }
+ }
+ return result
+}
diff --git a/.core/reference/contract.go b/.core/reference/contract.go
new file mode 100644
index 0000000..8718a90
--- /dev/null
+++ b/.core/reference/contract.go
@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Contracts, options, and type definitions for the Core framework.
+
+package core
+
+import (
+ "context"
+ "reflect"
+ "sync"
+)
+
+// Message is the type for IPC broadcasts (fire-and-forget).
+type Message any
+
+// Query is the type for read-only IPC requests.
+type Query any
+
+// QueryHandler handles Query requests. Returns Result{Value, OK}.
+type QueryHandler func(*Core, Query) Result
+
+// Startable is implemented by services that need startup initialisation.
+//
+// func (s *MyService) OnStartup(ctx context.Context) core.Result {
+// return core.Result{OK: true}
+// }
+type Startable interface {
+ OnStartup(ctx context.Context) Result
+}
+
+// Stoppable is implemented by services that need shutdown cleanup.
+//
+// func (s *MyService) OnShutdown(ctx context.Context) core.Result {
+// return core.Result{OK: true}
+// }
+type Stoppable interface {
+ OnShutdown(ctx context.Context) Result
+}
+
+// --- Action Messages ---
+
+type ActionServiceStartup struct{}
+type ActionServiceShutdown struct{}
+
+type ActionTaskStarted struct {
+ TaskIdentifier string
+ Action string
+ Options Options
+}
+
+type ActionTaskProgress struct {
+ TaskIdentifier string
+ Action string
+ Progress float64
+ Message string
+}
+
+type ActionTaskCompleted struct {
+ TaskIdentifier string
+ Action string
+ Result Result
+}
+
+// --- Constructor ---
+
+// CoreOption is a functional option applied during Core construction.
+// Returns Result — if !OK, New() stops and returns the error.
+//
+// core.New(
+// core.WithService(agentic.Register),
+// core.WithService(monitor.Register),
+// core.WithServiceLock(),
+// )
+type CoreOption func(*Core) Result
+
+// New initialises a Core instance by applying options in order.
+// Services registered here form the application conclave — they share
+// IPC access and participate in the lifecycle (ServiceStartup/ServiceShutdown).
+//
+// c := core.New(
+// core.WithOption("name", "myapp"),
+// core.WithService(auth.Register),
+// core.WithServiceLock(),
+// )
+// c.Run()
+func New(opts ...CoreOption) *Core {
+ c := &Core{
+ app: &App{},
+ data: &Data{Registry: NewRegistry[*Embed]()},
+ drive: &Drive{Registry: NewRegistry[*DriveHandle]()},
+ fs: (&Fs{}).New("/"),
+ config: (&Config{}).New(),
+ error: &ErrorPanic{},
+ log: &ErrorLog{},
+ lock: &Lock{locks: NewRegistry[*sync.RWMutex]()},
+ ipc: &Ipc{actions: NewRegistry[*Action](), tasks: NewRegistry[*Task]()},
+ info: systemInfo,
+ i18n: &I18n{},
+ api: &API{protocols: NewRegistry[StreamFactory]()},
+ services: &ServiceRegistry{Registry: NewRegistry[*Service]()},
+ commands: &CommandRegistry{Registry: NewRegistry[*Command]()},
+ entitlementChecker: defaultChecker,
+ }
+ c.context, c.cancel = context.WithCancel(context.Background())
+ c.api.core = c
+
+ // Core services
+ CliRegister(c)
+
+ for _, opt := range opts {
+ if r := opt(c); !r.OK {
+ Error("core.New failed", "err", r.Value)
+ break
+ }
+ }
+
+ // Apply service lock after all opts — v0.3.3 parity
+ c.LockApply()
+
+ return c
+}
+
+// WithOptions applies key-value configuration to Core.
+//
+// core.WithOptions(core.NewOptions(core.Option{Key: "name", Value: "myapp"}))
+func WithOptions(opts Options) CoreOption {
+ return func(c *Core) Result {
+ c.options = &opts
+ if name := opts.String("name"); name != "" {
+ c.app.Name = name
+ }
+ return Result{OK: true}
+ }
+}
+
+// WithService registers a service via its factory function.
+// If the factory returns a non-nil Value, WithService auto-discovers the
+// service name from the factory's package path (last path segment, lowercase,
+// with any "_test" suffix stripped) and calls RegisterService on the instance.
+// IPC handler auto-registration is handled by RegisterService.
+//
+// If the factory returns nil Value (it registered itself), WithService
+// returns success without a second registration.
+//
+// core.WithService(agentic.Register)
+// core.WithService(display.Register(nil))
+func WithService(factory func(*Core) Result) CoreOption {
+ return func(c *Core) Result {
+ r := factory(c)
+ if !r.OK {
+ return r
+ }
+ if r.Value == nil {
+ // Factory self-registered — nothing more to do.
+ return Result{OK: true}
+ }
+ // Auto-discover the service name from the instance's package path.
+ instance := r.Value
+ typeOf := reflect.TypeOf(instance)
+ if typeOf.Kind() == reflect.Ptr {
+ typeOf = typeOf.Elem()
+ }
+ pkgPath := typeOf.PkgPath()
+ parts := Split(pkgPath, "/")
+ name := Lower(parts[len(parts)-1])
+ if name == "" {
+ return Result{E("core.WithService", Sprintf("service name could not be discovered for type %T", instance), nil), false}
+ }
+
+ // RegisterService handles Startable/Stoppable/HandleIPCEvents discovery
+ return c.RegisterService(name, instance)
+ }
+}
+
+// WithName registers a service with an explicit name (no reflect discovery).
+//
+// core.WithName("ws", func(c *Core) Result {
+// return Result{Value: hub, OK: true}
+// })
+func WithName(name string, factory func(*Core) Result) CoreOption {
+ return func(c *Core) Result {
+ r := factory(c)
+ if !r.OK {
+ return r
+ }
+ if r.Value == nil {
+ return Result{E("core.WithName", Sprintf("failed to create service %q", name), nil), false}
+ }
+ return c.RegisterService(name, r.Value)
+ }
+}
+
+// WithOption is a convenience for setting a single key-value option.
+//
+// core.New(
+// core.WithOption("name", "myapp"),
+// core.WithOption("port", 8080),
+// )
+func WithOption(key string, value any) CoreOption {
+ return func(c *Core) Result {
+ if c.options == nil {
+ opts := NewOptions()
+ c.options = &opts
+ }
+ c.options.Set(key, value)
+ if key == "name" {
+ if s, ok := value.(string); ok {
+ c.app.Name = s
+ }
+ }
+ return Result{OK: true}
+ }
+}
+
+// WithServiceLock prevents further service registration after construction.
+//
+// core.New(
+// core.WithService(auth.Register),
+// core.WithServiceLock(),
+// )
+func WithServiceLock() CoreOption {
+ return func(c *Core) Result {
+ c.LockEnable()
+ return Result{OK: true}
+ }
+}
diff --git a/.core/reference/core.go b/.core/reference/core.go
new file mode 100644
index 0000000..21f13c1
--- /dev/null
+++ b/.core/reference/core.go
@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Package core is a dependency injection and service lifecycle framework for Go.
+// This file defines the Core struct, accessors, and IPC/error wrappers.
+
+package core
+
+import (
+ "context"
+ "os"
+ "sync"
+ "sync/atomic"
+)
+
+// --- Core Struct ---
+
+// Core is the central application object that manages services, assets, and communication.
+type Core struct {
+ options *Options // c.Options() — Input configuration used to create this Core
+ app *App // c.App() — Application identity + optional GUI runtime
+ data *Data // c.Data() — Embedded/stored content from packages
+ drive *Drive // c.Drive() — Resource handle registry (transports)
+ fs *Fs // c.Fs() — Local filesystem I/O (sandboxable)
+ config *Config // c.Config() — Configuration, settings, feature flags
+ error *ErrorPanic // c.Error() — Panic recovery and crash reporting
+ log *ErrorLog // c.Log() — Structured logging + error wrapping
+ // cli accessed via ServiceFor[*Cli](c, "cli")
+ commands *CommandRegistry // c.Command("path") — Command tree
+ services *ServiceRegistry // c.Service("name") — Service registry
+ lock *Lock // c.Lock("name") — Named mutexes
+ ipc *Ipc // c.IPC() — Message bus for IPC
+ api *API // c.API() — Remote streams
+ info *SysInfo // c.Env("key") — Read-only system/environment information
+ i18n *I18n // c.I18n() — Internationalisation and locale collection
+
+ entitlementChecker EntitlementChecker // default: everything permitted
+ usageRecorder UsageRecorder // default: nil (no-op)
+
+ context context.Context
+ cancel context.CancelFunc
+ taskIDCounter atomic.Uint64
+ waitGroup sync.WaitGroup
+ shutdown atomic.Bool
+}
+
+// --- Accessors ---
+
+// Options returns the input configuration passed to core.New().
+//
+// opts := c.Options()
+// name := opts.String("name")
+func (c *Core) Options() *Options { return c.options }
+
+// App returns application identity metadata.
+//
+// c.App().Name // "my-app"
+// c.App().Version // "1.0.0"
+func (c *Core) App() *App { return c.app }
+
+// Data returns the embedded asset registry (Registry[*Embed]).
+//
+// r := c.Data().ReadString("prompts/coding.md")
+func (c *Core) Data() *Data { return c.data }
+
+// Drive returns the transport handle registry (Registry[*DriveHandle]).
+//
+// r := c.Drive().Get("forge")
+func (c *Core) Drive() *Drive { return c.drive }
+
+// Fs returns the sandboxed filesystem.
+//
+// r := c.Fs().Read("/path/to/file")
+// c.Fs().WriteAtomic("/status.json", data)
+func (c *Core) Fs() *Fs { return c.fs }
+
+// Config returns runtime settings and feature flags.
+//
+// host := c.Config().String("database.host")
+// c.Config().Enable("dark-mode")
+func (c *Core) Config() *Config { return c.config }
+
+// Error returns the panic recovery subsystem.
+//
+// c.Error().Recover()
+func (c *Core) Error() *ErrorPanic { return c.error }
+
+// Log returns the structured logging subsystem.
+//
+// c.Log().Info("started", "port", 8080)
+func (c *Core) Log() *ErrorLog { return c.log }
+
+// Cli returns the CLI command framework (registered as service "cli").
+//
+// c.Cli().Run("deploy", "to", "homelab")
+func (c *Core) Cli() *Cli {
+ cl, _ := ServiceFor[*Cli](c, "cli")
+ return cl
+}
+
+// IPC returns the message bus internals.
+//
+// c.IPC()
+func (c *Core) IPC() *Ipc { return c.ipc }
+
+// I18n returns the internationalisation subsystem.
+//
+// tr := c.I18n().Translate("cmd.deploy.description")
+func (c *Core) I18n() *I18n { return c.i18n }
+
+// Env returns an environment variable by key (cached at init, falls back to os.Getenv).
+//
+// home := c.Env("DIR_HOME")
+// token := c.Env("FORGE_TOKEN")
+func (c *Core) Env(key string) string { return Env(key) }
+
+// Context returns Core's lifecycle context (cancelled on shutdown).
+//
+// ctx := c.Context()
+func (c *Core) Context() context.Context { return c.context }
+
+// Core returns self — satisfies the ServiceRuntime interface.
+//
+// c := s.Core()
+func (c *Core) Core() *Core { return c }
+
+// --- Lifecycle ---
+
+// RunE starts all services, runs the CLI, then shuts down.
+// Returns an error instead of calling os.Exit — let main() handle the exit.
+// ServiceShutdown is always called via defer, even on startup failure or panic.
+//
+// if err := c.RunE(); err != nil {
+// os.Exit(1)
+// }
+func (c *Core) RunE() error {
+ defer c.ServiceShutdown(context.Background())
+
+ r := c.ServiceStartup(c.context, nil)
+ if !r.OK {
+ if err, ok := r.Value.(error); ok {
+ return err
+ }
+ return E("core.Run", "startup failed", nil)
+ }
+
+ if cli := c.Cli(); cli != nil {
+ r = cli.Run()
+ }
+
+ if !r.OK {
+ if err, ok := r.Value.(error); ok {
+ return err
+ }
+ }
+ return nil
+}
+
+// Run starts all services, runs the CLI, then shuts down.
+// Calls os.Exit(1) on failure. For error handling use RunE().
+//
+// c := core.New(core.WithService(myService.Register))
+// c.Run()
+func (c *Core) Run() {
+ if err := c.RunE(); err != nil {
+ Error(err.Error())
+ os.Exit(1)
+ }
+}
+
+// --- IPC (uppercase aliases) ---
+
+// ACTION broadcasts a message to all registered handlers (fire-and-forget).
+// Each handler is wrapped in panic recovery. All handlers fire regardless.
+//
+// c.ACTION(messages.AgentCompleted{Agent: "codex", Status: "completed"})
+func (c *Core) ACTION(msg Message) Result { return c.broadcast(msg) }
+
+// QUERY sends a request — first handler to return OK wins.
+//
+// r := c.QUERY(MyQuery{Name: "brain"})
+func (c *Core) QUERY(q Query) Result { return c.Query(q) }
+
+// QUERYALL sends a request — collects all OK responses.
+//
+// r := c.QUERYALL(countQuery{})
+// results := r.Value.([]any)
+func (c *Core) QUERYALL(q Query) Result { return c.QueryAll(q) }
+
+// --- Error+Log ---
+
+// LogError logs an error and returns the Result from ErrorLog.
+func (c *Core) LogError(err error, op, msg string) Result {
+ return c.log.Error(err, op, msg)
+}
+
+// LogWarn logs a warning and returns the Result from ErrorLog.
+func (c *Core) LogWarn(err error, op, msg string) Result {
+ return c.log.Warn(err, op, msg)
+}
+
+// Must logs and panics if err is not nil.
+func (c *Core) Must(err error, op, msg string) {
+ c.log.Must(err, op, msg)
+}
+
+// --- Registry Accessor ---
+
+// RegistryOf returns a named registry for cross-cutting queries.
+// Known registries: "services", "commands", "actions".
+//
+// c.RegistryOf("services").Names() // all service names
+// c.RegistryOf("actions").List("process.*") // process capabilities
+// c.RegistryOf("commands").Len() // command count
+func (c *Core) RegistryOf(name string) *Registry[any] {
+ // Bridge typed registries to untyped access for cross-cutting queries.
+ // Each registry is wrapped in a read-only proxy.
+ switch name {
+ case "services":
+ return registryProxy(c.services.Registry)
+ case "commands":
+ return registryProxy(c.commands.Registry)
+ case "actions":
+ return registryProxy(c.ipc.actions)
+ default:
+ return NewRegistry[any]() // empty registry for unknown names
+ }
+}
+
+// registryProxy creates a read-only any-typed view of a typed registry.
+// Copies current state — not a live view (avoids type parameter leaking).
+func registryProxy[T any](src *Registry[T]) *Registry[any] {
+ proxy := NewRegistry[any]()
+ src.Each(func(name string, item T) {
+ proxy.Set(name, item)
+ })
+ return proxy
+}
+
+// --- Global Instance ---
diff --git a/.core/reference/data.go b/.core/reference/data.go
new file mode 100644
index 0000000..460277c
--- /dev/null
+++ b/.core/reference/data.go
@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Data is the embedded/stored content system for core packages.
+// Packages mount their embedded content here and other packages
+// read from it by path.
+//
+// Mount a package's assets:
+//
+// c.Data().New(core.NewOptions(
+// core.Option{Key: "name", Value: "brain"},
+// core.Option{Key: "source", Value: brainFS},
+// core.Option{Key: "path", Value: "prompts"},
+// ))
+//
+// Read from any mounted path:
+//
+// content := c.Data().ReadString("brain/coding.md")
+// entries := c.Data().List("agent/flow")
+//
+// Extract a template directory:
+//
+// c.Data().Extract("agent/workspace/default", "/tmp/ws", data)
+package core
+
+import (
+ "io/fs"
+ "path/filepath"
+)
+
+// Data manages mounted embedded filesystems from core packages.
+// Embeds Registry[*Embed] for thread-safe named storage.
+type Data struct {
+ *Registry[*Embed]
+}
+
+// New registers an embedded filesystem under a named prefix.
+//
+// c.Data().New(core.NewOptions(
+// core.Option{Key: "name", Value: "brain"},
+// core.Option{Key: "source", Value: brainFS},
+// core.Option{Key: "path", Value: "prompts"},
+// ))
+func (d *Data) New(opts Options) Result {
+ name := opts.String("name")
+ if name == "" {
+ return Result{}
+ }
+
+ r := opts.Get("source")
+ if !r.OK {
+ return r
+ }
+
+ fsys, ok := r.Value.(fs.FS)
+ if !ok {
+ return Result{E("data.New", "source is not fs.FS", nil), false}
+ }
+
+ path := opts.String("path")
+ if path == "" {
+ path = "."
+ }
+
+ mr := Mount(fsys, path)
+ if !mr.OK {
+ return mr
+ }
+
+ emb := mr.Value.(*Embed)
+ d.Set(name, emb)
+ return Result{emb, true}
+}
+
+// resolve splits a path like "brain/coding.md" into mount name + relative path.
+func (d *Data) resolve(path string) (*Embed, string) {
+ parts := SplitN(path, "/", 2)
+ if len(parts) < 2 {
+ return nil, ""
+ }
+ r := d.Get(parts[0])
+ if !r.OK {
+ return nil, ""
+ }
+ return r.Value.(*Embed), parts[1]
+}
+
+// ReadFile reads a file by full path.
+//
+// r := c.Data().ReadFile("brain/prompts/coding.md")
+// if r.OK { data := r.Value.([]byte) }
+func (d *Data) ReadFile(path string) Result {
+ emb, rel := d.resolve(path)
+ if emb == nil {
+ return Result{}
+ }
+ return emb.ReadFile(rel)
+}
+
+// ReadString reads a file as a string.
+//
+// r := c.Data().ReadString("agent/flow/deploy/to/homelab.yaml")
+// if r.OK { content := r.Value.(string) }
+func (d *Data) ReadString(path string) Result {
+ r := d.ReadFile(path)
+ if !r.OK {
+ return r
+ }
+ return Result{string(r.Value.([]byte)), true}
+}
+
+// List returns directory entries at a path.
+//
+// r := c.Data().List("agent/persona/code")
+// if r.OK { entries := r.Value.([]fs.DirEntry) }
+func (d *Data) List(path string) Result {
+ emb, rel := d.resolve(path)
+ if emb == nil {
+ return Result{}
+ }
+ r := emb.ReadDir(rel)
+ if !r.OK {
+ return r
+ }
+ return Result{r.Value, true}
+}
+
+// ListNames returns filenames (without extensions) at a path.
+//
+// r := c.Data().ListNames("agent/flow")
+// if r.OK { names := r.Value.([]string) }
+func (d *Data) ListNames(path string) Result {
+ r := d.List(path)
+ if !r.OK {
+ return r
+ }
+ entries := r.Value.([]fs.DirEntry)
+ var names []string
+ for _, e := range entries {
+ name := e.Name()
+ if !e.IsDir() {
+ name = TrimSuffix(name, filepath.Ext(name))
+ }
+ names = append(names, name)
+ }
+ return Result{names, true}
+}
+
+// Extract copies a template directory to targetDir.
+//
+// r := c.Data().Extract("agent/workspace/default", "/tmp/ws", templateData)
+func (d *Data) Extract(path, targetDir string, templateData any) Result {
+ emb, rel := d.resolve(path)
+ if emb == nil {
+ return Result{}
+ }
+ r := emb.Sub(rel)
+ if !r.OK {
+ return r
+ }
+ return Extract(r.Value.(*Embed).FS(), targetDir, templateData)
+}
+
+// Mounts returns the names of all mounted content in registration order.
+//
+// names := c.Data().Mounts()
+func (d *Data) Mounts() []string {
+ return d.Names()
+}
diff --git a/.core/reference/docs/RFC.md b/.core/reference/docs/RFC.md
new file mode 100644
index 0000000..457ef22
--- /dev/null
+++ b/.core/reference/docs/RFC.md
@@ -0,0 +1,439 @@
+# core/agent API Contract — RFC Specification
+
+> `dappco.re/go/core/agent` — Agentic dispatch, orchestration, and pipeline management.
+> An agent should be able to understand core/agent's architecture from this document alone.
+
+**Status:** v0.8.0+alpha.1
+**Module:** `dappco.re/go/core/agent`
+**Depends on:** core/go v0.8.0, go-process v0.8.0
+
+---
+
+## 1. Purpose
+
+core/agent dispatches AI agents (Claude, Codex, Gemini) to work on tasks in sandboxed git worktrees, monitors their progress, verifies output, and manages the merge pipeline.
+
+core/go provides the primitives. core/agent composes them.
+
+### File Layout
+
+```
+cmd/core-agent/main.go — entry point: core.New + Run
+pkg/agentic/ — orchestration (dispatch, prep, verify, scan, commands)
+pkg/agentic/actions.go — named Action handlers (ctx, Options) → Result
+pkg/agentic/proc.go — process helpers via s.Core().Process()
+pkg/agentic/handlers.go — IPC completion pipeline handlers
+pkg/agentic/status.go — workspace status (WriteAtomic + JSONMarshalString)
+pkg/agentic/paths.go — paths, fs (NewUnrestricted), helpers
+pkg/brain/ — OpenBrain (recall, remember, search)
+pkg/lib/ — embedded templates, personas, flows, plans
+pkg/messages/ — typed message structs for IPC broadcast
+pkg/monitor/ — agent monitoring via IPC (ServiceRuntime)
+pkg/setup/ — workspace detection + scaffolding (Service)
+claude/ — Claude Code plugin definitions
+docs/ — RFC, plans, architecture
+```
+
+---
+
+## 2. Service Registration
+
+All services use `ServiceRuntime[T]` — no raw `core *core.Core` fields.
+
+```go
+func Register(c *core.Core) core.Result {
+ prep := NewPrep()
+ prep.ServiceRuntime = core.NewServiceRuntime(c, AgentOptions{})
+
+ cfg := prep.loadAgentsConfig()
+ c.Config().Set("agents.concurrency", cfg.Concurrency)
+ c.Config().Set("agents.rates", cfg.Rates)
+
+ RegisterHandlers(c, prep)
+ return core.Result{Value: prep, OK: true}
+}
+
+// In main:
+c := core.New(
+ core.WithService(process.Register),
+ core.WithService(agentic.Register),
+ core.WithService(brain.Register),
+ core.WithService(monitor.Register),
+ core.WithService(mcp.Register),
+)
+c.Run()
+```
+
+---
+
+## 3. Named Actions — The Capability Map
+
+All capabilities registered as named Actions during OnStartup. Inspectable, composable, gatable by Entitlements.
+
+```go
+func (s *PrepSubsystem) OnStartup(ctx context.Context) core.Result {
+ c := s.Core()
+
+ // Dispatch & workspace
+ c.Action("agentic.dispatch", s.handleDispatch)
+ c.Action("agentic.prep", s.handlePrep)
+ c.Action("agentic.status", s.handleStatus)
+ c.Action("agentic.resume", s.handleResume)
+ c.Action("agentic.scan", s.handleScan)
+ c.Action("agentic.watch", s.handleWatch)
+
+ // Pipeline
+ c.Action("agentic.qa", s.handleQA)
+ c.Action("agentic.auto-pr", s.handleAutoPR)
+ c.Action("agentic.verify", s.handleVerify)
+ c.Action("agentic.ingest", s.handleIngest)
+ c.Action("agentic.poke", s.handlePoke)
+ c.Action("agentic.mirror", s.handleMirror)
+
+ // Forge
+ c.Action("agentic.issue.get", s.handleIssueGet)
+ c.Action("agentic.issue.list", s.handleIssueList)
+ c.Action("agentic.issue.create", s.handleIssueCreate)
+ c.Action("agentic.pr.get", s.handlePRGet)
+ c.Action("agentic.pr.list", s.handlePRList)
+ c.Action("agentic.pr.merge", s.handlePRMerge)
+
+ // Review & Epic
+ c.Action("agentic.review-queue", s.handleReviewQueue)
+ c.Action("agentic.epic", s.handleEpic)
+
+ // Completion pipeline — Task composition
+ c.Task("agent.completion", core.Task{
+ Description: "QA → PR → Verify → Merge",
+ Steps: []core.Step{
+ {Action: "agentic.qa"},
+ {Action: "agentic.auto-pr"},
+ {Action: "agentic.verify"},
+ {Action: "agentic.ingest", Async: true},
+ {Action: "agentic.poke", Async: true},
+ },
+ })
+
+ s.StartRunner()
+ s.registerCommands(ctx)
+ s.registerWorkspaceCommands()
+ s.registerForgeCommands()
+ return core.Result{OK: true}
+}
+```
+
+---
+
+## 4. Completion Pipeline
+
+When an agent completes, the IPC handler chain fires. Registered in `RegisterHandlers()`:
+
+```
+AgentCompleted → QA handler → QAResult
+QAResult{Passed} → PR handler → PRCreated
+PRCreated → Verify handler → PRMerged | PRNeedsReview
+AgentCompleted → Ingest handler (findings → issues)
+AgentCompleted → Poke handler (drain queue)
+```
+
+All handlers use `c.ACTION(messages.X{})` — no ChannelNotifier, no callbacks.
+
+---
+
+## 5. Process Execution
+
+All commands via `s.Core().Process()`. Returns `core.Result` — Value is always a string.
+
+```go
+func (s *PrepSubsystem) runCmd(ctx context.Context, dir, command string, args ...string) core.Result {
+ return s.Core().Process().RunIn(ctx, dir, command, args...)
+}
+
+func (s *PrepSubsystem) runCmdOK(ctx context.Context, dir, command string, args ...string) bool {
+ return s.runCmd(ctx, dir, command, args...).OK
+}
+
+func (s *PrepSubsystem) gitCmd(ctx context.Context, dir string, args ...string) core.Result {
+ return s.runCmd(ctx, dir, "git", args...)
+}
+
+func (s *PrepSubsystem) gitOutput(ctx context.Context, dir string, args ...string) string {
+ r := s.gitCmd(ctx, dir, args...)
+ if !r.OK { return "" }
+ return core.Trim(r.Value.(string))
+}
+```
+
+go-process is fully Result-native. `Start`, `Run`, `StartWithOptions`, `RunWithOptions` all return `core.Result`. Value is `*Process` for Start, `string` for Run. OK=true guarantees the type.
+
+---
+
+## 6. Status Management
+
+Workspace status uses `WriteAtomic` + `JSONMarshalString` for safe concurrent access:
+
+```go
+func writeStatus(wsDir string, status *WorkspaceStatus) error {
+ status.UpdatedAt = time.Now()
+ statusPath := core.JoinPath(wsDir, "status.json")
+ if r := fs.WriteAtomic(statusPath, core.JSONMarshalString(status)); !r.OK {
+ err, _ := r.Value.(error)
+ return core.E("writeStatus", "failed to write status", err)
+ }
+ return nil
+}
+```
+
+---
+
+## 7. Filesystem
+
+No `unsafe.Pointer`. Package-level unrestricted Fs via Core primitive:
+
+```go
+var fs = (&core.Fs{}).NewUnrestricted()
+```
+
+---
+
+## 8. IPC Messages
+
+All inter-service communication via typed messages in `pkg/messages/`:
+
+```go
+// Agent lifecycle
+messages.AgentStarted{Agent, Repo, Workspace}
+messages.AgentCompleted{Agent, Repo, Workspace, Status}
+
+// Pipeline
+messages.QAResult{Workspace, Repo, Passed}
+messages.PRCreated{Repo, Branch, PRURL, PRNum}
+messages.PRMerged{Repo, PRURL, PRNum}
+messages.PRNeedsReview{Repo, PRURL, PRNum, Reason}
+
+// Queue
+messages.QueueDrained{Completed}
+messages.PokeQueue{}
+
+// Monitor
+messages.HarvestComplete{Repo, Branch, Files}
+messages.HarvestRejected{Repo, Branch, Reason}
+messages.InboxMessage{New, Total}
+```
+
+---
+
+## 9. Monitor
+
+Embeds `*core.ServiceRuntime[MonitorOptions]`. All notifications via `m.Core().ACTION(messages.X{})` — no ChannelNotifier interface. Git operations via `m.Core().Process()`.
+
+```go
+func Register(c *core.Core) core.Result {
+ mon := New()
+ mon.ServiceRuntime = core.NewServiceRuntime(c, MonitorOptions{})
+
+ c.RegisterAction(func(c *core.Core, msg core.Message) core.Result {
+ switch ev := msg.(type) {
+ case messages.AgentCompleted:
+ mon.handleAgentCompleted(ev)
+ case messages.AgentStarted:
+ mon.handleAgentStarted(ev)
+ }
+ return core.Result{OK: true}
+ })
+
+ return core.Result{Value: mon, OK: true}
+}
+```
+
+---
+
+## 10. Setup
+
+Service with `*core.ServiceRuntime[SetupOptions]`. Detects project type, generates configs, scaffolds workspaces.
+
+```go
+func Register(c *core.Core) core.Result {
+ svc := &Service{
+ ServiceRuntime: core.NewServiceRuntime(c, SetupOptions{}),
+ }
+ return core.Result{Value: svc, OK: true}
+}
+```
+
+---
+
+## 11. Entitlements
+
+Actions are gated by `c.Entitled()` — checked automatically in `Action.Run()`.
+
+```go
+func (s *PrepSubsystem) handleDispatch(ctx context.Context, opts core.Options) core.Result {
+ e := s.Core().Entitled("agentic.concurrency", 1)
+ if !e.Allowed {
+ return core.Result{Value: core.E("dispatch", e.Reason, nil), OK: false}
+ }
+ // ... dispatch agent ...
+ s.Core().RecordUsage("agentic.dispatch")
+ return core.Result{OK: true}
+}
+```
+
+---
+
+## 12. MCP — Action Aggregator
+
+MCP auto-exposes all registered Actions as tools via `c.Actions()`. Register an Action → it appears as an MCP tool. The API stream primitive (`c.API()`) handles transport.
+
+---
+
+## 13. Remote Dispatch
+
+Transparent local/remote via `host:action` syntax:
+
+```go
+r := c.RemoteAction("agentic.status", ctx, opts) // local
+r := c.RemoteAction("charon:agentic.dispatch", ctx, opts) // remote
+r := c.RemoteAction("snider.lthn:brain.recall", ctx, opts) // web3
+```
+
+---
+
+## 14. Quality Gates
+
+```bash
+# No disallowed imports (source files only)
+grep -rn '"os"\|"os/exec"\|"io"\|"fmt"\|"errors"\|"log"\|"encoding/json"\|"path/filepath"\|"unsafe"\|"strings"' *.go **/*.go \
+ | grep -v _test.go
+
+# Test naming: TestFile_Function_{Good,Bad,Ugly}
+grep -rn "^func Test" *_test.go **/*_test.go \
+ | grep -v "Test[A-Z][a-z]*_.*_\(Good\|Bad\|Ugly\)"
+```
+
+---
+
+## 15. Validation and IDs
+
+```go
+if r := core.ValidateName(input.Repo); !r.OK { return r }
+safe := core.SanitisePath(userInput)
+id := core.ID() // "id-42-a3f2b1"
+```
+
+---
+
+## 16. JSON Serialisation
+
+All JSON via Core primitives. No `encoding/json` import.
+
+```go
+data := core.JSONMarshalString(status)
+core.JSONUnmarshalString(jsonStr, &result)
+```
+
+---
+
+## 17. Configuration
+
+```go
+c.Config().Set("agents.concurrency", 5)
+c.Config().String("workspace.root")
+c.Config().Int("agents.concurrency")
+c.Config().Enable("auto-merge")
+if c.Config().Enabled("auto-merge") { ... }
+```
+
+---
+
+## 18. Registry
+
+Use `Registry[T]` for any named collection. No `map[string]*T + sync.Mutex`.
+
+```go
+workspaces := core.NewRegistry[*WorkspaceStatus]()
+workspaces.Set(wsDir, status)
+workspaces.Get(wsDir)
+workspaces.Each(func(dir string, st *WorkspaceStatus) { ... })
+workspaces.Names() // insertion order
+c.RegistryOf("actions").List("agentic.*")
+```
+
+---
+
+## 19. String Operations
+
+No `fmt`, no `strings`, no `+` concat. Core provides everything:
+
+```go
+core.Println(value) // not fmt.Println
+core.Sprintf("port: %d", port) // not fmt.Sprintf
+core.Concat("hello ", name) // not "hello " + name
+core.Path(dir, "status.json") // not dir + "/status.json"
+core.Contains(s, "prefix") // not strings.Contains
+core.Split(s, "/") // not strings.Split
+core.Trim(s) // not strings.TrimSpace
+```
+
+---
+
+## 20. Error Handling and Logging
+
+All errors via `core.E()`. All logging via Core. No `fmt`, `errors`, or `log` imports.
+
+```go
+return core.E("dispatch.prep", "workspace not found", nil)
+return core.E("dispatch.prep", core.Concat("repo ", repo, " invalid"), cause)
+core.Info("agent dispatched", "repo", repo, "agent", agent)
+core.Error("dispatch failed", "err", err)
+core.Security("entitlement.denied", "action", action, "reason", reason)
+```
+
+---
+
+## 21. Stream Helpers and Data
+
+```go
+r := c.Data().ReadString("prompts/coding.md")
+c.Data().List("templates/")
+c.Drive().New(core.NewOptions(
+ core.Option{Key: "name", Value: "charon"},
+ core.Option{Key: "transport", Value: "http://10.69.69.165:9101"},
+))
+```
+
+---
+
+## 22. Comments (AX Principle 2)
+
+Every exported function MUST have a usage-example comment:
+
+```go
+// gitCmd runs a git command in a directory.
+//
+// r := s.gitCmd(ctx, "/repo", "log", "--oneline")
+func (s *PrepSubsystem) gitCmd(ctx context.Context, dir string, args ...string) core.Result {
+```
+
+---
+
+## 23. Test Strategy (AX Principle 7)
+
+`TestFile_Function_{Good,Bad,Ugly}` — 100% naming compliance target.
+
+---
+
+## Consumer RFCs
+
+| Package | RFC | Role |
+|---------|-----|------|
+| core/go | `core/go/docs/RFC.md` | Primitives — all 21 sections |
+| go-process | `core/go-process/docs/RFC.md` | Process Action handlers (Result-native) |
+
+---
+
+## Changelog
+
+- 2026-03-26: WIP — net/http consolidated to transport.go (ONE file). net/url + io/fs eliminated. RFC-025 updated with 3 new quality gates (net/http, net/url, io/fs). 1:1 test + example test coverage. Array[T].Deduplicate replaces custom helpers. Remaining: remove dead `client` field from test literals, brain/provider.go Gin handler.
+- 2026-03-25: Quality gates pass. Zero disallowed imports (all 10). encoding/json→Core JSON. path/filepath→Core Path. os→Core Env/Fs. io→Core ReadAll/WriteAll. go-process fully Result-native. ServiceRuntime on all subsystems. 22 named Actions + Task pipeline. ChannelNotifier→IPC. Reference docs synced.
+- 2026-03-25: Initial spec — written with full core/go v0.8.0 domain context.
diff --git a/.core/reference/docs/commands.md b/.core/reference/docs/commands.md
new file mode 100644
index 0000000..46e2022
--- /dev/null
+++ b/.core/reference/docs/commands.md
@@ -0,0 +1,177 @@
+---
+title: Commands
+description: Path-based command registration and CLI execution.
+---
+
+# Commands
+
+Commands are one of the most AX-native parts of CoreGO. The path is the identity.
+
+## Register a Command
+
+```go
+c.Command("deploy/to/homelab", core.Command{
+ Action: func(opts core.Options) core.Result {
+ target := opts.String("target")
+ return core.Result{Value: "deploying to " + target, OK: true}
+ },
+})
+```
+
+## Command Paths
+
+Paths must be clean:
+
+- no empty path
+- no leading slash
+- no trailing slash
+- no double slash
+
+These paths are valid:
+
+```text
+deploy
+deploy/to/homelab
+workspace/create
+```
+
+These are rejected:
+
+```text
+/deploy
+deploy/
+deploy//to
+```
+
+## Parent Commands Are Auto-Created
+
+When you register `deploy/to/homelab`, CoreGO also creates placeholder parents if they do not already exist:
+
+- `deploy`
+- `deploy/to`
+
+This makes the path tree navigable without extra setup.
+
+## Read a Command Back
+
+```go
+r := c.Command("deploy/to/homelab")
+if r.OK {
+ cmd := r.Value.(*core.Command)
+ _ = cmd
+}
+```
+
+## Run a Command Directly
+
+```go
+cmd := c.Command("deploy/to/homelab").Value.(*core.Command)
+
+r := cmd.Run(core.Options{
+ {Key: "target", Value: "uk-prod"},
+})
+```
+
+If `Action` is nil, `Run` returns `Result{OK:false}` with a structured error.
+
+## Run Through the CLI Surface
+
+```go
+r := c.Cli().Run("deploy", "to", "homelab", "--target=uk-prod", "--debug")
+```
+
+`Cli.Run` resolves the longest matching command path from the arguments, then converts the remaining args into `core.Options`.
+
+## Flag Parsing Rules
+
+### Double Dash
+
+```text
+--target=uk-prod -> key "target", value "uk-prod"
+--debug -> key "debug", value true
+```
+
+### Single Dash
+
+```text
+-v -> key "v", value true
+-n=4 -> key "n", value "4"
+```
+
+### Positional Arguments
+
+Non-flag arguments after the command path are stored as repeated `_arg` options.
+
+```go
+r := c.Cli().Run("workspace", "open", "alpha")
+```
+
+That produces an option like:
+
+```go
+core.Option{Key: "_arg", Value: "alpha"}
+```
+
+### Important Details
+
+- flag values stay as strings
+- `opts.Int("port")` only works if some code stored an actual `int`
+- invalid flags such as `-verbose` and `--v` are ignored
+
+## Help Output
+
+`Cli.PrintHelp()` prints executable commands:
+
+```go
+c.Cli().PrintHelp()
+```
+
+It skips:
+
+- hidden commands
+- placeholder parents with no `Action` and no `Lifecycle`
+
+Descriptions are resolved through `cmd.I18nKey()`.
+
+## I18n Description Keys
+
+If `Description` is empty, CoreGO derives a key from the path.
+
+```text
+deploy -> cmd.deploy.description
+deploy/to/homelab -> cmd.deploy.to.homelab.description
+workspace/create -> cmd.workspace.create.description
+```
+
+If `Description` is already set, CoreGO uses it as-is.
+
+## Lifecycle Commands
+
+Commands can also delegate to a lifecycle implementation.
+
+```go
+type daemonCommand struct{}
+
+func (d *daemonCommand) Start(opts core.Options) core.Result { return core.Result{OK: true} }
+func (d *daemonCommand) Stop() core.Result { return core.Result{OK: true} }
+func (d *daemonCommand) Restart() core.Result { return core.Result{OK: true} }
+func (d *daemonCommand) Reload() core.Result { return core.Result{OK: true} }
+func (d *daemonCommand) Signal(sig string) core.Result { return core.Result{Value: sig, OK: true} }
+
+c.Command("agent/serve", core.Command{
+ Lifecycle: &daemonCommand{},
+})
+```
+
+Important behavior:
+
+- `Start` falls back to `Run` when `Lifecycle` is nil
+- `Stop`, `Restart`, `Reload`, and `Signal` return an empty `Result` when `Lifecycle` is nil
+
+## List Command Paths
+
+```go
+paths := c.Commands()
+```
+
+Like the service registry, the command registry is map-backed, so iteration order is not guaranteed.
diff --git a/.core/reference/docs/configuration.md b/.core/reference/docs/configuration.md
new file mode 100644
index 0000000..0a0cf11
--- /dev/null
+++ b/.core/reference/docs/configuration.md
@@ -0,0 +1,96 @@
+---
+title: Configuration
+description: Constructor options, runtime settings, and feature flags.
+---
+
+# Configuration
+
+CoreGO uses two different configuration layers:
+
+- constructor-time `core.Options`
+- runtime `c.Config()`
+
+## Constructor-Time Options
+
+```go
+c := core.New(core.Options{
+ {Key: "name", Value: "agent-workbench"},
+})
+```
+
+### Current Behavior
+
+- `New` accepts `opts ...Options`
+- the current implementation copies only the first `Options` slice
+- the `name` key is applied to `c.App().Name`
+
+If you need more constructor data, put it in the first `core.Options` slice.
+
+## Runtime Settings with `Config`
+
+Use `c.Config()` for mutable process settings.
+
+```go
+c.Config().Set("workspace.root", "/srv/workspaces")
+c.Config().Set("max_agents", 8)
+c.Config().Set("debug", true)
+```
+
+Read them back with:
+
+```go
+root := c.Config().String("workspace.root")
+maxAgents := c.Config().Int("max_agents")
+debug := c.Config().Bool("debug")
+raw := c.Config().Get("workspace.root")
+```
+
+### Important Details
+
+- missing keys return zero values
+- typed accessors do not coerce strings into ints or bools
+- `Get` returns `core.Result`
+
+## Feature Flags
+
+`Config` also tracks named feature flags.
+
+```go
+c.Config().Enable("workspace.templates")
+c.Config().Enable("agent.review")
+c.Config().Disable("agent.review")
+```
+
+Read them with:
+
+```go
+enabled := c.Config().Enabled("workspace.templates")
+features := c.Config().EnabledFeatures()
+```
+
+Feature names are case-sensitive.
+
+## `ConfigVar[T]`
+
+Use `ConfigVar[T]` when you need a typed value that can also represent “set versus unset”.
+
+```go
+theme := core.NewConfigVar("amber")
+
+if theme.IsSet() {
+ fmt.Println(theme.Get())
+}
+
+theme.Unset()
+```
+
+This is useful for package-local state where zero values are not enough to describe configuration presence.
+
+## Recommended Pattern
+
+Use the two layers for different jobs:
+
+- put startup identity such as `name` into `core.Options`
+- put mutable runtime values and feature switches into `c.Config()`
+
+That keeps constructor intent separate from live process state.
diff --git a/.core/reference/docs/errors.md b/.core/reference/docs/errors.md
new file mode 100644
index 0000000..9b7d3f3
--- /dev/null
+++ b/.core/reference/docs/errors.md
@@ -0,0 +1,120 @@
+---
+title: Errors
+description: Structured errors, logging helpers, and panic recovery.
+---
+
+# Errors
+
+CoreGO treats failures as structured operational data.
+
+Repository convention: use `E()` instead of `fmt.Errorf` for framework and service errors.
+
+## `Err`
+
+The structured error type is:
+
+```go
+type Err struct {
+ Operation string
+ Message string
+ Cause error
+ Code string
+}
+```
+
+## Create Errors
+
+### `E`
+
+```go
+err := core.E("workspace.Load", "failed to read workspace manifest", cause)
+```
+
+### `Wrap`
+
+```go
+err := core.Wrap(cause, "workspace.Load", "manifest parse failed")
+```
+
+### `WrapCode`
+
+```go
+err := core.WrapCode(cause, "WORKSPACE_INVALID", "workspace.Load", "manifest parse failed")
+```
+
+### `NewCode`
+
+```go
+err := core.NewCode("NOT_FOUND", "workspace not found")
+```
+
+## Inspect Errors
+
+```go
+op := core.Operation(err)
+code := core.ErrorCode(err)
+msg := core.ErrorMessage(err)
+root := core.Root(err)
+stack := core.StackTrace(err)
+pretty := core.FormatStackTrace(err)
+```
+
+These helpers keep the operational chain visible without extra type assertions.
+
+## Join and Standard Wrappers
+
+```go
+combined := core.ErrorJoin(err1, err2)
+same := core.Is(combined, err1)
+```
+
+`core.As` and `core.NewError` mirror the standard library for convenience.
+
+## Log-and-Return Helpers
+
+`Core` exposes two convenience wrappers:
+
+```go
+r1 := c.LogError(err, "workspace.Load", "workspace load failed")
+r2 := c.LogWarn(err, "workspace.Load", "workspace load degraded")
+```
+
+These log through the default logger and return `core.Result`.
+
+You can also use the underlying `ErrorLog` directly:
+
+```go
+r := c.Log().Error(err, "workspace.Load", "workspace load failed")
+```
+
+`Must` logs and then panics when the error is non-nil:
+
+```go
+c.Must(err, "workspace.Load", "workspace load failed")
+```
+
+## Panic Recovery
+
+`ErrorPanic` handles process-safe panic capture.
+
+```go
+defer c.Error().Recover()
+```
+
+Run background work with recovery:
+
+```go
+c.Error().SafeGo(func() {
+ panic("captured")
+})
+```
+
+If `ErrorPanic` has a configured crash file path, it appends JSON crash reports and `Reports(n)` reads them back.
+
+That crash file path is currently internal state on `ErrorPanic`, not a public constructor option on `Core.New()`.
+
+## Logging and Error Context
+
+The logging subsystem automatically extracts `op` and logical stack information from structured errors when those values are present in the key-value list.
+
+That makes errors created with `E`, `Wrap`, or `WrapCode` much easier to follow in logs.
diff --git a/.core/reference/docs/getting-started.md b/.core/reference/docs/getting-started.md
new file mode 100644
index 0000000..d2d8166
--- /dev/null
+++ b/.core/reference/docs/getting-started.md
@@ -0,0 +1,208 @@
+---
+title: Getting Started
+description: Build a first CoreGO application with the current API.
+---
+
+# Getting Started
+
+This page shows the shortest path to a useful CoreGO application using the API that exists in this repository today.
+
+## Install
+
+```bash
+go get dappco.re/go/core
+```
+
+## Create a Core
+
+`New` takes zero or more `core.Options` slices, but the current implementation only reads the first one. In practice, treat the constructor as `core.New(core.Options{...})`.
+
+```go
+package main
+
+import "dappco.re/go/core"
+
+func main() {
+ c := core.New(core.Options{
+ {Key: "name", Value: "agent-workbench"},
+ })
+
+ _ = c
+}
+```
+
+The `name` option is copied into `c.App().Name`.
+
+## Register a Service
+
+Services are registered explicitly with a name and a `core.Service` DTO.
+
+```go
+c.Service("audit", core.Service{
+ OnStart: func() core.Result {
+ core.Info("audit service started", "app", c.App().Name)
+ return core.Result{OK: true}
+ },
+ OnStop: func() core.Result {
+ core.Info("audit service stopped", "app", c.App().Name)
+ return core.Result{OK: true}
+ },
+})
+```
+
+This registry stores `core.Service` values. It is a lifecycle registry, not a typed object container.
+
+## Register a Query, Task, and Command
+
+```go
+type workspaceCountQuery struct{}
+
+type createWorkspaceTask struct {
+ Name string
+}
+
+c.RegisterQuery(func(_ *core.Core, q core.Query) core.Result {
+ switch q.(type) {
+ case workspaceCountQuery:
+ return core.Result{Value: 1, OK: true}
+ }
+ return core.Result{}
+})
+
+c.RegisterTask(func(_ *core.Core, t core.Task) core.Result {
+ switch task := t.(type) {
+ case createWorkspaceTask:
+ path := "/tmp/agent-workbench/" + task.Name
+ return core.Result{Value: path, OK: true}
+ }
+ return core.Result{}
+})
+
+c.Command("workspace/create", core.Command{
+ Action: func(opts core.Options) core.Result {
+ return c.PERFORM(createWorkspaceTask{
+ Name: opts.String("name"),
+ })
+ },
+})
+```
+
+## Start the Runtime
+
+```go
+if !c.ServiceStartup(context.Background(), nil).OK {
+ panic("startup failed")
+}
+```
+
+`ServiceStartup` returns `core.Result`, not `error`.
+
+## Run Through the CLI Surface
+
+```go
+r := c.Cli().Run("workspace", "create", "--name=alpha")
+if r.OK {
+ fmt.Println("created:", r.Value)
+}
+```
+
+For flags with values, the CLI stores the value as a string. `--name=alpha` becomes `opts.String("name") == "alpha"`.
+
+## Query the System
+
+```go
+count := c.QUERY(workspaceCountQuery{})
+if count.OK {
+ fmt.Println("workspace count:", count.Value)
+}
+```
+
+## Shut Down Cleanly
+
+```go
+_ = c.ServiceShutdown(context.Background())
+```
+
+Shutdown cancels `c.Context()`, broadcasts `ActionServiceShutdown{}`, waits for background tasks to finish, and then runs service stop hooks.
+
+## Full Example
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+
+ "dappco.re/go/core"
+)
+
+type workspaceCountQuery struct{}
+
+type createWorkspaceTask struct {
+ Name string
+}
+
+func main() {
+ c := core.New(core.Options{
+ {Key: "name", Value: "agent-workbench"},
+ })
+
+ c.Config().Set("workspace.root", "/tmp/agent-workbench")
+ c.Config().Enable("workspace.templates")
+
+ c.Service("audit", core.Service{
+ OnStart: func() core.Result {
+ core.Info("service started", "service", "audit")
+ return core.Result{OK: true}
+ },
+ OnStop: func() core.Result {
+ core.Info("service stopped", "service", "audit")
+ return core.Result{OK: true}
+ },
+ })
+
+ c.RegisterQuery(func(_ *core.Core, q core.Query) core.Result {
+ switch q.(type) {
+ case workspaceCountQuery:
+ return core.Result{Value: 1, OK: true}
+ }
+ return core.Result{}
+ })
+
+ c.RegisterTask(func(_ *core.Core, t core.Task) core.Result {
+ switch task := t.(type) {
+ case createWorkspaceTask:
+ path := c.Config().String("workspace.root") + "/" + task.Name
+ return core.Result{Value: path, OK: true}
+ }
+ return core.Result{}
+ })
+
+ c.Command("workspace/create", core.Command{
+ Action: func(opts core.Options) core.Result {
+ return c.PERFORM(createWorkspaceTask{
+ Name: opts.String("name"),
+ })
+ },
+ })
+
+ if !c.ServiceStartup(context.Background(), nil).OK {
+ panic("startup failed")
+ }
+
+ created := c.Cli().Run("workspace", "create", "--name=alpha")
+ fmt.Println("created:", created.Value)
+
+ count := c.QUERY(workspaceCountQuery{})
+ fmt.Println("workspace count:", count.Value)
+
+ _ = c.ServiceShutdown(context.Background())
+}
+```
+
+## Next Steps
+
+- Read [primitives.md](primitives.md) next so the repeated shapes are clear.
+- Read [commands.md](commands.md) if you are building a CLI-first system.
+- Read [messaging.md](messaging.md) if services need to collaborate without direct imports.
diff --git a/.core/reference/docs/index.md b/.core/reference/docs/index.md
new file mode 100644
index 0000000..ca1ef99
--- /dev/null
+++ b/.core/reference/docs/index.md
@@ -0,0 +1,114 @@
+---
+title: CoreGO
+description: AX-first documentation for the CoreGO framework.
+---
+
+# CoreGO
+
+CoreGO is the foundation layer for the Core ecosystem. It gives you one container, one command tree, one message bus, and a small set of shared primitives that repeat across the whole framework.
+
+The current module path is `dappco.re/go/core`.
+
+Start with [RFC.md](RFC.md) for the full API contract and [../RFC-025-AGENT-EXPERIENCE.md](../RFC-025-AGENT-EXPERIENCE.md) for the AX design rules that shape it.
+
+## AX View
+
+CoreGO already follows the main AX ideas from RFC-025:
+
+- predictable names such as `Core`, `Service`, `Command`, `Options`, `Result`, `Message`
+- path-shaped command registration such as `deploy/to/homelab`
+- one repeated input shape (`Options`) and one repeated return shape (`Result`)
+- comments and examples that show real usage instead of restating the type signature
+
+## What CoreGO Owns
+
+| Surface | Purpose |
+|---------|---------|
+| `Core` | Central container and access point |
+| `Service` | Managed lifecycle component |
+| `Command` | Path-based command tree node |
+| `ACTION`, `QUERY`, `PERFORM` | Decoupled communication between components |
+| `Data`, `Drive`, `Fs`, `Config`, `I18n`, `Cli` | Built-in subsystems for common runtime work |
+| `E`, `Wrap`, `ErrorLog`, `ErrorPanic` | Structured failures and panic recovery |
+
+## Quick Example
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+
+ "dappco.re/go/core"
+)
+
+type flushCacheTask struct {
+ Name string
+}
+
+func main() {
+ c := core.New(core.Options{
+ {Key: "name", Value: "agent-workbench"},
+ })
+
+ c.Service("cache", core.Service{
+ OnStart: func() core.Result {
+ core.Info("cache ready", "app", c.App().Name)
+ return core.Result{OK: true}
+ },
+ OnStop: func() core.Result {
+ core.Info("cache stopped", "app", c.App().Name)
+ return core.Result{OK: true}
+ },
+ })
+
+ c.RegisterTask(func(_ *core.Core, task core.Task) core.Result {
+ switch task.(type) {
+ case flushCacheTask:
+ return core.Result{Value: "cache flushed", OK: true}
+ }
+ return core.Result{}
+ })
+
+ c.Command("cache/flush", core.Command{
+ Action: func(opts core.Options) core.Result {
+ return c.PERFORM(flushCacheTask{Name: opts.String("name")})
+ },
+ })
+
+ if !c.ServiceStartup(context.Background(), nil).OK {
+ panic("startup failed")
+ }
+
+ r := c.Cli().Run("cache", "flush", "--name=session-store")
+ fmt.Println(r.Value)
+
+ _ = c.ServiceShutdown(context.Background())
+}
+```
+
+## Documentation Paths
+
+| Path | Covers |
+|------|--------|
+| [getting-started.md](getting-started.md) | First runnable CoreGO app |
+| [primitives.md](primitives.md) | `Options`, `Result`, `Service`, `Message`, `Query`, `Task` |
+| [services.md](services.md) | Service registry, service locks, runtime helpers |
+| [commands.md](commands.md) | Path-based commands and CLI execution |
+| [messaging.md](messaging.md) | `ACTION`, `QUERY`, `QUERYALL`, `PERFORM`, `PerformAsync` |
+| [lifecycle.md](lifecycle.md) | Startup, shutdown, context, background task draining |
+| [configuration.md](configuration.md) | Constructor options, config state, feature flags |
+| [subsystems.md](subsystems.md) | `App`, `Data`, `Drive`, `Fs`, `I18n`, `Cli` |
+| [errors.md](errors.md) | Structured errors, logging helpers, panic recovery |
+| [testing.md](testing.md) | Test naming and framework-level testing patterns |
+| [pkg/core.md](pkg/core.md) | Package-level reference summary |
+| [pkg/log.md](pkg/log.md) | Logging reference for the root package |
+| [pkg/PACKAGE_STANDARDS.md](pkg/PACKAGE_STANDARDS.md) | AX package-authoring guidance |
+
+## Good Reading Order
+
+1. Start with [getting-started.md](getting-started.md).
+2. Learn the repeated shapes in [primitives.md](primitives.md).
+3. Pick the integration path you need next: [services.md](services.md), [commands.md](commands.md), or [messaging.md](messaging.md).
+4. Use [subsystems.md](subsystems.md), [errors.md](errors.md), and [testing.md](testing.md) as reference pages while building.
diff --git a/.core/reference/docs/lifecycle.md b/.core/reference/docs/lifecycle.md
new file mode 100644
index 0000000..59ba644
--- /dev/null
+++ b/.core/reference/docs/lifecycle.md
@@ -0,0 +1,111 @@
+---
+title: Lifecycle
+description: Startup, shutdown, context ownership, and background task draining.
+---
+
+# Lifecycle
+
+CoreGO manages lifecycle through `core.Service` callbacks, not through reflection or implicit interfaces.
+
+## Service Hooks
+
+```go
+c.Service("cache", core.Service{
+ OnStart: func() core.Result {
+ return core.Result{OK: true}
+ },
+ OnStop: func() core.Result {
+ return core.Result{OK: true}
+ },
+})
+```
+
+Only services with `OnStart` appear in `Startables()`. Only services with `OnStop` appear in `Stoppables()`.
+
+## `ServiceStartup`
+
+```go
+r := c.ServiceStartup(context.Background(), nil)
+```
+
+### What It Does
+
+1. clears the shutdown flag
+2. stores a new cancellable context on `c.Context()`
+3. runs each `OnStart`
+4. broadcasts `ActionServiceStartup{}`
+
+### Failure Behavior
+
+- if the input context is already cancelled, startup returns that error
+- if any `OnStart` returns `OK:false`, startup stops immediately and returns that result
+
+## `ServiceShutdown`
+
+```go
+r := c.ServiceShutdown(context.Background())
+```
+
+### What It Does
+
+1. sets the shutdown flag
+2. cancels `c.Context()`
+3. broadcasts `ActionServiceShutdown{}`
+4. waits for background tasks created by `PerformAsync`
+5. runs each `OnStop`
+
+### Failure Behavior
+
+- if draining background tasks hits the shutdown context deadline, shutdown returns that context error
+- when service stop hooks fail, CoreGO returns the first error it sees
+
+## Ordering
+
+The current implementation builds `Startables()` and `Stoppables()` by iterating over a map-backed registry.
+
+That means lifecycle order is not guaranteed today.
+
+If your application needs strict startup or shutdown ordering, orchestrate it explicitly inside a smaller number of service callbacks instead of relying on registry order.
+
+## `c.Context()`
+
+`ServiceStartup` creates the context returned by `c.Context()`.
+
+Use it for background work that should stop when the application shuts down:
+
+```go
+c.Service("watcher", core.Service{
+ OnStart: func() core.Result {
+ go func(ctx context.Context) {
+ <-ctx.Done()
+ }(c.Context())
+ return core.Result{OK: true}
+ },
+})
+```
+
+## Built-In Lifecycle Actions
+
+You can listen for lifecycle state changes through the action bus.
+
+```go
+c.RegisterAction(func(_ *core.Core, msg core.Message) core.Result {
+ switch msg.(type) {
+ case core.ActionServiceStartup:
+ core.Info("core startup completed")
+ case core.ActionServiceShutdown:
+ core.Info("core shutdown started")
+ }
+ return core.Result{OK: true}
+})
+```
+
+## Background Task Draining
+
+`ServiceShutdown` waits for the internal task waitgroup to finish before calling stop hooks.
+
+This is what makes `PerformAsync` safe for long-running work that should complete before teardown.
+
+## `OnReload`
+
+`Service` includes an `OnReload` callback field, but CoreGO does not currently expose a top-level lifecycle runner for reload operations.
diff --git a/.core/reference/docs/messaging.md b/.core/reference/docs/messaging.md
new file mode 100644
index 0000000..688893a
--- /dev/null
+++ b/.core/reference/docs/messaging.md
@@ -0,0 +1,171 @@
+---
+title: Messaging
+description: ACTION, QUERY, QUERYALL, PERFORM, and async task flow.
+---
+
+# Messaging
+
+CoreGO uses one message bus for broadcasts, lookups, and work dispatch.
+
+## Message Types
+
+```go
+type Message any
+type Query any
+type Task any
+```
+
+Your own structs define the protocol.
+
+```go
+type repositoryIndexed struct {
+ Name string
+}
+
+type repositoryCountQuery struct{}
+
+type syncRepositoryTask struct {
+ Name string
+}
+```
+
+## `ACTION`
+
+`ACTION` is a broadcast.
+
+```go
+c.RegisterAction(func(_ *core.Core, msg core.Message) core.Result {
+ switch m := msg.(type) {
+ case repositoryIndexed:
+ core.Info("repository indexed", "name", m.Name)
+ return core.Result{OK: true}
+ }
+ return core.Result{OK: true}
+})
+
+r := c.ACTION(repositoryIndexed{Name: "core-go"})
+```
+
+### Behavior
+
+- all registered action handlers are called in their current registration order
+- if a handler returns `OK:false`, dispatch stops and that `Result` is returned
+- if no handler fails, `ACTION` returns `Result{OK:true}`
+
+## `QUERY`
+
+`QUERY` is first-match request-response.
+
+```go
+c.RegisterQuery(func(_ *core.Core, q core.Query) core.Result {
+ switch q.(type) {
+ case repositoryCountQuery:
+ return core.Result{Value: 42, OK: true}
+ }
+ return core.Result{}
+})
+
+r := c.QUERY(repositoryCountQuery{})
+```
+
+### Behavior
+
+- handlers run until one returns `OK:true`
+- the first successful result wins
+- if nothing handles the query, CoreGO returns an empty `Result`
+
+## `QUERYALL`
+
+`QUERYALL` collects every successful non-nil response.
+
+```go
+r := c.QUERYALL(repositoryCountQuery{})
+results := r.Value.([]any)
+```
+
+### Behavior
+
+- every query handler is called
+- only `OK:true` results with non-nil `Value` are collected
+- the call itself returns `OK:true` even when the result list is empty
+
+## `PERFORM`
+
+`PERFORM` dispatches a task to the first handler that accepts it.
+
+```go
+c.RegisterTask(func(_ *core.Core, t core.Task) core.Result {
+ switch task := t.(type) {
+ case syncRepositoryTask:
+ return core.Result{Value: "synced " + task.Name, OK: true}
+ }
+ return core.Result{}
+})
+
+r := c.PERFORM(syncRepositoryTask{Name: "core-go"})
+```
+
+### Behavior
+
+- handlers run until one returns `OK:true`
+- the first successful result wins
+- if nothing handles the task, CoreGO returns an empty `Result`
+
+## `PerformAsync`
+
+`PerformAsync` runs a task in a background goroutine and returns a generated task identifier.
+
+```go
+r := c.PerformAsync(syncRepositoryTask{Name: "core-go"})
+taskID := r.Value.(string)
+```
+
+### Generated Events
+
+Async execution emits three action messages:
+
+| Message | When |
+|---------|------|
+| `ActionTaskStarted` | just before background execution begins |
+| `ActionTaskProgress` | whenever `Progress` is called |
+| `ActionTaskCompleted` | after the task finishes or panics |
+
+Example listener:
+
+```go
+c.RegisterAction(func(_ *core.Core, msg core.Message) core.Result {
+ switch m := msg.(type) {
+ case core.ActionTaskCompleted:
+ core.Info("task completed", "task", m.TaskIdentifier, "err", m.Error)
+ }
+ return core.Result{OK: true}
+})
+```
+
+## Progress Updates
+
+```go
+c.Progress(taskID, 0.5, "indexing commits", syncRepositoryTask{Name: "core-go"})
+```
+
+That broadcasts `ActionTaskProgress`.
+
+## `TaskWithIdentifier`
+
+Tasks that implement `TaskWithIdentifier` receive the generated ID before dispatch.
+
+```go
+type trackedTask struct {
+ ID string
+ Name string
+}
+
+func (t *trackedTask) SetTaskIdentifier(id string) { t.ID = id }
+func (t *trackedTask) GetTaskIdentifier() string { return t.ID }
+```
+
+## Shutdown Interaction
+
+When shutdown has started, `PerformAsync` returns an empty `Result` instead of scheduling more work.
+
+This is why `ServiceShutdown` can safely drain the outstanding background tasks before stopping services.
diff --git a/.core/reference/docs/pkg/PACKAGE_STANDARDS.md b/.core/reference/docs/pkg/PACKAGE_STANDARDS.md
new file mode 100644
index 0000000..398bbf6
--- /dev/null
+++ b/.core/reference/docs/pkg/PACKAGE_STANDARDS.md
@@ -0,0 +1,138 @@
+# AX Package Standards
+
+This page describes how to build packages on top of CoreGO in the style described by RFC-025.
+
+## 1. Prefer Predictable Names
+
+Use names that tell an agent what the thing is without translation.
+
+Good:
+
+- `RepositoryService`
+- `RepositoryServiceOptions`
+- `WorkspaceCountQuery`
+- `SyncRepositoryTask`
+
+Avoid shortening names unless the abbreviation is already universal.
+
+## 2. Put Real Usage in Comments
+
+Write comments that show a real call with realistic values.
+
+Good:
+
+```go
+// Sync a repository into the local workspace cache.
+// svc.SyncRepository("core-go", "/srv/repos/core-go")
+```
+
+Avoid comments that only repeat the signature.
+
+## 3. Keep Paths Semantic
+
+If a command or template lives at a path, let the path explain the intent.
+
+Good:
+
+```text
+deploy/to/homelab
+workspace/create
+template/workspace/go
+```
+
+That keeps the CLI, tests, docs, and message vocabulary aligned.
+
+## 4. Reuse CoreGO Primitives
+
+At Core boundaries, prefer the shared shapes:
+
+- `core.Options` for lightweight input
+- `core.Result` for output
+- `core.Service` for lifecycle registration
+- `core.Message`, `core.Query`, `core.Task` for bus protocols
+
+Inside your package, typed structs are still good. Use `ServiceRuntime[T]` when you want typed package options plus a `Core` reference.
+
+```go
+type repositoryServiceOptions struct {
+ BaseDirectory string
+}
+
+type repositoryService struct {
+ *core.ServiceRuntime[repositoryServiceOptions]
+}
+```
+
+## 5. Prefer Explicit Registration
+
+Register services and commands with names and paths that stay readable in grep results.
+
+```go
+c.Service("repository", core.Service{...})
+c.Command("repository/sync", core.Command{...})
+```
+
+## 6. Use the Bus for Decoupling
+
+When one package needs another package’s behavior, prefer queries and tasks over tight package coupling.
+
+```go
+type repositoryCountQuery struct{}
+type syncRepositoryTask struct {
+ Name string
+}
+```
+
+That keeps the protocol visible in code and easy for agents to follow.
+
+## 7. Use Structured Errors
+
+Use `core.E`, `core.Wrap`, and `core.WrapCode`.
+
+```go
+return core.Result{
+ Value: core.E("repository.Sync", "git fetch failed", err),
+ OK: false,
+}
+```
+
+Do not introduce free-form `fmt.Errorf` chains in framework code.
+
+## 8. Keep Testing Names Predictable
+
+Follow the repository pattern:
+
+- `_Good`
+- `_Bad`
+- `_Ugly`
+
+Example:
+
+```go
+func TestRepositorySync_Good(t *testing.T) {}
+func TestRepositorySync_Bad(t *testing.T) {}
+func TestRepositorySync_Ugly(t *testing.T) {}
+```
+
+## 9. Prefer Stable Shapes Over Clever APIs
+
+For package APIs, avoid patterns that force an agent to infer too much hidden control flow.
+
+Prefer:
+
+- clear structs
+- explicit names
+- path-based commands
+- visible message types
+
+Avoid:
+
+- implicit global state unless it is truly a default service
+- panic-hiding constructors
+- dense option chains when a small explicit struct would do
+
+## 10. Document the Current Reality
+
+If the implementation is in transition, document what the code does now, not the API shape you plan to have later.
+
+That keeps agents correct on first pass, which is the real AX metric.
diff --git a/.core/reference/docs/pkg/core.md b/.core/reference/docs/pkg/core.md
new file mode 100644
index 0000000..88bd18b
--- /dev/null
+++ b/.core/reference/docs/pkg/core.md
@@ -0,0 +1,81 @@
+# Package Reference: `core`
+
+Import path:
+
+```go
+import "dappco.re/go/core"
+```
+
+This repository exposes one root package. The main areas are:
+
+## Constructors and Accessors
+
+| Name | Purpose |
+|------|---------|
+| `New` | Create a `*Core` |
+| `NewRuntime` | Create an empty runtime wrapper |
+| `NewWithFactories` | Create a runtime wrapper from named service factories |
+| `Options`, `App`, `Data`, `Drive`, `Fs`, `Config`, `Error`, `Log`, `Cli`, `IPC`, `I18n`, `Context` | Access the built-in subsystems |
+
+## Core Primitives
+
+| Name | Purpose |
+|------|---------|
+| `Option`, `Options` | Input configuration and metadata |
+| `Result` | Shared output shape |
+| `Service` | Lifecycle DTO |
+| `Command` | Command tree node |
+| `Message`, `Query`, `Task` | Message bus payload types |
+
+## Service and Runtime APIs
+
+| Name | Purpose |
+|------|---------|
+| `Service` | Register or read a named service |
+| `Services` | List registered service names |
+| `Startables`, `Stoppables` | Snapshot lifecycle-capable services |
+| `LockEnable`, `LockApply` | Activate the service registry lock |
+| `ServiceRuntime[T]` | Helper for package authors |
+
+## Command and CLI APIs
+
+| Name | Purpose |
+|------|---------|
+| `Command` | Register or read a command by path |
+| `Commands` | List command paths |
+| `Cli().Run` | Resolve arguments to a command and execute it |
+| `Cli().PrintHelp` | Show executable commands |
+
+## Messaging APIs
+
+| Name | Purpose |
+|------|---------|
+| `ACTION`, `Action` | Broadcast a message |
+| `QUERY`, `Query` | Return the first successful query result |
+| `QUERYALL`, `QueryAll` | Collect all successful query results |
+| `PERFORM`, `Perform` | Run the first task handler that accepts the task |
+| `PerformAsync` | Run a task in the background |
+| `Progress` | Broadcast async task progress |
+| `RegisterAction`, `RegisterActions`, `RegisterQuery`, `RegisterTask` | Register bus handlers |
+
+## Subsystems
+
+| Name | Purpose |
+|------|---------|
+| `Config` | Runtime settings and feature flags |
+| `Data` | Embedded filesystem mounts |
+| `Drive` | Named transport handles |
+| `Fs` | Local filesystem operations |
+| `I18n` | Locale collection and translation delegation |
+| `App`, `Find` | Application identity and executable lookup |
+
+## Errors and Logging
+
+| Name | Purpose |
+|------|---------|
+| `E`, `Wrap`, `WrapCode`, `NewCode` | Structured error creation |
+| `Operation`, `ErrorCode`, `ErrorMessage`, `Root`, `StackTrace`, `FormatStackTrace` | Error inspection |
+| `NewLog`, `Default`, `SetDefault`, `SetLevel`, `SetRedactKeys` | Logger creation and defaults |
+| `LogErr`, `LogPanic`, `ErrorLog`, `ErrorPanic` | Error-aware logging and panic recovery |
+
+Use the top-level docs in `docs/` for task-oriented guidance, then use this page as a compact reference.
diff --git a/.core/reference/docs/pkg/log.md b/.core/reference/docs/pkg/log.md
new file mode 100644
index 0000000..15e9db1
--- /dev/null
+++ b/.core/reference/docs/pkg/log.md
@@ -0,0 +1,83 @@
+# Logging Reference
+
+Logging lives in the root `core` package in this repository. There is no separate `pkg/log` import path here.
+
+## Create a Logger
+
+```go
+logger := core.NewLog(core.LogOptions{
+ Level: core.LevelInfo,
+})
+```
+
+## Levels
+
+| Level | Meaning |
+|-------|---------|
+| `LevelQuiet` | no output |
+| `LevelError` | errors and security events |
+| `LevelWarn` | warnings, errors, security events |
+| `LevelInfo` | informational, warnings, errors, security events |
+| `LevelDebug` | everything |
+
+## Log Methods
+
+```go
+logger.Debug("workspace discovered", "path", "/srv/workspaces")
+logger.Info("service started", "service", "audit")
+logger.Warn("retrying fetch", "attempt", 2)
+logger.Error("fetch failed", "err", err)
+logger.Security("sandbox escape detected", "path", attemptedPath)
+```
+
+## Default Logger
+
+The package owns a default logger.
+
+```go
+core.SetLevel(core.LevelDebug)
+core.SetRedactKeys("token", "password")
+
+core.Info("service started", "service", "audit")
+```
+
+## Redaction
+
+Values for keys listed in `RedactKeys` are replaced with `[REDACTED]`.
+
+```go
+logger.SetRedactKeys("token")
+logger.Info("login", "user", "cladius", "token", "secret-value")
+```
+
+## Output and Rotation
+
+```go
+logger := core.NewLog(core.LogOptions{
+ Level: core.LevelInfo,
+ Output: os.Stderr,
+})
+```
+
+If you provide `Rotation` and set `RotationWriterFactory`, the logger writes to the rotating writer instead of the plain output stream.
+
+## Error-Aware Logging
+
+`LogErr` extracts structured error context before logging:
+
+```go
+le := core.NewLogErr(logger)
+le.Log(err)
+```
+
+`ErrorLog` is the log-and-return wrapper exposed through `c.Log()`.
+
+## Panic-Aware Logging
+
+`LogPanic` is the lightweight panic logger:
+
+```go
+defer core.NewLogPanic(logger).Recover()
+```
+
+It logs the recovered panic but does not manage crash files. For crash reports, use `c.Error().Recover()`.
diff --git a/.core/reference/docs/plans/2026-03-09-lint-pattern-catalog-design.md b/.core/reference/docs/plans/2026-03-09-lint-pattern-catalog-design.md
new file mode 100644
index 0000000..0825791
--- /dev/null
+++ b/.core/reference/docs/plans/2026-03-09-lint-pattern-catalog-design.md
@@ -0,0 +1,261 @@
+# Lint Pattern Catalog & Polish Skill Design
+
+> **Partial implementation (14 Mar 2026):** Layer 1 (`core/lint` -- catalog, matcher, scanner, CLI) is fully implemented and documented at `docs/tools/lint/index.md`. Layer 2 (MCP subsystem in `go-ai`) and Layer 3 (Claude Code polish skill in `core/agent`) are NOT implemented. This plan is retained for those remaining layers.
+
+**Goal:** A structured pattern catalog (`core/lint`) that captures recurring code quality findings as regex rules, exposes them via MCP tools in `go-ai`, and orchestrates multi-AI code review via a Claude Code skill in `core/agent`.
+
+**Architecture:** Three layers — a standalone catalog+matcher library (`core/lint`), an MCP subsystem in `go-ai` that exposes lint tools to agents, and a Claude Code plugin in `core/agent` that orchestrates the "polish" workflow (deterministic checks + AI reviewers + feedback loop into the catalog).
+
+**Tech Stack:** Go (catalog, matcher, CLI, MCP subsystem), YAML (rule definitions), JSONL (findings output, compatible with `~/.core/ai/metrics/`), Claude Code plugin format (hooks.json, commands/*.md, plugin.json).
+
+---
+
+## Context
+
+During a code review sweep of 18 Go repos (March 2026), AI reviewers (Gemini, Claude) found ~20 recurring patterns: SQL injection, path traversal, XSS, missing constant-time comparison, goroutine leaks, Go 1.26 modernisation opportunities, and more. Many of these patterns repeat across repos.
+
+Currently these findings exist only as commit messages. This design captures them as a reusable, machine-readable catalog that:
+1. Deterministic tools can run immediately (regex matching)
+2. MCP-connected agents can query and apply
+3. LEM models can train on for "does this comply with CoreGo standards?" judgements
+4. Grows automatically as AI reviewers find new patterns
+
+## Layer 1: `core/lint` — Pattern Catalog & Matcher
+
+### Repository Structure
+
+```
+core/lint/
+├── go.mod # forge.lthn.ai/core/lint
+├── catalog/
+│ ├── go-security.yaml # SQL injection, path traversal, XSS, constant-time
+│ ├── go-modernise.yaml # Go 1.26: slices.Clone, wg.Go, maps.Keys, range-over-int
+│ ├── go-correctness.yaml # Deadlocks, goroutine leaks, nil guards, error handling
+│ ├── php-security.yaml # XSS, CSRF, mass assignment, SQL injection
+│ ├── ts-security.yaml # DOM XSS, prototype pollution
+│ └── cpp-safety.yaml # Buffer overflow, use-after-free
+├── pkg/lint/
+│ ├── catalog.go # Load + parse YAML catalog files
+│ ├── rule.go # Rule struct definition
+│ ├── matcher.go # Regex matcher against file contents
+│ ├── report.go # Structured findings output (JSON/JSONL/text)
+│ ├── catalog_test.go
+│ ├── matcher_test.go
+│ └── report_test.go
+├── cmd/core-lint/
+│ └── main.go # `core-lint check ./...` CLI
+└── .core/
+ └── build.yaml # Produces core-lint binary
+```
+
+### Rule Schema (YAML)
+
+```yaml
+- id: go-sec-001
+ title: "SQL wildcard injection in LIKE clauses"
+ severity: high # critical, high, medium, low, info
+ languages: [go]
+ tags: [security, injection, owasp-a03]
+ pattern: 'LIKE\s+\?\s*,\s*["\x60]%\s*\+'
+ exclude_pattern: 'EscapeLike' # suppress if this also matches
+ fix: "Use parameterised LIKE with explicit escaping of % and _ characters"
+ found_in: [go-store] # repos where first discovered
+ example_bad: |
+ db.Where("name LIKE ?", "%"+input+"%")
+ example_good: |
+ db.Where("name LIKE ?", EscapeLike(input))
+ first_seen: "2026-03-09"
+ detection: regex # future: ast, semantic
+ auto_fixable: false # future: true when we add codemods
+```
+
+### Rule Struct (Go)
+
+```go
+type Rule struct {
+ ID string `yaml:"id"`
+ Title string `yaml:"title"`
+ Severity string `yaml:"severity"`
+ Languages []string `yaml:"languages"`
+ Tags []string `yaml:"tags"`
+ Pattern string `yaml:"pattern"`
+ ExcludePattern string `yaml:"exclude_pattern,omitempty"`
+ Fix string `yaml:"fix"`
+ FoundIn []string `yaml:"found_in,omitempty"`
+ ExampleBad string `yaml:"example_bad,omitempty"`
+ ExampleGood string `yaml:"example_good,omitempty"`
+ FirstSeen string `yaml:"first_seen"`
+ Detection string `yaml:"detection"` // regex | ast | semantic
+ AutoFixable bool `yaml:"auto_fixable"`
+}
+```
+
+### Finding Struct (Go)
+
+Designed to align with go-ai's `ScanAlert` shape and `~/.core/ai/metrics/` JSONL format:
+
+```go
+type Finding struct {
+ RuleID string `json:"rule_id"`
+ Title string `json:"title"`
+ Severity string `json:"severity"`
+ File string `json:"file"`
+ Line int `json:"line"`
+ Match string `json:"match"` // matched text
+ Fix string `json:"fix"`
+ Repo string `json:"repo,omitempty"`
+}
+```
+
+### CLI Interface
+
+```bash
+# Check current directory against all catalogs for detected languages
+core-lint check ./...
+
+# Check specific languages/catalogs
+core-lint check --lang go --catalog go-security ./pkg/...
+
+# Output as JSON (for piping to other tools)
+core-lint check --format json ./...
+
+# List available rules
+core-lint catalog list
+core-lint catalog list --lang go --severity high
+
+# Show a specific rule with examples
+core-lint catalog show go-sec-001
+```
+
+## Layer 2: `go-ai` Lint MCP Subsystem
+
+New subsystem registered alongside files/rag/ml/brain:
+
+```go
+type LintSubsystem struct {
+ catalog *lint.Catalog
+ root string // workspace root for scanning
+}
+
+func (s *LintSubsystem) Name() string { return "lint" }
+
+func (s *LintSubsystem) RegisterTools(server *mcp.Server) {
+ // lint_check - run rules against workspace files
+ // lint_catalog - list/search available rules
+ // lint_report - get findings summary for a path
+}
+```
+
+### MCP Tools
+
+| Tool | Input | Output | Group |
+|------|-------|--------|-------|
+| `lint_check` | `{path: string, lang?: string, severity?: string}` | `{findings: []Finding}` | lint |
+| `lint_catalog` | `{lang?: string, tags?: []string, severity?: string}` | `{rules: []Rule}` | lint |
+| `lint_report` | `{path: string, format?: "summary" or "detailed"}` | `{summary: ReportSummary}` | lint |
+
+This means any MCP-connected agent (Claude, LEM, Codex) can call `lint_check` to scan code against the catalog.
+
+## Layer 3: `core/agent` Polish Skill
+
+Claude Code plugin at `core/agent/claude/polish/`:
+
+```
+core/agent/claude/polish/
+├── plugin.json
+├── hooks.json # optional: PostToolUse after git commit
+├── commands/
+│ └── polish.md # /polish slash command
+└── scripts/
+ └── run-lint.sh # shells out to core-lint
+```
+
+### `/polish` Command Flow
+
+1. Run `core-lint check ./...` for fast deterministic findings
+2. Report findings to user
+3. Optionally run AI reviewers (Gemini CLI, Codex) for deeper analysis
+4. Deduplicate AI findings against catalog (already-known patterns)
+5. Propose new patterns as catalog additions (PR to core/lint)
+
+### Subagent Configuration (`.core/agents/`)
+
+Repos can configure polish behaviour:
+
+```yaml
+# any-repo/.core/agents/polish.yaml
+languages: [go]
+catalogs: [go-security, go-modernise, go-correctness]
+reviewers: [gemini] # which AI tools to invoke
+exclude: [vendor/, testdata/, *_test.go]
+severity_threshold: medium # only report medium+ findings
+```
+
+## Findings to LEM Pipeline
+
+```
+core-lint check -> findings.json
+ |
+ v
+~/.core/ai/metrics/YYYY-MM-DD.jsonl (audit trail)
+ |
+ v
+LEM training data:
+ - Rule examples (bad/good pairs) -> supervised training signal
+ - Finding frequency -> pattern importance weighting
+ - Rule descriptions -> natural language understanding of "why"
+ |
+ v
+LEM tool: "does this code comply with CoreGo standards?"
+ -> queries lint_catalog via MCP
+ -> applies learned pattern recognition
+ -> reports violations with rule IDs and fixes
+```
+
+## Initial Catalog Seed
+
+From the March 2026 ecosystem sweep:
+
+| ID | Title | Severity | Language | Found In |
+|----|-------|----------|----------|----------|
+| go-sec-001 | SQL wildcard injection | high | go | go-store |
+| go-sec-002 | Path traversal in cache keys | high | go | go-cache |
+| go-sec-003 | XSS in HTML output | high | go | go-html |
+| go-sec-004 | Non-constant-time auth comparison | high | go | go-crypt |
+| go-sec-005 | Log injection via unescaped input | medium | go | go-log |
+| go-sec-006 | Key material in log output | high | go | go-log |
+| go-cor-001 | Goroutine leak (no WaitGroup) | high | go | core/go |
+| go-cor-002 | Shutdown deadlock (wg.Wait no timeout) | high | go | core/go |
+| go-cor-003 | Silent error swallowing | medium | go | go-process, go-ratelimit |
+| go-cor-004 | Panic in library code | medium | go | go-i18n |
+| go-cor-005 | Delete without path validation | high | go | go-io |
+| go-mod-001 | Manual slice clone (append nil pattern) | low | go | core/go |
+| go-mod-002 | Manual sort instead of slices.Sorted | low | go | core/go |
+| go-mod-003 | Manual reverse loop instead of slices.Backward | low | go | core/go |
+| go-mod-004 | sync.WaitGroup Add+Done instead of Go() | low | go | core/go |
+| go-mod-005 | Manual map key collection instead of maps.Keys | low | go | core/go |
+| go-cor-006 | Missing error return from API calls | medium | go | go-forge, go-git |
+| go-cor-007 | Signal handler uses wrong type | medium | go | go-process |
+
+## Dependencies
+
+```
+core/lint (standalone, zero core deps)
+ ^
+ |
+go-ai/mcp/lint/ (imports core/lint for catalog + matcher)
+ ^
+ |
+core/agent/claude/polish/ (shells out to core-lint CLI)
+```
+
+`core/lint` has no dependency on `core/go` or any other framework module. It is a standalone library + CLI, like `core/go-io`.
+
+## Future Extensions (Not Built Now)
+
+- **AST-based detection** (layer 2): Parse Go/PHP AST, match structural patterns
+- **Semantic detection** (layer 3): LEM judges code against rule descriptions
+- **Auto-fix codemods**: `core-lint fix` applies known fixes automatically
+- **CI integration**: GitHub Actions workflow runs `core-lint check` on PRs
+- **CodeRabbit integration**: Import CodeRabbit findings as catalog entries
+- **Cross-repo dashboard**: Aggregate findings across all repos in workspace
diff --git a/.core/reference/docs/plans/2026-03-09-lint-pattern-catalog-plan.md b/.core/reference/docs/plans/2026-03-09-lint-pattern-catalog-plan.md
new file mode 100644
index 0000000..7f1ddec
--- /dev/null
+++ b/.core/reference/docs/plans/2026-03-09-lint-pattern-catalog-plan.md
@@ -0,0 +1,1668 @@
+# Lint Pattern Catalog Implementation Plan
+
+> **Fully implemented (14 Mar 2026).** All tasks in this plan are complete. The `core/lint` module ships 18 rules across 3 catalogs, with a working CLI and embedded YAML. This plan is retained alongside the design doc, which tracks the remaining MCP and polish skill layers.
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Build `core/lint` — a standalone Go library + CLI that loads YAML pattern catalogs and runs regex-based code checks, seeded with 18 patterns from the March 2026 ecosystem sweep.
+
+**Architecture:** Standalone Go module (`forge.lthn.ai/core/lint`) with zero framework deps. YAML catalog files define rules (id, severity, regex pattern, fix). `pkg/lint` loads catalogs and matches patterns against files. `cmd/core-lint` is a Cobra CLI. Uses `cli.Main()` + `cli.WithCommands()` from `core/cli`.
+
+**Tech Stack:** Go 1.26, `gopkg.in/yaml.v3` (YAML parsing), `forge.lthn.ai/core/cli` (CLI framework), `github.com/stretchr/testify` (testing), `embed` (catalog embedding).
+
+---
+
+### Task 1: Create repo and Go module
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/go.mod`
+- Create: `/Users/snider/Code/core/lint/.core/build.yaml`
+- Create: `/Users/snider/Code/core/lint/CLAUDE.md`
+
+**Step 1: Create repo on forge**
+
+```bash
+ssh -p 2223 git@forge.lthn.ai
+```
+
+If SSH repo creation isn't available, create via Forgejo API:
+```bash
+curl -X POST "https://forge.lthn.ai/api/v1/orgs/core/repos" \
+ -H "Authorization: token $FORGE_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{"name":"lint","description":"Pattern catalog & regex matcher for code quality","auto_init":true,"default_branch":"main"}'
+```
+
+Or manually create on forge.lthn.ai web UI under the `core` org.
+
+**Step 2: Clone and initialise Go module**
+
+```bash
+cd ~/Code/core
+git clone ssh://git@forge.lthn.ai:2223/core/lint.git
+cd lint
+go mod init forge.lthn.ai/core/lint
+```
+
+Set Go version in go.mod:
+```
+module forge.lthn.ai/core/lint
+
+go 1.26.0
+```
+
+**Step 3: Create `.core/build.yaml`**
+
+```yaml
+version: 1
+
+project:
+ name: core-lint
+ description: Pattern catalog and regex code checker
+ main: ./cmd/core-lint
+ binary: core-lint
+
+build:
+ cgo: false
+ flags:
+ - -trimpath
+ ldflags:
+ - -s
+ - -w
+
+targets:
+ - os: linux
+ arch: amd64
+ - os: linux
+ arch: arm64
+ - os: darwin
+ arch: arm64
+ - os: windows
+ arch: amd64
+```
+
+**Step 4: Create `CLAUDE.md`**
+
+```markdown
+# CLAUDE.md
+
+## Project Overview
+
+`core/lint` is a standalone pattern catalog and regex-based code checker. It loads YAML rule definitions and matches them against source files. Zero framework dependencies.
+
+## Build & Development
+
+```bash
+core go test
+core go qa
+core build # produces ./bin/core-lint
+```
+
+## Architecture
+
+- `catalog/` — YAML rule files (embedded at compile time)
+- `pkg/lint/` — Library: Rule, Catalog, Matcher, Report types
+- `cmd/core-lint/` — CLI binary using `cli.Main()`
+
+## Rule Schema
+
+Each YAML file contains an array of rules with: id, title, severity, languages, tags, pattern (regex), exclude_pattern, fix, example_bad, example_good, detection type.
+
+## Coding Standards
+
+- UK English
+- `declare(strict_types=1)` equivalent: all functions have typed params/returns
+- Tests use testify
+- License: EUPL-1.2
+```
+
+**Step 5: Add to go.work**
+
+Add `./core/lint` to `~/Code/go.work` under the Core framework section.
+
+**Step 6: Commit**
+
+```bash
+git add go.mod .core/ CLAUDE.md
+git commit -m "feat: initialise core/lint module"
+```
+
+---
+
+### Task 2: Rule struct and YAML parsing
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/pkg/lint/rule.go`
+- Create: `/Users/snider/Code/core/lint/pkg/lint/rule_test.go`
+
+**Step 1: Write the failing test**
+
+```go
+package lint
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestParseRules(t *testing.T) {
+ yaml := `
+- id: test-001
+ title: "Test rule"
+ severity: high
+ languages: [go]
+ tags: [security]
+ pattern: 'fmt\.Println'
+ fix: "Use structured logging"
+ detection: regex
+`
+ rules, err := ParseRules([]byte(yaml))
+ require.NoError(t, err)
+ require.Len(t, rules, 1)
+ assert.Equal(t, "test-001", rules[0].ID)
+ assert.Equal(t, "high", rules[0].Severity)
+ assert.Equal(t, []string{"go"}, rules[0].Languages)
+ assert.Equal(t, `fmt\.Println`, rules[0].Pattern)
+}
+
+func TestParseRules_Invalid(t *testing.T) {
+ _, err := ParseRules([]byte("not: valid: yaml: ["))
+ assert.Error(t, err)
+}
+
+func TestRule_Validate(t *testing.T) {
+ good := Rule{ID: "x-001", Title: "T", Severity: "high", Languages: []string{"go"}, Pattern: "foo", Detection: "regex"}
+ assert.NoError(t, good.Validate())
+
+ bad := Rule{} // missing required fields
+ assert.Error(t, bad.Validate())
+}
+
+func TestRule_Validate_BadRegex(t *testing.T) {
+ r := Rule{ID: "x-001", Title: "T", Severity: "high", Languages: []string{"go"}, Pattern: "[invalid", Detection: "regex"}
+ assert.Error(t, r.Validate())
+}
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v`
+Expected: FAIL — `ParseRules` and `Rule` not defined
+
+**Step 3: Write minimal implementation**
+
+```go
+package lint
+
+import (
+ "fmt"
+ "regexp"
+
+ "gopkg.in/yaml.v3"
+)
+
+// Rule defines a single lint pattern check.
+type Rule struct {
+ ID string `yaml:"id" json:"id"`
+ Title string `yaml:"title" json:"title"`
+ Severity string `yaml:"severity" json:"severity"`
+ Languages []string `yaml:"languages" json:"languages"`
+ Tags []string `yaml:"tags" json:"tags"`
+ Pattern string `yaml:"pattern" json:"pattern"`
+ ExcludePattern string `yaml:"exclude_pattern" json:"exclude_pattern,omitempty"`
+ Fix string `yaml:"fix" json:"fix"`
+ FoundIn []string `yaml:"found_in" json:"found_in,omitempty"`
+ ExampleBad string `yaml:"example_bad" json:"example_bad,omitempty"`
+ ExampleGood string `yaml:"example_good" json:"example_good,omitempty"`
+ FirstSeen string `yaml:"first_seen" json:"first_seen,omitempty"`
+ Detection string `yaml:"detection" json:"detection"`
+ AutoFixable bool `yaml:"auto_fixable" json:"auto_fixable"`
+}
+
+// Validate checks that a Rule has all required fields and a compilable regex pattern.
+func (r *Rule) Validate() error {
+ if r.ID == "" {
+ return fmt.Errorf("rule missing id")
+ }
+ if r.Title == "" {
+ return fmt.Errorf("rule %s: missing title", r.ID)
+ }
+ if r.Severity == "" {
+ return fmt.Errorf("rule %s: missing severity", r.ID)
+ }
+ if len(r.Languages) == 0 {
+ return fmt.Errorf("rule %s: missing languages", r.ID)
+ }
+ if r.Pattern == "" {
+ return fmt.Errorf("rule %s: missing pattern", r.ID)
+ }
+ if r.Detection == "regex" {
+ if _, err := regexp.Compile(r.Pattern); err != nil {
+ return fmt.Errorf("rule %s: invalid regex: %w", r.ID, err)
+ }
+ }
+ return nil
+}
+
+// ParseRules parses YAML bytes into a slice of Rules.
+func ParseRules(data []byte) ([]Rule, error) {
+ var rules []Rule
+ if err := yaml.Unmarshal(data, &rules); err != nil {
+ return nil, fmt.Errorf("parse rules: %w", err)
+ }
+ return rules, nil
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v`
+Expected: PASS (4 tests)
+
+**Step 5: Add yaml dependency**
+
+```bash
+cd ~/Code/core/lint && go get gopkg.in/yaml.v3 && go get github.com/stretchr/testify
+```
+
+**Step 6: Commit**
+
+```bash
+git add pkg/lint/rule.go pkg/lint/rule_test.go go.mod go.sum
+git commit -m "feat: add Rule struct with YAML parsing and validation"
+```
+
+---
+
+### Task 3: Catalog loader with embed support
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/pkg/lint/catalog.go`
+- Create: `/Users/snider/Code/core/lint/pkg/lint/catalog_test.go`
+- Create: `/Users/snider/Code/core/lint/catalog/go-security.yaml` (minimal test file)
+
+**Step 1: Create a minimal test catalog file**
+
+Create `/Users/snider/Code/core/lint/catalog/go-security.yaml`:
+```yaml
+- id: go-sec-001
+ title: "SQL wildcard injection in LIKE clauses"
+ severity: high
+ languages: [go]
+ tags: [security, injection]
+ pattern: 'LIKE\s+\?\s*,\s*["%].*\+'
+ fix: "Use parameterised LIKE with EscapeLike()"
+ found_in: [go-store]
+ first_seen: "2026-03-09"
+ detection: regex
+```
+
+**Step 2: Write the failing test**
+
+```go
+package lint
+
+import (
+ "embed"
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestCatalog_LoadDir(t *testing.T) {
+ // Find the catalog/ dir relative to the module root
+ dir := filepath.Join("..", "..", "catalog")
+ cat, err := LoadDir(dir)
+ require.NoError(t, err)
+ assert.Greater(t, len(cat.Rules), 0)
+ assert.Equal(t, "go-sec-001", cat.Rules[0].ID)
+}
+
+func TestCatalog_LoadDir_NotExist(t *testing.T) {
+ _, err := LoadDir("/nonexistent")
+ assert.Error(t, err)
+}
+
+func TestCatalog_Filter_Language(t *testing.T) {
+ cat := &Catalog{Rules: []Rule{
+ {ID: "go-001", Languages: []string{"go"}, Severity: "high"},
+ {ID: "php-001", Languages: []string{"php"}, Severity: "high"},
+ }}
+ filtered := cat.ForLanguage("go")
+ assert.Len(t, filtered, 1)
+ assert.Equal(t, "go-001", filtered[0].ID)
+}
+
+func TestCatalog_Filter_Severity(t *testing.T) {
+ cat := &Catalog{Rules: []Rule{
+ {ID: "a", Severity: "high"},
+ {ID: "b", Severity: "low"},
+ {ID: "c", Severity: "medium"},
+ }}
+ filtered := cat.AtSeverity("medium")
+ assert.Len(t, filtered, 2) // high + medium
+}
+
+func TestCatalog_LoadFS(t *testing.T) {
+ // Write temp yaml
+ dir := t.TempDir()
+ data := []byte(`- id: fs-001
+ title: "FS test"
+ severity: low
+ languages: [go]
+ tags: []
+ pattern: 'test'
+ fix: "fix"
+ detection: regex
+`)
+ require.NoError(t, os.WriteFile(filepath.Join(dir, "test.yaml"), data, 0644))
+
+ cat, err := LoadDir(dir)
+ require.NoError(t, err)
+ assert.Len(t, cat.Rules, 1)
+}
+```
+
+**Step 3: Write minimal implementation**
+
+```go
+package lint
+
+import (
+ "embed"
+ "fmt"
+ "io/fs"
+ "os"
+ "path/filepath"
+ "slices"
+ "strings"
+)
+
+// Catalog holds a collection of lint rules loaded from YAML files.
+type Catalog struct {
+ Rules []Rule
+}
+
+// severityOrder maps severity names to numeric priority (higher = more severe).
+var severityOrder = map[string]int{
+ "critical": 5,
+ "high": 4,
+ "medium": 3,
+ "low": 2,
+ "info": 1,
+}
+
+// LoadDir loads all .yaml files from a directory path into a Catalog.
+func LoadDir(dir string) (*Catalog, error) {
+ entries, err := os.ReadDir(dir)
+ if err != nil {
+ return nil, fmt.Errorf("load catalog dir: %w", err)
+ }
+
+ cat := &Catalog{}
+ for _, entry := range entries {
+ if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".yaml") {
+ continue
+ }
+ data, err := os.ReadFile(filepath.Join(dir, entry.Name()))
+ if err != nil {
+ return nil, fmt.Errorf("read %s: %w", entry.Name(), err)
+ }
+ rules, err := ParseRules(data)
+ if err != nil {
+ return nil, fmt.Errorf("parse %s: %w", entry.Name(), err)
+ }
+ cat.Rules = append(cat.Rules, rules...)
+ }
+ return cat, nil
+}
+
+// LoadFS loads all .yaml files from an embed.FS into a Catalog.
+func LoadFS(fsys embed.FS, dir string) (*Catalog, error) {
+ cat := &Catalog{}
+ err := fs.WalkDir(fsys, dir, func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if d.IsDir() || !strings.HasSuffix(path, ".yaml") {
+ return nil
+ }
+ data, err := fsys.ReadFile(path)
+ if err != nil {
+ return fmt.Errorf("read %s: %w", path, err)
+ }
+ rules, err := ParseRules(data)
+ if err != nil {
+ return fmt.Errorf("parse %s: %w", path, err)
+ }
+ cat.Rules = append(cat.Rules, rules...)
+ return nil
+ })
+ if err != nil {
+ return nil, err
+ }
+ return cat, nil
+}
+
+// ForLanguage returns rules that apply to the given language.
+func (c *Catalog) ForLanguage(lang string) []Rule {
+ var out []Rule
+ for _, r := range c.Rules {
+ if slices.Contains(r.Languages, lang) {
+ out = append(out, r)
+ }
+ }
+ return out
+}
+
+// AtSeverity returns rules at or above the given severity threshold.
+func (c *Catalog) AtSeverity(threshold string) []Rule {
+ minLevel := severityOrder[threshold]
+ var out []Rule
+ for _, r := range c.Rules {
+ if severityOrder[r.Severity] >= minLevel {
+ out = append(out, r)
+ }
+ }
+ return out
+}
+
+// ByID returns a rule by its ID, or nil if not found.
+func (c *Catalog) ByID(id string) *Rule {
+ for i := range c.Rules {
+ if c.Rules[i].ID == id {
+ return &c.Rules[i]
+ }
+ }
+ return nil
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v`
+Expected: PASS (all tests)
+
+**Step 5: Commit**
+
+```bash
+git add pkg/lint/catalog.go pkg/lint/catalog_test.go catalog/go-security.yaml
+git commit -m "feat: add Catalog loader with dir/embed/filter support"
+```
+
+---
+
+### Task 4: Regex matcher
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/pkg/lint/matcher.go`
+- Create: `/Users/snider/Code/core/lint/pkg/lint/matcher_test.go`
+
+**Step 1: Write the failing test**
+
+```go
+package lint
+
+import (
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestMatcher_Match(t *testing.T) {
+ rules := []Rule{
+ {
+ ID: "test-001",
+ Title: "fmt.Println usage",
+ Severity: "low",
+ Languages: []string{"go"},
+ Pattern: `fmt\.Println`,
+ Fix: "Use structured logging",
+ Detection: "regex",
+ },
+ }
+ m, err := NewMatcher(rules)
+ require.NoError(t, err)
+
+ content := `package main
+
+import "fmt"
+
+func main() {
+ fmt.Println("hello")
+}
+`
+ findings := m.Match("main.go", []byte(content))
+ require.Len(t, findings, 1)
+ assert.Equal(t, "test-001", findings[0].RuleID)
+ assert.Equal(t, "main.go", findings[0].File)
+ assert.Equal(t, 6, findings[0].Line)
+ assert.Contains(t, findings[0].Match, "fmt.Println")
+}
+
+func TestMatcher_ExcludePattern(t *testing.T) {
+ rules := []Rule{
+ {
+ ID: "test-002",
+ Title: "Println with exclude",
+ Severity: "low",
+ Languages: []string{"go"},
+ Pattern: `fmt\.Println`,
+ ExcludePattern: `// lint:ignore`,
+ Fix: "Use logging",
+ Detection: "regex",
+ },
+ }
+ m, err := NewMatcher(rules)
+ require.NoError(t, err)
+
+ content := `package main
+func a() { fmt.Println("bad") }
+func b() { fmt.Println("ok") // lint:ignore }
+`
+ findings := m.Match("main.go", []byte(content))
+ // Line 2 matches, line 3 is excluded
+ assert.Len(t, findings, 1)
+ assert.Equal(t, 2, findings[0].Line)
+}
+
+func TestMatcher_NoMatch(t *testing.T) {
+ rules := []Rule{
+ {ID: "test-003", Title: "T", Severity: "low", Languages: []string{"go"}, Pattern: `NEVER_MATCH_THIS`, Detection: "regex"},
+ }
+ m, err := NewMatcher(rules)
+ require.NoError(t, err)
+
+ findings := m.Match("main.go", []byte("package main\n"))
+ assert.Empty(t, findings)
+}
+
+func TestMatcher_InvalidRegex(t *testing.T) {
+ rules := []Rule{
+ {ID: "bad", Title: "T", Severity: "low", Languages: []string{"go"}, Pattern: `[invalid`, Detection: "regex"},
+ }
+ _, err := NewMatcher(rules)
+ assert.Error(t, err)
+}
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v -run TestMatcher`
+Expected: FAIL — `NewMatcher` not defined
+
+**Step 3: Write minimal implementation**
+
+```go
+package lint
+
+import (
+ "fmt"
+ "regexp"
+ "strings"
+)
+
+// Finding represents a single match of a rule against source code.
+type Finding struct {
+ RuleID string `json:"rule_id"`
+ Title string `json:"title"`
+ Severity string `json:"severity"`
+ File string `json:"file"`
+ Line int `json:"line"`
+ Match string `json:"match"`
+ Fix string `json:"fix"`
+ Repo string `json:"repo,omitempty"`
+}
+
+// compiledRule is a rule with its regex pre-compiled.
+type compiledRule struct {
+ rule Rule
+ pattern *regexp.Regexp
+ exclude *regexp.Regexp
+}
+
+// Matcher runs compiled rules against file contents.
+type Matcher struct {
+ rules []compiledRule
+}
+
+// NewMatcher compiles all rule patterns and returns a Matcher.
+func NewMatcher(rules []Rule) (*Matcher, error) {
+ compiled := make([]compiledRule, 0, len(rules))
+ for _, r := range rules {
+ if r.Detection != "regex" {
+ continue // skip non-regex rules
+ }
+ p, err := regexp.Compile(r.Pattern)
+ if err != nil {
+ return nil, fmt.Errorf("rule %s: invalid pattern: %w", r.ID, err)
+ }
+ cr := compiledRule{rule: r, pattern: p}
+ if r.ExcludePattern != "" {
+ ex, err := regexp.Compile(r.ExcludePattern)
+ if err != nil {
+ return nil, fmt.Errorf("rule %s: invalid exclude_pattern: %w", r.ID, err)
+ }
+ cr.exclude = ex
+ }
+ compiled = append(compiled, cr)
+ }
+ return &Matcher{rules: compiled}, nil
+}
+
+// Match checks file contents against all rules and returns findings.
+func (m *Matcher) Match(filename string, content []byte) []Finding {
+ lines := strings.Split(string(content), "\n")
+ var findings []Finding
+
+ for _, cr := range m.rules {
+ for i, line := range lines {
+ if !cr.pattern.MatchString(line) {
+ continue
+ }
+ if cr.exclude != nil && cr.exclude.MatchString(line) {
+ continue
+ }
+ findings = append(findings, Finding{
+ RuleID: cr.rule.ID,
+ Title: cr.rule.Title,
+ Severity: cr.rule.Severity,
+ File: filename,
+ Line: i + 1,
+ Match: strings.TrimSpace(line),
+ Fix: cr.rule.Fix,
+ })
+ }
+ }
+ return findings
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v -run TestMatcher`
+Expected: PASS (4 tests)
+
+**Step 5: Commit**
+
+```bash
+git add pkg/lint/matcher.go pkg/lint/matcher_test.go
+git commit -m "feat: add regex Matcher with exclude pattern support"
+```
+
+---
+
+### Task 5: Report output (JSON, text, JSONL)
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/pkg/lint/report.go`
+- Create: `/Users/snider/Code/core/lint/pkg/lint/report_test.go`
+
+**Step 1: Write the failing test**
+
+```go
+package lint
+
+import (
+ "bytes"
+ "encoding/json"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestReport_JSON(t *testing.T) {
+ findings := []Finding{
+ {RuleID: "x-001", Title: "Test", Severity: "high", File: "a.go", Line: 10, Match: "bad code", Fix: "fix it"},
+ }
+ var buf bytes.Buffer
+ require.NoError(t, WriteJSON(&buf, findings))
+
+ var parsed []Finding
+ require.NoError(t, json.Unmarshal(buf.Bytes(), &parsed))
+ assert.Len(t, parsed, 1)
+ assert.Equal(t, "x-001", parsed[0].RuleID)
+}
+
+func TestReport_JSONL(t *testing.T) {
+ findings := []Finding{
+ {RuleID: "a-001", File: "a.go", Line: 1},
+ {RuleID: "b-001", File: "b.go", Line: 2},
+ }
+ var buf bytes.Buffer
+ require.NoError(t, WriteJSONL(&buf, findings))
+
+ lines := strings.Split(strings.TrimSpace(buf.String()), "\n")
+ assert.Len(t, lines, 2)
+}
+
+func TestReport_Text(t *testing.T) {
+ findings := []Finding{
+ {RuleID: "x-001", Title: "Test rule", Severity: "high", File: "main.go", Line: 42, Match: "bad()", Fix: "use good()"},
+ }
+ var buf bytes.Buffer
+ WriteText(&buf, findings)
+
+ out := buf.String()
+ assert.Contains(t, out, "main.go:42")
+ assert.Contains(t, out, "x-001")
+ assert.Contains(t, out, "high")
+}
+
+func TestReport_Summary(t *testing.T) {
+ findings := []Finding{
+ {Severity: "high"},
+ {Severity: "high"},
+ {Severity: "low"},
+ }
+ s := Summarise(findings)
+ assert.Equal(t, 3, s.Total)
+ assert.Equal(t, 2, s.BySeverity["high"])
+ assert.Equal(t, 1, s.BySeverity["low"])
+}
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v -run TestReport`
+Expected: FAIL — functions not defined
+
+**Step 3: Write minimal implementation**
+
+```go
+package lint
+
+import (
+ "encoding/json"
+ "fmt"
+ "io"
+)
+
+// Summary holds aggregate stats about findings.
+type Summary struct {
+ Total int `json:"total"`
+ BySeverity map[string]int `json:"by_severity"`
+}
+
+// Summarise creates a Summary from a list of findings.
+func Summarise(findings []Finding) Summary {
+ s := Summary{
+ Total: len(findings),
+ BySeverity: make(map[string]int),
+ }
+ for _, f := range findings {
+ s.BySeverity[f.Severity]++
+ }
+ return s
+}
+
+// WriteJSON writes findings as a JSON array.
+func WriteJSON(w io.Writer, findings []Finding) error {
+ enc := json.NewEncoder(w)
+ enc.SetIndent("", " ")
+ return enc.Encode(findings)
+}
+
+// WriteJSONL writes findings as newline-delimited JSON (one object per line).
+// Compatible with ~/.core/ai/metrics/ format.
+func WriteJSONL(w io.Writer, findings []Finding) error {
+ enc := json.NewEncoder(w)
+ for _, f := range findings {
+ if err := enc.Encode(f); err != nil {
+ return err
+ }
+ }
+ return nil
+}
+
+// WriteText writes findings as human-readable text.
+func WriteText(w io.Writer, findings []Finding) {
+ for _, f := range findings {
+ fmt.Fprintf(w, "%s:%d [%s] %s (%s)\n", f.File, f.Line, f.Severity, f.Title, f.RuleID)
+ if f.Fix != "" {
+ fmt.Fprintf(w, " fix: %s\n", f.Fix)
+ }
+ }
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v -run TestReport`
+Expected: PASS (4 tests)
+
+**Step 5: Commit**
+
+```bash
+git add pkg/lint/report.go pkg/lint/report_test.go
+git commit -m "feat: add report output (JSON, JSONL, text, summary)"
+```
+
+---
+
+### Task 6: Scanner (walk files + match)
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/pkg/lint/scanner.go`
+- Create: `/Users/snider/Code/core/lint/pkg/lint/scanner_test.go`
+
+**Step 1: Write the failing test**
+
+```go
+package lint
+
+import (
+ "os"
+ "path/filepath"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestScanner_ScanDir(t *testing.T) {
+ // Set up temp dir with a .go file containing a known pattern
+ dir := t.TempDir()
+ goFile := filepath.Join(dir, "main.go")
+ require.NoError(t, os.WriteFile(goFile, []byte(`package main
+
+import "fmt"
+
+func main() {
+ fmt.Println("hello")
+}
+`), 0644))
+
+ rules := []Rule{
+ {ID: "test-001", Title: "Println", Severity: "low", Languages: []string{"go"}, Pattern: `fmt\.Println`, Fix: "log", Detection: "regex"},
+ }
+
+ s, err := NewScanner(rules)
+ require.NoError(t, err)
+
+ findings, err := s.ScanDir(dir)
+ require.NoError(t, err)
+ require.Len(t, findings, 1)
+ assert.Equal(t, "test-001", findings[0].RuleID)
+}
+
+func TestScanner_ScanDir_ExcludesVendor(t *testing.T) {
+ dir := t.TempDir()
+ vendor := filepath.Join(dir, "vendor")
+ require.NoError(t, os.MkdirAll(vendor, 0755))
+ require.NoError(t, os.WriteFile(filepath.Join(vendor, "lib.go"), []byte("package lib\nfunc x() { fmt.Println() }\n"), 0644))
+
+ rules := []Rule{
+ {ID: "test-001", Title: "Println", Severity: "low", Languages: []string{"go"}, Pattern: `fmt\.Println`, Fix: "log", Detection: "regex"},
+ }
+
+ s, err := NewScanner(rules)
+ require.NoError(t, err)
+
+ findings, err := s.ScanDir(dir)
+ require.NoError(t, err)
+ assert.Empty(t, findings)
+}
+
+func TestScanner_LanguageDetection(t *testing.T) {
+ assert.Equal(t, "go", DetectLanguage("main.go"))
+ assert.Equal(t, "php", DetectLanguage("app.php"))
+ assert.Equal(t, "ts", DetectLanguage("index.ts"))
+ assert.Equal(t, "ts", DetectLanguage("index.tsx"))
+ assert.Equal(t, "cpp", DetectLanguage("engine.cpp"))
+ assert.Equal(t, "cpp", DetectLanguage("engine.cc"))
+ assert.Equal(t, "", DetectLanguage("README.md"))
+}
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v -run TestScanner`
+Expected: FAIL — `NewScanner` not defined
+
+**Step 3: Write minimal implementation**
+
+```go
+package lint
+
+import (
+ "fmt"
+ "os"
+ "path/filepath"
+ "strings"
+)
+
+// defaultExcludes are directories skipped during scanning.
+var defaultExcludes = []string{"vendor", "node_modules", ".git", "testdata", ".core"}
+
+// extToLang maps file extensions to language identifiers.
+var extToLang = map[string]string{
+ ".go": "go",
+ ".php": "php",
+ ".ts": "ts",
+ ".tsx": "ts",
+ ".js": "js",
+ ".jsx": "js",
+ ".cpp": "cpp",
+ ".cc": "cpp",
+ ".cxx": "cpp",
+ ".c": "cpp",
+ ".h": "cpp",
+ ".hpp": "cpp",
+}
+
+// DetectLanguage returns the language identifier for a filename, or "" if unknown.
+func DetectLanguage(filename string) string {
+ ext := filepath.Ext(filename)
+ return extToLang[ext]
+}
+
+// Scanner walks directories and matches files against rules.
+type Scanner struct {
+ matcher *Matcher
+ rules []Rule
+ excludes []string
+}
+
+// NewScanner creates a Scanner from a set of rules.
+func NewScanner(rules []Rule) (*Scanner, error) {
+ m, err := NewMatcher(rules)
+ if err != nil {
+ return nil, err
+ }
+ return &Scanner{
+ matcher: m,
+ rules: rules,
+ excludes: defaultExcludes,
+ }, nil
+}
+
+// ScanDir walks a directory tree and returns all findings.
+func (s *Scanner) ScanDir(root string) ([]Finding, error) {
+ var all []Finding
+
+ err := filepath.WalkDir(root, func(path string, d os.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+
+ // Skip excluded directories
+ if d.IsDir() {
+ for _, ex := range s.excludes {
+ if d.Name() == ex {
+ return filepath.SkipDir
+ }
+ }
+ return nil
+ }
+
+ // Only scan files with known language extensions
+ lang := DetectLanguage(path)
+ if lang == "" {
+ return nil
+ }
+
+ content, err := os.ReadFile(path)
+ if err != nil {
+ return fmt.Errorf("read %s: %w", path, err)
+ }
+
+ // Make path relative to root for cleaner output
+ rel, err := filepath.Rel(root, path)
+ if err != nil {
+ rel = path
+ }
+
+ findings := s.matcher.Match(rel, content)
+ all = append(all, findings...)
+ return nil
+ })
+
+ return all, err
+}
+
+// ScanFile scans a single file and returns findings.
+func (s *Scanner) ScanFile(path string) ([]Finding, error) {
+ content, err := os.ReadFile(path)
+ if err != nil {
+ return nil, fmt.Errorf("read %s: %w", path, err)
+ }
+ return s.matcher.Match(path, content), nil
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v -run TestScanner`
+Expected: PASS (3 tests)
+
+**Step 5: Commit**
+
+```bash
+git add pkg/lint/scanner.go pkg/lint/scanner_test.go
+git commit -m "feat: add Scanner with directory walking and language detection"
+```
+
+---
+
+### Task 7: Seed the catalog YAML files
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/catalog/go-security.yaml` (expand from task 3)
+- Create: `/Users/snider/Code/core/lint/catalog/go-correctness.yaml`
+- Create: `/Users/snider/Code/core/lint/catalog/go-modernise.yaml`
+
+**Step 1: Write `catalog/go-security.yaml`**
+
+```yaml
+- id: go-sec-001
+ title: "SQL wildcard injection in LIKE clauses"
+ severity: high
+ languages: [go]
+ tags: [security, injection, owasp-a03]
+ pattern: 'LIKE\s+\?.*["%`]\s*\%.*\+'
+ exclude_pattern: 'EscapeLike'
+ fix: "Use parameterised LIKE with explicit escaping of % and _ characters"
+ found_in: [go-store]
+ example_bad: |
+ db.Where("name LIKE ?", "%"+input+"%")
+ example_good: |
+ db.Where("name LIKE ?", EscapeLike(input))
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-sec-002
+ title: "Path traversal in file/cache key operations"
+ severity: high
+ languages: [go]
+ tags: [security, path-traversal, owasp-a01]
+ pattern: 'filepath\.Join\(.*,\s*\w+\)'
+ exclude_pattern: 'filepath\.Clean|securejoin|ValidatePath'
+ fix: "Validate path components do not contain .. before joining"
+ found_in: [go-cache]
+ example_bad: |
+ path := filepath.Join(cacheDir, userInput)
+ example_good: |
+ if strings.Contains(key, "..") { return ErrInvalidKey }
+ path := filepath.Join(cacheDir, key)
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-sec-003
+ title: "XSS via unescaped HTML output"
+ severity: high
+ languages: [go]
+ tags: [security, xss, owasp-a03]
+ pattern: 'fmt\.Sprintf\(.*<.*>.*%s'
+ exclude_pattern: 'html\.EscapeString|template\.HTMLEscapeString'
+ fix: "Use html.EscapeString() for user-supplied values in HTML output"
+ found_in: [go-html]
+ example_bad: |
+ out := fmt.Sprintf("%s
", userInput)
+ example_good: |
+ out := fmt.Sprintf("%s
", html.EscapeString(userInput))
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-sec-004
+ title: "Non-constant-time comparison for authentication"
+ severity: high
+ languages: [go]
+ tags: [security, timing-attack, owasp-a02]
+ pattern: '==\s*\w*(token|key|secret|password|hash|digest|hmac|mac|sig)'
+ exclude_pattern: 'subtle\.ConstantTimeCompare|hmac\.Equal'
+ fix: "Use crypto/subtle.ConstantTimeCompare for security-sensitive comparisons"
+ found_in: [go-crypt]
+ example_bad: |
+ if providedToken == storedToken {
+ example_good: |
+ if subtle.ConstantTimeCompare([]byte(provided), []byte(stored)) == 1 {
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-sec-005
+ title: "Log injection via unescaped newlines"
+ severity: medium
+ languages: [go]
+ tags: [security, injection, logging]
+ pattern: 'log\.\w+\(.*\+.*\)'
+ exclude_pattern: 'strings\.ReplaceAll.*\\n|slog\.'
+ fix: "Use structured logging (slog) or sanitise newlines from user input"
+ found_in: [go-log]
+ example_bad: |
+ log.Printf("user login: " + username)
+ example_good: |
+ slog.Info("user login", "username", username)
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-sec-006
+ title: "Sensitive key material in log output"
+ severity: high
+ languages: [go]
+ tags: [security, secrets, logging]
+ pattern: 'log\.\w+\(.*(?i)(password|secret|token|apikey|private.?key|credential)'
+ exclude_pattern: 'REDACTED|\*\*\*|redact'
+ fix: "Redact sensitive fields before logging"
+ found_in: [go-log]
+ example_bad: |
+ log.Printf("config: token=%s", cfg.Token)
+ example_good: |
+ log.Printf("config: token=%s", redact(cfg.Token))
+ first_seen: "2026-03-09"
+ detection: regex
+```
+
+**Step 2: Write `catalog/go-correctness.yaml`**
+
+```yaml
+- id: go-cor-001
+ title: "Goroutine without WaitGroup or context"
+ severity: high
+ languages: [go]
+ tags: [correctness, goroutine-leak]
+ pattern: 'go\s+func\s*\('
+ exclude_pattern: 'wg\.|\.Go\(|context\.|done\s*<-|select\s*\{'
+ fix: "Use sync.WaitGroup.Go() or ensure goroutine has a shutdown signal"
+ found_in: [core/go]
+ example_bad: |
+ go func() { doWork() }()
+ example_good: |
+ wg.Go(func() { doWork() })
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-cor-002
+ title: "WaitGroup.Wait without context/timeout"
+ severity: high
+ languages: [go]
+ tags: [correctness, deadlock]
+ pattern: '\.Wait\(\)'
+ exclude_pattern: 'select\s*\{|ctx\.Done|context\.With|time\.After'
+ fix: "Wrap wg.Wait() in a select with context.Done() or timeout"
+ found_in: [core/go]
+ example_bad: |
+ wg.Wait() // blocks forever if goroutine hangs
+ example_good: |
+ done := make(chan struct{})
+ go func() { wg.Wait(); close(done) }()
+ select {
+ case <-done:
+ case <-ctx.Done():
+ }
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-cor-003
+ title: "Silent error swallowing"
+ severity: medium
+ languages: [go]
+ tags: [correctness, error-handling]
+ pattern: '^\s*_\s*=\s*\w+\.\w+\('
+ exclude_pattern: 'defer|Close\(|Flush\('
+ fix: "Handle or propagate errors instead of discarding with _"
+ found_in: [go-process, go-ratelimit]
+ example_bad: |
+ _ = db.Save(record)
+ example_good: |
+ if err := db.Save(record); err != nil {
+ return fmt.Errorf("save record: %w", err)
+ }
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-cor-004
+ title: "Panic in library code"
+ severity: medium
+ languages: [go]
+ tags: [correctness, panic]
+ pattern: '\bpanic\('
+ exclude_pattern: '_test\.go|// unreachable|Must\w+\('
+ fix: "Return errors instead of panicking in library code"
+ found_in: [go-i18n]
+ example_bad: |
+ func Parse(s string) *Node { panic("not implemented") }
+ example_good: |
+ func Parse(s string) (*Node, error) { return nil, fmt.Errorf("not implemented") }
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-cor-005
+ title: "File deletion without path validation"
+ severity: high
+ languages: [go]
+ tags: [correctness, safety]
+ pattern: 'os\.Remove(All)?\('
+ exclude_pattern: 'filepath\.Clean|ValidatePath|strings\.Contains.*\.\.'
+ fix: "Validate path does not escape base directory before deletion"
+ found_in: [go-io]
+ example_bad: |
+ os.RemoveAll(filepath.Join(base, userInput))
+ example_good: |
+ clean := filepath.Clean(filepath.Join(base, userInput))
+ if !strings.HasPrefix(clean, base) { return ErrPathTraversal }
+ os.RemoveAll(clean)
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-cor-006
+ title: "Missing error return from API/network calls"
+ severity: medium
+ languages: [go]
+ tags: [correctness, error-handling]
+ pattern: 'resp,\s*_\s*:=.*\.(Get|Post|Do|Send)\('
+ fix: "Check and handle HTTP/API errors"
+ found_in: [go-forge, go-git]
+ example_bad: |
+ resp, _ := client.Get(url)
+ example_good: |
+ resp, err := client.Get(url)
+ if err != nil { return fmt.Errorf("api call: %w", err) }
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-cor-007
+ title: "Signal handler uses wrong type"
+ severity: medium
+ languages: [go]
+ tags: [correctness, signals]
+ pattern: 'syscall\.Signal\b'
+ exclude_pattern: 'os\.Signal'
+ fix: "Use os.Signal for portable signal handling"
+ found_in: [go-process]
+ example_bad: |
+ func Handle(sig syscall.Signal) { ... }
+ example_good: |
+ func Handle(sig os.Signal) { ... }
+ first_seen: "2026-03-09"
+ detection: regex
+```
+
+**Step 3: Write `catalog/go-modernise.yaml`**
+
+```yaml
+- id: go-mod-001
+ title: "Manual slice clone via append([]T(nil)...)"
+ severity: low
+ languages: [go]
+ tags: [modernise, go126]
+ pattern: 'append\(\[\]\w+\(nil\),\s*\w+\.\.\.\)'
+ fix: "Use slices.Clone() from Go 1.21+"
+ found_in: [core/go]
+ example_bad: |
+ copy := append([]string(nil), original...)
+ example_good: |
+ copy := slices.Clone(original)
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-mod-002
+ title: "Manual sort of string/int slices"
+ severity: low
+ languages: [go]
+ tags: [modernise, go126]
+ pattern: 'sort\.Strings\(|sort\.Ints\(|sort\.Slice\('
+ exclude_pattern: 'sort\.SliceStable'
+ fix: "Use slices.Sort() or slices.Sorted(iter) from Go 1.21+"
+ found_in: [core/go]
+ example_bad: |
+ sort.Strings(names)
+ example_good: |
+ slices.Sort(names)
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-mod-003
+ title: "Manual reverse iteration loop"
+ severity: low
+ languages: [go]
+ tags: [modernise, go126]
+ pattern: 'for\s+\w+\s*:=\s*len\(\w+\)\s*-\s*1'
+ fix: "Use slices.Backward() from Go 1.23+"
+ found_in: [core/go]
+ example_bad: |
+ for i := len(items) - 1; i >= 0; i-- { use(items[i]) }
+ example_good: |
+ for _, item := range slices.Backward(items) { use(item) }
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-mod-004
+ title: "WaitGroup Add+Done instead of Go()"
+ severity: low
+ languages: [go]
+ tags: [modernise, go126]
+ pattern: 'wg\.Add\(1\)'
+ fix: "Use sync.WaitGroup.Go() from Go 1.26"
+ found_in: [core/go]
+ example_bad: |
+ wg.Add(1)
+ go func() { defer wg.Done(); work() }()
+ example_good: |
+ wg.Go(func() { work() })
+ first_seen: "2026-03-09"
+ detection: regex
+
+- id: go-mod-005
+ title: "Manual map key collection"
+ severity: low
+ languages: [go]
+ tags: [modernise, go126]
+ pattern: 'for\s+\w+\s*:=\s*range\s+\w+\s*\{\s*\n\s*\w+\s*=\s*append'
+ exclude_pattern: 'maps\.Keys'
+ fix: "Use maps.Keys() or slices.Sorted(maps.Keys()) from Go 1.23+"
+ found_in: [core/go]
+ example_bad: |
+ var keys []string
+ for k := range m { keys = append(keys, k) }
+ example_good: |
+ keys := slices.Sorted(maps.Keys(m))
+ first_seen: "2026-03-09"
+ detection: regex
+```
+
+**Step 4: Run all tests to verify catalog loads correctly**
+
+Run: `cd ~/Code/core/lint && go test ./pkg/lint/ -v`
+Expected: PASS (all tests, including TestCatalog_LoadDir which reads the catalog/ dir)
+
+**Step 5: Commit**
+
+```bash
+git add catalog/
+git commit -m "feat: seed catalog with 18 patterns from ecosystem sweep"
+```
+
+---
+
+### Task 8: CLI binary with `cli.Main()`
+
+**Files:**
+- Create: `/Users/snider/Code/core/lint/cmd/core-lint/main.go`
+- Create: `/Users/snider/Code/core/lint/lint.go` (embed catalog + public API)
+
+**Step 1: Create the embed entry point**
+
+Create `/Users/snider/Code/core/lint/lint.go`:
+
+```go
+package lint
+
+import (
+ "embed"
+
+ lintpkg "forge.lthn.ai/core/lint/pkg/lint"
+)
+
+//go:embed catalog/*.yaml
+var catalogFS embed.FS
+
+// LoadEmbeddedCatalog loads the built-in catalog from embedded YAML files.
+func LoadEmbeddedCatalog() (*lintpkg.Catalog, error) {
+ return lintpkg.LoadFS(catalogFS, "catalog")
+}
+```
+
+**Step 2: Create the CLI entry point**
+
+Create `/Users/snider/Code/core/lint/cmd/core-lint/main.go`:
+
+```go
+package main
+
+import (
+ "fmt"
+ "os"
+
+ "forge.lthn.ai/core/cli/pkg/cli"
+ lint "forge.lthn.ai/core/lint"
+ lintpkg "forge.lthn.ai/core/lint/pkg/lint"
+)
+
+func main() {
+ cli.Main(
+ cli.WithCommands("lint", addLintCommands),
+ )
+}
+
+func addLintCommands(root *cli.Command) {
+ lintCmd := &cli.Command{
+ Use: "lint",
+ Short: "Pattern-based code checker",
+ }
+ root.AddCommand(lintCmd)
+
+ // core-lint lint check [path...]
+ lintCmd.AddCommand(cli.NewCommand(
+ "check [path...]",
+ "Run pattern checks against source files",
+ "Scans files for known anti-patterns from the catalog",
+ func(cmd *cli.Command, args []string) error {
+ format, _ := cmd.Flags().GetString("format")
+ lang, _ := cmd.Flags().GetString("lang")
+ severity, _ := cmd.Flags().GetString("severity")
+
+ cat, err := lint.LoadEmbeddedCatalog()
+ if err != nil {
+ return fmt.Errorf("load catalog: %w", err)
+ }
+
+ rules := cat.Rules
+ if lang != "" {
+ rules = cat.ForLanguage(lang)
+ }
+ if severity != "" {
+ filtered := (&lintpkg.Catalog{Rules: rules}).AtSeverity(severity)
+ rules = filtered
+ }
+
+ scanner, err := lintpkg.NewScanner(rules)
+ if err != nil {
+ return fmt.Errorf("create scanner: %w", err)
+ }
+
+ paths := args
+ if len(paths) == 0 {
+ paths = []string{"."}
+ }
+
+ var allFindings []lintpkg.Finding
+ for _, p := range paths {
+ findings, err := scanner.ScanDir(p)
+ if err != nil {
+ return fmt.Errorf("scan %s: %w", p, err)
+ }
+ allFindings = append(allFindings, findings...)
+ }
+
+ switch format {
+ case "json":
+ return lintpkg.WriteJSON(os.Stdout, allFindings)
+ case "jsonl":
+ return lintpkg.WriteJSONL(os.Stdout, allFindings)
+ default:
+ lintpkg.WriteText(os.Stdout, allFindings)
+ }
+
+ if len(allFindings) > 0 {
+ s := lintpkg.Summarise(allFindings)
+ fmt.Fprintf(os.Stderr, "\n%d findings", s.Total)
+ for sev, count := range s.BySeverity {
+ fmt.Fprintf(os.Stderr, " | %s: %d", sev, count)
+ }
+ fmt.Fprintln(os.Stderr)
+ }
+ return nil
+ },
+ ))
+
+ // Add flags to check command
+ checkCmd := lintCmd.Commands()[0]
+ checkCmd.Flags().StringP("format", "f", "text", "Output format: text, json, jsonl")
+ checkCmd.Flags().StringP("lang", "l", "", "Filter by language: go, php, ts, cpp")
+ checkCmd.Flags().StringP("severity", "s", "", "Minimum severity: critical, high, medium, low, info")
+
+ // core-lint lint catalog
+ catalogCmd := &cli.Command{
+ Use: "catalog",
+ Short: "Browse the pattern catalog",
+ }
+ lintCmd.AddCommand(catalogCmd)
+
+ // core-lint lint catalog list
+ catalogCmd.AddCommand(cli.NewCommand(
+ "list",
+ "List available rules",
+ "",
+ func(cmd *cli.Command, args []string) error {
+ lang, _ := cmd.Flags().GetString("lang")
+
+ cat, err := lint.LoadEmbeddedCatalog()
+ if err != nil {
+ return err
+ }
+
+ rules := cat.Rules
+ if lang != "" {
+ rules = cat.ForLanguage(lang)
+ }
+
+ for _, r := range rules {
+ fmt.Printf("%-12s [%s] %s\n", r.ID, r.Severity, r.Title)
+ }
+ fmt.Fprintf(os.Stderr, "\n%d rules\n", len(rules))
+ return nil
+ },
+ ))
+ catalogCmd.Commands()[0].Flags().StringP("lang", "l", "", "Filter by language")
+
+ // core-lint lint catalog show
+ catalogCmd.AddCommand(cli.NewCommand(
+ "show [rule-id]",
+ "Show details for a specific rule",
+ "",
+ func(cmd *cli.Command, args []string) error {
+ if len(args) == 0 {
+ return fmt.Errorf("rule ID required")
+ }
+ cat, err := lint.LoadEmbeddedCatalog()
+ if err != nil {
+ return err
+ }
+ r := cat.ByID(args[0])
+ if r == nil {
+ return fmt.Errorf("rule %s not found", args[0])
+ }
+ fmt.Printf("ID: %s\n", r.ID)
+ fmt.Printf("Title: %s\n", r.Title)
+ fmt.Printf("Severity: %s\n", r.Severity)
+ fmt.Printf("Languages: %v\n", r.Languages)
+ fmt.Printf("Tags: %v\n", r.Tags)
+ fmt.Printf("Pattern: %s\n", r.Pattern)
+ if r.ExcludePattern != "" {
+ fmt.Printf("Exclude: %s\n", r.ExcludePattern)
+ }
+ fmt.Printf("Fix: %s\n", r.Fix)
+ if r.ExampleBad != "" {
+ fmt.Printf("\nBad:\n%s\n", r.ExampleBad)
+ }
+ if r.ExampleGood != "" {
+ fmt.Printf("Good:\n%s\n", r.ExampleGood)
+ }
+ return nil
+ },
+ ))
+}
+```
+
+**Step 3: Add cli dependency**
+
+```bash
+cd ~/Code/core/lint
+go get forge.lthn.ai/core/cli
+go mod tidy
+```
+
+**Step 4: Build and smoke test**
+
+```bash
+cd ~/Code/core/lint
+go build -o ./bin/core-lint ./cmd/core-lint
+./bin/core-lint lint catalog list
+./bin/core-lint lint catalog show go-sec-001
+./bin/core-lint lint check --lang go --format json ~/Code/host-uk/core/pkg/core/
+```
+
+Expected: Binary builds, catalog lists 18 rules, show displays rule details, check scans files.
+
+**Step 5: Commit**
+
+```bash
+git add lint.go cmd/core-lint/main.go go.mod go.sum
+git commit -m "feat: add core-lint CLI with check, catalog list, catalog show"
+```
+
+---
+
+### Task 9: Run all tests, push to forge
+
+**Step 1: Run full test suite**
+
+```bash
+cd ~/Code/core/lint
+go test -race -count=1 ./...
+```
+
+Expected: PASS with race detector
+
+**Step 2: Run go vet**
+
+```bash
+go vet ./...
+```
+
+Expected: No issues
+
+**Step 3: Build binary**
+
+```bash
+go build -trimpath -o ./bin/core-lint ./cmd/core-lint
+```
+
+**Step 4: Smoke test against a real repo**
+
+```bash
+./bin/core-lint lint check --lang go ~/Code/host-uk/core/pkg/core/
+./bin/core-lint lint check --lang go --severity high ~/Code/core/go-io/
+```
+
+Expected: Any findings are displayed (or no findings if the repos are already clean from our sweep)
+
+**Step 5: Update go.work**
+
+```bash
+# Add ./core/lint to ~/Code/go.work if not already there
+cd ~/Code && go work sync
+```
+
+**Step 6: Push to forge**
+
+```bash
+cd ~/Code/core/lint
+git push -u origin main
+```
+
+**Step 7: Tag initial release**
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
diff --git a/.core/reference/docs/plans/2026-03-12-altum-update-checker-design.md b/.core/reference/docs/plans/2026-03-12-altum-update-checker-design.md
new file mode 100644
index 0000000..a0bbe0d
--- /dev/null
+++ b/.core/reference/docs/plans/2026-03-12-altum-update-checker-design.md
@@ -0,0 +1,160 @@
+# AltumCode Update Checker — Design
+
+> **Note:** Layer 1 (version detection via PHP artisan) is implemented and documented at `docs/docs/php/packages/uptelligence.md`. Layer 2 (browser-automated downloads via Claude Code skill) is NOT yet implemented.
+
+## Problem
+
+Host UK runs 4 AltumCode SaaS products and 13 plugins across two marketplaces (CodeCanyon + LemonSqueezy). Checking for updates and downloading them is a manual process: ~50 clicks across two marketplace UIs, moving 16+ zip files, extracting to the right directories. This eats a morning of momentum every update cycle.
+
+## Solution
+
+Two-layer system: lightweight version detection (PHP artisan command) + browser-automated download (Claude Code skill).
+
+## Architecture
+
+```
+Layer 1: Detection (core/php-uptelligence)
+ artisan uptelligence:check-updates
+ 5 HTTP GETs, no auth, schedulable
+ Compares remote vs deployed versions
+
+Layer 2: Download (Claude Code skill)
+ Playwright → LemonSqueezy (16 items)
+ Claude in Chrome → CodeCanyon (2 items)
+ Downloads zips to staging folder
+ Extracts to saas/services/{product}/package/
+
+Layer 3: Deploy (existing — manual)
+ docker build → scp → deploy_saas.yml
+ Human in the loop
+```
+
+## Layer 1: Version Detection
+
+### Public Endpoints (no auth required)
+
+| Endpoint | Returns |
+|----------|---------|
+| `GET https://66analytics.com/info.php` | `{"latest_release_version": "66.0.0", "latest_release_version_code": 6600}` |
+| `GET https://66biolinks.com/info.php` | Same format |
+| `GET https://66pusher.com/info.php` | Same format |
+| `GET https://66socialproof.com/info.php` | Same format |
+| `GET https://dev.altumcode.com/plugins-versions` | `{"affiliate": {"version": "2.0.1"}, "ultimate-blocks": {"version": "9.1.0"}, ...}` |
+
+### Deployed Version Sources
+
+- **Product version**: `PRODUCT_CODE` constant in deployed source `config.php`
+- **Plugin versions**: `version` field in each plugin's `config.php` or `config.json`
+
+### Artisan Command
+
+`php artisan uptelligence:check-updates`
+
+Output:
+```
+Product Deployed Latest Status
+──────────────────────────────────────────────
+66analytics 65.0.0 66.0.0 UPDATE AVAILABLE
+66biolinks 65.0.0 66.0.0 UPDATE AVAILABLE
+66pusher 65.0.0 65.0.0 ✓ current
+66socialproof 65.0.0 66.0.0 UPDATE AVAILABLE
+
+Plugin Deployed Latest Status
+──────────────────────────────────────────────
+affiliate 2.0.0 2.0.1 UPDATE AVAILABLE
+ultimate-blocks 9.1.0 9.1.0 ✓ current
+...
+```
+
+Lives in `core/php-uptelligence` as a scheduled check or on-demand command.
+
+## Layer 2: Browser-Automated Download
+
+### Claude Code Skill: `/update-altum`
+
+Workflow:
+1. Run version check (Layer 1) — show what needs updating
+2. Ask for confirmation before downloading
+3. Download from both marketplaces
+4. Extract to staging directories
+5. Report what changed
+
+### Marketplace Access
+
+**LemonSqueezy (Playwright)**
+- Auth: Magic link email to `snider@lt.hn` — user taps on phone
+- Flow per item: Navigate to order detail → click "Download" button
+- 16 items across 2 pages of orders
+- Session persists for the skill invocation
+
+**CodeCanyon (Claude in Chrome)**
+- Auth: Saved browser session cookies (user `snidered`)
+- Flow per item: Click "Download" dropdown → "All files & documentation"
+- 2 items on downloads page
+
+### Product-to-Marketplace Mapping
+
+| Product | CodeCanyon | LemonSqueezy |
+|---------|-----------|--------------|
+| 66biolinks | Regular licence | Extended licence (66biolinks custom, $359.28) |
+| 66socialproof | Regular licence | — |
+| 66analytics | — | Regular licence |
+| 66pusher | — | Regular licence |
+
+### Plugin Inventory (all LemonSqueezy)
+
+| Plugin | Price | Applies To |
+|--------|-------|------------|
+| Pro Notifications | $58.80 | 66socialproof |
+| Teams Plugin | $58.80 | All products |
+| Push Notifications Plugin | $46.80 | All products |
+| Ultimate Blocks | $32.40 | 66biolinks |
+| Pro Blocks | $32.40 | 66biolinks |
+| Payment Blocks | $32.40 | 66biolinks |
+| Affiliate Plugin | $32.40 | All products |
+| PWA Plugin | $25.20 | All products |
+| Image Optimizer Plugin | $19.20 | All products |
+| Email Shield Plugin | FREE | All products |
+| Dynamic OG images plugin | FREE | 66biolinks |
+| Offload & CDN Plugin | FREE | All products (gift from Altum) |
+
+### Staging & Extraction
+
+- Download to: `~/Code/lthn/saas/updates/YYYY-MM-DD/`
+- Products extract to: `~/Code/lthn/saas/services/{product}/package/product/`
+- Plugins extract to: `~/Code/lthn/saas/services/{product}/package/product/plugins/{plugin_id}/`
+
+## LemonSqueezy Order UUIDs
+
+Stable order URLs for direct navigation:
+
+| Product | Order URL |
+|---------|-----------|
+| 66analytics | `/my-orders/2972471f-abac-4165-b78d-541b176de180` |
+
+(Remaining UUIDs to be captured on first full run of the skill.)
+
+## Out of Scope
+
+- No auto-deploy to production (human runs `deploy_saas.yml`)
+- No licence key handling or financial transactions
+- No AltumCode Club membership management
+- No Blesta updates (different vendor)
+- No update SQL migration execution (handled by AltumCode's own update scripts)
+
+## Key Technical Details
+
+- AltumCode products use Unirest HTTP client for API calls
+- Product `info.php` endpoints are public, no rate limiting observed
+- Plugin versions endpoint (`dev.altumcode.com`) is also public
+- Production Docker images have `/install/` and `/update/` directories stripped
+- Updates require full Docker image rebuild and redeployment via Ansible
+- CodeCanyon download URLs contain stable purchase UUIDs
+- LemonSqueezy uses magic link auth (no password, email-based)
+- Playwright can access LemonSqueezy; Claude in Chrome cannot (payment platform safety block)
+
+## Workflow Summary
+
+**Before**: Get email from AltumCode → log into 2 marketplaces → click through 18 products/plugins → download 16+ zips → extract to right directories → rebuild Docker images → deploy. Half a morning.
+
+**After**: Run `artisan uptelligence:check-updates` → see what's behind → invoke `/update-altum` → tap magic link on phone → go make coffee → come back to staged files → `deploy_saas.yml`. 10 minutes of human time.
diff --git a/.core/reference/docs/plans/2026-03-12-altum-update-checker-plan.md b/.core/reference/docs/plans/2026-03-12-altum-update-checker-plan.md
new file mode 100644
index 0000000..37ecb28
--- /dev/null
+++ b/.core/reference/docs/plans/2026-03-12-altum-update-checker-plan.md
@@ -0,0 +1,799 @@
+# AltumCode Update Checker Implementation Plan
+
+> **Note:** Layer 1 (Tasks 1-2, 4: version checking + seeder + sync command) is implemented and documented at `docs/docs/php/packages/uptelligence.md`. Task 3 (Claude Code browser skill for Layer 2 downloads) is NOT yet implemented.
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Add AltumCode product + plugin version checking to uptelligence, and create a Claude Code skill for browser-automated downloads from LemonSqueezy and CodeCanyon.
+
+**Architecture:** Extend the existing `VendorUpdateCheckerService` to handle `PLATFORM_ALTUM` vendors via 5 public HTTP endpoints. Seed the vendors table with all 4 products and 13 plugins. Create a Claude Code plugin skill that uses Playwright (LemonSqueezy) and Chrome (CodeCanyon) to download updates.
+
+**Tech Stack:** PHP 8.4, Laravel, Pest, Claude Code plugins (Playwright MCP + Chrome MCP)
+
+---
+
+### Task 1: Add AltumCode check to VendorUpdateCheckerService
+
+**Files:**
+- Modify: `/Users/snider/Code/core/php-uptelligence/Services/VendorUpdateCheckerService.php`
+- Test: `/Users/snider/Code/core/php-uptelligence/tests/Unit/AltumCodeCheckerTest.php`
+
+**Step 1: Write the failing test**
+
+Create `/Users/snider/Code/core/php-uptelligence/tests/Unit/AltumCodeCheckerTest.php`:
+
+```php
+service = app(VendorUpdateCheckerService::class);
+});
+
+it('checks altum product version via info.php', function () {
+ Http::fake([
+ 'https://66analytics.com/info.php' => Http::response([
+ 'latest_release_version' => '66.0.0',
+ 'latest_release_version_code' => 6600,
+ ]),
+ ]);
+
+ $vendor = Vendor::factory()->create([
+ 'slug' => '66analytics',
+ 'name' => '66analytics',
+ 'source_type' => Vendor::SOURCE_LICENSED,
+ 'plugin_platform' => Vendor::PLATFORM_ALTUM,
+ 'current_version' => '65.0.0',
+ 'is_active' => true,
+ ]);
+
+ $result = $this->service->checkVendor($vendor);
+
+ expect($result['status'])->toBe('success')
+ ->and($result['current'])->toBe('65.0.0')
+ ->and($result['latest'])->toBe('66.0.0')
+ ->and($result['has_update'])->toBeTrue();
+});
+
+it('reports no update when altum product is current', function () {
+ Http::fake([
+ 'https://66analytics.com/info.php' => Http::response([
+ 'latest_release_version' => '65.0.0',
+ 'latest_release_version_code' => 6500,
+ ]),
+ ]);
+
+ $vendor = Vendor::factory()->create([
+ 'slug' => '66analytics',
+ 'name' => '66analytics',
+ 'source_type' => Vendor::SOURCE_LICENSED,
+ 'plugin_platform' => Vendor::PLATFORM_ALTUM,
+ 'current_version' => '65.0.0',
+ 'is_active' => true,
+ ]);
+
+ $result = $this->service->checkVendor($vendor);
+
+ expect($result['has_update'])->toBeFalse();
+});
+
+it('checks altum plugin versions via plugins-versions endpoint', function () {
+ Http::fake([
+ 'https://dev.altumcode.com/plugins-versions' => Http::response([
+ 'affiliate' => ['version' => '2.0.1'],
+ 'teams' => ['version' => '3.0.0'],
+ ]),
+ ]);
+
+ $vendor = Vendor::factory()->create([
+ 'slug' => 'altum-plugin-affiliate',
+ 'name' => 'Affiliate Plugin',
+ 'source_type' => Vendor::SOURCE_PLUGIN,
+ 'plugin_platform' => Vendor::PLATFORM_ALTUM,
+ 'current_version' => '2.0.0',
+ 'is_active' => true,
+ ]);
+
+ $result = $this->service->checkVendor($vendor);
+
+ expect($result['status'])->toBe('success')
+ ->and($result['latest'])->toBe('2.0.1')
+ ->and($result['has_update'])->toBeTrue();
+});
+
+it('handles altum info.php timeout gracefully', function () {
+ Http::fake([
+ 'https://66analytics.com/info.php' => Http::response('', 500),
+ ]);
+
+ $vendor = Vendor::factory()->create([
+ 'slug' => '66analytics',
+ 'name' => '66analytics',
+ 'source_type' => Vendor::SOURCE_LICENSED,
+ 'plugin_platform' => Vendor::PLATFORM_ALTUM,
+ 'current_version' => '65.0.0',
+ 'is_active' => true,
+ ]);
+
+ $result = $this->service->checkVendor($vendor);
+
+ expect($result['status'])->toBe('error')
+ ->and($result['has_update'])->toBeFalse();
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd /Users/snider/Code/core/php-uptelligence && composer test -- --filter=AltumCodeChecker`
+Expected: FAIL — altum vendors still hit `skipCheck()`
+
+**Step 3: Write minimal implementation**
+
+In `/Users/snider/Code/core/php-uptelligence/Services/VendorUpdateCheckerService.php`, modify `checkVendor()` to route altum vendors:
+
+```php
+public function checkVendor(Vendor $vendor): array
+{
+ $result = match (true) {
+ $this->isAltumPlatform($vendor) && $vendor->isLicensed() => $this->checkAltumProduct($vendor),
+ $this->isAltumPlatform($vendor) && $vendor->isPlugin() => $this->checkAltumPlugin($vendor),
+ $vendor->isOss() && $this->isGitHubUrl($vendor->git_repo_url) => $this->checkGitHub($vendor),
+ $vendor->isOss() && $this->isGiteaUrl($vendor->git_repo_url) => $this->checkGitea($vendor),
+ default => $this->skipCheck($vendor),
+ };
+
+ // ... rest unchanged
+}
+```
+
+Add the three new methods:
+
+```php
+/**
+ * Check if vendor is on the AltumCode platform.
+ */
+protected function isAltumPlatform(Vendor $vendor): bool
+{
+ return $vendor->plugin_platform === Vendor::PLATFORM_ALTUM;
+}
+
+/**
+ * AltumCode product info endpoint mapping.
+ */
+protected function getAltumProductInfoUrl(Vendor $vendor): ?string
+{
+ $urls = [
+ '66analytics' => 'https://66analytics.com/info.php',
+ '66biolinks' => 'https://66biolinks.com/info.php',
+ '66pusher' => 'https://66pusher.com/info.php',
+ '66socialproof' => 'https://66socialproof.com/info.php',
+ ];
+
+ return $urls[$vendor->slug] ?? null;
+}
+
+/**
+ * Check an AltumCode product for updates via its info.php endpoint.
+ */
+protected function checkAltumProduct(Vendor $vendor): array
+{
+ $url = $this->getAltumProductInfoUrl($vendor);
+ if (! $url) {
+ return $this->errorResult("No info.php URL mapped for {$vendor->slug}");
+ }
+
+ try {
+ $response = Http::timeout(5)->get($url);
+
+ if (! $response->successful()) {
+ return $this->errorResult("AltumCode info.php returned {$response->status()}");
+ }
+
+ $data = $response->json();
+ $latestVersion = $data['latest_release_version'] ?? null;
+
+ if (! $latestVersion) {
+ return $this->errorResult('No version in info.php response');
+ }
+
+ return $this->buildResult(
+ vendor: $vendor,
+ latestVersion: $this->normaliseVersion($latestVersion),
+ releaseInfo: [
+ 'version_code' => $data['latest_release_version_code'] ?? null,
+ 'source' => $url,
+ ]
+ );
+ } catch (\Exception $e) {
+ return $this->errorResult("AltumCode check failed: {$e->getMessage()}");
+ }
+}
+
+/**
+ * Check an AltumCode plugin for updates via the central plugins-versions endpoint.
+ */
+protected function checkAltumPlugin(Vendor $vendor): array
+{
+ try {
+ $allPlugins = $this->getAltumPluginVersions();
+
+ if ($allPlugins === null) {
+ return $this->errorResult('Failed to fetch AltumCode plugin versions');
+ }
+
+ // Extract the plugin_id from the vendor slug (strip 'altum-plugin-' prefix)
+ $pluginId = str_replace('altum-plugin-', '', $vendor->slug);
+
+ if (! isset($allPlugins[$pluginId])) {
+ return $this->errorResult("Plugin '{$pluginId}' not found in AltumCode registry");
+ }
+
+ $latestVersion = $allPlugins[$pluginId]['version'] ?? null;
+
+ return $this->buildResult(
+ vendor: $vendor,
+ latestVersion: $this->normaliseVersion($latestVersion),
+ releaseInfo: ['source' => 'dev.altumcode.com/plugins-versions']
+ );
+ } catch (\Exception $e) {
+ return $this->errorResult("AltumCode plugin check failed: {$e->getMessage()}");
+ }
+}
+
+/**
+ * Fetch all AltumCode plugin versions (cached for 1 hour within a check run).
+ */
+protected ?array $altumPluginVersionsCache = null;
+
+protected function getAltumPluginVersions(): ?array
+{
+ if ($this->altumPluginVersionsCache !== null) {
+ return $this->altumPluginVersionsCache;
+ }
+
+ $response = Http::timeout(5)->get('https://dev.altumcode.com/plugins-versions');
+
+ if (! $response->successful()) {
+ return null;
+ }
+
+ $this->altumPluginVersionsCache = $response->json();
+
+ return $this->altumPluginVersionsCache;
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd /Users/snider/Code/core/php-uptelligence && composer test -- --filter=AltumCodeChecker`
+Expected: PASS (4 tests)
+
+**Step 5: Commit**
+
+```bash
+cd /Users/snider/Code/core/php-uptelligence
+git add Services/VendorUpdateCheckerService.php tests/Unit/AltumCodeCheckerTest.php
+git commit -m "feat: add AltumCode product + plugin version checking
+
+Extends VendorUpdateCheckerService to check AltumCode products via
+their info.php endpoints and plugins via dev.altumcode.com/plugins-versions.
+No auth required — all endpoints are public.
+
+Co-Authored-By: Virgil "
+```
+
+---
+
+### Task 2: Seed AltumCode vendors
+
+**Files:**
+- Create: `/Users/snider/Code/core/php-uptelligence/database/seeders/AltumCodeVendorSeeder.php`
+- Test: `/Users/snider/Code/core/php-uptelligence/tests/Unit/AltumCodeVendorSeederTest.php`
+
+**Step 1: Write the failing test**
+
+Create `/Users/snider/Code/core/php-uptelligence/tests/Unit/AltumCodeVendorSeederTest.php`:
+
+```php
+artisan('db:seed', ['--class' => 'Core\\Mod\\Uptelligence\\Database\\Seeders\\AltumCodeVendorSeeder']);
+
+ expect(Vendor::where('source_type', Vendor::SOURCE_LICENSED)
+ ->where('plugin_platform', Vendor::PLATFORM_ALTUM)
+ ->count()
+ )->toBe(4);
+});
+
+it('seeds 13 altum plugins', function () {
+ $this->artisan('db:seed', ['--class' => 'Core\\Mod\\Uptelligence\\Database\\Seeders\\AltumCodeVendorSeeder']);
+
+ expect(Vendor::where('source_type', Vendor::SOURCE_PLUGIN)
+ ->where('plugin_platform', Vendor::PLATFORM_ALTUM)
+ ->count()
+ )->toBe(13);
+});
+
+it('is idempotent', function () {
+ $this->artisan('db:seed', ['--class' => 'Core\\Mod\\Uptelligence\\Database\\Seeders\\AltumCodeVendorSeeder']);
+ $this->artisan('db:seed', ['--class' => 'Core\\Mod\\Uptelligence\\Database\\Seeders\\AltumCodeVendorSeeder']);
+
+ expect(Vendor::where('plugin_platform', Vendor::PLATFORM_ALTUM)->count())->toBe(17);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd /Users/snider/Code/core/php-uptelligence && composer test -- --filter=AltumCodeVendorSeeder`
+Expected: FAIL — seeder class not found
+
+**Step 3: Write minimal implementation**
+
+Create `/Users/snider/Code/core/php-uptelligence/database/seeders/AltumCodeVendorSeeder.php`:
+
+```php
+ '66analytics', 'name' => '66analytics', 'vendor_name' => 'AltumCode', 'current_version' => '65.0.0'],
+ ['slug' => '66biolinks', 'name' => '66biolinks', 'vendor_name' => 'AltumCode', 'current_version' => '65.0.0'],
+ ['slug' => '66pusher', 'name' => '66pusher', 'vendor_name' => 'AltumCode', 'current_version' => '65.0.0'],
+ ['slug' => '66socialproof', 'name' => '66socialproof', 'vendor_name' => 'AltumCode', 'current_version' => '65.0.0'],
+ ];
+
+ foreach ($products as $product) {
+ Vendor::updateOrCreate(
+ ['slug' => $product['slug']],
+ [
+ ...$product,
+ 'source_type' => Vendor::SOURCE_LICENSED,
+ 'plugin_platform' => Vendor::PLATFORM_ALTUM,
+ 'is_active' => true,
+ ]
+ );
+ }
+
+ $plugins = [
+ ['slug' => 'altum-plugin-affiliate', 'name' => 'Affiliate Plugin', 'current_version' => '2.0.0'],
+ ['slug' => 'altum-plugin-push-notifications', 'name' => 'Push Notifications Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-teams', 'name' => 'Teams Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-pwa', 'name' => 'PWA Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-image-optimizer', 'name' => 'Image Optimizer Plugin', 'current_version' => '3.1.0'],
+ ['slug' => 'altum-plugin-email-shield', 'name' => 'Email Shield Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-dynamic-og-images', 'name' => 'Dynamic OG Images Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-offload', 'name' => 'Offload & CDN Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-payment-blocks', 'name' => 'Payment Blocks Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-ultimate-blocks', 'name' => 'Ultimate Blocks Plugin', 'current_version' => '9.1.0'],
+ ['slug' => 'altum-plugin-pro-blocks', 'name' => 'Pro Blocks Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-pro-notifications', 'name' => 'Pro Notifications Plugin', 'current_version' => '1.0.0'],
+ ['slug' => 'altum-plugin-aix', 'name' => 'AIX Plugin', 'current_version' => '1.0.0'],
+ ];
+
+ foreach ($plugins as $plugin) {
+ Vendor::updateOrCreate(
+ ['slug' => $plugin['slug']],
+ [
+ ...$plugin,
+ 'vendor_name' => 'AltumCode',
+ 'source_type' => Vendor::SOURCE_PLUGIN,
+ 'plugin_platform' => Vendor::PLATFORM_ALTUM,
+ 'is_active' => true,
+ ]
+ );
+ }
+ }
+}
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd /Users/snider/Code/core/php-uptelligence && composer test -- --filter=AltumCodeVendorSeeder`
+Expected: PASS (3 tests)
+
+**Step 5: Commit**
+
+```bash
+cd /Users/snider/Code/core/php-uptelligence
+git add database/seeders/AltumCodeVendorSeeder.php tests/Unit/AltumCodeVendorSeederTest.php
+git commit -m "feat: seed AltumCode vendors — 4 products + 13 plugins
+
+Idempotent seeder using updateOrCreate. Products are SOURCE_LICENSED,
+plugins are SOURCE_PLUGIN, all PLATFORM_ALTUM. Version numbers will
+need updating to match actual deployed versions.
+
+Co-Authored-By: Virgil "
+```
+
+---
+
+### Task 3: Create Claude Code plugin skill for downloads
+
+**Files:**
+- Create: `/Users/snider/.claude/plugins/altum-updater/plugin.json`
+- Create: `/Users/snider/.claude/plugins/altum-updater/skills/update-altum.md`
+
+**Step 1: Create plugin manifest**
+
+Create `/Users/snider/.claude/plugins/altum-updater/plugin.json`:
+
+```json
+{
+ "name": "altum-updater",
+ "description": "Download AltumCode product and plugin updates from LemonSqueezy and CodeCanyon",
+ "version": "0.1.0",
+ "skills": [
+ {
+ "name": "update-altum",
+ "path": "skills/update-altum.md",
+ "description": "Download AltumCode product and plugin updates from marketplaces. Use when the user mentions updating AltumCode products, downloading from LemonSqueezy or CodeCanyon, or running the update checker."
+ }
+ ]
+}
+```
+
+**Step 2: Create skill file**
+
+Create `/Users/snider/.claude/plugins/altum-updater/skills/update-altum.md`:
+
+```markdown
+---
+name: update-altum
+description: Download AltumCode product and plugin updates from LemonSqueezy and CodeCanyon
+---
+
+# AltumCode Update Downloader
+
+## Overview
+
+Downloads updated AltumCode products and plugins from two marketplaces:
+- **LemonSqueezy** (Playwright): 66analytics, 66pusher, 66biolinks (extended), 13 plugins
+- **CodeCanyon** (Claude in Chrome): 66biolinks (regular), 66socialproof
+
+## Pre-flight
+
+1. Run `php artisan uptelligence:check-updates --vendor=66analytics` (or check all) to see what needs updating
+2. Show the user the version comparison table
+3. Ask which products/plugins to download
+
+## LemonSqueezy Download Flow (Playwright)
+
+LemonSqueezy uses magic link auth. The user will need to tap the link on their phone.
+
+1. Navigate to `https://app.lemonsqueezy.com/my-orders`
+2. If on login page, fill email `snider@lt.hn` and click Sign In
+3. Tell user: "Magic link sent — tap the link on your phone"
+4. Wait for redirect to orders page
+5. For each product/plugin that needs updating:
+ a. Click the product link on the orders page (paginated — 10 per page, 2 pages)
+ b. In the order detail, find the "Download" button under "Files"
+ c. Click Download — file saves to default downloads folder
+6. Move downloaded zips to staging: `~/Code/lthn/saas/updates/YYYY-MM-DD/`
+
+### LemonSqueezy Product Names (as shown on orders page)
+
+| Our Name | LemonSqueezy Order Name |
+|----------|------------------------|
+| 66analytics | "66analytics - Regular License" |
+| 66pusher | "66pusher - Regular License" |
+| 66biolinks (extended) | "66biolinks custom" |
+| Affiliate Plugin | "Affiliate Plugin" |
+| Push Notifications Plugin | "Push Notifications Plugin" |
+| Teams Plugin | "Teams Plugin" |
+| PWA Plugin | "PWA Plugin" |
+| Image Optimizer Plugin | "Image Optimizer Plugin" |
+| Email Shield Plugin | "Email Shield Plugin" |
+| Dynamic OG Images | "Dynamic OG images plugin" |
+| Offload & CDN | "Offload & CDN Plugin" |
+| Payment Blocks | "Payment Blocks - 66biolinks plugin" |
+| Ultimate Blocks | "Ultimate Blocks - 66biolinks plugin" |
+| Pro Blocks | "Pro Blocks - 66biolinks plugin" |
+| Pro Notifications | "Pro Notifications - 66socialproof plugin" |
+| AltumCode Club | "The AltumCode Club" |
+
+## CodeCanyon Download Flow (Claude in Chrome)
+
+CodeCanyon uses saved browser session cookies (user: snidered).
+
+1. Navigate to `https://codecanyon.net/downloads`
+2. Dismiss cookie banner if present (click "Reject all")
+3. For 66socialproof:
+ a. Find "66socialproof" Download button
+ b. Click the dropdown arrow
+ c. Click "All files & documentation"
+4. For 66biolinks:
+ a. Find "66biolinks" Download button (scroll down)
+ b. Click the dropdown arrow
+ c. Click "All files & documentation"
+5. Move downloaded zips to staging
+
+### CodeCanyon Download URLs (stable)
+
+- 66socialproof: `/user/snidered/download_purchase/8d8ef4c1-5add-4eba-9a89-4261a9c87e0b`
+- 66biolinks: `/user/snidered/download_purchase/38d79f4e-19cd-480a-b068-4332629b5206`
+
+## Post-Download
+
+1. List all zips in staging folder
+2. For each product zip:
+ - Extract to `~/Code/lthn/saas/services/{product}/package/product/`
+3. For each plugin zip:
+ - Extract to the correct product's `plugins/{plugin_id}/` directory
+ - Note: Some plugins apply to multiple products (affiliate, teams, etc.)
+4. Show summary of what was updated
+5. Remind user: "Files staged. Run `deploy_saas.yml` when ready to deploy."
+
+## Important Notes
+
+- Never make purchases or enter financial information
+- LemonSqueezy session expires — if Playwright gets a login page mid-flow, re-trigger magic link
+- CodeCanyon session depends on Chrome cookies — if logged out, tell user to log in manually
+- The AltumCode Club subscription is NOT a downloadable product — skip it
+- Plugin `aix` may not appear on LemonSqueezy (bundled with products) — skip if not found
+```
+
+**Step 3: Verify plugin loads**
+
+Run: `claude` in a new terminal, then type `/update-altum` to verify the skill is discovered.
+
+**Step 4: Commit**
+
+```bash
+cd /Users/snider/.claude/plugins/altum-updater
+git init
+git add plugin.json skills/update-altum.md
+git commit -m "feat: altum-updater Claude Code plugin — marketplace download skill
+
+Playwright for LemonSqueezy, Chrome for CodeCanyon. Includes full
+product/plugin mapping and download flow documentation.
+
+Co-Authored-By: Virgil "
+```
+
+---
+
+### Task 4: Sync deployed plugin versions from source
+
+**Files:**
+- Create: `/Users/snider/Code/core/php-uptelligence/Console/SyncAltumVersionsCommand.php`
+- Modify: `/Users/snider/Code/core/php-uptelligence/Boot.php` (register command)
+- Test: `/Users/snider/Code/core/php-uptelligence/tests/Unit/SyncAltumVersionsCommandTest.php`
+
+**Step 1: Write the failing test**
+
+```php
+artisan('uptelligence:sync-altum-versions', ['--dry-run' => true])
+ ->assertExitCode(0);
+});
+```
+
+**Step 2: Run test to verify it fails**
+
+Run: `cd /Users/snider/Code/core/php-uptelligence && composer test -- --filter=SyncAltumVersions`
+Expected: FAIL — command not found
+
+**Step 3: Write minimal implementation**
+
+Create `/Users/snider/Code/core/php-uptelligence/Console/SyncAltumVersionsCommand.php`:
+
+```php
+ '66analytics/package/product',
+ '66biolinks' => '66biolinks/package/product',
+ '66pusher' => '66pusher/package/product',
+ '66socialproof' => '66socialproof/package/product',
+ ];
+
+ public function handle(): int
+ {
+ $basePath = $this->option('path')
+ ?? env('SAAS_SERVICES_PATH', base_path('../lthn/saas/services'));
+ $dryRun = $this->option('dry-run');
+
+ $this->info('Syncing AltumCode versions from source...');
+ $this->newLine();
+
+ $updates = [];
+
+ // Sync product versions
+ foreach ($this->productPaths as $slug => $relativePath) {
+ $productPath = rtrim($basePath, '/') . '/' . $relativePath;
+ $version = $this->readProductVersion($productPath);
+
+ if ($version) {
+ $updates[] = $this->syncVendorVersion($slug, $version, $dryRun);
+ } else {
+ $this->warn(" Could not read version for {$slug} at {$productPath}");
+ }
+ }
+
+ // Sync plugin versions — read from biolinks as canonical source
+ $biolinkPluginsPath = rtrim($basePath, '/') . '/66biolinks/package/product/plugins';
+ if (is_dir($biolinkPluginsPath)) {
+ foreach (glob($biolinkPluginsPath . '/*/config.php') as $configFile) {
+ $pluginId = basename(dirname($configFile));
+ $version = $this->readPluginVersion($configFile);
+
+ if ($version) {
+ $slug = "altum-plugin-{$pluginId}";
+ $updates[] = $this->syncVendorVersion($slug, $version, $dryRun);
+ }
+ }
+ }
+
+ // Output table
+ $this->table(
+ ['Vendor', 'Old Version', 'New Version', 'Status'],
+ array_filter($updates)
+ );
+
+ if ($dryRun) {
+ $this->warn('Dry run — no changes written.');
+ }
+
+ return self::SUCCESS;
+ }
+
+ protected function readProductVersion(string $productPath): ?string
+ {
+ // Read version from app/init.php or similar — look for PRODUCT_VERSION define
+ $initFile = $productPath . '/app/init.php';
+ if (! file_exists($initFile)) {
+ return null;
+ }
+
+ $content = file_get_contents($initFile);
+ if (preg_match("/define\('PRODUCT_VERSION',\s*'([^']+)'\)/", $content, $matches)) {
+ return $matches[1];
+ }
+
+ return null;
+ }
+
+ protected function readPluginVersion(string $configFile): ?string
+ {
+ if (! file_exists($configFile)) {
+ return null;
+ }
+
+ $content = file_get_contents($configFile);
+
+ // PHP config format: 'version' => '2.0.0'
+ if (preg_match("/'version'\s*=>\s*'([^']+)'/", $content, $matches)) {
+ return $matches[1];
+ }
+
+ return null;
+ }
+
+ protected function syncVendorVersion(string $slug, string $version, bool $dryRun): ?array
+ {
+ $vendor = Vendor::where('slug', $slug)->first();
+ if (! $vendor) {
+ return [$slug, '(not in DB)', $version, 'SKIPPED'];
+ }
+
+ $oldVersion = $vendor->current_version;
+ if ($oldVersion === $version) {
+ return [$slug, $oldVersion, $version, 'current'];
+ }
+
+ if (! $dryRun) {
+ $vendor->update(['current_version' => $version]);
+ }
+
+ return [$slug, $oldVersion ?? '(none)', $version, $dryRun ? 'WOULD UPDATE' : 'UPDATED'];
+ }
+}
+```
+
+Register in Boot.php — add to `onConsole()`:
+
+```php
+$event->command(Console\SyncAltumVersionsCommand::class);
+```
+
+**Step 4: Run test to verify it passes**
+
+Run: `cd /Users/snider/Code/core/php-uptelligence && composer test -- --filter=SyncAltumVersions`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+cd /Users/snider/Code/core/php-uptelligence
+git add Console/SyncAltumVersionsCommand.php Boot.php tests/Unit/SyncAltumVersionsCommandTest.php
+git commit -m "feat: sync deployed AltumCode versions from source files
+
+Reads PRODUCT_VERSION from product init.php and plugin versions from
+config.php files. Updates uptelligence_vendors table so check-updates
+knows what's actually deployed.
+
+Co-Authored-By: Virgil "
+```
+
+---
+
+### Task 5: End-to-end verification
+
+**Step 1: Seed vendors on local dev**
+
+```bash
+cd /Users/snider/Code/lab/host.uk.com
+php artisan db:seed --class="Core\Mod\Uptelligence\Database\Seeders\AltumCodeVendorSeeder"
+```
+
+**Step 2: Sync actual deployed versions**
+
+```bash
+php artisan uptelligence:sync-altum-versions --path=/Users/snider/Code/lthn/saas/services
+```
+
+**Step 3: Run the update check**
+
+```bash
+php artisan uptelligence:check-updates
+```
+
+Expected: Table showing current vs latest versions for all 17 AltumCode vendors.
+
+**Step 4: Test the skill**
+
+Open a new Claude Code session and run `/update-altum` to verify the skill loads and shows the workflow.
+
+**Step 5: Commit any fixes**
+
+```bash
+git add -A && git commit -m "fix: adjustments from end-to-end testing"
+```
diff --git a/.core/reference/docs/primitives.md b/.core/reference/docs/primitives.md
new file mode 100644
index 0000000..43701f2
--- /dev/null
+++ b/.core/reference/docs/primitives.md
@@ -0,0 +1,169 @@
+---
+title: Core Primitives
+description: The repeated shapes that make CoreGO easy to navigate.
+---
+
+# Core Primitives
+
+CoreGO is easiest to use when you read it as a small vocabulary repeated everywhere. Most of the framework is built from the same handful of types.
+
+## Primitive Map
+
+| Type | Used For |
+|------|----------|
+| `Options` | Input values and lightweight metadata |
+| `Result` | Output values and success state |
+| `Service` | Lifecycle-managed components |
+| `Message` | Broadcast events |
+| `Query` | Request-response lookups |
+| `Task` | Side-effecting work items |
+
+## `Option` and `Options`
+
+`Option` is one key-value pair. `Options` is an ordered slice of them.
+
+```go
+opts := core.Options{
+ {Key: "name", Value: "brain"},
+ {Key: "path", Value: "prompts"},
+ {Key: "debug", Value: true},
+}
+```
+
+Use the helpers to read values:
+
+```go
+name := opts.String("name")
+path := opts.String("path")
+debug := opts.Bool("debug")
+hasPath := opts.Has("path")
+raw := opts.Get("name")
+```
+
+### Important Details
+
+- `Get` returns the first matching key.
+- `String`, `Int`, and `Bool` do not convert between types.
+- Missing keys return zero values.
+- CLI flags with values are stored as strings, so `--port=8080` should be read with `opts.String("port")`, not `opts.Int("port")`.
+
+## `Result`
+
+`Result` is the universal return shape.
+
+```go
+r := core.Result{Value: "ready", OK: true}
+
+if r.OK {
+ fmt.Println(r.Value)
+}
+```
+
+It has two jobs:
+
+- carry a value when work succeeds
+- carry either an error or an empty state when work does not succeed
+
+### `Result.Result(...)`
+
+The `Result()` method adapts plain Go values and `(value, error)` pairs into a `core.Result`.
+
+```go
+r1 := core.Result{}.Result("hello")
+r2 := core.Result{}.Result(file, err)
+```
+
+This is how several built-in helpers bridge standard-library calls.
+
+## `Service`
+
+`Service` is the managed lifecycle DTO stored in the registry.
+
+```go
+svc := core.Service{
+ Name: "cache",
+ Options: core.Options{
+ {Key: "backend", Value: "memory"},
+ },
+ OnStart: func() core.Result {
+ return core.Result{OK: true}
+ },
+ OnStop: func() core.Result {
+ return core.Result{OK: true}
+ },
+ OnReload: func() core.Result {
+ return core.Result{OK: true}
+ },
+}
+```
+
+### Important Details
+
+- `OnStart` and `OnStop` are used by the framework lifecycle.
+- `OnReload` is stored on the service DTO, but CoreGO does not currently call it automatically.
+- The registry stores `*core.Service`, not arbitrary typed service instances.
+
+## `Message`, `Query`, and `Task`
+
+These are simple aliases to `any`.
+
+```go
+type Message any
+type Query any
+type Task any
+```
+
+That means your own structs become the protocol:
+
+```go
+type deployStarted struct {
+ Environment string
+}
+
+type workspaceCountQuery struct{}
+
+type syncRepositoryTask struct {
+ Name string
+}
+```
+
+## `TaskWithIdentifier`
+
+Long-running tasks can opt into task identifiers.
+
+```go
+type indexedTask struct {
+ ID string
+}
+
+func (t *indexedTask) SetTaskIdentifier(id string) { t.ID = id }
+func (t *indexedTask) GetTaskIdentifier() string { return t.ID }
+```
+
+If a task implements `TaskWithIdentifier`, `PerformAsync` injects the generated `task-N` identifier before dispatch.
+
+## `ServiceRuntime[T]`
+
+`ServiceRuntime[T]` is the small helper for packages that want to keep a Core reference and a typed options struct together.
+
+```go
+type agentServiceOptions struct {
+ WorkspacePath string
+}
+
+type agentService struct {
+ *core.ServiceRuntime[agentServiceOptions]
+}
+
+runtime := core.NewServiceRuntime(c, agentServiceOptions{
+ WorkspacePath: "/srv/agent-workspaces",
+})
+```
+
+It exposes:
+
+- `Core()`
+- `Options()`
+- `Config()`
+
+This helper does not register anything by itself. It is a composition aid for package authors.
diff --git a/.core/reference/docs/services.md b/.core/reference/docs/services.md
new file mode 100644
index 0000000..ad95d64
--- /dev/null
+++ b/.core/reference/docs/services.md
@@ -0,0 +1,152 @@
+---
+title: Services
+description: Register, inspect, and lock CoreGO services.
+---
+
+# Services
+
+In CoreGO, a service is a named lifecycle entry stored in the Core registry.
+
+## Register a Service
+
+```go
+c := core.New()
+
+r := c.Service("audit", core.Service{
+ OnStart: func() core.Result {
+ core.Info("audit started")
+ return core.Result{OK: true}
+ },
+ OnStop: func() core.Result {
+ core.Info("audit stopped")
+ return core.Result{OK: true}
+ },
+})
+```
+
+Registration succeeds when:
+
+- the name is not empty
+- the registry is not locked
+- the name is not already in use
+
+## Read a Service Back
+
+```go
+r := c.Service("audit")
+if r.OK {
+ svc := r.Value.(*core.Service)
+ _ = svc
+}
+```
+
+The returned value is `*core.Service`.
+
+## List Registered Services
+
+```go
+names := c.Services()
+```
+
+### Important Detail
+
+The current registry is map-backed. `Services()`, `Startables()`, and `Stoppables()` do not promise a stable order.
+
+## Lifecycle Snapshots
+
+Use these helpers when you want the current set of startable or stoppable services:
+
+```go
+startables := c.Startables()
+stoppables := c.Stoppables()
+```
+
+They return `[]*core.Service` inside `Result.Value`.
+
+## Lock the Registry
+
+CoreGO has a service-lock mechanism, but it is explicit.
+
+```go
+c := core.New()
+
+c.LockEnable()
+c.Service("audit", core.Service{})
+c.Service("cache", core.Service{})
+c.LockApply()
+```
+
+After `LockApply`, new registrations fail:
+
+```go
+r := c.Service("late", core.Service{})
+fmt.Println(r.OK) // false
+```
+
+The default lock name is `"srv"`. You can pass a different name if you need a custom lock namespace.
+
+For the service registry itself, use the default `"srv"` lock path. That is the path used by `Core.Service(...)`.
+
+## `NewWithFactories`
+
+For GUI runtimes or factory-driven setup, CoreGO provides `NewWithFactories`.
+
+```go
+r := core.NewWithFactories(nil, map[string]core.ServiceFactory{
+ "audit": func() core.Result {
+ return core.Result{Value: core.Service{
+ OnStart: func() core.Result {
+ return core.Result{OK: true}
+ },
+ }, OK: true}
+ },
+ "cache": func() core.Result {
+ return core.Result{Value: core.Service{}, OK: true}
+ },
+})
+```
+
+### Important Details
+
+- each factory must return a `core.Service` in `Result.Value`
+- factories are executed in sorted key order
+- nil factories are skipped
+- the return value is `*core.Runtime`
+
+## `Runtime`
+
+`Runtime` is a small wrapper used for external runtimes such as GUI bindings.
+
+```go
+r := core.NewRuntime(nil)
+rt := r.Value.(*core.Runtime)
+
+_ = rt.ServiceStartup(context.Background(), nil)
+_ = rt.ServiceShutdown(context.Background())
+```
+
+`Runtime.ServiceName()` returns `"Core"`.
+
+## `ServiceRuntime[T]` for Package Authors
+
+If you are writing a package on top of CoreGO, use `ServiceRuntime[T]` to keep a typed options struct and the parent `Core` together.
+
+```go
+type repositoryServiceOptions struct {
+ BaseDirectory string
+}
+
+type repositoryService struct {
+ *core.ServiceRuntime[repositoryServiceOptions]
+}
+
+func newRepositoryService(c *core.Core) *repositoryService {
+ return &repositoryService{
+ ServiceRuntime: core.NewServiceRuntime(c, repositoryServiceOptions{
+ BaseDirectory: "/srv/repos",
+ }),
+ }
+}
+```
+
+This is a package-authoring helper. It does not replace the `core.Service` registry entry.
diff --git a/.core/reference/docs/subsystems.md b/.core/reference/docs/subsystems.md
new file mode 100644
index 0000000..f39ea16
--- /dev/null
+++ b/.core/reference/docs/subsystems.md
@@ -0,0 +1,158 @@
+---
+title: Subsystems
+description: Built-in accessors for app metadata, embedded data, filesystem, transport handles, i18n, and CLI.
+---
+
+# Subsystems
+
+`Core` gives you a set of built-in subsystems so small applications do not need extra plumbing before they can do useful work.
+
+## Accessor Map
+
+| Accessor | Purpose |
+|----------|---------|
+| `App()` | Application identity and external runtime |
+| `Data()` | Named embedded filesystem mounts |
+| `Drive()` | Named transport handles |
+| `Fs()` | Local filesystem access |
+| `I18n()` | Locale collection and translation delegation |
+| `Cli()` | Command-line surface over the command tree |
+
+## `App`
+
+`App` stores process identity and optional GUI runtime state.
+
+```go
+app := c.App()
+app.Name = "agent-workbench"
+app.Version = "0.25.0"
+app.Description = "workspace runner"
+app.Runtime = myRuntime
+```
+
+`Find` resolves an executable on `PATH` and returns an `*App`.
+
+```go
+r := core.Find("go", "Go toolchain")
+```
+
+## `Data`
+
+`Data` mounts named embedded filesystems and makes them addressable through paths like `mount-name/path/to/file`.
+
+```go
+c.Data().New(core.Options{
+ {Key: "name", Value: "app"},
+ {Key: "source", Value: appFS},
+ {Key: "path", Value: "templates"},
+})
+```
+
+Read content:
+
+```go
+text := c.Data().ReadString("app/agent.md")
+bytes := c.Data().ReadFile("app/agent.md")
+list := c.Data().List("app")
+names := c.Data().ListNames("app")
+```
+
+Extract a mounted directory:
+
+```go
+r := c.Data().Extract("app/workspace", "/tmp/workspace", nil)
+```
+
+### Path Rule
+
+The first path segment is always the mount name.
+
+## `Drive`
+
+`Drive` is a registry for named transport handles.
+
+```go
+c.Drive().New(core.Options{
+ {Key: "name", Value: "api"},
+ {Key: "transport", Value: "https://api.lthn.ai"},
+})
+
+c.Drive().New(core.Options{
+ {Key: "name", Value: "mcp"},
+ {Key: "transport", Value: "mcp://mcp.lthn.sh"},
+})
+```
+
+Read them back:
+
+```go
+handle := c.Drive().Get("api")
+hasMCP := c.Drive().Has("mcp")
+names := c.Drive().Names()
+```
+
+## `Fs`
+
+`Fs` wraps local filesystem operations with a consistent `Result` shape.
+
+```go
+c.Fs().Write("/tmp/core-go/example.txt", "hello")
+r := c.Fs().Read("/tmp/core-go/example.txt")
+```
+
+Other helpers:
+
+```go
+c.Fs().EnsureDir("/tmp/core-go/cache")
+c.Fs().List("/tmp/core-go")
+c.Fs().Stat("/tmp/core-go/example.txt")
+c.Fs().Rename("/tmp/core-go/example.txt", "/tmp/core-go/example-2.txt")
+c.Fs().Delete("/tmp/core-go/example-2.txt")
+```
+
+### Important Details
+
+- the default `Core` starts with `Fs{root:"/"}`
+- relative paths resolve from the current working directory
+- `Delete` and `DeleteAll` refuse to remove `/` and `$HOME`
+
+## `I18n`
+
+`I18n` collects locale mounts and forwards translation work to a translator implementation when one is registered.
+
+```go
+c.I18n().SetLanguage("en-GB")
+```
+
+Without a translator, `Translate` returns the message key itself:
+
+```go
+r := c.I18n().Translate("cmd.deploy.description")
+```
+
+With a translator:
+
+```go
+c.I18n().SetTranslator(myTranslator)
+```
+
+Then:
+
+```go
+langs := c.I18n().AvailableLanguages()
+current := c.I18n().Language()
+```
+
+## `Cli`
+
+`Cli` exposes the command registry through a terminal-facing API.
+
+```go
+c.Cli().SetBanner(func(_ *core.Cli) string {
+ return "Agent Workbench"
+})
+
+r := c.Cli().Run("workspace", "create", "--name=alpha")
+```
+
+Use [commands.md](commands.md) for the full command and flag model.
diff --git a/.core/reference/docs/testing.md b/.core/reference/docs/testing.md
new file mode 100644
index 0000000..656634a
--- /dev/null
+++ b/.core/reference/docs/testing.md
@@ -0,0 +1,118 @@
+---
+title: Testing
+description: Test naming and testing patterns used by CoreGO.
+---
+
+# Testing
+
+The repository uses `github.com/stretchr/testify/assert` and a simple AX-friendly naming pattern.
+
+## Test Names
+
+Use:
+
+- `_Good` for expected success
+- `_Bad` for expected failure
+- `_Ugly` for panics, degenerate input, and edge behavior
+
+Examples from this repository:
+
+```go
+func TestNew_Good(t *testing.T) {}
+func TestService_Register_Duplicate_Bad(t *testing.T) {}
+func TestCore_Must_Ugly(t *testing.T) {}
+```
+
+## Start with a Small Core
+
+```go
+c := core.New(core.Options{
+ {Key: "name", Value: "test-core"},
+})
+```
+
+Then register only the pieces your test needs.
+
+## Test a Service
+
+```go
+started := false
+
+c.Service("audit", core.Service{
+ OnStart: func() core.Result {
+ started = true
+ return core.Result{OK: true}
+ },
+})
+
+r := c.ServiceStartup(context.Background(), nil)
+assert.True(t, r.OK)
+assert.True(t, started)
+```
+
+## Test a Command
+
+```go
+c.Command("greet", core.Command{
+ Action: func(opts core.Options) core.Result {
+ return core.Result{Value: "hello " + opts.String("name"), OK: true}
+ },
+})
+
+r := c.Cli().Run("greet", "--name=world")
+assert.True(t, r.OK)
+assert.Equal(t, "hello world", r.Value)
+```
+
+## Test a Query or Task
+
+```go
+c.RegisterQuery(func(_ *core.Core, q core.Query) core.Result {
+ if q == "ping" {
+ return core.Result{Value: "pong", OK: true}
+ }
+ return core.Result{}
+})
+
+assert.Equal(t, "pong", c.QUERY("ping").Value)
+```
+
+```go
+c.RegisterTask(func(_ *core.Core, t core.Task) core.Result {
+ if t == "compute" {
+ return core.Result{Value: 42, OK: true}
+ }
+ return core.Result{}
+})
+
+assert.Equal(t, 42, c.PERFORM("compute").Value)
+```
+
+## Test Async Work
+
+For `PerformAsync`, observe completion through the action bus.
+
+```go
+completed := make(chan core.ActionTaskCompleted, 1)
+
+c.RegisterAction(func(_ *core.Core, msg core.Message) core.Result {
+ if event, ok := msg.(core.ActionTaskCompleted); ok {
+ completed <- event
+ }
+ return core.Result{OK: true}
+})
+```
+
+Then wait with normal Go test tools such as channels, timers, or `assert.Eventually`.
+
+## Use Real Temporary Paths
+
+When testing `Fs`, `Data.Extract`, or other I/O helpers, use `t.TempDir()` and create realistic paths instead of mocking the filesystem by default.
+
+## Repository Commands
+
+```bash
+core go test
+core go test --run TestPerformAsync_Good
+go test ./...
+```
diff --git a/.core/reference/drive.go b/.core/reference/drive.go
new file mode 100644
index 0000000..7bf6869
--- /dev/null
+++ b/.core/reference/drive.go
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Drive is the resource handle registry for transport connections.
+// Packages register their transport handles (API, MCP, SSH, VPN)
+// and other packages access them by name.
+//
+// Register a transport:
+//
+// c.Drive().New(core.NewOptions(
+// core.Option{Key: "name", Value: "api"},
+// core.Option{Key: "transport", Value: "https://api.lthn.ai"},
+// ))
+// c.Drive().New(core.NewOptions(
+// core.Option{Key: "name", Value: "ssh"},
+// core.Option{Key: "transport", Value: "ssh://claude@10.69.69.165"},
+// ))
+// c.Drive().New(core.NewOptions(
+// core.Option{Key: "name", Value: "mcp"},
+// core.Option{Key: "transport", Value: "mcp://mcp.lthn.sh"},
+// ))
+//
+// Retrieve a handle:
+//
+// api := c.Drive().Get("api")
+package core
+
+// DriveHandle holds a named transport resource.
+type DriveHandle struct {
+ Name string
+ Transport string
+ Options Options
+}
+
+// Drive manages named transport handles. Embeds Registry[*DriveHandle].
+type Drive struct {
+ *Registry[*DriveHandle]
+}
+
+// New registers a transport handle.
+//
+// c.Drive().New(core.NewOptions(
+// core.Option{Key: "name", Value: "api"},
+// core.Option{Key: "transport", Value: "https://api.lthn.ai"},
+// ))
+func (d *Drive) New(opts Options) Result {
+ name := opts.String("name")
+ if name == "" {
+ return Result{}
+ }
+
+ handle := &DriveHandle{
+ Name: name,
+ Transport: opts.String("transport"),
+ Options: opts,
+ }
+
+ d.Set(name, handle)
+ return Result{handle, true}
+}
diff --git a/.core/reference/embed.go b/.core/reference/embed.go
new file mode 100644
index 0000000..7951543
--- /dev/null
+++ b/.core/reference/embed.go
@@ -0,0 +1,668 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Embedded assets for the Core framework.
+//
+// Embed provides scoped filesystem access for go:embed and any fs.FS.
+// Also includes build-time asset packing (AST scanner + compressor)
+// and template-based directory extraction.
+//
+// Usage (mount):
+//
+// sub, _ := core.Mount(myFS, "lib/persona")
+// content, _ := sub.ReadString("secops/developer.md")
+//
+// Usage (extract):
+//
+// core.Extract(fsys, "/tmp/workspace", data)
+//
+// Usage (pack):
+//
+// refs, _ := core.ScanAssets([]string{"main.go"})
+// source, _ := core.GeneratePack(refs)
+package core
+
+import (
+ "bytes"
+ "compress/gzip"
+ "embed"
+ "encoding/base64"
+ "fmt"
+ "go/ast"
+ "go/parser"
+ "go/token"
+ "io"
+ "io/fs"
+ "os"
+ "path/filepath"
+ "sync"
+ "text/template"
+)
+
+// --- Runtime: Asset Registry ---
+
+// AssetGroup holds a named collection of packed assets.
+type AssetGroup struct {
+ assets map[string]string // name → compressed data
+}
+
+var (
+ assetGroups = make(map[string]*AssetGroup)
+ assetGroupsMu sync.RWMutex
+)
+
+// AddAsset registers a packed asset at runtime (called from generated init()).
+func AddAsset(group, name, data string) {
+ assetGroupsMu.Lock()
+ defer assetGroupsMu.Unlock()
+
+ g, ok := assetGroups[group]
+ if !ok {
+ g = &AssetGroup{assets: make(map[string]string)}
+ assetGroups[group] = g
+ }
+ g.assets[name] = data
+}
+
+// GetAsset retrieves and decompresses a packed asset.
+//
+// r := core.GetAsset("mygroup", "greeting")
+// if r.OK { content := r.Value.(string) }
+func GetAsset(group, name string) Result {
+ assetGroupsMu.RLock()
+ g, ok := assetGroups[group]
+ if !ok {
+ assetGroupsMu.RUnlock()
+ return Result{}
+ }
+ data, ok := g.assets[name]
+ assetGroupsMu.RUnlock()
+ if !ok {
+ return Result{}
+ }
+ s, err := decompress(data)
+ if err != nil {
+ return Result{err, false}
+ }
+ return Result{s, true}
+}
+
+// GetAssetBytes retrieves a packed asset as bytes.
+//
+// r := core.GetAssetBytes("mygroup", "file")
+// if r.OK { data := r.Value.([]byte) }
+func GetAssetBytes(group, name string) Result {
+ r := GetAsset(group, name)
+ if !r.OK {
+ return r
+ }
+ return Result{[]byte(r.Value.(string)), true}
+}
+
+// --- Build-time: AST Scanner ---
+
+// AssetRef is a reference to an asset found in source code.
+type AssetRef struct {
+ Name string
+ Path string
+ Group string
+ FullPath string
+}
+
+// ScannedPackage holds all asset references from a set of source files.
+type ScannedPackage struct {
+ PackageName string
+ BaseDirectory string
+ Groups []string
+ Assets []AssetRef
+}
+
+// ScanAssets parses Go source files and finds asset references.
+// Looks for calls to: core.GetAsset("group", "name"), core.AddAsset, etc.
+func ScanAssets(filenames []string) Result {
+ packageMap := make(map[string]*ScannedPackage)
+ var scanErr error
+
+ for _, filename := range filenames {
+ fset := token.NewFileSet()
+ node, err := parser.ParseFile(fset, filename, nil, parser.AllErrors)
+ if err != nil {
+ return Result{err, false}
+ }
+
+ baseDir := filepath.Dir(filename)
+ pkg, ok := packageMap[baseDir]
+ if !ok {
+ pkg = &ScannedPackage{BaseDirectory: baseDir}
+ packageMap[baseDir] = pkg
+ }
+ pkg.PackageName = node.Name.Name
+
+ ast.Inspect(node, func(n ast.Node) bool {
+ if scanErr != nil {
+ return false
+ }
+ call, ok := n.(*ast.CallExpr)
+ if !ok {
+ return true
+ }
+
+ sel, ok := call.Fun.(*ast.SelectorExpr)
+ if !ok {
+ return true
+ }
+
+ ident, ok := sel.X.(*ast.Ident)
+ if !ok {
+ return true
+ }
+
+ // Look for core.GetAsset or mewn.String patterns
+ if ident.Name == "core" || ident.Name == "mewn" {
+ switch sel.Sel.Name {
+ case "GetAsset", "GetAssetBytes", "String", "MustString", "Bytes", "MustBytes":
+ if len(call.Args) >= 1 {
+ if lit, ok := call.Args[len(call.Args)-1].(*ast.BasicLit); ok {
+ path := TrimPrefix(TrimSuffix(lit.Value, "\""), "\"")
+ group := "."
+ if len(call.Args) >= 2 {
+ if glit, ok := call.Args[0].(*ast.BasicLit); ok {
+ group = TrimPrefix(TrimSuffix(glit.Value, "\""), "\"")
+ }
+ }
+ fullPath, err := filepath.Abs(filepath.Join(baseDir, group, path))
+ if err != nil {
+ scanErr = Wrap(err, "core.ScanAssets", Join(" ", "could not determine absolute path for asset", path, "in group", group))
+ return false
+ }
+ pkg.Assets = append(pkg.Assets, AssetRef{
+ Name: path,
+
+ Group: group,
+ FullPath: fullPath,
+ })
+ }
+ }
+ case "Group":
+ // Variable assignment: g := core.Group("./assets")
+ if len(call.Args) == 1 {
+ if lit, ok := call.Args[0].(*ast.BasicLit); ok {
+ path := TrimPrefix(TrimSuffix(lit.Value, "\""), "\"")
+ fullPath, err := filepath.Abs(filepath.Join(baseDir, path))
+ if err != nil {
+ scanErr = Wrap(err, "core.ScanAssets", Join(" ", "could not determine absolute path for group", path))
+ return false
+ }
+ pkg.Groups = append(pkg.Groups, fullPath)
+ // Track for variable resolution
+ }
+ }
+ }
+ }
+
+ return true
+ })
+ if scanErr != nil {
+ return Result{scanErr, false}
+ }
+ }
+
+ var result []ScannedPackage
+ for _, pkg := range packageMap {
+ result = append(result, *pkg)
+ }
+ return Result{result, true}
+}
+
+// GeneratePack creates Go source code that embeds the scanned assets.
+func GeneratePack(pkg ScannedPackage) Result {
+ b := NewBuilder()
+
+ b.WriteString(fmt.Sprintf("package %s\n\n", pkg.PackageName))
+ b.WriteString("// Code generated by core pack. DO NOT EDIT.\n\n")
+
+ if len(pkg.Assets) == 0 && len(pkg.Groups) == 0 {
+ return Result{b.String(), true}
+ }
+
+ b.WriteString("import \"dappco.re/go/core\"\n\n")
+ b.WriteString("func init() {\n")
+
+ // Pack groups (entire directories)
+ packed := make(map[string]bool)
+ for _, groupPath := range pkg.Groups {
+ files, err := getAllFiles(groupPath)
+ if err != nil {
+ return Result{err, false}
+ }
+ for _, file := range files {
+ if packed[file] {
+ continue
+ }
+ data, err := compressFile(file)
+ if err != nil {
+ return Result{err, false}
+ }
+ localPath := TrimPrefix(file, groupPath+"/")
+ relGroup, err := filepath.Rel(pkg.BaseDirectory, groupPath)
+ if err != nil {
+ return Result{err, false}
+ }
+ b.WriteString(fmt.Sprintf("\tcore.AddAsset(%q, %q, %q)\n", relGroup, localPath, data))
+ packed[file] = true
+ }
+ }
+
+ // Pack individual assets
+ for _, asset := range pkg.Assets {
+ if packed[asset.FullPath] {
+ continue
+ }
+ data, err := compressFile(asset.FullPath)
+ if err != nil {
+ return Result{err, false}
+ }
+ b.WriteString(fmt.Sprintf("\tcore.AddAsset(%q, %q, %q)\n", asset.Group, asset.Name, data))
+ packed[asset.FullPath] = true
+ }
+
+ b.WriteString("}\n")
+ return Result{b.String(), true}
+}
+
+// --- Compression ---
+
+func compressFile(path string) (string, error) {
+ data, err := os.ReadFile(path)
+ if err != nil {
+ return "", err
+ }
+ return compress(string(data))
+}
+
+func compress(input string) (string, error) {
+ var buf bytes.Buffer
+ b64 := base64.NewEncoder(base64.StdEncoding, &buf)
+ gz, err := gzip.NewWriterLevel(b64, gzip.BestCompression)
+ if err != nil {
+ return "", err
+ }
+ if _, err := gz.Write([]byte(input)); err != nil {
+ _ = gz.Close()
+ _ = b64.Close()
+ return "", err
+ }
+ if err := gz.Close(); err != nil {
+ _ = b64.Close()
+ return "", err
+ }
+ if err := b64.Close(); err != nil {
+ return "", err
+ }
+ return buf.String(), nil
+}
+
+func decompress(input string) (string, error) {
+ b64 := base64.NewDecoder(base64.StdEncoding, NewReader(input))
+ gz, err := gzip.NewReader(b64)
+ if err != nil {
+ return "", err
+ }
+
+ data, err := io.ReadAll(gz)
+ if err != nil {
+ return "", err
+ }
+ if err := gz.Close(); err != nil {
+ return "", err
+ }
+ return string(data), nil
+}
+
+func getAllFiles(dir string) ([]string, error) {
+ var result []string
+ err := filepath.WalkDir(dir, func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if !d.IsDir() {
+ result = append(result, path)
+ }
+ return nil
+ })
+ return result, err
+}
+
+// --- Embed: Scoped Filesystem Mount ---
+
+// Embed wraps an fs.FS with a basedir for scoped access.
+// All paths are relative to basedir.
+type Embed struct {
+ basedir string
+ fsys fs.FS
+ embedFS *embed.FS // original embed.FS for type-safe access via EmbedFS()
+}
+
+// Mount creates a scoped view of an fs.FS anchored at basedir.
+//
+// r := core.Mount(myFS, "lib/prompts")
+// if r.OK { emb := r.Value.(*Embed) }
+func Mount(fsys fs.FS, basedir string) Result {
+ s := &Embed{fsys: fsys, basedir: basedir}
+
+ if efs, ok := fsys.(embed.FS); ok {
+ s.embedFS = &efs
+ }
+
+ if r := s.ReadDir("."); !r.OK {
+ return r
+ }
+ return Result{s, true}
+}
+
+// MountEmbed creates a scoped view of an embed.FS.
+//
+// r := core.MountEmbed(myFS, "testdata")
+func MountEmbed(efs embed.FS, basedir string) Result {
+ return Mount(efs, basedir)
+}
+
+func (s *Embed) path(name string) Result {
+ joined := filepath.ToSlash(filepath.Join(s.basedir, name))
+ if HasPrefix(joined, "..") || Contains(joined, "/../") || HasSuffix(joined, "/..") {
+ return Result{E("embed.path", Concat("path traversal rejected: ", name), nil), false}
+ }
+ return Result{joined, true}
+}
+
+// Open opens the named file for reading.
+//
+// r := emb.Open("test.txt")
+// if r.OK { file := r.Value.(fs.File) }
+func (s *Embed) Open(name string) Result {
+ r := s.path(name)
+ if !r.OK {
+ return r
+ }
+ f, err := s.fsys.Open(r.Value.(string))
+ if err != nil {
+ return Result{err, false}
+ }
+ return Result{f, true}
+}
+
+// ReadDir reads the named directory.
+func (s *Embed) ReadDir(name string) Result {
+ r := s.path(name)
+ if !r.OK {
+ return r
+ }
+ return Result{}.New(fs.ReadDir(s.fsys, r.Value.(string)))
+}
+
+// ReadFile reads the named file.
+//
+// r := emb.ReadFile("test.txt")
+// if r.OK { data := r.Value.([]byte) }
+func (s *Embed) ReadFile(name string) Result {
+ r := s.path(name)
+ if !r.OK {
+ return r
+ }
+ data, err := fs.ReadFile(s.fsys, r.Value.(string))
+ if err != nil {
+ return Result{err, false}
+ }
+ return Result{data, true}
+}
+
+// ReadString reads the named file as a string.
+//
+// r := emb.ReadString("test.txt")
+// if r.OK { content := r.Value.(string) }
+func (s *Embed) ReadString(name string) Result {
+ r := s.ReadFile(name)
+ if !r.OK {
+ return r
+ }
+ return Result{string(r.Value.([]byte)), true}
+}
+
+// Sub returns a new Embed anchored at a subdirectory within this mount.
+//
+// r := emb.Sub("testdata")
+// if r.OK { sub := r.Value.(*Embed) }
+func (s *Embed) Sub(subDir string) Result {
+ r := s.path(subDir)
+ if !r.OK {
+ return r
+ }
+ sub, err := fs.Sub(s.fsys, r.Value.(string))
+ if err != nil {
+ return Result{err, false}
+ }
+ return Result{&Embed{fsys: sub, basedir: "."}, true}
+}
+
+// FS returns the underlying fs.FS.
+func (s *Embed) FS() fs.FS {
+ return s.fsys
+}
+
+// EmbedFS returns the underlying embed.FS if mounted from one.
+// Returns zero embed.FS if mounted from a non-embed source.
+func (s *Embed) EmbedFS() embed.FS {
+ if s.embedFS != nil {
+ return *s.embedFS
+ }
+ return embed.FS{}
+}
+
+// BaseDirectory returns the base directory this Embed is anchored at.
+func (s *Embed) BaseDirectory() string {
+ return s.basedir
+}
+
+// --- Template Extraction ---
+
+// ExtractOptions configures template extraction.
+type ExtractOptions struct {
+ // TemplateFilters identifies template files by substring match.
+ // Default: [".tmpl"]
+ TemplateFilters []string
+
+ // IgnoreFiles is a set of filenames to skip during extraction.
+ IgnoreFiles map[string]struct{}
+
+ // RenameFiles maps original filenames to new names.
+ RenameFiles map[string]string
+}
+
+// Extract copies a template directory from an fs.FS to targetDir,
+// processing Go text/template in filenames and file contents.
+//
+// Files containing a template filter substring (default: ".tmpl") have
+// their contents processed through text/template with the given data.
+// The filter is stripped from the output filename.
+//
+// Directory and file names can contain Go template expressions:
+// {{.Name}}/main.go → myproject/main.go
+//
+// Data can be any struct or map[string]string for template substitution.
+func Extract(fsys fs.FS, targetDir string, data any, opts ...ExtractOptions) Result {
+ opt := ExtractOptions{
+ TemplateFilters: []string{".tmpl"},
+ IgnoreFiles: make(map[string]struct{}),
+ RenameFiles: make(map[string]string),
+ }
+ if len(opts) > 0 {
+ if len(opts[0].TemplateFilters) > 0 {
+ opt.TemplateFilters = opts[0].TemplateFilters
+ }
+ if opts[0].IgnoreFiles != nil {
+ opt.IgnoreFiles = opts[0].IgnoreFiles
+ }
+ if opts[0].RenameFiles != nil {
+ opt.RenameFiles = opts[0].RenameFiles
+ }
+ }
+
+ // Ensure target directory exists
+ targetDir, err := filepath.Abs(targetDir)
+ if err != nil {
+ return Result{err, false}
+ }
+ if err := os.MkdirAll(targetDir, 0755); err != nil {
+ return Result{err, false}
+ }
+
+ // Categorise files
+ var dirs []string
+ var templateFiles []string
+ var standardFiles []string
+
+ err = fs.WalkDir(fsys, ".", func(path string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return err
+ }
+ if path == "." {
+ return nil
+ }
+ if d.IsDir() {
+ dirs = append(dirs, path)
+ return nil
+ }
+ filename := filepath.Base(path)
+ if _, ignored := opt.IgnoreFiles[filename]; ignored {
+ return nil
+ }
+ if isTemplate(filename, opt.TemplateFilters) {
+ templateFiles = append(templateFiles, path)
+ } else {
+ standardFiles = append(standardFiles, path)
+ }
+ return nil
+ })
+ if err != nil {
+ return Result{err, false}
+ }
+
+ // safePath ensures a rendered path stays under targetDir.
+ safePath := func(rendered string) (string, error) {
+ abs, err := filepath.Abs(rendered)
+ if err != nil {
+ return "", err
+ }
+ if !HasPrefix(abs, targetDir+string(filepath.Separator)) && abs != targetDir {
+ return "", E("embed.Extract", Concat("path escapes target: ", abs), nil)
+ }
+ return abs, nil
+ }
+
+ // Create directories (names may contain templates)
+ for _, dir := range dirs {
+ target, err := safePath(renderPath(filepath.Join(targetDir, dir), data))
+ if err != nil {
+ return Result{err, false}
+ }
+ if err := os.MkdirAll(target, 0755); err != nil {
+ return Result{err, false}
+ }
+ }
+
+ // Process template files
+ for _, path := range templateFiles {
+ tmpl, err := template.ParseFS(fsys, path)
+ if err != nil {
+ return Result{err, false}
+ }
+
+ targetFile := renderPath(filepath.Join(targetDir, path), data)
+
+ // Strip template filters from filename
+ dir := filepath.Dir(targetFile)
+ name := filepath.Base(targetFile)
+ for _, filter := range opt.TemplateFilters {
+ name = Replace(name, filter, "")
+ }
+ if renamed := opt.RenameFiles[name]; renamed != "" {
+ name = renamed
+ }
+ targetFile, err = safePath(filepath.Join(dir, name))
+ if err != nil {
+ return Result{err, false}
+ }
+
+ f, err := os.Create(targetFile)
+ if err != nil {
+ return Result{err, false}
+ }
+ if err := tmpl.Execute(f, data); err != nil {
+ f.Close()
+ return Result{err, false}
+ }
+ f.Close()
+ }
+
+ // Copy standard files
+ for _, path := range standardFiles {
+ targetPath := path
+ name := filepath.Base(path)
+ if renamed := opt.RenameFiles[name]; renamed != "" {
+ targetPath = filepath.Join(filepath.Dir(path), renamed)
+ }
+ target, err := safePath(renderPath(filepath.Join(targetDir, targetPath), data))
+ if err != nil {
+ return Result{err, false}
+ }
+ if err := copyFile(fsys, path, target); err != nil {
+ return Result{err, false}
+ }
+ }
+
+ return Result{OK: true}
+}
+
+func isTemplate(filename string, filters []string) bool {
+ for _, f := range filters {
+ if Contains(filename, f) {
+ return true
+ }
+ }
+ return false
+}
+
+func renderPath(path string, data any) string {
+ if data == nil {
+ return path
+ }
+ tmpl, err := template.New("path").Parse(path)
+ if err != nil {
+ return path
+ }
+ var buf bytes.Buffer
+ if err := tmpl.Execute(&buf, data); err != nil {
+ return path
+ }
+ return buf.String()
+}
+
+func copyFile(fsys fs.FS, source, target string) error {
+ s, err := fsys.Open(source)
+ if err != nil {
+ return err
+ }
+ defer s.Close()
+
+ if err := os.MkdirAll(filepath.Dir(target), 0755); err != nil {
+ return err
+ }
+
+ d, err := os.Create(target)
+ if err != nil {
+ return err
+ }
+ defer d.Close()
+
+ _, err = io.Copy(d, s)
+ return err
+}
diff --git a/.core/reference/error.go b/.core/reference/error.go
new file mode 100644
index 0000000..d562494
--- /dev/null
+++ b/.core/reference/error.go
@@ -0,0 +1,395 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Structured errors, crash recovery, and reporting for the Core framework.
+// Provides E() for error creation, Wrap()/WrapCode() for chaining,
+// and Err for panic recovery and crash reporting.
+
+package core
+
+import (
+ "encoding/json"
+ "errors"
+ "iter"
+ "maps"
+ "os"
+ "path/filepath"
+ "runtime"
+ "runtime/debug"
+ "sync"
+ "time"
+)
+
+// ErrorSink is the shared interface for error reporting.
+// Implemented by ErrorLog (structured logging) and ErrorPanic (panic recovery).
+type ErrorSink interface {
+ Error(msg string, keyvals ...any)
+ Warn(msg string, keyvals ...any)
+}
+
+var _ ErrorSink = (*Log)(nil)
+
+// Err represents a structured error with operational context.
+// It implements the error interface and supports unwrapping.
+type Err struct {
+ Operation string // Operation being performed (e.g., "user.Save")
+ Message string // Human-readable message
+ Cause error // Underlying error (optional)
+ Code string // Error code (optional, e.g., "VALIDATION_FAILED")
+}
+
+// Error implements the error interface.
+func (e *Err) Error() string {
+ var prefix string
+ if e.Operation != "" {
+ prefix = e.Operation + ": "
+ }
+ if e.Cause != nil {
+ if e.Code != "" {
+ return Concat(prefix, e.Message, " [", e.Code, "]: ", e.Cause.Error())
+ }
+ return Concat(prefix, e.Message, ": ", e.Cause.Error())
+ }
+ if e.Code != "" {
+ return Concat(prefix, e.Message, " [", e.Code, "]")
+ }
+ return Concat(prefix, e.Message)
+}
+
+// Unwrap returns the underlying error for use with errors.Is and errors.As.
+func (e *Err) Unwrap() error {
+ return e.Cause
+}
+
+// --- Error Creation Functions ---
+
+// E creates a new Err with operation context.
+// The underlying error can be nil for creating errors without a cause.
+//
+// Example:
+//
+// return log.E("user.Save", "failed to save user", err)
+// return log.E("api.Call", "rate limited", nil) // No underlying cause
+func E(op, msg string, err error) error {
+ return &Err{Operation: op, Message: msg, Cause: err}
+}
+
+// Wrap wraps an error with operation context.
+// Returns nil if err is nil, to support conditional wrapping.
+// Preserves error Code if the wrapped error is an *Err.
+//
+// Example:
+//
+// return log.Wrap(err, "db.Query", "database query failed")
+func Wrap(err error, op, msg string) error {
+ if err == nil {
+ return nil
+ }
+ // Preserve Code from wrapped *Err
+ var logErr *Err
+ if As(err, &logErr) && logErr.Code != "" {
+ return &Err{Operation: op, Message: msg, Cause: err, Code: logErr.Code}
+ }
+ return &Err{Operation: op, Message: msg, Cause: err}
+}
+
+// WrapCode wraps an error with operation context and error code.
+// Returns nil only if both err is nil AND code is empty.
+// Useful for API errors that need machine-readable codes.
+//
+// Example:
+//
+// return log.WrapCode(err, "VALIDATION_ERROR", "user.Validate", "invalid email")
+func WrapCode(err error, code, op, msg string) error {
+ if err == nil && code == "" {
+ return nil
+ }
+ return &Err{Operation: op, Message: msg, Cause: err, Code: code}
+}
+
+// NewCode creates an error with just code and message (no underlying error).
+// Useful for creating sentinel errors with codes.
+//
+// Example:
+//
+// var ErrNotFound = log.NewCode("NOT_FOUND", "resource not found")
+func NewCode(code, msg string) error {
+ return &Err{Message: msg, Code: code}
+}
+
+// --- Standard Library Wrappers ---
+
+// Is reports whether any error in err's tree matches target.
+// Wrapper around errors.Is for convenience.
+func Is(err, target error) bool {
+ return errors.Is(err, target)
+}
+
+// As finds the first error in err's tree that matches target.
+// Wrapper around errors.As for convenience.
+func As(err error, target any) bool {
+ return errors.As(err, target)
+}
+
+// NewError creates a simple error with the given text.
+// Wrapper around errors.New for convenience.
+func NewError(text string) error {
+ return errors.New(text)
+}
+
+// ErrorJoin combines multiple errors into one.
+//
+// core.ErrorJoin(err1, err2, err3)
+func ErrorJoin(errs ...error) error {
+ return errors.Join(errs...)
+}
+
+// --- Error Introspection Helpers ---
+
+// Operation extracts the operation name from an error.
+// Returns empty string if the error is not an *Err.
+func Operation(err error) string {
+ var e *Err
+ if As(err, &e) {
+ return e.Operation
+ }
+ return ""
+}
+
+// ErrorCode extracts the error code from an error.
+// Returns empty string if the error is not an *Err or has no code.
+func ErrorCode(err error) string {
+ var e *Err
+ if As(err, &e) {
+ return e.Code
+ }
+ return ""
+}
+
+// Message extracts the message from an error.
+// Returns the error's Error() string if not an *Err.
+func ErrorMessage(err error) string {
+ if err == nil {
+ return ""
+ }
+ var e *Err
+ if As(err, &e) {
+ return e.Message
+ }
+ return err.Error()
+}
+
+// Root returns the root cause of an error chain.
+// Unwraps until no more wrapped errors are found.
+func Root(err error) error {
+ if err == nil {
+ return nil
+ }
+ for {
+ unwrapped := errors.Unwrap(err)
+ if unwrapped == nil {
+ return err
+ }
+ err = unwrapped
+ }
+}
+
+// AllOperations returns an iterator over all operational contexts in the error chain.
+// It traverses the error tree using errors.Unwrap.
+func AllOperations(err error) iter.Seq[string] {
+ return func(yield func(string) bool) {
+ for err != nil {
+ if e, ok := err.(*Err); ok {
+ if e.Operation != "" {
+ if !yield(e.Operation) {
+ return
+ }
+ }
+ }
+ err = errors.Unwrap(err)
+ }
+ }
+}
+
+// StackTrace returns the logical stack trace (chain of operations) from an error.
+// It returns an empty slice if no operational context is found.
+func StackTrace(err error) []string {
+ var stack []string
+ for op := range AllOperations(err) {
+ stack = append(stack, op)
+ }
+ return stack
+}
+
+// FormatStackTrace returns a pretty-printed logical stack trace.
+func FormatStackTrace(err error) string {
+ var ops []string
+ for op := range AllOperations(err) {
+ ops = append(ops, op)
+ }
+ if len(ops) == 0 {
+ return ""
+ }
+ return Join(" -> ", ops...)
+}
+
+// --- ErrorLog: Log-and-Return Error Helpers ---
+
+// ErrorLog combines error creation with logging.
+// Primary action: return an error. Secondary: log it.
+type ErrorLog struct {
+ log *Log
+}
+
+func (el *ErrorLog) logger() *Log {
+ if el.log != nil {
+ return el.log
+ }
+ return Default()
+}
+
+// Error logs at Error level and returns a Result with the wrapped error.
+func (el *ErrorLog) Error(err error, op, msg string) Result {
+ if err == nil {
+ return Result{OK: true}
+ }
+ wrapped := Wrap(err, op, msg)
+ el.logger().Error(msg, "op", op, "err", err)
+ return Result{wrapped, false}
+}
+
+// Warn logs at Warn level and returns a Result with the wrapped error.
+func (el *ErrorLog) Warn(err error, op, msg string) Result {
+ if err == nil {
+ return Result{OK: true}
+ }
+ wrapped := Wrap(err, op, msg)
+ el.logger().Warn(msg, "op", op, "err", err)
+ return Result{wrapped, false}
+}
+
+// Must logs and panics if err is not nil.
+func (el *ErrorLog) Must(err error, op, msg string) {
+ if err != nil {
+ el.logger().Error(msg, "op", op, "err", err)
+ panic(Wrap(err, op, msg))
+ }
+}
+
+// --- Crash Recovery & Reporting ---
+
+// CrashReport represents a single crash event.
+type CrashReport struct {
+ Timestamp time.Time `json:"timestamp"`
+ Error string `json:"error"`
+ Stack string `json:"stack"`
+ System CrashSystem `json:"system,omitempty"`
+ Meta map[string]string `json:"meta,omitempty"`
+}
+
+// CrashSystem holds system information at crash time.
+type CrashSystem struct {
+ OperatingSystem string `json:"operatingsystem"`
+ Architecture string `json:"architecture"`
+ Version string `json:"go_version"`
+}
+
+// ErrorPanic manages panic recovery and crash reporting.
+type ErrorPanic struct {
+ filePath string
+ meta map[string]string
+ onCrash func(CrashReport)
+}
+
+// Recover captures a panic and creates a crash report.
+// Use as: defer c.Error().Recover()
+func (h *ErrorPanic) Recover() {
+ if h == nil {
+ return
+ }
+ r := recover()
+ if r == nil {
+ return
+ }
+
+ err, ok := r.(error)
+ if !ok {
+ err = NewError(Sprint("panic: ", r))
+ }
+
+ report := CrashReport{
+ Timestamp: time.Now(),
+ Error: err.Error(),
+ Stack: string(debug.Stack()),
+ System: CrashSystem{
+ OperatingSystem: runtime.GOOS,
+ Architecture: runtime.GOARCH,
+ Version: runtime.Version(),
+ },
+ Meta: maps.Clone(h.meta),
+ }
+
+ if h.onCrash != nil {
+ h.onCrash(report)
+ }
+
+ if h.filePath != "" {
+ h.appendReport(report)
+ }
+}
+
+// SafeGo runs a function in a goroutine with panic recovery.
+func (h *ErrorPanic) SafeGo(fn func()) {
+ go func() {
+ defer h.Recover()
+ fn()
+ }()
+}
+
+// Reports returns the last n crash reports from the file.
+func (h *ErrorPanic) Reports(n int) Result {
+ if h.filePath == "" {
+ return Result{}
+ }
+ crashMu.Lock()
+ defer crashMu.Unlock()
+ data, err := os.ReadFile(h.filePath)
+ if err != nil {
+ return Result{err, false}
+ }
+ var reports []CrashReport
+ if err := json.Unmarshal(data, &reports); err != nil {
+ return Result{err, false}
+ }
+ if n <= 0 || len(reports) <= n {
+ return Result{reports, true}
+ }
+ return Result{reports[len(reports)-n:], true}
+}
+
+var crashMu sync.Mutex
+
+func (h *ErrorPanic) appendReport(report CrashReport) {
+ crashMu.Lock()
+ defer crashMu.Unlock()
+
+ var reports []CrashReport
+ if data, err := os.ReadFile(h.filePath); err == nil {
+ if err := json.Unmarshal(data, &reports); err != nil {
+ reports = nil
+ }
+ }
+
+ reports = append(reports, report)
+ data, err := json.MarshalIndent(reports, "", " ")
+ if err != nil {
+ Default().Error(Concat("crash report marshal failed: ", err.Error()))
+ return
+ }
+ if err := os.MkdirAll(filepath.Dir(h.filePath), 0755); err != nil {
+ Default().Error(Concat("crash report dir failed: ", err.Error()))
+ return
+ }
+ if err := os.WriteFile(h.filePath, data, 0600); err != nil {
+ Default().Error(Concat("crash report write failed: ", err.Error()))
+ }
+}
diff --git a/.core/reference/fs.go b/.core/reference/fs.go
new file mode 100644
index 0000000..a18a3d2
--- /dev/null
+++ b/.core/reference/fs.go
@@ -0,0 +1,423 @@
+// Sandboxed local filesystem I/O for the Core framework.
+package core
+
+import (
+ "io"
+ "io/fs"
+ "os"
+ "os/user"
+ "path/filepath"
+ "time"
+)
+
+// Fs is a sandboxed local filesystem backend.
+type Fs struct {
+ root string
+}
+
+// New initialises an Fs with the given root directory.
+// Root "/" means unrestricted access. Empty root defaults to "/".
+//
+// fs := (&core.Fs{}).New("/")
+func (m *Fs) New(root string) *Fs {
+ if root == "" {
+ root = "/"
+ }
+ m.root = root
+ return m
+}
+
+// NewUnrestricted returns a new Fs with root "/", granting full filesystem access.
+// Use this instead of unsafe.Pointer to bypass the sandbox.
+//
+// fs := c.Fs().NewUnrestricted()
+// fs.Read("/etc/hostname") // works — no sandbox
+func (m *Fs) NewUnrestricted() *Fs {
+ return (&Fs{}).New("/")
+}
+
+// Root returns the sandbox root path.
+//
+// root := c.Fs().Root() // e.g. "/home/agent/.core"
+func (m *Fs) Root() string {
+ if m.root == "" {
+ return "/"
+ }
+ return m.root
+}
+
+// path sanitises and returns the full path.
+// Absolute paths are sandboxed under root (unless root is "/").
+// Empty root defaults to "/" — the zero value of Fs is usable.
+func (m *Fs) path(p string) string {
+ root := m.root
+ if root == "" {
+ root = "/"
+ }
+ if p == "" {
+ return root
+ }
+
+ // If the path is relative and the medium is rooted at "/",
+ // treat it as relative to the current working directory.
+ // This makes io.Local behave more like the standard 'os' package.
+ if root == "/" && !filepath.IsAbs(p) {
+ cwd, _ := os.Getwd()
+ return filepath.Join(cwd, p)
+ }
+
+ // Use filepath.Clean with a leading slash to resolve all .. and . internally
+ // before joining with the root. This is a standard way to sandbox paths.
+ clean := filepath.Clean("/" + p)
+
+ // If root is "/", allow absolute paths through
+ if root == "/" {
+ return clean
+ }
+
+ // Strip leading "/" so Join works correctly with root
+ return filepath.Join(root, clean[1:])
+}
+
+// validatePath ensures the path is within the sandbox, following symlinks if they exist.
+func (m *Fs) validatePath(p string) Result {
+ root := m.root
+ if root == "" {
+ root = "/"
+ }
+ if root == "/" {
+ return Result{m.path(p), true}
+ }
+
+ // Split the cleaned path into components
+ parts := Split(filepath.Clean("/"+p), string(os.PathSeparator))
+ current := root
+
+ for _, part := range parts {
+ if part == "" {
+ continue
+ }
+
+ next := filepath.Join(current, part)
+ realNext, err := filepath.EvalSymlinks(next)
+ if err != nil {
+ if os.IsNotExist(err) {
+ // Part doesn't exist, we can't follow symlinks anymore.
+ // Since the path is already Cleaned and current is safe,
+ // appending a component to current will not escape.
+ current = next
+ continue
+ }
+ return Result{err, false}
+ }
+
+ // Verify the resolved part is still within the root
+ rel, err := filepath.Rel(root, realNext)
+ if err != nil || HasPrefix(rel, "..") {
+ // Security event: sandbox escape attempt
+ username := "unknown"
+ if u, err := user.Current(); err == nil {
+ username = u.Username
+ }
+ Print(os.Stderr, "[%s] SECURITY sandbox escape detected root=%s path=%s attempted=%s user=%s",
+ time.Now().Format(time.RFC3339), root, p, realNext, username)
+ if err == nil {
+ err = E("fs.validatePath", Concat("sandbox escape: ", p, " resolves outside ", m.root), nil)
+ }
+ return Result{err, false}
+ }
+ current = realNext
+ }
+
+ return Result{current, true}
+}
+
+// Read returns file contents as string.
+func (m *Fs) Read(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ data, err := os.ReadFile(vp.Value.(string))
+ if err != nil {
+ return Result{err, false}
+ }
+ return Result{string(data), true}
+}
+
+// Write saves content to file, creating parent directories as needed.
+// Files are created with mode 0644. For sensitive files (keys, secrets),
+// use WriteMode with 0600.
+func (m *Fs) Write(p, content string) Result {
+ return m.WriteMode(p, content, 0644)
+}
+
+// WriteMode saves content to file with explicit permissions.
+// Use 0600 for sensitive files (encryption output, private keys, auth hashes).
+func (m *Fs) WriteMode(p, content string, mode os.FileMode) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ full := vp.Value.(string)
+ if err := os.MkdirAll(filepath.Dir(full), 0755); err != nil {
+ return Result{err, false}
+ }
+ if err := os.WriteFile(full, []byte(content), mode); err != nil {
+ return Result{err, false}
+ }
+ return Result{OK: true}
+}
+
+// TempDir creates a temporary directory and returns its path.
+// The caller is responsible for cleanup via fs.DeleteAll().
+//
+// dir := fs.TempDir("agent-workspace")
+// defer fs.DeleteAll(dir)
+func (m *Fs) TempDir(prefix string) string {
+ dir, err := os.MkdirTemp("", prefix)
+ if err != nil {
+ return ""
+ }
+ return dir
+}
+
+// DirFS returns an fs.FS rooted at the given directory path.
+//
+// fsys := core.DirFS("/path/to/templates")
+func DirFS(dir string) fs.FS {
+ return os.DirFS(dir)
+}
+
+// WriteAtomic writes content by writing to a temp file then renaming.
+// Rename is atomic on POSIX — concurrent readers never see a partial file.
+// Use this for status files, config, or any file read from multiple goroutines.
+//
+// r := fs.WriteAtomic("/status.json", jsonData)
+func (m *Fs) WriteAtomic(p, content string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ full := vp.Value.(string)
+ if err := os.MkdirAll(filepath.Dir(full), 0755); err != nil {
+ return Result{err, false}
+ }
+
+ tmp := full + ".tmp." + shortRand()
+ if err := os.WriteFile(tmp, []byte(content), 0644); err != nil {
+ return Result{err, false}
+ }
+ if err := os.Rename(tmp, full); err != nil {
+ os.Remove(tmp)
+ return Result{err, false}
+ }
+ return Result{OK: true}
+}
+
+// EnsureDir creates directory if it doesn't exist.
+func (m *Fs) EnsureDir(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ if err := os.MkdirAll(vp.Value.(string), 0755); err != nil {
+ return Result{err, false}
+ }
+ return Result{OK: true}
+}
+
+// IsDir returns true if path is a directory.
+func (m *Fs) IsDir(p string) bool {
+ if p == "" {
+ return false
+ }
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return false
+ }
+ info, err := os.Stat(vp.Value.(string))
+ return err == nil && info.IsDir()
+}
+
+// IsFile returns true if path is a regular file.
+func (m *Fs) IsFile(p string) bool {
+ if p == "" {
+ return false
+ }
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return false
+ }
+ info, err := os.Stat(vp.Value.(string))
+ return err == nil && info.Mode().IsRegular()
+}
+
+// Exists returns true if path exists.
+func (m *Fs) Exists(p string) bool {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return false
+ }
+ _, err := os.Stat(vp.Value.(string))
+ return err == nil
+}
+
+// List returns directory entries.
+func (m *Fs) List(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ return Result{}.New(os.ReadDir(vp.Value.(string)))
+}
+
+// Stat returns file info.
+func (m *Fs) Stat(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ return Result{}.New(os.Stat(vp.Value.(string)))
+}
+
+// Open opens the named file for reading.
+func (m *Fs) Open(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ return Result{}.New(os.Open(vp.Value.(string)))
+}
+
+// Create creates or truncates the named file.
+func (m *Fs) Create(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ full := vp.Value.(string)
+ if err := os.MkdirAll(filepath.Dir(full), 0755); err != nil {
+ return Result{err, false}
+ }
+ return Result{}.New(os.Create(full))
+}
+
+// Append opens the named file for appending, creating it if it doesn't exist.
+func (m *Fs) Append(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ full := vp.Value.(string)
+ if err := os.MkdirAll(filepath.Dir(full), 0755); err != nil {
+ return Result{err, false}
+ }
+ return Result{}.New(os.OpenFile(full, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644))
+}
+
+// ReadStream returns a reader for the file content.
+func (m *Fs) ReadStream(path string) Result {
+ return m.Open(path)
+}
+
+// WriteStream returns a writer for the file content.
+func (m *Fs) WriteStream(path string) Result {
+ return m.Create(path)
+}
+
+// ReadAll reads all bytes from a ReadCloser and closes it.
+// Wraps io.ReadAll so consumers don't import "io".
+//
+// r := fs.ReadStream(path)
+// data := core.ReadAll(r.Value)
+func ReadAll(reader any) Result {
+ rc, ok := reader.(io.Reader)
+ if !ok {
+ return Result{E("core.ReadAll", "not a reader", nil), false}
+ }
+ data, err := io.ReadAll(rc)
+ if closer, ok := reader.(io.Closer); ok {
+ closer.Close()
+ }
+ if err != nil {
+ return Result{err, false}
+ }
+ return Result{string(data), true}
+}
+
+// WriteAll writes content to a writer and closes it if it implements Closer.
+//
+// r := fs.WriteStream(path)
+// core.WriteAll(r.Value, "content")
+func WriteAll(writer any, content string) Result {
+ wc, ok := writer.(io.Writer)
+ if !ok {
+ return Result{E("core.WriteAll", "not a writer", nil), false}
+ }
+ _, err := wc.Write([]byte(content))
+ if closer, ok := writer.(io.Closer); ok {
+ closer.Close()
+ }
+ if err != nil {
+ return Result{err, false}
+ }
+ return Result{OK: true}
+}
+
+// CloseStream closes any value that implements io.Closer.
+//
+// core.CloseStream(r.Value)
+func CloseStream(v any) {
+ if closer, ok := v.(io.Closer); ok {
+ closer.Close()
+ }
+}
+
+// Delete removes a file or empty directory.
+func (m *Fs) Delete(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ full := vp.Value.(string)
+ if full == "/" || full == os.Getenv("HOME") {
+ return Result{E("fs.Delete", Concat("refusing to delete protected path: ", full), nil), false}
+ }
+ if err := os.Remove(full); err != nil {
+ return Result{err, false}
+ }
+ return Result{OK: true}
+}
+
+// DeleteAll removes a file or directory recursively.
+func (m *Fs) DeleteAll(p string) Result {
+ vp := m.validatePath(p)
+ if !vp.OK {
+ return vp
+ }
+ full := vp.Value.(string)
+ if full == "/" || full == os.Getenv("HOME") {
+ return Result{E("fs.DeleteAll", Concat("refusing to delete protected path: ", full), nil), false}
+ }
+ if err := os.RemoveAll(full); err != nil {
+ return Result{err, false}
+ }
+ return Result{OK: true}
+}
+
+// Rename moves a file or directory.
+func (m *Fs) Rename(oldPath, newPath string) Result {
+ oldVp := m.validatePath(oldPath)
+ if !oldVp.OK {
+ return oldVp
+ }
+ newVp := m.validatePath(newPath)
+ if !newVp.OK {
+ return newVp
+ }
+ if err := os.Rename(oldVp.Value.(string), newVp.Value.(string)); err != nil {
+ return Result{err, false}
+ }
+ return Result{OK: true}
+}
diff --git a/.core/reference/i18n.go b/.core/reference/i18n.go
new file mode 100644
index 0000000..7061ce8
--- /dev/null
+++ b/.core/reference/i18n.go
@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Internationalisation for the Core framework.
+// I18n collects locale mounts from services and delegates
+// translation to a registered Translator implementation (e.g., go-i18n).
+
+package core
+
+import (
+ "sync"
+)
+
+// Translator defines the interface for translation services.
+// Implemented by go-i18n's Srv.
+type Translator interface {
+ // Translate translates a message by its ID with optional arguments.
+ Translate(messageID string, args ...any) Result
+ // SetLanguage sets the active language (BCP47 tag, e.g., "en-GB", "de").
+ SetLanguage(lang string) error
+ // Language returns the current language code.
+ Language() string
+ // AvailableLanguages returns all loaded language codes.
+ AvailableLanguages() []string
+}
+
+// LocaleProvider is implemented by services that ship their own translation files.
+// Core discovers this interface during service registration and collects the
+// locale mounts. The i18n service loads them during startup.
+//
+// Usage in a service package:
+//
+// //go:embed locales
+// var localeFS embed.FS
+//
+// func (s *MyService) Locales() *Embed {
+// m, _ := Mount(localeFS, "locales")
+// return m
+// }
+type LocaleProvider interface {
+ Locales() *Embed
+}
+
+// I18n manages locale collection and translation dispatch.
+type I18n struct {
+ mu sync.RWMutex
+ locales []*Embed // collected from LocaleProvider services
+ locale string
+ translator Translator // registered implementation (nil until set)
+}
+
+// AddLocales adds locale mounts (called during service registration).
+func (i *I18n) AddLocales(mounts ...*Embed) {
+ i.mu.Lock()
+ i.locales = append(i.locales, mounts...)
+ i.mu.Unlock()
+}
+
+// Locales returns all collected locale mounts.
+func (i *I18n) Locales() Result {
+ i.mu.RLock()
+ out := make([]*Embed, len(i.locales))
+ copy(out, i.locales)
+ i.mu.RUnlock()
+ return Result{out, true}
+}
+
+// SetTranslator registers the translation implementation.
+// Called by go-i18n's Srv during startup.
+func (i *I18n) SetTranslator(t Translator) {
+ i.mu.Lock()
+ i.translator = t
+ locale := i.locale
+ i.mu.Unlock()
+ if t != nil && locale != "" {
+ _ = t.SetLanguage(locale)
+ }
+}
+
+// Translator returns the registered translation implementation, or nil.
+func (i *I18n) Translator() Result {
+ i.mu.RLock()
+ t := i.translator
+ i.mu.RUnlock()
+ if t == nil {
+ return Result{}
+ }
+ return Result{t, true}
+}
+
+// Translate translates a message. Returns the key as-is if no translator is registered.
+func (i *I18n) Translate(messageID string, args ...any) Result {
+ i.mu.RLock()
+ t := i.translator
+ i.mu.RUnlock()
+ if t != nil {
+ return t.Translate(messageID, args...)
+ }
+ return Result{messageID, true}
+}
+
+// SetLanguage sets the active language and forwards to the translator if registered.
+func (i *I18n) SetLanguage(lang string) Result {
+ if lang == "" {
+ return Result{OK: true}
+ }
+ i.mu.Lock()
+ i.locale = lang
+ t := i.translator
+ i.mu.Unlock()
+ if t != nil {
+ if err := t.SetLanguage(lang); err != nil {
+ return Result{err, false}
+ }
+ }
+ return Result{OK: true}
+}
+
+// Language returns the current language code, or "en" if not set.
+func (i *I18n) Language() string {
+ i.mu.RLock()
+ locale := i.locale
+ i.mu.RUnlock()
+ if locale != "" {
+ return locale
+ }
+ return "en"
+}
+
+// AvailableLanguages returns all loaded language codes.
+func (i *I18n) AvailableLanguages() []string {
+ i.mu.RLock()
+ t := i.translator
+ i.mu.RUnlock()
+ if t != nil {
+ return t.AvailableLanguages()
+ }
+ return []string{"en"}
+}
diff --git a/.core/reference/ipc.go b/.core/reference/ipc.go
new file mode 100644
index 0000000..bedbd65
--- /dev/null
+++ b/.core/reference/ipc.go
@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Message bus for the Core framework.
+// Dispatches actions (fire-and-forget), queries (first responder),
+// and tasks (first executor) between registered handlers.
+
+package core
+
+import (
+ "slices"
+ "sync"
+)
+
+// Ipc holds IPC dispatch data and the named action registry.
+//
+// ipc := (&core.Ipc{}).New()
+type Ipc struct {
+ ipcMu sync.RWMutex
+ ipcHandlers []func(*Core, Message) Result
+
+ queryMu sync.RWMutex
+ queryHandlers []QueryHandler
+
+ actions *Registry[*Action] // named action registry
+ tasks *Registry[*Task] // named task registry
+}
+
+// broadcast dispatches a message to all registered IPC handlers.
+// Each handler is wrapped in panic recovery. All handlers fire regardless of individual results.
+func (c *Core) broadcast(msg Message) Result {
+ c.ipc.ipcMu.RLock()
+ handlers := slices.Clone(c.ipc.ipcHandlers)
+ c.ipc.ipcMu.RUnlock()
+
+ for _, h := range handlers {
+ func() {
+ defer func() {
+ if r := recover(); r != nil {
+ Error("ACTION handler panicked", "panic", r)
+ }
+ }()
+ h(c, msg)
+ }()
+ }
+ return Result{OK: true}
+}
+
+// Query dispatches a request — first handler to return OK wins.
+//
+// r := c.Query(MyQuery{})
+func (c *Core) Query(q Query) Result {
+ c.ipc.queryMu.RLock()
+ handlers := slices.Clone(c.ipc.queryHandlers)
+ c.ipc.queryMu.RUnlock()
+
+ for _, h := range handlers {
+ r := h(c, q)
+ if r.OK {
+ return r
+ }
+ }
+ return Result{}
+}
+
+// QueryAll dispatches a request — collects all OK responses.
+//
+// r := c.QueryAll(countQuery{})
+// results := r.Value.([]any)
+func (c *Core) QueryAll(q Query) Result {
+ c.ipc.queryMu.RLock()
+ handlers := slices.Clone(c.ipc.queryHandlers)
+ c.ipc.queryMu.RUnlock()
+
+ var results []any
+ for _, h := range handlers {
+ r := h(c, q)
+ if r.OK && r.Value != nil {
+ results = append(results, r.Value)
+ }
+ }
+ return Result{results, true}
+}
+
+// RegisterQuery registers a handler for QUERY dispatch.
+//
+// c.RegisterQuery(func(_ *core.Core, q core.Query) core.Result { ... })
+func (c *Core) RegisterQuery(handler QueryHandler) {
+ c.ipc.queryMu.Lock()
+ c.ipc.queryHandlers = append(c.ipc.queryHandlers, handler)
+ c.ipc.queryMu.Unlock()
+}
+
+// --- IPC Registration (handlers) ---
+
+// RegisterAction registers a broadcast handler for ACTION messages.
+//
+// c.RegisterAction(func(c *core.Core, msg core.Message) core.Result {
+// if ev, ok := msg.(AgentCompleted); ok { ... }
+// return core.Result{OK: true}
+// })
+func (c *Core) RegisterAction(handler func(*Core, Message) Result) {
+ c.ipc.ipcMu.Lock()
+ c.ipc.ipcHandlers = append(c.ipc.ipcHandlers, handler)
+ c.ipc.ipcMu.Unlock()
+}
+
+// RegisterActions registers multiple broadcast handlers.
+func (c *Core) RegisterActions(handlers ...func(*Core, Message) Result) {
+ c.ipc.ipcMu.Lock()
+ c.ipc.ipcHandlers = append(c.ipc.ipcHandlers, handlers...)
+ c.ipc.ipcMu.Unlock()
+}
+
diff --git a/.core/reference/lock.go b/.core/reference/lock.go
new file mode 100644
index 0000000..a963278
--- /dev/null
+++ b/.core/reference/lock.go
@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Synchronisation, locking, and lifecycle snapshots for the Core framework.
+
+package core
+
+import (
+ "sync"
+)
+
+// Lock is the DTO for a named mutex.
+type Lock struct {
+ Name string
+ Mutex *sync.RWMutex
+ locks *Registry[*sync.RWMutex] // per-Core named mutexes
+}
+
+// Lock returns a named Lock, creating the mutex if needed.
+// Locks are per-Core — separate Core instances do not share mutexes.
+func (c *Core) Lock(name string) *Lock {
+ r := c.lock.locks.Get(name)
+ if r.OK {
+ return &Lock{Name: name, Mutex: r.Value.(*sync.RWMutex)}
+ }
+ m := &sync.RWMutex{}
+ c.lock.locks.Set(name, m)
+ return &Lock{Name: name, Mutex: m}
+}
+
+// LockEnable marks that the service lock should be applied after initialisation.
+func (c *Core) LockEnable(name ...string) {
+ c.services.lockEnabled = true
+}
+
+// LockApply activates the service lock if it was enabled.
+func (c *Core) LockApply(name ...string) {
+ if c.services.lockEnabled {
+ c.services.Lock()
+ }
+}
+
+// Startables returns services that have an OnStart function, in registration order.
+func (c *Core) Startables() Result {
+ if c.services == nil {
+ return Result{}
+ }
+ var out []*Service
+ c.services.Each(func(_ string, svc *Service) {
+ if svc.OnStart != nil {
+ out = append(out, svc)
+ }
+ })
+ return Result{out, true}
+}
+
+// Stoppables returns services that have an OnStop function, in registration order.
+func (c *Core) Stoppables() Result {
+ if c.services == nil {
+ return Result{}
+ }
+ var out []*Service
+ c.services.Each(func(_ string, svc *Service) {
+ if svc.OnStop != nil {
+ out = append(out, svc)
+ }
+ })
+ return Result{out, true}
+}
diff --git a/.core/reference/log.go b/.core/reference/log.go
new file mode 100644
index 0000000..65f8c5f
--- /dev/null
+++ b/.core/reference/log.go
@@ -0,0 +1,402 @@
+// Structured logging for the Core framework.
+//
+// core.SetLevel(core.LevelDebug)
+// core.Info("server started", "port", 8080)
+// core.Error("failed to connect", "err", err)
+package core
+
+import (
+ goio "io"
+ "os"
+ "os/user"
+ "slices"
+ "sync"
+ "sync/atomic"
+ "time"
+)
+
+// Level defines logging verbosity.
+type Level int
+
+// Logging level constants ordered by increasing verbosity.
+const (
+ // LevelQuiet suppresses all log output.
+ LevelQuiet Level = iota
+ // LevelError shows only error messages.
+ LevelError
+ // LevelWarn shows warnings and errors.
+ LevelWarn
+ // LevelInfo shows informational messages, warnings, and errors.
+ LevelInfo
+ // LevelDebug shows all messages including debug details.
+ LevelDebug
+)
+
+// String returns the level name.
+func (l Level) String() string {
+ switch l {
+ case LevelQuiet:
+ return "quiet"
+ case LevelError:
+ return "error"
+ case LevelWarn:
+ return "warn"
+ case LevelInfo:
+ return "info"
+ case LevelDebug:
+ return "debug"
+ default:
+ return "unknown"
+ }
+}
+
+// Log provides structured logging.
+type Log struct {
+ mu sync.RWMutex
+ level Level
+ output goio.Writer
+
+ // RedactKeys is a list of keys whose values should be masked in logs.
+ redactKeys []string
+
+ // Style functions for formatting (can be overridden)
+ StyleTimestamp func(string) string
+ StyleDebug func(string) string
+ StyleInfo func(string) string
+ StyleWarn func(string) string
+ StyleError func(string) string
+ StyleSecurity func(string) string
+}
+
+// RotationLogOptions defines the log rotation and retention policy.
+type RotationLogOptions struct {
+ // Filename is the log file path. If empty, rotation is disabled.
+ Filename string
+
+ // MaxSize is the maximum size of the log file in megabytes before it gets rotated.
+ // It defaults to 100 megabytes.
+ MaxSize int
+
+ // MaxAge is the maximum number of days to retain old log files based on their
+ // file modification time. It defaults to 28 days.
+ // Note: set to a negative value to disable age-based retention.
+ MaxAge int
+
+ // MaxBackups is the maximum number of old log files to retain.
+ // It defaults to 5 backups.
+ MaxBackups int
+
+ // Compress determines if the rotated log files should be compressed using gzip.
+ // It defaults to true.
+ Compress bool
+}
+
+// LogOptions configures a Log.
+type LogOptions struct {
+ Level Level
+ // Output is the destination for log messages. If Rotation is provided,
+ // Output is ignored and logs are written to the rotating file instead.
+ Output goio.Writer
+ // Rotation enables log rotation to file. If provided, Filename must be set.
+ Rotation *RotationLogOptions
+ // RedactKeys is a list of keys whose values should be masked in logs.
+ RedactKeys []string
+}
+
+// RotationWriterFactory creates a rotating writer from options.
+// Set this to enable log rotation (provided by core/go-io integration).
+var RotationWriterFactory func(RotationLogOptions) goio.WriteCloser
+
+// New creates a new Log with the given options.
+func NewLog(opts LogOptions) *Log {
+ output := opts.Output
+ if opts.Rotation != nil && opts.Rotation.Filename != "" && RotationWriterFactory != nil {
+ output = RotationWriterFactory(*opts.Rotation)
+ }
+ if output == nil {
+ output = os.Stderr
+ }
+
+ return &Log{
+ level: opts.Level,
+ output: output,
+ redactKeys: slices.Clone(opts.RedactKeys),
+ StyleTimestamp: identity,
+ StyleDebug: identity,
+ StyleInfo: identity,
+ StyleWarn: identity,
+ StyleError: identity,
+ StyleSecurity: identity,
+ }
+}
+
+func identity(s string) string { return s }
+
+// SetLevel changes the log level.
+func (l *Log) SetLevel(level Level) {
+ l.mu.Lock()
+ l.level = level
+ l.mu.Unlock()
+}
+
+// Level returns the current log level.
+func (l *Log) Level() Level {
+ l.mu.RLock()
+ defer l.mu.RUnlock()
+ return l.level
+}
+
+// SetOutput changes the output writer.
+func (l *Log) SetOutput(w goio.Writer) {
+ l.mu.Lock()
+ l.output = w
+ l.mu.Unlock()
+}
+
+// SetRedactKeys sets the keys to be redacted.
+func (l *Log) SetRedactKeys(keys ...string) {
+ l.mu.Lock()
+ l.redactKeys = slices.Clone(keys)
+ l.mu.Unlock()
+}
+
+func (l *Log) shouldLog(level Level) bool {
+ l.mu.RLock()
+ defer l.mu.RUnlock()
+ return level <= l.level
+}
+
+func (l *Log) log(level Level, prefix, msg string, keyvals ...any) {
+ l.mu.RLock()
+ output := l.output
+ styleTimestamp := l.StyleTimestamp
+ redactKeys := l.redactKeys
+ l.mu.RUnlock()
+
+ timestamp := styleTimestamp(time.Now().Format("15:04:05"))
+
+ // Copy keyvals to avoid mutating the caller's slice
+ keyvals = append([]any(nil), keyvals...)
+
+ // Automatically extract context from error if present in keyvals
+ origLen := len(keyvals)
+ for i := 0; i < origLen; i += 2 {
+ if i+1 < origLen {
+ if err, ok := keyvals[i+1].(error); ok {
+ if op := Operation(err); op != "" {
+ // Check if op is already in keyvals
+ hasOp := false
+ for j := 0; j < len(keyvals); j += 2 {
+ if k, ok := keyvals[j].(string); ok && k == "op" {
+ hasOp = true
+ break
+ }
+ }
+ if !hasOp {
+ keyvals = append(keyvals, "op", op)
+ }
+ }
+ if stack := FormatStackTrace(err); stack != "" {
+ // Check if stack is already in keyvals
+ hasStack := false
+ for j := 0; j < len(keyvals); j += 2 {
+ if k, ok := keyvals[j].(string); ok && k == "stack" {
+ hasStack = true
+ break
+ }
+ }
+ if !hasStack {
+ keyvals = append(keyvals, "stack", stack)
+ }
+ }
+ }
+ }
+ }
+
+ // Format key-value pairs
+ var kvStr string
+ if len(keyvals) > 0 {
+ kvStr = " "
+ for i := 0; i < len(keyvals); i += 2 {
+ if i > 0 {
+ kvStr += " "
+ }
+ key := keyvals[i]
+ var val any
+ if i+1 < len(keyvals) {
+ val = keyvals[i+1]
+ }
+
+ // Redaction logic
+ keyStr := Sprint(key)
+ if slices.Contains(redactKeys, keyStr) {
+ val = "[REDACTED]"
+ }
+
+ // Secure formatting to prevent log injection
+ if s, ok := val.(string); ok {
+ kvStr += Sprintf("%v=%q", key, s)
+ } else {
+ kvStr += Sprintf("%v=%v", key, val)
+ }
+ }
+ }
+
+ Print(output, "%s %s %s%s", timestamp, prefix, msg, kvStr)
+}
+
+// Debug logs a debug message with optional key-value pairs.
+func (l *Log) Debug(msg string, keyvals ...any) {
+ if l.shouldLog(LevelDebug) {
+ l.log(LevelDebug, l.StyleDebug("[DBG]"), msg, keyvals...)
+ }
+}
+
+// Info logs an info message with optional key-value pairs.
+func (l *Log) Info(msg string, keyvals ...any) {
+ if l.shouldLog(LevelInfo) {
+ l.log(LevelInfo, l.StyleInfo("[INF]"), msg, keyvals...)
+ }
+}
+
+// Warn logs a warning message with optional key-value pairs.
+func (l *Log) Warn(msg string, keyvals ...any) {
+ if l.shouldLog(LevelWarn) {
+ l.log(LevelWarn, l.StyleWarn("[WRN]"), msg, keyvals...)
+ }
+}
+
+// Error logs an error message with optional key-value pairs.
+func (l *Log) Error(msg string, keyvals ...any) {
+ if l.shouldLog(LevelError) {
+ l.log(LevelError, l.StyleError("[ERR]"), msg, keyvals...)
+ }
+}
+
+// Security logs a security event with optional key-value pairs.
+// It uses LevelError to ensure security events are visible even in restrictive
+// log configurations.
+func (l *Log) Security(msg string, keyvals ...any) {
+ if l.shouldLog(LevelError) {
+ l.log(LevelError, l.StyleSecurity("[SEC]"), msg, keyvals...)
+ }
+}
+
+// Username returns the current system username.
+// It uses os/user for reliability and falls back to environment variables.
+func Username() string {
+ if u, err := user.Current(); err == nil {
+ return u.Username
+ }
+ // Fallback for environments where user lookup might fail
+ if u := os.Getenv("USER"); u != "" {
+ return u
+ }
+ return os.Getenv("USERNAME")
+}
+
+// --- Default logger ---
+
+var defaultLogPtr atomic.Pointer[Log]
+
+func init() {
+ l := NewLog(LogOptions{Level: LevelInfo})
+ defaultLogPtr.Store(l)
+}
+
+// Default returns the default logger.
+func Default() *Log {
+ return defaultLogPtr.Load()
+}
+
+// SetDefault sets the default logger.
+func SetDefault(l *Log) {
+ defaultLogPtr.Store(l)
+}
+
+// SetLevel sets the default logger's level.
+func SetLevel(level Level) {
+ Default().SetLevel(level)
+}
+
+// SetRedactKeys sets the default logger's redaction keys.
+func SetRedactKeys(keys ...string) {
+ Default().SetRedactKeys(keys...)
+}
+
+// Debug logs to the default logger.
+func Debug(msg string, keyvals ...any) {
+ Default().Debug(msg, keyvals...)
+}
+
+// Info logs to the default logger.
+func Info(msg string, keyvals ...any) {
+ Default().Info(msg, keyvals...)
+}
+
+// Warn logs to the default logger.
+func Warn(msg string, keyvals ...any) {
+ Default().Warn(msg, keyvals...)
+}
+
+// Error logs to the default logger.
+func Error(msg string, keyvals ...any) {
+ Default().Error(msg, keyvals...)
+}
+
+// Security logs to the default logger.
+func Security(msg string, keyvals ...any) {
+ Default().Security(msg, keyvals...)
+}
+
+// --- LogErr: Error-Aware Logger ---
+
+// LogErr logs structured information extracted from errors.
+// Primary action: log. Secondary: extract error context.
+type LogErr struct {
+ log *Log
+}
+
+// NewLogErr creates a LogErr bound to the given logger.
+func NewLogErr(log *Log) *LogErr {
+ return &LogErr{log: log}
+}
+
+// Log extracts context from an Err and logs it at Error level.
+func (le *LogErr) Log(err error) {
+ if err == nil {
+ return
+ }
+ le.log.Error(ErrorMessage(err), "op", Operation(err), "code", ErrorCode(err), "stack", FormatStackTrace(err))
+}
+
+// --- LogPanic: Panic-Aware Logger ---
+
+// LogPanic logs panic context without crash file management.
+// Primary action: log. Secondary: recover panics.
+type LogPanic struct {
+ log *Log
+}
+
+// NewLogPanic creates a LogPanic bound to the given logger.
+func NewLogPanic(log *Log) *LogPanic {
+ return &LogPanic{log: log}
+}
+
+// Recover captures a panic and logs it. Does not write crash files.
+// Use as: defer core.NewLogPanic(logger).Recover()
+func (lp *LogPanic) Recover() {
+ r := recover()
+ if r == nil {
+ return
+ }
+ err, ok := r.(error)
+ if !ok {
+ err = NewError(Sprint("panic: ", r))
+ }
+ lp.log.Error("panic recovered",
+ "err", err,
+ "op", Operation(err),
+ "stack", FormatStackTrace(err),
+ )
+}
diff --git a/.core/reference/options.go b/.core/reference/options.go
new file mode 100644
index 0000000..3721232
--- /dev/null
+++ b/.core/reference/options.go
@@ -0,0 +1,197 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Core primitives: Option, Options, Result.
+//
+// Options is the universal input type. Result is the universal output type.
+// All Core operations accept Options and return Result.
+//
+// opts := core.NewOptions(
+// core.Option{Key: "name", Value: "brain"},
+// core.Option{Key: "path", Value: "prompts"},
+// )
+// r := c.Drive().New(opts)
+// if !r.OK { log.Fatal(r.Error()) }
+package core
+
+// --- Result: Universal Output ---
+
+// Result is the universal return type for Core operations.
+// Replaces the (value, error) pattern — errors flow through Core internally.
+//
+// r := c.Data().New(opts)
+// if !r.OK { core.Error("failed", "err", r.Error()) }
+type Result struct {
+ Value any
+ OK bool
+}
+
+// Result gets or sets the value. Zero args returns Value. With args, maps
+// Go (value, error) pairs to Result and returns self.
+//
+// r.Result(file, err) // OK = err == nil, Value = file
+// r.Result(value) // OK = true, Value = value
+// r.Result() // after set — returns the value
+func (r Result) Result(args ...any) Result {
+ if len(args) == 0 {
+ return r
+ }
+ return r.New(args...)
+}
+
+// New adapts Go (value, error) pairs into a Result.
+//
+// r := core.Result{}.New(file, err)
+func (r Result) New(args ...any) Result {
+ if len(args) == 0 {
+ return r
+ }
+
+ if len(args) > 1 {
+ if err, ok := args[len(args)-1].(error); ok {
+ if err != nil {
+ return Result{Value: err, OK: false}
+ }
+ r.Value = args[0]
+ r.OK = true
+ return r
+ }
+ }
+
+ r.Value = args[0]
+
+ if err, ok := r.Value.(error); ok {
+ if err != nil {
+ return Result{Value: err, OK: false}
+ }
+ return Result{OK: true}
+ }
+
+ r.OK = true
+ return r
+}
+
+// Get returns the Result if OK, empty Result otherwise.
+//
+// r := core.Result{Value: "hello", OK: true}.Get()
+func (r Result) Get() Result {
+ if r.OK {
+ return r
+ }
+ return Result{Value: r.Value, OK: false}
+}
+
+// Option is a single key-value configuration pair.
+//
+// core.Option{Key: "name", Value: "brain"}
+// core.Option{Key: "port", Value: 8080}
+type Option struct {
+ Key string
+ Value any
+}
+
+// --- Options: Universal Input ---
+
+// Options is the universal input type for Core operations.
+// A structured collection of key-value pairs with typed accessors.
+//
+// opts := core.NewOptions(
+// core.Option{Key: "name", Value: "myapp"},
+// core.Option{Key: "port", Value: 8080},
+// )
+// name := opts.String("name")
+type Options struct {
+ items []Option
+}
+
+// NewOptions creates an Options collection from key-value pairs.
+//
+// opts := core.NewOptions(
+// core.Option{Key: "name", Value: "brain"},
+// core.Option{Key: "path", Value: "prompts"},
+// )
+func NewOptions(items ...Option) Options {
+ cp := make([]Option, len(items))
+ copy(cp, items)
+ return Options{items: cp}
+}
+
+// Set adds or updates a key-value pair.
+//
+// opts.Set("port", 8080)
+func (o *Options) Set(key string, value any) {
+ for i, opt := range o.items {
+ if opt.Key == key {
+ o.items[i].Value = value
+ return
+ }
+ }
+ o.items = append(o.items, Option{Key: key, Value: value})
+}
+
+// Get retrieves a value by key.
+//
+// r := opts.Get("name")
+// if r.OK { name := r.Value.(string) }
+func (o Options) Get(key string) Result {
+ for _, opt := range o.items {
+ if opt.Key == key {
+ return Result{opt.Value, true}
+ }
+ }
+ return Result{}
+}
+
+// Has returns true if a key exists.
+//
+// if opts.Has("debug") { ... }
+func (o Options) Has(key string) bool {
+ return o.Get(key).OK
+}
+
+// String retrieves a string value, empty string if missing.
+//
+// name := opts.String("name")
+func (o Options) String(key string) string {
+ r := o.Get(key)
+ if !r.OK {
+ return ""
+ }
+ s, _ := r.Value.(string)
+ return s
+}
+
+// Int retrieves an int value, 0 if missing.
+//
+// port := opts.Int("port")
+func (o Options) Int(key string) int {
+ r := o.Get(key)
+ if !r.OK {
+ return 0
+ }
+ i, _ := r.Value.(int)
+ return i
+}
+
+// Bool retrieves a bool value, false if missing.
+//
+// debug := opts.Bool("debug")
+func (o Options) Bool(key string) bool {
+ r := o.Get(key)
+ if !r.OK {
+ return false
+ }
+ b, _ := r.Value.(bool)
+ return b
+}
+
+// Len returns the number of options.
+func (o Options) Len() int {
+ return len(o.items)
+}
+
+// Items returns a copy of the underlying option slice.
+func (o Options) Items() []Option {
+ cp := make([]Option, len(o.items))
+ copy(cp, o.items)
+ return cp
+}
diff --git a/.core/reference/runtime.go b/.core/reference/runtime.go
new file mode 100644
index 0000000..c9a8223
--- /dev/null
+++ b/.core/reference/runtime.go
@@ -0,0 +1,164 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Runtime helpers for the Core framework.
+// ServiceRuntime is embedded by consumer services.
+// Runtime is the GUI binding container (e.g., Wails).
+
+package core
+
+import (
+ "context"
+ "maps"
+ "slices"
+)
+
+// --- ServiceRuntime (embedded by consumer services) ---
+
+// ServiceRuntime is embedded in services to provide access to the Core and typed options.
+type ServiceRuntime[T any] struct {
+ core *Core
+ opts T
+}
+
+// NewServiceRuntime creates a ServiceRuntime for a service constructor.
+func NewServiceRuntime[T any](c *Core, opts T) *ServiceRuntime[T] {
+ return &ServiceRuntime[T]{core: c, opts: opts}
+}
+
+// Core returns the Core instance this service is registered with.
+//
+// c := s.Core()
+func (r *ServiceRuntime[T]) Core() *Core { return r.core }
+
+// Options returns the typed options this service was created with.
+//
+// opts := s.Options() // MyOptions{BufferSize: 1024, ...}
+func (r *ServiceRuntime[T]) Options() T { return r.opts }
+
+// Config is a shortcut to s.Core().Config().
+//
+// host := s.Config().String("database.host")
+func (r *ServiceRuntime[T]) Config() *Config { return r.core.Config() }
+
+// --- Lifecycle ---
+
+// ServiceStartup runs OnStart for all registered services that have one.
+func (c *Core) ServiceStartup(ctx context.Context, options any) Result {
+ c.shutdown.Store(false)
+ c.context, c.cancel = context.WithCancel(ctx)
+ startables := c.Startables()
+ if startables.OK {
+ for _, s := range startables.Value.([]*Service) {
+ if err := ctx.Err(); err != nil {
+ return Result{err, false}
+ }
+ r := s.OnStart()
+ if !r.OK {
+ return r
+ }
+ }
+ }
+ c.ACTION(ActionServiceStartup{})
+ return Result{OK: true}
+}
+
+// ServiceShutdown drains background tasks, then stops all registered services.
+func (c *Core) ServiceShutdown(ctx context.Context) Result {
+ c.shutdown.Store(true)
+ c.cancel() // signal all context-aware tasks to stop
+ c.ACTION(ActionServiceShutdown{})
+
+ // Drain background tasks before stopping services.
+ done := make(chan struct{})
+ go func() {
+ c.waitGroup.Wait()
+ close(done)
+ }()
+ select {
+ case <-done:
+ case <-ctx.Done():
+ return Result{ctx.Err(), false}
+ }
+
+ // Stop services
+ var firstErr error
+ stoppables := c.Stoppables()
+ if stoppables.OK {
+ for _, s := range stoppables.Value.([]*Service) {
+ if err := ctx.Err(); err != nil {
+ return Result{err, false}
+ }
+ r := s.OnStop()
+ if !r.OK && firstErr == nil {
+ if e, ok := r.Value.(error); ok {
+ firstErr = e
+ } else {
+ firstErr = E("core.ServiceShutdown", Sprint("service OnStop failed: ", r.Value), nil)
+ }
+ }
+ }
+ }
+ if firstErr != nil {
+ return Result{firstErr, false}
+ }
+ return Result{OK: true}
+}
+
+// --- Runtime DTO (GUI binding) ---
+
+// Runtime is the container for GUI runtimes (e.g., Wails).
+type Runtime struct {
+ app any
+ Core *Core
+}
+
+// ServiceFactory defines a function that creates a Service.
+type ServiceFactory func() Result
+
+// NewWithFactories creates a Runtime with the provided service factories.
+func NewWithFactories(app any, factories map[string]ServiceFactory) Result {
+ c := New(WithOptions(NewOptions(Option{Key: "name", Value: "core"})))
+ c.app.Runtime = app
+
+ names := slices.Sorted(maps.Keys(factories))
+ for _, name := range names {
+ factory := factories[name]
+ if factory == nil {
+ continue
+ }
+ r := factory()
+ if !r.OK {
+ cause, _ := r.Value.(error)
+ return Result{E("core.NewWithFactories", Concat("factory \"", name, "\" failed"), cause), false}
+ }
+ svc, ok := r.Value.(Service)
+ if !ok {
+ return Result{E("core.NewWithFactories", Concat("factory \"", name, "\" returned non-Service type"), nil), false}
+ }
+ sr := c.Service(name, svc)
+ if !sr.OK {
+ return sr
+ }
+ }
+ return Result{&Runtime{app: app, Core: c}, true}
+}
+
+// NewRuntime creates a Runtime with no custom services.
+func NewRuntime(app any) Result {
+ return NewWithFactories(app, map[string]ServiceFactory{})
+}
+
+// ServiceName returns "Core" — the Runtime's service identity.
+func (r *Runtime) ServiceName() string { return "Core" }
+
+// ServiceStartup starts all services via the embedded Core.
+func (r *Runtime) ServiceStartup(ctx context.Context, options any) Result {
+ return r.Core.ServiceStartup(ctx, options)
+}
+// ServiceShutdown stops all services via the embedded Core.
+func (r *Runtime) ServiceShutdown(ctx context.Context) Result {
+ if r.Core != nil {
+ return r.Core.ServiceShutdown(ctx)
+ }
+ return Result{OK: true}
+}
diff --git a/.core/reference/service.go b/.core/reference/service.go
new file mode 100644
index 0000000..46738ad
--- /dev/null
+++ b/.core/reference/service.go
@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Service registry for the Core framework.
+//
+// Register a service (DTO with lifecycle hooks):
+//
+// c.Service("auth", core.Service{OnStart: startFn})
+//
+// Register a service instance (auto-discovers Startable/Stoppable/HandleIPCEvents):
+//
+// c.RegisterService("display", displayInstance)
+//
+// Get a service:
+//
+// r := c.Service("auth")
+// if r.OK { svc := r.Value }
+
+package core
+
+import "context"
+
+// Service is a managed component with optional lifecycle.
+type Service struct {
+ Name string
+ Instance any // the raw service instance (for interface discovery)
+ Options Options
+ OnStart func() Result
+ OnStop func() Result
+ OnReload func() Result
+}
+
+// ServiceRegistry holds registered services. Embeds Registry[*Service]
+// for thread-safe named storage with insertion order.
+type ServiceRegistry struct {
+ *Registry[*Service]
+ lockEnabled bool
+}
+
+// --- Core service methods ---
+
+// Service gets or registers a service by name.
+//
+// c.Service("auth", core.Service{OnStart: startFn})
+// r := c.Service("auth")
+func (c *Core) Service(name string, service ...Service) Result {
+ if len(service) == 0 {
+ r := c.services.Get(name)
+ if !r.OK {
+ return Result{}
+ }
+ svc := r.Value.(*Service)
+ // Return the instance if available, otherwise the Service DTO
+ if svc.Instance != nil {
+ return Result{svc.Instance, true}
+ }
+ return Result{svc, true}
+ }
+
+ if name == "" {
+ return Result{E("core.Service", "service name cannot be empty", nil), false}
+ }
+
+ if c.services.Locked() {
+ return Result{E("core.Service", Concat("service \"", name, "\" not permitted — registry locked"), nil), false}
+ }
+ if c.services.Has(name) {
+ return Result{E("core.Service", Join(" ", "service", name, "already registered"), nil), false}
+ }
+
+ srv := &service[0]
+ srv.Name = name
+ return c.services.Set(name, srv)
+}
+
+// RegisterService registers a service instance by name.
+// Auto-discovers Startable, Stoppable, and HandleIPCEvents interfaces
+// on the instance and wires them into the lifecycle and IPC bus.
+//
+// c.RegisterService("display", displayInstance)
+func (c *Core) RegisterService(name string, instance any) Result {
+ if name == "" {
+ return Result{E("core.RegisterService", "service name cannot be empty", nil), false}
+ }
+
+ if c.services.Locked() {
+ return Result{E("core.RegisterService", Concat("service \"", name, "\" not permitted — registry locked"), nil), false}
+ }
+ if c.services.Has(name) {
+ return Result{E("core.RegisterService", Join(" ", "service", name, "already registered"), nil), false}
+ }
+
+ srv := &Service{Name: name, Instance: instance}
+
+ // Auto-discover lifecycle interfaces
+ if s, ok := instance.(Startable); ok {
+ srv.OnStart = func() Result {
+ return s.OnStartup(c.context)
+ }
+ }
+ if s, ok := instance.(Stoppable); ok {
+ srv.OnStop = func() Result {
+ return s.OnShutdown(context.Background())
+ }
+ }
+
+ c.services.Set(name, srv)
+
+ // Auto-discover IPC handler
+ if handler, ok := instance.(interface {
+ HandleIPCEvents(*Core, Message) Result
+ }); ok {
+ c.ipc.ipcMu.Lock()
+ c.ipc.ipcHandlers = append(c.ipc.ipcHandlers, handler.HandleIPCEvents)
+ c.ipc.ipcMu.Unlock()
+ }
+
+ return Result{OK: true}
+}
+
+// ServiceFor retrieves a registered service by name and asserts its type.
+//
+// prep, ok := core.ServiceFor[*agentic.PrepSubsystem](c, "agentic")
+func ServiceFor[T any](c *Core, name string) (T, bool) {
+ var zero T
+ r := c.Service(name)
+ if !r.OK {
+ return zero, false
+ }
+ typed, ok := r.Value.(T)
+ return typed, ok
+}
+
+// MustServiceFor retrieves a registered service by name and asserts its type.
+// Panics if the service is not found or the type assertion fails.
+//
+// cli := core.MustServiceFor[*Cli](c, "cli")
+func MustServiceFor[T any](c *Core, name string) T {
+ v, ok := ServiceFor[T](c, name)
+ if !ok {
+ panic(E("core.MustServiceFor", Sprintf("service %q not found or wrong type", name), nil))
+ }
+ return v
+}
+
+// Services returns all registered service names in registration order.
+//
+// names := c.Services()
+func (c *Core) Services() []string {
+ if c.services == nil {
+ return nil
+ }
+ return c.services.Names()
+}
diff --git a/.core/reference/string.go b/.core/reference/string.go
new file mode 100644
index 0000000..4c64aa7
--- /dev/null
+++ b/.core/reference/string.go
@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// String operations for the Core framework.
+// Provides safe, predictable string helpers that downstream packages
+// use directly — same pattern as Array[T] for slices.
+
+package core
+
+import (
+ "fmt"
+ "strings"
+ "unicode/utf8"
+)
+
+// HasPrefix returns true if s starts with prefix.
+//
+// core.HasPrefix("--verbose", "--") // true
+func HasPrefix(s, prefix string) bool {
+ return strings.HasPrefix(s, prefix)
+}
+
+// HasSuffix returns true if s ends with suffix.
+//
+// core.HasSuffix("test.go", ".go") // true
+func HasSuffix(s, suffix string) bool {
+ return strings.HasSuffix(s, suffix)
+}
+
+// TrimPrefix removes prefix from s.
+//
+// core.TrimPrefix("--verbose", "--") // "verbose"
+func TrimPrefix(s, prefix string) string {
+ return strings.TrimPrefix(s, prefix)
+}
+
+// TrimSuffix removes suffix from s.
+//
+// core.TrimSuffix("test.go", ".go") // "test"
+func TrimSuffix(s, suffix string) string {
+ return strings.TrimSuffix(s, suffix)
+}
+
+// Contains returns true if s contains substr.
+//
+// core.Contains("hello world", "world") // true
+func Contains(s, substr string) bool {
+ return strings.Contains(s, substr)
+}
+
+// Split splits s by separator.
+//
+// core.Split("a/b/c", "/") // ["a", "b", "c"]
+func Split(s, sep string) []string {
+ return strings.Split(s, sep)
+}
+
+// SplitN splits s by separator into at most n parts.
+//
+// core.SplitN("key=value=extra", "=", 2) // ["key", "value=extra"]
+func SplitN(s, sep string, n int) []string {
+ return strings.SplitN(s, sep, n)
+}
+
+// Join joins parts with a separator, building via Concat.
+//
+// core.Join("/", "deploy", "to", "homelab") // "deploy/to/homelab"
+// core.Join(".", "cmd", "deploy", "description") // "cmd.deploy.description"
+func Join(sep string, parts ...string) string {
+ if len(parts) == 0 {
+ return ""
+ }
+ result := parts[0]
+ for _, p := range parts[1:] {
+ result = Concat(result, sep, p)
+ }
+ return result
+}
+
+// Replace replaces all occurrences of old with new in s.
+//
+// core.Replace("deploy/to/homelab", "/", ".") // "deploy.to.homelab"
+func Replace(s, old, new string) string {
+ return strings.ReplaceAll(s, old, new)
+}
+
+// Lower returns s in lowercase.
+//
+// core.Lower("HELLO") // "hello"
+func Lower(s string) string {
+ return strings.ToLower(s)
+}
+
+// Upper returns s in uppercase.
+//
+// core.Upper("hello") // "HELLO"
+func Upper(s string) string {
+ return strings.ToUpper(s)
+}
+
+// Trim removes leading and trailing whitespace.
+//
+// core.Trim(" hello ") // "hello"
+func Trim(s string) string {
+ return strings.TrimSpace(s)
+}
+
+// RuneCount returns the number of runes (unicode characters) in s.
+//
+// core.RuneCount("hello") // 5
+// core.RuneCount("🔥") // 1
+func RuneCount(s string) int {
+ return utf8.RuneCountInString(s)
+}
+
+// NewBuilder returns a new strings.Builder.
+//
+// b := core.NewBuilder()
+// b.WriteString("hello")
+// b.String() // "hello"
+func NewBuilder() *strings.Builder {
+ return &strings.Builder{}
+}
+
+// NewReader returns a strings.NewReader for the given string.
+//
+// r := core.NewReader("hello world")
+func NewReader(s string) *strings.Reader {
+ return strings.NewReader(s)
+}
+
+// Sprint converts any value to its string representation.
+//
+// core.Sprint(42) // "42"
+// core.Sprint(err) // "connection refused"
+func Sprint(args ...any) string {
+ return fmt.Sprint(args...)
+}
+
+// Sprintf formats a string with the given arguments.
+//
+// core.Sprintf("%v=%q", "key", "value") // `key="value"`
+func Sprintf(format string, args ...any) string {
+ return fmt.Sprintf(format, args...)
+}
+
+// Concat joins variadic string parts into one string.
+// Hook point for validation, sanitisation, and security checks.
+//
+// core.Concat("cmd.", "deploy.to.homelab", ".description")
+// core.Concat("https://", host, "/api/v1")
+func Concat(parts ...string) string {
+ b := NewBuilder()
+ for _, p := range parts {
+ b.WriteString(p)
+ }
+ return b.String()
+}
diff --git a/.core/reference/task.go b/.core/reference/task.go
new file mode 100644
index 0000000..b761f9d
--- /dev/null
+++ b/.core/reference/task.go
@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Background action dispatch for the Core framework.
+// PerformAsync runs a named Action in a background goroutine with
+// panic recovery and progress broadcasting.
+
+package core
+
+import "context"
+
+// PerformAsync dispatches a named action in a background goroutine.
+// Broadcasts ActionTaskStarted, ActionTaskProgress, and ActionTaskCompleted
+// as IPC messages so other services can track progress.
+//
+// r := c.PerformAsync("agentic.dispatch", opts)
+// taskID := r.Value.(string)
+func (c *Core) PerformAsync(action string, opts Options) Result {
+ if c.shutdown.Load() {
+ return Result{}
+ }
+ taskID := ID()
+
+ c.ACTION(ActionTaskStarted{TaskIdentifier: taskID, Action: action, Options: opts})
+
+ c.waitGroup.Go(func() {
+ defer func() {
+ if rec := recover(); rec != nil {
+ c.ACTION(ActionTaskCompleted{
+ TaskIdentifier: taskID,
+ Action: action,
+ Result: Result{E("core.PerformAsync", Sprint("panic: ", rec), nil), false},
+ })
+ }
+ }()
+
+ r := c.Action(action).Run(context.Background(), opts)
+
+ c.ACTION(ActionTaskCompleted{
+ TaskIdentifier: taskID,
+ Action: action,
+ Result: r,
+ })
+ })
+
+ return Result{taskID, true}
+}
+
+// Progress broadcasts a progress update for a background task.
+//
+// c.Progress(taskID, 0.5, "halfway done", "agentic.dispatch")
+func (c *Core) Progress(taskID string, progress float64, message string, action string) {
+ c.ACTION(ActionTaskProgress{
+ TaskIdentifier: taskID,
+ Action: action,
+ Progress: progress,
+ Message: message,
+ })
+}
+
+// Registration methods (RegisterAction, RegisterActions)
+// are in ipc.go — registration is IPC's responsibility.
diff --git a/.core/reference/utils.go b/.core/reference/utils.go
new file mode 100644
index 0000000..e510b78
--- /dev/null
+++ b/.core/reference/utils.go
@@ -0,0 +1,223 @@
+// SPDX-License-Identifier: EUPL-1.2
+
+// Utility functions for the Core framework.
+// Built on core string.go primitives.
+
+package core
+
+import (
+ crand "crypto/rand"
+ "encoding/hex"
+ "fmt"
+ "io"
+ "os"
+ "strconv"
+ "sync/atomic"
+)
+
+// --- ID Generation ---
+
+var idCounter atomic.Uint64
+
+// ID returns a unique identifier. Format: "id-{counter}-{random}".
+// Counter is process-wide atomic. Random suffix prevents collision across restarts.
+//
+// id := core.ID() // "id-1-a3f2b1"
+// id2 := core.ID() // "id-2-c7e4d9"
+func ID() string {
+ return Concat("id-", strconv.FormatUint(idCounter.Add(1), 10), "-", shortRand())
+}
+
+func shortRand() string {
+ b := make([]byte, 3)
+ crand.Read(b)
+ return hex.EncodeToString(b)
+}
+
+// --- Validation ---
+
+// ValidateName checks that a string is a valid service/action/command name.
+// Rejects empty, ".", "..", and names containing path separators.
+//
+// r := core.ValidateName("brain") // Result{"brain", true}
+// r := core.ValidateName("") // Result{error, false}
+// r := core.ValidateName("../escape") // Result{error, false}
+func ValidateName(name string) Result {
+ if name == "" || name == "." || name == ".." {
+ return Result{E("validate", Concat("invalid name: ", name), nil), false}
+ }
+ if Contains(name, "/") || Contains(name, "\\") {
+ return Result{E("validate", Concat("name contains path separator: ", name), nil), false}
+ }
+ return Result{name, true}
+}
+
+// SanitisePath extracts the base filename and rejects traversal attempts.
+// Returns "invalid" for dangerous inputs.
+//
+// core.SanitisePath("../../etc/passwd") // "passwd"
+// core.SanitisePath("") // "invalid"
+// core.SanitisePath("..") // "invalid"
+func SanitisePath(path string) string {
+ safe := PathBase(path)
+ if safe == "." || safe == ".." || safe == "" {
+ return "invalid"
+ }
+ return safe
+}
+
+// --- I/O ---
+
+// Println prints values to stdout with a newline. Replaces fmt.Println.
+//
+// core.Println("hello", 42, true)
+func Println(args ...any) {
+ fmt.Println(args...)
+}
+
+// Print writes a formatted line to a writer, defaulting to os.Stdout.
+//
+// core.Print(nil, "hello %s", "world") // → stdout
+// core.Print(w, "port: %d", 8080) // → w
+func Print(w io.Writer, format string, args ...any) {
+ if w == nil {
+ w = os.Stdout
+ }
+ fmt.Fprintf(w, format+"\n", args...)
+}
+
+// JoinPath joins string segments into a path with "/" separator.
+//
+// core.JoinPath("deploy", "to", "homelab") // → "deploy/to/homelab"
+func JoinPath(segments ...string) string {
+ return Join("/", segments...)
+}
+
+// IsFlag returns true if the argument starts with a dash.
+//
+// core.IsFlag("--verbose") // true
+// core.IsFlag("-v") // true
+// core.IsFlag("deploy") // false
+func IsFlag(arg string) bool {
+ return HasPrefix(arg, "-")
+}
+
+// Arg extracts a value from variadic args at the given index.
+// Type-checks and delegates to the appropriate typed extractor.
+// Returns Result — OK is false if index is out of bounds.
+//
+// r := core.Arg(0, args...)
+// if r.OK { path = r.Value.(string) }
+func Arg(index int, args ...any) Result {
+ if index >= len(args) {
+ return Result{}
+ }
+ v := args[index]
+ switch v.(type) {
+ case string:
+ return Result{ArgString(index, args...), true}
+ case int:
+ return Result{ArgInt(index, args...), true}
+ case bool:
+ return Result{ArgBool(index, args...), true}
+ default:
+ return Result{v, true}
+ }
+}
+
+// ArgString extracts a string at the given index.
+//
+// name := core.ArgString(0, args...)
+func ArgString(index int, args ...any) string {
+ if index >= len(args) {
+ return ""
+ }
+ s, ok := args[index].(string)
+ if !ok {
+ return ""
+ }
+ return s
+}
+
+// ArgInt extracts an int at the given index.
+//
+// port := core.ArgInt(1, args...)
+func ArgInt(index int, args ...any) int {
+ if index >= len(args) {
+ return 0
+ }
+ i, ok := args[index].(int)
+ if !ok {
+ return 0
+ }
+ return i
+}
+
+// ArgBool extracts a bool at the given index.
+//
+// debug := core.ArgBool(2, args...)
+func ArgBool(index int, args ...any) bool {
+ if index >= len(args) {
+ return false
+ }
+ b, ok := args[index].(bool)
+ if !ok {
+ return false
+ }
+ return b
+}
+
+// FilterArgs removes empty strings and Go test runner flags from an argument list.
+//
+// clean := core.FilterArgs(os.Args[1:])
+func FilterArgs(args []string) []string {
+ var clean []string
+ for _, a := range args {
+ if a == "" || HasPrefix(a, "-test.") {
+ continue
+ }
+ clean = append(clean, a)
+ }
+ return clean
+}
+
+// ParseFlag parses a single flag argument into key, value, and validity.
+// Single dash (-) requires exactly 1 character (letter, emoji, unicode).
+// Double dash (--) requires 2+ characters.
+//
+// "-v" → "v", "", true
+// "-🔥" → "🔥", "", true
+// "--verbose" → "verbose", "", true
+// "--port=8080" → "port", "8080", true
+// "-verbose" → "", "", false (single dash, 2+ chars)
+// "--v" → "", "", false (double dash, 1 char)
+// "hello" → "", "", false (not a flag)
+func ParseFlag(arg string) (key, value string, valid bool) {
+ if HasPrefix(arg, "--") {
+ rest := TrimPrefix(arg, "--")
+ parts := SplitN(rest, "=", 2)
+ name := parts[0]
+ if RuneCount(name) < 2 {
+ return "", "", false
+ }
+ if len(parts) == 2 {
+ return name, parts[1], true
+ }
+ return name, "", true
+ }
+
+ if HasPrefix(arg, "-") {
+ rest := TrimPrefix(arg, "-")
+ parts := SplitN(rest, "=", 2)
+ name := parts[0]
+ if RuneCount(name) != 1 {
+ return "", "", false
+ }
+ if len(parts) == 2 {
+ return name, parts[1], true
+ }
+ return name, "", true
+ }
+
+ return "", "", false
+}
diff --git a/.gitignore b/.gitignore
index 6ec6138..5347f92 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,7 +1,12 @@
.idea/
.vscode/
*.log
-.core/
+.core/*
+!.core/docs/
+!.core/docs/**
+!.core/reference/
+!.core/reference/**
+!.core/workspace.yaml
node_modules/
bin/
dist/
diff --git a/CODEX.md b/CODEX.md
new file mode 100644
index 0000000..19cbc1d
--- /dev/null
+++ b/CODEX.md
@@ -0,0 +1,86 @@
+# CODEX.md
+
+Instructions for Codex when working in `dappco.re/go/agent`.
+
+Read these files in order:
+1. `CODEX.md`
+2. `.core/reference/RFC-025-AGENT-EXPERIENCE.md`
+3. `.core/reference/docs/RFC.md`
+4. `AGENTS.md`
+
+## Overview
+
+This repo is the Core ecosystem's agent orchestration service. It is AX-first: predictable names, named Actions, Core primitives, and behaviour-driven tests matter more than terse APIs.
+
+## Build And Test
+
+```bash
+go build ./...
+go build ./cmd/core-agent/
+go test ./... -count=1 -timeout 60s
+go vet ./...
+```
+
+## Core Registration Pattern
+
+Register services through `core.New` and `WithService`, not ad hoc globals.
+
+```go
+c := core.New(
+ core.WithOption("name", "core-agent"),
+ core.WithService(agentic.ProcessRegister),
+ core.WithService(agentic.Register),
+ core.WithService(runner.Register),
+ core.WithService(monitor.Register),
+ core.WithService(brain.Register),
+)
+c.Run()
+```
+
+## Mandatory Conventions
+
+- Use UK English in comments and docs.
+- Use `core.E("pkg.Method", "message", err)` for errors. Never use `fmt.Errorf` or `errors.New`.
+- Use Core filesystem helpers or package-level `fs`. Never use raw `os.ReadFile`, `os.WriteFile`, or `filepath.*`.
+- Route external commands through `pkg/agentic/proc.go` or `s.Core().Process()`. Never import `os/exec`.
+- Use Core string helpers such as `core.Contains`, `core.Trim`, and `core.Split` instead of `strings.*`.
+- Prefer `core.Result{Value: x, OK: true}` over `(value, error)` return pairs in Core-facing code.
+- Comments should show real usage examples, not restate the signature.
+- Prefer predictable names such as `Config`, `Service`, and `Options`; avoid abbreviations.
+- Add `// SPDX-License-Identifier: EUPL-1.2` to Go source files.
+
+## AX Quality Gates
+
+Treat these imports as review failures in non-test Go code:
+
+- `os`
+- `os/exec`
+- `fmt`
+- `log`
+- `errors`
+- `encoding/json`
+- `path/filepath`
+- `strings`
+- `unsafe`
+
+Use the Core primitive or the repo helper instead.
+
+## Testing
+
+Use AX test naming:
+
+```text
+TestFile_Function_Good
+TestFile_Function_Bad
+TestFile_Function_Ugly
+```
+
+One source file should have its own focused test file and example file where practical. The test suite is the behavioural spec.
+
+## Commits
+
+Use `type(scope): description` and include:
+
+```text
+Co-Authored-By: Virgil
+```