fix: KEEP-1051 prune stale doc pages, drop a version tag, and rename cmd/protocol - #78
Merged
Merged
Conversation
GenMarkdownTree only writes; it never removes. A page therefore outlives
its own command:
- kh_protocol.md, kh_protocol_get.md, kh_protocol_list.md - the command
was renamed to plugin (cmd/protocol/protocol.go declares Use:
"plugin"), so cobra generates kh_plugin*.md and drops protocol from
the index, but the old pages stayed
- kh_serve.md - serve is Deprecated, so IsAvailableCommand() is false
and cobra skips it by design
All four kept publishing commands that no longer exist. docs-check could
not notice: an orphan's content never changes, so it produces no diff.
Clearing kh*.md before generating makes the tree authoritative, so a
removal now surfaces as a deletion the check can catch. Only kh*.md is
swept - the hand-written guides and the generator sources sit in the same
directory.
The help text stated 'v0.1.0 does not launch a browser session handshake', which the generator publishes verbatim to docs.keeperhub.com. Version tags in published docs go stale silently - the sentence describes current behaviour, not behaviour specific to a release, so it now says so without pinning a version. The internal code comment above it keeps its provenance note; only the published string changes.
…mmand The package declares Use: "plugin" - it was renamed at some point and the directory never followed. That mismatch is what let the stale kh_protocol*.md pages go unnoticed: the generated pages were named after the command, the source after its former name, so neither looked wrong on its own. Renames the directory, protocol.go, the package, and NewProtocolCmd -> NewPluginCmd, plus the cross-reference in cmd/serve/schemas.go. No behaviour change and no generated-docs change: the command has been called plugin all along, so regenerating produces an identical tree.
5 tasks
suisuss
added a commit
that referenced
this pull request
Jul 28, 2026
Nothing in the CLI was called enable, so turning a workflow on looked impossible: pause turns off, go-live publishes a template, update has no flag. The capability existed as resume - named for the inverse of pause rather than for the action - so a reader scanning the verb list, or searching for enable, concluded it was missing and reached for the API or the web UI. enable and disable become the primary names. resume, activate and pause are kept as aliases and stay working indefinitely; scripts, tutorials and published doc links depend on them, and tests pin each alias to its command so a later rename cannot quietly drop one. Their help text now cross-references, so finding one leads to the other. Runtime output follows the new vocabulary: 'Workflow <id> disabled' rather than 'paused'. This is a visible change for anyone matching on that string, and leaving it would have kept the confusion the rename exists to remove - the command and its own output would disagree. Regenerating replaces the pause and resume pages with enable and disable, which is the first real exercise of the pruning added in #78: the old pages are deleted rather than left behind as orphans.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #76, from reviewing the first sync it produced
(KeeperHub/keeperhub#1843). Making generation run was not sufficient to make
it correct: the reference still contained four pages for commands that no
longer exist, and one page published a version tag.
Three commits, one per issue.
1. Stale pages outlived their commands (
81bd0b1)GenMarkdownTreeonly writes; it never removes. So a page survives its owncommand:
kh_protocol.md,kh_protocol_get.md,kh_protocol_list.md- the commandwas renamed to
plugin(Use: "plugin"), so cobra generateskh_plugin*.mdand drops
protocolfrom the index. The old pages stayed.kh_serve.md-serveisDeprecated, soIsAvailableCommand()is falseand cobra skips it deliberately.
All four kept publishing commands that do not exist. A reader following
kh protocol listgets an error.docs-checkcould not catch this, even after #76: an orphan's content neverchanges, so it produces no diff. Clearing
kh*.mdbefore generating makes thetree authoritative, so a removal now surfaces as a deletion.
72 -> 68 pages. Only
kh*.mdis swept; the hand-written guides and thegenerator sources share that directory and survive.
2. Version tag in published docs (
ca3e3e9)kh wallet linkhelp text said "v0.1.0 does not launch a browser sessionhandshake", published verbatim to docs.keeperhub.com. Version tags in published
docs go stale silently, and the sentence describes current behaviour rather than
one release's. Fixed at the source and regenerated - editing the page directly
would be overwritten by the next sync.
3.
cmd/protocol->cmd/plugin(f1167cd)The package declared
Use: "plugin"; the directory never followed. Thatmismatch is why the orphans went unnoticed - generated pages were named after
the command, sources after its former name, so neither looked wrong on its own.
No behaviour change and no generated-docs change: the command has been
pluginall along, so regenerating produces an identical tree. That is the evidence it is
a pure refactor.
Verification
The point is not that the orphans were deleted, but that the guard can now catch
them, so I tested that directly:
docs/kh_ghostcommand.md, regenerated -> it appears asD, sogit diff --exit-code docs/fails. Before this change an orphan producedno diff at all.
changes nothing user-visible.
go build,go vet,golangci-lint run ./...(0 issues), fullgo test -race ./...- no failures.Downstream
KeeperHub/keeperhub#1843 still carries the four orphan pages and the
v0.1.0line, so it should not merge as-is. Once this lands and a release publishes, the
sync regenerates that content correctly - or #1843 can be closed and superseded
by the next automated sync, as #1842 was.