Documentation: Upstream sync workflow #11779

# Upstream Sync Guide

## Overview
This document describes how to sync backend changes from upstream sst/opencode.

## Setup (One-time)
\`\`\`bash
git remote add upstream https://github.com/sst/opencode.git
\`\`\`

## Sync Workflow

### 1. Fetch upstream changes
\`\`\`bash
git fetch upstream
\`\`\`

### 2. Identify relevant commits
\`\`\`bash
# Backend-only commits
git log --oneline upstream/dev -- \
  packages/opencode/src/session \
  packages/opencode/src/provider \
  packages/opencode/src/tool \
  packages/opencode/src/mcp \
  packages/opencode/src/skill \
  packages/opencode/src/agent \
  packages/opencode/src/permission
\`\`\`

### 3. Review and cherry-pick
\`\`\`bash
git cherry-pick <commit-hash>
\`\`\`

### 4. Handle conflicts
- **cli/lite/**: Always keep ours (--ours)
- **cli/cmd/tui/**: Always keep ours (--ours)
- **Backend code**: Merge carefully, test after

### 5. Update sync log
Add entry to this file with commit hash and date.

## Include Patterns
- fix(provider):, feat(provider):
- fix(session):, feat(session):
- fix(tool):, feat(tool):
- fix(mcp):, feat(mcp):
- fix(skill):, feat(skill):

## Exclude Patterns
- tui:, fix(tui):, feat(tui):
- fix(app):, feat(app):
- desktop:

## Sync Log

| Date | Upstream Commit | Description |
|------|-----------------|-------------|
| 2026-02-02 | (initial fork) | Fork from sst/opencode |

## Recommended Cadence
- Weekly: Check for critical fixes
- Bi-weekly: Cherry-pick accumulated changes
- Per release: Review CHANGELOG for breaking changes