From 01cab5a565b8bf617a2515ad11f70bf44ff3dce0 Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Wed, 14 Oct 2026 21:54:40 +0200 Subject: [PATCH] docs(okf): rebuild roadmap for Terraform, own proxy and WebMCP insert 0.2.0 Terraform server and 0.4.0 reverse proxy/DNS, renumber releases, fold story cards into 0.9.0 and tracker into 1.0.0; release 1.1.0 becomes WebMCP from the Nuxt page (server-side MCP endpoint dropped); update open questions, v1 scope and log --- decisions/open-questions.md | 13 +++-- decisions/v1-scope.md | 2 +- log.md | 6 ++ roadmap.md | 106 ++++++++++++++++++------------------ 4 files changed, 66 insertions(+), 61 deletions(-) diff --git a/decisions/open-questions.md b/decisions/open-questions.md index 97e094a..9eb89fb 100644 --- a/decisions/open-questions.md +++ b/decisions/open-questions.md @@ -9,11 +9,12 @@ 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) | Four placeholder chapters: one completed, one active, one unfinished, 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 | +| Final chapter list and the state of each chapter | 0.3.0 (placeholders), 1.0.0 (final) | Four placeholder chapters: one completed, one active, one unfinished, one failed | +| Story card text per chapter | 0.9.0 | None, Noel writes it | +| Life map visual form: timeline, graph or map | 0.9.0 | Vertical timeline | +| Approve Terraform for server provisioning | 0.2.0 | Do it, infra as code is the point | +| How the server is reachable: router port-forward, static IP or DDNS | 0.4.0 | DDNS + port-forward 80/443 | +| k6 staging target: namespace or separate cluster | 1.2.0 | Namespace `cv-staging` on the same cluster | +| WebMCP scope: state read-only, or state plus push | 1.1.0 | State plus push, 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/decisions/v1-scope.md b/decisions/v1-scope.md index 3590ec7..e68f1d0 100644 --- a/decisions/v1-scope.md +++ b/decisions/v1-scope.md @@ -24,7 +24,7 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } |---|---|---| | 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 | +| Server-side MCP endpoint on the gateway | Replaced by WebMCP from the Nuxt page: agents use the same public API, the gateway gains no new authority | Phase 2 (1.1.0) | | 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 | diff --git a/log.md b/log.md index ecbcda3..ccb3400 100644 --- a/log.md +++ b/log.md @@ -1,5 +1,11 @@ # Update Log +## 2026-10-14 +* **Direction change**: No Cloudflare Tunnel. The apex domain points straight at the home server; nginx (installed by Terraform with certbot TLS) is the only public entry. See [own proxy](/decisions/own-proxy.md). +* **Decision**: Add [Terraform provisioning](/architecture/terraform.md): packages, swap, k3s, nginx and DNS are code; workloads inside the cluster stay with kustomize. See [decision](/decisions/provision-with-terraform.md). +* **Update**: Rebuilt the [roadmap](/roadmap.md) around the new direction: Terraform server (0.2.0), reverse proxy and DNS (0.4.0), renumbered releases, and story cards folded into the life map release. +* **Decision**: Server-side MCP endpoint on the gateway is out. Replaced by WebMCP on the Nuxt page (release 1.1.0): the page exposes read-state and push tools to an agent in the browser, calling the same public gateway API with the same limits. + ## 2026-10-11 * **Update**: Replaced the GoatCounter proposal with Noel's [own tracker on SQLite](/decisions/own-tracker.md). * **Creation**: Added the [server and memory budget](/architecture/server-budget.md) from measured usage, and proposed GoatCounter over Umami (since replaced by the [own tracker](/decisions/own-tracker.md)). diff --git a/roadmap.md b/roadmap.md index b38445d..f512f31 100644 --- a/roadmap.md +++ b/roadmap.md @@ -1,10 +1,10 @@ --- type: Roadmap title: Roadmap -description: Small releases in three phases, each a few days of work at most, each ending in something that runs. +description: Rebuilt plan - Terraform-provisioned server, self-run nginx proxy, and the original release track on top. Each release is a few days of work and ends in something that runs. tags: [roadmap, planning] -status: stable -generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } +status: revised +generated: { by: claude-code/claude-opus-5-5, at: 2026-10-14T00:00:00Z } --- # Overview @@ -12,22 +12,22 @@ generated: { by: claude-code/claude-opus-5-5, at: 2026-10-11T12:15:30Z } | 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 | Tiny interactive load test with HPA, chat model, own autograd engine | +| 2: Depth | 1.1.0 - 1.7.0 | WebMCP, k6 release gate, 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 | 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 | -| 0.9.0 | Own tracker | 1-2 | -| 1.0.0 | Real content, launch | 2-3 | -| 1.1.0 | MCP endpoint | 1 | +| 0.2.0 | Terraform server | 2-3 | +| 0.3.0 | Chapters on k3s | 2 | +| 0.4.0 | Reverse proxy and DNS | 1-2 | +| 0.5.0 | Pipeline | 2 | +| 0.6.0 | Live states | 2-3 | +| 0.7.0 | Knockdown | 1-2 | +| 0.8.0 | First screen | 2 | +| 0.9.0 | Life map and story cards | 3-4 | +| 1.0.0 | Own tracker, real content, launch | 3-4 | +| 1.1.0 | WebMCP | 2 | | 1.2.0 | k6 release gate | 2 | | 1.3.0 | Dev terminal | 2 | | 1.4.0 | LM: data and tokenizer | 2-3 | @@ -60,32 +60,44 @@ stays inside the [memory budget](/architecture/server-budget.md). - **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 +## 0.2.0 Terraform server -- 2 GB swap file, k3s installed with traefik and servicelb disabled and kubelet reservations. See [server budget](/architecture/server-budget.md). -- ResourceQuota (384Mi) and LimitRange on namespace `cv`. -- Four placeholder chapters: one Job (`complete`), one each of `healthy`, `not-ready`, `crash`. +- Terraform module that rebuilds server0 from nothing: packages, 2 GB swap file, k3s installed with traefik and servicelb disabled, kubelet reservations, and the `imagePullSecret` for the Gitea registry. See [terraform provisioning](/architecture/terraform.md). +- Terraform also creates namespace `cv` with the ResourceQuota (384Mi) and LimitRange, and the DNS A record for the apex domain. +- State file stays local; `plan` output is reviewed before every apply. +- **Done when:** `terraform destroy` then `terraform apply` on a blank server0 leaves k3s running, swap active, namespace `cv` with its quota on a fresh server. No hand steps. +- **Learn:** Terraform (providers, provisioners, plan/apply, state), cloud-init/SSH provisioning, why infra as code beats hand setup. + +## 0.3.0 Chapters on k3s + +- Four placeholder chapters applied with `kubectl apply -k deploy/`: 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, resource limits and quotas. -## 0.3.0 Pipeline +## 0.4.0 Reverse proxy and DNS + +- nginx (installed and templated by the Terraform module from 0.2.0) is the only public entry: TLS via certbot. Until the gateway exists it forwards to a placeholder. +- Router port-forward, static IP or DDNS, per [own proxy](/decisions/own-proxy.md). +- **Done when:** the apex domain loads over HTTPS from outside the home network, certificate auto-renews, and a `terraform destroy` on the network config is recovered by re-applying Terraform. +- **Learn:** reverse proxies, TLS/certbot, DNS records, port-forwarding. + +## 0.5.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`. Runner capacity 1, so builds never run in parallel. - **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 +## 0.6.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. +- ServiceAccount with read-only Role. nginx route now points at the gateway for real. - 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. +- **Learn:** client-go, in-cluster auth, SSE, serving through a self-run proxy. -## 0.5.0 Knockdown +## 0.7.0 Knockdown - `POST /api/fall/{chapter}`: allowlist, 30-second per-chapter cooldown, global `rate.Limiter`. - Recovery time from the Ready condition's `lastTransitionTime`. @@ -95,53 +107,39 @@ stays inside the [memory budget](/architecture/server-budget.md). - **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 +## 0.8.0 First screen -- Nuxt project, `nuxt generate` with `NODE_OPTIONS=--max-old-space-size=512`, multi-stage Dockerfile that embeds the output in the gateway. +- Nuxt project, `nuxt generate` with `NODE_OPTIONS=--max-old-space-size=512`, multi-stage Dockerfile that embeds the output in the gateway image. - 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 +## 0.9.0 Life map and story cards - 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. +- Story card on every fall with the measured seconds. Lesson card for CrashLoopBackOff chapters. Falls back to the data file with a "live cluster offline" note when the stream fails. +- Dev view: the raw stream in a `
`.
+- **Done when:** a non-technical person can push a chapter, say what happened, and two browsers see each other's knockdowns live.
 - **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.
-
-## 0.9.0 Own tracker
-
-- Gateway middleware writing daily totals to SQLite (`modernc.org/sqlite`) on a `local-path` volume. See [decision](/decisions/own-tracker.md).
-- Count page views, PDF downloads and falls per chapter. No IPs, no cookies.
-- Gateway Deployment switches to strategy `Recreate`.
-- One test for the upsert and the bot filter.
-- **Done when:** a test visit, a PDF download and a fall each raise their count in the SQLite file.
-- **Learn:** SQLite, Go `database/sql`, HTTP middleware, privacy by design.
-
-## 1.0.0 Real content and launch
+## 1.0.0 Own tracker and launch
 
+- Gateway middleware writing daily totals to SQLite (`modernc.org/sqlite`) on a `local-path` volume. See [decision](/decisions/own-tracker.md). Count page views, PDF downloads and falls per chapter. No IPs, no cookies. Deployment strategy `Recreate`.
 - Final chapter list, one manifest per chapter, story text, final PDF CV.
-- Point the apex domain at the tunnel.
-- One `chapters/.md` concept per chapter.
-- **Done when:** someone from HR finds the PDF within 10 seconds, and the live map shows every real chapter.
+- **Done when:** someone from HR finds the PDF within 10 seconds, the live map shows every real chapter, and a test visit, a PDF download and a fall each raise their count in the SQLite file.
+- **Learn:** SQLite, Go `database/sql`, HTTP middleware, privacy by design, finishing work.
 
 ---
 
 # Phase 2: Depth
 
-## 1.1.0 MCP endpoint
+## 1.1.0 WebMCP
 
-- 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.
+- No server-side MCP endpoint. Instead, the Nuxt page itself exposes tools over WebMCP (the browser-native agent interface): a tool to read chapter states and a tool to push a chapter.
+- Under the hood the tools call the same public gateway API, so agents get exactly the limits visitors get. The gateway gains no new authority.
+- **Done when:** an agent in the browser can list chapters and push one, and the gateway counts and rate-limits it like any other visitor.
+- **Learn:** WebMCP, agent-facing tool design, least-privilege agency.
 
 ## 1.2.0 k6 release gate