Skip to main content
Locality is built around one rule: when a task can be expressed as a file operation, the file operation is the natural path.

​
Notion shape

Notion pages are directories. The body of the page is page.md.
A child page lives inside its parent page directory. The containing directory determines the remote parent. Do not infer the remote parent from title search results.

​
Moves and renames

Moving a page directory is the filesystem way to change the remote parent. Renaming the directory changes the title. A single mv can do both:
Locality records that as one pending entity move, not as unrelated delete and create operations. For connectors that support entity moves, push applies the parent change and final title through the connector’s native move/update APIs and then reconciles the page at its final path. When a remote rename or parent move is observed, Locality moves clean local projections atomically. If any local file in the affected subtree is dirty or conflicted, Locality leaves that subtree in place and reports review needed instead of moving pending local work.

​
Databases

A Notion database is projected as a directory.
_schema.yaml describes the database properties Locality can validate before push. Row pages are normal page directories with page.md; their frontmatter includes supported row properties. When the UI says database, it means a Notion database-like object, not Locality’s internal SQLite database.

​
Google Docs shape

Google Drive folders become directories. Google Docs documents become page directories containing page.md.
Non-Google-Docs Drive files are ignored by the V1 connector.

​
Frontmatter

Locality uses YAML frontmatter for identity and source metadata.
Preserve existing Locality frontmatter unless the task is explicitly about identity, migration, or rendering. Agents should edit the body and supported user-facing properties, not the generated identity block.

​
Stubs and hydration

Large workspaces do not require a full first sync. Locality can list many objects before every body is downloaded.
  • stub: Locality knows the object exists, but the body is not ready locally;
  • hydrated: page.md content is available and tracked;
  • dirty: the local file changed from the last synced shadow;
  • conflicted: Locality found unresolved conflict markers or an unsafe merge state.
Opening, locating, pulling, or editing a file can prioritize hydration for that path.

​
Media

Downloaded media lives under .loc/media/ at the projection root.
This keeps content directories readable while giving agents and editors stable local files for images, PDFs, audio, video, and other supported media.

​
Local create

Create a new page with the CLI:
Or manually create the directory shape:
New local pages do not have a loc: identity block until Locality pushes them and reconciles the remote object.