diff --git a/hive-forge/src/main.rs b/hive-forge/src/main.rs
index 3aad7deb..6e8c07d4 100644
--- a/hive-forge/src/main.rs
+++ b/hive-forge/src/main.rs
@@ -36,17 +36,24 @@ use clap::{Parser, Subcommand};
     disable_help_subcommand = true
 )]
 struct Cli {
-    /// Repo to act on, as `owner/name` (default: `HIVE_FORGE_REPO`).
-    /// Works with any verb.
+    /// Repo override (default from `HIVE_FORGE_REPO`).
+    /// Applies to any verb; replaces the per-verb `[repo]` trailing
+    /// positional the bash helper used.
     #[arg(short = 'r', long, global = true)]
     repo: Option<String>,
-    /// Act as a dashboard-provisioned external forge account (by its
-    /// FORGES-tab label) instead of the internal forge. Independent of
-    /// `-r/--repo`.
+    /// 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.
     #[arg(short = 'f', long, global = true)]
     forge: Option<String>,
-    /// Emit JSON instead of the default human-readable output (for verbs
-    /// that support both).
+    /// 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.
     #[arg(long, global = true)]
     json: bool,
     #[command(subcommand)]
@@ -73,6 +80,8 @@ 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.
@@ -106,15 +115,21 @@ 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 repo URL. The instance disables push-to-create, so this is
+    /// 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 every label defined on the repo (name + description),
-    /// optionally filtered by a name substring.
+    /// 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).
     RepoLabels(verbs::repo_labels::Args),
-    /// Search the forge for repositories by keyword, topic, or description.
+    /// 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.
     RepoSearch(verbs::repo_search::Args),
     /// Triage lint queries (unassigned / no-reviewer / stale-branches / assignments).
     Lint(verbs::lint::Args),
@@ -163,13 +178,18 @@ 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>`).
-    /// Saves a zip, or pass `-o -` to stream to stdout.
+    /// 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).
     ArtifactGet(verbs::artifact_get::Args),
-    /// Print a CI Actions run's job step logs
-    /// (`--run <n> [--job i] [--step i]`).
+    /// 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.
     CiLog(verbs::ci_log::Args),
-    /// Re-run CI without an empty commit. Pass one of `--pr <n>`,
-    /// `--run <n>`, or `--branch <name>`; `--workflow` defaults to `ci.yml`.
+    /// 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`.
     CiRerun(verbs::ci_rerun::Args),
 }
 
diff --git a/hive-forge/src/verbs/ci_log.rs b/hive-forge/src/verbs/ci_log.rs
index b90329cb..a871a62e 100644
--- a/hive-forge/src/verbs/ci_log.rs
+++ b/hive-forge/src/verbs/ci_log.rs
@@ -30,17 +30,20 @@ use crate::client::Client;
 
 #[derive(ClapArgs)]
 pub struct Args {
-    /// Workflow run number — the `runs/<n>` in the run-page URL (shown
-    /// by `pr-status`).
+    /// Workflow run number — the `runs/<n>` in the run-page URL, which
+    /// `pr-status` surfaces as a CI context's `target_url`.
     #[arg(long)]
     run: u64,
-    /// Job index within the run (0-based, default 0).
+    /// Job index within the run (0-based; default 0 — the first job).
     #[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 (re-runs increment it; default 1).
+    /// Run attempt number for the durable persisted-log download (re-runs
+    /// increment it; default 1 covers the common single-attempt case).
     #[arg(long, default_value_t = 1)]
     attempt: u64,
 }
diff --git a/hive-forge/src/verbs/ci_rerun.rs b/hive-forge/src/verbs/ci_rerun.rs
index db038425..7ca8ed29 100644
--- a/hive-forge/src/verbs/ci_rerun.rs
+++ b/hive-forge/src/verbs/ci_rerun.rs
@@ -35,21 +35,23 @@ use crate::client::{Client, index};
 
 #[derive(ClapArgs)]
 pub struct Args {
-    /// Re-run CI for this PR (its head branch). Mutually exclusive with
-    /// `--run` / `--branch`.
+    /// Re-run CI for this PR: resolves the PR's head branch and dispatches
+    /// `--workflow` on it. Mutually exclusive with `--run` / `--branch`.
     #[arg(long, conflicts_with_all = ["run", "branch"])]
     pr: Option<u64>,
-    /// 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`.
+    /// 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`.
     #[arg(long, conflicts_with_all = ["pr", "branch"])]
     run: Option<u64>,
-    /// Re-run `--workflow` on this branch. Mutually exclusive with
-    /// `--pr` / `--run`.
+    /// Dispatch `--workflow` on this branch directly. Mutually exclusive
+    /// with `--pr` / `--run`.
     #[arg(long, conflicts_with_all = ["pr", "run"])]
     branch: Option<String>,
-    /// Workflow file to run (default `ci.yml`). Ignored for `--run`,
-    /// which uses the run's own workflow.
+    /// 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).
     #[arg(long, default_value = "ci.yml")]
     workflow: String,
 }
