docs: state that docs search has no true no-match - #117
Merged
Conversation
`docs search` is a semantic (Mintlify nearest-neighbour) search with no relevance threshold, so every query returns up to 10 plausible-looking hits -- a nonsense query included -- at exit 0. An agent could treat a returned hit as proof a concept exists, or an unexpected result as proof it is absent; both are wrong. The upstream returns no score to surface as a signal (the result carries only path/content/title, verified against the live API), so documentation is the fix. The `docs search` help and the embedded `docs agents` doc now say plainly that a hit is not proof, and point to `docs endpoints --filter` (which has a real no-match) for checking whether an endpoint exists. A guard test pins the caveat against a silent edit. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
leet-c1
added a commit
that referenced
this pull request
Sep 3, 2026
A full audit of every tracked .md file against the current command/help surface and recent PRs (#103-#117) found gaps where a shipped change had not reached one or more docs. No behavioral defects and no branding/identifier leaks were found; these are documentation-only fixes. HIGH: - cmd/agents.md: document the v0.6.0 BREAKING envelope-unwrap in "Reading output" — typed `get` prints the resource flat (`.id`, not `.app.id`), naming a wrapper key in `--fields` exits 2, and `mcp servers get` has only `connectorId`. README already covered this; the agent-facing doc did not. - README.md: add the `docs search` no-relevance-threshold caveat (#117), which had reached help + `docs agents` but not README. - CHANGELOG.md: merge the duplicated `### Added`/`### Changed` headers in [Unreleased] into one block each (Added/Changed/Fixed); all 14 entries preserved verbatim. MED: - README.md: `policies` step_kinds/baseline_policy_id + the auto-approval jq recipe (#103); `mcp servers register --user-id` and the flags settable at register time. - cmd/agents.md: `mcp tools approve` takes multiple ids in one process (#116). - CLAUDE.md: document the shared repeatable-flag registrar convention (#111). LOW: - README.md: `--tool-id` caps (100/32), requestable-connectors non-pagination, `entitlements create --resource-type` default CUSTOM, `requests create --duration` is Go-style vs the protobuf-duration flags. - cmd/agents.md + skill: malformed-`--url` rejection (#115). - CLAUDE.md: negative `--limit`/`--page-size` rejection + page-size clamp. - .claude/commands/c1i.md: add `auth token`, the ~/.c1i.yaml wrong-tenant stderr warning, a pointer to the command groups, and the docs-search caveat. Every claim verified against `--help` or live behavior; embedded `docs agents` re-checked to render the new content. Build/vet/test/shuffle/lint/gosec/gitleaks /govulncheck all clean. Co-authored-by: leet-c1 <264029741+leet-c1@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
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
1 participant
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.
Closes ledger item C53.
c1i docs searchis a semantic search (Mintlify nearest-neighbour). It returns up to 10 plausible-looking hits for any query — a nonsense query included — at exit 0. An agent could read a returned hit as proof a concept exists, or an unexpected result as proof it's absent. Both are wrong, and nothing in the output marks a weak match.Why documentation, not a relevance signal
The upstream returns no score: the response carries only
path,content, andmetadata.title(verified against the live API). There's nothing to threshold on, and a client-side "is this a good match" heuristic would be exactly the fragile guesswork to avoid. So the honest fix is to say so.What changed
docs search --helpand the embeddeddocs agentsdoc now state plainly: semantic, no relevance threshold, up to 10 hits; a hit is not proof a concept exists, an unexpected hit is not proof it's absent; usedocs endpoints --filter(which has a real no-match) to check whether an endpoint exists.Validation
docs search --helpanddocs agentsboth render the caveat (verified on the built binary); the nonsense-query hit still returns at exit 0 (now documented). Three independent reviews (full + wording + reflow), all clean. Gates: build, vet, test,-shuffle=on, golangci-lint (0), gosec (0), gitleaks (clean), govulncheck (clean).🤖 Generated with Claude Code