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:
1 parent
957a386b58
commit
64fef83314
22 files changed
+37
-153
No files matched your search
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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.
|
||||
@@ -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 |
|
||||
@@ -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.
|
||||
@@ -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 |
|
||||
Reference in new issue
Block a user