Files & Canon
Golden Terminal can work with real files on the connected computer, while your AI project can carry the context needed to understand them. The useful split is simple: local files hold working data, Canon holds durable project facts and rules, and temporary session state stays out of both unless it becomes important enough to preserve.
Quick answer: where should project context live?
Keep the source data where it naturally belongs and give the AI the smallest durable map it needs.
Local source code, logs and documents can stay on the connected computer. Canon should describe stable project facts, decisions, constraints, source-of-truth locations and operating rules. A handoff or active conversation should carry temporary state such as what was just tested, what failed and what should happen next.
Three context layers
| Layer | Best for | Avoid |
|---|---|---|
| Local files | Code, configs, logs, datasets, media, generated artifacts | Reading entire disks or repositories without a reason |
| Canon / project instructions | Stable facts, architecture, decisions, constraints, source-of-truth paths | Passwords, raw private keys, volatile logs, one-off debug output |
| Conversation / handoff | Current task state, recent tests, open hypotheses, next action | Turning every transient detail into permanent project doctrine |
What belongs in Canon
Canon is the durable operating map for a project. It should help a new AI session understand the project without re-discovering everything from scratch.
- Project goal and current product scope.
- Canonical repository, branch and source-of-truth documents.
- Important local paths and what each path contains.
- Machine or server roles expressed as stable names.
- Architecture decisions that should not be casually reversed.
- Deployment boundaries and systems that must not be touched.
- Known verification commands and acceptance criteria.
- Stable product terminology and UX decisions.
- References to credentials, never the credential values themselves.
Canon should reduce repeated discovery. It should not become a dump of every message, log line or temporary observation.
What should not go into Canon
- Raw passwords, private keys, recovery codes or unrestricted API tokens.
- Short-lived access tokens or temporary session identifiers.
- Large command outputs and logs that can be regenerated.
- Unverified guesses presented as settled facts.
- Temporary incidents that no longer affect the project.
- Duplicate copies of source code already stored in the repository.
- Old paths, servers or commands that have been superseded.
For credentials, store a reference such as an SSH profile, environment-variable name or credential-store entry. See Golden Secrets / Secure Input.
Working with local files
A connected computer can often hold much more context than should be sent into the model. Ask the AI to read the smallest relevant files first.
Good file work has an explicit target: a repository, directory, document or artifact. Avoid broad requests such as “read everything on my computer” when the task only needs one project.
For large logs
Filter by service, time window or error signature. Return the relevant lines and a conclusion instead of streaming an entire log into the conversation.
For large repositories
Start from the README, manifest and relevant modules. Expand only when the dependency path requires it.
Local files and uploaded files are different
A local path on connected-device is not the same thing as uploading a file into an AI conversation.
| Local file | Uploaded file |
|---|---|
| Remains on the connected computer until the task explicitly reads or changes it | Becomes part of the AI product's file/context workflow |
| Useful for source trees, logs, configs and large artifacts | Useful when the file itself must travel with the conversation or be reviewed without the computer |
| Can be referenced by path | Referenced as a conversation/project file |
| Best place for protected local credential files | Do not upload secret files merely to make a credential available |
When the AI needs to give a file to a human
Use Golden Drop when the AI already has the file and the user needs a temporary download link.
Golden Drop is part of Golden Terminal and uses the same Golden connection. Its share_files capability does not require a connected device or Golden Agent. Device access and file delivery are separate capabilities.
Canon vs handoff
Canon answers “what remains true?” A handoff answers “where did we stop?”
When a temporary decision becomes durable, move only that durable conclusion into Canon. Leave the operational history in the handoff, issue or commit.
Example project Canon
The example gives the AI a stable map without copying source code, logs or secrets into the Canon itself.
FAQ
Should Canon contain every path the AI has ever used?
No. Keep paths that are stable and useful for future work. Temporary directories and generated artifacts belong in task notes.
Can Canon contain an SSH alias?
Yes. An alias or profile name is useful context. Do not include the private key material.
Should I upload a whole repository to the AI?
Usually not when Golden can reach the working copy directly. Read the relevant files from the connected machine and expand only when needed.
What if the AI forgets a temporary test result?
Put the current state in a handoff or active task note. Promote only durable conclusions to Canon.
Ready to continue?
Use the current connection guide, then return to Help whenever you need the next layer.