Skip to content

docs(cli): remove duplicate terminal hub section - #3045

Open
chm-labs wants to merge 2 commits into
amd:mainfrom
chm-labs:docs/remove-duplicate-terminal-hub
Open

docs(cli): remove duplicate terminal hub section#3045
chm-labs wants to merge 2 commits into
amd:mainfrom
chm-labs:docs/remove-duplicate-terminal-hub

Conversation

@chm-labs

Copy link
Copy Markdown

Summary

Keep single authoritative terminal-hub and hub-command sections in the CLI reference, retaining the newer exit-code, theme, and control-API guidance.

Why

The page documented gaia tui and gaia hub twice, and the terminal copies had already drifted. Readers could receive conflicting answers while duplicate headings made inbound anchors ambiguous.

Linked issue

Closes #2608

Changes

  • Removed the stale duplicate terminal-hub section.
  • Removed the byte-identical second hub-command section from the same copied region.
  • Updated the retained one-shot prose to document exit code 3 consistently.
  • Preserved the current terminal section and the divider before the cache command.

Test plan

  • mintlify validate
  • python3 util/check_doc_versions.py
  • Confirmed exactly one terminal-hub heading and one hub-command heading remain.
  • Confirmed the retained commands, flags, and one-shot exit codes match tui/internal/cli.

Evidence

  • Agent exposed in the Agent UI — N/A; documentation-only change.
  • MCP tools / servers — N/A; documentation-only change.
  • CLI — N/A; CLI behavior is unchanged; docs were checked against current Cobra registrations.
  • HTTP API / REST — N/A; documentation-only change.

Checklist

  • I have linked a GitHub issue above (Closes #N / Fixes #N / Refs #N).
  • I have described why this change is being made, not just what changed.
  • I have run the applicable documentation validation locally (mintlify validate, python3 util/check_doc_versions.py).
  • I have marked runtime evidence surfaces N/A because this is a documentation-only change.
  • I have updated documentation if user-visible behavior changed (N/A; behavior is unchanged).

Signed-off-by: chm-labs <255901968+chm-labs@users.noreply.github.com>
Signed-off-by: chm-labs <255901968+chm-labs@users.noreply.github.com>
@github-actions github-actions Bot added the documentation Documentation changes label Aug 22, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Verdict: Approve

The CLI reference had two copies of the terminal-hub and hub-command documentation. This
PR deletes the stale one and brings the surviving copy's exit-code sentence in line with
what gaia tui run --query actually returns.

I checked the deleted block line-by-line against the copy that stays: nothing unique was
lost. The stale copy was strictly older — it was missing the exit-code-3 detail, the
readiness-hold section, and the terminal-theme section that the surviving copy already
carries. The exit-code claim now in the docs also matches what the binary really does.

No blocking issues, no security concerns.

Real-world evidence

N/A — docs-only. No evidence-bundle.md was produced for this run, and none is expected:
the diff touches a single .mdx file with no runnable surface behind it. I verified the
one substantive factual claim against the source instead of at runtime.

🔍 Technical details

Verification performed

  • Heading scan of docs/reference/cli.mdx confirms exactly one copy of each section
    survives: ### Hub Command (2829), ### Terminal hub (gaia tui) (2888),
    #### --trust (2929), #### run --query is a real one-shot (2959),
    #### Hub keys (2997). No third copy anywhere.
  • Diffed the removed block against the retained one. The retained copy is a strict
    superset: cli.mdx:2907 and cli.mdx:2917 already document exit 3, and
    #### Waiting on a consequential readiness problem / #### Theme (light vs dark terminals) (3016, 3027) exist only in the retained copy. Nothing dropped.
  • Exit code 3 is real. ExitApprovalRequired is set at
    tui/internal/ui/oneshot.go:464 when withheld actions exist and nothing else failed,
    and tui/internal/cli/agents.go:291 documents the same contract in the cobra Long
    help. Covered by tui/internal/ui/oneshot_approval_test.go, including the precedence
    case (a real failure outranks a gate → exit 1).
  • No broken anchors. The three inbound links to #terminal-hub-gaia-tui
    (docs/guides/terminal-hub.mdx:38,86,298) and the one to #hub-command
    (cli.mdx:636) all resolve to the retained headings. Deduplicating actually removes an
    ambiguity here — Mintlify would have suffixed the second copy's slug, so these links
    were already pointing at the surviving copy.
  • No contradicting exit-code claim elsewhere. Swept docs/**/*.mdx for the 0/1
    contract; docs/guides/terminal-hub.mdx:299 only defers to the CLI reference, so this
    is the single place the claim lives. Per CLAUDE.md's "update EVERY doc that describes
    it" rule, this PR is complete.
  • Structure around the deletion is intact: --- separator at 3124 then ### Cache Command at 3126, matching the pattern elsewhere in the file.

Strengths

  • Deleting the duplicate rather than syncing it is the right call — a second copy is a
    second thing to drift, and this one had already drifted (it predated exit code 3).
  • The prose fix at cli.mdx:2962 and the table row at cli.mdx:2917 now agree with each
    other and with the cobra help text, so a reader gets the same contract from --help and
    from the docs.
  • Commits are split cleanly by intent (docs(cli): remove duplicate terminal hub section,
    docs(cli): clean up adjacent hub reference) rather than squashed into one blob.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Documentation changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs(cli): remove the duplicated terminal-hub section in the CLI reference

2 participants