@gram 2
doc blog-desktop-guide
t Set up Thegram Desktop and connect a storage source
d A cautious walkthrough from opening a local document to separately authorizing an account or Drive connection.
tag guides
view document

::rich
# Start with a file you control

The Mac app is the direct route when you want to inspect and edit .gram documents in a native workspace. Begin by following the install instructions linked from the product site and opening a document from a location you chose. The desktop README describes a local mode that works without server requests; signing in is a separate choice. This distinction is useful: a local document workflow should not be described as requiring a Vault account, and signing in should not be treated as automatically granting access to a separate storage provider.

Before connecting anything, decide which copy is canonical. A local folder, personal Drive folder, or mounted Vault may have different ownership and synchronization behavior. Do not move a source file into a cloud account merely to make the UI appear populated. The app’s format boundary says .gram and its history are canonical; derived search, graph, and vector data can be rebuilt.

## Open and read

Use the native file-open flow to choose a .gram file or folder. The desktop design uses a document list, central content, an inspector, and graph/history navigation. A selected historical revision is a read-only view; it is not a direct rollback. To make an intentional change based on old text, return to the current state and edit or copy the desired material into a new change. If Core reports a stale write or invalid history, preserve the original file and resolve that condition rather than replacing it with a hand-edited reconstruction.

A useful first check is whether the title, typed records, relationships and rich body appear as expected. A graph edge expresses a stored relation; visual proximity or a search result can be a derived candidate, not a fact written into the file. Likewise a status label or scope field describes data but does not change its permission model.

## Connect a Thegram account or Drive

Desktop documentation separates account authentication from storage mounting. Account sign-in uses the configured identity flow. Google Drive connection is separately consented to, and personal Drive and company Shared Drive flows are distinct. A logged-in user may see a company Vault mounted according to their role; a Drive connection is not simply the account login screen under a different name. Read the prompts carefully and confirm which account and folder are being connected.

After authorizing a source, inspect the displayed path and document identity before editing. Remote storage synchronization can introduce stale states or conflicts; the desktop README says agent imports should preserve stale conflict rather than silently overwrite. If two copies disagree, retain both until the application’s conflict workflow identifies the intended current file. A self-hosted connection may expose an optional advanced mTLS route, but that is not a prerequisite for ordinary local use.

## Example workflow

Suppose you have a local `launch-review.gram` and want to read team evidence. First open the local file and identify its current revision and any link to evidence. If shared material lives in a team Vault, sign in only if needed, then verify that the expected Vault appears under the correct identity and role. If a personal Drive is the actual source, use its separate consent flow and inspect that folder instead. Read the decision and its evidence together. For a new decision, create a separate decision record and link the supporting evidence; do not overwrite an old accepted fact to make a conclusion look historically true.

## Tradeoffs and limits

Local work needs no account or network, but does not share files across devices. Remote storage adds identity, consent, organization roles, sync, and conflict handling. The separate sandboxed Mac App Store edition is in preparation, with App Store entitlements, a privacy manifest, and installer-signing work, but no release is evidenced. Its inherited README and acceptance retain the Source-r2 TEST/UNRESOLVED-license boundary. The public 0.9.6 README also marks Core licensing UNRESOLVED; notarization is not license review.

For exact screen names and supported behavior, read the current Desktop README, `docs/ui-design.md`, and `docs/architecture.md`; for server-backed operations read the Vault specification and current install guide. This guide describes decision points, not an account grant or verified live login session.

## Install and enable agent access

Thegram requires an Apple silicon Mac (M1 or later) and macOS 26 or later. Download Thegram.dmg from the official install page, open it, drag Thegram to Applications, eject the disk image, and open the app from Applications. Account sign-in is optional; the install guide says local files can be used without an account. To let a coding agent read and write project memory, open Thegram > Settings… (⌘,), choose Agent Connections, set Agent Access to Read and Write, and wait until Connection says Running. Install the agent from the Agent Apps section or follow the command for that agent. Node.js 22 or later is required. The connection works on this Mac while Thegram is open; choose Read instead if the agent should not write. Codex asks once whether to trust plugin hooks. Grant write access only to an agent and project you intend to authorize.

