Reference Docs: a library, not a search index.

Reference Docs are the documents your agents work from — the handbook, the style guide, the source material. GoTo Agents deliberately treats them as a curated library rather than a retrieval corpus: agents see an index of what exists and read whole documents when relevant, the same way a good collaborator uses a shelf of references.

Three scopes, one mechanism

Format: markdown with a "when to use it" description

Each document is markdown with YAML frontmatter — the same contract as every other GoTo Agents object. The description states when the doc should be consulted, exactly like a skill description states when a skill should load:

---
type: reference
description: Return/refund policy — consult for any customer return question.
tags: [policy, customer-service]
---

The index agents see is derived from these descriptions at prompt time — there's no separate index file to drift out of date. Raw data files (.csv, .json) can't carry frontmatter and appear by filename; if a data file needs explaining, write a small wrapper doc — better for the agent anyway.

How agents (and you) use them

• Standing index — every agent's prompt lists available docs with descriptions; the agent reads one in full with read_document(scope, path) when it's relevant, passing an optional section to pull just one heading of a long doc.
• Always-load — an agent-scope doc marked always_load: true is inlined into the system prompt wholesale, for the one spec that is the job.
• @-mention — reference any doc directly in chat to pull it into that message; profile docs are primarily used this way, on your initiative.
• From skills — a skill can cite a library doc by path: the playbook cites the handbook.

Uploads and imports

Text formats are stored as-is. PDF and Word uploads are imported — extracted to a visible, editable markdown file with source: and imported: frontmatter recording provenance — because a document agents will quote from should be one you can read and correct. Large documents get a size warning at upload: docs meant to be used fully should be docs that can be used fully.

Where's the vector database?

There isn't one, on purpose. For a curated shelf of documents, an index plus whole-document reading beats similarity search over chunks — chunk retrieval hands an agent paragraph 7 of a policy without the caveats in paragraph 2. If you genuinely have a large retrieval corpus, attach a RAG system via MCP; retrieval infrastructure is a fine thing to plug in and a poor thing to hard-wire.

Where it lives

• documents/ folders at each scope — the storage layer.
• core/prompt_builder.py — index assembly into the prompt.
• core/file_parser.py — the frontmatter contract.