hive-forge, hivectl, swarmctl: fix clap help passive voice, regen docs

Rewrites every write-good.Passive hit in the hive-forge clap help text
into terse, imperative, active voice (meaning unchanged) and drops
clap-markdown's own fixed footer ('This document was generated
automatically by...') via MarkdownOptions::show_footer(false), since
that string isn't ours to reword and vale flagged it too.

docs/tools/{hivectl,swarmctl,forge}-cli.md are generated from each
crate's clap tree (see hive-forge/src/main.rs's MarkdownDocs verb) —
regenerated here from the fixed source, not hand-edited.

Refs #4549

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::<Cli>());
+        // `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::<Cli>(&options));
         return Ok(());
     }
     let client = client::Client::from_env(cli.repo, cli.json, cli.forge)

hive-forge/src/verbs/comments.rs

@@ -54,8 +54,8 @@ pub struct Args {
     #[arg(long, conflicts_with = "tail")]
     limit: Option<u64>,
     /// 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<usize>,
     /// Only show comments at or after this RFC3339 timestamp (same

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<u64>,

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 <id>`.

hive-forge/src/verbs/issue_create.rs

@@ -25,7 +25,7 @@ pub struct Args {
     assignee: Option<String>,
     /// 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<String>,

hive-forge/src/verbs/issue_edit.rs

@@ -1,6 +1,6 @@
 //! `issue edit <number> [--title <t>] [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/<n>` 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.

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 {

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 <id>`.

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 },

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<String>,
-    /// 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,
 }

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).

hive-forge/src/verbs/timeline.rs

@@ -46,8 +46,8 @@ pub struct Args {
     #[arg(long, conflicts_with = "tail")]
     limit: Option<u64>,
     /// 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<usize>,
     /// Only show events at or after this RFC3339 timestamp (same format