From 17ae94530d745a8d56b9f08be115e4527b3013d5 Mon Sep 17 00:00:00 2001
From: Snider <snider@host.uk.com>
Date: Fri, 20 Feb 2026 15:57:44 +0000
Subject: [PATCH] docs: add CLAUDE.md and README.md

Agent instructions and quick start guide with RouteGroup example.

Co-Authored-By: Virgil <virgil@lethean.io>
---
 CLAUDE.md | 32 ++++++++++++++++++++++++++++++++
 README.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 87 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 README.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b9dff93
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code when working with the go-api repository.
+
+## Project Overview
+
+**go-api** is the REST framework for the Lethean Go ecosystem. It provides a Gin-based HTTP engine with middleware, response envelopes, WebSocket integration, and OpenAPI generation. Subsystems implement the `RouteGroup` interface to register their own endpoints.
+
+- **Module path**: `forge.lthn.ai/core/go-api`
+- **Language**: Go 1.25
+- **Licence**: EUPL-1.2
+
+See `docs/` for architecture, tool reference, and development guide.
+
+## Build & Test Commands
+
+```bash
+go test ./...                       # Run all tests
+go test -run TestName ./...         # Run a single test
+go test -v -race ./...              # Verbose with race detector
+go build ./...                      # Build (library — no main package)
+go vet ./...                        # Vet
+```
+
+## Coding Standards
+
+- **UK English** in comments and user-facing strings (colour, organisation, unauthorised)
+- **Conventional commits**: `type(scope): description`
+- **Co-Author**: `Co-Authored-By: Virgil <virgil@lethean.io>`
+- **Error handling**: Return wrapped errors with context, never panic
+- **Test naming**: `_Good` (happy path), `_Bad` (expected errors), `_Ugly` (panics/edge cases)
+- **Licence**: EUPL-1.2
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3665ae0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,55 @@
+# go-api
+
+REST framework + OpenAPI SDK generation for the Lethean Go ecosystem.
+
+## Overview
+
+go-api provides a Gin-based HTTP engine that subsystems plug into via the `RouteGroup` interface. Each ecosystem package (go-ml, go-rag, go-agentic, etc.) registers its own route group, and go-api handles the HTTP plumbing, middleware, response envelopes, WebSocket integration, and OpenAPI spec generation.
+
+## Quick Start
+
+```go
+import api "forge.lthn.ai/core/go-api"
+
+engine, _ := api.New(
+    api.WithAddr(":8080"),
+    api.WithBearerAuth("my-token"),
+    api.WithCORS("*"),
+    api.WithRequestID(),
+    api.WithSwagger("My API", "Description", "0.1.0"),
+)
+
+engine.Register(myRoutes)
+engine.Serve(ctx)
+```
+
+## Implementing a RouteGroup
+
+```go
+type Routes struct{ service *mypackage.Service }
+
+func (r *Routes) Name() string     { return "mypackage" }
+func (r *Routes) BasePath() string { return "/v1/mypackage" }
+
+func (r *Routes) RegisterRoutes(rg *gin.RouterGroup) {
+    rg.GET("/items", r.ListItems)
+    rg.POST("/items", r.CreateItem)
+}
+
+func (r *Routes) ListItems(c *gin.Context) {
+    items, _ := r.service.List(c.Request.Context())
+    c.JSON(200, api.OK(items))
+}
+```
+
+## Features
+
+- **Response envelope** — `api.OK()`, `api.Fail()`, `api.Paginated()` for consistent JSON responses
+- **Middleware** — Bearer auth, CORS, request ID generation, panic recovery
+- **WebSocket** — `WithWSHandler()` mounts any `http.Handler` at `/ws`
+- **Swagger UI** — `WithSwagger()` serves interactive API docs at `/swagger/`
+- **Health check** — Built-in `GET /health` endpoint
+
+## Licence
+
+EUPL-1.2