docs(shared): S4 — document subtree sync commands; R1 realized

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AaQCFnfsh3tfq1VfzdJpoi

shared/README.md

@@ -36,9 +36,30 @@ 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 (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:
+
+  ```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.
 
 See the target picture for the full architecture: `docs/plan/2026-06-26-maalbilde-agentic-loop.md`.