Skip to content

Install/prerequisite docs don't resolve to a single successful path #345

Description

@justaugustus

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

  1. Start from README.md and try to reach a single authoritative statement of the runtime prerequisites needed to run a live audit.
  2. 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).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions