docs(spec): document when a root mount runs, and overrides_default

[jdx]

Cleaning up after myself. The mount documentation on main describes only the first commit of #806 and missed everything the later ones changed:

• It claims flags never trigger discovery, which is untrue of completions and of rendering help — both resolve the mount up front, because both need the whole command list.
• overrides_default is undocumented entirely, despite shipping.
• Nothing says the default-subcommand gate applies to completions as well as parses, which is the part with a user-visible consequence.

How it happened, since it is worth knowing

Both docs edits in that PR were string replacements against text prettier had already reformatted — rewrapped lines, and *own* turned into _own_. The replacements matched nothing and silently did nothing, and I asserted in a PR comment that the page had been corrected. It had not.

The lesson is mechanical: a .replace() that no-ops leaves no trace, so an edit made that way needs its diff checked rather than its exit code. This one is verified — git diff --stat shows 25 insertions, and the rendered diff is in the commit.

What the page says now

A table for when the root's mount runs, since "lazily" was never the whole truth:

asking	when it runs
a completion, or rendering help	up front — both need the whole command list
a parse	only when a word matches nothing already declared
a parse, for a flag	never

Plus overrides_default, and why it governs completions too: a completion offering a command that running would hand to the default subcommand instead is worse than not offering it.

AI-assisted — Tool: Claude Code; model: anthropic/claude-fable-5; version: unavailable.

---

Note

Low Risk
Documentation-only change to the mount reference; no runtime or security-sensitive code is modified.

Overview
Corrects the root mount docs that previously claimed discovery never runs for flags and omitted later behavior.

Adds a table for when a root mount runs: up front for completions/help, lazily for unmatched parse words, and never for flags during parse. Also documents overrides_default, including that default_subcommand outranks discovery for both parses and completions unless a mount opts in.

^{Reviewed by Cursor Bugbot for commit f942f04. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

Warning

Review limit reached

@jdx, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 1 minute

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Central YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro Plus

Run ID: 6b18c8a3-94aa-4fb2-a230-20432112a698

📥 Commits

Reviewing files that changed from the base of the PR and between cbdf826 and f942f04.

📒 Files selected for processing (1)

• docs/spec/reference/cmd.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

Updates the command specification reference to accurately document root mount resolution and the overrides_default option.

• Clarifies when mounts run for completion, help rendering, parsing, and flags.
• Documents how default_subcommand interacts with discovery.
• Adds an example enabling overrides_default.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
docs/spec/reference/cmd.md	Documentation-only update clarifying shipped root-mount behavior and the overrides_default setting; no eligible follow-up issue was identified.

_{Reviews (2): Last reviewed commit: "docs(spec): document when a root mount r..." | Re-trigger Greptile}

[github-actions]

Instruction counts

benchmark	trend	instructions	Δ	wall (min)	Δ
markdown	▁▁▁▁▁▁▁▁▁▁▁▁██████	148,146,307 → 148,169,738	+0.02%	13.82 → 14.53ms	+5.14%
startup	▃▃▄▁▁▁▁▁▁▁▁▂██████	1,204,030 → 1,204,110	+0.01%	0.99 → 0.94ms	-4.83%

No instruction-count regression above 1%.

_{Only instruction counts gate. Wall clock is shown for context — on identical hardware it moves 4-20% run to run.}

_{Measured by tak — instruction-counted CLI benchmarks, stored in this repository's git notes.}

_{f942f04ef388 vs cbdf8265b174 · measured on the runner, not pushed to the history.}