Syncing Documentation

The sync_docs tool detects changes in your documentation and syncs them with the backend efficiently.

Basic Usage

Sync my documentation changes

Or with dry-run to preview:

sync_docs({ "dryRun": true })

Parameters

Parameter	Type	Required	Default	Description
publishableKey	string	No	env var	Cyborg publishable key
docsDir	string	No	./cyborg-docs	Documentation directory
dryRun	boolean	No	false	Preview changes without uploading

Smart Change Detection

The sync process uses a 3-pass algorithm to minimize API calls:

Pass 1: Local Hash Comparison (Fast)

• Reads all local files
• Calculates current content hashes
• Compares against stored hashes in state file
• Identifies: added files, potentially modified files, unchanged files

Pass 2: Backend Comparison (Only Changed Files)

• Fetches backend hashes only for potentially modified files
• Compares to confirm actual changes
• Minimizes API calls by skipping unchanged files

Pass 3: Upload/Update

• Uploads new files
• Updates modified files
• Reports deleted files (in state but missing locally)

Dry Run Output

{
  "success": true,
  "dryRun": true,
  "changes": {
    "toUpload": ["new-guide.md"],
    "toUpdate": ["getting-started.md"],
    "unchanged": ["api/useChat.md", "api/useCyborg.md"],
    "deleted": ["old-file.md"]
  }
}

Full Sync Output

{
  "success": true,
  "uploaded": [{ "path": "new-guide.md", "documentId": "doc_xyz789" }],
  "updated": [{ "path": "getting-started.md", "documentId": "doc_abc123" }],
  "unchanged": 2,
  "deleted": ["old-file.md"]
}

Workflow

1. Preview Changes

sync_docs({ "dryRun": true })

Review what will be uploaded, updated, or detected as deleted.

2. Apply Changes

sync_docs()

Upload new files and update modified files.

3. Handle Deletions

Deleted files (in state but missing locally) are reported but not automatically removed from the backend. Use delete_doc to remove them if needed.

Examples

Preview Changes

What documentation changes need to be synced?

Sync After Code Changes

I've updated the API docs, sync them to Cyborg

Sync Specific Directory

sync_docs({
  "docsDir": "./documentation"
})

Best Practices

1. Always dry-run first when unsure: sync_docs({ dryRun: true })
2. Commit state file to version control for team synchronization
3. Run after code changes to keep docs in sync with implementation
4. Review deleted files - they may need to be explicitly removed

State File Updates

After sync, .cyborg-state.json is updated with:

• New document IDs for uploaded files
• Updated hashes for modified files
• Updated lastSyncedAt timestamp

Handling Conflicts

If a file was modified both locally and on the backend:

• Local changes take precedence
• The file is uploaded as an update
• Backend version is overwritten

Next Steps

• Tools Reference - All sync options
• Upload Docs - Initial upload