docs(cmd): document the stock :Forge completion contract and non-goals #343

New issue

Closed

opened 2026-04-20 00:19:10 +00:00 by barrettruth · 0 comments

barrettruth commented

2026-04-20 00:19:10 +00:00

Prerequisites

I have searched existing issues

Problem

The stock :Forge cmdline completion contract is subtle enough that code alone is not a sufficient source of truth. Without documentation, users and future contributors are likely to assume one of two incorrect extremes:

the cmdline should be as rich as the picker
the cmdline should be entirely static

The actual contract is narrower and more intentional than either of those.

Proposed solution

Document the stock :Forge completion contract and its non-goals.

Documentation scope

explain that cmdline completion inherits picker semantics where useful, but not picker-style display richness
explain that no fetch happens on keystroke; explicit completion is the only time a fetch may occur
explain that numeric entity completion is intentionally suppressed in the stock cmdline
explain that release tags remain dynamically completable
explain the local/grounded modifier-value behavior for:
- repo=
- template=
- head=
- base=
- branch=
- commit=
- target=
- adapter=
- method=
explain that no new setting exists for this behavior

Concrete examples to include

:Forge review <Tab> -> open, repo=, adapter=
:Forge issue browse <Tab> -> repo=
:Forge ci browse <Tab> -> repo=
:Forge release browse <Tab> -> repo= plus release tags
:Forge release delete <Tab> -> release tags
head= / base= revision-address examples using @...

Places likely needing updates

vimdoc command-completion section
any user-facing command docs that currently imply broader picker parity than the cmdline actually has
any examples that could be misread as promising numeric entity completion

Acceptance criteria:

the docs describe both the behavior and the intentional omissions
examples match the actual slot matrix
no docs imply fetch-on-keystroke or picker-style cmdline richness
no docs imply a remote= modifier exists

Alternatives considered

Leave the contract implicit in tests and code comments
Document only the happy path and omit the intentional non-goals

## Prerequisites - [x] I have searched existing issues ## Problem The stock `:Forge` cmdline completion contract is subtle enough that code alone is not a sufficient source of truth. Without documentation, users and future contributors are likely to assume one of two incorrect extremes: - the cmdline should be as rich as the picker - the cmdline should be entirely static The actual contract is narrower and more intentional than either of those. ## Proposed solution Document the stock `:Forge` completion contract and its non-goals. ### Documentation scope - explain that cmdline completion inherits picker semantics where useful, but not picker-style display richness - explain that no fetch happens on keystroke; explicit completion is the only time a fetch may occur - explain that numeric entity completion is intentionally suppressed in the stock cmdline - explain that release tags remain dynamically completable - explain the local/grounded modifier-value behavior for: - `repo=` - `template=` - `head=` - `base=` - `branch=` - `commit=` - `target=` - `adapter=` - `method=` - explain that no new setting exists for this behavior ### Concrete examples to include - `:Forge review <Tab>` -> `open`, `repo=`, `adapter=` - `:Forge issue browse <Tab>` -> `repo=` - `:Forge ci browse <Tab>` -> `repo=` - `:Forge release browse <Tab>` -> `repo=` plus release tags - `:Forge release delete <Tab>` -> release tags - `head=` / `base=` revision-address examples using `@...` ### Places likely needing updates - vimdoc command-completion section - any user-facing command docs that currently imply broader picker parity than the cmdline actually has - any examples that could be misread as promising numeric entity completion Acceptance criteria: - the docs describe both the behavior and the intentional omissions - examples match the actual slot matrix - no docs imply fetch-on-keystroke or picker-style cmdline richness - no docs imply a `remote=` modifier exists ## Alternatives considered - Leave the contract implicit in tests and code comments - Document only the happy path and omit the intentional non-goals