Documents and retrieval model

Documents in the extension system fall into two categories.

10.1 Thread-attached documents

Chat retrieval works against thread-attached files.

The retrieval settings struct is DocumentRetrievalSettings:

{
  "maxChunks": 8,
  "taggedFiles": ["spec.pdf", "notes.md"]
}

Only files attached to the thread are accepted by validated_tagged_files() unless a specialized path explicitly provides a different mapping.

10.2 Document snapshots for retrieval/search

Use extension_upsert_document_snapshot() to store searchable text snapshots in the host vector DB.

Payload:

• documentName
• content or text
• optional maxChunkSize

Return value includes:

• ok
• documentName
• documentPath
• maxChunkSize

Snapshots are stored under a derived path shaped like:

• extension-snapshots/<extensionId>/<documentName>

10.3 Important rule

Being present in vector storage does not automatically make a document part of every chat. Retrieval still depends on how the thread and request identify allowed files.