Document References

A document is a GLB that carries geometry. Its gateway configuration, written machine knowledge and extension code each live in separate project files. The document names the files it needs.

References follow these rules:

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

You set these three fields on the document’s row in the project manifest (project.json). They are keyed by the document, so renaming its GLB keeps the references.

Each document names its files in project.json. Two documents can share the same configuration path.

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 ending `.md` (`.knowledge.md` by convention)
Script	Project code that extends the viewer for this document	A `.ts` or `.tsx` file under `plugins/`

The file ending identifies configurations and knowledge files, regardless of their folder. A configuration next to its model is recognised just like one in a connect/ folder. That folder is simply where the gateway writes configurations. File endings are hidden: 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.
Click a binding to reveal its file in the tree. To remove it, use the slot’s own control.

An empty slot displays a message, including on read-only documents. Only dropping a file needs write access. If a referenced file has been deleted, the reference is shown as missing.

Project code and the trust prompt

A script reference can be resolved two ways. Code compiled into the viewer build runs as part of it. Code from a project folder is read from the project and imported at runtime. It runs as ordinary JavaScript with the same authority as the page.

The viewer asks for permission to run project code:

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. If the browser cannot remember the answer, for example in a private window, the decision lasts for the session. The viewer asks again next time and never assumes permission.
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 included in the build does not require this permission. It is in the published repository and can be reviewed like the viewer itself. An uninformative prompt can teach users to dismiss prompts that matter.

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 .md (.knowledge.md by convention).
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.