parent
be383ab276
commit
df8a82bc33
22 changed files with 54 additions and 48 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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) ·
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
|
|
|
|||
|
|
@ -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
Loading…
Reference in a new issue