docs(#2671): trim per-verb arg help (pr-create, comments, ci-log, ci-rerun)

Drop implementation detail from the clap arg help (the `<verb> --help`
surface) — which API/endpoint, page-count math, persisted-vs-streamer
log-source internals, refspec shapes — keeping only what/when-to-use for
each flag. Module `//!` docs (dev-facing, not shown by `--help`) left
intact.

hive-forge/src/verbs/ci_log.rs

@@ -30,20 +30,17 @@ use crate::client::Client;
 
 #[derive(ClapArgs)]
 pub struct Args {
-    /// Workflow run number — the `runs/<n>` in the run-page URL, which
-    /// `pr-status` surfaces as a CI context's `target_url`.
+    /// Workflow run number — the `runs/<n>` in the run-page URL (shown
+    /// by `pr-status`).
     #[arg(long)]
     run: u64,
-    /// Job index within the run (0-based; default 0 — the first job).
+    /// Job index within the run (0-based, default 0).
     #[arg(long, default_value_t = 0)]
     job: u64,
     /// Print only this step's log (0-based). Omit to print every step.
-    /// Honored on the live-streamer path only; the durable persisted-log
-    /// fallback serves a flat whole-job log and ignores `--step`.
     #[arg(long)]
     step: Option<usize>,
-    /// Run attempt number for the durable persisted-log download (re-runs
-    /// increment it; default 1 covers the common single-attempt case).
+    /// Run attempt number (re-runs increment it; default 1).
     #[arg(long, default_value_t = 1)]
     attempt: u64,
 }

hive-forge/src/verbs/ci_rerun.rs

@@ -35,23 +35,21 @@ use crate::client::{Client, index};
 
 #[derive(ClapArgs)]
 pub struct Args {
-    /// Re-run CI for this PR: resolves the PR's head branch and dispatches
-    /// `--workflow` on it. Mutually exclusive with `--run` / `--branch`.
+    /// Re-run CI for this PR (its head branch). Mutually exclusive with
+    /// `--run` / `--branch`.
     #[arg(long, conflicts_with_all = ["run", "branch"])]
     pr: Option<u64>,
-    /// Dispatch a fresh run of the workflow that produced this run, on the
-    /// same branch the run used. The run number is the `runs/<n>` in the
-    /// run-page URL — what `pr-status` surfaces as a CI context's
-    /// `target_url`. Mutually exclusive with `--pr` / `--branch`.
+    /// Re-run the same workflow on the same branch this run used. The run
+    /// number is the `runs/<n>` in the run-page URL. Mutually exclusive
+    /// with `--pr` / `--branch`.
     #[arg(long, conflicts_with_all = ["pr", "branch"])]
     run: Option<u64>,
-    /// Dispatch `--workflow` on this branch directly. Mutually exclusive
-    /// with `--pr` / `--run`.
+    /// Re-run `--workflow` on this branch. Mutually exclusive with
+    /// `--pr` / `--run`.
     #[arg(long, conflicts_with_all = ["pr", "run"])]
     branch: Option<String>,
-    /// Workflow file to dispatch for `--pr` / `--branch` (the file name under
-    /// `.forgejo/workflows/`). Ignored for `--run`, which resolves the
-    /// workflow from the run itself (falling back to this value).
+    /// Workflow file to run (default `ci.yml`). Ignored for `--run`,
+    /// which uses the run's own workflow.
     #[arg(long, default_value = "ci.yml")]
     workflow: String,
 }

hive-forge/src/verbs/comments.rs

@@ -44,15 +44,12 @@ const PAGE_SIZE: usize = 50;
 pub struct Args {
     /// Issue or PR number.
     pub(crate) number: u64,
-    /// Page size for the head-of-thread shape (Forgejo caps at 50).
+    /// Number of comments from the start of the thread (max 50).
     /// Mutually exclusive with `--tail`.
     #[arg(long, default_value_t = 50, conflicts_with = "tail")]
     limit: u64,
-    /// Return the last `N` comments in chronological order. Reads
-    /// the issue's `comments` count first, then fetches only the
-    /// `ceil(N/50) + 1` pages that contain the tail — work is
-    /// bounded by N, not by thread length. Mutually exclusive with
-    /// `--limit`.
+    /// Return the last `N` comments (chronological). Mutually exclusive
+    /// with `--limit`.
     #[arg(long)]
     tail: Option<usize>,
 }

hive-forge/src/verbs/pr_create.rs

@@ -48,29 +48,22 @@ pub struct Args {
     /// Read body from a file. `-` means stdin.
     #[arg(long = "body-file")]
     body_file: Option<String>,
-    /// Open as draft. Ignored in `--agit` mode (the `AGit` push has no
-    /// draft push-option).
+    /// Open as draft. Ignored in `--agit` mode.
     #[arg(long)]
     draft: bool,
-    /// Push the local `--head` branch to `--remote` before creating
-    /// the PR. Suppresses forgejo's "Create / Visit a pull request"
-    /// hint block (we print the URL ourselves).
+    /// Push the local `--head` branch to `--remote` before creating the PR.
     #[arg(long)]
     push: bool,
-    /// Remote name to push to. Defaults to the hyperhive convention
-    /// `forge` for the normal flow, and `origin` in `--agit` mode (the
-    /// remote a `hive-forge clone` sets up).
+    /// Remote to push to (default: `forge`, or `origin` in `--agit` mode).
     #[arg(long)]
     remote: Option<String>,
-    /// Open the PR via Forgejo's `AGit` flow: push the current `HEAD`
-    /// to `refs/for/<base>/<topic>` instead of calling the REST API.
-    /// Works for read-only collaborators (no branch-push needed). Run
-    /// from inside a cloned repo.
+    /// Open the PR via Forgejo's `AGit` flow instead of pushing a branch —
+    /// works for read-only collaborators. Run from inside a cloned repo.
     #[arg(long)]
     agit: bool,
-    /// `AGit` topic — groups repeated pushes into ONE PR (re-running
-    /// with the same topic updates it). Defaults to the current branch
-    /// name, or `contribution`. Only meaningful with `--agit`.
+    /// `AGit` topic — groups repeated pushes into one PR (re-run with the
+    /// same topic to update it). Defaults to the branch name. Only
+    /// meaningful with `--agit`.
     #[arg(long)]
     topic: Option<String>,
 }