Skip to content

docs: first-party-cutover.md isn't linked from any other doc #530

Description

@codeforester

Location and audience

docs/first-party-cutover.md, reviewed against origin/main (8de2056,
"security: constrain standalone application payloads (#520)") during a
pre-release documentation sweep (2026-09-21). Audience: a maintainer or new
contributor trying to understand the v1.4.0-to-v2 first-party cutover history,
or anyone auditing what first-party-cutover.yaml / scripts/first-party-cutover
are for.

The 44-line doc (Issue #240's promotion-handoff record) is not linked from any
other tracked markdown file in the repo — not README.md's "Documentation
map" section, not docs/README.md, not CHANGELOG.md. The only repo hits for
"first-party-cutover" are the sibling first-party-cutover.yaml and
scripts/first-party-cutover, which are different files with a similar name.
It's discoverable only by browsing docs/ directly.

Suggested correction

Either:

  • add one line linking docs/first-party-cutover.md from README.md's
    "Documentation map" section (it fits near the versioning-policy /
    release-process entries as historical migration record), or
  • if it's intentionally archival now that the v2 cutover (Migrate first-party consumers and Homebrew to the Base Bash 2.0 contract #240) is complete,
    say so explicitly at the top of the doc and/or move it under a clearly
    historical section, so its unlinked status reads as a decision rather than
    an oversight.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationDocumentation improvements

Type

No type

Projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions