docs(opsx): clarify /opsx:sync description and add usage section

[clay-good]

Supersedes #1061 (rebased onto main with the merge conflict resolved). Original work by @HowardYan888 — thank you!

Status

LGTM — merge-ready. Docs-only, verified safe and hardened.

What was missing / motivation

docs/opsx.md described /opsx:sync inconsistently with the rest of the docs (commands.md, migration-guide.md, fixed in the merged #1059): it used "Sync … to main (default workflow, optional)" and had no Usage section for the command.

What it does

• Table row: Sync delta specs to main (default workflow, optional) → Merge delta specs into main specs (optional) (the canonical wording used in commands.md and migration-guide.md).
• New "Sync delta specs" Usage section: a single prose paragraph matching the file's six sibling Usage sections, describing what sync does and when to reach for it.

Hardening (second commit)

Adversarially fact-checked every claim against src/core/templates/workflows/sync-specs.ts and archive-change.ts, then tightened the section:

• Removed two inaccurate use cases from the original draft ("changes see each other's specs" and "test integration" — neither exists in the sync workflow).
• Added the honest non-additive detail: sync applies the whole delta, so a ## REMOVED requirement is deleted from the main spec and a renamed one is retitled — the section no longer reads as additive-only.
• Matched house style (spaced em-dash, prose paragraph instead of a bold-label/bullet block unique to this file).

Proof it works

• Docs-site build (the Cloudflare Pages gate): ran the real pipeline locally — sync-docs.mjs → fumadocs-mdx → next build — exit 0, /docs/opsx renders end-to-end with the edited content. Docs sync as plain .md (not .mdx), so there is no JSX/expression parsing to break.
• Doc accuracy: every remaining claim verified against source (sync merges deltas into openspec/specs/, leaves the change active, archive prompts to sync, REMOVED/RENAMED applied).
• Repo regression gate: eslint src/ ✅, node build.js ✅, vitest run → 3859 passed. This branch's entire diff vs main is docs/opsx.md (git diff main...HEAD -- src/ test/ is empty), so nothing in the CLI is touched.

Notes

• No Closes #X: this is a docs-consistency cleanup following docs(migration-guide): fix inconsistent /opsx:sync description #1059; there is no open issue reporting the wording gap.
• Related: Clarify archive sync for new specs #1271 (also improves sync-before-archive clarity, but edits archive-change.ts — no file overlap, no conflict).

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Clarified that /opsx:sync merges delta specifications into the main specifications.
  • Added usage guidance, behavior details, and example scenarios for syncing delta specifications.
  • Documented that the active change is preserved during synchronization.
  • Explained when syncing is appropriate and how full-delta merges behave.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 1e18230a-8bd2-48ed-8de8-7ca7a44f60db

📥 Commits

Reviewing files that changed from the base of the PR and between e5c97b5 and 02c5938.

📒 Files selected for processing (1)

• docs/opsx.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/opsx.md

---

📝 Walkthrough

Walkthrough

The PR updates docs/opsx.md to document /opsx:sync as a command that merges delta specs into main specs. It adds merge behavior, active-change retention, and usage scenarios.

Changes

/opsx:sync Documentation

Layer / File(s)	Summary
Document sync behavior and usage docs/opsx.md	The command description now states that /opsx:sync merges delta specs into main specs. The usage section documents full delta application, removal and renaming handling, preservation of unmentioned content, active-change retention, and recommended usage scenarios.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related PRs

• Fission-AI/OpenSpec#450: Documents the /opsx:sync command and its delta-spec workflow.
• Fission-AI/OpenSpec#1059: Updates /opsx:sync documentation with delta-spec merge behavior.
• Fission-AI/OpenSpec#1402: Updates /opsx:sync documentation with delta-spec merge guidance.

Suggested reviewers: tabishb

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly identifies the documentation update to clarify the /opsx:sync description and add usage guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/pr-1061-merge-ready-334ae9

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying openspec-docs with    Cloudflare Pages

Latest commit:	02c5938
Status:	✅  Deploy successful!
Preview URL:	https://12275f78.openspec-docs.pages.dev
Branch Preview URL:	https://claude-pr-1061-merge-ready-3.openspec-docs.pages.dev

View logs

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/opsx.md`:
- Around line 219-221: Update the code fence containing `/opsx:sync` in the
documentation to specify the `text` language on its opening fence, resolving the
markdownlint MD040 violation.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 7dcfa899-2864-4944-9929-3d5df2c87ebe

📥 Commits

Reviewing files that changed from the base of the PR and between ec99091 and e5c97b5.

📒 Files selected for processing (1)

• docs/opsx.md

[alfred-openspec]

The sync description now matches the whole-delta behavior and accurately explains preservation, removal, and rename semantics. The docs build and exact-head checks pass.