Halbert

Here’s how I work.

Halbert is software that installs on one machine and speaks for that machine. This site is its documentation: what the machine needs, what happens in the minute after you start it, how to connect the pieces that need connecting, and what every command, endpoint, setting and capability is called.

If you have not seen it run, start with What Halbert is. If you have, go to Install — and note before you type anything that the command halbert starts the dashboard and takes no subcommands. The command line is python Halbert/main.py, from a checkout. Install explains why.

The six sections

Start here is a sequence, meant in order: What Halbert is, Install, First run, and Your first conversation. At the end of it you have a machine that answers questions about itself from measurement.

How-to is one task per page, each written by doing it on a real machine: Connect a local model, Connect Home Assistant, Stage and approve a command, and Set up voice. Where a step does not work yet, the page says so and says what does.

Concepts covers the decisions that are easiest to get wrong from the outside: Model locality and the secure tier, Capabilities, not variants, and Guardrails and approvals. Each names the one place in the code where its rule is decided.

Features is the dictionary — one page per feature, saying what it is, how it works, and what it will refuse to do. It is generated from a single catalog that the marketing site reads as well, so there is one description of a feature rather than two. Start from the sidebar, or search: Home Assistant control and MCP server are representative entries.

Reference is not written by hand. CLI, REST API, Configuration and Capabilities are each emitted from the tree they describe, and a check in CI fails the build when a page and the tree disagree. The hand-written command reference that came before is why: it had drifted to 42 of the 67 subcommands, listed several under names they no longer had, and carried a note at the top telling readers that --help was the authoritative source instead.

Operations is for running Halbert as a service on a machine you do not sit in front of, rather than as an app you open.

Pages that are not written yet

Several pages hold a place in the navigation and have no content. Each says so at the top rather than reading like an answer: the shape of the documentation is easier to judge whole than in pieces, and a stub that admits it is cheaper to fix than a page that quietly says nothing.

Not written yet: The computer speaks for itself, Memory and continuity, Grounded answers, Add a second machine, Read a finding, all three Operations pages — systemd units, Kiosk appliance and Paths and data formats — and the Reference section page itself, whose four generated pages below it are written.

Where these pages come from

Every page carries a sources list in its front matter naming the files it describes, and a check asserts that each of those paths still exists. That catches the cheapest kind of rot — a page describing a function that has been renamed away — and it catches nothing else. A page can still be wrong about code that is still there. When one is, it is a bug in the documentation, and documentation/ in the repository is where the internal record of the same system lives.