Cloud Sync

Overview

HQ Cloud Sync enables bidirectional syncing between your local HQ folder and cloud storage (S3), with a mobile-friendly PWA dashboard for access from any device.

Local HQ  ←→  Sync Daemon  ←→  S3 Bucket  ←→  PWA Dashboard
              (chokidar)       (AWS)          (hq.indigoai.com)

Setup

Install the CLI

npm install -g @indigoai-us/hq-cli

Authenticate

hq sync init

This opens your browser for IndigoAI sign-up/sign-in. After authentication:

Your account is provisioned
An S3 bucket is created for your files
Credentials are stored locally at ~/.hq/credentials.json

Start Syncing

hq sync start

This starts a background daemon that watches your HQ directory for changes and syncs them to S3 in real-time.

Commands

Command	Description
`hq sync init`	Authenticate and provision cloud storage
`hq sync start`	Start the background sync daemon
`hq sync stop`	Stop the daemon
`hq sync status`	Show sync health (running, last sync, file count, errors)
`hq sync push`	Force upload all local changes
`hq sync pull`	Force download all cloud changes
`hq sync doctor --reconcile-conflicts`	Clean up legacy `.conflict-*` twin files (dry-run; add `--yes` to apply)
`hq access <path-or-query>`	One file missing or locked? Reports never-existed / not-synced / no-access, fetches it when you have access, otherwise asks the owner for a grant (see hq-share)

How Sync Works

File watcher monitors your HQ directory using chokidar
Changes are debounced (2-second quiet period) and batched
File hashes are computed and compared against the sync journal
Changed files are uploaded to S3 at s3://{bucket}/hq/{path}
The journal (.hq-sync-journal.json) is updated with new hashes

Conflict Resolution

When the same file changed on both sides, sync picks a winner without leaving anything next to the live file:

If both copies carry a frontmatter version: number, the higher version wins.
Otherwise the newer modification time wins.
Identical bodies keep the local copy; a true tie keeps the cloud copy.

The losing copy is parked out of tree under .hq/conflict-backups/ (never synced), and the decision — winner, reason, and both versions — is recorded on the matching row in .hq-conflicts/index.json. The journal still tracks hash, size, timestamp, and sync direction for every file, and Git handles content-level conflicts for version-controlled files.

Cleaning up legacy conflict twins

Older versions of the engine wrote a sibling <file>.conflict-<timestamp>-<machine>.<ext> twin beside the live file. hq sync doctor --reconcile-conflicts walks your HQ root and prints a plan for every twin it finds; add --yes to apply it (use --hq-root <path> to point at a different HQ):

A twin replaces the live file only when its frontmatter version: is strictly higher than the live file’s. Otherwise the live file stays and the twin is parked.
Twins whose live file no longer exists are parked, never restored, and listed for manual review.
Symlinked or unreadable twins are skipped and listed for manual review.

Everything parked lands in .hq/conflict-backups/, so no content is destroyed. The command is local-only and needs no cloud sign-in.

What Syncs

Synced	Not Synced
`workspace/`	`repos/` (use git)
`knowledge/`	`node_modules/`
`companies/`	`.git/`
`.claude/`	Build artifacts (`dist/`)
`workers/`	Files > 50MB
`projects/`	Paths in `.hqsyncignore`

.hqsyncignore

Create a .hqsyncignore file in your HQ root to exclude additional paths (gitignore syntax):

# Exclude large data files
companies/*/data/exports/*.csv

# Exclude temp files
workspace/scratch/

Mobile Access

Once sync is running, access your HQ at hq.indigoai.com:

File browser — Navigate your HQ directory structure
Markdown viewer — Read knowledge files, reports, and threads
Quick actions — Approve social drafts, add notes
Search — Filter files by name and path

The PWA can be installed on your phone’s home screen for app-like access.