oma-search · diff
git:20261010.7f78296 to git:20261026.aafee62
77 added, 38 removed. Audit A to A.
---
name: oma-search
description: Find external documentation, web sources, or remote code with
citations. Local code navigation uses the configured code tools.
---
# Search Router
## Scheduling
### Goal
- Route an information request to the appropriate channel and return relevant sources with trust labels.
+ Select the search or retrieval channel needed by the request and return sources
+ with supporting evidence and retrieval limits.
### Intent signature
- - Search, find, look up, reference docs, inspect official APIs, or search remote code.
- - Another skill requests docs, web, code, or local search with a query and constraints.
+ - Find external documentation, web information, or remote implementation examples.
+ - Read a known external URL or supply external sources to another skill.
### When to use
- - Library documentation, web research, GitHub/GitLab implementation patterns, or unclear search channels.
+ Library documentation, web research, remote code search, known-URL reading, and
+ requests whose external source channel needs selection.
### When NOT to use
- - Pure local code exploration -> use configured code intelligence under the shared contract.
+ - Pure local code exploration -> use configured code intelligence directly under
+ `../_shared/core/code-intelligence.md`; do not dispatch this skill.
- Git history/blame -> `oma-scm`; architecture analysis -> `oma-architecture`.
### Expected inputs
- Query, optional route hint (`docs`, `web`, `code`, `local`), source/recency constraints, and flags. Explicit `--docs`, `--code`, or `--web` selects the route; `--strict` filters trust, `--wide` retains labeled results, and `--gitlab` selects the remote code host.
+ Query or known URL; optional route hint (`docs`, `web`, `code`, `fetch`); version,
+ recency, host, repository and source constraints; optional web-provider override.
+ Explicit `--docs`, `--code` or `--web` selects the search route. `--gitlab` selects
+ the remote code host. `--strict` requires suitable primary or official sources
+ with inspected supporting content; `--wide` includes broader results with their
+ limitations. These modifiers preserve the request's source constraints.
### Expected outputs
- Ranked sources with URL or file reference, route, relevance, trust level/score, and material fallback limits. Do not invent sources when no reliable result is found.
+ An answer or relevant source list with source URL/file reference, route, actual
+ provider, source type, content-read status, supporting evidence and material
+ limitations. Include publication, retrieval and version details when observed.
+ Do not invent results, dates, sources or certainty.
### Dependencies
- Context7 for docs, runtime web search, `oma search`/`gh`/`glab` for remote code, and configured code intelligence or native local search.
+ Context7 for documentation; the configured `providers.web` (`native`, `brave` or
+ `exa`) for web discovery; `oma search code`/`gh`/`glab` for remote code; runtime
+ retrieval tools or `oma search fetch` for known URLs. `oma search providers`
+ reports registration, selection and credential metadata; `oma doctor` checks
+ credential presence without verifying validity or API reachability.
## Structural Flow
### Routes
- | Route | Primary | Fallback | Use for |
- |---|---|---|---|
- | `docs` | Context7 `resolve-library-id` → `query-docs` | Web search | Official API/framework documentation |
- | `web` | Runtime web search | `oma search fetch <url>` for known result URLs | Web sources |
- | `code` | `oma search code` | Report unavailable host/auth | Remote repository patterns |
- | `local` | Configured code-intelligence provider | Native search and scoped reads | Current project files and symbols |
+ | Route | Execution | Scope |
+ |---|---|---|
+ | `docs` | Context7 library resolution and queries; official-site discovery when needed | Official documentation within requested version constraints |
+ | `web` | Selected web provider: runtime tools for `native`, CLI adapter for `brave` or `exa` | Discover URLs relevant to a query |
+ | `code` | `oma search code` through the selected code host | Remote implementation matches within host/repository constraints |
+ | `fetch` | Available URL reader/browser or `oma search fetch <url>` | Read a URL already supplied or discovered |
### Failure and recovery
- - Missing/empty documentation lookup: use web search and state the fallback.
- - A known URL cannot be fetched: use the fetch strategies in the route reference; retain authentication/blocking errors if all strategies fail.
- - Configured local tools unavailable or timed out: follow `references/_shared/core/code-intelligence.md`.
- - Unknown trust: retain the result as `unknown` with score `—`; do not imply verification.
- - No result satisfies `--strict`: report that outcome and offer a wider or narrower query.
+ - Missing/empty documentation lookup: use official-site discovery while retaining
+ the documentation route's version and source limits.
+ - Selected web provider unavailable, unauthenticated or rate-limited: report its
+ failure. Do not silently replace an explicit provider choice with native search.
+ - Search returns no candidate URLs: refine within the original constraints or
+ report no result. URL retrieval cannot replace missing search results.
+ - A known URL cannot be read: use the retrieval-specific recovery reference and
+ preserve access/authentication errors and archive provenance.
+ - No source meets `--strict`: report the source or evidence gap. A broader result
+ set does not automatically satisfy the strict request.
### Exit
- Return evidence-backed results and disclose failed routes or source limitations. A domain score alone does not verify an individual claim.
+ Return supported results and disclose failed routes, unread sources, stale or
+ archived content, and version limits. A provider name or domain label does not
+ verify an individual claim.
## Logical Operations
### Canonical workflow path
- 1. Parse the query and explicit flags. Use `resources/intent-rules.md` only when classification is needed; select one route unless ambiguity requires more.
- 2. Dispatch using Routes. Load `resources/execution-protocol.md` for the selected channel's command flags, fetch strategies, or normalization details.
- 3. Collect source references and deduplicate by URL. For non-local results, resolve domain trust using `resources/trust-registry.md`; reuse the current session cache. Apply `--strict` after scoring.
- 4. Rank by relevance, using trust as a tiebreaker. Return the requested answer or source list with supporting references and fallback limitations.
+ 1. Resolve the requested outcome and constraints. Hand pure local-code requests
+ directly to configured code intelligence. For external work, select one primary
+ route; use `resources/intent-rules.md` only when selection is unclear.
+ 2. Execute that route using `resources/execution-protocol.md`. Resolve the web
+ provider from configuration or the request override. Add another route only
+ when the remaining evidence gap needs it; do not fan out by default.
+ 3. Read the relevant content needed to support the answer. Retain URLs and
+ inspection status, deduplicate results, and apply source/version constraints.
+ Use `resources/trust-registry.md` for provenance rules or an explicitly needed
+ optional domain diagnostic; no numeric lookup is required for ordinary results.
+ 4. Rank by relevance and source suitability for the question. Return the requested
+ answer or sources with evidence, the actual route/provider and material limits.
### CLI entry points
```bash
+ oma search providers
+ oma search web "<query>" [--provider <id>] [--limit <n>]
oma search code "<query>" [--host gitlab] [--language <lang>] [--repo <owner/repo>]
- oma search trust <domain>
oma search fetch <url>
+ oma search trust <domain>
```
- The CLI also exposes `api`, `api:search`, `meta`, `rss`, `rss:google`, `media`, `archive`, and `doctor`; use a primitive only when the selected route needs it.
+ Use `api`, `rss`, `meta`, `media`, `archive` or `doctor` only when the selected
+ operation needs that primitive. `trust` remains an optional domain diagnostic.
### Guardrails
- - Explicit route/source constraints take precedence over automatic classification.
- - Score at domain level, not URL-path or page level. Use the CLI registry and the documented Context7/official-site exceptions; do not invent scores.
- - Do not duplicate successful routes or search locally via the web.
- - Use available runtime web tools and the configured local provider; do not install or track a repository automatically.
+ - Preserve explicit route, provider, source, host, version and date constraints.
+ - Keep query discovery separate from reading an existing URL.
+ - Treat search snippets and excerpts as limited evidence; identify unread sources.
+ - Do not manufacture trust scores or promote Context7/GitHub results to claim-level
+ verification based on their provider or hosting domain.
+ - Do not repeat successful routes, search local project files via the web, install
+ a provider or track a repository automatically.
### Resource scope and effects
- Search may contact external services or inspect local code and spawn `gh`/`glab` processes. Query constraints, selected sources, and trust metadata are session context; persistent caches belong in generated state, not skill definitions.
+ Search may contact external services and spawn configured provider or code-host
+ processes. Retrieval may launch an available browser. Query constraints and
+ provenance are session context; persistent caches belong in generated state, not
+ skill definitions. Local source navigation belongs to the configured code tools.
## References
- - Intent classifier: `resources/intent-rules.md` (no explicit route or ambiguous query)
- - Route execution detail: `resources/execution-protocol.md` (selected channel only)
- - Trust resolution and cache rules: `resources/trust-registry.md` (non-local sources)
- - Recovery detail: `resources/error-playbook.md` (route failures)
- - Result checklist: `resources/checklist.md` (applicable route checks)
- - Examples: `resources/examples.md` (unfamiliar input/output contracts)
- - Local code-intelligence contract: `references/_shared/core/code-intelligence.md`
+ - Route selection: `resources/intent-rules.md` (unclear external request)
+ - Execution: `resources/execution-protocol.md` (selected route only)
+ - Provenance and optional domain diagnostics: `resources/trust-registry.md` (source/evidence interpretation)
+ - Recovery: `resources/error-playbook.md` (route failure)
+ - Result checks: `resources/checklist.md` (applicable source and evidence checks)
+ - Examples: `resources/examples.md` (unfamiliar input or boundary)
+ - Local-code handoff: `../_shared/core/code-intelligence.md` (local requests)