From c64136d09493cae871f86c93517a850c9b5300f1 Mon Sep 17 00:00:00 2001
From: atlas <atlas@hyperhive.local>
Date: Thu, 23 Jul 2026 21:52:33 +0200
Subject: [PATCH] docs(#2671): trim hive-forge top-level + global-option help

Drop implementation mechanics from the `--help` surface, keep only
what a user needs to run the command:

- global `-r`/`-f`/`--json`: remove token-file paths, the bash-helper
  history, and the "already-JSON verbs ignore --json" aside.
- verb `about` strings (repo-create/repo-labels/repo-search/artifact-get/
  ci-log/ci-rerun/pr-commits): drop which-API / "no REST endpoint" /
  web-route / workflow-dispatch internals and cross-refs.

Per-verb arg help (verbs/*.rs) trimmed in follow-up commits.
---
 hive-forge/src/main.rs | 52 +++++++++++++-----------------------------
 1 file changed, 16 insertions(+), 36 deletions(-)

diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs
index 6e8c07d4..3aad7deb 100644
--- a/hive-forge/src/main.rs
+++ b/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`).
-    /// Applies to any verb; replaces the per-verb `[repo]` trailing
-    /// positional the bash helper used.
+    /// Repo to act on, as `owner/name` (default: `HIVE_FORGE_REPO`).
+    /// Works with any verb.
     #[arg(short = 'r', long, global = true)]
     repo: Option<String>,
-    /// Target an external forge account provisioned via the dashboard's
-    /// FORGES tab, by label, instead of the internal forge. Reads
-    /// `${HYPERHIVE_STATE_DIR}/forge-<label>-token` for the token and
-    /// `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.
+    /// Act as a dashboard-provisioned external forge account (by its
+    /// FORGES-tab label) instead of the internal forge. Independent of
+    /// `-r/--repo`.
     #[arg(short = 'f', long, global = true)]
     forge: Option<String>,
-    /// Emit JSON output instead of the verb's default human-readable
-    /// shape, for verbs that support both. Verbs whose
-    /// only output is already JSON (`issue`, `pr`, etc.) ignore this
-    /// flag — they always print JSON regardless.
+    /// Emit JSON instead of the default human-readable output (for verbs
+    /// that support both).
     #[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 supported path to a new repo. Pairs with `repo-add-collaborator`.
+    /// the repo URL.
     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
-    /// filtered by a name substring. Unlike `labels <number>` (which lists
-    /// 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).
+    /// List every label defined on the repo (name + description),
+    /// optionally filtered by a name substring.
     RepoLabels(verbs::repo_labels::Args),
-    /// Search for repositories on the forge instance by keyword, topic, or
-    /// description. Not repo-scoped — queries the instance-wide explore
-    /// endpoint. `--json` emits the full repository objects.
+    /// Search the forge for repositories by keyword, topic, or description.
     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
-    /// caller supplies the run number + artifact name. Saves a zip
-    /// (or `-o -` to stream).
+    /// Saves a zip, or pass `-o -` to stream to stdout.
     ArtifactGet(verbs::artifact_get::Args),
-    /// Print a CI Actions run's job step logs (`--run <n> [--job i]
-    /// [--step i]`). Uses Forgejo's web run-view streamer (no REST
-    /// endpoint exists); reliable for live + recently-finished runs.
+    /// Print a CI Actions run's job step logs
+    /// (`--run <n> [--job i] [--step i]`).
     CiLog(verbs::ci_log::Args),
-    /// Re-run CI without an empty commit: dispatches a fresh run via the
-    /// workflow-dispatch API. Pass one of `--pr <n>` (the PR head branch),
-    /// `--run <n>` (branch + workflow resolved from that run), or
-    /// `--branch <name>`; `--workflow <file>` defaults to `ci.yml`.
+    /// Re-run CI without an empty commit. Pass one of `--pr <n>`,
+    /// `--run <n>`, or `--branch <name>`; `--workflow` defaults to `ci.yml`.
     CiRerun(verbs::ci_rerun::Args),
 }