Problem
contexting search-hints "query" --json returns [] in two very different situations:
- No matches — index exists and is healthy, query just didn't match anything
- Broken/missing index — index file doesn't exist or is corrupted, search silently returns nothing
LLM agents and tools can't tell the difference. They assume "empty results = nothing relevant" when it might mean "your index is broken."
Proposed Solution
Wrap JSON output in an envelope with metadata:
{
"source": "memory | snapshot | none",
"index_generated_at": "2026-06-16T10:00:00Z",
"results": [
{"path": "src/auth.go", "type": "file", "score": 85, "matches": ["..."]}
]
}
Where source:
"memory" — results from live watch server
"snapshot" — results from .ctx/ctx_index.json file
"none" — no index available, results always empty
Implementation Notes
- Modify
resultsToJSON or create new envelopeToJSON wrapper
- Track
source in the search flow (already have usedMemory bool in command_search.go:84)
index_generated_at from ContextIndex.GeneratedAt (already in index JSON)
- For
--dir-summary mode, add same envelope
- Non-JSON output (
--json=false) unchanged
Acceptance Criteria
Problem
contexting search-hints "query" --jsonreturns[]in two very different situations:LLM agents and tools can't tell the difference. They assume "empty results = nothing relevant" when it might mean "your index is broken."
Proposed Solution
Wrap JSON output in an envelope with metadata:
{ "source": "memory | snapshot | none", "index_generated_at": "2026-06-16T10:00:00Z", "results": [ {"path": "src/auth.go", "type": "file", "score": 85, "matches": ["..."]} ] }Where
source:"memory"— results from live watch server"snapshot"— results from.ctx/ctx_index.jsonfile"none"— no index available, results always emptyImplementation Notes
resultsToJSONor create newenvelopeToJSONwrappersourcein the search flow (already haveusedMemorybool incommand_search.go:84)index_generated_atfromContextIndex.GeneratedAt(already in index JSON)--dir-summarymode, add same envelope--json=false) unchangedAcceptance Criteria
--jsonoutput includessourcefieldsource: "none"when index missing or corruptedsource: "memory"when connected to live watch serversource: "snapshot"when reading from index fileindex_generated_atincluded when availableresultsarray has same shape as current output