Reference
Retrieval and Search
Understand how HotRoute customer-safe retrieval and search should cite product docs and visible football canon without exposing hidden private state.
Overview / Purpose
Retrieval and search help users and approved customer agents find the right context without turning search into authority.
In HotRoute, search may point to product docs or visible football canon. The user should still be able to inspect where the answer came from, what object was cited, and whether the system refused because the scope was missing or unsafe.
Who this is for
This page is for organization owners, coaches, analysts, and approved integration users who need to understand what customer-safe search can and cannot cite.
It is also useful when a service account or customer agent returns a refusal instead of an answer.
What to know first
Search is not a publish path. It does not approve plays, rewrite terminology, change a playbook, or make a callsheet authoritative.
Product-doc search and private-canon search are different:
- Product-doc search can cite approved HotRoute docs pages and sections.
- Private-canon search can cite visible customer football objects only when organization, team, season, role, entitlement, service-account scope, lifecycle, credit, and rate-limit checks allow it.
When scope is missing, ambiguous, or unsafe, HotRoute should ask for the missing scope or refuse. It should not reveal whether a hidden object exists.
How it works
Customer-safe retrieval can use these kinds of context:
| Context | What it can cite |
|---|---|
| Product docs | Approved public or customer-safe docs pages and sections. |
| Playbooks | Visible playbook records in the requested scope. |
| Plays and play versions | Visible play records and published or pinned version context when allowed. |
| Terminology | Published baseline or organization-local terms visible to the caller. |
| Tags and usage links | Safe relationship details that explain why a result matched. |
Search may return results, an empty result, a clarification request, a refusal, a rate-limit state, an unavailable-plan state, an insufficient-credit state, stale-source status, or provider-unavailable status.
Those states should be treated as part of the product. They keep the answer honest when HotRoute cannot safely cite the requested context.
The search response should explain why something matched. Useful citations include page or object label, source type, version or lifecycle context when available, and a short snippet from approved content.
Step-by-step instructions
- Start with a clear question.
- Include organization context when using a customer workspace or approved service account.
- Include team and season when the question depends on private football canon.
- Ask for product docs when you only need HotRoute product guidance.
- Ask for private canon only when the current user or service account has the right scope.
- Read the citations before acting on an answer.
- If HotRoute asks for scope, provide the missing team, season, playbook, or object context.
- If HotRoute refuses, do not try to infer hidden object existence from the refusal.
- Return to the source object before changing football truth.
What good looks like
A good retrieval or search result is cite-first and scope-aware.
Users should be able to answer:
- Did this result come from product docs or private football canon?
- Which object, page, or section was cited?
- Is the cited object published, draft-only, reduced, or otherwise limited?
- Why did the result match?
- What scope was used?
- Did the system ask for clarification or refuse safely when scope was missing?
- Did the response explain whether a denial came from scope, plan/add-on posture, credits, rate limits, lifecycle, or unavailable provider state?
Common questions or mistakes
Can product-doc search answer questions about my private playbook?
No. Product docs explain how HotRoute works. They do not decide or reveal customer-private football truth.
Can private-canon search cite drafts?
Only when the current user and surface are allowed to see that draft context. External and customer-agent use should prefer published or pinned refs unless an approved snapshot path exists.
Why did search ask for team or season?
Private football objects are scoped. Team and season help prevent cross-scope confusion and hidden-object leakage.
Does a search hit mean the object is authoritative?
No. Search can find context. Authority still belongs to the owning HotRoute object, published version, or approved source of truth.
Related docs / next steps
Read Manage Service Accounts before connecting an approved external tool.
Read External API for the customer-safe route families approved integrations can call.
Read Customer Agent Integrations before connecting Codex, Claude, ChatGPT, MCP, hotroute-tools, or another agent-style workflow.
Read Terminology Registry to understand term and tag citations.
Read Plays and Playbooks for the football objects private search may cite.