The design docs for osapi-io. Written before the code, corrected when the code proves them wrong.
Doc-driven: the page is the design, then the description.
You design something by writing its page, build it, then correct the page where building proved it wrong. Same page all three times, so nothing is converted from one form into another, because that conversion is where the design and the docs drift apart.
osapi-io makes a Linux host behave like an appliance. One binary and a config file give you a REST API, a CLI, a Go SDK and an embedded dashboard over hostname, DNS, disk, memory, load, packages, services, users, sysctl, cron, certificates, containers, files and command execution, across a fleet rather than one box.
The design fact everything else follows from: work reaches a host by being queued, not by being called. The controller writes a job and waits; an agent picks it up and a provider does the work on the machine. At-least-once delivery, the idempotency providers owe, two independent timeouts and a per-host result all come out of that one choice.
components/ one page per repository, plus a page per subject
ARCHITECTURE.md how they fit together, and what breaks what
CONSTITUTION.md the rules every repository follows
Read osapi first. Its subject pages hang off it, and four of the other five repositories either feed it or consume it.
Design something by writing its page. Build it. Correct the page where building proved it wrong. Same page all three times, and nothing is converted from one form into another, because that conversion is where the design and the docs drift apart.
So a change here is one of four things:
| You are | Change |
|---|---|
| Designing something new | A new page under its component |
| Changing how something behaves | The page that already covers it |
| Agreeing something between repositories | ARCHITECTURE.md |
| Binding every repository to a rule | CONSTITUTION.md |
CONTRIBUTING.md has the test for which, and what a page looks like.
A reader. Hand somebody the page and nothing else, ask them the question it claims to answer, and fix what they could not work out. That has found seven permissions where a page said one, thirteen struct fields where it said fourteen, and a bucket TTL described backwards.
| Repository | Is |
|---|---|
| osapi | The API and the agent that manage a host |
| osapi-orchestrator | A declarative layer over osapi's SDK |
| nats-client | A wrapper over the NATS client |
| nats-server | A NATS server embedded in its consumer |
| gohai | A system fact collection library, standalone |
| osapi-justfiles | Shared just recipes |
The four things most likely to catch you out, all written up: a missing row in a broadcast result is not an error and nothing reports it, audit redaction is a name-matched denylist with no test behind it, a direct permission silently nullifies every role on the token, and ten minutes is a ceiling rather than a fallback, so a job that needs twenty does not get them.
Skills here answer questions that span every repository, and carry the operational knowledge for working in them.
None of them lists what it describes. org-status takes the repository list
from GitHub on each run, add-a-domain resolves its reference domain from the
codebase, and document reads the component pages that exist rather than a
table of them. An inventory written into a skill is right the day it is written
and wrong after the next change, with nothing marking the moment.
| Skill | Answers |
|---|---|
| document | Where a design goes, what the page looks like, and whether one already covers it |
| org-status | Open pull requests, Dependabot bumps, security alerts, whether CI is green, and working the merge queue across osapi-io |
| add-a-domain | Adding an osapi domain: the provider and every layer it has to appear in, in the order that avoids rework |
| release | Whether a repository needs a tag, which number it takes, and whether the tag will actually publish |
Each follows the Agent Skills format: a slim SKILL.md that routes, with the
detail in reference files an agent reads only when the question calls for them.
See the Contributing guide for prerequisites, the test for where a change belongs, what a page looks like, and the PR workflow.
The MIT License.