diff --git a/docs/tools/forge-cli.md b/docs/tools/forge-cli.md index c1ab85db..7e544401 100644 --- a/docs/tools/forge-cli.md +++ b/docs/tools/forge-cli.md @@ -143,7 +143,7 @@ Issue-scoped commands: `issue ` * `timeline` — List timeline events @@ -173,7 +173,7 @@ Create an issue * `--body ` — Inline body text * `--body-file ` — Read body from a file. `-` means stdin * `--assignee ` — Initial assignee login -* `--label ` — Label name to attach, repeatable (for example `--label area/ops --label type/bug`). Same spelling `labels add` accepts. An unresolved name errors out (before the issue is created) rather than silently attaching fewer labels than asked for +* `--label ` — Label name to attach, repeatable (for example `--label area/ops --label type/bug`). Same spelling `labels add` accepts. An unresolved name errors out (before creating the issue) rather than silently attaching fewer labels than asked for @@ -243,7 +243,7 @@ List comments on the issue ###### **Options:** * `--limit ` — Number of comments from the start of the thread (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail` -* `--tail ` — Return the last `N` comments (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since` +* `--tail ` — Return the last `N` comments (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since` * `--since ` — Only show comments at or after this RFC3339 timestamp (same format this verb's own output prints). Mutually exclusive with `--tail` * `--show-reactions` — Fetch + display each shown comment's reaction summary. Costs one extra request per comment shown — opt-in, not the default @@ -281,7 +281,7 @@ List / add / remove labels ###### **Subcommands:** -* `list` — List labels (default when no action is given) +* `list` — List labels (default when you give no action) * `add` — Add labels by name * `remove` — Remove labels by name @@ -293,7 +293,7 @@ List / add / remove labels ## `hive-forge issue labels list` -List labels (default when no action is given) +List labels (default when you give no action) **Usage:** `hive-forge issue labels list` @@ -342,14 +342,14 @@ Assign or unassign a user ## `hive-forge issue dependency` -List / add / remove dependencies (issues this one is blocked by) +List / add / remove dependencies (issues blocking this one) **Usage:** `hive-forge issue dependency [COMMAND]` ###### **Subcommands:** -* `list` — List dependencies (default when no action is given) — the issues/PRs this one is blocked by -* `add` — Add one or more issues/PRs this one is blocked by +* `list` — List dependencies (default when you give no action) — the issues/PRs blocking this one +* `add` — Add one or more issues/PRs that block this one * `remove` — Remove one or more dependency links ###### **Arguments:** @@ -360,7 +360,7 @@ List / add / remove dependencies (issues this one is blocked by) ## `hive-forge issue dependency list` -List dependencies (default when no action is given) — the issues/PRs this one is blocked by +List dependencies (default when you give no action) — the issues/PRs blocking this one **Usage:** `hive-forge issue dependency list` @@ -368,7 +368,7 @@ List dependencies (default when no action is given) — the issues/PRs this one ## `hive-forge issue dependency add` -Add one or more issues/PRs this one is blocked by +Add one or more issues/PRs that block this one **Usage:** `hive-forge issue dependency add [DEPS]...` @@ -398,13 +398,13 @@ List / add / remove emoji reactions on the issue, or on one of its comments with ###### **Subcommands:** -* `list` — List reactions (default when no action is given) +* `list` — List reactions (default when you give no action) * `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket` * `remove` — Remove your own reaction with this content ###### **Arguments:** -* `` — Issue or PR number. Ignored (but still required) when `--list-allowed` is set +* `` — Issue or PR number. Ignored (but still required) when you pass `--list-allowed` ###### **Options:** @@ -415,7 +415,7 @@ List / add / remove emoji reactions on the issue, or on one of its comments with ## `hive-forge issue reaction list` -List reactions (default when no action is given) +List reactions (default when you give no action) **Usage:** `hive-forge issue reaction list` @@ -458,7 +458,7 @@ List timeline events ###### **Options:** * `--limit ` — Return the first `N` events (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail` -* `--tail ` — Return the last `N` events (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since` +* `--tail ` — Return the last `N` events (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since` * `--since ` — Only show events at or after this RFC3339 timestamp (same format this verb's own output prints) — pass back the last-seen row's `created_at` to fetch only what's new @@ -480,14 +480,14 @@ PR-scoped commands: `pr ` * `timeline` — List timeline events @@ -653,7 +653,7 @@ Show title + body + comments ## `hive-forge pr edit` -Edit the PR's title / body / state / milestone. Fields not passed are left unchanged +Edit the PR's title / body / state / milestone. Fields you don't pass keep their current value **Usage:** `hive-forge pr edit [OPTIONS] ` @@ -705,7 +705,7 @@ List comments on the PR ###### **Options:** * `--limit ` — Number of comments from the start of the thread (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail` -* `--tail ` — Return the last `N` comments (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since` +* `--tail ` — Return the last `N` comments (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since` * `--since ` — Only show comments at or after this RFC3339 timestamp (same format this verb's own output prints). Mutually exclusive with `--tail` * `--show-reactions` — Fetch + display each shown comment's reaction summary. Costs one extra request per comment shown — opt-in, not the default @@ -743,7 +743,7 @@ List / add / remove labels ###### **Subcommands:** -* `list` — List labels (default when no action is given) +* `list` — List labels (default when you give no action) * `add` — Add labels by name * `remove` — Remove labels by name @@ -755,7 +755,7 @@ List / add / remove labels ## `hive-forge pr labels list` -List labels (default when no action is given) +List labels (default when you give no action) **Usage:** `hive-forge pr labels list` @@ -804,14 +804,14 @@ Assign or unassign a user (the PR's assignee list) ## `hive-forge pr dependency` -List / add / remove dependencies (issues/PRs this one is blocked by) +List / add / remove dependencies (issues/PRs blocking this one) **Usage:** `hive-forge pr dependency [COMMAND]` ###### **Subcommands:** -* `list` — List dependencies (default when no action is given) — the issues/PRs this one is blocked by -* `add` — Add one or more issues/PRs this one is blocked by +* `list` — List dependencies (default when you give no action) — the issues/PRs blocking this one +* `add` — Add one or more issues/PRs that block this one * `remove` — Remove one or more dependency links ###### **Arguments:** @@ -822,7 +822,7 @@ List / add / remove dependencies (issues/PRs this one is blocked by) ## `hive-forge pr dependency list` -List dependencies (default when no action is given) — the issues/PRs this one is blocked by +List dependencies (default when you give no action) — the issues/PRs blocking this one **Usage:** `hive-forge pr dependency list` @@ -830,7 +830,7 @@ List dependencies (default when no action is given) — the issues/PRs this one ## `hive-forge pr dependency add` -Add one or more issues/PRs this one is blocked by +Add one or more issues/PRs that block this one **Usage:** `hive-forge pr dependency add [DEPS]...` @@ -860,13 +860,13 @@ List / add / remove emoji reactions on the PR, or on one of its comments with `- ###### **Subcommands:** -* `list` — List reactions (default when no action is given) +* `list` — List reactions (default when you give no action) * `add` — Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket` * `remove` — Remove your own reaction with this content ###### **Arguments:** -* `` — Issue or PR number. Ignored (but still required) when `--list-allowed` is set +* `` — Issue or PR number. Ignored (but still required) when you pass `--list-allowed` ###### **Options:** @@ -877,7 +877,7 @@ List / add / remove emoji reactions on the PR, or on one of its comments with `- ## `hive-forge pr reaction list` -List reactions (default when no action is given) +List reactions (default when you give no action) **Usage:** `hive-forge pr reaction list` @@ -920,7 +920,7 @@ List timeline events ###### **Options:** * `--limit ` — Return the first `N` events (oldest-first), or (with `--since`) the most this call returns — capped at [`crate::verbs::MAX_LIMIT`] in the latter case. An explicit opt-in: with neither this nor `--tail` given, the default is the newest 10 (see `--tail`). Mutually exclusive with `--tail` -* `--tail ` — Return the last `N` events (chronological) — the most recent activity. This is the default (`N` = 10) when neither `--limit` nor `--tail` is given. Mutually exclusive with `--limit`/`--since` +* `--tail ` — Return the last `N` events (chronological) — the most recent activity. Defaults to `N` = 10 when you pass neither `--limit` nor `--tail`. Mutually exclusive with `--limit`/`--since` * `--since ` — Only show events at or after this RFC3339 timestamp (same format this verb's own output prints) — pass back the last-seen row's `created_at` to fetch only what's new @@ -979,7 +979,7 @@ Create a forge repo under the current user (or `--org`). Prints the repo URL ###### **Arguments:** -* `` — Repository name (required). Created under the authenticated user unless `--org` is given +* `` — Repository name (required). Creates it under the authenticated user unless you pass `--org` ###### **Options:** @@ -987,7 +987,7 @@ Create a forge repo under the current user (or `--org`). Prints the repo URL * `--private` — Create the repo as private (default: public) * `--default-branch ` — Default branch name (for example `main`). Only takes effect with `--auto-init` * `--org ` — Create under this organisation instead of your own namespace -* `--auto-init` — Seed an initial commit (README) so the repo is non-empty and can be cloned immediately. Omit to create a bare repo you push into +* `--auto-init` — Seed an initial commit (README) so you can clone the repo immediately instead of getting an empty one. Omit to create a bare repo you push into @@ -1040,7 +1040,7 @@ Search the forge for repositories by keyword, topic, or description * `-q`, `--query ` — Keyword to search for (matches repo name by default; combine with `--include-desc` to also match description text) * `--topic` — Restrict matches to repositories that have the keyword as a **topic** tag rather than in the name -* `--include-desc` — Extend the keyword search to repository descriptions (in addition to names, or topics when `--topic` is set) +* `--include-desc` — Extend the keyword search to repository descriptions (in addition to names, or topics when you pass `--topic`) * `--limit ` — Maximum number of results to return (default: 30) Default value: `30` @@ -1398,9 +1398,3 @@ List CI Actions runs, newest first (`--workflow`, `--branch`, `--limit`, `--page -
- - - This document was generated automatically by - clap-markdown. - diff --git a/docs/tools/hivectl-cli.md b/docs/tools/hivectl-cli.md index cb787d1b..12ecc67a 100644 --- a/docs/tools/hivectl-cli.md +++ b/docs/tools/hivectl-cli.md @@ -247,7 +247,7 @@ Invite a matrix user to the hive Space, or a specific room with `--room`. Idempo GitHub account provisioning. -Store an operator-supplied personal access token (PAT) for an agent so its `gh` and git can authenticate. No account is created — the PAT is for an existing GitHub account. +Store an operator-supplied personal access token (PAT) for an agent so its `gh` and git can authenticate. Creates no account — the PAT is for an existing GitHub account. **Usage:** `hivectl github ` @@ -503,7 +503,7 @@ A fresh session by default, or resume a prior one. Requires root or `hive-admin` ###### **Options:** -* `--resume ` — Resume a prior claude session by its session id, passed through as `claude --resume ` (claude's `--continue` takes no value — it resumes the cwd's latest session, which is the harness's, so choom never uses it; this flag matches the claude flag it maps to). Omit for a fresh blank session. A value is required when the flag is given +* `--resume ` — Resume a prior claude session by its session id, passed through as `claude --resume ` (claude's `--continue` takes no value — it resumes the cwd's latest session, which is the harness's, so choom never uses it; this flag matches the claude flag it maps to). Omit for a fresh blank session. Requires a value @@ -641,7 +641,7 @@ Export a snapshot to a local file via `btrfs send` — the local-file half of th Stream a snapshot to the swarm's snapshot store over the WireGuard mesh — the network half of the migration transport. -Nothing is staged locally: `btrfs send` writes straight into the connection, so a multi-gigabyte agent needs no scratch space on this host. The mesh is the authentication (cryptokey routing binds the sender's address to its key), so there is no credential to pass here. +Stages nothing locally: `btrfs send` writes straight into the connection, so a multi-gigabyte agent needs no scratch space on this host. The mesh is the authentication (cryptokey routing binds the sender's address to its key), so there is no credential to pass here. No destination argument exists: a swarm has one store, read from `services.hyperhive.swarm.snapshotStore`. @@ -901,9 +901,3 @@ Supports bash, zsh, fish, elvish, and powershell. The NixOS module already insta -
- - - This document was generated automatically by - clap-markdown. - diff --git a/docs/tools/swarmctl-cli.md b/docs/tools/swarmctl-cli.md index 125e95d0..4cc0af2e 100644 --- a/docs/tools/swarmctl-cli.md +++ b/docs/tools/swarmctl-cli.md @@ -52,7 +52,7 @@ Queue creation of a new agent on a hive in this swarm. Asks the swarm-controller to insert its agent-creation job graph — SSO identity, forge user, config repo, and the deploy message that puts the agent on `--hive` — and prints the queued job's node id. -**This returns as soon as the work is queued.** It doesn't wait, and a finished graph would not mean the agent is up either: the last node publishes a deploy, after which the hive converges on its own clock. Watch the swarm UI's job view, or the hive itself, for the rest. +**This returns as soon as it queues the work.** It doesn't wait, and a finished graph would not mean the agent is up either: the last node publishes a deploy, after which the hive converges on its own clock. Watch the swarm UI's job view, or the hive itself, for the rest. No approval gate guards this: running this binary already means being root on the controller's host. @@ -62,13 +62,13 @@ No approval gate guards this: running this binary already means being root on th * `` — Name for the new agent: 1–63 characters of `[a-z0-9-]`. - Becomes an SSO subject, a forge user and a repository name, so it's validated here before anything is queued. + Becomes an SSO subject, a forge user and a repository name, so it's validated here before queuing. ###### **Options:** * `--hive ` — Hive in this swarm to deploy the agent to. - Required, and deliberately not defaulted: it's an *address* — the hive a deploy message is sent to — and only the operator knows which one they mean. The controller checks it against the swarm's hive roster and names the known hives if it misses. + Required, and deliberately not defaulted: it's an *address* — the hive that gets the deploy message — and only the operator knows which one they mean. The controller checks it against the swarm's hive roster and names the known hives if it misses. * `--controller-socket ` — swarm-controller's unix socket. Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`. @@ -157,9 +157,3 @@ Dispatched before `PathArgs::resolve()` for the same reason as `markdown-docs`: -
- - - This document was generated automatically by - clap-markdown. - diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs index c9bec2c0..93ced2d0 100644 --- a/hive-forge/src/main.rs +++ b/hive-forge/src/main.rs @@ -226,7 +226,14 @@ fn run() -> Result<()> { // credentials — just a pure render of the clap tree the docs build // pipes into `docs/tools/forge-cli.md`. if let Verb::MarkdownDocs = verb { - print!("{}", clap_markdown::help_markdown::()); + // `show_footer(false)`: the default footer's wording ("This + // document was generated automatically by...") is clap-markdown's + // own fixed text, not ours to reword into active voice, and the + // repo's docs are prose we write ourselves throughout — so we + // drop the footer rather than carry the one string in this tree + // we have no control over. + let options = clap_markdown::MarkdownOptions::new().show_footer(false); + print!("{}", clap_markdown::help_markdown_custom::(&options)); return Ok(()); } let client = client::Client::from_env(cli.repo, cli.json, cli.forge) diff --git a/hive-forge/src/verbs/comments.rs b/hive-forge/src/verbs/comments.rs index 3c47181b..0db9b078 100644 --- a/hive-forge/src/verbs/comments.rs +++ b/hive-forge/src/verbs/comments.rs @@ -54,8 +54,8 @@ pub struct Args { #[arg(long, conflicts_with = "tail")] limit: Option, /// Return the last `N` comments (chronological) — the most recent - /// activity. This is the default (`N` = 10) when neither `--limit` - /// nor `--tail` is given. Mutually exclusive with `--limit`/`--since`. + /// activity. Defaults to `N` = 10 when you pass neither `--limit` + /// nor `--tail`. Mutually exclusive with `--limit`/`--since`. #[arg(long, conflicts_with = "since")] tail: Option, /// Only show comments at or after this RFC3339 timestamp (same diff --git a/hive-forge/src/verbs/dependency.rs b/hive-forge/src/verbs/dependency.rs index 7fd82521..97d759b7 100644 --- a/hive-forge/src/verbs/dependency.rs +++ b/hive-forge/src/verbs/dependency.rs @@ -30,10 +30,10 @@ pub struct Args { #[derive(Subcommand)] enum Action { - /// List dependencies (default when no action is given) — the - /// issues/PRs this one is blocked by. + /// List dependencies (default when you give no action) — the + /// issues/PRs blocking this one. List, - /// Add one or more issues/PRs this one is blocked by. + /// Add one or more issues/PRs that block this one. Add { /// Issue/PR numbers to add as dependencies. deps: Vec, diff --git a/hive-forge/src/verbs/issue_cmd.rs b/hive-forge/src/verbs/issue_cmd.rs index 168ab2e3..fd2292bb 100644 --- a/hive-forge/src/verbs/issue_cmd.rs +++ b/hive-forge/src/verbs/issue_cmd.rs @@ -40,7 +40,7 @@ enum Cmd { Labels(verbs::labels::Args), /// Assign or unassign a user. Assign(verbs::assign::Args), - /// List / add / remove dependencies (issues this one is blocked by). + /// List / add / remove dependencies (issues blocking this one). Dependency(verbs::dependency::Args), /// List / add / remove emoji reactions on the issue, or on one of its /// comments with `--comment `. diff --git a/hive-forge/src/verbs/issue_create.rs b/hive-forge/src/verbs/issue_create.rs index 7f1f3851..90de0882 100644 --- a/hive-forge/src/verbs/issue_create.rs +++ b/hive-forge/src/verbs/issue_create.rs @@ -25,7 +25,7 @@ pub struct Args { assignee: Option, /// Label name to attach, repeatable (for example `--label area/ops --label /// type/bug`). Same spelling `labels add` accepts. An unresolved name - /// errors out (before the issue is created) rather than silently + /// errors out (before creating the issue) rather than silently /// attaching fewer labels than asked for. #[arg(long = "label")] labels: Vec, diff --git a/hive-forge/src/verbs/issue_edit.rs b/hive-forge/src/verbs/issue_edit.rs index 9120dda4..f9a10fb2 100644 --- a/hive-forge/src/verbs/issue_edit.rs +++ b/hive-forge/src/verbs/issue_edit.rs @@ -1,6 +1,6 @@ //! `issue edit [--title ] [body sources] [--state s] -//! [--milestone id] [repo]` — partial update of an issue. Fields not -//! provided are left unchanged. Also backs `pr edit`: Forgejo serves +//! [--milestone id] [repo]` — partial update of an issue. Omitted +//! fields keep their current value. Also backs `pr edit`: Forgejo serves //! both kinds off the same `/issues/` endpoint, so this is shared //! as-is — `pr_cmd.rs` wires it in with a `Kind::Pr` check, the same //! pattern `close`/`reopen`/`labels` already use. diff --git a/hive-forge/src/verbs/labels.rs b/hive-forge/src/verbs/labels.rs index 13102f12..77f6bcab 100644 --- a/hive-forge/src/verbs/labels.rs +++ b/hive-forge/src/verbs/labels.rs @@ -19,7 +19,7 @@ pub struct Args { #[derive(Subcommand)] enum Action { - /// List labels (default when no action is given). + /// List labels (default when you give no action). List, /// Add labels by name. Add { diff --git a/hive-forge/src/verbs/pr_cmd.rs b/hive-forge/src/verbs/pr_cmd.rs index 19574b38..1a369c7e 100644 --- a/hive-forge/src/verbs/pr_cmd.rs +++ b/hive-forge/src/verbs/pr_cmd.rs @@ -39,8 +39,8 @@ enum Cmd { Diff(verbs::diff::Args), /// Show title + body + comments. View(verbs::view::Args), - /// Edit the PR's title / body / state / milestone. Fields not passed - /// are left unchanged. + /// Edit the PR's title / body / state / milestone. Fields you don't + /// pass keep their current value. Edit(verbs::issue_edit::Args), /// Post a comment on the PR. Comment(verbs::comment::Args), @@ -55,7 +55,7 @@ enum Cmd { /// Assign or unassign a user (the PR's assignee list). #[command(alias = "assign")] AssignCommitter(verbs::assign::Args), - /// List / add / remove dependencies (issues/PRs this one is blocked by). + /// List / add / remove dependencies (issues/PRs blocking this one). Dependency(verbs::dependency::Args), /// List / add / remove emoji reactions on the PR, or on one of its /// comments with `--comment `. diff --git a/hive-forge/src/verbs/reaction.rs b/hive-forge/src/verbs/reaction.rs index 4a744b8c..dd6d0db6 100644 --- a/hive-forge/src/verbs/reaction.rs +++ b/hive-forge/src/verbs/reaction.rs @@ -29,8 +29,8 @@ use crate::verbs::{comment_reactions, issue_reactions, print_json}; #[derive(ClapArgs)] pub struct Args { - /// Issue or PR number. Ignored (but still required) when - /// `--list-allowed` is set. + /// Issue or PR number. Ignored (but still required) when you pass + /// `--list-allowed`. pub(crate) number: u64, /// Target a specific comment's reactions instead of the issue/PR /// itself — the comment's own id (from `comments`/`comment-show`), @@ -48,7 +48,7 @@ pub struct Args { #[derive(Subcommand)] enum Action { - /// List reactions (default when no action is given). + /// List reactions (default when you give no action). List, /// Add a reaction — a Forgejo shortcode, for example `+1`, `heart`, `rocket`. Add { content: String }, diff --git a/hive-forge/src/verbs/repo_create.rs b/hive-forge/src/verbs/repo_create.rs index 3311760d..63e30ec1 100644 --- a/hive-forge/src/verbs/repo_create.rs +++ b/hive-forge/src/verbs/repo_create.rs @@ -18,8 +18,8 @@ use crate::verbs::print_json; #[derive(ClapArgs)] pub struct Args { - /// Repository name (required). Created under the authenticated user - /// unless `--org` is given. + /// Repository name (required). Creates it under the authenticated + /// user unless you pass `--org`. name: String, /// Repository description. #[arg(long)] @@ -33,8 +33,9 @@ pub struct Args { /// Create under this organisation instead of your own namespace. #[arg(long)] org: Option, - /// Seed an initial commit (README) so the repo is non-empty and can - /// be cloned immediately. Omit to create a bare repo you push into. + /// Seed an initial commit (README) so you can clone the repo + /// immediately instead of getting an empty one. Omit to create a + /// bare repo you push into. #[arg(long = "auto-init")] auto_init: bool, } diff --git a/hive-forge/src/verbs/repo_search.rs b/hive-forge/src/verbs/repo_search.rs index 382d1076..5ad952c8 100644 --- a/hive-forge/src/verbs/repo_search.rs +++ b/hive-forge/src/verbs/repo_search.rs @@ -26,7 +26,7 @@ pub struct Args { #[arg(long)] topic: bool, /// Extend the keyword search to repository descriptions (in addition to - /// names, or topics when `--topic` is set). + /// names, or topics when you pass `--topic`). #[arg(long = "include-desc")] include_desc: bool, /// Maximum number of results to return (default: 30). diff --git a/hive-forge/src/verbs/timeline.rs b/hive-forge/src/verbs/timeline.rs index 2e9acad2..a421bc1b 100644 --- a/hive-forge/src/verbs/timeline.rs +++ b/hive-forge/src/verbs/timeline.rs @@ -46,8 +46,8 @@ pub struct Args { #[arg(long, conflicts_with = "tail")] limit: Option, /// Return the last `N` events (chronological) — the most recent - /// activity. This is the default (`N` = 10) when neither `--limit` - /// nor `--tail` is given. Mutually exclusive with `--limit`/`--since`. + /// activity. Defaults to `N` = 10 when you pass neither `--limit` + /// nor `--tail`. Mutually exclusive with `--limit`/`--since`. #[arg(long, conflicts_with = "since")] tail: Option, /// Only show events at or after this RFC3339 timestamp (same format diff --git a/hivectl/src/cli.rs b/hivectl/src/cli.rs index 25e8231e..12a81b75 100644 --- a/hivectl/src/cli.rs +++ b/hivectl/src/cli.rs @@ -49,8 +49,8 @@ pub enum Cmd { /// GitHub account provisioning. /// /// Store an operator-supplied personal access token (PAT) for an agent - /// so its `gh` and git can authenticate. No account is created — the - /// PAT is for an existing GitHub account. + /// so its `gh` and git can authenticate. Creates no account — the PAT + /// is for an existing GitHub account. Github { #[command(subcommand)] cmd: GithubCmd, @@ -551,7 +551,7 @@ pub enum AgentCmd { /// takes no value — it resumes the cwd's latest session, which /// is the harness's, so choom never uses it; this flag matches /// the claude flag it maps to). Omit for a fresh blank session. - /// A value is required when the flag is given. + /// Requires a value. #[arg(long = "resume", value_name = "SESSION")] resume_session: Option, }, @@ -662,7 +662,7 @@ pub enum SnapshotCmd { /// Stream a snapshot to the swarm's snapshot store over the /// WireGuard mesh — the network half of the migration transport. /// - /// Nothing is staged locally: `btrfs send` writes straight into the + /// Stages nothing locally: `btrfs send` writes straight into the /// connection, so a multi-gigabyte agent needs no scratch space on /// this host. The mesh is the authentication (cryptokey routing /// binds the sender's address to its key), so there is no credential diff --git a/hivectl/src/main.rs b/hivectl/src/main.rs index 95c4751b..3182deb7 100644 --- a/hivectl/src/main.rs +++ b/hivectl/src/main.rs @@ -127,7 +127,11 @@ async fn main() -> Result<()> { Cmd::Start { scope, no_wait } => start(&socket, scope.to_scope(), no_wait).await, Cmd::Restart { scope, graceful } => restart(&socket, scope.to_scope(), graceful).await, Cmd::MarkdownDocs => { - print!("{}", clap_markdown::help_markdown::()); + // `show_footer(false)`: drop clap-markdown's own fixed + // "This document was generated automatically by..." footer — + // it's the one string in this doc that isn't ours to reword. + let options = clap_markdown::MarkdownOptions::new().show_footer(false); + print!("{}", clap_markdown::help_markdown_custom::(&options)); Ok(()) } Cmd::Open { target } => open_url(&socket, target).await, diff --git a/swarmctl/src/main.rs b/swarmctl/src/main.rs index 4efe3d7c..ec9a4307 100644 --- a/swarmctl/src/main.rs +++ b/swarmctl/src/main.rs @@ -159,7 +159,7 @@ enum AgentVerb { /// SSO identity, forge user, config repo, and the deploy message that /// puts the agent on `--hive` — and prints the queued job's node id. /// - /// **This returns as soon as the work is queued.** It doesn't wait, + /// **This returns as soon as it queues the work.** It doesn't wait, /// and a finished graph would not mean the agent is up either: the /// last node publishes a deploy, after which the hive converges on its /// own clock. Watch the swarm UI's job view, or the hive itself, for @@ -175,12 +175,12 @@ struct AgentCreateArgs { /// Name for the new agent: 1–63 characters of `[a-z0-9-]`. /// /// Becomes an SSO subject, a forge user and a repository name, so - /// it's validated here before anything is queued. + /// it's validated here before queuing. name: String, /// Hive in this swarm to deploy the agent to. /// /// Required, and deliberately not defaulted: it's an *address* — the - /// hive a deploy message is sent to — and only the operator knows + /// hive that gets the deploy message — and only the operator knows /// which one they mean. The controller checks it against the swarm's /// hive roster and names the known hives if it misses. #[arg(long, value_name = "HIVE")] @@ -275,7 +275,11 @@ fn main() -> Result<()> { command: UserVerb::List, } => user_list(&paths.resolve()?), Verb::MarkdownDocs => { - print!("{}", clap_markdown::help_markdown::()); + // `show_footer(false)`: drop clap-markdown's own fixed + // "This document was generated automatically by..." footer — + // it's the one string in this doc that isn't ours to reword. + let options = clap_markdown::MarkdownOptions::new().show_footer(false); + print!("{}", clap_markdown::help_markdown_custom::(&options)); Ok(()) } Verb::Completions { shell } => {