docs(#2671): trim per-verb arg help (repo-create)

Drop the API path from --org and the "Forgejo applies it to the initial
commit" mechanics from --default-branch (kept the user-facing caveat:
only takes effect with --auto-init). Swept the remaining verbs
(attachment-get, pr-reviews, attach, repo-add-collaborator, comment,
clone, pr-cmd router, …) — already user-relevant, no changes needed.

hive-forge/src/main.rs

@@ -36,24 +36,17 @@ use clap::{Parser, Subcommand};
     disable_help_subcommand = true
 )]
 struct Cli {
-    /// Repo override (default from `HIVE_FORGE_REPO`).
+    /// Repo to act on, as `owner/name` (default: `HIVE_FORGE_REPO`).
-    /// Applies to any verb; replaces the per-verb `[repo]` trailing
+    /// Works with any verb.
-    /// positional the bash helper used.
     #[arg(short = 'r', long, global = true)]
     repo: Option<String>,
-    /// Target an external forge account provisioned via the dashboard's
+    /// Act as a dashboard-provisioned external forge account (by its
-    /// FORGES tab, by label, instead of the internal forge. Reads
+    /// FORGES-tab label) instead of the internal forge. Independent of
-    /// `${HYPERHIVE_STATE_DIR}/forge-<label>-token` for the token and
+    /// `-r/--repo`.
-    /// `forge-<label>.json` for the base URL (the same two files the
-    /// dashboard writes) instead of `HIVE_FORGE_URL`/`forge-token`.
-    /// Orthogonal to `-r/--repo`, which still just picks which repo on
-    /// whichever forge is selected.
     #[arg(short = 'f', long, global = true)]
     forge: Option<String>,
-    /// Emit JSON output instead of the verb's default human-readable
+    /// Emit JSON instead of the default human-readable output (for verbs
-    /// shape, for verbs that support both. Verbs whose
+    /// that support both).
-    /// only output is already JSON (`issue`, `pr`, etc.) ignore this
-    /// flag — they always print JSON regardless.
     #[arg(long, global = true)]
     json: bool,
     #[command(subcommand)]
@@ -80,8 +73,6 @@ enum Verb {
     /// PR-scoped commands: `pr <show|status|create|merge|reviews|assign-reviewer|commits|diff|view|comment|comments|close|reopen|labels|assign-committer|timeline> …`.
     Pr(verbs::pr_cmd::Args),
     /// List a PR's commits as JSON (sha, message, author date, author).
-    /// Survives rebase-rewritten shas — message + author date let a
-    /// caller match the rows against linear `main` history.
     #[command(hide = true)]
     PrCommits(verbs::pr_commits::Args),
     /// Create a pull request. Prints the PR URL on success.
@@ -115,21 +106,15 @@ enum Verb {
     /// credentials auto-injected. Pairs with `pr-create --agit`.
     Clone(verbs::clone::Args),
     /// Create a forge repo under the current user (or `--org`). Prints
-    /// the repo URL. The instance disables push-to-create, so this is
+    /// the repo URL.
-    /// the supported path to a new repo. Pairs with `repo-add-collaborator`.
     RepoCreate(verbs::repo_create::Args),
     /// Add a collaborator to the active repo (`-r`/`HIVE_FORGE_REPO`)
     /// with a permission level. Companion to `repo-create`.
     RepoAddCollaborator(verbs::repo_add_collaborator::Args),
-    /// List the active repo's full label set (project-wide), optionally
+    /// List every label defined on the repo (name + description),
-    /// filtered by a name substring. Unlike `labels <number>` (which lists
+    /// optionally filtered by a name substring.
-    /// an issue/PR's labels), this shows every label defined on the repo —
-    /// the valid names + descriptions for triage / labelling. `--json`
-    /// emits the full label objects (id, name, color, description).
     RepoLabels(verbs::repo_labels::Args),
-    /// Search for repositories on the forge instance by keyword, topic, or
+    /// Search the forge for repositories by keyword, topic, or description.
-    /// description. Not repo-scoped — queries the instance-wide explore
-    /// endpoint. `--json` emits the full repository objects.
     RepoSearch(verbs::repo_search::Args),
     /// Triage lint queries (unassigned / no-reviewer / stale-branches / assignments).
     Lint(verbs::lint::Args),
@@ -178,18 +163,13 @@ enum Verb {
     /// prints the path (pass `-o -` to stream raw bytes to stdout).
     AttachmentGet(verbs::attachment_get::Args),
     /// Download a CI Actions artifact from a run (`<name> --run <n>`).
-    /// Forgejo serves artifacts only via the web route, not REST; the
+    /// Saves a zip, or pass `-o -` to stream to stdout.
-    /// caller supplies the run number + artifact name. Saves a zip
-    /// (or `-o -` to stream).
     ArtifactGet(verbs::artifact_get::Args),
-    /// Print a CI Actions run's job step logs (`--run <n> [--job i]
+    /// Print a CI Actions run's job step logs
-    /// [--step i]`). Uses Forgejo's web run-view streamer (no REST
+    /// (`--run <n> [--job i] [--step i]`).
-    /// endpoint exists); reliable for live + recently-finished runs.
     CiLog(verbs::ci_log::Args),
-    /// Re-run CI without an empty commit: dispatches a fresh run via the
+    /// Re-run CI without an empty commit. Pass one of `--pr <n>`,
-    /// workflow-dispatch API. Pass one of `--pr <n>` (the PR head branch),
+    /// `--run <n>`, or `--branch <name>`; `--workflow` defaults to `ci.yml`.
-    /// `--run <n>` (branch + workflow resolved from that run), or
-    /// `--branch <name>`; `--workflow <file>` defaults to `ci.yml`.
     CiRerun(verbs::ci_rerun::Args),
 }
 

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
+    /// Workflow run number — the `runs/<n>` in the run-page URL (shown
-    /// `pr-status` surfaces as a CI context's `target_url`.
+    /// 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
+    /// Run attempt number (re-runs increment it; default 1).
-    /// increment it; default 1 covers the common single-attempt case).
     #[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
+    /// Re-run CI for this PR (its head branch). Mutually exclusive with
-    /// `--workflow` on it. Mutually exclusive with `--run` / `--branch`.
+    /// `--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
+    /// Re-run the same workflow on the same branch this run used. The run
-    /// same branch the run used. The run number is the `runs/<n>` in the
+    /// number is the `runs/<n>` in the run-page URL. Mutually exclusive
-    /// run-page URL — what `pr-status` surfaces as a CI context's
+    /// with `--pr` / `--branch`.
-    /// `target_url`. Mutually exclusive with `--pr` / `--branch`.
     #[arg(long, conflicts_with_all = ["pr", "branch"])]
     run: Option<u64>,
-    /// Dispatch `--workflow` on this branch directly. Mutually exclusive
+    /// Re-run `--workflow` on this branch. Mutually exclusive with
-    /// with `--pr` / `--run`.
+    /// `--pr` / `--run`.
     #[arg(long, conflicts_with_all = ["pr", "run"])]
     branch: Option<String>,
-    /// Workflow file to dispatch for `--pr` / `--branch` (the file name under
+    /// Workflow file to run (default `ci.yml`). Ignored for `--run`,
-    /// `.forgejo/workflows/`). Ignored for `--run`, which resolves the
+    /// which uses the run's own workflow.
-    /// workflow from the run itself (falling back to this value).
     #[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
+    /// Return the last `N` comments (chronological). Mutually exclusive
-    /// the issue's `comments` count first, then fetches only the
+    /// with `--limit`.
-    /// `ceil(N/50) + 1` pages that contain the tail — work is
-    /// bounded by N, not by thread length. Mutually exclusive with
-    /// `--limit`.
     #[arg(long)]
     tail: Option<usize>,
 }

hive-forge/src/verbs/diff.rs

@@ -23,10 +23,9 @@ use crate::client::{Client, index};
 pub struct Args {
     /// PR number.
     number: u64,
-    /// Print the unfiltered diff including autogenerated-file
+    /// Print the unfiltered diff. By default, autogenerated-file hunks
-    /// hunks (`flake.lock`, `Cargo.lock`, etc.). Default is to
+    /// (`flake.lock`, `Cargo.lock`, …) are collapsed to a placeholder so
-    /// collapse those hunks to a placeholder so the human-authored
+    /// human-authored changes stay readable.
-    /// changes aren't drowned in lock churn.
     #[arg(long)]
     full: bool,
 }

hive-forge/src/verbs/lint.rs

@@ -109,10 +109,8 @@ struct NoReviewerArgs {
     /// Filter by PR state.
     #[arg(long, value_enum, default_value_t = State::Open)]
     state: State,
-    /// Reviewer login to look for (matches `@<reviewer>` in PR body or
+    /// Reviewer login to look for (matches `@<reviewer>` in the PR body
-    /// any comment). Required — defaulting to a specific name would
+    /// or any comment).
-    /// bake one deployment's reviewer convention into the binary
-    /// (flagged in review).
     #[arg(long)]
     reviewer: String,
 }

hive-forge/src/verbs/list.rs

@@ -89,12 +89,8 @@ pub struct Args {
     /// ~50, applies). Must be >= 1.
     #[arg(long, default_value_t = 30, value_parser = clap::value_parser!(u64).range(1..))]
     limit: u64,
-    /// Page number to fetch (1-based; default 1). Combine with `--limit`
+    /// Page number to fetch (1-based, default 1). Combine with `--limit`
-    /// to walk a large result set incrementally — fetch page 1, process,
+    /// to page through large result sets incrementally.
-    /// fetch page 2, … until a short/empty page. This keeps each call
-    /// token-bounded (one page at a time) instead of pulling a whole
-    /// repo's population into a single response. Must be >= 1 (the forge
-    /// pages are 1-based; page 0 is rejected).
     #[arg(long, default_value_t = 1, value_parser = clap::value_parser!(u64).range(1..))]
     page: u64,
 }

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

hive-forge/src/verbs/pr_merge.rs

@@ -24,9 +24,9 @@ use crate::client::{Client, index, split_repo};
 /// per-commit history, so a squash option isn't exposed).
 #[derive(Clone, Copy, ValueEnum)]
 pub enum Method {
-    /// Create a merge commit (Forgejo `Do: merge`).
+    /// Create a merge commit.
     Merge,
-    /// Rebase the head branch onto the base then fast-forward (Forgejo `Do: rebase`).
+    /// Rebase the head branch onto the base, then fast-forward.
     Rebase,
 }
 
@@ -56,13 +56,11 @@ pub struct Args {
     /// Merge strategy (default: a merge commit). Squash is not offered.
     #[arg(long, value_enum, default_value = "merge")]
     method: Method,
-    /// Keep the head branch after merging. By default the head branch is
+    /// Keep the head branch after merging (deleted by default).
-    /// deleted once the merge succeeds.
     #[arg(long = "keep-branch")]
     keep_branch: bool,
     /// Merge even if the PR is not mergeable, CI is not green, or a review
-    /// requests changes. Also sets Forgejo's `force_merge` so the server does
+    /// requests changes.
-    /// not refuse on its own status checks.
     #[arg(long)]
     force: bool,
 }

hive-forge/src/verbs/repo_create.rs

@@ -27,12 +27,10 @@ pub struct Args {
     /// Create the repo as private (default: public).
     #[arg(long)]
     private: bool,
-    /// Default branch name (e.g. `main`). Forgejo applies it to the
+    /// Default branch name (e.g. `main`). Only takes effect with `--auto-init`.
-    /// initial commit, so it only takes effect alongside `--auto-init`.
     #[arg(long = "default-branch")]
     default_branch: Option<String>,
-    /// Create under this organisation (`POST /orgs/<org>/repos`) instead
+    /// Create under this organisation instead of your own namespace.
-    /// of the authenticated user's namespace.
     #[arg(long)]
     org: Option<String>,
     /// Seed an initial commit (README) so the repo is non-empty and can