CLI flag help says "Promise ..." where it means "Output ...", and it has shipped into the docs

Feature: #834 — Help and reference: wrapped help, generated CLI docs, the specification

Four CLI flag descriptions read "Promise ..." where they mean "Output ...". The wording is meaningless to a
user, and because promise is a binding kind in this codebase it actively misleads: a reader may think
--output has something to do with promise bindings.

The shape is consistent with a global Output -> Promise replace that caught flag help text — plausibly
from the rename of output-bindings to promise-bindings.

Sites

File	Flag	Current	Intended
`cmd/lore/lore/commands.go:360`	`--output, -o`	Promise bundle path	Output bundle path
`cmd/lore/lore/commands.go:569`	`--format`	Promise format (table, manifest, json)	Output format
`cmd/lore/lore/commands.go:621`	`--output`	Promise directory path	Output directory path
`cmd/writ/writ/migrate_cmd.go:63`	`--format`	Promise format: json (default), yaml, text	Output format

It has shipped into the docs

The CLI reference is generated from these strings, so the corruption is published:

docs/cli/lore/bundle.md:26
docs/cli/lore/onboard.md:41
docs/cli/lore/list.md:25

Fixing the Go strings and regenerating should carry through; the generated files must not be hand-edited.

Worth checking while fixing

Whether the same replace damaged other user-facing strings that a "Promise <noun>" grep would not catch —
for example a sentence where "output" was a verb.

Acceptance

All four flag descriptions say what the flag does
The generated CLI docs no longer say "Promise bundle/directory/format"
A grep for "Promise across cmd/ returns nothing user-facing

Correction: the corruption did not ship into the docs

The title and body of this issue say the wrong strings "shipped into the docs" and cite three pages under
docs/cli/lore/. That is wrong, and I wrote it. .gitignore:5 ignores /docs/cli/ and git ls-files docs/cli returns nothing: the reference is build output from make docs, not repository content. Nothing
was published.

The defect was real but narrower than stated -- four help strings in the Go source:

cmd/lore/lore/commands.go -- --output, --format, --output descriptions
cmd/writ/writ/migrate_cmd.go -- --format description

And a fourth site the original report missed, because it is prose rather than a flag description and a grep
aimed at flag strings never saw it:

cmd/lore/lore/commands.go:828 -- lore inspect's long description, "Promise is JSON by default for
scripting. Use --format for alternatives."

All four are fixed. make docs regenerates cleanly, which verifies the fix rather than delivering it.

One consequence worth recording: because docs/cli is not committed, nothing compares it against the source
on a schedule. make docs after a flag change is the only thing that catches drift, so it belongs in the
flag-changing work rather than as a separate chore.
docs/architecture/10-command-line-interface.md §12 now says so, and invariant 6 was reworded -- it had
described a "codegen determinism gate" that does not cover this directory.

Retracting the correction above -- the original report was right

My previous comment said the corruption "did not ship into the docs" because /docs/cli/ is gitignored. That
reasoning was wrong: I went from not tracked in this repository to never published, without looking for a
publishing path. There is one.

.github/workflows/docs-publish.yaml:

on: push: branches: [develop, main, 'release/*']
  - run: make docs
  - checkout: NobleFactor/devlore.noblefactor.com   → path: site
  - run: cp -r docs/cli/ site/src/content/cli/
          cp -r docs/guides/ site/src/content/guides/
  - Create and merge PR on site repo

Every push to develop regenerates the reference and auto-merges it into the site repository. So
"Promise bundle path" was live on devlore.noblefactor.com, exactly as this issue originally said. The title
is restored.

Being gitignored made it worse, not better: a help string gets no diff in this repository and no approval
in the site repository. It is published prose that nobody reviews.

devlore-registry is unrelated to this -- it is the package registry
(cmd/internal/config/registry.go:8), not a docs target.

docs/architecture/10-command-line-interface.md §12 now records the pipeline and that consequence, and
invariant 6 was reworded again: it now says help strings must read as published prose and that make docs
plus reading the output belongs in the flag-changing work.

The substantive facts from the previous comment stand -- four sites in the Go source, including
lore inspect's long description at cmd/lore/lore/commands.go:828, which a grep aimed at flag descriptions
missed because it is prose. All four are fixed.

feat(writ): the common set, and --json retires (#739, #740)

docs(cli): bring the reference and the plans current (#739, #740)

One output convention for every app: result to stdout, documents to t…

Navigation Menu

Repository navigation

CLI flag help says "Promise ..." where it means "Output ...", and it has shipped into the docs #739

Sites

It has shipped into the docs

Worth checking while fixing

Acceptance

Correction: the corruption did not ship into the docs

Retracting the correction above -- the original report was right

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

CLI flag help says "Promise ..." where it means "Output ...", and it has shipped into the docs #739

Description

Sites

It has shipped into the docs

Worth checking while fixing

Acceptance

Activity

David-Noble-at-work commented on Aug 30, 2026

Correction: the corruption did not ship into the docs

David-Noble-at-work commented on Aug 30, 2026

Retracting the correction above -- the original report was right

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions