Document References

Overview

A document is a GLB, and a GLB carries geometry. Everything else a document needs — the gateway configuration it talks to, the written knowledge that belongs to the machine, the code that extends it — lives in the project as a separate file, and the document names it.

That naming is the whole model, and it is deliberately narrow:

Named on the document, and nowhere else. Nothing is found by scanning a folder, by a fixed path or by matching names. If a document does not name a file, that file is not bound to it.
Named relative to the project. A reference is a path inside the project directory. Copy or move the project and every binding still resolves, because nothing points outside.
Many documents may name the same file. Two documents naming the same configuration share it. There is no registry to keep in sync and no reverse list that can go stale.
Renaming does not break a binding. A document keeps its identity when its file is renamed, so the reference survives.

The three references

Reference	What it names	Recognised by
CONNECT configuration	The gateway configuration this document runs with	The file ending `.connect.json`
Knowledge file	The written knowledge belonging to this machine	The file ending `.knowledge.md`
Script	Project code that extends the viewer for this document	The reference itself

The ending is the classification, never the folder. A configuration kept next to its model is exactly as much a configuration as one in a connect/ folder — that folder is only where the gateway happens to write. The endings themselves are machinery and are never shown: a configuration called line3.connect.json is displayed as line3.

What a reference may point at

A reference must stay inside the project. These are refused:

an empty path
an absolute path, or one starting with a Windows drive letter
a URL
any path with a .. segment in it

The check is on whole segments, so an ordinary folder whose name merely contains dots is fine. Separators are normalised, so a path picked up on Windows and one typed by hand mean the same file.

Secrets are not part of the document reference. A project keeps them in its own sidecar file, connect/secrets.local.json unless the project names another location.

Binding and clearing

Bindings are made in the dashboard, on the card of the open document:

Open the dashboard and find the configuration or knowledge file in the project tree.
Drag it onto the open document’s card. The card highlights the slot the drop will fill.
To follow a binding, click it — the file is revealed in the tree. To remove it, use the slot’s own control.

A slot with nothing in it says so rather than staying blank, and it says so on a read-only document too; only the drop itself needs write access. A reference whose file has since been deleted is shown as missing instead of quietly resolving to nothing.

Project code and the trust prompt

A script reference can be resolved two ways. Code that was compiled into the viewer build runs as part of it. Code that arrives with a project folder does not: it is read out of the project and imported at runtime, which means it is ordinary JavaScript with the same authority as the page around it.

So it is asked for, and how it is asked matters:

Per project, not once for everything. The unit you can judge is “this folder, from these people”. Allowing one project never allows the next.
Once, then remembered. The answer is stored for that project, so switching documents does not ask again.
Refusal is the default. No answer means no execution. Where the browser cannot remember the answer — a private window, for instance — the decision holds for the session and is asked again next time. It is never assumed to be yes.
A project with no code never prompts. The question is only asked once there is something to ask about; reading a file executes nothing.

Code that came with the build is deliberately not gated. It is in the published repository and is as reviewable as the viewer itself; a prompt that carries no information only teaches people to click through prompts that do.

Project code must be self-contained. It is imported as a single unit, so it cannot pull in a sibling file of its own at runtime.

Quick Start

Put the configuration or knowledge file in the project, next to the model or in a folder of your choosing.
Give it the right ending — .connect.json or .knowledge.md.
Open the dashboard, open the document you want to bind it to, and drag the file onto its card.
Verify the binding by clicking it: the file is revealed in the tree.
Copy the whole project folder to another machine and open it there. Every binding still resolves.