From 1576f744d10503b4bd9fcb4e758dfebb312c87aa Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Fri, 20 Feb 2026 15:11:19 +0000
Subject: [PATCH] docs: add README with quick start and docs links

Co-Authored-By: Virgil <virgil@lethean.io>
---
 README.md | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 92f2919..078cd2e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,41 @@
 # go-inference
 
-Shared inference interfaces (TextModel, Backend, Token). Zero deps, compiles everywhere.
\ No newline at end of file
+Shared interface contract for text generation backends in the Core Go ecosystem. Defines `TextModel`, `Backend`, `Token`, `Message`, and associated configuration types that GPU-specific backends implement and consumers depend on. Zero external dependencies — stdlib only — and compiles on all platforms regardless of GPU availability. The backend registry supports automatic selection (Metal preferred on macOS, ROCm on Linux) and explicit pinning.
+
+**Module**: `forge.lthn.ai/core/go-inference`
+**Licence**: EUPL-1.2
+**Language**: Go 1.25
+
+## Quick Start
+
+```go
+import (
+    "forge.lthn.ai/core/go-inference"
+    _ "forge.lthn.ai/core/go-mlx"   // registers "metal" backend on darwin/arm64
+)
+
+model, err := inference.LoadModel("/path/to/safetensors/model/")
+defer model.Close()
+
+for tok := range model.Generate(ctx, "Hello", inference.WithMaxTokens(256)) {
+    fmt.Print(tok.Text)
+}
+```
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — interfaces, registry, options, stability contract, ecosystem position
+- [Development Guide](docs/development.md) — prerequisites, build, test patterns, coding standards
+- [Project History](docs/history.md) — completed phases, commit log, known limitations
+
+## Build & Test
+
+```bash
+go test ./...
+go vet ./...
+go build ./...
+```
+
+## Licence
+
+European Union Public Licence 1.2 — see [LICENCE](LICENCE) for details.