Skip to main content
The desktop app is the fastest path for humans. It handles connection setup, workspace mounting, Finder access, pending changes, and Live Mode.

​
First run

The first-run flow guides the user through the same core setup path:
1

Connect Notion

Start with Notion. OAuth opens in the browser and lets you choose the pages or workspace content Locality can access.
2

Create or verify the local folder

Locality prepares the local workspace folder and registers the native file provider when that projection mode is used.
3

Open the folder

The app shows the mounted folder path and opens it for Finder, editors, terminals, and agents.
4

Find one file

Paste a Notion URL or search by title/path to find the local page.md path.

​
Home

Home shows the daily workspace state:
  • connected source state;
  • mounted folder state;
  • pending files that need attention;
  • a place to paste a page URL or search for a file.
Common actions are:
  • open mounted folder;
  • copy path;
  • reveal in Finder;
  • locate page;
  • review pending changes.

​
Mounts and Files

Mounts and Files are closely related, but they answer different jobs.
  • Mounts are connected workspaces and their local roots.
  • Files are the current local targets a user or agent may work on.
Use Mounts when you need the inventory of registered roots. Use Files when you need current paths, recent files, search results, pending files, or conflicted files.

​
Pending changes

Pending changes are local edits that can affect the remote app. The desktop pending screen provides actions for:
  • review plan;
  • push safe changes;
  • pull remote update;
  • restore local file;
  • open file;
  • copy path.
undo is not a general safety button after a push. Use CLI journal undo only when the target push has a journal-backed reverse plan that still applies.

​
Live Mode

Live Mode is the desktop background sync loop. Use it when users want clean hydrated pages checked for remote changes and safe local edits pushed continuously. Keep it conservative:
  • push only safe plans;
  • pull clean remote updates;
  • pause for conflicts, unsupported operations, destructive changes, or review-required plans;
  • scope controls per file or active target when possible.
Agents should not run routine push/pull commands after every edit when Live Mode is handling the file. They should inspect status only when Locality reports attention needed.

​
Diagnostics

Start with:
On macOS, remember there are three relevant layers:
  • the CloudStorage-visible folder;
  • the File Provider content cache;
  • Locality daemon state.
If those disagree, restart the provider and check status before deleting any visible files.