Watch
0
0
Fork
You've already forked hyperhive
0

docs: move the cli references under 2-handbook/tools

Closes #6157
This commit is contained in:
atlas 2026-11-06 22:59:11 +01:00 • committed by mara
commit df8a82bc33
22 changed files with 54 additions and 48 deletions

View file

@ -4,11 +4,11 @@
# generator, not the formatter, owns these files' layout. Every CLI
# reference doc belongs here — adding one and forgetting this line is
# what made swarmctl's fail.
docs/2-handbook/reference/hivectl-cli.md
docs/2-handbook/reference/swarmctl-cli.md
docs/2-handbook/reference/forge-cli.md
docs/2-handbook/reference/swarm-logs-cli.md
docs/2-handbook/reference/swarm-metrics-cli.md
docs/2-handbook/tools/hivectl-cli.md
docs/2-handbook/tools/swarmctl-cli.md
docs/2-handbook/tools/forge-cli.md
docs/2-handbook/tools/swarm-logs-cli.md
docs/2-handbook/tools/swarm-metrics-cli.md
# Files with multi-line list-item continuations that prettier strips to col 0.
# prettier's `proseWrap: "preserve"` prevents prose reflow but not list-item

View file

@ -33,8 +33,8 @@ nix fmt # treefmt is the CI gate, NOT bare cargo fmt
Changed a `hivectl` / `swarmctl` verb or flag? Regenerate its doc — only
CI's `nix flake check` catches the drift:
`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/reference/hivectl-cli.md`
(same for `swarmctl` → `docs/2-handbook/reference/swarmctl-cli.md`). CI red but local
`nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/tools/hivectl-cli.md`
(same for `swarmctl` → `docs/2-handbook/tools/swarmctl-cli.md`). CI red but local
green → build the suspect check (e.g. `nix build
.#checks.x86_64-linux.hivectl-docs`) before blaming the builder.
@ -58,7 +58,7 @@ Per-hive (host + in-container):
crate.
- **`hivectl/`** — operator CLI; talks to `hive-c0re` over the host admin
socket, does NOT link it. Verb reference (CI-enforced):
[`docs/2-handbook/reference/hivectl-cli.md`](docs/2-handbook/reference/hivectl-cli.md).
[`docs/2-handbook/tools/hivectl-cli.md`](docs/2-handbook/tools/hivectl-cli.md).
- **`hive-priv/`** — minimal root helper, socket-activated at
`/run/hive/priv.sock`; the few root ops (bind-mount edits, nsenter)
`hive-c0re` delegates. See `docs/2-handbook/trust-boundary/boundary.md`.
@ -130,7 +130,7 @@ Swarm-level:
**`users.yml` in place**, shared with `swarm-authelia-bridge`; that
crate's README says what both writers must uphold. Verb reference
(CI-enforced):
[`docs/2-handbook/reference/swarmctl-cli.md`](docs/2-handbook/reference/swarmctl-cli.md).
[`docs/2-handbook/tools/swarmctl-cli.md`](docs/2-handbook/tools/swarmctl-cli.md).
- **`swarm-authelia-bridge/`** (+ **`swarm-authelia-bridge-sock/`** wire
types) — the other writer of authelia's users DB; runs inside
`swarm-authelia`.

View file

@ -175,7 +175,7 @@ once, top to bottom.
[`docs/2-handbook/swarm/ui.md`](docs/2-handbook/swarm/ui.md)
- **`swarmctl`** — the swarm's CLI, on the swarm-controller host: create
agents and mint their identities, manage SSO users, make forge admins.
→ [reference](docs/2-handbook/reference/swarmctl-cli.md)
→ [reference](docs/2-handbook/tools/swarmctl-cli.md)
- **per-hive** — each hive's dashboard (container state,
rebuild queue) and `hivectl` for host-level administration and
container shells. → [`docs/2-handbook/web-ui/`](docs/2-handbook/web-ui/README.md) ·

View file

@ -41,7 +41,7 @@ kqzpmwab "standup" every 1d from 2026-10-05T07:00:00Z next 2026-10-05T07:00:
- `schedule list` shows one row per prompt: id, name, cadence, start, next
fire time, agents, and the first line of the body.
The full flag reference is [`swarmctl-cli.md`](../reference/swarmctl-cli.md).
The full flag reference is [`swarmctl-cli.md`](../tools/swarmctl-cli.md).
## When a prompt fires

View file

@ -50,7 +50,7 @@ this password is stored nowhere — record it now
the hash. It reads and writes authelia's `users.yml` directly — it's
the one user store, shared with `swarm-authelia-bridge`, which creates
agent identities in the same file. No restart: authelia watches it. Full
reference: [`2-handbook/reference/swarmctl-cli.md`](../reference/swarmctl-cli.md).
reference: [`2-handbook/tools/swarmctl-cli.md`](../tools/swarmctl-cli.md).
You can edit `users.yml` by hand, and `swarmctl` will read what you
wrote. ⚠️ It rewrites the whole file on every change, so **comments and

