From 4524281094f548a555f9e7a827604c946416f0b6 Mon Sep 17 00:00:00 2001
From: Aboo <a.azarnoush@pap.dev>
Date: Sun, 17 May 2026 23:00:40 +1000
Subject: [PATCH] docs: Add sync documentation to README files

- Users need to know how to keep their workbench up to date
- Added Syncing Your Workbench section to top-level README
- Added Sync section with flag table and examples to CLI README
- Documented sync-specific error messages in CLI README

Delivers #37
---
 README.md                        | 16 ++++++++++++++++
 packages/workbench-cli/README.md | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/README.md b/README.md
index 02935f6..9af96d1 100644
--- a/README.md
+++ b/README.md
@@ -161,6 +161,22 @@ Authentication and setup instructions vary by backend — refer to the relevant
 
 The setup wizard optionally indexes your repositories with [ck](https://beaconbay.github.io/ck/) — a hybrid code search tool by [BeaconBay](https://github.com/beaconbay) that fuses lexical (BM25/grep) precision with embedding-based recall, so you can find the right code even when the exact keywords aren't there.
 
+
+## Syncing Your Workbench
+
+The workbench is periodically updated with improvements to slash commands, skills, schemas, and documentation. To fetch the latest managed files from the source repository, run `workbench --sync` from your workbench root:
+
+```bash
+workbench --sync
+```
+
+Sync clones the source, applies the configured file paths (`.opencode/`, `.workbench/schemas/`, `README.md`), and auto-commits changes with a chore message. An interactive confirmation prompt lets you review and abort before any files are overwritten.
+
+Sync requires an initialized workbench (created via `workbench --init`) and a clean working tree. Run periodically to stay updated.
+
+See [packages/workbench-cli/README.md](packages/workbench-cli/README.md) for full flag documentation and troubleshooting.
+
+
 ## Development Setup
 
 To set up the workbench CLI for local development:
diff --git a/packages/workbench-cli/README.md b/packages/workbench-cli/README.md
index 996c987..86b92e1 100644
--- a/packages/workbench-cli/README.md
+++ b/packages/workbench-cli/README.md
@@ -84,6 +84,17 @@ These flags work with both `--init` and standalone usage:
 
 > **What is ck?** [ck](https://beaconbay.github.io/ck/) is a hybrid code search tool by [BeaconBay](https://github.com/beaconbay) that fuses lexical (BM25/grep) precision with embedding-based recall, so you can find the right code even when the exact keywords aren't there.
 
+
+## Sync
+
+Fetches managed workbench files from the source repository and merges them into your local workbench. Sync clones the source, reads the configured `sync.paths`, prompts for confirmation, and auto-commits any changes. This keeps your workbench up to date with upstream improvements without manual file tracking.
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--sync` | Sync workbench files (`.opencode/`, `.workbench/schemas/`, `README.md`) from the source repository | `false` |
+
+Sync requires an initialized workbench and a clean working tree. Run `workbench --sync` from your workbench root.
+
 ## Examples
 
 ```bash
@@ -107,6 +118,8 @@ workbench --org myorg --code-repository https://github.com/myorg/backend
 
 # Interactive setup (existing repo)
 workbench --tui
+# Sync managed files from the source workbench
+workbench --sync
 ```
 
 ## What the setup wizard does
@@ -129,6 +142,10 @@ Afterwards, `.workbench/config.yaml` is written with the selected configuration.
 | `Remote creation failed` | `gh repo create` failed | Check `gh auth login` and org permissions |
 | `gh CLI is not authenticated` | `gh auth` not set up | Run `gh auth login` |
 | `Invalid name "X"` | Bad characters in name | Use only alphanumeric, `-`, `.`, `_` |
+| `No .workbench/config.yaml found` | Workbench not initialized | Run `workbench --init` first |
+| `No source.repository found in config` | Config predates sync feature | Re-initialize workbench |
+| `Working tree is not clean` | Uncommitted changes present | Commit or stash changes first |
+| `No sync.paths found in source` | Source workbench doesn't support sync | Contact source maintainer |
 
 ## Development