Update CLI ReadMe for Sync

[aboo]

Document workbench --sync in README files

Description

PR #36 added the workbench --sync command — a 10-step flow that fetches managed files from the source workbench and merges them into the local workbench, with an auto-commit. The implementation is complete but the command is undocumented in both README files. This issue adds user-facing documentation for --sync in the root README.md and the CLI package README.md.

Context

Users who fork or clone the workbench repository need to stay in sync with upstream improvements (updated slash commands, skills, schemas, and README). The --sync command makes this seamless — it clones the source, applies configured sync.paths, and commits the result. Without documentation, users won't discover or understand this capability.

This is a documentation-only issue. No code changes. All sync implementation is already merged and committed in PR #36.

Requirements

Functional Requirements

• Add a ## Syncing Your Workbench section to the root README.md, placed between "Code indexing with ck" and "Development Setup"
  • Brief description of what --sync does (fetches upstream managed files to keep workbench current)
  • Mention that sync auto-commits changes with a chore message
  • Mention the interactive confirmation prompt before files are overwritten
  • One-line usage example: workbench --sync
  • Cross-reference link to packages/workbench-cli/README.md for full flag documentation
  • Note: must be run from an initialized workbench (created via workbench --init)
  • Note: "Run periodically to stay updated" (non-prescriptive guidance)
• Add a ## Sync section to packages/workbench-cli/README.md, placed after "Setup flags"
  • One-paragraph narrative explaining what sync does at a high level
  • Flag table (matching the "Init flags" / "Setup flags" pattern) with columns Flag | Description | Default
    • --sync — Sync workbench files (.opencode/, .workbench/schemas/, README.md) from the source repository — false
  • Note that sync auto-commits changes and prompts for confirmation before overwriting
• Add workbench --sync to the existing "Examples" section in the CLI README
• Add sync-specific error rows to the existing "Error scenarios" table in the CLI README:
  • 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

Non-Functional Requirements

• Follow the existing documentation style and formatting conventions of each README
• Flag table in CLI README must match the column structure (Flag | Description | Default) of existing tables
• Error table additions must match the existing Error | Cause | Resolution column structure

Current State

• Root README.md (188 lines): Sections include Getting Started, Folder Structure, Working on issues, Project Management, Code indexing with ck, Development Setup, etc. No mention of --sync anywhere.
• CLI README.md (166 lines): Has "Init flags" table and "Setup flags" table. --sync is absent from both. Has "Examples" section and "Error scenarios" table. No mention of sync anywhere.
• --help output (packages/workbench-cli/src/args.ts): Already includes --sync in USAGE, OPTIONS, and EXAMPLES blocks (lines 68, 83, 95). No changes needed here — this is explicitly out of scope.

Desired State

After this issue, a user reading either README will:

1. Discover that workbench --sync exists and understand what it does
2. Know the prerequisites (must be in an initialized workbench)
3. Know what to expect (confirmation prompt, file overwrites, auto-commit)
4. Know how to troubleshoot common errors
5. Be able to navigate from the root README to the CLI README for full flag details

Research Context

Keywords to Search

• sync — flag name and command; used in args.ts, sync.ts, settings.yml
• --sync — exact CLI flag format
• workbench --sync — usage string
• executeSync — main implementation function in packages/workbench-cli/src/commands/sync.ts
• sync.paths — configuration key in .workbench/settings.yml
• source.repository — config dependency in .workbench/config.yaml

Patterns to Investigate

