# Comment.io — Local Sync Files

Use this when you need to inspect the local ~/Comment Docs mirror, understand what it syncs, or check whether local projections are writable on this device. For the concise start page, fetch https://comment.io/llms.txt.

## Local sync files

The current local sync product mirrors Markdown projections under `~/Comment Docs`, read-only by default. It syncs the declared scope into `My Files/`, `Shared With Me/`, `Team Wiki/`, and `Botlets/<owner>/<bot>/brain/` folders, and writes public agent docs into `_Comment.io Docs/`. Local runtimes using this device are trusted with read access to the configured sync root. Unsupported library sections are reported by `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync status --json`; do not assume they are mirrored.

Start with one exact saved computer account for this origin. Reuse the account name already selected by setup. If none is saved yet, run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME -u COMMENT_IO_ENV -u COMMENT_IO_BASE_URL -u COMMENT_IO_STAGING_BASE_URL comment auth login --origin 'https://comment.io' --account <owner-handle>`, replacing `<owner-handle>` with the human account you expect to approve; its final `Added account NAME` or `Selected account NAME` line supplies the exact saved `NAME`. Replace `your-saved-account` once with that saved name in every sync command below. Keep the same exact `--origin` / `--account` tuple and omit `--home`: the registry resolves the account's real home, including a secondary account's scoped home. Never use an ambient active account when more than one account is saved for the origin.

With that exact saved account, start with `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync status --json`. Treat sync as configured only when the JSON says `"configured": true` and `"baseUrl"` matches this origin; then skip login and run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync once`. Otherwise run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync login`: the selected account's pairing provisions the sync credential with no second browser approval; only an unpaired or different-origin account falls back to browser approval. Then run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync once`. For persistent, always-fresh sync, run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync enable` and install or run the Comment.io daemon with `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME -u COMMENT_IO_ENV COMMENT_IO_BASE_URL='https://comment.io' COMMENT_IO_STAGING_BASE_URL='https://comment.io' comment --production bus install --home "${COMMENT_IO_HOME:-$HOME/.comment-io}"` or `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME -u COMMENT_IO_ENV COMMENT_IO_BASE_URL='https://comment.io' COMMENT_IO_STAGING_BASE_URL='https://comment.io' comment --production bus run --home "${COMMENT_IO_HOME:-$HOME/.comment-io}"`; the sync worker runs inside that daemon and, by default, the live WebSocket path pushes each change to your local files within seconds. Enabling sync turns on the live WebSocket by default; if you don't want WebSockets, run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync enable --no-live` (alias `--poll`) to use periodic polling as the backup instead. Live is on by default; a deployment can disable the live stream server-side (`ENABLE_LIBRARY_SYNC_LIVE="false"`), in which case the daemon falls back to periodic sync and reports `COMMENT_IO_LOCAL_SYNC_FRESHNESS=periodic`. Use `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync live disable` to turn off only the live path on this computer while keeping periodic background sync enabled. The fresh Go sync path does not require Node, npm, tsx, FUSE, macFUSE, or libfuse.

Each synced Markdown file starts with a hidden `comment.io:projection` HTML comment containing the token-free canonical URL, slug, revision, and body hash. Ignore that header when constructing API edit `old_string` values; use only the canonical body after the header. Check `COMMENT_IO_LOCAL_SYNC_MODE` for whether local edits sync: `read-only-projection` (the default) or `read-write-projection` (the human enabled write sync on this device).

In `read-only-projection` mode, local files are not an upload surface — do not edit them as a way to modify Comment.io. Local edits are preserved under `~/.comment-io/sync/recovery` and the canonical server version is restored by live sync when enabled and available, or by the periodic fallback. Use `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync conflicts` and `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync recover <path|recovery-id>` to inspect, copy, diff, or discard preserved local text.

In `read-write-projection` mode (`env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync write enable`, an explicit browser consent; `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync write disable` turns push off and keeps the key), **My Files** projections are writable: editing the file body below the projection header syncs to the cloud doc as a normal collaborative edit, and the file re-materializes to the server's canonical Markdown after each push — expect formatting to normalize and keep the header line intact. Concurrent cloud edits merge when they touch different text; when both sides edit the same characters, the merge keeps both texts adjacent in the doc body (cloud text first, then the local edit) rather than dropping either — review the merged sentence afterward. Comment threads on untouched text survive a push; if a local edit removes commented text, those threads become visible orphans and a system comment on the doc reports the detachment. Write sync covers My Files only: `Shared With Me/`, `Team Wiki/`, and `Botlets/` brains stay read-only, and sync roots configured with frontmatter (OKF) or Obsidian-style links are not writable in v1. Frontmatter is never pushed. For revision-checked edits with a response payload, prefer the REST API; file edits are eventually consistent.

Local deletion of a clean projection does not delete the remote document; the next authoritative sync repairs it. To remove remote content, use Comment.io. To stop local mirroring, revoke the device in Settings or run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync logout`; to remove verified clean local projections too, run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' sync logout --purge-local`.

When `COMMENT_IO_LOCAL_SYNC_ROOT` is set, prefer local filesystem reads for broad inspection: `rg "term" "$COMMENT_IO_LOCAL_SYNC_ROOT"` and `sed -n '1,160p' "$COMMENT_IO_LOCAL_SYNC_ROOT/Team Wiki/Doc.md"` or `"$COMMENT_IO_LOCAL_SYNC_ROOT/My Files/Doc.md"`. Keep the current task, comm, and runtime-provided Comment.io tools first. When `COMMENT_IO_LOCAL_DOCS_ROOT` is set, use `$COMMENT_IO_LOCAL_DOCS_ROOT/reference.txt` only for exact REST or recovery detail and `$COMMENT_IO_LOCAL_DOCS_ROOT/llms.txt` only as the fallback startup index. If the local mirror is missing, stale, or does not contain the document, fall back to `GET /docs/{slug}`.

Use the REST API or the web UI to create, edit, resolve, accept, reject, or reply to comments and suggestions. API write responses return the canonical `markdown` and `revision`; after a write, live sync can refresh the projection within seconds when the daemon is online and the server live stream is enabled; otherwise the periodic fallback refreshes it. Fall back to `GET /docs/{slug}` if the local cache has not caught up. The local mirror is for search, indexing, context, inspection, and — in `read-write-projection` mode — direct My Files edits; it has no mount, commit, relink, or sidecar-edit contract.