## Sources

Instructions are based on Desktop README and design/architecture docs, installation materials, Vault contract, and the App Store edition’s preparation status and inherited README/acceptance boundary.

@ids
15 setup-heading
setup-heading-1 setup-heading-text
16 setup-paragraph
setup-paragraph-1 setup-text
17 15
18 16
::end

SRC desktop-readme
d Internal source reviewed at revision b6c769a0365166ba943d8501abb639bd09c00c6e (main: README.md; docs/ui-design.md; docs/architecture.md); not publicly available.
t Desktop application README
SRC desktop-ui
d Internal source reviewed at revision b6c769a0365166ba943d8501abb639bd09c00c6e (main: docs/ui-design.md); not publicly available.
t Desktop UI design
SRC desktop-architecture
d Internal source reviewed at revision b6c769a0365166ba943d8501abb639bd09c00c6e (main: docs/architecture.md); not publicly available.
t Desktop architecture
SRC desktop-appstore-readme
d Internal source reviewed at revision b3389ce165fa80d46873df3f4fb6951d98fbeb60 (main: README.md; inherited from the desktop line); not publicly available.
t Sandboxed App Store edition README; not release evidence
SRC desktop-appstore-acceptance
d Internal source reviewed at revision b3389ce165fa80d46873df3f4fb6951d98fbeb60 (main: docs/acceptance.md; inherited from the desktop line); not publicly available.
t App Store acceptance text; not release evidence
SRC vault-spec
d Internal source reviewed at revision a193a190141054e07b268f0a38489467db82a335 on branch master (README.md; docs/SPEC.md); not publicly available.
t Vault service contract
SRC website-install
t Product installation instructions
ref https://thegram.one/install/
K local-workflow
t Local file workflow is independent of account login
d Desktop documents local mode without server requests; authentication and storage mounting are separate choices.
source desktop-readme
supports storage-choice
K storage-choice
t Choose identity and storage separately
d Account sign-in, Google Drive consent, company Vault role and local files represent distinct access paths.
source desktop-architecture
source vault-spec

K release-status
d The sandboxed edition is in preparation; inherited README/acceptance text from the desktop line retains Source-r2 TEST/UNRESOLVED-license status, not an App Store release report.
source desktop-appstore-readme
source desktop-appstore-acceptance
t The in-preparation sandboxed edition has no evidenced App Store release


