diff --git a/CHANGELOG.md b/CHANGELOG.md
index 331843f..4039d21 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,10 @@
 
 ## 1.3.0
 
+### Breaking Changes
+
+_None._
+
 ### Features
 
 - **Linearize fallback for reverse sync**: When josh-proxy rejects a push due to unmappable merge commits, reverse sync automatically falls back to linearizing the history — cherry-picking regular commits individually and squashing only the problematic merge commits via `cherry-pick -m 1`. Preserves individual commit granularity while handling complex merge topologies that josh cannot map. PR body notes when linearization was used.
@@ -19,6 +23,10 @@
 
 ## 1.2.0
 
+### Breaking Changes
+
+_None._
+
 ### Features
 
 - **File exclusion**: `exclude` config field removes files/directories from the subrepo at the josh-proxy transport layer. Patterns are embedded inline in the josh-proxy URL using `:exclude[::pattern,...]` syntax — no extra files to generate or commit.
@@ -38,6 +46,10 @@
 
 ## 1.1.0
 
+### Breaking Changes
+
+_None._
+
 ### Features
 
 - **`onboard` command**: Interactive, resumable workflow for importing existing subrepos into the monorepo. Walks through: prerequisites check, import (creates PRs), wait for merge, reset (pushes josh-filtered history). Checkpoint/resume at every step.
diff --git a/README.md b/README.md
index 3b39733..0f8466c 100644
--- a/README.md
+++ b/README.md
@@ -63,6 +63,18 @@ Run `josh-sync preflight` to validate your setup.
 - **[Architecture Decision Records](docs/adr/)** — Design rationale and trade-offs
 - **[Changelog](CHANGELOG.md)** — Version history
 
+## Versioning
+
+josh-sync follows [semver](https://semver.org/):
+
+| Bump | Meaning | Action required |
+|------|---------|-----------------|
+| **Patch** (1.x.**y**) | Bug fixes only | Safe to upgrade |
+| **Minor** (1.**y**.0) | New optional config fields, new commands, new action inputs | Safe to upgrade; new features are opt-in |
+| **Major** (**y**.0.0) | Removed or renamed config fields, CLI flags, action inputs, env vars, or state format | Read the **Breaking Changes** section in the changelog before upgrading |
+
+CI workflows pin to a floating major tag (e.g. `@v1`). A breaking change bumps the major version and moves the tag — `@v1` workflows keep working until you explicitly update to `@v2`.
+
 ## CLI
 
 ```
diff --git a/lib/config.sh b/lib/config.sh
index bdf8b95..bc12366 100644
--- a/lib/config.sh
+++ b/lib/config.sh
@@ -16,6 +16,11 @@ parse_config() {
   local config_json
   config_json=$(yq -o json "$config_file") || die "Failed to parse ${config_file}"
 
+  # Schema version check (optional field — absent means v1)
+  local schema_version
+  schema_version=$(echo "$config_json" | jq -r '.schema_version // 1')
+  [ "$schema_version" = "1" ] || die "Unsupported schema_version ${schema_version} in ${config_file} (this version of josh-sync supports schema_version 1 — see CHANGELOG.md for migration instructions)"
+
   # Export global values
   export JOSH_PROXY_URL
   JOSH_PROXY_URL=$(echo "$config_json" | jq -r '.josh.proxy_url')
diff --git a/schema/config-schema.json b/schema/config-schema.json
index b3c9675..4afeb72 100644
--- a/schema/config-schema.json
+++ b/schema/config-schema.json
@@ -5,6 +5,11 @@
   "type": "object",
   "required": ["josh", "targets", "bot"],
   "properties": {
+    "schema_version": {
+      "type": "integer",
+      "const": 1,
+      "description": "Schema version. Bump when config fields are removed or renamed (matches josh-sync major version)."
+    },
     "josh": {
       "type": "object",
       "required": ["proxy_url", "monorepo_path"],