diff --git a/.changeset/effa-sync-shared.md b/.changeset/effa-sync-shared.md
new file mode 100644
index 000000000..8a0f1b666
--- /dev/null
+++ b/.changeset/effa-sync-shared.md
@@ -0,0 +1,20 @@
+---
+"@effect-app/cli": minor
+---
+
+Add `effa sync` / `effa sync-diff` / `effa sync-push` subcommands for syncing content (architecture docs, e2e helpers, ts-plugins) from `effect-app/shared` into consuming projects per a project-side `.shared.json` lockfile.
+
+- `effa sync` — clone/checkout the shared repo at the pinned ref into `~/.cache/effa/shared/<slug>`, then copy the artifact map's files into the project (honoring `exclude`).
+- `effa sync-diff` — sha256 compare each tracked file against the cache copy; reports `M` (modified locally), `D` (missing from project), `E` (excluded).
+- `effa sync-push [--pr] [-m msg] [--branch name]` — branch in the cache off the pinned ref, copy modified project files in, commit, push. Optional `--pr` opens a PR via `gh pr create`.
+
+Lockfile shape:
+
+```json
+{
+  "repo": "github.com/effect-app/shared",
+  "ref": "<sha>",
+  "artifacts": { "<src-in-shared>": "<dest-in-project>" },
+  "exclude": ["<src-path>"]
+}
+```
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 71946fc03..01d14ddd6 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -57,6 +57,10 @@
     "./sync-effect-subtree": {
       "types": "./dist/sync-effect-subtree.d.ts",
       "default": "./dist/sync-effect-subtree.js"
+    },
+    "./sync-shared": {
+      "types": "./dist/sync-shared.d.ts",
+      "default": "./dist/sync-shared.js"
     }
   },
   "scripts": {