randomparity / randomparity/kdive
Write the BYO host operator runbook and agent-facing documentation
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- Avg merge
- 1h 26m
- Merged PRs (30d)
- 311
Description
Part of #1814
## Problem
A BYO host provider is unusable without operator documentation: unlike the libvirt providers, it
depends on facts KDIVE cannot discover — which service processor the host has, what credentials it
takes, which kernel is the baseline, and what happens when a host gets cordoned.
There is a second audience with a harder constraint. FastMCP serializes **only** the
`@app.tool`-decorated wrapper's docstring and its `Field(description=...)` text into the tool
schema. An agent cannot read `docs/`, an ADR, or the inner handler. Any BYO capability or limit
that lives only in this runbook is invisible at call time — and per AGENTS.md, guidance an agent
cannot read is a discoverability defect even when the behavior is correct.
That matters most for the limits this epic introduces: real-hardware POST and power-cycle windows
are far longer than a VM's, and an agent with no wall clock fills unspecified space with worst-case
assumptions and invents workarounds.
## Evidence
- AGENTS.md: "The wrapper docstring is the agent-facing contract... Guidance that lives only on the
inner handler or in an ADR is a discoverability defect."
- AGENTS.md cross-cutting invariant: state all five parts of a limit contract — unit, reference
clock, scope, consequence of violation, and recovery action; prefer absolute deadlines plus a
`server_time` reference clock over relative durations.
- `docs/operating/runbooks/live-stack.md` and `live-testing.md` — the runbook precedents.
- `docs/operating/runbooks/` also holds `self-hosted-kvm-runner.md`, the model for documenting a
physical host contract.
- Doc-style guard: "Milestone" never "Sprint"; avoid "critical", "robust", "comprehensive",
"elegant".
## Expected outcome
- An operator runbook under `docs/operating/runbooks/` covering: host prerequisites per arch, OOB
setup for each of Redfish/IPMI/HMC, the `[[byo_host]]` declaration with a worked example, the
pre-flight (`doctor`) workflow, and what a cordoned host means and how to re-arm it.
- MCP wrapper docstrings and `Field` text updated for every BYO-visible capability and limit —
including the OOB power and reboot windows with all five parts of the limit contract and the
named recovery tool in `suggested_next_actions`.
- `systems.toml.example` cross-referenced so the declaration is discoverable from both directions.
- No phantom features: nothing documented that is not implemented and installable.
Blocked by #1829
Blocked by #1830
Contributor guide
Research direction
Read AGENTS.md and compare docs/operating/runbooks/live-stack.md, live-testing.md, and self-hosted-kvm-runner.md. Then inspect the BYO MCP wrappers and Field descriptions, plus systems.toml.example, to identify the documented capabilities and limits. Done means the runbook, cross-references, and agent-facing text cover the requested contracts without documenting unimplemented features.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 55/100