Squashed 'shared/' changes from 7d2b46c..db86e15

db86e15 docs: document subtree consumption — R1 realized, sync is pull-only

git-subtree-dir: shared
git-subtree-split: db86e159148d7d8553a38516e174370cf913f889

README.md

@@ -36,9 +36,27 @@ so the only thing that differs is the agent framework itself.
 
 - **Nothing in here may import or depend on a specific agent framework.** If it does,
   it does not belong in `shared/`.
-- **Repo layout (decision R1, 2026-06-26):** the shared core lives here for now. When
-  work on the sibling repository begins, it will be extracted into its own repository
-  (e.g. `portfolio-optimiser-commons`) via `git subtree split`, and both implementation
-  repos will consume it. This defers cross-repo plumbing until it is actually needed.
+- **Repo layout (decision R1, realized 2026-07-03):** the shared core lives in its own
+  repository, [`portfolio-optimiser-commons`](https://git.fromaitochitta.com/ktg/portfolio-optimiser-commons)
+  — the **source of truth**. Each implementation repo consumes it as a **git subtree**
+  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 (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`).
+
+**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
+```
+
+**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`.