feat(spec): add a top-level repository field

[jdx]

A usage spec has no way to say where the CLI's source lives.

The nearest thing today is source_code_link_template, but that's a per-command deep link with a {{path}} placeholder, built for rendering "view source" links in generated markdown. Getting a repository URL out of it means pattern-matching https://github.com/(owner)/(repo)/blob/… — one forge, one URL layout — and it's absent from most specs anyway, since clap emits nothing for it and it only exists where someone hand-wrote it into an extra spec.

repository "https://github.com/jdx/mise"

A plain URL, the same value a Cargo.toml, package.json or pyproject.toml carries. Parsed, merged and re-emitted like the other optional top-level strings, and passed through to documentation templates as repository.

Why

Anything that reads a spec away from its checkout has a spec and no way back to the project it describes: usage.sh, a registry, an agent handed a .usage.kdl file. The repo is the one piece of provenance that isn't derivable from the spec's own contents.

It's deliberately separate from source_code_link_template, and neither implies the other. Set both if you want both.

Notes

• clap_usage can't generate this — clap has no equivalent concept. It goes in an extra spec merged over the generated one, exactly where source_code_link_template already lives. usage's own cli/assets/usage-extra.usage.kdl does that here, so the regenerated cli/usage.usage.kdl and docs/cli/reference/commands.json carry it.
• Spec is #[non_exhaustive], so the field is additive. cargo semver-checks reports no break; the docs model it also touches is pub(crate).
• Tests cover parse → re-emit round-tripping and merge-over-generated, which are the two ways a new top-level field silently goes missing.

This PR was generated by an AI coding assistant.

---

Note

Low Risk
Additive optional metadata on a non-exhaustive Spec; no behavior changes unless callers set the field.

Overview
Adds an optional top-level repository string to usage specs so readers (docs generators, JSON export, registries) get a plain project URL without inferring it from source_code_link_template.

The field is wired through Spec like other optional metadata: KDL parse/emit, merge for extra specs layered on clap-generated output, serde serialization, and the docs Spec model for template context. Spec reference docs explain how it differs from per-command source links and that clap cannot emit it.

The usage CLI sets repository in usage-extra.usage.kdl, which flows into regenerated usage.usage.kdl and commands.json. Tests cover parse → re-emit and merge-over-generated behavior.

^{Reviewed by Cursor Bugbot for commit b12fca6. 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: 33 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

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: d9476d30-1e92-46de-84d6-47c6bd737ee4

📥 Commits

Reviewing files that changed from the base of the PR and between 1c8f2c3 and b12fca6.

📒 Files selected for processing (6)

• cli/assets/usage-extra.usage.kdl
• cli/usage.usage.kdl
• docs/cli/reference/commands.json
• docs/spec/reference/index.md
• lib/src/docs/models.rs
• lib/src/spec/mod.rs

---

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

Adds optional repository provenance throughout the usage specification pipeline.

• Parses, merges, serializes, and round-trips the top-level repository KDL field.
• Exposes the field to documentation templates and generated JSON.
• Documents the field and adds it to usage's dogfooded specification.
• Adds tests for round-tripping and merging repository metadata.

Confidence Score: 5/5

The PR appears safe to merge, with the new optional field propagated consistently through its intended parsing, composition, serialization, and documentation paths.

The repository value is preserved by parsing, merge-over-generated composition, KDL re-emission, documentation-model conversion, and raw JSON serialization, with targeted tests covering the principal silent-drop paths.

Important Files Changed

Filename	Overview
lib/src/spec/mod.rs	Adds the optional field consistently across parsing, merging, KDL serialization, and focused tests.
lib/src/docs/models.rs	Correctly mirrors repository metadata into the shared documentation-template model.
cli/assets/usage-extra.usage.kdl	Declares the repository in the hand-maintained extension used when regenerating usage's own spec.
cli/usage.usage.kdl	Generated specification correctly carries the newly declared repository URL.
docs/cli/reference/commands.json	Generated JSON correctly exposes the repository field.
docs/spec/reference/index.md	Documents the field's syntax, purpose, template availability, and distinction from source-code deep-link templates.

_{Reviews (1): Last reviewed commit: "feat(spec): add a top-level `repository`..." | Re-trigger Greptile}