From 64fef83314d6d2b5c7840ebd8903408bfac49f6a Mon Sep 17 00:00:00 2001 From: Noel Sabia Date: Sun, 11 Oct 2026 14:22:03 +0200 Subject: [PATCH] docs(okf): move bundle to repo root and retire brief The brief is fully captured in the bundle; it stays in git history. Co-Authored-By: Claude Opus 5.5 --- .../chapter-service.md | 0 .../architecture => architecture}/delivery.md | 0 .../architecture => architecture}/frontend.md | 0 .../architecture => architecture}/gateway.md | 0 .../architecture => architecture}/index.md | 0 .../language-model.md | 0 .../architecture => architecture}/system.md | 0 brief.md | 133 ------------------ {knowledge/chapters => chapters}/index.md | 0 .../chapters => chapters}/state-mapping.md | 0 .../accept-downtime-v1.md | 0 decisions/bundle-at-root.md | 24 ++++ .../decisions => decisions}/ci-on-gitea.md | 0 {knowledge/decisions => decisions}/index.md | 2 +- .../decisions => decisions}/open-questions.md | 0 .../static-nuxt-in-gateway.md | 0 .../decisions => decisions}/v1-scope.md | 0 knowledge/index.md => index.md | 0 knowledge/decisions/bundle-in-subdirectory.md | 18 --- knowledge/log.md => log.md | 1 + knowledge/overview.md => overview.md | 10 ++ knowledge/roadmap.md => roadmap.md | 2 +- 22 files changed, 37 insertions(+), 153 deletions(-) rename {knowledge/architecture => architecture}/chapter-service.md (100%) rename {knowledge/architecture => architecture}/delivery.md (100%) rename {knowledge/architecture => architecture}/frontend.md (100%) rename {knowledge/architecture => architecture}/gateway.md (100%) rename {knowledge/architecture => architecture}/index.md (100%) rename {knowledge/architecture => architecture}/language-model.md (100%) rename {knowledge/architecture => architecture}/system.md (100%) delete mode 100644 brief.md rename {knowledge/chapters => chapters}/index.md (100%) rename {knowledge/chapters => chapters}/state-mapping.md (100%) rename {knowledge/decisions => decisions}/accept-downtime-v1.md (100%) create mode 100644 decisions/bundle-at-root.md rename {knowledge/decisions => decisions}/ci-on-gitea.md (100%) rename {knowledge/decisions => decisions}/index.md (78%) rename {knowledge/decisions => decisions}/open-questions.md (100%) rename {knowledge/decisions => decisions}/static-nuxt-in-gateway.md (100%) rename {knowledge/decisions => decisions}/v1-scope.md (100%) rename knowledge/index.md => index.md (100%) delete mode 100644 knowledge/decisions/bundle-in-subdirectory.md rename knowledge/log.md => log.md (63%) rename knowledge/overview.md => overview.md (84%) rename knowledge/roadmap.md => roadmap.md (99%) diff --git a/knowledge/architecture/chapter-service.md b/architecture/chapter-service.md similarity index 100% rename from knowledge/architecture/chapter-service.md rename to architecture/chapter-service.md diff --git a/knowledge/architecture/delivery.md b/architecture/delivery.md similarity index 100% rename from knowledge/architecture/delivery.md rename to architecture/delivery.md diff --git a/knowledge/architecture/frontend.md b/architecture/frontend.md similarity index 100% rename from knowledge/architecture/frontend.md rename to architecture/frontend.md diff --git a/knowledge/architecture/gateway.md b/architecture/gateway.md similarity index 100% rename from knowledge/architecture/gateway.md rename to architecture/gateway.md diff --git a/knowledge/architecture/index.md b/architecture/index.md similarity index 100% rename from knowledge/architecture/index.md rename to architecture/index.md diff --git a/knowledge/architecture/language-model.md b/architecture/language-model.md similarity index 100% rename from knowledge/architecture/language-model.md rename to architecture/language-model.md diff --git a/knowledge/architecture/system.md b/architecture/system.md similarity index 100% rename from knowledge/architecture/system.md rename to architecture/system.md diff --git a/brief.md b/brief.md deleted file mode 100644 index 18d7de0..0000000 --- a/brief.md +++ /dev/null @@ -1,133 +0,0 @@ -# Interactive CV on k3s: Planning Brief - -Handoff document for further planning. Owner: Noel Sabia. - -## 1. Goal - -A creative, interactive CV on the apex of Noel's main domain. It must work for two audiences: - -- **Non-technical HR:** understandable without any coding knowledge. -- **Programmers:** real infrastructure, inspectable, technically credible. - -Core life lesson: **falling down and standing up again.** It is shown live on a k3s cluster running on Noel's home server. - -## 2. Fixed constraints (already decided) - -| Area | Decision | -|---|---| -| Frontend | Nuxt | -| Backend | Multiple Go microservices | -| Orchestration | k3s on home server (Ryzen 5, 24 GB RAM) | -| Security | Snyk | -| Delivery | CI/CD pipeline, release-please for versioning | -| Exposure | Cloudflare Tunnel | -| Design | Drafted with Stitch prompts. Terminal/IT feel, usable by non-IT visitors. | -| Brand | Navy #1A3D64 and white. Logo has a "broken pieces" look, which fits the fall/recover theme. | -| AI access | MCP-ready, so agents can read states and trigger a fall. Only include it if it is doable in under 2 hours without AI. Keep it minimal. | -| Tooling rule | **Any tooling beyond this stack needs Noel's approval before it enters the spec.** k6 is approved by Noel. | - -## 3. Core concept - -- Each life chapter runs as its own microservice or workload in k3s. -- Some chapters stay unhealthy on purpose. -- Visitors interactively knock chapters down and watch Kubernetes bring them back up. -- k6 load testing is integrated on the side. - -### Kubernetes state to life meaning - -| K8s primitive / state | Meaning | Example use | -|---|---|---| -| `Job` → Completed | Finished chapter | School, 42 piscine | -| `Deployment` → Running + Ready | Active, stable chapter | PreZero, Example | -| Running, **NotReady** (readiness fails on purpose) | Exists, unfinished | Ongoing studies, thesis | -| `CrashLoopBackOff` (permanent) | Attempt that failed and stayed failed | Abandoned projects, dead ends | -| `restartCount` | Setbacks survived | "fell 3×, stood up 3×" | -| Replicas / HPA scale-up | Load carried, growth under pressure | Team lead, two businesses in parallel | -| Rolling update / new revision | Pivot or reinvention | Career switch, new role | - -Key structural choice: finished chapters run as **Jobs** (they complete), and current chapters run as **Deployments** (they must stay alive). - -## 4. Audience layers (one data source, different rendering) - -| Layer | Audience | Content | -|---|---|---| -| 0: First screen | HR, 10-second skim | Name, role, contact, **static PDF CV download**. Never gated behind interaction. | -| 1: Life map | Non-technical | Timeline or graph of chapters. States in plain words ("recovering", "unfinished", "failed, lesson learned"). A "Push this chapter" button. | -| 2: Terminal | Developers | kubectl-style view: events, probes, restart history, YAML per chapter, live k6 results | - -## 5. Architecture - -``` -Visitor ─► Cloudflare Tunnel ─► Nuxt - │ SSE/WebSocket (state) - ▼ - Go gateway (only public API) - ├─ watch: read-only informer on namespace `cv` - ├─ actions: allowlisted, rate-limited - └─ MCP endpoint (same actions, same limits) - │ - ┌────────────────────┼────────────────────┐ - chapter-svc (Go) chapter-svc (Go) k6 Job (on demand) - /healthz /ready /fall -``` - -- **One Go chapter-service template.** Its health behavior is set by env config: `healthy`, `not-ready` or `crash`. -- **Knockdown via `/fall` on the service itself.** The process exits or fails its liveness probe, and the kubelet restarts it. This needs no delete permission on the cluster. -- **Gateway ServiceAccount:** scoped to namespace `cv`, read-only `get/list/watch` on pods, events and jobs. - -## 6. Non-negotiable rules - -- No visitor or agent gets Kubernetes API access. Everything goes through the gateway. -- Per-chapter cooldown and a global rate limit, so one visitor cannot hold everything down. -- Shared cluster state is a feature. Show messages like "someone just knocked down Example". -- Offline fallback: the gateway persists the last known state, and Nuxt renders a static snapshot with a "live cluster offline" banner. HR never sees an error page. -- Permanently unhealthy services get resource limits and a long backoff, so they don't waste CPU. - -## 7. Narrative layer - -- Every fall triggers a story card: what went wrong in that chapter and what got Noel back up. -- The time to recover is real measured seconds, shown next to the story. -- Permanently failed chapters show a "lesson" card instead of a recovery. -- Failures must be labeled explicitly as lessons, never as bugs. - -## 8. k6 integration - -| Use | Implementation | Visitor sees | -|---|---|---| -| Real engineering | k6 in CI against staging. Performance thresholds gate release-please releases. | Badge: "p95 < X ms, last run" | -| Interactive pressure test | Predefined script run as a k8s `Job` with the `grafana/k6` image. Capped VUs and duration, one run at a time across the whole site. | HPA scales replicas up and down live, with a latency graph | -| Dev layer | Raw k6 summary streamed to the terminal view | Full metrics | - -- HPA uses metrics-server, which ships with k3s by default. No extra tooling. -- No k6 operator; a plain Job is enough. The operator would be extra tooling and needs approval. -- Never allow visitor-defined k6 scripts or parameters. That would turn the site into a DoS tool against the home server. - -## 9. Build order - -1. Go chapter-service template with `/healthz`, `/ready` and `/fall`, configured by env. -2. Manifests for all chapters (Jobs plus Deployments), with states set through config. -3. Go gateway: informer, SSE, allowlisted actions, rate limits, snapshot persistence. -4. Nuxt Layer 0, plus Layer 1 life map and story cards. -5. Layer 2 terminal view. -6. k6: first as a CI gate, then as the bounded interactive Job, then the HPA demo. -7. MCP endpoint on the gateway, reusing the action allowlist. - -## 10. Risks - -| Risk | Mitigation | -|---|---| -| HR confusion | Layer 0 is conventional and complete on its own. The interactive part is optional. | -| Spectacle without substance | Every state change links to a story card | -| Home server downtime | Snapshot fallback, plus Layer 0 served statically | -| Abuse | Cooldowns, global k6 lock, no raw cluster exposure | -| "Unhealthy" read as incompetence | Failures labeled as lessons | - -## 11. Open decisions - -- Final chapter list and the state assigned to each chapter (completed, active, unfinished, permanently failed). -- Story card content per chapter: the setback and the recovery. -- Life map visual form: timeline, graph or map. -- Where state snapshots persist: file, ConfigMap or a database. Any new database needs approval. -- Staging environment for k6 in CI: a separate namespace or a separate cluster. -- Scope of the MCP endpoint: read-only, or read plus `/fall`. -- Whether Layer 0 is served by Nuxt or as a fully static page outside the cluster for maximum uptime. \ No newline at end of file diff --git a/knowledge/chapters/index.md b/chapters/index.md similarity index 100% rename from knowledge/chapters/index.md rename to chapters/index.md diff --git a/knowledge/chapters/state-mapping.md b/chapters/state-mapping.md similarity index 100% rename from knowledge/chapters/state-mapping.md rename to chapters/state-mapping.md diff --git a/knowledge/decisions/accept-downtime-v1.md b/decisions/accept-downtime-v1.md similarity index 100% rename from knowledge/decisions/accept-downtime-v1.md rename to decisions/accept-downtime-v1.md diff --git a/decisions/bundle-at-root.md b/decisions/bundle-at-root.md new file mode 100644 index 0000000..ac9e72d --- /dev/null +++ b/decisions/bundle-at-root.md @@ -0,0 +1,24 @@ +--- +type: Decision +title: Knowledge bundle lives at the repository root +description: The repository root is the OKF bundle root; any other markdown file there needs frontmatter to stay conformant. +tags: [decision, okf] +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 + +The OKF v0.2 bundle root is the repository root. + +# Consequence + +OKF requires frontmatter with a `type` in every non-reserved `.md` file in the +bundle. Any other markdown at the root breaks conformance unless it carries +frontmatter, for example: + +- `README.md`: give it frontmatter (`type: Readme`) or skip it; `index.md` already does its job. +- `CHANGELOG.md` from release-please: release-please writes it without + frontmatter. Options: point release-please's `changelog-path` at a non-`.md` + file, or accept that one file is non-conformant. diff --git a/knowledge/decisions/ci-on-gitea.md b/decisions/ci-on-gitea.md similarity index 100% rename from knowledge/decisions/ci-on-gitea.md rename to decisions/ci-on-gitea.md diff --git a/knowledge/decisions/index.md b/decisions/index.md similarity index 78% rename from knowledge/decisions/index.md rename to decisions/index.md index 19a7e8e..f0dd6bd 100644 --- a/knowledge/decisions/index.md +++ b/decisions/index.md @@ -4,7 +4,7 @@ * [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. +* [Knowledge bundle lives at the repository root](bundle-at-root.md) - The repository root is the OKF bundle root; any other markdown file there needs frontmatter to stay conformant. # Open diff --git a/knowledge/decisions/open-questions.md b/decisions/open-questions.md similarity index 100% rename from knowledge/decisions/open-questions.md rename to decisions/open-questions.md diff --git a/knowledge/decisions/static-nuxt-in-gateway.md b/decisions/static-nuxt-in-gateway.md similarity index 100% rename from knowledge/decisions/static-nuxt-in-gateway.md rename to decisions/static-nuxt-in-gateway.md diff --git a/knowledge/decisions/v1-scope.md b/decisions/v1-scope.md similarity index 100% rename from knowledge/decisions/v1-scope.md rename to decisions/v1-scope.md diff --git a/knowledge/index.md b/index.md similarity index 100% rename from knowledge/index.md rename to index.md diff --git a/knowledge/decisions/bundle-in-subdirectory.md b/knowledge/decisions/bundle-in-subdirectory.md deleted file mode 100644 index c87fb23..0000000 --- a/knowledge/decisions/bundle-in-subdirectory.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -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/log.md b/log.md similarity index 63% rename from knowledge/log.md rename to log.md index 67a3a66..46ab92d 100644 --- a/knowledge/log.md +++ b/log.md @@ -1,5 +1,6 @@ # Update Log ## 2026-10-11 +* **Update**: Moved the bundle from `knowledge/` to the repository root and replaced the planning brief with this bundle. See [bundle at root](/decisions/bundle-at-root.md). * **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/overview.md similarity index 84% rename from knowledge/overview.md rename to overview.md index 13f12a4..a17f14d 100644 --- a/knowledge/overview.md +++ b/overview.md @@ -61,3 +61,13 @@ page shows the real recovery time next to the story of how Noel recovered. 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.** + +# Risks + +| Risk | Mitigation | +|---|---| +| HR confusion | The first screen is conventional and complete on its own. The interactive part is optional. | +| Spectacle without substance | Every state change links to a story card. | +| Home server downtime | Accepted for v1, see [decision](/decisions/accept-downtime-v1.md). | +| Abuse | Cooldowns, global rate limit, no raw cluster access, no visitor-defined k6 scripts. | +| "Unhealthy" read as incompetence | Failures are labeled as lessons. | diff --git a/knowledge/roadmap.md b/roadmap.md similarity index 99% rename from knowledge/roadmap.md rename to roadmap.md index a9c50b9..01f7213 100644 --- a/knowledge/roadmap.md +++ b/roadmap.md @@ -115,7 +115,7 @@ when its "done when" check passes on the real cluster, not locally. - 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. +- 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. ---