docs: automate OpenShell CLI reference markdown generation into two places

[miyoungc]

Summary

Preview: https://cuddly-tribble-p3evl8k.pages.github.io/pr-preview/pr-270/reference/cli-generated.html

Automates CLI reference markdown generation from source /// doc comments, eliminating manual documentation maintenance and ensuring CLI docs stay in sync with code.

What this adds

• cli_reference.rs — A new module that introspects the clap Command tree at runtime and generates a complete markdown reference (command tree, flag tables with defaults, env vars, grouped sections).
• openshell docs cli-reference — A hidden subcommand that runs the generator and prints markdown to stdout.
• Mise tasks — docs:cli-reference (regenerate) and docs:cli-reference:check (staleness check wired into pre-commit).
• Generated output deployed to two locations:
  • .agents/skills/openshell-cli/cli-reference-generated.md (agent skills)
  • docs/reference/cli-generated.md (user-facing docs site)
• Agent skill (.agents/skills/generate-cli-reference/SKILL.md) documenting the regeneration workflow.
• CONTRIBUTING.md updated with the new task and a "Generated Documentation" section.

Why

The CLI reference was previously maintained by hand across multiple locations, leading to staleness and inconsistency. Now the /// doc comments on commands and flags in main.rs are the single source of truth. The pre-commit hook catches drift automatically.

Notable details

• Clap's derive macro strips trailing periods from single-line doc comments. The generator restores them via ensure_period() so the output has consistent punctuation.
• The hidden subcommand approach avoids a separate binary while keeping generator code isolated in its own module.

Changed files

File	Change
crates/navigator-cli/src/cli_reference.rs	New module: markdown generator
crates/navigator-cli/src/lib.rs	Expose cli_reference module
crates/navigator-cli/src/main.rs	Add hidden docs cli-reference subcommand; fix one missing trailing period
tasks/docs.toml	Add docs:cli-reference and docs:cli-reference:check tasks
tasks/ci.toml	Wire staleness check into pre-commit
CONTRIBUTING.md	Document docs:cli-reference task and generated docs workflow
docs/index.md	Add reference/cli-generated to docs toctree
.agents/skills/generate-cli-reference/SKILL.md	New agent skill for the regeneration workflow
.agents/skills/openshell-cli/cli-reference-generated.md	Generated output (agent skills)
docs/reference/cli-generated.md	Generated output (user-facing docs)

Test plan

• cargo test -p navigator-cli cli_reference — unit tests pass
• mise run docs:cli-reference — regenerates successfully
• mise run docs:cli-reference:check — passes when docs are current
• mise run docs:cli-reference:check — fails with clear error when docs are stale
• mise run pre-commit — full CI suite including staleness check

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA.github.io/OpenShell/pr-preview/pr-270/
Built to branch gh-pages at 2026-03-13 02:30 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[drew]

Remove one, prefer CLI Reference

[drew]

Closing for now- we won't provide a CLI reference.