feat: dci commands --search finds the command for a task in plain words

COMMAND-DOCS-SPEC.md

@@ -162,6 +162,12 @@ notes: |
 
 # Optional. Defaults to the other commands in the same group.
 related: [get-anomaly, list-anomalies, anomalies-recent]
+
+# Optional. Plain words a user reaches for that neither the command name nor
+# the spec summary contains. They feed `dci commands --search` at the same
+# weight as the command name and are not rendered in --help or on the web.
+# Add them when a search for the command's obvious task misses it.
+keywords: [spike, unusual spend, review, resolve]
 ```
 
 Rules:

README.md

@@ -56,6 +56,9 @@ dci --help
 # Get help for a specific command
 dci list-budgets --help
 
+# Find the command for a task described in plain words
+dci commands --search "budgets about to overspend"
+
 # Get the machine-readable command catalog
 dci commands --json
 ```

command-docs/budgets-at-risk.yaml

@@ -8,4 +8,6 @@ examples:
   - description: Just the first five.
     command: "dci budgets-at-risk --max-results 5"
 
+keywords: [overspend, breach, over budget, forecast, projected]
+
 related: [list-budgets, get-budget]

command-docs/commands.yaml

@@ -1,6 +1,10 @@
 command: commands
 
 examples:
+  - description: Find the command for a task described in plain words — the best matches, with a curated example each.
+    command: 'dci commands --search "budgets about to overspend"'
+  - description: The same search as JSON (what agents get by default), with the matched words and a next-step hint.
+    command: 'dci commands --search "delete a report" --json'
   - description: The machine-readable catalog of every command, with arguments, flags, and curated examples.
     command: "dci commands --json"
   - description: Include beta commands (invoked as dci beta <command>).

command-docs/customer-context-show.yaml

@@ -3,3 +3,5 @@ command: customer-context show
 examples:
   - description: Show the persisted default customer context.
     command: "dci customer-context show"
+
+keywords: [current customer, which customer, active customer, tenant]

command-docs/login.yaml

@@ -3,3 +3,5 @@ command: login
 examples:
   - description: Sign in through the DoiT Console in your browser.
     command: "dci login"
+
+keywords: [sign in, log in, authenticate, browser, oauth, session]

command-docs/query.yaml

@@ -12,4 +12,25 @@ examples:
   - description: A stacked chart under the table (human mode only).
     command: "dci query --chart < query.json"
 
+keywords:
+  [
+    spend,
+    cost,
+    usage,
+    how much,
+    breakdown,
+    by service,
+    by project,
+    by label,
+    last month,
+    trend,
+    analytics,
+    cloud analytics,
+    report config,
+    gcp,
+    aws,
+    azure,
+    cloud provider,
+  ]
+
 related: [get-report, get-report-config, update-report]

command-docs/status.yaml

@@ -5,3 +5,5 @@ examples:
     command: "dci status"
   - description: Force agent mode to see the machine-oriented output.
     command: "dci status --agent"
+
+keywords: [logged in, signed in, who am i, current customer, which customer, active context, agent mode, configuration]

command-docs/validate.yaml

@@ -11,6 +11,8 @@ examples:
   - description: As JSON, for a CI preflight step.
     command: "dci validate --output json"
 
+keywords: [logged in, who am i, whoami, access check, permissions, credentials, api key]
+
 notes: |
   :::tip Authentication vs. access
   `dci login` proves authentication; `dci validate` confirms both identity and access under

command_catalog.go

@@ -54,6 +54,8 @@ type commandCatalogEntry struct {
 	Examples []commandCatalogExample `json:"examples,omitempty"`
 	Notes    string                  `json:"notes,omitempty"`
 	Related  []string                `json:"related,omitempty"`
+	// Keywords are the curated search words from the command doc; additive.
+	Keywords []string `json:"keywords,omitempty"`
 }
 
 type commandCatalogExample struct {
@@ -91,8 +93,12 @@ var requiredOperationFlags = map[string]map[string]bool{
 func registerCommandCatalog() {
 	command := &cobra.Command{
 		Use:   "commands",
-		Short: "Print the machine-readable command catalog",
-		Args:  cobra.NoArgs,
+		Short: "Print the machine-readable command catalog, or search it in plain words",
+		Long: "Print the machine-readable command catalog (every command with its arguments, flags, " +
+			"and curated examples), or pass --search to find the command for a task described in " +
+			"plain words — the catalog is large, so search first and read one command's --help " +
+			"rather than loading the whole catalog.",
+		Args: cobra.NoArgs,
 		RunE: func(command *cobra.Command, args []string) error {
 			apiCommand := findDCICommand()
 			if apiCommand == nil {
@@ -103,7 +109,12 @@ func registerCommandCatalog() {
 				return fmt.Errorf("load DCI command catalog: %w", err)
 			}
 			catalog := buildCommandCatalog(api)
-			if includeBeta, _ := command.Flags().GetBool("beta"); includeBeta {
+			query, searching := commandSearchRequested(command)
+			includeBeta, _ := command.Flags().GetBool("beta")
+			// Search always covers beta commands: a hit it hides is a command
+			// the caller never learns exists. Results carry stage: beta and the
+			// early-access note, so a gated hit is still an informed one.
+			if includeBeta || searching {
 				betaAPI, err := loadBetaAPI()
 				if err != nil {
 					return fmt.Errorf("load beta command catalog: %w", err)
@@ -117,13 +128,17 @@ func registerCommandCatalog() {
 					return strings.Join(catalog.Commands[i].Path, " ") < strings.Join(catalog.Commands[j].Path, " ")
 				})
 			}
+			if searching {
+				return runCommandSearch(command, catalog.Commands, query, os.Stdout)
+			}
 			encoder := json.NewEncoder(os.Stdout)
 			encoder.SetIndent("", "  ")
 			return encoder.Encode(catalog)
 		},
 	}
-	command.Flags().Bool("json", false, "Emit JSON (the catalog's stable wire format)")
+	command.Flags().Bool("json", false, "Emit JSON (the catalog's stable wire format; with --search, the ranked results as JSON even at a terminal)")
 	command.Flags().Bool("beta", false, "Include beta commands (invoked as dci beta <command>; entries carry stage: beta)")
+	registerCommandSearchFlags(command)
 	cli.Root.AddCommand(command)
 }
 
@@ -262,6 +277,7 @@ func applyCommandDocToCatalogEntry(entry *commandCatalogEntry) {
 	}
 	entry.Notes = doc.Notes
 	entry.Related = doc.Related
+	entry.Keywords = doc.Keywords
 	positional := 0
 	for _, argument := range entry.Arguments {
 		if argument.Location == "path" {

command_docs.go

@@ -46,6 +46,12 @@ type commandDoc struct {
 	// replaces omni's former command-notes/<command>.mdx overlays.
 	Notes   string   `yaml:"notes,omitempty" json:"notes,omitempty"`
 	Related []string `yaml:"related,omitempty" json:"related,omitempty"`
+	// Keywords are the plain words a user reaches for that the command name
+	// and spec summary do not contain ("spend", "how much", "logged in").
+	// They feed `dci commands --search` (command_search.go) at the same
+	// weight as the command name, and nothing else: --help and the Help
+	// Center page do not render them.
+	Keywords []string `yaml:"keywords,omitempty" json:"keywords,omitempty"`
 }
 
 type commandDocExample struct {