tcld reference docs: gen-docs template produces subject-verb agreement errors (e.g. "command manage namespace capacity") #5113

Summary

Auto-generated tcld command reference pages under docs/cloud/tcld/ contain grammar errors like:

The tcld namespace capacity command manage namespace capacity.

(docs/cloud/tcld/namespace.mdx, line 936)

These pages are regenerated from a gen-docs tool intended to live in the temporalio/tcld repo (per the description of #4778, which last regenerated these pages), but the tool hasn't landed on tcld's main branch. It currently exists only in two open, competing PRs:

• Add gen-docs tool for reference documentation tcld#499 — "Add gen-docs tool for reference documentation"
• tcld docs gen tcld#398 — "tcld docs gen"

Editing the .mdx files directly won't fix this — they're marked {/* This is an auto-generated file. Do not edit directly. */} and get overwritten on the next regen.

Root cause

In PR #499's writeCommand(), the intro sentence for every command is built with:

b.WriteString(fmt.Sprintf("The `%s` command %s.\n\n", fullPath, lowercaseFirst(escapedUsage)))

This lowercases the command's cli.Command.Usage string and splices it after "The <command> command", assuming Usage is always phrased as a third-person-singular verb. That assumption breaks whenever the source Usage string in tcld is an imperative (written for --help output), producing subject-verb agreement errors, e.g.:

• app/namespace.go: Usage: "Manage namespace capacity" → "The tcld namespace capacity command manage namespace capacity." (should be "manages")
• Same pattern hits login.mdx ("command login as user"), logout.mdx ("command logout current user"), request.mdx ("command manage asynchronous requests")

It also produces an incidental capitalization artifact on service-account.mdx ("command service Account management operations"), because lowercaseFirst only touches the first character, leaving a mid-string capital from Usage: "Service Account management operations".

Suggested fix

Replace the template with a colon instead of "command", and drop lowercaseFirst entirely:

b.WriteString(fmt.Sprintf("`%s`: %s.\n\n", fullPath, escapedUsage))

This reads correctly whether Usage is a noun phrase or an imperative, since a colon has no subject-verb agreement to violate, and it preserves the fully-qualified command path in backticks — currently the only place that string appears near each subcommand's heading (headings only show the leaf name, e.g. #### update, not the full path).

Verified against Usage strings already in tcld:

• `tcld namespace capacity`: Manage namespace capacity.
• `tcld namespace`: Namespace operations.
• `tcld login`: Login as user.
• `tcld namespace capacity update`: Set the capacity of a given namespace.

Action needed

Apply this fix in whichever of tcld#499 / tcld#398 ends up landing, before the next update-cli-docs-style regeneration of docs/cloud/tcld/*.mdx in this repo. Filing here rather than on temporalio/tcld to track the docs-visible symptom, since regeneration is triggered from this repo's side.