• Flag table pattern in CLI README — "Init flags" and "Setup flags" use | Flag | Description | Default | three-column format. New sync table must match exactly.
• Section structure pattern in root README — h2 sections (##) with brief prose and no tables. New "Syncing Your Workbench" section should follow this style.
• Error table pattern in CLI README — uses | Error | Cause | Resolution | three-column format. Sync error rows must match.
• Cross-reference pattern — root README line 37 already links to CLI README with See [packages/workbench-cli/README.md](...) for full CLI documentation. New section should use a similar link.

Key Decisions Made

• Root README: New ## Syncing Your Workbench section inserted between "Code indexing with ck" and "Development Setup" — scope confirmed in Q&A
• CLI README: New ## Sync section after "Setup flags" with flag table + narrative paragraph — scope confirmed in Q&A
• Auto-commit behavior must be documented (users need to know sync creates a commit) — confirmed in Q&A
• Interactive confirmation prompt must be mentioned — confirmed in Q&A
• sync.paths configuration is NOT documented for end users — works out of the box — confirmed in Q&A
• --help output update, CONTRIBUTING.md update, sync.paths defaults, snapshot/rollback — all explicitly out of scope
• No code changes — documentation only

Environment Context

• Pathway mode: workbench
• ck CLI available: false (disabled in settings)
• PM tool: github-issues

Success Criteria

Automated Verification

• No verification steps applicable (documentation-only change)

Manual Verification

• Root README.md contains a ## Syncing Your Workbench section between "Code indexing with ck" and "Development Setup" with description, example, and cross-reference
• CLI README.md contains a ## Sync section after "Setup flags" with flag table and narrative paragraph
• CLI README "Examples" section includes workbench --sync
• CLI README "Error scenarios" table includes the four sync-specific error rows
• workbench --help output remains unchanged (out of scope)

[aboo]

Implementation Report: #37 - 2026-05-17T09-55-00Z

Report Version: v1
Report Status: Complete
Issue: #37 — Update CLI ReadMe for Sync
Pathway: 1 (workbench development mode)
Start status: none (no status-ticket label)
Entry step: ticket
Stop step: ticket

---

Steps

1. ticket — success

• Agent: ticketer
• Outcome: Issue structured with detailed functional/non-functional requirements. 2 rounds of Q&A (19 questions) exploring scope boundaries across both README files. 3 scope pushbacks confirmed out of scope: Getting Started mention, rollback docs, CI badges. No decomposition needed (single-concern documentation issue).
• Status: none → status:open
• Rationale: Clean documentation-only task with well-defined scope from the PR description. The sync implementation is fully committed (Adds CLI command to sync workbench files #36) — this ticket adds README documentation only.

Scope

In scope:

• Root README.md: New ## Syncing Your Workbench section with description, example, cross-reference to CLI README
• CLI README.md: New ## Sync section with flag table + narrative, example in "Examples" block, error rows in "Error scenarios" table

Out of scope:

• --help output (already done in args.ts)
• CONTRIBUTING.md updates
• sync.paths default changes
• Snapshot/rollback documentation
• Getting Started section modification
• CI badges

---

Workflow Outcome

Completed. Single step (ticket) ran with no failures. Issue is ready for research/plan/execute.

[aboo]

Research: #37 - Update CLI ReadMe for Sync

Metadata

• Date: 2026-05-17T22:22:02+10:00
• Branch: feature/36-add-sync-doc
• Commit: d3ecba8
• Repository: 36-add-sync-doc

Ticket Synopsis

Add user-facing documentation for workbench --sync (implemented in PR #36) to both the root README.md and the CLI package README.md. The sync command fetches managed files from the source workbench and merges them into the local workbench, with an interactive confirmation prompt and auto-commit. This is a documentation-only issue.

Summary

Both README files currently have zero mentions of --sync. The implementation in packages/workbench-cli/src/commands/sync.ts defines a 10-step flow with four distinct error states that need documenting. The --help output in args.ts already includes --sync in USAGE, OPTIONS, and EXAMPLES — no changes needed there. Four insertion points are identified with exact line numbers, and all flag details, table columns, and content requirements are catalogued.

Detailed Findings

1. Root README.md — Current State & Insertion Point

File: /README.md (188 lines)

The insertion point for the new ## Syncing Your Workbench section is between:

• Line 163: End of ## Code indexing with ck section (ends with blank line)
• Line 164: Start of ## Development Setup section

Existing section structure uses ## h2 headers with brief prose paragraphs and no tables. The new section should follow this style.

Cross-reference pattern (line 37):

See [packages/workbench-cli/README.md](packages/workbench-cli/README.md) for full CLI documentation.

The new section should use a similar link pattern to point to the CLI README for full flag docs.

Required content (per issue FRs):

• Brief description of what --sync does
• Mention auto-commit behavior (chore message)
• Mention interactive confirmation prompt
• One-line usage: workbench --sync
• Cross-reference link to CLI README
• Note: must run from initialized workbench
• Note: "Run periodically to stay updated"

2. CLI README.md — Current State & Insertion Points

File: /packages/workbench-cli/README.md (166 lines)

Insertion Point A — New ## Sync section (after line 86, before line 87):

• Line 86: End of ck note blockquote (part of "Setup flags" section)
• Line 87: ## Examples section

The new section should follow the existing flag table pattern:

Existing flag table pattern (lines 61-69, 75-83):

Flag	Description	Default

Flag details for sync table:

Flag	Description	Default
--sync	Sync workbench files (.opencode/, .workbench/schemas/, README.md) from the source repository	false

The narrative paragraph should explain: fetches upstream managed files, merges into local workbench, prompts for confirmation, auto-commits.

Insertion Point B — Example in "Examples" section (after line 110):

• Line 110: workbench --tui (last existing example)
• Line 111: blank line
• Line 112: ## What the setup wizard does

Add as the last example entry (with surrounding code fence if needed, or as an additional line in the existing code block ending at line 110). The existing examples are inside a single fenced code block (lines 89-110). Adding workbench --sync as the last line of that block (after line 109, before the closing ``` at line 110) is the cleanest approach.

Insertion Point C — Error rows in "Error scenarios" (after line 131):

• Line 131: Last row in existing error table
• Line 132: blank line

Existing error table pattern (lines 124-131):

Error	Cause	Resolution

Sync error rows to add:

Error	Cause	Resolution
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

3. Sync Implementation Behaviors

File: packages/workbench-cli/src/commands/sync.ts (227 lines)

executeSync() implements a 10-step flow:

Step	Line	Behavior
1	70-75	Validate .workbench/config.yaml exists
2	87-92	Validate source.repository in config
3	97-117	Check working tree is clean (any uncommitted changes = abort)
4	119-130	Interactive confirmation prompt with source info display
5	132-151	Shallow clone (depth 1) source repo into temp dir
6	155-162	Read sync.paths from source's .workbench/settings.yml
7	168-183	Merge each sync path (directory or file) into local workbench
8	185-216	Check for changes, auto-commit with chore: sync workbench from {repo}@{sha}
9	212	Clean up temp directory
10	215-218	Report completion

Key behaviors to document for users:

• Confirmation prompt: "Do you want to continue? [y/N]" — sync can be aborted safely
• Auto-commit: Creates commit with message chore: sync workbench from {repository}@{shortSha}
• Up-to-date detection: If no changes after merge, reports "Your workbench is already up to date"
• Warning: "This will overwrite local managed files" — customizations to managed paths are lost
• Sync paths: Currently .opencode/, .workbench/schemas/, README.md (from source's settings.yml)

Error states and messages:

Condition	Error Message	Line
No config.yaml	Error: No .workbench/config.yaml found. Run \workbench --init` first to initialise a workbench.`	73
No source.repository	Error: No source.repository found in .workbench/config.yaml. The workbench may have been initialised before this feature was available. Re-initialise to enable syncing.	89
Git status failure	Error: Failed to check git status. Ensure you are in a git repository.	106
Dirty working tree	Error: Working tree is not clean. Please commit or stash your changes before syncing.	114
No sync.paths in source	Error: No sync.paths found in the source workbench's .workbench/settings.yml. The source workbench may not support syncing yet.	160
General failure	Error: Sync failed: {err}	223

4. Flag Details from args.ts

File: packages/workbench-cli/src/args.ts (97 lines)

Flag definition (line 36):

sync: { type: "boolean", default: false },

Interface (line 17):

sync: boolean

--help output entries:

• USAGE (line 68): workbench --sync
• OPTIONS (line 83): --sync Sync workbench files from the source repository
• EXAMPLES (line 95): workbench --sync

5. Sync Configuration from settings.yml

File: .workbench/settings.yml (lines 17-21)

sync:
  paths:
    - .opencode
    - .workbench/schemas
    - README.md

This is the source workbench's sync configuration — it defines what paths get distributed to downstream workbenches when they run --sync. Per the Q&A decision, sync.paths is NOT documented for end users — it works out of the box.

6. Dispatch Flow in index.ts

File: packages/workbench-cli/src/index.ts (341 lines)

• Line 22-23: if (args.sync) { void runSync(args) } — --sync is checked before all other commands
• Line 36-47: runSync() calls executeSync(), prints error on failure (exit 1), exits 0 on success

7. Existing Cross-References

Root README line 37: See [packages/workbench-cli/README.md](packages/workbench-cli/README.md) for full CLI documentation.

This is the model for the cross-reference link from the new "Syncing Your Workbench" section to the CLI README.

Code References

• README.md:160-163 — "Code indexing with ck" section (before insertion point)
• README.md:164-174 — "Development Setup" section (after insertion point)
• README.md:37 — Cross-reference pattern for CLI README link
• packages/workbench-cli/README.md:86 — End of Setup flags section (before Sync insertion)
• packages/workbench-cli/README.md:87-110 — Examples section
• packages/workbench-cli/README.md:124-131 — Error scenarios table
• packages/workbench-cli/src/commands/sync.ts:68-227 — executeSync() full implementation
• packages/workbench-cli/src/commands/sync.ts:70-75 — Config validation
• packages/workbench-cli/src/commands/sync.ts:97-117 — Working tree check
• packages/workbench-cli/src/commands/sync.ts:119-130 — Confirmation prompt
• packages/workbench-cli/src/commands/sync.ts:185-216 — Auto-commit logic
• packages/workbench-cli/src/args.ts:36 — --sync flag definition
• packages/workbench-cli/src/args.ts:68,83,95 — --help output lines
• packages/workbench-cli/src/index.ts:22-47 — Sync dispatch
• .workbench/settings.yml:17-21 — sync.paths configuration

Architecture Insights

• Early dispatch: --sync is checked before all other commands in the main entry point (line 22), making it a standalone top-level operation — not nested under init or setup.
• Immutable source: Sync clones the source into a temp directory rather than requiring it to be a git remote, avoiding persistent references and keeping the cloned workbench's git history clean.
• Self-contained: Sync has no dependency on TUI or init code paths. It uses only standard Node.js fs/path/os modules and the spawn utility. No OpenTUI or gh CLI needed.
• Commit hygiene: Auto-commit message uses conventional format (chore:) and includes source repo + short SHA for traceability.
• Configuration separation: Sync paths are defined in the source workbench's .workbench/settings.yml (push side), not in the target's config (pull side). Users never configure what gets synced.

Historical Context (from thoughts/)

No existing research documents related to sync were found in thoughts/research/. This is the first research document for the sync feature. All prior context comes from the merged implementation in PR #36 and the ticket body of issue #37.

Open Questions

None. All insertion points, flag details, behaviors, and formatting patterns are fully identified.

[aboo]

Update CLI ReadMe for Sync — Implementation Plan

Overview

Add user-facing documentation for workbench --sync (implemented in PR #36) to the root README.md and the CLI package README.md. The sync command fetches managed files (.opencode/, .workbench/schemas/, README.md) from the source workbench repository and merges them into the local workbench, with an interactive confirmation prompt and auto-commit. This is a documentation-only change — no code modifications.

Current State Analysis

Root README.md (188 lines): Contains sections for Getting Started, Folder Structure, Working on Issues, Project Management, Code indexing with ck, Development Setup, and more. There is zero mention of --sync anywhere. Users fork or clone the workbench and have no way to discover the sync feature through the primary documentation.

CLI README.md (166 lines): Contains Init flags and Setup flags tables, Examples, Error scenarios, and Development sections. --sync is absent from all sections. The --help output in args.ts already includes --sync in USAGE, OPTIONS, and EXAMPLES blocks — that is correct and out of scope.

Sync implementation (packages/workbench-cli/src/commands/sync.ts, 227 lines): executeSync() implements a 10-step flow:

1. Validate .workbench/config.yaml exists
2. Validate source.repository in config
3. Check working tree is clean
4. Interactive confirmation prompt
5. Shallow clone source into temp dir
6. Read sync.paths from source's .workbench/settings.yml
7. Merge each sync path into local workbench
8. Auto-commit with chore: sync workbench from {repo}@{sha}
9. Clean up temp dir
10. Report completion

Key Discoveries

• Root README insertion point: Between line 163 (## Code indexing with ck section end) and line 164 (## Development Setup). The new ## Syncing Your Workbench section fits logically here — between code tooling and developer setup.
• CLI README flag table pattern (lines 61-83): Three-column format | Flag | Description | Default | — new sync table must match exactly.
• CLI README error table pattern (lines 124-131): Three-column format | Error | Cause | Resolution | — sync error rows must match.
• Cross-reference pattern (root README line 37): See [packages/workbench-cli/README.md](...) for full CLI documentation. — template for link in new section.
• --sync in --help: Already present in args.ts:68,83,95 — no changes needed (confirmed out of scope).

Desired End State

After implementation, a user reading either README will:

1. Discover that workbench --sync exists and understand what it does
2. Know the prerequisites (must be in an initialized workbench with clean working tree)
3. Know what to expect (overwrite warning, confirmation prompt, auto-commit)
4. Know how to troubleshoot common errors via the error table
5. Navigate from the root README overview to the CLI README for full flag details

What We're NOT Doing

• No code changes — documentation only. The sync implementation in sync.ts is complete and merged.
• No --help updates — args.ts lines 68, 83, 95 already include --sync with correct text.
• No sync.paths documentation — per Q&A, this configuration key works out of the box and is not user-facing.
• No CONTRIBUTING.md changes — explicitly out of scope.
• No snapshot or rollback documentation — out of scope.
• No changes to existing documented features — --init, --tui, setup flags remain untouched.

Implementation Approach

Two independent, atomic phases — one per README file. Each phase is self-contained and verifiable independently. No ordering dependency between phases.

Changes are purely additive (no existing content is modified or removed). Each insertion follows the existing formatting conventions of its target file.

---

Phase 1: Root README — Syncing Your Workbench Section

Overview

Insert a new ## Syncing Your Workbench section into the root README.md between ## Code indexing with ck (ends at line 163) and ## Development Setup (starts at line 164). The section follows the existing README style: brief prose with an h2 heading, no tables.

Changes Required

1. Root README.md — New Section Insertion

File: README.md
Changes: Insert new section between lines 163 and 164. No existing content is modified.

Content (to be inserted after line 163, before the blank line preceding ## Development Setup):

## 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 for full flag documentation and troubleshooting.

### Success Criteria

#### Automated Verification
- [ ] `fgrep -q "Syncing Your Workbench" README.md` — section heading exists
- [ ] `fgrep -q "workbench --sync" README.md` — usage example present
- [ ] The new section appears between `## Code indexing with ck` and `## Development Setup` (manual ordering check via `grep -n "^## " README.md`)
- [ ] `wc -l README.md` returns 204 lines (188 original + ~16 new, excluding the blank line before Development Setup that gets absorbed)

#### Manual Verification
- [ ] The `## Syncing Your Workbench` section is readable and self-contained
- [ ] The cross-reference link to `packages/workbench-cli/README.md` works and navigates correctly
- [ ] The section explains: what sync does, how to run it, prerequisites, auto-commit behavior, and confirmation prompt
- [ ] No existing section content is altered or displaced

---

## Phase 2: CLI README — Sync Section, Example, and Error Rows

### Overview

Add sync documentation to three locations in `packages/workbench-cli/README.md`:
1. **New `## Sync` section** after Setup flags (after line 86, before line 87 `## Examples`), with a narrative paragraph and flag table
2. **New example** — add `workbench --sync` to the Examples code block (before closing fence at line 110)
3. **Four new error rows** — append to the Error scenarios table (after line 131)

### Changes Required

#### 1. New Sync Section
**File**: `packages/workbench-cli/README.md`
**Changes**: Insert after line 86 (end of ck note blockquote), before line 87 (`## Examples`).

**Content**:

```markdown
## 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.

2. New Example

File: packages/workbench-cli/README.md
Changes: Add one line to the Examples code block (lines 89-110), between line 109 (workbench --tui) and the closing triple-backtick fence on line 110.

Content: Add as the last example line:

# Sync managed files from the source workbench
workbench --sync

3. New Error Rows

File: packages/workbench-cli/README.md
Changes: Append four rows to the Error scenarios table after line 131.

Content:

| `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 |

Success Criteria

Automated Verification

• fgrep -q "## Sync" packages/workbench-cli/README.md — Sync section heading exists
• fgrep -q "\--sync`" packages/workbench-cli/README.md` — flag documented in table
• fgrep -q "workbench --sync" packages/workbench-cli/README.md — example present (should match in both Examples section and Sync section)
• fgrep -q "No .workbench/config.yaml found" packages/workbench-cli/README.md — first sync error row
• fgrep -q "No sync.paths found in source" packages/workbench-cli/README.md — last sync error row
• The Sync section appears between Setup flags and Examples (manual ordering check via grep -n "^## " packages/workbench-cli/README.md)

Manual Verification

• The ## Sync section flag table uses the same three-column format (Flag | Description | Default) as existing Init/Setup flag tables
• The ## Sync narrative paragraph is accurate and matches the implementation behavior
• The workbench --sync example in the Examples section is properly formatted (matches existing example style)
• Error table additions use the same three-column format (Error | Cause | Resolution) as existing rows
• All four error messages match the exact strings output by sync.ts (verified against implementation)
• No existing section content is altered or displaced

---

Testing Strategy

This is a documentation-only change. No code tests apply.

Pre-merge verification

1. Review the rendered markdown in GitHub preview (after PR creation)
2. Verify all inline links resolve correctly
3. Confirm --help output still matches args.ts (no regressions — workbench --help | grep sync)

Post-merge verification

1. Navigate to the repo's GitHub README and confirm the new section renders correctly
2. Navigate to packages/workbench-cli/README.md and confirm sync content renders correctly

Performance Considerations

None — documentation-only change with no runtime impact.

Migration Notes

Not applicable — purely additive documentation. No existing users need to take any action.

References

• Issue: #37 — Update CLI ReadMe for Sync
• PR Adds CLI command to sync workbench files #36 (sync implementation): packages/workbench-cli/src/commands/sync.ts
• Help text reference: packages/workbench-cli/src/args.ts:68,83,95
• Research document: GitHub comment

[aboo]

Plan: #37 - Update CLI ReadMe for Sync

Update CLI ReadMe for Sync — Implementation Plan

Overview

Add user-facing documentation for workbench --sync (implemented in PR #36) to the root README.md and the CLI package README.md. The sync command fetches managed files (.opencode/, .workbench/schemas/, README.md) from the source workbench repository and merges them into the local workbench, with an interactive confirmation prompt and auto-commit. This is a documentation-only change — no code modifications.

Current State Analysis

Root README.md (188 lines): Contains sections for Getting Started, Folder Structure, Working on Issues, Project Management, Code indexing with ck, Development Setup, and more. There is zero mention of --sync anywhere. Users fork or clone the workbench and have no way to discover the sync feature through the primary documentation.

CLI README.md (166 lines): Contains Init flags and Setup flags tables, Examples, Error scenarios, and Development sections. --sync is absent from all sections. The --help output in args.ts already includes --sync in USAGE, OPTIONS, and EXAMPLES blocks — that is correct and out of scope.

Sync implementation (packages/workbench-cli/src/commands/sync.ts, 227 lines): executeSync() implements a 10-step flow:

1. Validate .workbench/config.yaml exists
2. Validate source.repository in config
3. Check working tree is clean
4. Interactive confirmation prompt
5. Shallow clone source into temp dir
6. Read sync.paths from source's .workbench/settings.yml
7. Merge each sync path into local workbench
8. Auto-commit with chore: sync workbench from {repo}@{sha}
9. Clean up temp dir
10. Report completion

Key Discoveries

• Root README insertion point: Between line 163 (## Code indexing with ck section end) and line 164 (## Development Setup). The new ## Syncing Your Workbench section fits logically here — between code tooling and developer setup.
• CLI README flag table pattern (lines 61-83): Three-column format | Flag | Description | Default | — new sync table must match exactly.
• CLI README error table pattern (lines 124-131): Three-column format | Error | Cause | Resolution | — sync error rows must match.
• Cross-reference pattern (root README line 37): See [packages/workbench-cli/README.md](...) for full CLI documentation. — template for link in new section.
• --sync in --help: Already present in args.ts:68,83,95 — no changes needed (confirmed out of scope).

Desired End State

After implementation, a user reading either README will:

1. Discover that workbench --sync exists and understand what it does
2. Know the prerequisites (must be in an initialized workbench with clean working tree)
3. Know what to expect (overwrite warning, confirmation prompt, auto-commit)
4. Know how to troubleshoot common errors via the error table
5. Navigate from the root README overview to the CLI README for full flag details

What We're NOT Doing

• No code changes — documentation only. The sync implementation in sync.ts is complete and merged.
• No --help updates — args.ts lines 68, 83, 95 already include --sync with correct text.
• No sync.paths documentation — per Q&A, this configuration key works out of the box and is not user-facing.
• No CONTRIBUTING.md changes — explicitly out of scope.
• No snapshot or rollback documentation — out of scope.
• No changes to existing documented features — --init, --tui, setup flags remain untouched.

Implementation Approach

Two independent, atomic phases — one per README file. Each phase is self-contained and verifiable independently. No ordering dependency between phases.

Changes are purely additive (no existing content is modified or removed). Each insertion follows the existing formatting conventions of its target file.

---

Phase 1: Root README — Syncing Your Workbench Section

Overview

Insert a new ## Syncing Your Workbench section into the root README.md between ## Code indexing with ck (ends at line 163) and ## Development Setup (starts at line 164). The section follows the existing README style: brief prose with an h2 heading, no tables.

Changes Required

1. Root README.md — New Section Insertion

File: README.md
Changes: Insert new section between lines 163 and 164. No existing content is modified.

Content (to be inserted after line 163, before the blank line preceding ## Development Setup):

## 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 for full flag documentation and troubleshooting.

### Success Criteria

#### Automated Verification
- [ ] `fgrep -q "Syncing Your Workbench" README.md` — section heading exists
- [ ] `fgrep -q "workbench --sync" README.md` — usage example present
- [ ] The new section appears between `## Code indexing with ck` and `## Development Setup` (manual ordering check via `grep -n "^## " README.md`)
- [ ] `wc -l README.md` returns 204 lines (188 original + ~16 new, excluding the blank line before Development Setup that gets absorbed)

#### Manual Verification
- [ ] The `## Syncing Your Workbench` section is readable and self-contained
- [ ] The cross-reference link to `packages/workbench-cli/README.md` works and navigates correctly
- [ ] The section explains: what sync does, how to run it, prerequisites, auto-commit behavior, and confirmation prompt
- [ ] No existing section content is altered or displaced

---

## Phase 2: CLI README — Sync Section, Example, and Error Rows

### Overview

Add sync documentation to three locations in `packages/workbench-cli/README.md`:
1. **New `## Sync` section** after Setup flags (after line 86, before line 87 `## Examples`), with a narrative paragraph and flag table
2. **New example** — add `workbench --sync` to the Examples code block (before closing fence at line 110)
3. **Four new error rows** — append to the Error scenarios table (after line 131)

### Changes Required

#### 1. New Sync Section
**File**: `packages/workbench-cli/README.md`
**Changes**: Insert after line 86 (end of ck note blockquote), before line 87 (`## Examples`).

**Content**:

```markdown
## 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.

2. New Example

File: packages/workbench-cli/README.md
Changes: Add one line to the Examples code block (lines 89-110), between line 109 (workbench --tui) and the closing triple-backtick fence on line 110.

Content: Add as the last example line:

# Sync managed files from the source workbench
workbench --sync

3. New Error Rows

File: packages/workbench-cli/README.md
Changes: Append four rows to the Error scenarios table after line 131.

Content:

| `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 |

Success Criteria

Automated Verification

• fgrep -q "## Sync" packages/workbench-cli/README.md — Sync section heading exists
• fgrep -q "\--sync`" packages/workbench-cli/README.md` — flag documented in table
• fgrep -q "workbench --sync" packages/workbench-cli/README.md — example present (should match in both Examples section and Sync section)
• fgrep -q "No .workbench/config.yaml found" packages/workbench-cli/README.md — first sync error row
• fgrep -q "No sync.paths found in source" packages/workbench-cli/README.md — last sync error row
• The Sync section appears between Setup flags and Examples (manual ordering check via grep -n "^## " packages/workbench-cli/README.md)

Manual Verification

• The ## Sync section flag table uses the same three-column format (Flag | Description | Default) as existing Init/Setup flag tables
• The ## Sync narrative paragraph is accurate and matches the implementation behavior
• The workbench --sync example in the Examples section is properly formatted (matches existing example style)
• Error table additions use the same three-column format (Error | Cause | Resolution) as existing rows
• All four error messages match the exact strings output by sync.ts (verified against implementation)
• No existing section content is altered or displaced

---

Testing Strategy

This is a documentation-only change. No code tests apply.

Pre-merge verification

1. Review the rendered markdown in GitHub preview (after PR creation)
2. Verify all inline links resolve correctly
3. Confirm --help output still matches args.ts (no regressions — workbench --help | grep sync)

Post-merge verification

1. Navigate to the repo's GitHub README and confirm the new section renders correctly
2. Navigate to packages/workbench-cli/README.md and confirm sync content renders correctly

Performance Considerations

None — documentation-only change with no runtime impact.

Migration Notes

Not applicable — purely additive documentation. No existing users need to take any action.

References

• Issue: #37 — Update CLI ReadMe for Sync
• PR Adds CLI command to sync workbench files #36 (sync implementation): packages/workbench-cli/src/commands/sync.ts
• Help text reference: packages/workbench-cli/src/args.ts:68,83,95
• Research document: GitHub comment

[aboo]

Execution Notes: #37 - Update CLI ReadMe for Sync

Summary

All phases completed successfully. This was a documentation-only change adding workbench --sync documentation to two README files. No code modifications.

Phase 1: Root README — Syncing Your Workbench Section

Status: ✅ Complete
File: README.md (188 → 204 lines)

Inserted ## Syncing Your Workbench section between ## Code indexing with ck (line 160) and ## Development Setup (line 180). Content includes:

• Brief description of what --sync does
• One-line usage example: workbench --sync
• Explanation of auto-commit and confirmation prompt
• Prerequisites note (initialized workbench + clean tree)
• Cross-reference link to CLI README

Verification: All automated checks pass — heading found, example present, correct section ordering.

Phase 2: CLI README — Sync Section, Example, and Error Rows

Status: ✅ Complete
File: packages/workbench-cli/README.md (166 → 182 lines)

2a: Sync Section

Inserted ## Sync section between ## Setup flags (line 71) and ## Examples (line 97) with:

• Narrative paragraph explaining sync behavior
• Flag table matching existing three-column format (Flag | Description | Default)
• --sync flag row with description of managed file paths
• Requirement notes

2b: Examples

Added workbench --sync example inside the Examples code block, before the closing fence:

# Sync managed files from the source workbench
workbench --sync

2c: Error Rows

Appended 4 sync-specific error rows to the Error scenarios table in existing three-column format (Error | Cause | Resolution):

• No .workbench/config.yaml found → Workbench not initialized
• No source.repository found in config → Config predates sync feature
• Working tree is not clean → Uncommitted changes present
• No sync.paths found in source → Source doesn't support sync

Verification: All automated checks pass — Sync heading found, flag documented, example present, all 4 error rows present, correct section ordering.

Deviations

None. All changes implemented exactly as specified in the plan.

Verification Summary

Check	Phase	Result
## Syncing Your Workbench heading	Phase 1	✅
workbench --sync in root README	Phase 1	✅
Section between ck and Dev Setup	Phase 1	✅
## Sync heading in CLI README	Phase 2	✅
--sync flag in table	Phase 2	✅
workbench --sync in Examples block	Phase 2	✅
4 sync error rows appended	Phase 2	✅
Section between Setup flags and Examples	Phase 2	✅

Completion

• Root README.md: 204 lines (was 188)
• CLI README.md: 182 lines (was 166)
• No code changes — documentation only

[aboo]

Review: #37 - Update CLI ReadMe for Sync

Validation Report: Update CLI ReadMe for Sync

Implementation Status

✓ Phase 1: Root README — Syncing Your Workbench Section — Fully implemented
✓ Phase 2: CLI README — Sync Section, Example, and Error Rows — Fully implemented

Automated Verification Results

✓ ## Syncing Your Workbench heading exists in root README (line 165)
✓ workbench --sync usage example present in root README (lines 167, 170)
✓ Section ordering correct: Code indexing with ck (160) → Syncing Your Workbench (165) → Development Setup (180)
✓ Root README line count: 204 (matches plan: 188 + 16)
✓ ## Sync heading exists in CLI README (line 88)
✓ --sync flag documented in table (line 94)
✓ workbench --sync present in Examples code block (line 121)
✓ All 4 sync error rows appended (lines 144–147)
✓ CLI section ordering correct: Setup flags (71) → Sync (88) → Examples (97)
✓ CLI README line count: 182 (matches plan: 166 + 16)

Code Review Findings

Matches Plan

• Phase 1 content is character-for-character identical to the plan specification
• Phase 2 sync section content is character-for-character identical to the plan specification
• Phase 2 example line matches the plan exactly
• Phase 2 error rows match the plan exactly (all 4 rows)
• Insertion points respect the plan's specified locations
• No existing content was modified, moved, or deleted
• Error messages in README accurately reflect the error strings in sync.ts:
  • No .workbench/config.yaml found ↔ sync.ts line 73
  • No source.repository found in config ↔ sync.ts line 90
  • Working tree is not clean ↔ sync.ts line 115
  • No sync.paths found in source ↔ sync.ts line 161
• Narrative descriptions match the actual sync implementation behavior (10-step flow in sync.ts)
• Cross-reference link packages/workbench-cli/README.md resolves correctly

Deviations From Plan

• None. All changes match the plan specification exactly.

Potential Issues

• ⚠ Missing blank line before ## Examples heading (CLI README, lines 96→97): The text "Sync requires an initialized workbench..." (line 96) flows directly into ## Examples (line 97) without an intervening blank line. Standard Markdown style requires a blank line before ATX headings. Other section transitions in the file consistently have blank lines (e.g., line 87 before ## Sync, line 98 before the code fence, line 123 before ## What the setup wizard does). This is a minor formatting inconsistency — does not affect rendering or readability on GitHub, but creates a style discrepancy. Root cause: the plan's content block did not include a trailing blank line.

Manual Testing Required

1. Open README.md on GitHub and verify the ## Syncing Your Workbench section renders correctly, with the code block and inline link working
2. Open packages/workbench-cli/README.md on GitHub and verify:
   • ## Sync section renders with the flag table and note
   • workbench --sync example appears correctly in the Examples code block
   • All 4 sync error rows appear in the Error scenarios table
   • The ## Examples heading renders correctly despite the missing blank line (GitHub's Markdown parser is forgiving)
3. Run workbench --help | grep sync to confirm no regressions in the CLI help output (already present in args.ts)

Recommendations

• Fix: Add a blank line between the Sync section note (line 96) and ## Examples (line 97) in packages/workbench-cli/README.md for formatting consistency with the rest of the file

Verdict

✅ Pass — Implementation is correct, complete, and matches the plan. Zero deviations. The single formatting issue (missing blank line) is cosmetic and does not block passing. The documentation accurately describes the sync feature and provides users with clear guidance on usage, prerequisites, and troubleshooting.