refactor

docs/deployment.md

@@ -10,6 +10,7 @@ Running go-bananas, from a laptop to a production cluster.
 - [Configuration](#configuration)
 - [Authentication](#authentication)
 - [Helm](#helm)
+- [Local deployment (lcl)](#local-deployment-lcl)
 - [The production checklist](#the-production-checklist)
 - [Scaling](#scaling)
 - [Backup and restore](#backup-and-restore)
@@ -127,7 +128,7 @@ is made impossible to construct.
 
 ### The shared development realm
 
-The chart defaults to `https://auth-dev.urpi.be/realms/urpi`, so a development cluster
+The chart defaults to `https://auth.lcl-urpi.be/realms/urpi`, so a development cluster
 works with no identity configuration.
 
 The realm path is part of the issuer. The value must match the `iss` claim in the ID
@@ -260,6 +261,77 @@ helm lint deploy/helm/go-bananas --strict
 
 ---
 
+## Local deployment (lcl)
+
+The `lcl` environment is the developer's own single-node **k3s** cluster used for
+local integration testing. It is defined by `deploy/helm/go-bananas/values-lcl.yaml`:
+
+- `config.environment: development` so the local auth bypass is allowed.
+- `identity.mode: dev` so you can sign in without an OIDC provider.
+- `image.registry: localhost:5000` so the cluster pulls from a local registry.
+- Ingress host `bananas-lcl.intern-urpi.be`, terminated by the local TLS edge.
+
+All the `go-*` applications share the **`go-insane-lcl`** namespace; go-bananas is a
+Helm release named `go-bananas` inside it.
+
+### Prerequisites
+
+1. A running local k3s cluster and a registry at `localhost:5000`.
+2. `bananas-lcl.intern-urpi.be` resolving to the node (`/etc/hosts`) behind the TLS edge.
+3. `docker buildx`, `helm` and `kubectl`.
+
+> **Kubeconfig caveat.** On this machine the default `local` context goes through a
+> Rancher proxy (`https://rancher.urpi.be/k8s/clusters/local`) which can 502. When it
+> does, talk to k3s directly instead: `export KUBECONFIG=/etc/rancher/k3s/k3s.yaml`.
+> Everything below respects that variable.
+
+### One-shot build + deploy + verify
+
+```bash
+KUBECONFIG=/etc/rancher/k3s/k3s.yaml ./hack/deploy-lcl.sh
+# or, equivalently:
+KUBECONFIG=/etc/rancher/k3s/k3s.yaml make deploy-lcl
+```
+
+This builds a fresh image (with the web admin UI and runtime SDK compiled in), pushes
+it to the local registry, runs `helm upgrade --install`, waits for the rollout, and
+curls the runtime manifest through the TLS edge. The image tag defaults to a build
+timestamp so a rebuild is always re-pulled (`IfNotPresent` would otherwise serve a
+stale cached tag). Override it with `LCL_TAG=...`.
+
+### Step by step
+
+```bash
+make install             # Go and Node dependencies
+make image-lcl           # build + push to localhost:5000/go-bananas:<LCL_TAG>
+make helm-template-lcl   # sanity-check the rendered manifest
+make helm-install-lcl    # helm upgrade --install into go-insane-lcl
+```
+
+`LCL_TAG`, `LCL_REGISTRY` and `LCL_NAMESPACE` are overridable:
+
+```bash
+make deploy-lcl LCL_TAG=v1 LCL_REGISTRY=registry:5000 LCL_NAMESPACE=go-insane-lcl
+```
+
+### Sign in and verify
+
+The release uses `dev` authentication, so any user is a local administrator. Open
+`https://bananas-lcl.intern-urpi.be/?dev-user=you@example.test`, then:
+
+```bash
+curl -sk https://bananas-lcl.intern-urpi.be/readyz
+curl -sk https://bananas-lcl.intern-urpi.be/rt/v1/manifest.json | jq '.themes[].slug'
+```
+
+### Remove
+
+```bash
+KUBECONFIG=/etc/rancher/k3s/k3s.yaml make helm-uninstall-lcl
+```
+
+---
+
 ## The production checklist
 
 - [ ] `config.environment: production`
@@ -544,4 +616,4 @@ applications. A CDN or browser holding an old version explains it; the runtime
 manifest's `baseUrl` will show whether a CDN is in the path.
 
 **The stylesheet is stale after a publish.** Expected within one `s-maxage` window
-(300 s by default). To force it, lower `config.runtimeCacheControl` or purge the CDN.
+(300 s by default). To force it, lower `config.runtimeCacheControl` or purge the CDN.

docs/development.md

@@ -26,7 +26,7 @@ make tools         # air, golangci-lint, sqlc
 ## Running
 
 ```bash
-make dev-all       # API on :8080, admin UI on :5173 with a proxy
+make dev-all       # API on :8080, admin UI on :5173 with a proxy (builds the SDK first)
 ```
 
 Open <http://localhost:5173>. The Vite dev server proxies `/api`, `/rt` and `/auth`
@@ -34,11 +34,18 @@ to the Go process, so the session cookie works exactly as it will in production.
 Same-origin matters: a cross-origin setup would not authenticate at all, and the
 problem would look like a bug rather than a topology difference.
 
+The admin UI is itself a consumer of the runtime: the header theme selector and the
+light/dark toggle are the shipped controls, loaded from `/rt/v1/components.js`, which
+the **API** serves from `sdk/dist` (Vite proxies `/rt` to it). `make dev-all` builds
+the SDK up front for exactly this reason — an unbuilt `sdk/dist` means those controls
+never define and the switcher silently falls back.
+
 Other entry points:
 
 ```bash
-make dev-api       # the API alone, with hot reload
-make dev-web       # the admin UI alone
+make dev           # the API with hot reload (air); serves web/dist and sdk/dist, so `make build` first
+make dev-api       # the API alone, no hot reload; serves the runtime SDK, Vite serves the UI
+make dev-web       # the admin UI alone (its /api and /rt proxy to :8080)
 make run           # build everything, run the real binary
 ```