Description
The git+gh runtime prerequisite is documented, but restated across many pages with inconsistent wording and no canonical source, across disconnected reader tracks. There is no single "prerequisites" page that the install channels, usage guide, and getting-started docs all reference, and some cross-references are stale.
Steps to Reproduce
- Start from
README.md and try to reach a single authoritative statement of the runtime prerequisites needed to run a live audit.
- Compare the prerequisite wording across the install channel docs and the getting-started docs.
Expected Behavior
One canonical runtime-prerequisites location that other pages link to; consistent wording; working cross-links between the install-user track and the usage/getting-started tracks.
Actual Behavior
The git+gh prerequisite is duplicated with inconsistent phrasing:
docs/install/pypi.md:106 "some darnit controls invoke git and gh"
docs/install/binary.md:74 "some darnit controls invoke them at runtime"
docs/install/container.md:82 "many controls invoke it"
docs/install/homebrew.md:46 "most darnit audit controls shell out to them"
docs/getting-started/environment-setup.md:14 frames it as "for integration tests"
docs/USAGE_GUIDE.md:41 "GitHub CLI (gh) for GitHub API access"
Cross-linking is siloed: README.md:59 links to docs/install/README.md but not to USAGE_GUIDE.md; the docs/install/*.md docs never link to docs/getting-started/environment-setup.md (which tutorials treat as THE prerequisites page); there is no top-level docs/ hub. Additionally, the README and docs/install/* reference a stale org name for the repository (40+ occurrences) that no longer matches the canonical location (currently masked by a redirect).
Environment
- darnit version:
main @ 86f9cfa
- Docs as of the same commit
Additional Context
Non-prescriptive suggestion: a single canonical runtime-prerequisites section that the install channels, USAGE_GUIDE.md, and getting-started/ link to instead of restating; add the missing cross-links; and correct the stale org references. Relates to #282 (programmatic per-module tool declaration would be the structural complement).
Description
The
git+ghruntime prerequisite is documented, but restated across many pages with inconsistent wording and no canonical source, across disconnected reader tracks. There is no single "prerequisites" page that the install channels, usage guide, and getting-started docs all reference, and some cross-references are stale.Steps to Reproduce
README.mdand try to reach a single authoritative statement of the runtime prerequisites needed to run a live audit.Expected Behavior
One canonical runtime-prerequisites location that other pages link to; consistent wording; working cross-links between the install-user track and the usage/getting-started tracks.
Actual Behavior
The
git+ghprerequisite is duplicated with inconsistent phrasing:docs/install/pypi.md:106"some darnit controls invokegitandgh"docs/install/binary.md:74"some darnit controls invoke them at runtime"docs/install/container.md:82"many controls invoke it"docs/install/homebrew.md:46"most darnit audit controls shell out to them"docs/getting-started/environment-setup.md:14frames it as "for integration tests"docs/USAGE_GUIDE.md:41"GitHub CLI (gh) for GitHub API access"Cross-linking is siloed:
README.md:59links todocs/install/README.mdbut not toUSAGE_GUIDE.md; thedocs/install/*.mddocs never link todocs/getting-started/environment-setup.md(which tutorials treat as THE prerequisites page); there is no top-leveldocs/hub. Additionally, the README anddocs/install/*reference a stale org name for the repository (40+ occurrences) that no longer matches the canonical location (currently masked by a redirect).Environment
main@86f9cfaAdditional Context
Non-prescriptive suggestion: a single canonical runtime-prerequisites section that the install channels,
USAGE_GUIDE.md, andgetting-started/link to instead of restating; add the missing cross-links; and correct the stale org references. Relates to #282 (programmatic per-module tool declaration would be the structural complement).