Reference
Storage Permissions in Local, Vault, and Drive Workflows
Choose a storage boundary deliberately: local files, Thegram Vault mounts, and Google Drive mounts have different identities, permissions, paths, synchronization, and conflict behavior.
Explore as .gram
Start by checking the exact destination
Before opening, importing, or editing a document, identify the canonical copy and the storage identity that owns it. A local file, a Thegram Vault mount, and a Google Drive mount are different destinations; signing in to one does not grant access to another. Inspect the full mount key, path, reported access level, and selected account before writing.
For client setup, use the shared local setup or cloud setup guide. This page explains what the storage boundaries mean; it is not a substitute for provider consent or a role grant.
Local files: the person and filesystem control access
A local .gram file is governed by the operating-system account and filesystem permissions of its location. Desktop local mode can work without an account or network request. That convenience does not synchronize the file to another device or make it shared. Keep the original in the chosen folder, and do not move it to a cloud location just to make a client show it. The file contains document content and revision history; search indexes and other derived views are not a replacement for it.
If an agent connection is enabled, its read/write mode is a separate local app permission. Choose Read when the agent only needs context; enable Read and Write only when that is the intended capability. The app must be running for its local connection. See local setup for the current host-specific flow.
Thegram Vault: authorize an account, then use the returned mount
A Vault mount is account-backed service storage. Authentication, organization membership, the effective role, and a mount's reported access level determine what that caller can do; a document's .gram fields do not grant access. A viewer or read-only mount cannot be made writable by changing the requested path. Vault document writes are limited to top-level .gram documents: use a path such as @mounts/<vault-id>/project.gram, not an invented nested path. The literal <vault-id> must be the identifier returned in the mount key.
After connection, call gram_projects and copy the exact mount key from its response. The key (for example, @mounts/<id>) is the stable path prefix to use; do not substitute a display name or guess an ID. Confirm the destination account and access level before each requested write. If a write is denied, stop at that destination; do not silently copy to another mount.
A cloud account may receive a default writable Vault during first discovery if none exists. That is account setup, not authorization to create project records or import private content. Confirm the user's requested document and destination separately. See cloud setup for the connection path.
Google Drive: provider consent and folder scope are separate
A Drive mount is based on the Google account and Drive scopes authorized for the integration. Personal Drive and Shared Drive are distinct places; the visible folder and the granted provider permissions constrain access. The mount's returned key and exact path identify the destination. Drive mounts can expose folders, unlike Vault's top-level document-path restriction, but that does not make every file or Shared Drive writable. Follow the mount's actual access report and provider response.
A Drive OAuth grant is not a Thegram account role, and a Thegram login is not a Google authorization. Revoke or narrow provider access through the provider's own account controls; changing a .gram record cannot change OAuth scopes or Drive sharing.
Handle updates as conditional writes
For an update, read the current document and use the revision and hash observed from that same state as the compare-and-swap precondition. Core records the accepted change as a new revision. If another writer has changed the document, a stale-revision or storage-conflict response means the write was not accepted against the state you observed: read the new current version, compare both edits, and construct a fresh intentional change. Do not replay a stale patch unchanged or replace the file by hand.
For a Drive-backed write, claim remote persistence only when the returned synchronization state is synced. A successful local Core write or request receipt does not by itself prove that Drive has synchronized it. If synchronization is pending or failed, retain the source and report the actual state. Do not retry into a different mount to make a failed sync appear successful.
A safe choice in practice
Choose local storage when one person needs a file on that machine and explicitly owns its filesystem location.
Choose a Vault mount when the intended account and organization role provide the required access; verify the exact top-level mount path.
Choose Drive when the authorized Google account and mounted folder are the intended shared source; verify personal versus Shared Drive scope.
For any remote destination, inspect its key and access report, use a current revision/hash, and read back the result. Report provider sync only when the provider confirms it.
Limits and evidence
These paths have different trust boundaries. A public web renderer is an ephemeral document-rendering service, not a mounted storage location or sync target. An iOS Vault/Drive document is a read-only downloaded copy in the reviewed client flow; it does not imply editing the provider's file. Exact role, OAuth, and synchronization behavior is determined by the currently deployed service and provider response, not this guide.
Internal Vault service contract reviewed for account identity, mount roles, path constraints, conditional writes, and synchronization; not a public service-availability claim.
https://github.com/clab-one/thegram-vault/blob/main/docs/SPEC.mdGoogle Drive API documentation on file permissions and access behavior.
https://developers.google.com/drive/api/guides/about-permissionsThegram Core source-history contract for History/6 revisions, CAS writes, state replay, and journal provenance.
https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.mdInternal Desktop, iOS, local agent, and cloud MCP sources reviewed for local connection permissions and read-only downloaded client flows.
sha256:0320384eaf6203c8d10873fda9497e3e999deb611701aa911859b45d0c0fca4e@gram 2
doc blog-storage-permissions
t Storage Permissions in Local, Vault, and Drive Workflows
d Choose a storage boundary deliberately: local files, Thegram Vault mounts, and Google Drive mounts have different identities, permissions, paths, synchronization, and conflict behavior.
tag reference
view document
::rich
# Start by checking the exact destination
Before opening, importing, or editing a document, identify the canonical copy and the storage identity that owns it. A local file, a Thegram Vault mount, and a Google Drive mount are different destinations; signing in to one does not grant access to another. Inspect the full mount key, path, reported access level, and selected account before writing.
For client setup, use the shared [local setup](/guides/local-setup/) or [cloud setup](/guides/cloud-setup/) guide. This page explains what the storage boundaries mean; it is not a substitute for provider consent or a role grant.
## Local files: the person and filesystem control access
A local .gram file is governed by the operating-system account and filesystem permissions of its location. Desktop local mode can work without an account or network request. That convenience does not synchronize the file to another device or make it shared. Keep the original in the chosen folder, and do not move it to a cloud location just to make a client show it. The file contains document content and revision history; search indexes and other derived views are not a replacement for it.
If an agent connection is enabled, its read/write mode is a separate local app permission. Choose Read when the agent only needs context; enable Read and Write only when that is the intended capability. The app must be running for its local connection. See [local setup](/guides/local-setup/) for the current host-specific flow.
## Thegram Vault: authorize an account, then use the returned mount
A Vault mount is account-backed service storage. Authentication, organization membership, the effective role, and a mount's reported access level determine what that caller can do; a document's .gram fields do not grant access. A viewer or read-only mount cannot be made writable by changing the requested path. Vault document writes are limited to top-level .gram documents: use a path such as `@mounts/<vault-id>/project.gram`, not an invented nested path. The literal <vault-id> must be the identifier returned in the mount key.
After connection, call `gram_projects` and copy the exact mount key from its response. The key (for example, `@mounts/<id>`) is the stable path prefix to use; do not substitute a display name or guess an ID. Confirm the destination account and access level before each requested write. If a write is denied, stop at that destination; do not silently copy to another mount.
A cloud account may receive a default writable Vault during first discovery if none exists. That is account setup, not authorization to create project records or import private content. Confirm the user's requested document and destination separately. See [cloud setup](/guides/cloud-setup/) for the connection path.
## Google Drive: provider consent and folder scope are separate
A Drive mount is based on the Google account and Drive scopes authorized for the integration. Personal Drive and Shared Drive are distinct places; the visible folder and the granted provider permissions constrain access. The mount's returned key and exact path identify the destination. Drive mounts can expose folders, unlike Vault's top-level document-path restriction, but that does not make every file or Shared Drive writable. Follow the mount's actual access report and provider response.
A Drive OAuth grant is not a Thegram account role, and a Thegram login is not a Google authorization. Revoke or narrow provider access through the provider's own account controls; changing a .gram record cannot change OAuth scopes or Drive sharing.
## Handle updates as conditional writes
For an update, read the current document and use the revision and hash observed from that same state as the compare-and-swap precondition. Core records the accepted change as a new revision. If another writer has changed the document, a stale-revision or storage-conflict response means the write was not accepted against the state you observed: read the new current version, compare both edits, and construct a fresh intentional change. Do not replay a stale patch unchanged or replace the file by hand.
For a Drive-backed write, claim remote persistence only when the returned synchronization state is `synced`. A successful local Core write or request receipt does not by itself prove that Drive has synchronized it. If synchronization is pending or failed, retain the source and report the actual state. Do not retry into a different mount to make a failed sync appear successful.
## A safe choice in practice
- Choose local storage when one person needs a file on that machine and explicitly owns its filesystem location.
- Choose a Vault mount when the intended account and organization role provide the required access; verify the exact top-level mount path.
- Choose Drive when the authorized Google account and mounted folder are the intended shared source; verify personal versus Shared Drive scope.
- For any remote destination, inspect its key and access report, use a current revision/hash, and read back the result. Report provider sync only when the provider confirms it.
## Limits and evidence
These paths have different trust boundaries. A public web renderer is an ephemeral document-rendering service, not a mounted storage location or sync target. An iOS Vault/Drive document is a read-only downloaded copy in the reviewed client flow; it does not imply editing the provider's file. Exact role, OAuth, and synchronization behavior is determined by the currently deployed service and provider response, not this guide.
[[src-vault-contract]]
[[src-drive-permissions]]
[[src-core-history]]
[[src-client-boundaries]]
::end
SRC src-vault-contract
t Vault authorization and storage contract
d Internal Vault service contract reviewed for account identity, mount roles, path constraints, conditional writes, and synchronization; not a public service-availability claim.
ref https://github.com/clab-one/thegram-vault/blob/main/docs/SPEC.md
SRC src-drive-permissions
t Google Drive permissions model
d Google Drive API documentation on file permissions and access behavior.
ref https://developers.google.com/drive/api/guides/about-permissions
SRC src-core-history
t Core history and conditional-write contract
d Thegram Core source-history contract for History/6 revisions, CAS writes, state replay, and journal provenance.
ref https://github.com/clab-one/thegram-format/blob/main/spec/source-history-render.md
SRC src-client-boundaries
t Client storage boundary sources
d Internal Desktop, iOS, local agent, and cloud MCP sources reviewed for local connection permissions and read-only downloaded client flows.