diff --git a/hive-forge/src/verbs/comments.rs b/hive-forge/src/verbs/comments.rs
index 17bde9e6..bde87687 100644
--- a/hive-forge/src/verbs/comments.rs
+++ b/hive-forge/src/verbs/comments.rs
@@ -44,12 +44,15 @@ const PAGE_SIZE: usize = 50;
 pub struct Args {
     /// Issue or PR number.
     pub(crate) number: u64,
-    /// Number of comments from the start of the thread (max 50).
+    /// Page size for the head-of-thread shape (Forgejo caps at 50).
     /// Mutually exclusive with `--tail`.
     #[arg(long, default_value_t = 50, conflicts_with = "tail")]
     limit: u64,
-    /// Return the last `N` comments (chronological). Mutually exclusive
-    /// with `--limit`.
+    /// 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`.
     #[arg(long)]
     tail: Option<usize>,
 }
diff --git a/hive-forge/src/verbs/diff.rs b/hive-forge/src/verbs/diff.rs
index 1aed2c2e..17bdebe1 100644
--- a/hive-forge/src/verbs/diff.rs
+++ b/hive-forge/src/verbs/diff.rs
@@ -23,9 +23,10 @@ use crate::client::{Client, index};
 pub struct Args {
     /// PR number.
     number: u64,
-    /// Print the unfiltered diff. By default, autogenerated-file hunks
-    /// (`flake.lock`, `Cargo.lock`, …) are collapsed to a placeholder so
-    /// human-authored changes stay readable.
+    /// Print the unfiltered diff including autogenerated-file
+    /// hunks (`flake.lock`, `Cargo.lock`, etc.). Default is to
+    /// collapse those hunks to a placeholder so the human-authored
+    /// changes aren't drowned in lock churn.
     #[arg(long)]
     full: bool,
 }
diff --git a/hive-forge/src/verbs/lint.rs b/hive-forge/src/verbs/lint.rs
index 079fd253..be7d378a 100644
--- a/hive-forge/src/verbs/lint.rs
+++ b/hive-forge/src/verbs/lint.rs
@@ -109,8 +109,10 @@ 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 the PR body
-    /// or any comment).
+    /// Reviewer login to look for (matches `@<reviewer>` in PR body or
+    /// any comment). Required — defaulting to a specific name would
+    /// bake one deployment's reviewer convention into the binary
+    /// (flagged in review).
     #[arg(long)]
     reviewer: String,
 }
diff --git a/hive-forge/src/verbs/list.rs b/hive-forge/src/verbs/list.rs
index a3da678c..471da239 100644
--- a/hive-forge/src/verbs/list.rs
+++ b/hive-forge/src/verbs/list.rs
@@ -89,8 +89,12 @@ 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`
-    /// to page through large result sets incrementally.
+    /// Page number to fetch (1-based; default 1). Combine with `--limit`
+    /// to walk a large result set incrementally — fetch page 1, process,
+    /// 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,
 }
diff --git a/hive-forge/src/verbs/pr_create.rs b/hive-forge/src/verbs/pr_create.rs
index 45545d4e..2d1f8d49 100644
--- a/hive-forge/src/verbs/pr_create.rs
+++ b/hive-forge/src/verbs/pr_create.rs
@@ -48,22 +48,29 @@ 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.
+    /// Open as draft. Ignored in `--agit` mode (the `AGit` push has no
+    /// draft push-option).
     #[arg(long)]
     draft: bool,
-    /// Push the local `--head` branch to `--remote` before creating the PR.
+    /// 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).
     #[arg(long)]
     push: bool,
-    /// Remote to push to (default: `forge`, or `origin` in `--agit` mode).
+    /// 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).
     #[arg(long)]
     remote: Option<String>,
-    /// Open the PR via Forgejo's `AGit` flow instead of pushing a branch —
-    /// works for read-only collaborators. Run from inside a cloned repo.
+    /// 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.
     #[arg(long)]
     agit: bool,
-    /// `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`.
+    /// `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`.
     #[arg(long)]
     topic: Option<String>,
 }
diff --git a/hive-forge/src/verbs/pr_merge.rs b/hive-forge/src/verbs/pr_merge.rs
index ac4c4755..884abbb8 100644
--- a/hive-forge/src/verbs/pr_merge.rs
+++ b/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.
+    /// Create a merge commit (Forgejo `Do: merge`).
     Merge,
-    /// Rebase the head branch onto the base, then fast-forward.
+    /// Rebase the head branch onto the base then fast-forward (Forgejo `Do: rebase`).
     Rebase,
 }
 
@@ -56,11 +56,13 @@ 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 (deleted by default).
+    /// Keep the head branch after merging. By default the head branch is
+    /// 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.
+    /// requests changes. Also sets Forgejo's `force_merge` so the server does
+    /// not refuse on its own status checks.
     #[arg(long)]
     force: bool,
 }
diff --git a/hive-forge/src/verbs/repo_create.rs b/hive-forge/src/verbs/repo_create.rs
index 2419228b..9ce580e8 100644
--- a/hive-forge/src/verbs/repo_create.rs
+++ b/hive-forge/src/verbs/repo_create.rs
@@ -27,10 +27,12 @@ pub struct Args {
     /// Create the repo as private (default: public).
     #[arg(long)]
     private: bool,
-    /// Default branch name (e.g. `main`). Only takes effect with `--auto-init`.
+    /// Default branch name (e.g. `main`). Forgejo applies it to the
+    /// initial commit, so it only takes effect alongside `--auto-init`.
     #[arg(long = "default-branch")]
     default_branch: Option<String>,
-    /// Create under this organisation instead of your own namespace.
+    /// Create under this organisation (`POST /orgs/<org>/repos`) instead
+    /// of the authenticated user's namespace.
     #[arg(long)]
     org: Option<String>,
     /// Seed an initial commit (README) so the repo is non-empty and can