Proposed machine retrieval

Nothing here is implemented. No retrieval server exists in CCC, and none is being built by the work that produced this collection. This page exists so a future implementer can map a capability to a definition that already holds, rather than inventing business meaning.

Why write it now

The expensive part of machine retrieval is not the transport. It is agreeing what a metric means, which identity it uses, which date basis, and what its limitations are. Those answers are the rest of this collection. Writing the capability contracts now keeps the definitions honest, because a capability that cannot be specified is usually one whose underlying definition is unclear.

Two design decisions have already been taken in the application's favour, and they cost nothing now while being expensive to retrofit:

• One getter serves both surfaces, so a screen and a future tool read through the same code.
• Retrieval is Markdown, rendering is HTML. The documents are the payload; the renderer is a presentation concern.

Documentation retrieval contract

A future documentation reader should support finding a relevant page and returning a whole page or named section. A result should carry its canonical id, title, type, section anchor, Markdown body, TL;DR, editorial dates and evidence references. Include the repository revision used for retrieval; updated alone is not a source revision or a data-freshness timestamp.

docs->getdocuments() and getdocument() already provide the local document map and content. The current adapter rewrites links for the app. A machine caller needs an explicit link-resolution contract, including canonical targets and source paths, so the answer remains navigable outside CCC. Unknown ids and missing sections should be distinct from empty search results.

Publish only the deliberately permitted document set. Documentation contains no live customer examples, but that is not an authorization policy for querying customer records. Business-data capabilities below need their own permissions, row limits and freshness evidence. Returning a guide to a repair must not execute the repair.

Proposed capabilities

Each is not implemented. Each would need the contract beside it settled before it is built.

What every capability needs

• the identity and date range it operates on, and which date basis
• the grain of its result, and the currency and sign convention
• the freshness evidence behind the answer
• behaviour on empty and partial results, distinguishing "no data" from "no source for that period"
• its permission boundary
• whether it can change anything. The recommendation is read-only. A write capability needs its own scope and its own review

Ambiguous questions, and what to ask back

Some questions cannot be answered correctly as asked, and answering them anyway is worse than asking:

• "How many new customers last month?" Which life definition, and which date basis.
• "What was our margin?" Expected or realised, which currency, and over which period basis.
• "Who used this discount code?" A discount code is a voucher, not an identity. It does not identify anyone.

What is deliberately not decided here

Transport, tool names, schemas, hosting and authentication. Those are implementation choices for whoever builds it, and settling them now would freeze guesses.

Access scope is not deferred, though: a documentation page permission does not define what a token may retrieve. The published set has to be a deliberate decision, and the same scope applies to both surfaces.

Related

• Consumption contracts
• Interfaces, what exists today
• Consuming CCC

Evidence

Capability contracts derive from the definitions in this collection, each cited in its own document. The two design decisions are recorded in the feature's research notes, taken from a working implementation on the same framework in a sibling repository. Basis: code-checked at 30f5313 for the CCC side. The proposed retrieval capabilities are not implemented; the existing disk models are the implementation foundation, not an MCP endpoint.