docs(go): flesh out orm + inference, promote to content sidebar

orm
  - Stateless typed-bridge model: callers build intent, Mediums transport it
  - orm.Define schema declaration with field constraints
  - Bridge[T] typed query builder — Where/OrderBy/Limit/Get/First/Count
  - Insert/Update/Delete via Bridge or package-level helpers
  - From() aliases for joins + With() for eager-loaded relations
  - WhereGroup for compound (A AND (B OR C)) predicates
  - Polyglot story per RFC §12 — Go/PHP/TS produce identical Schema JSON

inference
  - The Backend contract every GPU-specific runtime registers against
  - Stdlib-only — compiles on every platform regardless of GPU
  - Quick-start with blank-import backend registration pattern
  - LoadModel + Generate streaming token loop with options table
  - LoadOption vs GenerateOption split (load-time vs runtime knobs)
  - LoadTrainable for fine-tuning workflows (gradients + Step)
  - Service Register pattern, ProbeBus for token-level introspection
  - Capability registry for backend discovery

Sidebar
  - Promoted orm + inference into "Packages — content" — total now 14
    pages with real examples
  - Removed both from "Packages — index" stub list

Co-Authored-By: Virgil <virgil@lethean.io>

Author: Snider

astro.config.mjs

@@ -61,6 +61,8 @@ export default defineConfig({
 						{ label: 'process', slug: 'go/process' },
 						{ label: 'webview', slug: 'go/webview' },
 						{ label: 'forge', slug: 'go/forge' },
+						{ label: 'orm', slug: 'go/orm' },
+						{ label: 'inference', slug: 'go/inference' },
 						{ label: 'agent', slug: 'go/agent' },
 						{ label: 'mcp', slug: 'go/mcp' },
 						{ label: 'miner', slug: 'go/miner' },
@@ -93,12 +95,10 @@ export default defineConfig({
 						{ label: 'html', slug: 'go/html' },
 						{ label: 'i18n', slug: 'go/i18n' },
 						{ label: 'ide', slug: 'go/ide' },
-						{ label: 'inference', slug: 'go/inference' },
 						{ label: 'log', slug: 'go/log' },
 						{ label: 'ml', slug: 'go/ml' },
 						{ label: 'mlx', slug: 'go/mlx' },
 						{ label: 'netops', slug: 'go/netops' },
-						{ label: 'orm', slug: 'go/orm' },
 						{ label: 'p2p', slug: 'go/p2p' },
 						{ label: 'rag', slug: 'go/rag' },
 						{ label: 'scm', slug: 'go/scm' },

src/content/docs/go/inference.mdx

@@ -1,6 +1,6 @@
 ---
 title: inference
-description: Local inference adapters — Default, LoadModel, LoadTrainable.
+description: Local text generation — the Backend contract every GPU-specific runtime implements.
 head:
   - tag: meta
     attrs:
@@ -12,7 +12,12 @@ head:
       content: 'dappco.re/go/inference https://github.com/dappcore/go-inference https://github.com/dappcore/go-inference/tree/main{/dir} https://github.com/dappcore/go-inference/blob/main{/dir}/{file}#L{line}'
 ---
 
-Local inference adapters — Default, LoadModel, LoadTrainable. Built on the [`core/go`](/go/) primitives.
+The shared contract every text-generation backend implements. `TextModel`
++ `Backend` + `Token` + `Message` are stdlib-only types that compile on
+every platform regardless of GPU availability; GPU-specific runtimes
+(Metal, ROCm, CUDA, …) register themselves at import time. Built on
+[`core/go`](/go/) — `LoadModel` returns a [`Result`](/go/result/), zero
+external dependencies.
 
 ## Install
 
@@ -23,10 +28,154 @@ go get dappco.re/go/inference@latest
 ## Import
 
 ```go
-import "dappco.re/go/inference"
+import (
+    "dappco.re/go/inference"
+
+    // Pick one or more — each blank import registers a backend
+    _ "forge.lthn.ai/core/go-mlx"   // "metal" backend on darwin/arm64
+    // _ "forge.lthn.ai/core/go-rocm"  // "rocm" backend on linux/amd64
+    // _ "forge.lthn.ai/core/go-cuda"  // "cuda" backend on linux/amd64
+)
+```
+
+The base package compiles without any backend; calls fail cleanly with
+`no backend registered` rather than refusing to build. This is what lets
+the same binary target a laptop without a GPU and a Mac Studio without
+two `GOOS` builds.
+
+## Quick start
+
+```go
+r := inference.LoadModel("/path/to/safetensors/model/")
+if !r.OK { return r }
+model := r.Value.(inference.TextModel)
+defer model.Close()
+
+for tok := range model.Generate(ctx, "Hello", inference.WithMaxTokens(256)) {
+    fmt.Print(tok.Text)
+}
+```
+
+Backend selection is automatic — the registry picks Metal on Apple
+Silicon, ROCm on Linux+AMD, CUDA on Linux+NVIDIA, in that preferred
+order — but you can pin explicitly:
+
+```go
+r := inference.LoadModel(path, inference.WithBackend("metal"))
 ```
 
-## Status
+`inference.List()` returns the backend names that registered at import
+time, which is useful for runtime config + diagnostics.
+
+## Generate options
+
+Every generation call takes a variadic `GenerateOption`:
+
+| Option | Effect |
+|---|---|
+| `WithMaxTokens(n)` | Cap output length |
+| `WithTemperature(t)` | Sampling temperature (0 = greedy) |
+| `WithTopK(k)` | Restrict sampling to top K logits |
+| `WithTopP(p)` | Nucleus sampling threshold |
+| `WithStopTokens(ids...)` | Halt on any of these token IDs |
+| `WithRepeatPenalty(p)` | Penalise repeated tokens |
+| `WithLogits()` | Emit raw logits per token (for analysis) |
+
+## Load options
+
+`LoadOption` configures the model **at load time** — runtime knobs that
+the backend can't change without reloading:
+
+| Option | Effect |
+|---|---|
+| `WithBackend(name)` | Pin a specific backend instead of auto-select |
+| `WithContextLen(n)` | Override the model's default context length |
+| `WithGPULayers(n)` | How many transformer layers live on GPU vs CPU |
+| `WithParallelSlots(n)` | Number of concurrent generation slots |
+| `WithAdapterPath(path)` | Layer a LoRA adapter over the base model |
+
+## Trainable models
+
+For fine-tuning workflows, `LoadTrainable` returns a model that exposes
+gradients alongside generation:
+
+```go
+r := inference.LoadTrainable(path, inference.WithAdapterPath("lora/"))
+if !r.OK { return r }
+trainable := r.Value.(inference.TrainableModel)
+
+// Same generation surface
+for tok := range trainable.Generate(ctx, "prompt") { /* ... */ }
+
+// Plus the training surface
+trainable.Backward(loss)
+trainable.Step()
+```
+
+Backend support for the trainable path is opt-in — backends that ship
+inference-only will return `not supported`.
+
+## Service registration
+
+The canonical `core/go` Service shape lets a Core instance host an
+inference runtime that every consumer reaches through actions:
+
+```go
+c := core.New(core.Options{})
+
+if r := inference.RegisterCore(c); !r.OK { return r }
+
+// Or with options
+svc := inference.NewService(inference.Options{
+    DefaultBackend: "metal",
+    ModelPath:      "/srv/models/gemma-4-e2b",
+})
+if r := svc(c); !r.OK { return r }
+```
+
+## Probe bus
+
+`NewProbeBus(sinks...)` wires up token-by-token introspection — useful
+for metrics, eval harnesses, or live UIs that show what the model is
+"thinking":
+
+```go
+bus := inference.NewProbeBus(
+    inference.NewTelemetrySink(c),
+    inference.NewLogitSink(eval),
+)
+
+r := inference.LoadModel(path, inference.WithProbeBus(bus))
+```
+
+Each `ProbeSink` receives every token + (optionally) the logits behind
+it. The base package ships the bus + interface; concrete sinks live in
+consumer code.
+
+## Capabilities
+
+Each registered backend declares a `Capability` list that the registry
+exposes for discovery. A consumer can pick a backend based on what it
+supports (training? batched inference? logits? KV-cache snapshots?):
+
+```go
+for _, name := range inference.List() {
+    caps := inference.BackendCaps(name)
+    for _, cap := range caps {
+        fmt.Printf("%s: %s (%s)\n", name, cap.ID, cap.Status)
+    }
+}
+```
+
+## Sibling packages
+
+- [`go/ai`](/go/ai/) — higher-level multi-provider orchestrator built on
+  inference plus remote API clients
+- [`go/mlx`](/go/mlx/) — Apple Silicon Metal backend that registers as
+  `"metal"`
+- [`go/rag`](/go/rag/) — retrieval-augmented pipeline that consumes
+  inference for the generation stage
+
+## Source
 
-Page in flight — content fills in as the package converges. Source of truth
-today is the README and inline docstrings in the repo.
+[`github.com/dappcore/go-inference`](https://github.com/dappcore/go-inference) — full source, contract tests, and the capability registry.

src/content/docs/go/orm.mdx

@@ -1,6 +1,6 @@
 ---
 title: orm
-description: Typed query layer over core/go/store — query builder, repositories, materialised views.
+description: Typed fluent communications bridge — schema, intent, Medium-transported.
 head:
   - tag: meta
     attrs:
@@ -12,8 +12,11 @@ head:
       content: 'dappco.re/go/orm https://github.com/dAppCore/orm https://github.com/dAppCore/orm/tree/main{/dir} https://github.com/dAppCore/orm/blob/main{/dir}/{file}#L{line}'
 ---
 
-Typed query layer over [`core/go/store`](/go/store/) — query builder,
-repositories, materialised views. Built on the [`core/go`](/go/) primitives.
+A typed, fluent communications bridge over backend Media. Callers build
+**intent**; a Medium **transports** it. The same `Schema` declaration
+lands against DuckDB today, Postgres tomorrow, a Borg DataNode next week
+— the bridge is stateless, the backend's capability is what changes.
+Built on [`core/go`](/go/) — every query returns a [`Result`](/go/result/).
 
 ## Install
 
@@ -27,7 +30,147 @@ go get dappco.re/go/orm@latest
 import "dappco.re/go/orm"
 ```
 
-## Status
+## Declare a Schema
 
-Page in flight — content fills in as the package converges. Source of truth
-today is the README and inline docstrings in the repo.
+`orm.Define` collects field declarations into a `Schema` value. Field
+builders are chainable so constraints stay close to the column they
+describe:
+
+```go
+type User struct {
+    ID    int64
+    Name  string
+    Email string
+}
+
+func (User) Schema() orm.Schema {
+    return orm.Define(func(b *orm.Builder) {
+        b.Name("users")
+        b.PK("id")
+        b.String("name").NotNull()
+        b.String("email").Unique()
+    })
+}
+
+type Post struct {
+    ID     int64
+    UserID int64
+    Title  string
+}
+
+func (Post) Schema() orm.Schema {
+    return orm.Define(func(b *orm.Builder) {
+        b.Name("posts")
+        b.PK("id")
+        b.Int64("user_id")
+        b.String("title")
+    })
+}
+```
+
+Schemas are values — pass them around, serialise them to JSON via
+`SchemaFromJSON`, ship them across the polyglot boundary (per RFC §12 the
+same `Schema()` declaration ports across Go, PHP, and TS implementations
+producing identical JSON shape).
+
+## Mount a Medium
+
+A Medium is what carries intent to a real backend. Today: in-memory
+(`NewMemium`), DuckDB (via [`go/store`](/go/store/)), more to follow.
+Mount once on a Core and every Bridge call routes through:
+
+```go
+c := core.New()
+mem := orm.NewMemium()
+orm.Mount(c, "default", mem)
+```
+
+## Query — typed Bridge
+
+`Bridge[T]` is the typed query builder. Construct one from a Schema +
+Core, chain predicates, terminate with a fetch verb that returns
+`core.Result`:
+
+```go
+bridge := orm.From[User](c)
+
+r := bridge.
+    Where("email", "=", "a@b.com").
+    First()
+if !r.OK { return r }
+user := r.Value.(*User)
+
+// Multi-row + ordering + limit
+r := orm.From[Post](c).
+    Where("user_id", "=", user.ID).
+    OrderBy("id", "desc").
+    Limit(10).
+    Get()
+posts := r.Value.([]*Post)
+
+// Aggregates
+r := orm.From[Post](c).Where("user_id", "=", user.ID).Count()
+n := r.Value.(int)
+```
+
+The fluent surface mirrors Eloquent's reading rhythm without dragging in
+Eloquent's machinery. Every predicate, every order, every join is just
+intent in a Go value until the Medium turns it into a backend call.
+
+## Write — Insert, Update, Delete
+
+Writes go through the same Bridge or the package-level helpers:
+
+```go
+// Through the Bridge
+bridge.Insert(&User{Name: "alice", Email: "a@b.com"})
+bridge.Where("id", "=", 42).Update(map[string]any{"name": "renamed"})
+bridge.Where("id", "=", 42).Delete(&User{})
+
+// Package-level — multi-row insert
+orm.Insert(c, &User{Name: "bob"}, &User{Name: "carol"})
+orm.Delete(c, &User{ID: 7})
+```
+
+Every write returns `core.Result` — failures surface the bridge intent
+that didn't transport plus the underlying Medium error, so the call site
+sees what was attempted.
+
+## Joins + relations
+
+`Bridge.From(...)` aliases a related Schema for cross-table predicates;
+`Bridge.With(...)` declares eager-load relations the Medium should
+pre-fetch:
+
+```go
+users := orm.From[User](c).
+    From(orm.A{"posts": Post{}.Schema()}).
+    Where("posts.title", "like", "%golang%").
+    With("posts").
+    Get()
+```
+
+## Predicate grouping
+
+Compound `(A AND (B OR C))` predicates with `WhereGroup`:
+
+```go
+bridge.
+    Where("status", "=", "active").
+    WhereGroup(func(g *orm.Group) {
+        g.Where("role", "=", "admin").
+          OrWhere("role", "=", "owner")
+    }).
+    Get()
+```
+
+## Sibling packages
+
+- [`go/store`](/go/store/) — the persistence layer most orm Mediums route to
+- [`go/io`](/go/io/) — Medium transport contract orm extends
+- [`go/api`](/go/api/) — the polyglot boundary orm Schemas cross at runtime
+
+## Source
+
+[`github.com/dAppCore/orm`](https://github.com/dAppCore/orm) — full source,
+RFC, and the IMPLEMENTATION_PLAN that sequences the Go v1 build.