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 <noreply@anthropic.com>
This commit is contained in:
Noel SabiaandClaude Opus 5.5 committed 2026-10-11 14:22:03 +02:00
1 parent 957a386b58
commit 64fef83314
22 files changed
+37 -153

No files matched your search

+25
View File
@@ -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.
+24
View File
@@ -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.
+24
View File
@@ -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).
+11
View File
@@ -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 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
* [Open questions](open-questions.md) - Decisions still to make, with the release that needs each answer.
+19
View File
@@ -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 |
+26
View File
@@ -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.
+32
View File
@@ -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 `<pre>`. 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 |