diff --git a/shared/README.md b/shared/README.md
index 7fb0e11..66da623 100644
--- a/shared/README.md
+++ b/shared/README.md
@@ -42,24 +42,21 @@ so the only thing that differs is the agent framework itself.
   at this unchanged `shared/` path (so tests and the `PORTFOLIO_SHARED_ROOT` default
   resolver are unaffected). Do not edit commons content anywhere else without syncing.
 
-## Subtree sync (run from the consuming repo's root)
+## Subtree sync (pull-only — run from the consuming repo's root)
 
 The remote is registered as `commons`
 (`ssh://git@git.fromaitochitta.com/ktg/portfolio-optimiser-commons.git`).
 
-- **Pull** upstream changes from commons into this repo:
+**All edits land in commons first** (clone it, commit, push there), then each
+consuming repo pulls them in:
 
-  ```sh
-  git subtree pull --prefix=shared commons main --squash
-  ```
+```sh
+git subtree pull --prefix=shared commons main --squash
+```
 
-- **Push** local `shared/` edits (committed here first) back to commons:
-
-  ```sh
-  git subtree push --prefix=shared commons main
-  ```
-
-Edits should preferably land in commons first and be pulled; pushing from a consumer
-is for small fixes made in place. Either way, commons remains the source of truth.
+**Never run `git subtree push` from a consuming repo.** Observed 2026-07-03: because
+this repo's history contains commits that create/delete the `shared/` prefix, the
+push re-split leaked the consumer's *entire* history into commons (cleaned up by
+force-push the same day). Pull-only keeps commons the clean source of truth.
 
 See the target picture for the full architecture: `docs/plan/2026-06-26-maalbilde-agentic-loop.md`.