docs(cli): the converge help row is named by its text, not by a line that moved twice today #2044

Merged
jaylouisw merged 1 commit from docs/1118-2217 into main 2026-11-18 22:38:01 +00:00
Owner

docs/CLI.md said engine/cli.js:6765 was the converge [<ms> | at <ms>] row of the help index. It is not.

Evidence (the code is the truth):

  • engine/cli.js:6765 is the body of _banner() — return 'PacketForge ' + dev.label + ' (' + dev.vendor + ' ' + dev.model + ')'.
  • The row the sentence describes is engine/cli.js:6817: ' converge [<ms> | at <ms>] - when each control plane finishes'.
  • The number was right when #2023 repointed the anchor (6765), then #2024 (LAG member limit) moved it to 6811 and #2041 (interface-description research) moved it to 6817 — two drifts in one day, because the citation points into an array literal that grows from above.

The row is now named by its own text (_help() carries converge [<ms> | at <ms>]), which is what a reader greps for and what no future landing above it can falsify.

scripts/check-doc-citations.js cannot judge this one either way: the sentence names _help() and the row sits 44 lines into it, past the 40-line tolerance — so the pointer would keep being a number nobody verifies.

Guards: syntax-check 426 files OK; docs-show-commands 59 forms / 118 commands / 74 refusals, 7 passed; docs-cli-transcript 4 passed; help-completeness 102 advertised commands, 16 shows, 19 mechanisms, 8 passed; doc-catalog-counts 43 passed; check-doc-citations 355 citations, 19 judged, 0 suspects; check-control-bytes clean. Counts unchanged before/after except citations 356 -> 355 (the number is gone).

Docs only — no engine change.

`docs/CLI.md` said `engine/cli.js:6765` was the `converge [<ms> | at <ms>]` row of the `help` index. It is not. **Evidence (the code is the truth):** - `engine/cli.js:6765` is the body of `_banner()` — `return 'PacketForge ' + dev.label + ' (' + dev.vendor + ' ' + dev.model + ')'`. - The row the sentence describes is `engine/cli.js:6817`: `' converge [<ms> | at <ms>] - when each control plane finishes'`. - The number was right when #2023 repointed the anchor (6765), then #2024 (LAG member limit) moved it to 6811 and #2041 (interface-description research) moved it to 6817 — two drifts in one day, because the citation points into an array literal that grows from above. The row is now named by its own text (`_help()` carries `converge [<ms> | at <ms>]`), which is what a reader greps for and what no future landing above it can falsify. `scripts/check-doc-citations.js` cannot judge this one either way: the sentence names `_help()` and the row sits 44 lines into it, past the 40-line tolerance — so the pointer would keep being a number nobody verifies. **Guards:** `syntax-check` 426 files OK; `docs-show-commands` 59 forms / 118 commands / 74 refusals, 7 passed; `docs-cli-transcript` 4 passed; `help-completeness` 102 advertised commands, 16 shows, 19 mechanisms, 8 passed; `doc-catalog-counts` 43 passed; `check-doc-citations` 355 citations, 19 judged, 0 suspects; `check-control-bytes` clean. Counts unchanged before/after except citations 356 -> 355 (the number is gone). Docs only — no engine change.
docs(cli): the converge help row is named by its text, because the line number moved twice today
All checks were successful
PR rebase / Rebase onto main and arm auto-merge (pull_request) Successful in 4s
CI / Classify the change (pull_request) Successful in 6s
CI / Server smoke test (pull_request) Has been skipped
CI / Docker build (pull_request) Has been skipped
CI / Test (Node 20) (pull_request) Successful in 58s
CI / Test (Node 22) (pull_request) Successful in 1m1s
CI / Test (Node 18) (pull_request) Successful in 1m7s
CI / Arm auto-merge (pull_request) Successful in 2s
41a2f328e3
`docs/CLI.md` told a reader that `engine/cli.js:6765` was the `converge [<ms> | at <ms>]` row of
`_help()`. That was true when #2023 fixed the anchor and false within the hour: the row is at 6817 now,
and 6765 is the `return 'PacketForge ' + dev.label …` line of `_banner()`. #2024 pushed it to 6811 and
#2041 pushed it again - the citation rotted twice in one day, which is what a pointer into an array literal
does.

The row is named by its own text instead, which is what a reader greps for and what survives the next
feature landing above it. `scripts/check-doc-citations.js` cannot judge this citation either way (it
lands 44 lines into `_help()`, past its 40-line tolerance), so the text is the durable form.
forgejo-actions scheduled this pull request to auto merge when all checks succeed 2026-11-18 22:31:00 +00:00
jaylouisw deleted branch docs/1118-2217 2026-11-18 22:38:02 +00:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
jaylouisw/packetforge!2044
No description provided.