@gram-history 6
@rev 0 2026-10-12T08:08:28.687Z - 081ceddaff05212dda9fcccaba22d5807da49968b5bb9a818a95d990ba1762c0
@rev 1 2026-10-12T08:11:57.098Z - req=blog-desktop-guide-agent-access-20261012 dig=63c14b849130ed27 2097ded8d302b4c9368cbc6c277e4b9d7ec2fbc1838138cea8804f8f56fbde9e
@@ 36 4 0
@@ 43 8 0
@rev 2 2026-10-12T08:13:38.847Z - req=blog-private-source-note-desktop-guide-20261012 dig=13086c356275b73d 547f2b1f1261db97115fb6d9935474187f074e3f5f64bf735a14505df19f618a
@@ 69 1 0
@@ 71 0 1
ref https://github.com/clab-one/thegram-vault/blob/main/docs/SPEC.md
@rev 3 2026-10-12T08:14:42.059Z - req=blog-editorial-knowledge-desktop-guide-20261012 dig=3eb1fce030b10721 69cd856dfac2b137c67d01ad85c4c901288346b66e745d18c590ccdb13a0fdc9
@@ 84 2 2
X release-status
t Test builds do not establish official release readiness
@@ 89 1 0
@rev 4 2026-10-12T08:15:32.743Z - req=blog-private-source-paths-desktop-guide-20261012 dig=baefb29d26e889d6 f9891ce07695ec1a08852691150895a3a28a48f4325f13a5f123450bef3efc9a
@@ 69 1 1
d Internal source reviewed at revision a193a190141054e07b268f0a38489467db82a335; not publicly available.
@rev 5 2026-10-12T08:40:15.725Z - req=platform-corrections-desktop-guide-20261012 dig=919f2f3cd6f2ee99 kind=SourceImported e37197e9802ff00ef6a888862ba53ff1627098819d68ad7459f2d6494f3d3ccb
@@ 32 1 1
Local mode reduces dependence on accounts and network availability, but it does not automatically share a file across devices. Remote storage may be convenient, but account identity, provider consent, organization roles, sync state and conflict handling become relevant. Do not infer that every deployment supports every provider, or that every desktop checkout has the same release status. The separate `thegram-desktop-appstore` checkout currently identifies itself as TEST-only with unresolved Core licensing; that is not the public release line described by `thegram-desktop` README.
@@ 38 1 1
Download Thegram.dmg from the official install page, open it, drag Thegram to Applications, eject the disk image, and open the app from Applications. Account sign-in is optional; the install guide says local files can be used without an account. To let a coding agent read and write project memory, open Thegram > Settings… (⌘,), choose Agent Connections, set Agent Access to Read and Write, and wait until Connection says Running. Install the agent from the Agent Apps section or follow the command for that agent. Node.js 22 or later is required. The connection works on this Mac while Thegram is open; choose Read instead if the agent should not write. Codex asks once whether to trust plugin hooks. Grant write access only to an agent and project you intend to authorize.
@@ 54 1 0
@@ 56 0 1
ref https://github.com/clab-one/thegram-desktop/blob/main/README.md
@@ 57 1 0
@@ 59 0 1
ref https://github.com/clab-one/thegram-desktop/blob/main/docs/ui-design.md
@@ 60 1 0
@@ 62 0 1
ref https://github.com/clab-one/thegram-desktop/blob/main/docs/architecture.md
@@ 63 2 2
t Desktop App Store test-line README
ref https://github.com/clab-one/thegram-desktop-appstore/blob/main/README.md
@@ 66 2 2
t App Store line acceptance and release boundary
ref https://github.com/clab-one/thegram-desktop-appstore/blob/main/docs/acceptance.md
@@ 73 1 1
ref https://thegram.one/install/agents.md
@@ 90 1 1
supports local-workflow
@rev 6 2026-10-12T08:44:48.022Z - req=platform-corrections-desktop-guide-trim-20261012 dig=67e4afb3e9f50bbb kind=SourceImported 17c93006d3057920d43535779ca0b5590ab11156713213d419e17addcd6ab50d
@@ 32 1 1
Local mode reduces dependence on accounts and network availability, but it does not automatically share a file across devices. Remote storage may be convenient, but account identity, provider consent, organization roles, sync state and conflict handling become relevant. Do not infer that every deployment supports every provider, or that every desktop checkout has the same release status. The separate sandboxed Mac App Store edition is in preparation, with App Store entitlements, a privacy manifest, and installer-signing work; no App Store release is evidenced. Its README and acceptance file are inherited from the desktop line and retain a Source-r2 TEST/UNRESOLVED-license boundary, not a statement of App Store release status. The public 0.9.6 README also records Core license status as UNRESOLVED; notarization does not imply license review.
@rev 7 2026-10-12T08:46:16.032Z - req=platform-source-notes-desktop-guide-20261012 dig=bb638e4e2b6e5b1e kind=SourceImported ca825ec2294a6d8232c442e4b53440aafaa7fe6415265a65f1d5a3140f974110
@@ 69 1 1
d Internal source reviewed at revision a193a190141054e07b268f0a38489467db82a335 (README.md; docs/SPEC.md); not publicly available.
@rev 8 2026-10-12T08:56:16.352Z - req=platform-final-fixes-desktop-guide-20261012 dig=7fd3e6d5f7d0a3e2 6f0dd09a5aa25afc9b5f9c3c987e6fc864088dcdb6ea367a26c60547113d1324
@@ 42 1 1
Instructions are based on Desktop README and design/architecture docs, installation materials, Vault contract, and App Store test-line acceptance status.
@@ 86 1 1
d The App Store checkout says official release remains blocked by unresolved Core licensing and incomplete acceptance.
@@ 89 1 1
t Test builds do not establish official release readiness