How a pack reads documents

When you teach a pack a document, edisyl turns it into records that it can search quickly and cite exactly. Every record keeps a link to the passage it came from. Any answer drawn from your documents points back to the words that support it.

What happens after you teach

1. Indexed. The document is split into chunks and indexed. The teach Action succeeds at this point. The pack can already read the document when an ask explores (the New route).
2. Compiled. In the background, edisyl extracts claims quoted word for word from the document and turns them into facts. It also adds what the document mentions to the pack’s context graph. When this compile finishes, the document is part of the governed answer that the Known and Understood routes plan over. A large document can take tens of minutes.
3. Tested. Calibration writes test questions about the new document and checks the pack’s answers to them. See Calibration.

edisyl calibrate status <pack> shows Compiling: … while step 2 runs. In chat, the assistant reads the calibration state with calibration_status. An ask during this time can return a missing-source gap. Wait for the compile to finish and ask again. Do not teach the same document twice.

The context graph

The context graph is the pack’s map of what your documents say. Each node is a thing the documents mention, such as a machine, a fault code, or an alarm. Each edge records how two of those things relate. When a question needs something from your documents, the pack uses this map to find the passages that matter.

You don’t edit the graph by hand. It is built from what you teach. You control it by choosing which documents go in and keeping them current.

Facts

A fact is a saved pointer to the exact place where an answer is. For a question about an error code, the fact points to the passage that describes that code. The pack goes directly there instead of searching again.

A fact records where the answer is, not a copy of its words. If that passage is revised later, the fact still points to the same place, and the answer uses the new text. Answers drawn from documents cite the claim quoted from the original.

The pack also creates facts as it works: during calibration, and the first time a live question needs exploration to answer. These are saved as learning candidates that later asks can use.

The Lexicon sits on top

People use different words for the same thing: a code, its nickname, its official name. The Lexicon maps those words to the same term. Each word then gets the same answer. On a pack built only from documents, Lexicon terms are bound to topics taken from the documents.

Documents and data sources work together

Teaching a document changes the context graph. Connecting a data source doesn’t. Instead, enrichment builds data models from your tables. Enrichment reads your documents to describe each table in your organization’s terms. Teach the documents before you connect the data.

Keep one version of each document

If you teach two versions of the same document, both stay in the pack. A question may be answered from either one, or the pack may ask which one you mean. When you replace a document, forget the old version before you teach the new one.

MCP

Say it in chat. The assistant calls forget on the old version, then teach with the new file.

“Forget the old travel policy, then teach this new version.”

MCP has no tool that lists a pack’s documents. The assistant takes the old version’s record id from an earlier teach, or from an answer that cited it.

CLI

edisyl pack documents list <pack>           # find the old version's record id
edisyl forget <pack> <record-id>
edisyl teach <pack> --file ./policy-v2.pdf

forget removes the document and everything created from it.

Teach the document, not a summary

Every teach becomes a document that answers cite, including a one-line --text note. If you teach the document that states a fact, the citation points to the real source. A definition of a word belongs in the Lexicon. An instruction about how the pack should work belongs in PACK.md.

Next: Calibration, for how the pack checks what it holds before people rely on it.