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

[spark2ignite]

What

dci commands --search "<task in plain words>" ranks the command catalog against a natural-language query so an agent (or a human) finds the right command without loading the ~270-entry catalog into context. Prompted by Cloudflare's cf cli search (launch post); this was the one agent-facing feature dci lacked.

$ dci commands --search "budgets about to overspend" --limit 3
budgets-at-risk  List budgets projected to breach their configured amount before the current period ends
                 e.g. dci budgets-at-risk
list-budgets     List budgets
                 e.g. dci list-budgets
get-budget       Retrieve a budget
                 e.g. dci get-budget "Team Backyard"

Run `dci <command> --help` for arguments and flags, or `dci commands --json` for the full catalog.

In agent mode (or with --json) the same search returns a compact envelope: query, ranked results with the matched words, destructive flag, beta stage, one curated example each, and a next-step hint.

How it ranks

Deterministic weighted keyword matching over the catalog entries themselves (name, curated keywords, summary, examples, argument and flag text, notes, related), built on the fly from the same data dci commands --json prints. Prefix matching stands in for stemming, a small synonym table maps everyday verbs and nouns to the API vocabulary, and coverage scaling rewards entries that match every query word. No model, no extra network call. Beta commands are always searchable and marked.

Command docs: optional keywords:

Some spec summaries are too terse to be found ("Run a query"). Command docs gain an optional keywords: list, indexed at the same weight as the command name and exposed additively in the catalog JSON (schema version unchanged). Not rendered in --help or on the Help Center. Tagged query, status, login, validate, customer-context show, budgets-at-risk. omni's generator parses these files with js-yaml against a TypeScript type and ignores unknown keys. Documented in COMMAND-DOCS-SPEC.md §3.

Telling the agent

The one-time agent onboarding hint now leads with the search command; the root --help long description and examples, dci docs, dci commands --help, the README, and the embedded skill (SKILL.md, examples.md) all mention it.

Testing

• Unit tests for tokenizing, stemming, query normalization (including dropping a synonym that duplicates another query word), ranking on a fixture catalog, result shape, JSON vs. text output, no-match hint, limit validation, and keyword propagation into the catalog.
• Hand runs against the live spec in agent and human mode for ~15 queries; every one returns the intended command first.
• A blind subagent given only the binary, an empty config dir, no credentials, and two tasks found --search from the onboarding hint on its third call and got the right command at rank one for both tasks.
• Full suite passes, including the pty end-to-end tests.

Found along the way (not in this PR)

On a fresh install with no credentials, dci --help, dci help, and dci <cmd> --help all fail with "no credentials available", so a new agent's first help call teaches it nothing. Pre-existing; being fixed separately.

Changelog

User-facing (feat:); add a ### New bullet under the next release heading when tagging.

🤖 Generated with Claude Code

[chaim0m]

Nice addition

[claude]

I reviewed this PR and didn't find any bugs. Because it's a sizable new feature (a ~465-line deterministic ranking engine plus wiring through command_catalog.go, docs_command.go, and main.go) and it touches skills/dci-cli/ (a CODEOWNERS-protected path), a human look would still be worthwhile.

What was reviewed:

• Beta-catalog wiring in command_catalog.go: confirmed --search now always loads the beta spec and merges beta entries into the catalog before ranking; checked betaCatalogEntries/buildCommandCatalog for the suggested duplicate/mismarked-entry scenario on a literal "beta" query and found no duplicate catalog entries introduced by the merge.
• Command-docs keyword additions (query.yaml, budgets-at-risk.yaml, etc.): the new keywords: flow-array formatting matches Prettier's exploded-array style used elsewhere in the repo.
• Search ranking flow (tokenizing, synonym table, field weighting) in command_search.go against its test coverage in command_search_test.go.

Extended reasoning...

The diff adds a new command_search.go/_test.go chapter pair implementing natural-language ranking over the ~270-entry command catalog, wires it into commands/help plumbing in command_catalog.go, command_docs.go, docs_command.go, and main.go, adds an optional keywords: field to several command-docs YAML files, and updates README.md and skills/dci-cli docs. No auth, crypto, or injection-relevant surface is touched; it's read-only catalog/search logic. Two candidate issues (beta-spec parse failures hard-failing unrelated searches; potential duplicate/mismarked results when searching the literal word "beta") were already investigated and ruled out before this run, and I did not find a duplicate-entry defect in the catalog merge code myself. Approval is withheld mainly because of the change's size/complexity and because it touches a CODEOWNERS-owned path (skills/), not because of any specific defect found.