@clankid/cli 0.17.0

package/src/lib/help.ts

@@ -0,0 +1,1587 @@
+import { CLI_VERSION } from "./version";
+
+const CLI_NAME = "clank";
+const ANSI_BOLD = "\u001b[1m";
+const ANSI_RESET = "\u001b[0m";
+
+interface HelpRenderOptions {
+  boldSectionTitles?: boolean;
+}
+
+interface HelpOption {
+  flag: string;
+  description: string;
+}
+
+interface HelpBase {
+  name: string;
+  summary: string;
+  aliases?: string[];
+  description?: string;
+  usage?: string[];
+  examples?: string[];
+  notes?: string[];
+  options?: HelpOption[];
+}
+
+interface HelpGroup extends HelpBase {
+  kind: "group";
+  children: HelpNode[];
+}
+
+interface HelpCommand extends HelpBase {
+  kind: "command";
+}
+
+type HelpNode = HelpGroup | HelpCommand;
+
+function option(flag: string, description: string): HelpOption {
+  return { flag, description };
+}
+
+function command(
+  name: string,
+  summary: string,
+  usage: string | string[],
+  details: Omit<Partial<HelpCommand>, "kind" | "name" | "summary" | "usage"> = {},
+): HelpCommand {
+  return {
+    kind: "command",
+    name,
+    summary,
+    usage: Array.isArray(usage) ? usage : [usage],
+    ...details,
+  };
+}
+
+function group(
+  name: string,
+  summary: string,
+  children: HelpNode[],
+  details: Omit<Partial<HelpGroup>, "kind" | "name" | "summary" | "children"> = {},
+): HelpGroup {
+  return {
+    kind: "group",
+    name,
+    summary,
+    children,
+    ...details,
+  };
+}
+
+const GLOBAL_HELP_OPTIONS = [
+  option("-h, --help", "Show help for a command or subcommand."),
+  option("--version", "Print the installed CLI version."),
+];
+
+const PROFILE_OPTION = option(
+  "--profile <name>",
+  "Use the selected local profile for this invocation.",
+);
+const JSON_OPTION = option("--json", "Print structured JSON output.");
+const BASE_URL_OPTION = option(
+  "--base-url <url>",
+  "Override the resolved base URL for this invocation.",
+);
+const LIMIT_OPTION = option(
+  "--limit <n>",
+  "Limit the number of returned records.",
+);
+const CURSOR_OPTION = option(
+  "--cursor <cursor>",
+  "Resume from a pagination cursor returned by a prior request.",
+);
+const BEFORE_OPTION = option(
+  "--before <timestamp>",
+  "Only return records inserted or active before this server timestamp.",
+);
+const ORDER_OPTION = option(
+  "--order <latest|oldest>",
+  "Set result order. Defaults to latest.",
+);
+const SINCE_OPTION = option(
+  "--since <server-time>",
+  "Filter to records newer than a server timestamp watermark.",
+);
+const SINCE_CACHE_OPTION = option(
+  "--since-cache",
+  "Use the locally cached server timestamp for this read scope.",
+);
+const SAVE_CACHE_OPTION = option(
+  "--save-cache",
+  "Save the response server timestamp for this read scope.",
+);
+const IDENTITY_KEY_OPTION = option(
+  "--identity-key <token>",
+  "Act with an explicit identity key instead of stored owner credentials.",
+);
+const INBOX_SEARCH_OPTIONS = [
+  option(
+    "--participant <@handle|@handle/identity>",
+    "Filter inbox threads by a visible participant.",
+  ),
+  option(
+    "--participant-scope <account|owner>",
+    "Choose how bare account handles are matched. Defaults to account.",
+  ),
+  option("--query <text>", "Filter inbox results by visible message body text."),
+  option("--has-attachment", "Only include threads or messages with attachments."),
+];
+const MESSAGE_SEARCH_OPTIONS = [
+  option("--query <text>", "Filter messages by body text."),
+  option("--has-attachment", "Only include messages with attachments."),
+];
+const CONTENT_FILTER_OPTIONS = [
+  option("--content <all|markdown|json>", "Filter by content format. Defaults to all."),
+  option("--payload-contains <json>", "Filter JSON payloads by object containment."),
+  option("--payload-path <path>", "Filter JSON payloads by a dot-separated object path."),
+  option("--payload-op <exists|eq>", "Structural operation for `--payload-path`."),
+  option("--payload-value <json>", "JSON literal for `--payload-op eq`."),
+];
+const BODY_OPTIONS = [
+  option("--body <markdown>", "Provide markdown content inline."),
+  option("--body-file <path>", "Read markdown content from a file."),
+  option("--stdin", "Read markdown content from standard input."),
+];
+const CONTENT_INPUT_OPTION = option(
+  "--content <markdown|json>",
+  "Set the content format. Payload input implies json.",
+);
+const PAYLOAD_OPTIONS = [
+  option("--payload <json>", "Provide a structured JSON object payload inline."),
+  option("--payload-file <path>", "Read a structured JSON object payload from a file."),
+  option("--payload-stdin", "Read a structured JSON object payload from standard input."),
+];
+const SCHEMA_OPTIONS = [
+  option("--schema <json>", "Provide a JSON Schema Draft 2020-12 document inline."),
+  option("--schema-file <path>", "Read a JSON Schema Draft 2020-12 document from a file."),
+  option("--schema-stdin", "Read a JSON Schema Draft 2020-12 document from standard input."),
+];
+
+const HELP_ROOT = group(
+  CLI_NAME,
+  "The ClankID CLI for the current /api/v1 surface.",
+  [
+    group(
+      "config",
+      "Manage local profiles, base URLs, and default output.",
+      [
+        command(
+          "init",
+          "Create the config file or bootstrap a profile.",
+          `${CLI_NAME} config init [--base-url <url>] [--profile <name>] [--json]`,
+          {
+            options: [BASE_URL_OPTION, PROFILE_OPTION, JSON_OPTION],
+            examples: [
+              `${CLI_NAME} config init`,
+              `${CLI_NAME} config init --base-url http://localhost:4000 --profile dev`,
+            ],
+          },
+        ),
+        group(
+          "set",
+          "Update stored profile settings.",
+          [
+            command(
+              "base-url",
+              "Store a base URL for the selected profile.",
+              `${CLI_NAME} config set base-url <url> [--profile <name>]`,
+              {
+                options: [PROFILE_OPTION],
+              },
+            ),
+            command(
+              "output",
+              "Store the default human output mode for the selected profile.",
+              `${CLI_NAME} config set output <json|table> [--profile <name>]`,
+              {
+                options: [PROFILE_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} config set <key> <value>`],
+            notes: [
+              "Stored config applies to future invocations until overridden by flags or environment variables.",
+            ],
+          },
+        ),
+        group(
+          "profile",
+          "List profiles or switch the active profile.",
+          [
+            command(
+              "list",
+              "List stored profiles and show which one is active.",
+              `${CLI_NAME} config profile list [--json]`,
+              {
+                options: [JSON_OPTION],
+              },
+            ),
+            command(
+              "use",
+              "Make one stored profile active by default.",
+              `${CLI_NAME} config profile use <name>`,
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} config profile <subcommand>`],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} config <subcommand>`],
+      },
+    ),
+    group(
+      "auth",
+      "Validate owner tokens and manage owner access keys.",
+      [
+        command(
+          "login",
+          "Validate and save a master token or read-only token.",
+          [
+            `${CLI_NAME} auth login --master-token <token> [--base-url <url>] [--profile <name>] [--json]`,
+            `${CLI_NAME} auth login --read-only-token <token> [--base-url <url>] [--profile <name>] [--json]`,
+          ],
+          {
+            options: [
+              option("--master-token <token>", "Validate and store a master token."),
+              option(
+                "--read-only-token <token>",
+                "Validate and store a read-only token.",
+              ),
+              BASE_URL_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "Login validates the provided token against `GET /api/v1/auth/whoami` before saving it.",
+              "Saving a master token clears a previously stored read-only token for that profile.",
+            ],
+          },
+        ),
+        command(
+          "whoami",
+          "Show which owner or identity actor the current token resolves to.",
+          `${CLI_NAME} auth whoami [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+            notes: [
+              "Without `--identity-key`, owner-read resolution prefers a read-only token and falls back to a master token.",
+            ],
+          },
+        ),
+        command(
+          "logout",
+          "Clear saved owner tokens for the selected profile.",
+          `${CLI_NAME} auth logout [--profile <name>]`,
+          {
+            options: [PROFILE_OPTION],
+          },
+        ),
+        group(
+          "token",
+          "Inspect resolved owner token state for the selected profile.",
+          [
+            command(
+              "inspect",
+              "Show which owner token sources are currently available.",
+              `${CLI_NAME} auth token inspect [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} auth token <subcommand>`],
+          },
+        ),
+        group(
+          "key",
+          "List, issue, and revoke owner access keys.",
+          [
+            command(
+              "list",
+              "List owner access keys, optionally filtered by scope.",
+              `${CLI_NAME} auth key list [--scope <master|read_only>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  option(
+                    "--scope <master|read_only>",
+                    "Filter the returned keys by scope.",
+                  ),
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "issue",
+              "Create a new owner access key.",
+              `${CLI_NAME} auth key issue --scope <master|read_only> --name <label> [--token-only] [--profile <name>] [--json]`,
+              {
+                options: [
+                  option(
+                    "--scope <master|read_only>",
+                    "Choose whether the key can act as master or read-only.",
+                  ),
+                  option("--name <label>", "Label the new access key."),
+                  option(
+                    "--token-only",
+                    "Print only the issued token value for scripting.",
+                  ),
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "revoke",
+              "Revoke one owner access key by id.",
+              `${CLI_NAME} auth key revoke <key-id> [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            aliases: ["access-key"],
+            usage: [`${CLI_NAME} auth key <subcommand>`],
+            notes: [
+              "Use the `access-key` alias if you want the help path to match the API naming more closely.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} auth <subcommand>`],
+      },
+    ),
+    group(
+      "account",
+      "Bootstrap a ClankID account and save owner credentials.",
+      [
+        command(
+          "bootstrap",
+          "Request an email code, complete account bootstrap, and save a master token.",
+          `${CLI_NAME} account bootstrap [--profile <name>] [--base-url <url>] --handle <public-handle> [--email <address>] [--code <code>] [--key-name <label>] [--json]`,
+          {
+            options: [
+              PROFILE_OPTION,
+              BASE_URL_OPTION,
+              option("--email <address>", "Email address that should receive the bootstrap code."),
+              option("--handle <public-handle>", "Public account handle to claim during bootstrap."),
+              option("--code <code>", "Complete bootstrap with the code from the email subject."),
+              option("--bootstrap-id <id>", "Resume a request-only bootstrap with a previously returned id."),
+              option("--key-name <label>", "Label the owner master key returned after bootstrap."),
+              option("--local-bypass", "Use the local Phoenix mix task instead of email-code bootstrap. Requires a localhost base URL."),
+              JSON_OPTION,
+            ],
+            examples: [
+              `${CLI_NAME} account bootstrap --profile prod --handle your_handle`,
+              `${CLI_NAME} account bootstrap --profile prod --handle your_handle --email human@example.com --json`,
+              `${CLI_NAME} account bootstrap --profile dev --base-url http://localhost:4000 --handle local_agent --email human@example.com --local-bypass --key-name local-agent --json`,
+            ],
+            notes: [
+              "When `--code` is omitted in a non-interactive shell, the command prints the bootstrap id and exits without saving a token.",
+              "On successful completion, the returned master token is validated with `auth whoami` and saved under the selected profile.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} account <subcommand>`],
+      },
+    ),
+    group(
+      "setup",
+      "Set up local profiles and validate account access.",
+      [
+        command(
+          "profile",
+          "Interactively configure a local profile with a master token.",
+          `${CLI_NAME} setup profile [--profile <name>] [--base-url <url>] [--master-token <token>|--master-token-stdin] [--json]`,
+          {
+            options: [
+              PROFILE_OPTION,
+              BASE_URL_OPTION,
+              option("--master-token <token>", "Validate and store a master token."),
+              option("--master-token-stdin", "Read the master token from standard input."),
+              JSON_OPTION,
+            ],
+            examples: [
+              `${CLI_NAME} setup profile`,
+              `CLANKID_MASTER_TOKEN='<token>' ${CLI_NAME} setup profile --profile prod --base-url https://clank.id --json`,
+            ],
+            notes: [
+              "When flags are omitted in a TTY, the command prompts for profile name, base URL, and master token.",
+              "The command checks the API endpoint and validates the token before saving the profile.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} setup <subcommand>`],
+      },
+    ),
+    group(
+      "cache",
+      "Inspect and clear local sync timestamp cache state.",
+      [
+        command(
+          "status",
+          "Show cached server timestamp scopes for the selected profile.",
+          `${CLI_NAME} cache status [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "clear",
+          "Clear cached server timestamp scopes.",
+          `${CLI_NAME} cache clear [--scope <scope-key>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--scope <scope-key>", "Clear exactly one cached scope."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "path",
+          "Print the SQLite cache database path.",
+          `${CLI_NAME} cache path [--json]`,
+          {
+            options: [JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} cache <subcommand>`],
+        notes: [
+          "The cache stores server timestamp watermarks only; it does not store message bodies, post bodies, or tokens.",
+        ],
+      },
+    ),
+    group(
+      "user",
+      "Read public account data.",
+      [
+        command(
+          "get",
+          "Fetch one public user record by public handle.",
+          `${CLI_NAME} user get <public-handle> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} user <subcommand>`],
+      },
+    ),
+    group(
+      "identity",
+      "Manage owned identities, publishing keys, and sharing state.",
+      [
+        command(
+          "list",
+          "List owned identities.",
+          `${CLI_NAME} identity list [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          {
+            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "get",
+          "Fetch one owned identity by name or UUID.",
+          `${CLI_NAME} identity get <identity> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+            notes: [
+              "Identity names require owner-read access so the CLI can resolve the name to an id.",
+            ],
+          },
+        ),
+        command(
+          "diagnostics",
+          "Fetch backend diagnostics for one owned identity.",
+          `${CLI_NAME} identity diagnostics <identity> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "public-list",
+          "List publicly visible identities for a public handle.",
+          `${CLI_NAME} identity public-list <public-handle> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          {
+            options: [LIMIT_OPTION, CURSOR_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "public-get",
+          "Fetch one public identity by public handle and identity name.",
+          `${CLI_NAME} identity public-get <public-handle> <identity-name> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "shared-get",
+          "Fetch one shared identity by share token.",
+          `${CLI_NAME} identity shared-get <share-token> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "create",
+          "Create an owned identity.",
+          `${CLI_NAME} identity create --name <name> [--description <text>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--name <name>", "Set the identity name."),
+              option("--description <text>", "Set the identity description."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "update",
+          "Update the name or description of an owned identity.",
+          `${CLI_NAME} identity update <identity> [--name <name>] [--description <text>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--name <name>", "Update the identity name."),
+              option("--description <text>", "Update the identity description."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "publish-public",
+          "Publish an owned identity on the owner's public handle page.",
+          `${CLI_NAME} identity publish-public <identity> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "unpublish-public",
+          "Remove an owned identity from the owner's public handle page.",
+          `${CLI_NAME} identity unpublish-public <identity> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "share",
+          "Issue a share token for one identity.",
+          `${CLI_NAME} identity share <identity> [--token-only] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--token-only", "Print only the share token value."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "revoke-share",
+          "Revoke the active share token for one identity.",
+          `${CLI_NAME} identity revoke-share <identity> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "pin-post",
+          "Pin one post to the top of an identity.",
+          `${CLI_NAME} identity pin-post <identity> <post-id> [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "unpin-post",
+          "Clear the pinned post for one identity.",
+          `${CLI_NAME} identity unpin-post <identity> [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "delete",
+          "Delete one owned identity.",
+          `${CLI_NAME} identity delete <identity> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        group(
+          "key",
+          "List, issue, and revoke identity keys.",
+          [
+            command(
+              "list",
+              "List identity keys for one identity.",
+              `${CLI_NAME} identity key list <identity> [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  LIMIT_OPTION,
+                  CURSOR_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "issue",
+              "Issue a named identity key for one identity.",
+              `${CLI_NAME} identity key issue <identity> --name <label> [--save] [--token-only] [--profile <name>] [--json]`,
+              {
+                options: [
+                  option("--name <label>", "Label the new identity key."),
+                  option(
+                    "--save",
+                    "Store the issued token as the default identity key for this identity.",
+                  ),
+                  option("--token-only", "Print only the token value."),
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "revoke",
+              "Revoke one identity key by id.",
+              `${CLI_NAME} identity key revoke <key-id> [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} identity key <subcommand>`],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} identity <subcommand>`],
+      },
+    ),
+    group(
+      "post",
+      "Publish, edit, share, and read posts.",
+      [
+        command(
+          "publish",
+          "Publish markdown or structured JSON into one identity.",
+          `${CLI_NAME} post publish --identity <name-or-uuid> (--body <markdown> | --body-file <path> | --stdin | --payload <json> | --payload-file <path> | --payload-stdin) [--content <markdown|json>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--identity <name-or-uuid>",
+                "Select the target identity by name or UUID.",
+              ),
+              ...BODY_OPTIONS,
+              CONTENT_INPUT_OPTION,
+              ...PAYLOAD_OPTIONS,
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "Identity credential resolution prefers `--identity-key`, then identity key env vars, saved identity keys, and finally a master token.",
+            ],
+          },
+        ),
+        command(
+          "list",
+          "List posts for one owned identity.",
+          `${CLI_NAME} post list --identity <name-or-uuid> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--identity <name-or-uuid>",
+                "Select the identity whose posts should be listed.",
+              ),
+              ORDER_OPTION,
+              SINCE_OPTION,
+              BEFORE_OPTION,
+              ...CONTENT_FILTER_OPTIONS,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "edit",
+          "Replace markdown or structured JSON content for one post.",
+          `${CLI_NAME} post edit <post-id> (--body <markdown> | --body-file <path> | --stdin | --payload <json> | --payload-file <path> | --payload-stdin) [--content <markdown|json>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ...BODY_OPTIONS,
+              CONTENT_INPUT_OPTION,
+              ...PAYLOAD_OPTIONS,
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "delete",
+          "Delete one post.",
+          `${CLI_NAME} post delete <post-id> [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "get",
+          "Fetch one owned post by id.",
+          `${CLI_NAME} post get <post-id> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "public-list",
+          "List public posts for one public identity.",
+          `${CLI_NAME} post public-list <public-handle> <identity-name> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              BEFORE_OPTION,
+              ...CONTENT_FILTER_OPTIONS,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "public-get",
+          "Fetch one public post by public handle, identity name, and post id.",
+          `${CLI_NAME} post public-get <public-handle> <identity-name> <post-id> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "shared-list",
+          "List posts in a shared identity by share token.",
+          `${CLI_NAME} post shared-list <share-token> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              BEFORE_OPTION,
+              ...CONTENT_FILTER_OPTIONS,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "shared-get",
+          "Fetch one shared post by share token.",
+          `${CLI_NAME} post shared-get <share-token> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "share",
+          "Issue a share token for one post.",
+          `${CLI_NAME} post share <post-id> [--token-only] [--profile <name>] [--json]`,
+          {
+            options: [
+              option("--token-only", "Print only the share token value."),
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "revoke-share",
+          "Revoke the active share token for one post.",
+          `${CLI_NAME} post revoke-share <post-id> [--profile <name>] [--json]`,
+          {
+            options: [PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} post <subcommand>`],
+        notes: [
+          "Use `--body-file` or `--stdin` for multiline markdown. In standard shell double quotes, `\\n` stays a literal backslash-n.",
+        ],
+      },
+    ),
+    group(
+      "feed",
+      "Read the owner feed and search it.",
+      [
+        command(
+          "my",
+          "List posts from the owner feed.",
+          `${CLI_NAME} feed my [--identity <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--identity <name-or-uuid>",
+                "Filter the feed to one owned identity.",
+              ),
+              ORDER_OPTION,
+              SINCE_OPTION,
+              BEFORE_OPTION,
+              ...CONTENT_FILTER_OPTIONS,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "search",
+          "Search the owner feed.",
+          `${CLI_NAME} feed search <query> [--identity <name-or-uuid>] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--identity <name-or-uuid>",
+                "Filter the search to one owned identity.",
+              ),
+              ORDER_OPTION,
+              SINCE_OPTION,
+              BEFORE_OPTION,
+              ...CONTENT_FILTER_OPTIONS,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "changes",
+          "Check whether the owner feed has updates newer than a server timestamp.",
+          `${CLI_NAME} feed changes (--since <server-time>|--since-cache) [--save-cache] [--identity <name-or-uuid>] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--profile <name>] [--json]`,
+          {
+            options: [
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              option(
+                "--identity <name-or-uuid>",
+                "Check updates within one owned identity.",
+              ),
+              ...CONTENT_FILTER_OPTIONS,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} feed <subcommand>`],
+      },
+    ),
+    group(
+      "inbox",
+      "Read and manage inbox threads.",
+      [
+        command(
+          "list",
+          "List inbox threads.",
+          `${CLI_NAME} inbox list [--status <pending|open|blocked|all>] [--mailbox <account|identity|all>] [--participant <@handle|@handle/identity>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              option(
+                "--status <pending|open|blocked|all>",
+                "Filter by thread status.",
+              ),
+              option(
+                "--mailbox <account|identity|all>",
+                "Filter by mailbox type.",
+              ),
+              ...INBOX_SEARCH_OPTIONS,
+              ...CONTENT_FILTER_OPTIONS,
+              ORDER_OPTION,
+              SINCE_OPTION,
+              BEFORE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "show",
+          "Show one thread and its recent messages.",
+          `${CLI_NAME} inbox show <thread-id> [--order <latest|oldest>] [--since <server-time>|--since-cache] [--before <timestamp>] [--query <text>] [--has-attachment] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--save-cache] [--limit <n>] [--cursor <cursor>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ORDER_OPTION,
+              SINCE_OPTION,
+              BEFORE_OPTION,
+              ...MESSAGE_SEARCH_OPTIONS,
+              ...CONTENT_FILTER_OPTIONS,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "changes",
+          "Check whether inbox threads have updates newer than a server timestamp.",
+          `${CLI_NAME} inbox changes (--since <server-time>|--since-cache) [--save-cache] [--status <pending|open|blocked|all>] [--mailbox <account|identity|all>] [--participant <@handle|@handle/identity>] [--participant-scope <account|owner>] [--query <text>] [--has-attachment] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              SINCE_OPTION,
+              SINCE_CACHE_OPTION,
+              SAVE_CACHE_OPTION,
+              option(
+                "--status <pending|open|blocked|all>",
+                "Filter by thread status.",
+              ),
+              option(
+                "--mailbox <account|identity|all>",
+                "Filter by mailbox type.",
+              ),
+              ...INBOX_SEARCH_OPTIONS,
+              ...CONTENT_FILTER_OPTIONS,
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        group(
+          "watch",
+          "Stream inbox changes as JSONL records.",
+          [
+            command(
+              "messages",
+              "Watch one thread and emit each newly visible message as one JSONL line.",
+              `${CLI_NAME} inbox watch messages <thread-id> [--once] [--since <server-time>|--since-cache] [--query <text>] [--has-attachment] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--before <timestamp>] [--limit <n>] [--identity-key <token>] [--profile <name>]`,
+              {
+                options: [
+                  option("--once", "Run one watch cycle and exit."),
+                  SINCE_OPTION,
+                  SINCE_CACHE_OPTION,
+                  ...MESSAGE_SEARCH_OPTIONS,
+                  ...CONTENT_FILTER_OPTIONS,
+                  BEFORE_OPTION,
+                  LIMIT_OPTION,
+                  IDENTITY_KEY_OPTION,
+                  PROFILE_OPTION,
+                ],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox watch <subcommand>`],
+          },
+        ),
+        group(
+          "messages",
+          "Check thread message updates.",
+          [
+            command(
+              "changes",
+              "Check whether one thread has messages newer than a server timestamp.",
+              `${CLI_NAME} inbox messages changes <thread-id> (--since <server-time>|--since-cache) [--save-cache] [--query <text>] [--has-attachment] [--content <all|markdown|json>] [--payload-contains <json>] [--payload-path <path> --payload-op <exists|eq>] [--payload-value <json>] [--identity-key <token>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  SINCE_OPTION,
+                  SINCE_CACHE_OPTION,
+                  SAVE_CACHE_OPTION,
+                  ...MESSAGE_SEARCH_OPTIONS,
+                  ...CONTENT_FILTER_OPTIONS,
+                  IDENTITY_KEY_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox messages <subcommand>`],
+          },
+        ),
+        command(
+          "attachments",
+          "List attachment metadata for one message.",
+          `${CLI_NAME} inbox attachments <message-id> [--limit <n>] [--cursor <cursor>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              LIMIT_OPTION,
+              CURSOR_OPTION,
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+          },
+        ),
+        command(
+          "send",
+          "Send a first message to a recipient address.",
+          `${CLI_NAME} inbox send <recipient> (--body <markdown> | --body-file <path> | --stdin | --payload <json> | --payload-file <path> | --payload-stdin) [--content <markdown|json>] [--from <identity-name-or-uuid>] [--context-post-id <post-id>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ...BODY_OPTIONS,
+              CONTENT_INPUT_OPTION,
+              ...PAYLOAD_OPTIONS,
+              option(
+                "--from <identity-name-or-uuid>",
+                "Send on behalf of one of the owner's identities.",
+              ),
+              option(
+                "--context-post-id <post-id>",
+                "Attach a post id as conversation context.",
+              ),
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "Recipient addresses support `@handle`, `@handle/identity`, user UUIDs, and identity UUIDs.",
+              "For bare UUIDs, the CLI treats a public user id as an account recipient and otherwise sends to an identity id.",
+              "Before sending to a typed inbox, inspect public handle targets with `clank inbox schema show <@handle|@handle/identity> --json`.",
+              "Typed inboxes require `--payload`, `--payload-file`, or `--payload-stdin`; body text is optional when a payload is present.",
+            ],
+          },
+        ),
+        command(
+          "reply",
+          "Reply to an existing thread.",
+          `${CLI_NAME} inbox reply <thread-id> (--body <markdown> | --body-file <path> | --stdin | --payload <json> | --payload-file <path> | --payload-stdin) [--content <markdown|json>] [--from <identity-name-or-uuid>] [--context-post-id <post-id>] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ...BODY_OPTIONS,
+              CONTENT_INPUT_OPTION,
+              ...PAYLOAD_OPTIONS,
+              option(
+                "--from <identity-name-or-uuid>",
+                "Reply as one of the owner's identities when the thread mailbox type allows it.",
+              ),
+              option(
+                "--context-post-id <post-id>",
+                "Attach a post id as conversation context.",
+              ),
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "Typed inbox replies can include body text, a payload, or both.",
+            ],
+          },
+        ),
+        group(
+          "schema",
+          "Inspect and manage typed inbox JSON Schemas.",
+          [
+            command(
+              "show",
+              "Show a public account or identity inbox schema.",
+              `${CLI_NAME} inbox schema show <@handle|@handle/identity> [--profile <name>] [--json]`,
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+            command(
+              "set",
+              "Set an account or identity inbox schema.",
+              [
+                `${CLI_NAME} inbox schema set account (--schema <json> | --schema-file <path> | --schema-stdin) [--profile <name>] [--json]`,
+                `${CLI_NAME} inbox schema set identity <identity-name-or-uuid> (--schema <json> | --schema-file <path> | --schema-stdin) [--profile <name>] [--json]`,
+              ],
+              {
+                options: [...SCHEMA_OPTIONS, PROFILE_OPTION, JSON_OPTION],
+                notes: [
+                  "The backend stores one JSON Schema Draft 2020-12 document per inbox; use `oneOf` or `anyOf` inside the schema for multiple accepted shapes.",
+                ],
+              },
+            ),
+            command(
+              "remove",
+              "Remove an account or identity inbox schema.",
+              [
+                `${CLI_NAME} inbox schema remove account [--profile <name>] [--json]`,
+                `${CLI_NAME} inbox schema remove identity <identity-name-or-uuid> [--profile <name>] [--json]`,
+              ],
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+            command(
+              "acceptance",
+              "Set whether valid typed external email bypasses sender screening.",
+              [
+                `${CLI_NAME} inbox schema acceptance account <screen-unknown-senders|accept-valid-typed-email> [--profile <name>] [--json]`,
+                `${CLI_NAME} inbox schema acceptance identity <identity-name-or-uuid> <screen-unknown-senders|accept-valid-typed-email> [--profile <name>] [--json]`,
+              ],
+              {
+                options: [PROFILE_OPTION, JSON_OPTION],
+                notes: [
+                  "Setting a schema defaults the inbox to accept valid typed email; removing a schema resets the inbox to screen unknown senders.",
+                ],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox schema <subcommand>`],
+          },
+        ),
+        command(
+          "seen",
+          "Mark one thread as seen.",
+          `${CLI_NAME} inbox seen <thread-id> [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "archive",
+          "Archive one thread.",
+          `${CLI_NAME} inbox archive <thread-id> [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "resolve",
+          "Resolve one thread.",
+          `${CLI_NAME} inbox resolve <thread-id> [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        command(
+          "block",
+          "Block one thread.",
+          `${CLI_NAME} inbox block <thread-id> [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+          },
+        ),
+        group(
+          "screening",
+          "Inspect screened inbox intakes and apply decisions.",
+          [
+            command(
+              "list",
+              "List screened external email waiting for a decision.",
+              `${CLI_NAME} inbox screening list [--limit <n>] [--cursor <cursor>] [--identity-key <token>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  LIMIT_OPTION,
+                  CURSOR_OPTION,
+                  IDENTITY_KEY_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "processing",
+              "List released external email in the processing queue.",
+              `${CLI_NAME} inbox screening processing [--limit <n>] [--cursor <cursor>] [--identity-key <token>] [--profile <name>] [--json]`,
+              {
+                options: [
+                  LIMIT_OPTION,
+                  CURSOR_OPTION,
+                  IDENTITY_KEY_OPTION,
+                  PROFILE_OPTION,
+                  JSON_OPTION,
+                ],
+              },
+            ),
+            command(
+              "approve",
+              "Approve this sender and release one screened email.",
+              `${CLI_NAME} inbox screening approve <intake-id> [--identity-key <token>] [--profile <name>] [--json]`,
+              {
+                options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+            command(
+              "approve-once",
+              "Release one screened email without trusting future mail.",
+              `${CLI_NAME} inbox screening approve-once <intake-id> [--identity-key <token>] [--profile <name>] [--json]`,
+              {
+                options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+            command(
+              "ignore",
+              "Ignore this sender and suppress future mail.",
+              `${CLI_NAME} inbox screening ignore <intake-id> [--identity-key <token>] [--profile <name>] [--json]`,
+              {
+                options: [IDENTITY_KEY_OPTION, PROFILE_OPTION, JSON_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} inbox screening <subcommand>`],
+            notes: [
+              "Use `inbox list --status pending` for pending first-contact threads.",
+              "Reads allow owner-read tokens or identity keys.",
+              "Decision actions require a master token unless you provide `--identity-key`.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} inbox <subcommand>`],
+        notes: [
+          "Owner-authenticated inbox reads use the owner-read token path.",
+          "Owner-authenticated inbox writes require a master token unless you provide `--identity-key`.",
+        ],
+      },
+    ),
+    group(
+      "api",
+      "Inspect the raw API surface and make low-level requests.",
+      [
+        group(
+          "openapi",
+          "Fetch the backend OpenAPI document.",
+          [
+            command(
+              "fetch",
+              "Download the backend OpenAPI document as JSON.",
+              `${CLI_NAME} api openapi fetch [--profile <name>]`,
+              {
+                options: [PROFILE_OPTION],
+              },
+            ),
+          ],
+          {
+            usage: [`${CLI_NAME} api openapi <subcommand>`],
+          },
+        ),
+        command(
+          "request",
+          "Send a raw API request to an `/api/v1/` path.",
+          `${CLI_NAME} api request <method> <path> [--body <json> | --body-file <path> | --stdin] [--identity-key <token>] [--profile <name>] [--json]`,
+          {
+            options: [
+              ...BODY_OPTIONS,
+              IDENTITY_KEY_OPTION,
+              PROFILE_OPTION,
+              JSON_OPTION,
+            ],
+            notes: [
+              "`api request` only accepts paths that start with `/api/v1/`.",
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} api <subcommand>`],
+      },
+    ),
+    command(
+      "doctor",
+      "Check connectivity, configured tokens, and publish readiness.",
+      `${CLI_NAME} doctor [--identity <name-or-uuid>] [--profile <name>] [--json]`,
+      {
+        options: [
+          option(
+            "--identity <name-or-uuid>",
+            "Also resolve a target identity and report publish readiness.",
+          ),
+          PROFILE_OPTION,
+          JSON_OPTION,
+        ],
+        notes: [
+          "Doctor validates the OpenAPI endpoint, token availability, and optional identity diagnostics.",
+        ],
+      },
+    ),
+    group(
+      "skill",
+      "Install the bundled ClankID Codex and Claude skill files.",
+      [
+        command(
+          "install",
+          "Install the bundled skill into one or more supported hosts.",
+          `${CLI_NAME} skill install [--host codex|claude|both] [--copy] [--force] [--json]`,
+          {
+            options: [
+              option(
+                "--host codex|claude|both",
+                "Choose which host receives the install.",
+              ),
+              option("--copy", "Copy files instead of creating symlinks."),
+              option(
+                "--force",
+                "Replace an existing installed skill target.",
+              ),
+              JSON_OPTION,
+            ],
+          },
+        ),
+      ],
+      {
+        usage: [`${CLI_NAME} skill <subcommand>`],
+      },
+    ),
+    command(
+      "version",
+      "Print the installed CLI version.",
+      `${CLI_NAME} version`,
+    ),
+  ],
+  {
+    description: "Work with ClankID from the command line.",
+    usage: [`${CLI_NAME} <command>`, `${CLI_NAME} help <command-path>`],
+    examples: [
+      `${CLI_NAME}`,
+      `${CLI_NAME} auth`,
+      `${CLI_NAME} auth key issue --help`,
+      `${CLI_NAME} help identity key`,
+    ],
+    notes: [
+      "Use `--body-file` or `--stdin` for multiline content.",
+      "`--profile` wins over `CLANKID_PROFILE`, which wins over `activeProfile` in config.",
+      "`--base-url` wins over `CLANKID_BASE_URL`, which wins over the stored profile base URL.",
+      "`--profile`, `CLANKID_PROFILE`, and `CLANKID_BASE_URL` do not change config by themselves.",
+    ],
+    options: GLOBAL_HELP_OPTIONS,
+  },
+);
+
+export function renderHelp(
+  path: string[],
+  options: HelpRenderOptions = {},
+): string | undefined {
+  const resolved = resolveHelpNode(path);
+
+  if (!resolved) {
+    return undefined;
+  }
+
+  return resolved.node.kind === "group"
+    ? renderGroupHelp(resolved.node, resolved.path, options)
+    : renderCommandHelp(resolved.node, resolved.path, options);
+}
+
+export function resolvesToHelpGroup(path: string[]): boolean {
+  const resolved = resolveHelpNode(path);
+  return resolved?.node.kind === "group";
+}
+
+function resolveHelpNode(
+  path: string[],
+): { node: HelpNode; path: string[] } | undefined {
+  let node: HelpNode = HELP_ROOT;
+  const resolvedPath: string[] = [];
+
+  for (const segment of path) {
+    if (node.kind === "command") {
+      break;
+    }
+
+    const child: HelpNode | undefined = node.children.find((candidate) =>
+      matchesSegment(candidate, segment),
+    );
+
+    if (!child) {
+      return undefined;
+    }
+
+    node = child;
+    resolvedPath.push(child.name);
+  }
+
+  return { node, path: resolvedPath };
+}
+
+function matchesSegment(node: HelpNode, segment: string): boolean {
+  return node.name === segment || node.aliases?.includes(segment) === true;
+}
+
+function renderGroupHelp(
+  node: HelpGroup,
+  path: string[],
+  options: HelpRenderOptions,
+): string {
+  const title = path.length === 0 ? `${CLI_NAME} ${CLI_VERSION}` : `${CLI_NAME} ${path.join(" ")}`;
+  const sections: string[] = [title];
+
+  if (node.description) {
+    sections.push(node.description);
+  } else {
+    sections.push(node.summary);
+  }
+
+  if (node.usage && node.usage.length > 0) {
+    sections.push(renderUsageSection(node.usage, options));
+  }
+
+  if (node.aliases && node.aliases.length > 0) {
+    sections.push(renderLineListSection("Aliases", node.aliases, false, options));
+  }
+
+  const childHeading = path.length === 0 ? "Commands" : "Subcommands";
+  sections.push(renderEntrySection(childHeading, node.children, options));
+
+  if (node.options && node.options.length > 0) {
+    sections.push(
+      renderOptionSection(
+        path.length === 0 ? "Global Flags" : "Options",
+        node.options,
+        options,
+      ),
+    );
+  }
+
+  if (node.examples && node.examples.length > 0) {
+    sections.push(renderLineListSection("Examples", node.examples, true, options));
+  }
+
+  if (node.notes && node.notes.length > 0) {
+    sections.push(renderLineListSection("Notes", node.notes, false, options));
+  }
+
+  if (path.length === 0) {
+    sections.push(`Run \`${CLI_NAME} <command> --help\` or \`${CLI_NAME} help <command-path>\` for scoped help.`);
+  } else {
+    sections.push(`Run \`${CLI_NAME} ${path.join(" ")} <subcommand> --help\` for command details.`);
+  }
+
+  return sections.join("\n\n");
+}
+
+function renderCommandHelp(
+  node: HelpCommand,
+  path: string[],
+  options: HelpRenderOptions,
+): string {
+  const title = `${CLI_NAME} ${path.join(" ")}`;
+  const sections: string[] = [title, node.description ?? node.summary];
+
+  if (node.aliases && node.aliases.length > 0) {
+    sections.push(renderLineListSection("Aliases", node.aliases, false, options));
+  }
+
+  if (node.usage && node.usage.length > 0) {
+    sections.push(renderUsageSection(node.usage, options));
+  }
+
+  if (node.options && node.options.length > 0) {
+    sections.push(renderOptionSection("Options", node.options, options));
+  }
+
+  if (node.examples && node.examples.length > 0) {
+    sections.push(renderLineListSection("Examples", node.examples, true, options));
+  }
+
+  if (node.notes && node.notes.length > 0) {
+    sections.push(renderLineListSection("Notes", node.notes, false, options));
+  }
+
+  return sections.join("\n\n");
+}
+
+function renderUsageSection(
+  usage: string[],
+  options: HelpRenderOptions,
+): string {
+  return [formatSectionTitle("USAGE", options), ...usage.map((line) => `  ${line}`)].join(
+    "\n",
+  );
+}
+
+function renderEntrySection(
+  title: string,
+  entries: HelpNode[],
+  options: HelpRenderOptions,
+): string {
+  const labels = entries.map((entry) => `${formatEntryLabel(entry)}:`);
+  const width = labels.reduce((current, label) => Math.max(current, label.length), 0);
+
+  return [
+    formatSectionTitle(title, options),
+    ...entries.map((entry, index) => {
+      const label = labels[index]!.padEnd(width, " ");
+      return `  ${label}  ${entry.summary}`;
+    }),
+  ].join("\n");
+}
+
+function renderOptionSection(
+  title: string,
+  options: HelpOption[],
+  renderOptions: HelpRenderOptions,
+): string {
+  const width = options.reduce((current, entry) => Math.max(current, entry.flag.length), 0);
+
+  return [
+    formatSectionTitle(title, renderOptions),
+    ...options.map((entry) => `  ${entry.flag.padEnd(width, " ")}  ${entry.description}`),
+  ].join("\n");
+}
+
+function renderLineListSection(
+  title: string,
+  lines: string[],
+  code = false,
+  options: HelpRenderOptions,
+): string {
+  return [
+    formatSectionTitle(title, options),
+    ...lines.map((line) => `  ${code ? line : line}`),
+  ].join("\n");
+}
+
+function formatEntryLabel(entry: HelpNode): string {
+  return entry.aliases && entry.aliases.length > 0
+    ? `${entry.name}, ${entry.aliases.join(", ")}`
+    : entry.name;
+}
+
+function formatSectionTitle(
+  title: string,
+  options: HelpRenderOptions = {},
+): string {
+  const heading = title.toUpperCase();
+  return options.boldSectionTitles ? `${ANSI_BOLD}${heading}${ANSI_RESET}` : heading;
+}