fix: KEEP-1051 prune stale doc pages, drop a version tag, and rename cmd/protocol

cmd/protocol/get.go → cmd/plugin/get.go

@@ -1,4 +1,4 @@
-package protocol
+package plugin
 
 import (
 	"encoding/json"

cmd/protocol/get_test.go → cmd/plugin/get_test.go

@@ -1,12 +1,12 @@
-package protocol_test
+package plugin_test
 
 import (
 	"encoding/json"
 	"net/http"
 	"net/http/httptest"
 	"testing"
 
-	"github.com/keeperhub/cli/cmd/protocol"
+	"github.com/keeperhub/cli/cmd/plugin"
 	"github.com/keeperhub/cli/internal/cache"
 	"github.com/keeperhub/cli/internal/config"
 	khhttp "github.com/keeperhub/cli/internal/http"
@@ -43,7 +43,7 @@ func TestGetCmd(t *testing.T) {
 	ios, outBuf, _, _ := iostreams.Test()
 	f := newProtoGetFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"get", "aave"})
 	err := cmd.Execute()
 	require.NoError(t, err)
@@ -70,7 +70,7 @@ func TestGetCmd_NotFound(t *testing.T) {
 	ios, _, _, _ := iostreams.Test()
 	f := newProtoGetFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"get", "nonexistent-slug"})
 	err := cmd.Execute()
 	assert.Error(t, err)

cmd/protocol/list.go → cmd/plugin/list.go

@@ -1,4 +1,4 @@
-package protocol
+package plugin
 
 import (
 	"encoding/json"

cmd/protocol/list_test.go → cmd/plugin/list_test.go

@@ -1,4 +1,4 @@
-package protocol_test
+package plugin_test
 
 import (
 	"encoding/json"
@@ -7,7 +7,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/keeperhub/cli/cmd/protocol"
+	"github.com/keeperhub/cli/cmd/plugin"
 	"github.com/keeperhub/cli/internal/cache"
 	"github.com/keeperhub/cli/internal/config"
 	khhttp "github.com/keeperhub/cli/internal/http"
@@ -78,7 +78,7 @@ func TestListCmd_CacheMiss(t *testing.T) {
 	ios, outBuf, _, _ := iostreams.Test()
 	f := newProtoFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"list"})
 	err := cmd.Execute()
 	require.NoError(t, err)
@@ -107,7 +107,7 @@ func TestListCmd_CacheHit(t *testing.T) {
 	ios, outBuf, _, _ := iostreams.Test()
 	f := newProtoFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"list"})
 	err := cmd.Execute()
 	require.NoError(t, err)
@@ -139,7 +139,7 @@ func TestListCmd_Refresh(t *testing.T) {
 	ios, _, _, _ := iostreams.Test()
 	f := newProtoFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"list", "--refresh"})
 	err := cmd.Execute()
 	require.NoError(t, err)
@@ -168,7 +168,7 @@ func TestListCmd_StaleWithError(t *testing.T) {
 	ios, outBuf, errBuf, _ := iostreams.Test()
 	f := newProtoFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"list"})
 	err := cmd.Execute()
 	require.NoError(t, err, "stale cache with error should not return error")
@@ -188,7 +188,7 @@ func TestListCmd_NoCacheWithError(t *testing.T) {
 	ios, _, _, _ := iostreams.Test()
 	f := newProtoFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"list"})
 	err := cmd.Execute()
 	assert.Error(t, err, "expected error when no cache and API fails")
