docs(cli): correct agentic query JSON contract (NVBug 6657480)

[kheiss-uwzoo]

Summary

• Correct the documented agentic CLI result contract after PR Return full metadata with agentic retrieval hits #2569 (NVBug 6657480).
• Dense retriever query still projects five fields (modality, page_number, score, source, text). Agentic mode prints the internal hit dictionary plus doc_id, rank, and result_source.
• CLI unretrieved hits are annotation-only (keys absent, not null). Service/MCP unresolved hits still fill nulls and fall source back to doc_id.
• Align nemo_retriever/README.md, the CLI README (MkDocs quickstart snippet), and the published agentic concept and workflow pages.

Test plan

• Compare dense vs --agentic JSON keys on the same LanceDB table.
• Confirm rehydrated_agentic_hit(None, ...) returns only doc_id, rank, and result_source.
• Confirm the two README surfaces and the workflow result-contract section agree with each other.

pre-draft: leakage, mkdocs --strict, ::a, ::p, ::r on the diff vs main

Base: upstream/main
Files: docs/docs/extraction/agentic-retrieval-concept.md, docs/docs/extraction/workflow-agentic-retrieval.md, nemo_retriever/README.md, nemo_retriever/docs/cli/README.md

Check	Result
Leakage (page roles + see [ CTAs)	PASS ? working-tree grep of these 4 files has no see [ CTAs; faq.md / overview.md / multimodal-extraction.md unchanged. The leakage script vs origin/main scanned 31 files (fork origin/main is behind upstream/main) and flagged untracked leftover custom-metadata.md, which is not in this diff.
Allowed paths	PASS ? 4 documentation files
mkdocs --strict	FAIL ? exit 1; 4 warnings on untracked leftover custom-metadata.md and user-defined-stages.md. Those pages are not in this diff. Changed pages produced no warnings.
::a audit	PASS ? 8 claims triangulated at ~95%. Dense CLI 5-key projection (cli/query/app.py:86-92, tests/test_root_query_cli.py:43). Agentic CLI dumps rehydrated_agentic_hit() (query/workflow.py, cli/query/app.py:287, tests/test_agentic_eval.py:176). Degraded CLI is annotation-only (agentic.py:577, test_agentic_eval.py:196). Service unresolved hits use nulls and source=doc_id (service/agentic_query.py:26-72, test_service_agentic_query.py:121). DORI validate_code_blocks / verify_docs / detect_drift passed on all 4 files.
::p polish	Applied ? replaced ?serializers? / ?serializes? with ?output? / ?prints?; rewrapped the result_source sentence.
::r style	95% ? no blocking issues in the new contract prose

Code drift (not in this docs PR): nemo_retriever/src/nemo_retriever/query/workflow.py:222 still claims the same fields as dense query_documents. nemo_retriever/src/nemo_retriever/query/agentic.py:571 still says agentic output matches classic retrieval.

PR: this draft

[greptile-apps]

Greptile Summary

Corrects the documented agentic-query JSON contract to distinguish local CLI output from the service and MCP response envelope.

• Clarifies that dense CLI queries use a five-field projection while agentic CLI queries preserve the internal hit dictionary and add ranking annotations.
• Documents annotation-only unresolved CLI hits and null-filled unresolved service/MCP hits.
• Aligns the main README, CLI quickstart, concept page, and workflow documentation.

Confidence Score: 5/5

The documentation-only PR appears safe to merge.

The revised CLI, service, and MCP contracts align with the checked serialization, response-adapter, and unresolved-hit behavior, with no actionable inconsistency identified.

Important Files Changed

Filename	Overview
docs/docs/extraction/agentic-retrieval-concept.md	Correctly distinguishes agentic CLI results from the five-field dense CLI projection.
docs/docs/extraction/workflow-agentic-retrieval.md	Accurately documents the separate CLI and service/MCP result shapes, including unresolved-hit behavior.
nemo_retriever/README.md	Updates the agentic retrieval example with the correct ranking annotations and absent-key behavior.
nemo_retriever/docs/cli/README.md	Clarifies that agentic mode is not output-compatible with the compact classic CLI projection.

_{Reviews (1): Last reviewed commit: "docs(cli): correct agentic query JSON co..." | Re-trigger Greptile}