Skip to main content
Use Locality like a local workspace over a remote source of truth. The fastest workflows are narrow, path-based, and reviewable.

​
Start with one real workspace

Mount the workspace or page tree where work actually happens.
Then use the desktop locate input for a known Notion URL/title, or browse the mounted folder to find the specific file:
Avoid creating many one-off mounts for individual pages unless you are testing or isolating a small project.

​
Give agents exact file targets

Agents perform better with concrete paths than broad app instructions.
This keeps the task inspectable and avoids accidental broad edits.

​
Keep edits scoped

Prefer commands on one file or a small directory:
Broad workspace pushes are harder to review and easier to misinterpret.

​
Preserve identity metadata

Do not edit generated Locality identity fields unless the task is explicitly about identity or migration. Leave these alone unless you know why they must change:
  • loc: frontmatter;
  • ::loc{...} directives;
  • _schema.yaml;
  • AGENTS.md;
  • CLAUDE.md.
Those fields let Locality map Markdown back to the correct remote object.

​
Use Live Mode for routine safe sync

Live Mode is useful when a file is clean, hydrated, and actively being edited. Expect it to pause for:
  • conflicts;
  • unsupported operations;
  • destructive changes;
  • remote drift that needs review;
  • connector or provider errors.
When Live Mode pauses, inspect the narrow path:

​
Pull remote changes before pushing stale work

If Locality reports remote_update_available, pull the file before pushing:
If conflict markers appear, resolve the file to the final intended content and remove every marker line before pushing.

​
Diagnose before deleting visible files

On macOS File Provider and other virtual projections, the visible file, provider cache, and daemon state can drift. Before deleting or moving a suspicious folder:
If the tracked path moved, check whether the old visible path has local-only edits before removing it.

​
Use OKF export for portable context

Export when an agent, search system, or review process needs a clean portable bundle instead of live app access.
OKF export is read-only with respect to the remote app.

​
Keep the review loop simple

The most reliable loop is:
1

Find

Search or locate the target file.
2

Edit

Human or agent edits mounted Markdown.
3

Review

Run loc status and loc diff on the narrow path.
4

Sync

Push safe changes or let Live Mode handle the file when appropriate.