View file

@ -12,12 +12,12 @@ debug agent behavior.
- **[hivectl](hivectl.md)** — the curated guide: provisioning forge
and matrix accounts, container
lifecycle shortcuts, interactive agent shell access.
- **[hivectl-cli](../reference/hivectl-cli.md)** — the exhaustive, autogenerated
- **[hivectl-cli](hivectl-cli.md)** — the exhaustive, autogenerated
flag-by-flag reference, kept in lockstep with the binary by CI.
## For the swarm operator
- **[swarmctl-cli](../reference/swarmctl-cli.md)** — the exhaustive, autogenerated
- **[swarmctl-cli](swarmctl-cli.md)** — the exhaustive, autogenerated
flag-by-flag reference for `swarmctl`, kept in lockstep with the
binary by CI the same way `hivectl-cli.md` is. `swarmctl` itself
runs as root on the swarm-controller host, not through `hivectl` —
@ -25,6 +25,12 @@ debug agent behavior.
(authelia's subject store, edited in place) and `agent create`
(queues the swarm-controller's creation job graph). No curated guide
yet; add one here if/when that grows.
- **[swarm-logs-cli](swarm-logs-cli.md)** — the exhaustive, autogenerated
flag-by-flag reference for `swarm-logs`, kept in lockstep with the
binary by CI. No curated guide.
- **[swarm-metrics-cli](swarm-metrics-cli.md)** — the exhaustive,
autogenerated flag-by-flag reference for `swarm-metrics`, kept in
lockstep with the binary by CI. No curated guide.
## What your agents can do
@ -37,7 +43,7 @@ debug agent behavior.
- **[forge](forge.md)** — the `hive-forge` Forgejo CLI every agent has
for issues, PRs, and comments. Not an MCP tool — a binary agents
shell out to instead of ad-hoc curl.
- **[forge-cli](../reference/forge-cli.md)** — the exhaustive, autogenerated
- **[forge-cli](forge-cli.md)** — the exhaustive, autogenerated
flag-by-flag reference for `hive-forge`, kept in lockstep with the
binary by CI the same way `hivectl-cli.md` is.
- **[matrix](matrix.md)** — the matrix MCP tool surface

View file

@ -6,11 +6,11 @@ proper Rust binary). Use it instead of ad-hoc curl pipelines.
This page is the curated guide. For the exhaustive flag-by-flag reference
autogenerated from the binary's own command tree, see
[`forge-cli.md`](../reference/forge-cli.md) — emitted by the hidden `hive-forge
[`forge-cli.md`](forge-cli.md) — emitted by the hidden `hive-forge
markdown-docs` subcommand and kept in lockstep with the code by the
`hive-forge-docs` flake check (CI fails if the committed copy drifts).
Regenerate with `nix build .#hive-forge && ./result/bin/hive-forge
markdown-docs > docs/2-handbook/reference/forge-cli.md`.
markdown-docs > docs/2-handbook/tools/forge-cli.md`.
## Credentials and repo defaults

View file

@ -15,11 +15,11 @@ shortcuts and interactive agent shell access.
This page is the curated guide. For the exhaustive flag-by-flag
reference autogenerated from the binary's own command tree, see
[`hivectl-cli.md`](../reference/hivectl-cli.md) — emitted by the hidden `hivectl
[`hivectl-cli.md`](hivectl-cli.md) — emitted by the hidden `hivectl
markdown-docs` subcommand and kept in lockstep with the code by the
`hivectl-docs` flake check (CI fails if the committed copy drifts).
Regenerate with `nix build .#default && ./result/bin/hivectl
markdown-docs > docs/2-handbook/reference/hivectl-cli.md`.
markdown-docs > docs/2-handbook/tools/hivectl-cli.md`.
## Agents

View file

@ -30,7 +30,7 @@ swarmctl agent inference clear iris
running on, each with where it comes from.
- `clear` removes every field; the agent goes back to its own values.
The full flag reference is [`swarmctl-cli.md`](../../2-handbook/reference/swarmctl-cli.md). The
The full flag reference is [`swarmctl-cli.md`](../../2-handbook/tools/swarmctl-cli.md). The
swarm UI's agents page edits the same settings; see [UI](../../2-handbook/swarm/ui.md). The
swarm is the only place to change an agent's model or effort at runtime:
its web UI shows both but has no picker and no `/model` or `/effort`

View file

@ -497,20 +497,20 @@ mara — don't add `#[allow]` speculatively. The gate is intentional.
fmt / `cargo test` cover most gates, but `nix flake check` runs extra
check derivations they don't:
- **`hivectl-docs`** regenerates `docs/2-handbook/reference/hivectl-cli.md` from
- **`hivectl-docs`** regenerates `docs/2-handbook/tools/hivectl-cli.md` from
hivectl's clap tree and **fails if the committed copy is stale**.
**After any change to a hivectl verb or flag, regenerate it**:
```sh
nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/reference/hivectl-cli.md
nix develop -c cargo run --bin hivectl -- markdown-docs > docs/2-handbook/tools/hivectl-cli.md
```
clippy / fmt / `cargo test` all pass *without* this — only the
flake check catches the drift, and `ci-log` often can't show you
why (it 500s on a fast failure), so you're left guessing "builder
flake" when it's a stale doc.
- **`swarmctl-docs`** is the same check for `swarmctl` /
`docs/2-handbook/reference/swarmctl-cli.md`:
`docs/2-handbook/tools/swarmctl-cli.md`:
```sh
nix develop -c cargo run --bin swarmctl -- markdown-docs > docs/2-handbook/reference/swarmctl-cli.md
nix develop -c cargo run --bin swarmctl -- markdown-docs > docs/2-handbook/tools/swarmctl-cli.md
```
- there's also a flake `cargo-test` check and NixOS module
evaluation in the set.

View file

@ -336,7 +336,7 @@ nix develop -c cargo run -p hive-c0re --bin hivectl -- <args>
```
This is also how you regenerate committed generated docs locally —
for example `docs/2-handbook/reference/hivectl-cli.md` via the `hivectl markdown-docs`
for example `docs/2-handbook/tools/hivectl-cli.md` via the `hivectl markdown-docs`
subcommand (its `hivectl-docs` flake check otherwise only fails in
CI on drift).

View file

@ -34,9 +34,9 @@ later work.
tool surface (bash, forge, lifecycle, matrix).
- **What does `hivectl` do? Provisioning, gateway users, container
shells?** → [`2-handbook/tools/hivectl.md`](2-handbook/tools/hivectl.md) (the curated guide);
[`2-handbook/reference/hivectl-cli.md`](2-handbook/reference/hivectl-cli.md) for the exhaustive,
[`2-handbook/tools/hivectl-cli.md`](2-handbook/tools/hivectl-cli.md) for the exhaustive,
autogenerated flag reference. The other command-line references sit beside it in
[`2-handbook/reference/`](2-handbook/reference/).
[`2-handbook/tools/`](2-handbook/tools/README.md).
### Agent lifecycle

View file

@ -229,7 +229,7 @@ fn run() -> Result<()> {
}
// Same reasoning as `credential-helper` above: no repo, no forge
// credentials — just a pure render of the clap tree the docs build
// pipes into `docs/2-handbook/reference/forge-cli.md`.
// pipes into `docs/2-handbook/tools/forge-cli.md`.
if let Verb::MarkdownDocs = verb {
// `show_footer(false)`: the default footer's wording ("This
// document was generated automatically by...") is clap-markdown's

View file

@ -473,7 +473,7 @@ in
};
# `hivectl` CLI reference freshness check. The committed
# markdown at `docs/2-handbook/reference/hivectl-cli.md` is the rendered
# markdown at `docs/2-handbook/tools/hivectl-cli.md` is the rendered
# output of the hidden `hivectl markdown-docs` subcommand
# (clap-markdown walks the binary's own command tree). This
# check regenerates it from the built binary and fails if the
@ -485,13 +485,13 @@ in
# makes this check unsatisfiable rather than merely stale.
# Regenerate locally with:
# nix build .#default
# ./result/bin/hivectl markdown-docs > docs/2-handbook/reference/hivectl-cli.md
# ./result/bin/hivectl markdown-docs > docs/2-handbook/tools/hivectl-cli.md
hivectl-docs = pkgs.runCommand "hivectl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
${self.packages.${system}.default}/bin/hivectl markdown-docs > generated.md
if ! diff -u ${../docs/2-handbook/reference/hivectl-cli.md} generated.md; then
if ! diff -u ${../docs/2-handbook/tools/hivectl-cli.md} generated.md; then
echo "" >&2
echo "ERROR: docs/2-handbook/reference/hivectl-cli.md is out of date — regenerate it:" >&2
echo " nix build .#default && ./result/bin/hivectl markdown-docs > docs/2-handbook/reference/hivectl-cli.md" >&2
echo "ERROR: docs/2-handbook/tools/hivectl-cli.md is out of date — regenerate it:" >&2
echo " nix build .#default && ./result/bin/hivectl markdown-docs > docs/2-handbook/tools/hivectl-cli.md" >&2
exit 1
fi
touch "$out"
@ -504,10 +504,10 @@ in
# nix/packages/default.nix's comment on it).
swarmctl-docs = pkgs.runCommand "swarmctl-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; } ''
${self.packages.${system}.swarmctl}/bin/swarmctl markdown-docs > generated.md
if ! diff -u ${../docs/2-handbook/reference/swarmctl-cli.md} generated.md; then
if ! diff -u ${../docs/2-handbook/tools/swarmctl-cli.md} generated.md; then
echo "" >&2
echo "ERROR: docs/2-handbook/reference/swarmctl-cli.md is out of date — regenerate it:" >&2
echo " nix build .#swarmctl && ./result/bin/swarmctl markdown-docs > docs/2-handbook/reference/swarmctl-cli.md" >&2
echo "ERROR: docs/2-handbook/tools/swarmctl-cli.md is out of date — regenerate it:" >&2
echo " nix build .#swarmctl && ./result/bin/swarmctl markdown-docs > docs/2-handbook/tools/swarmctl-cli.md" >&2
exit 1
fi
touch "$out"
@ -521,10 +521,10 @@ in
pkgs.runCommand "swarm-logs-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; }
''
${self.packages.${system}.swarm-logs}/bin/swarm-logs markdown-docs > generated.md
if ! diff -u ${../docs/2-handbook/reference/swarm-logs-cli.md} generated.md; then
if ! diff -u ${../docs/2-handbook/tools/swarm-logs-cli.md} generated.md; then
echo "" >&2
echo "ERROR: docs/2-handbook/reference/swarm-logs-cli.md is out of date — regenerate it:" >&2
echo " nix build .#swarm-logs && ./result/bin/swarm-logs markdown-docs > docs/2-handbook/reference/swarm-logs-cli.md" >&2
echo "ERROR: docs/2-handbook/tools/swarm-logs-cli.md is out of date — regenerate it:" >&2
echo " nix build .#swarm-logs && ./result/bin/swarm-logs markdown-docs > docs/2-handbook/tools/swarm-logs-cli.md" >&2
exit 1
fi
touch "$out"
@ -536,10 +536,10 @@ in
pkgs.runCommand "swarm-metrics-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; }
''
${self.packages.${system}.swarm-metrics}/bin/swarm-metrics markdown-docs > generated.md
if ! diff -u ${../docs/2-handbook/reference/swarm-metrics-cli.md} generated.md; then
if ! diff -u ${../docs/2-handbook/tools/swarm-metrics-cli.md} generated.md; then
echo "" >&2
echo "ERROR: docs/2-handbook/reference/swarm-metrics-cli.md is out of date — regenerate it:" >&2
echo " nix build .#swarm-metrics && ./result/bin/swarm-metrics markdown-docs > docs/2-handbook/reference/swarm-metrics-cli.md" >&2
echo "ERROR: docs/2-handbook/tools/swarm-metrics-cli.md is out of date — regenerate it:" >&2
echo " nix build .#swarm-metrics && ./result/bin/swarm-metrics markdown-docs > docs/2-handbook/tools/swarm-metrics-cli.md" >&2
exit 1
fi
touch "$out"
@ -554,10 +554,10 @@ in
pkgs.runCommand "hive-forge-docs-fresh" { nativeBuildInputs = [ pkgs.diffutils ]; }
''
${self.packages.${system}.hive-forge}/bin/hive-forge markdown-docs > generated.md
if ! diff -u ${../docs/2-handbook/reference/forge-cli.md} generated.md; then
if ! diff -u ${../docs/2-handbook/tools/forge-cli.md} generated.md; then
echo "" >&2
echo "ERROR: docs/2-handbook/reference/forge-cli.md is out of date — regenerate it:" >&2
echo " nix build .#hive-forge && ./result/bin/hive-forge markdown-docs > docs/2-handbook/reference/forge-cli.md" >&2
echo "ERROR: docs/2-handbook/tools/forge-cli.md is out of date — regenerate it:" >&2
echo " nix build .#hive-forge && ./result/bin/hive-forge markdown-docs > docs/2-handbook/tools/forge-cli.md" >&2
exit 1
fi
touch "$out"

View file

@ -62,7 +62,7 @@ enum Verb {
format: query::Format,
},
/// Print this CLI's reference as markdown (source of `docs/2-handbook/reference/swarm-logs-cli.md`).
/// Print this CLI's reference as markdown (source of `docs/2-handbook/tools/swarm-logs-cli.md`).
///
/// No `completions` sibling, unlike `hivectl` and `swarmctl`: those are
/// installed on an operator's interactive host, where a completion script

Some files were not shown because too many files have changed in this diff Show more