@@ -211,7 +211,7 @@ func TestListCmd_Table(t *testing.T) {
 	ios, outBuf, _, _ := iostreams.Test()
 	f := newProtoFactory(server, ios)
 
-	cmd := protocol.NewProtocolCmd(f)
+	cmd := plugin.NewPluginCmd(f)
 	cmd.SetArgs([]string{"list"})
 	err := cmd.Execute()
 	require.NoError(t, err)

cmd/protocol/protocol.go → cmd/plugin/plugin.go

@@ -1,11 +1,11 @@
-package protocol
+package plugin
 
 import (
 	"github.com/keeperhub/cli/pkg/cmdutil"
 	"github.com/spf13/cobra"
 )
 
-func NewProtocolCmd(f *cmdutil.Factory) *cobra.Command {
+func NewPluginCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "plugin",
 		Short:   "Browse available plugins and integrations",

cmd/root.go

@@ -12,7 +12,7 @@ import (
 	"github.com/keeperhub/cli/cmd/help"
 	"github.com/keeperhub/cli/cmd/org"
 	"github.com/keeperhub/cli/cmd/project"
-	"github.com/keeperhub/cli/cmd/protocol"
+	"github.com/keeperhub/cli/cmd/plugin"
 	"github.com/keeperhub/cli/cmd/read"
 	"github.com/keeperhub/cli/cmd/run"
 	"github.com/keeperhub/cli/cmd/serve"
@@ -53,7 +53,7 @@ func NewRootCmd(f *cmdutil.Factory) *cobra.Command {
 	cmd.AddCommand(execute.NewExecuteCmd(f))
 	cmd.AddCommand(org.NewOrgCmd(f))
 	cmd.AddCommand(project.NewProjectCmd(f))
-	cmd.AddCommand(protocol.NewProtocolCmd(f))
+	cmd.AddCommand(plugin.NewPluginCmd(f))
 	cmd.AddCommand(read.NewReadCmd(f))
 	cmd.AddCommand(run.NewRunCmd(f))
 	cmd.AddCommand(serve.NewServeCmd(f))

cmd/serve/schemas.go

@@ -12,7 +12,7 @@ import (
 
 // SchemasResponse is the correct shape of the /api/mcp/schemas response.
 // The Actions field is a map keyed by actionType (e.g. "web3/check-balance").
-// NOTE: This is intentionally separate from cmd/protocol/list.go which uses a
+// NOTE: This is intentionally separate from cmd/plugin/list.go which uses a
 // different (incorrect) response shape for the protocol discovery commands.
 type SchemasResponse struct {
 	Actions map[string]ActionSchema `json:"actions"`

cmd/wallet/link.go

@@ -21,7 +21,7 @@ func NewLinkCmd(f *cmdutil.Factory) *cobra.Command {
 Thin wrapper around ` + "`npx @keeperhub/wallet link`" + `. Requires the KH_SESSION_COOKIE env var
 set to a valid kh session cookie (sign in at app.keeperhub.com, copy the session cookie, export it).
 
-v0.1.0 does not launch a browser session handshake; this env-var contract matches the npm CLI.`,
+This command does not launch a browser session handshake; the env-var contract matches the npm CLI.`,
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			if os.Getenv("KH_SESSION_COOKIE") == "" {

docs/generate.go

@@ -4,6 +4,8 @@ package main
 
 import (
 	"log"
+	"os"
+	"path/filepath"
 
 	"github.com/keeperhub/cli/cmd"
 	"github.com/keeperhub/cli/pkg/cmdutil"
@@ -16,6 +18,17 @@ import (
 // scanned.
 
 func main() {
+	// GenMarkdownTree only writes; it never removes. Without this sweep a page
+	// survives its own command: renaming `protocol` to `plugin` left three
+	// kh_protocol*.md behind, and deprecating `serve` left kh_serve.md, all
+	// still published while cobra had correctly dropped them from the index.
+	// Their content never changes, so the docs check sees no diff and cannot
+	// notice. Clearing first makes the generated tree authoritative, so a
+	// removal shows up as a deletion the check can catch.
+	if err := pruneGeneratedPages("."); err != nil {
+		log.Fatal(err)
+	}
+
 	ios := iostreams.System()
 	f := &cmdutil.Factory{AppVersion: "dev", IOStreams: ios}
 	root := cmd.NewRootCmd(f)
@@ -24,3 +37,21 @@ func main() {
 		log.Fatal(err)
 	}
 }
+
+// pruneGeneratedPages removes the generated command reference from dir.
+//
+// Only `kh*.md` is touched: the hand-written guides (quickstart.md,
+// concepts.md) and the generator's own sources live alongside it and must
+// survive.
+func pruneGeneratedPages(dir string) error {
+	matches, err := filepath.Glob(filepath.Join(dir, "kh*.md"))
+	if err != nil {
+		return err
+	}
+	for _, path := range matches {
+		if err := os.Remove(path); err != nil {
+			return err
+		}
+	}
+	return nil
+}

docs/kh_wallet_link.md

@@ -9,7 +9,7 @@ Link the current agentic wallet to your KeeperHub account by calling POST /api/a
 Thin wrapper around `npx @keeperhub/wallet link`. Requires the KH_SESSION_COOKIE env var
 set to a valid kh session cookie (sign in at app.keeperhub.com, copy the session cookie, export it).
 
-v0.1.0 does not launch a browser session handshake; this env-var contract matches the npm CLI.
+This command does not launch a browser session handshake; the env-var contract matches the npm CLI.
 
 ```
 kh wallet link [flags]