diff --git a/knowledge/architecture/chapter-service.md b/knowledge/architecture/chapter-service.md new file mode 100644 index 0000000..7f3c210 --- /dev/null +++ b/knowledge/architecture/chapter-service.md @@ -0,0 +1,45 @@ +--- +type: Service +title: Chapter service +description: One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it. +tags: [architecture, go, k3s] +status: stable +generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } +--- + +# Behavior + +| `MODE` | Runs as | `/healthz` (liveness) | `/ready` (readiness) | Resulting state | +|---|---|---|---|---| +| `healthy` | Deployment | 200 | 200 | Running, Ready | +| `not-ready` | Deployment | 200 | 503 | Running, NotReady | +| `crash` | Deployment | n/a | n/a | Exits on start: CrashLoopBackOff | +| `complete` | Job | n/a | n/a | Prints a line, exits 0: Completed | + +`CHAPTER` env var names the chapter. Used in logs only. + +# Endpoints + +- `GET /healthz` - liveness. +- `GET /ready` - readiness, depends on `MODE`. +- `POST /fall` - responds 202, then `os.Exit(1)`. The kubelet restarts the container and increments `restartCount`. + +# Kubernetes details + +- Each chapter gets a Deployment (1 replica) and a Service `chapter-{name}`. +- Services set `publishNotReadyAddresses: true`, otherwise a NotReady chapter + has no endpoints and the gateway cannot push it. +- Label every pod `cv.noelsabia.dev/chapter: {name}`. The gateway uses it to map pods to chapters. +- Tight resource limits on every chapter (for example 10m CPU, 16Mi memory). + Crashing chapters back off on Kubernetes' default schedule, which caps at 5 minutes. +- Completed Jobs keep no `ttlSecondsAfterFinished`, so they stay visible as Completed. +- A CrashLoopBackOff chapter cannot be pushed; it is already down. The UI shows its lesson card instead. + +# Manifests + +Plain YAML, one file per chapter, applied with `kubectl apply -k` (kustomize is +built into kubectl). Copy-paste per chapter is fine at this size. + +# Size + +About 50 lines of Go, standard library only. diff --git a/knowledge/architecture/delivery.md b/knowledge/architecture/delivery.md new file mode 100644 index 0000000..423ab66 --- /dev/null +++ b/knowledge/architecture/delivery.md @@ -0,0 +1,37 @@ +--- +type: Pipeline +title: Delivery +description: Gitea Actions on the home server scan, build, push to the Gitea registry, deploy with kubectl, and version with release-please. +tags: [architecture, ci, gitea, release-please] +status: stable +generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } +--- + +# Pipeline + +``` +push to main ─► Gitea Actions (runner on the home server) + ├─ go test ./... + ├─ snyk test + ├─ build images: gateway (with Nuxt), chapter + ├─ push to the Gitea container registry + └─ kubectl apply -k deploy/ + ─► release-please (Gitea variant) opens a release PR; merging it tags the version +``` + +# Details + +- **Commits:** Conventional Commits. `feat:` bumps minor, `fix:` bumps patch, + `docs:` and `chore:` do not release. +- **Image tags:** the git SHA, so every deploy is traceable. +- **Registry pull:** k3s needs an `imagePullSecret` for the Gitea registry, + or `/etc/rancher/k3s/registries.yaml` if the registry is plain HTTP. +- **Runner permissions:** a kubeconfig for a ServiceAccount that can only + manage resources in `cv`. +- **Jobs are immutable:** changing a completed chapter's Job spec needs a + delete before apply. Rare, since finished chapters do not change. +- **Snyk:** needs a `SNYK_TOKEN` secret in Gitea. + +# Later + +- k6 as a release gate needs a staging target. See [open questions](/decisions/open-questions.md). diff --git a/knowledge/architecture/frontend.md b/knowledge/architecture/frontend.md new file mode 100644 index 0000000..cd39ff1 --- /dev/null +++ b/knowledge/architecture/frontend.md @@ -0,0 +1,48 @@ +--- +type: Frontend +title: Frontend +description: Nuxt site generated to static files and served by the gateway, with three audience layers fed by one SSE stream. +tags: [architecture, nuxt, design] +status: stable +generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } +--- + +# Build + +`nuxt generate` produces static, prerendered files. A multi-stage Docker build +runs it in a Node stage and copies the output into the gateway's Go stage for +`go:embed`. No Node process runs in the cluster. + +# Layers + +| Layer | Audience | Content | Needs live cluster | +|---|---|---|---| +| 0: First screen | HR | Name, role, contact, PDF CV download | No | +| 1: Life map | Non-technical | Chapters in plain words, "Push this chapter", story cards | Yes, degrades to static | +| 2: Dev view | Developers | Raw SSE events in a `
` | Yes |
+
+# Content
+
+Chapter text (title, dates, story, setback, recovery, lesson) lives in the
+Nuxt repo as one data file. The key is the chapter name, the same value as the
+pod label `cv.noelsabia.dev/chapter`. The gateway knows nothing about stories.
+
+# Behavior without the live stream
+
+If `/api/events` fails, the life map renders from the data file with a small
+"live cluster offline" note. No error page.
+
+# Plain-word states
+
+| State | Shown as |
+|---|---|
+| Completed | finished |
+| Running, Ready | active |
+| Running, NotReady | unfinished |
+| CrashLoopBackOff | failed, lesson learned |
+| Restarting after a push | recovering |
+
+# Design
+
+Terminal feel, navy `#1A3D64` and white, logo with a "broken pieces" look.
+Drafted with Stitch prompts.
diff --git a/knowledge/architecture/gateway.md b/knowledge/architecture/gateway.md
new file mode 100644
index 0000000..8866c5a
--- /dev/null
+++ b/knowledge/architecture/gateway.md
@@ -0,0 +1,48 @@
+---
+type: Service
+title: Gateway
+description: The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
+tags: [architecture, go, security]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Routes
+
+| Route | Does |
+|---|---|
+| `GET /` and static paths | Serves the Nuxt build, embedded with `go:embed` |
+| `GET /api/events` | SSE stream: full state on connect, then each change |
+| `POST /api/fall/{chapter}` | Allowlist, cooldown, rate limit, then calls the chapter's `/fall` |
+
+# Reading cluster state
+
+- v1 polls `list pods` and `list events` in `cv` every 2 seconds and diffs the result.
+ At about 10 pods this is cheap. Upgrade path: a client-go informer.
+- Recovery times come from the pod's Ready condition `lastTransitionTime`,
+ so they are exact even though polling is not.
+- Dependency: `k8s.io/client-go`. It authenticates through the in-cluster ServiceAccount.
+
+# SSE event shape
+
+```json
+{"chapter": "example", "phase": "Running", "ready": true, "restarts": 3, "event": "recovered", "seconds": 4.2}
+```
+
+The same stream feeds the life map and the developer view.
+
+# Limits
+
+- **Per-chapter cooldown:** a `map[string]time.Time` behind a mutex. Default 30 seconds.
+- **Global limit:** `golang.org/x/time/rate`, for example 1 fall per second with burst 3.
+- Knockdowns are shared state on purpose: every viewer sees "someone just knocked down X".
+
+# Cloudflare Tunnel and SSE
+
+- Send `Content-Type: text/event-stream` and flush after every message.
+- Send a comment line (`: ping`) every 30 seconds so idle connections are not closed.
+
+# RBAC
+
+ServiceAccount `gateway` in `cv`, Role with `get/list/watch` on `pods`,
+`events` and `jobs`. No create, delete or patch.
diff --git a/knowledge/architecture/index.md b/knowledge/architecture/index.md
new file mode 100644
index 0000000..3c70678
--- /dev/null
+++ b/knowledge/architecture/index.md
@@ -0,0 +1,8 @@
+# Architecture
+
+* [System](system.md) - All runtime components of the v1 site and how a request and a knockdown flow through them.
+* [Chapter service](chapter-service.md) - One small Go binary whose health behavior is set by the MODE env var; every life chapter runs it.
+* [Gateway](gateway.md) - The only public service; serves the static site, streams chapter states over SSE, and forwards rate-limited knockdowns.
+* [Frontend](frontend.md) - Nuxt site generated to static files and served by the gateway, with three audience layers fed by one SSE stream.
+* [Delivery](delivery.md) - Gitea Actions on the home server scan, build, push to the Gitea registry, deploy with kubectl, and version with release-please.
+* [In-browser language model](language-model.md) - A tiny language model trained by Noel that runs entirely in the visitor's browser and shows its internals live.
diff --git a/knowledge/architecture/language-model.md b/knowledge/architecture/language-model.md
new file mode 100644
index 0000000..482826b
--- /dev/null
+++ b/knowledge/architecture/language-model.md
@@ -0,0 +1,40 @@
+---
+type: Project
+title: In-browser language model
+description: A tiny language model trained by Noel that runs entirely in the visitor's browser and shows its internals live.
+tags: [architecture, ml, typescript, learning]
+status: draft
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Goal
+
+A from-scratch learning project on the same domain: a small transformer whose
+attention patterns, next-token probabilities and temperature are visible and
+adjustable in the browser.
+
+# Architecture
+
+No backend. A `/lm` page in the Nuxt build plus a weights file, both served
+statically by the [gateway](/architecture/gateway.md). It adds nothing to the cluster.
+
+# Plan
+
+| Step | What | Guide |
+|---|---|---|
+| Base model | About 5M parameters, layers written by hand, trained with PyTorch on TinyStories with word-piece tokens | Karpathy "Zero to Hero", llama2.c |
+| Browser inference | Forward pass in plain TypeScript | llama2.c |
+| Visuals | Attention heatmaps, next-token probabilities, temperature slider | |
+| Chat | Fine-tune at 15-30M parameters on simple dialogues in a fixed user/bot format | |
+| Own engine | Replace PyTorch gradients with Noel's own autograd | micrograd |
+
+# Expectations
+
+- TinyStories gives coherent short stories. Grimm gives stylish nonsense.
+- The chat handles greetings and small talk, not knowledge questions or long conversations.
+
+# Constraints
+
+- **Download size:** 5M parameters in fp32 is about 20 MB, 30M is about 120 MB.
+ Ship int8 weights (about 4× smaller) and load them lazily.
+- **PyTorch is new tooling** and needs Noel's approval under the stack rule.
diff --git a/knowledge/architecture/system.md b/knowledge/architecture/system.md
new file mode 100644
index 0000000..14c60de
--- /dev/null
+++ b/knowledge/architecture/system.md
@@ -0,0 +1,59 @@
+---
+type: Architecture
+title: System architecture
+description: All runtime components of the v1 site and how a request and a knockdown flow through them.
+tags: [architecture, k3s, go, nuxt]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Components
+
+| Component | Runs as | Job |
+|---|---|---|
+| Cloudflare Tunnel | `cloudflared` on the home server | Only way in from the internet. Points at the gateway. |
+| [Gateway](/architecture/gateway.md) | 1 Deployment, Go | Serves the static site, streams states, forwards knockdowns. The only public service. |
+| [Frontend](/architecture/frontend.md) | Static files inside the gateway image | Nuxt, built with `nuxt generate`. |
+| [Chapter service](/architecture/chapter-service.md) | One Deployment or Job per chapter | Behaves healthy, not-ready, crashing, or completed, set by env. |
+| [Delivery](/architecture/delivery.md) | Gitea Actions on the home server | Test, scan, build, push, deploy, version. |
+
+Everything runs in one namespace: `cv`.
+
+# Images
+
+Two images from one Go module:
+
+```
+cmd/gateway → image `gateway` (includes the Nuxt build)
+cmd/chapter → image `chapter`
+```
+
+# Flow: page load
+
+1. Visitor opens the apex domain. Cloudflare Tunnel forwards to the gateway Service.
+2. Gateway returns prerendered Nuxt HTML. The first screen works without JavaScript.
+3. The page opens `GET /api/events` (SSE) and receives the current state of every chapter, then every change.
+
+# Flow: knockdown
+
+1. Visitor clicks "Push this chapter": `POST /api/fall/{chapter}`.
+2. Gateway checks the allowlist, the per-chapter cooldown, and the global rate limit.
+3. Gateway calls `http://chapter-{chapter}.cv.svc/fall` over cluster DNS.
+4. The chapter process exits. The kubelet restarts it, `restartCount` goes up.
+5. Gateway sees the pod go not-ready, then ready again, and pushes both changes over SSE.
+6. Recovery time = Ready condition `lastTransitionTime` minus the fall time.
+7. The page shows the story card with the measured seconds.
+
+No step needs write access to the Kubernetes API.
+
+# Security boundaries
+
+- Only the gateway is reachable from outside.
+- Gateway ServiceAccount: `get/list/watch` on pods, events and jobs in `cv`. Nothing else.
+- `/fall` is unauthenticated inside the cluster. A NetworkPolicy (supported natively by k3s) restricts it to the gateway.
+- No visitor-supplied input reaches the cluster except a chapter name checked against an allowlist.
+
+# Accepted risk
+
+If the home server is down, the whole site is down. See
+[accept downtime in v1](/decisions/accept-downtime-v1.md).
diff --git a/knowledge/chapters/index.md b/knowledge/chapters/index.md
new file mode 100644
index 0000000..7188341
--- /dev/null
+++ b/knowledge/chapters/index.md
@@ -0,0 +1,7 @@
+# Chapters
+
+* [Chapter states](state-mapping.md) - How each Kubernetes primitive and state maps to a meaning in Noel's life story.
+
+# Chapter list
+
+Not written yet. One concept per chapter: dates, state, story, setback, recovery or lesson.
diff --git a/knowledge/chapters/state-mapping.md b/knowledge/chapters/state-mapping.md
new file mode 100644
index 0000000..5b34425
--- /dev/null
+++ b/knowledge/chapters/state-mapping.md
@@ -0,0 +1,30 @@
+---
+type: Reference
+title: Chapter states
+description: How each Kubernetes primitive and state maps to a meaning in Noel's life story.
+tags: [chapters, k3s, narrative]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Mapping
+
+| Kubernetes | Meaning | Example | Release |
+|---|---|---|---|
+| Job, Completed | Finished chapter | School, 42 piscine | v1 |
+| Deployment, Running and Ready | Active, stable chapter | PreZero, Example | v1 |
+| Running, NotReady | Exists, unfinished | Ongoing studies, thesis | v1 |
+| CrashLoopBackOff | Failed and stayed failed | Abandoned projects | v1 |
+| `restartCount` | Setbacks survived | "fell 3×, stood up 3×" | v1 |
+| Replicas, HPA scale-up | Load carried, growth under pressure | Team lead, two businesses | Phase 3 |
+| Rolling update | Pivot or reinvention | Career switch | Not planned yet |
+
+Finished chapters are Jobs because they complete. Current chapters are
+Deployments because they must stay alive.
+
+# Narrative rules
+
+- Every fall shows a story card: what went wrong and what got Noel back up.
+- The recovery time shown is real, measured in seconds.
+- Permanently failed chapters show a lesson card, not a recovery.
+- Failures are labeled as lessons, never as bugs.
diff --git a/knowledge/decisions/accept-downtime-v1.md b/knowledge/decisions/accept-downtime-v1.md
new file mode 100644
index 0000000..2ad5681
--- /dev/null
+++ b/knowledge/decisions/accept-downtime-v1.md
@@ -0,0 +1,25 @@
+---
+type: Decision
+title: Accept home-server downtime in v1
+description: v1 serves everything from the home server; if it is down, the whole site is down.
+tags: [decision, availability]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
+---
+
+# Decision
+
+Accept the risk. No off-box hosting, no snapshot persistence in v1.
+
+# Why
+
+- Off-box hosting (Cloudflare Pages, GitHub Pages) is new tooling and needs approval.
+- A snapshot fallback only helps when the server is up but the gateway is not,
+ which the static Nuxt data file already covers.
+- If the server is down, visitors see Cloudflare's error page. HR may hit it.
+
+# Revisit when
+
+The CV is actively sent to employers, or downtime is noticed in practice.
+The fix is hosting the static first screen off-box.
diff --git a/knowledge/decisions/bundle-in-subdirectory.md b/knowledge/decisions/bundle-in-subdirectory.md
new file mode 100644
index 0000000..c87fb23
--- /dev/null
+++ b/knowledge/decisions/bundle-in-subdirectory.md
@@ -0,0 +1,18 @@
+---
+type: Decision
+title: Knowledge bundle lives in knowledge/
+description: The OKF bundle sits in a subdirectory, not at the repository root.
+tags: [decision, okf]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Decision
+
+The OKF v0.2 bundle lives in `knowledge/`.
+
+# Why
+
+OKF requires frontmatter in every non-reserved `.md` file in the bundle. The
+repo root will hold files like `README.md` and release-please's `CHANGELOG.md`
+that have none, which would make a root-level bundle non-conformant.
diff --git a/knowledge/decisions/ci-on-gitea.md b/knowledge/decisions/ci-on-gitea.md
new file mode 100644
index 0000000..5cf0a5f
--- /dev/null
+++ b/knowledge/decisions/ci-on-gitea.md
@@ -0,0 +1,24 @@
+---
+type: Decision
+title: CI/CD on Gitea Actions
+description: The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
+tags: [decision, ci, gitea, release-please]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+verified: { by: human:noel, at: 2026-10-11T12:15:30Z }
+---
+
+# Decision
+
+Use Gitea Actions with the runner already on the home server, the Gitea
+container registry, and the Gitea variant of the release-please action.
+
+# Why
+
+- GitHub Actions cannot reach the k3s API behind the tunnel. The local runner can.
+- No new tooling: Gitea, its runner and its registry already exist.
+- No GitOps agent (Flux, Argo) needed.
+
+# Details
+
+See [delivery](/architecture/delivery.md).
diff --git a/knowledge/decisions/index.md b/knowledge/decisions/index.md
new file mode 100644
index 0000000..19a7e8e
--- /dev/null
+++ b/knowledge/decisions/index.md
@@ -0,0 +1,11 @@
+# Decisions
+
+* [v1 scope](v1-scope.md) - What the first public version keeps and what moves to later phases.
+* [Accept home-server downtime in v1](accept-downtime-v1.md) - v1 serves everything from the home server; if it is down, the whole site is down.
+* [Static Nuxt served by the gateway](static-nuxt-in-gateway.md) - Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
+* [CI/CD on Gitea Actions](ci-on-gitea.md) - The existing Gitea instance and runner on the home server build, scan, deploy and version the project.
+* [Knowledge bundle lives in knowledge/](bundle-in-subdirectory.md) - The OKF bundle sits in a subdirectory, not at the repository root.
+
+# Open
+
+* [Open questions](open-questions.md) - Decisions still to make, with the release that needs each answer.
diff --git a/knowledge/decisions/open-questions.md b/knowledge/decisions/open-questions.md
new file mode 100644
index 0000000..9c7dbaa
--- /dev/null
+++ b/knowledge/decisions/open-questions.md
@@ -0,0 +1,19 @@
+---
+type: Open Questions
+title: Open questions
+description: Decisions still to make, with the release that needs each answer.
+tags: [decision, open]
+status: draft
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+| Question | Needed by | Default if nobody decides |
+|---|---|---|
+| Final chapter list and the state of each chapter | 0.2.0 (placeholders), 1.0.0 (final) | Three placeholder chapters: one completed, one active, one failed |
+| Story card text per chapter | 1.0.0 | None, Noel writes it |
+| Life map visual form: timeline, graph or map | 0.7.0 | Vertical timeline |
+| Which Gitea release-please action, exact name | 0.1.0 | None, Noel names it |
+| Staging for k6 in CI: namespace or separate cluster | 1.2.0 | Namespace `cv-staging` on the same cluster |
+| MCP scope: read-only or read plus `/fall` | 1.1.0 | Read plus `/fall`, same limits as visitors |
+| Approve PyTorch for the language model | 1.5.0 | None, needs Noel |
+| Approve NumPy (or similar) for the own autograd engine | 1.13.0 | None, needs Noel |
diff --git a/knowledge/decisions/static-nuxt-in-gateway.md b/knowledge/decisions/static-nuxt-in-gateway.md
new file mode 100644
index 0000000..30116d1
--- /dev/null
+++ b/knowledge/decisions/static-nuxt-in-gateway.md
@@ -0,0 +1,26 @@
+---
+type: Decision
+title: Static Nuxt served by the gateway
+description: Nuxt is generated to static files and embedded in the gateway image instead of running as its own pod.
+tags: [decision, nuxt, go]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Decision
+
+Build with `nuxt generate`, embed the output in the gateway with `go:embed`.
+
+# Why
+
+- One less Deployment, no Node runtime in the cluster.
+- One public service, same origin for the site and `/api`, so no CORS.
+- The life map can still render from its data file when the live stream fails.
+
+# Cost
+
+Frontend and gateway release together in one image.
+
+# Revisit when
+
+The site needs server-side rendering per request.
diff --git a/knowledge/decisions/v1-scope.md b/knowledge/decisions/v1-scope.md
new file mode 100644
index 0000000..3590ec7
--- /dev/null
+++ b/knowledge/decisions/v1-scope.md
@@ -0,0 +1,32 @@
+---
+type: Decision
+title: v1 scope
+description: What the first public version keeps and what moves to later phases.
+tags: [decision, scope, roadmap]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Keep in v1
+
+- First screen: name, role, contact, PDF CV. Never gated behind interaction.
+- Life map with plain-word states and a "Push this chapter" button.
+- Story cards with real recovery seconds, lesson cards for failed chapters.
+- Live states: Completed, Ready, NotReady, CrashLoopBackOff, restart counts.
+- Gateway: SSE plus `/fall` with per-chapter cooldown and global rate limit.
+- "Someone just knocked down X" messages. Free, the SSE stream carries them.
+- Dev view: the raw event stream in a ``. Also free.
+- CI: Snyk, build, deploy, release-please.
+
+# Cut from v1
+
+| Cut | Why | Where it went |
+|---|---|---|
+| Separate Nuxt pod | Static build served by the gateway is simpler | [Decision](/decisions/static-nuxt-in-gateway.md) |
+| Snapshot persistence, offline banner | Downtime accepted for v1 | [Decision](/decisions/accept-downtime-v1.md) |
+| MCP endpoint | Cheap to add later, reuses `/fall` | Phase 2 |
+| k6 as a CI gate | Needs a staging target first | Phase 2 |
+| Full kubectl-style terminal (YAML, probes) | The raw stream covers it | Phase 2 |
+| Interactive k6, HPA demo, latency graph | Most work and most abuse risk | Phase 3 |
+| Rolling update as "pivot" | Nothing triggers it yet | Not planned |
+| client-go informer | Polling every 2 seconds is enough at about 10 pods | When polling falls short |
diff --git a/knowledge/index.md b/knowledge/index.md
index 0b6c434..2db42b7 100644
--- a/knowledge/index.md
+++ b/knowledge/index.md
@@ -2,22 +2,14 @@
okf_version: "0.2"
---
-# Project
+# Start here
-* [Overview](overview.md) - Interactive CV on k3s: falling down and standing up again, shown live.
-* [Roadmap](roadmap.md) - What ships in v1, v2 and v3, including the in-browser language model.
+* [Overview](overview.md) - A CV whose life chapters run as real Kubernetes workloads that visitors can knock down and watch recover.
+* [Roadmap](roadmap.md) - Small releases in three phases, each a few days of work at most, each ending in something that runs.
+* [Update log](log.md) - History of changes to this bundle.
-# Architecture
+# Drill down
-* [System](architecture/system.md) - Cloudflare Tunnel, Go gateway serving the static Nuxt build, chapter services in namespace `cv`.
-* [Chapter service](architecture/chapter-service.md) - One Go image, health behavior set by `MODE`, knockdown via `/fall`.
-* [Gateway](architecture/gateway.md) - Only public API: SSE pod states and rate-limited `/fall`.
-* [Delivery](architecture/delivery.md) - Gitea Actions: Snyk, build, Gitea registry, `kubectl apply -k`, release-please.
-
-# Decisions
-
-* [Decisions](decisions/) - Accepted trade-offs, such as v1 accepting home-server downtime.
-
-# Chapters
-
-* [Chapters](chapters/) - One concept per life chapter and its Kubernetes state.
+* [Architecture](architecture/) - Components, services, frontend, delivery, and the in-browser language model.
+* [Decisions](decisions/) - What we chose, what we cut, and what is still open.
+* [Chapters](chapters/) - How Kubernetes states map to life chapters, and later one concept per chapter.
diff --git a/knowledge/log.md b/knowledge/log.md
new file mode 100644
index 0000000..67a3a66
--- /dev/null
+++ b/knowledge/log.md
@@ -0,0 +1,5 @@
+# Update Log
+
+## 2026-10-11
+* **Creation**: Wrote the [overview](/overview.md), [architecture](/architecture/), [decisions](/decisions/), [chapter states](/chapters/state-mapping.md) and [roadmap](/roadmap.md) from the planning conversation.
+* **Initialization**: Created the bundle [index](/index.md).
diff --git a/knowledge/overview.md b/knowledge/overview.md
new file mode 100644
index 0000000..13f12a4
--- /dev/null
+++ b/knowledge/overview.md
@@ -0,0 +1,63 @@
+---
+type: Overview
+title: Interactive CV on k3s
+description: A CV whose life chapters run as real Kubernetes workloads that visitors can knock down and watch recover.
+tags: [overview, cv, k3s]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# In one sentence
+
+Noel's CV on the apex domain, where every life chapter is a workload on a
+home k3s cluster: visitors push a chapter over and watch it stand up again.
+The theme is **falling down and standing up again**.
+
+# Two audiences, one page
+
+| Audience | What they get |
+|---|---|
+| HR, 10 seconds | Name, role, contact, PDF CV. No interaction needed. |
+| Non-technical visitor | A life map of chapters in plain words, a "Push this chapter" button, and a story card after every fall. |
+| Developer | The raw live event stream from the cluster: pod states, restarts, recovery times. |
+
+# The idea in pictures
+
+| Kubernetes state | Life meaning |
+|---|---|
+| Job, Completed | Finished chapter (school, 42 piscine) |
+| Deployment, Running and Ready | Active chapter |
+| Running, NotReady | Exists but unfinished (studies, thesis) |
+| CrashLoopBackOff | An attempt that failed and stayed failed, shown as a lesson |
+| restartCount | Setbacks survived |
+
+Full mapping: [chapter states](/chapters/state-mapping.md).
+
+# How it works, high level
+
+```
+Visitor ─► Cloudflare Tunnel ─► Go gateway ─┬─ serves the Nuxt site (static files)
+ ├─ streams live chapter states (SSE)
+ └─ forwards "push" to a chapter's /fall
+ │
+ chapter services in namespace `cv`
+ (one Go image, behavior set by env)
+```
+
+When a chapter is pushed, its process exits, Kubernetes restarts it, and the
+page shows the real recovery time next to the story of how Noel recovered.
+
+# Drill down
+
+* [System architecture](/architecture/system.md) - every component and how they connect.
+* [Roadmap](/roadmap.md) - small releases, each a few days of work.
+* [Decisions](/decisions/) - what we chose and what we cut.
+* [Open questions](/decisions/open-questions.md) - what is still undecided.
+
+# Ground rules
+
+- **Learning project, ship small.** Each release is a few days of work.
+- **No tooling beyond the stack without Noel's approval.** The stack is Nuxt,
+ Go, k3s, Snyk, Gitea Actions, release-please, Cloudflare Tunnel, and k6.
+- **Nobody gets Kubernetes API access.** Visitors and agents only talk to the gateway.
+- **Failures are lessons, never bugs.**
diff --git a/knowledge/roadmap.md b/knowledge/roadmap.md
new file mode 100644
index 0000000..a9c50b9
--- /dev/null
+++ b/knowledge/roadmap.md
@@ -0,0 +1,197 @@
+---
+type: Roadmap
+title: Roadmap
+description: Small releases in three phases, each a few days of work at most, each ending in something that runs.
+tags: [roadmap, planning]
+status: stable
+generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z }
+---
+
+# Overview
+
+| Phase | Releases | Outcome |
+|---|---|---|
+| 1: Ship the CV | 0.1.0 - 1.0.0 | Public interactive CV on the apex domain |
+| 2: Depth | 1.1.0 - 1.7.0 | MCP, k6 release gate, full dev terminal, in-browser language model |
+| 3: Pressure and from scratch | 1.8.0 - 1.13.0 | Interactive load test with HPA, chat model, own autograd engine |
+
+| Release | Name | Days |
+|---|---|---|
+| 0.1.0 | Chapter service | 1-2 |
+| 0.2.0 | Chapters on k3s | 1-2 |
+| 0.3.0 | Pipeline | 2 |
+| 0.4.0 | Live states | 2-3 |
+| 0.5.0 | Knockdown | 1-2 |
+| 0.6.0 | First screen | 2 |
+| 0.7.0 | Life map | 3 |
+| 0.8.0 | Story cards and dev view | 2 |
+| 1.0.0 | Real content, launch | 2-3 |
+| 1.1.0 | MCP endpoint | 1 |
+| 1.2.0 | k6 release gate | 2 |
+| 1.3.0 | Dev terminal | 2 |
+| 1.4.0 | LM: data and tokenizer | 2-3 |
+| 1.5.0 | LM: model and training | 3 |
+| 1.6.0 | LM: browser inference | 3 |
+| 1.7.0 | LM: visuals | 2-3 |
+| 1.8.0 | Interactive k6 | 3 |
+| 1.9.0 | HPA demo | 2-3 |
+| 1.10.0 | LM: bigger base model | 2-3 |
+| 1.11.0 | LM: chat fine-tune | 3 |
+| 1.12.0 | Own autograd engine | 3 |
+| 1.13.0 | Train with own engine | 2-3 |
+
+Each release is cut by release-please from `feat:` commits. A release is done
+when its "done when" check passes on the real cluster, not locally.
+
+---
+
+# Phase 1: Ship the CV
+
+## 0.1.0 Chapter service
+
+- Go module with `cmd/chapter`: `/healthz`, `/ready`, `/fall`, behavior from `MODE`. See [chapter service](/architecture/chapter-service.md).
+- Dockerfile, distroless or scratch base.
+- One `go test` that checks `/ready` per `MODE`.
+- release-please config, manifest and Gitea workflow, so this release is the first one it cuts.
+- **Done when:** `docker run -e MODE=not-ready` answers 503 on `/ready`, and `POST /fall` ends the container with exit code 1.
+- **Learn:** Go `net/http`, container basics, Conventional Commits.
+
+## 0.2.0 Chapters on k3s
+
+- Namespace `cv`, four placeholder chapters: one Job (`complete`), one each of `healthy`, `not-ready`, `crash`.
+- Services with `publishNotReadyAddresses: true`, resource limits, pod label `cv.noelsabia.dev/chapter`.
+- Registry pull from Gitea, `kubectl apply -k deploy/`.
+- **Done when:** `kubectl get pods -n cv` shows Completed, Running 1/1, Running 0/1 and CrashLoopBackOff, and a `/fall` from a debug pod raises `restartCount`.
+- **Learn:** Deployments, Jobs, probes, Services, kustomize.
+
+## 0.3.0 Pipeline
+
+- Gitea workflow: `go test`, `snyk test`, build and push images tagged with the git SHA, `kubectl apply -k`.
+- Runner kubeconfig limited to namespace `cv`.
+- **Done when:** a push to `main` deploys a new image without touching the server by hand.
+- **Learn:** Gitea Actions, RBAC for CI, Snyk.
+
+## 0.4.0 Live states
+
+- `cmd/gateway`: polls pods and events every 2 seconds, streams changes on `GET /api/events` with a 30-second ping.
+- ServiceAccount with read-only Role. Cloudflare Tunnel route to the gateway.
+- A bare HTML page that prints the stream.
+- **Done when:** the public URL shows a chapter going not-ready and back after `kubectl delete pod`.
+- **Learn:** client-go, in-cluster auth, SSE, Cloudflare Tunnel.
+
+## 0.5.0 Knockdown
+
+- `POST /api/fall/{chapter}`: allowlist, 30-second per-chapter cooldown, global `rate.Limiter`.
+- Recovery time from the Ready condition's `lastTransitionTime`.
+- "fell" and "recovered" events with seconds in the stream.
+- NetworkPolicy: only the gateway can reach chapter `/fall`.
+- One test for the cooldown and limiter logic.
+- **Done when:** a POST knocks a chapter over, a second POST within 30 seconds gets 429, and the stream shows the recovery seconds.
+- **Learn:** rate limiting, NetworkPolicy, measuring with Kubernetes conditions.
+
+## 0.6.0 First screen
+
+- Nuxt project, `nuxt generate`, multi-stage Dockerfile that embeds the output in the gateway.
+- Layer 0: name, role, contact, PDF CV download. Navy `#1A3D64` and white.
+- **Done when:** the page loads and the PDF downloads with JavaScript disabled.
+- **Learn:** Nuxt static generation, `go:embed`, multi-stage builds.
+
+## 0.7.0 Life map
+
+- Chapter data file in Nuxt keyed by chapter name.
+- Life map (default: vertical timeline) with plain-word states from the stream and a "Push this chapter" button.
+- Falls back to the data file with a "live cluster offline" note when the stream fails.
+- **Done when:** a non-technical person can push a chapter and say what happened.
+- **Learn:** Nuxt components, `EventSource`, degrading gracefully.
+
+## 0.8.0 Story cards and dev view
+
+- Story card on every fall with the measured seconds. Lesson card for CrashLoopBackOff chapters.
+- "Someone just knocked down X" message when another visitor pushes.
+- Dev view: the raw stream in a ``.
+- **Done when:** two browsers see each other's knockdowns live.
+
+## 1.0.0 Real content and launch
+
+- Final chapter list, one manifest per chapter, story text, final PDF CV.
+- Point the apex domain at the tunnel.
+- One `knowledge/chapters/.md` concept per chapter.
+- **Done when:** someone from HR finds the PDF within 10 seconds, and the live map shows every real chapter.
+
+---
+
+# Phase 2: Depth
+
+## 1.1.0 MCP endpoint
+
+- MCP on the gateway: a tool to read states, a tool to push a chapter, same limits as visitors.
+- The brief caps this at under 2 hours of work without AI. If it takes longer, drop it.
+- **Done when:** an agent can list chapters and push one.
+
+## 1.2.0 k6 release gate
+
+- Namespace `cv-staging`, deploy there first in CI, run a fixed k6 script, fail the pipeline on the p95 threshold.
+- Badge on the site: "p95 < X ms, last run".
+- **Done when:** a deliberately slow build blocks the release.
+
+## 1.3.0 Dev terminal
+
+- kubectl-style view: events, probe results, restart history, YAML per chapter (read-only `get` through the gateway).
+- **Done when:** a developer can inspect any chapter's state without the cluster.
+
+## 1.4.0 LM: data and tokenizer
+
+- TinyStories download, word-piece tokenizer written by hand, train/validation split.
+- **Done when:** encode then decode round-trips the validation set.
+
+## 1.5.0 LM: model and training
+
+- About 5M-parameter transformer, layers written by hand, gradients from PyTorch (needs approval).
+- Training run on the home server CPU, checkpoint saved.
+- **Done when:** samples read like short simple stories.
+
+## 1.6.0 LM: browser inference
+
+- Export int8 weights, forward pass in plain TypeScript on `/lm`.
+- **Done when:** TypeScript logits match PyTorch logits within a small tolerance for the same input.
+
+## 1.7.0 LM: visuals
+
+- Attention heatmaps per head, next-token probability bars, temperature slider.
+- **Done when:** moving the slider visibly changes the probability bars and the generated text.
+
+---
+
+# Phase 3: Pressure and from scratch
+
+## 1.8.0 Interactive k6
+
+- Fixed k6 script run as a Job with the `grafana/k6` image, capped virtual users and duration.
+- One run at a time across the site. No visitor-supplied parameters.
+- The gateway needs `create` on Jobs for this, the first write permission it gets. Limit it to this one Job template.
+- **Done when:** a second visitor sees "a test is already running".
+
+## 1.9.0 HPA demo
+
+- HPA on one chapter using metrics-server (ships with k3s), live replica count and latency graph during a k6 run.
+- **Done when:** replicas go up during a run and back down after.
+
+## 1.10.0 LM: bigger base model
+
+- Retrain the base model at 15-30M parameters. Check training time on the CPU first.
+- **Done when:** samples are clearly better than the 5M model.
+
+## 1.11.0 LM: chat fine-tune
+
+- Fine-tune on simple dialogues in a fixed user/bot format.
+- **Done when:** it answers greetings and small talk in the browser.
+
+## 1.12.0 Own autograd engine
+
+- Tensor autograd written by Noel, likely on NumPy (needs approval).
+- **Done when:** gradients match PyTorch on a small model.
+
+## 1.13.0 Train with own engine
+
+- Train the 5M model with the own engine instead of PyTorch.
+- **Done when:** loss curves roughly match the PyTorch run.