oleks
182ca54bc5
Read the full diff rather than trusting the "docs" framing — this session already had a PR labelled docs(...) that shipped three breaking behavior guards. This one is genuinely documentation: 7 files, +150/-13, no executable code. What it changes: - integration-preflight becomes a mandatory step 0, with a new non-skippable procedure step 6: one real authenticated request against every external dependency FROM THE RUNTIME CONTEXT, with the status code pasted into the plan. - onboard-host, integrate-service and finish-migration each gain an explicit entry gate, so it is a checklist item rather than a judgment call. onboard-host previously said "run it first IF any existing drift could interact" — that conditional is exactly how it got skipped twice. - Two new failure classes: F12 (external dependency never smoke-tested from the runtime context) and F13 (preflight treated as a judgment call), written in the catalog's existing style with real issue refs. - Output becomes TWO tables (layers + dependencies); either left blank means the preflight did not run. - plugin.json 1.0.0 -> 1.0.1, required for the plugin cache to pick the change up. The worked example is the right one: oleks/armer#171, where the token was byte-identical and correctly injected, 127.0.0.1 returned 200 and the ZeroTier IP returned 401. Nothing about the credential was wrong — the source address was. That distinction is the whole lesson. NOT closing oleks/cluster#271 on this merge: the repo has no CI (verified two ways — find returns nothing, and Woodpecker GET /repos/lookup 404s), and the remaining acceptance items need a human. Docs efficacy cannot be proven by a lint gate; the real test is whether the next rollout actually invokes it. Refs oleks/cluster#271, oleks/armer#171, oleks/cluster#260
fleet-integration
Integration playbooks for the oleks fleet, distilled from the 2026-07-21 k3s-over-ZeroTier connectivity research (27 incidents across 12 repos; full evidence on the oleks/cluster wiki → K3s-over-ZeroTier-Connectivity page).
Core finding: the fleet's failures were integration-shaped, not
platform-shaped. A different overlay, cluster, or cloud would have failed the
same way — through undeclared state, half-finished migrations, hardcoded
environment assumptions, half-implemented lifecycles, and watchdogs that
amplify. These playbooks encode the failure classes (durable) rather than
current fleet facts (which rot — stale docs were themselves failure class F9).
Where a current value matters, the playbooks point at the live source of truth
(fleet-modules/cluster-topology.nix, the wiki) instead of restating it.
Skills
| Skill | When | Closes |
|---|---|---|
integration-preflight |
Step 0 of every multi-step rollout (mandatory) — diff declared vs live per layer, then smoke-test every external dependency from the runtime context | F1 F2 F3 F9 F12 F13 |
onboard-host |
New host into the fleet network and/or k3s | F1 F3 F4 F8 F10 |
integrate-service |
New workload end to end: chart, Flux, ingress, DNS, secrets, DB, TLS, tracking | F3 F8 F9 F11 |
ephemeral-lifecycle |
Scale-to-zero nodes: credentials, admission, allocation, reaping | F5 F6 F11 |
add-watchdog |
Any health-check/auto-restart mechanism, new or under review | F7 F10 |
finish-migration |
Cutovers — planning them, and auditing half-done ones | F1 F2 F9 F10 |
The failure catalog
references/failure-catalog.md defines F1–F13 with the real incidents behind
each (issue refs in full owner/repo#N form). Read it once; the skills cite
it by class.
- F1 Undeclared state · F2 Half-finished migrations · F3 Hardcoded environment assumptions · F4 MTU/encapsulation budget ignored · F5 Half-implemented lifecycle · F6 Control plane on its own data path · F7 Watchdog amplification · F8 Multi-layer firewalls changed separately · F9 Stale documentation as active misinformation · F10 Guard drift · F11 Read-modify-write without exclusion · F12 External dependency never smoke-tested from the runtime context · F13 Preflight treated as a judgment call
Provenance
Built from: the tracker sweep (oleks/armer, oleks/cluster, oleks/fleet,
oleks/builder-arbitrage, oleks/matrix-moq and others), a file:line code sweep
of ~/projects/servers and builder-arbitrage, live fleet verification, and
session memory. Defects discovered during the research were filed as
oleks/armer#166 and oleks/cluster#260 before this plugin cited them.