From 8175508e4dc99843d21fd121ad1f13ff07e7b551 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Sat, 4 Apr 2026 17:56:00 -0400
Subject: [PATCH] docs: clarify repo topology and connected surfaces

---
 README.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 074ff78..374e34a 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,23 @@ This revision closes the biggest implementability gaps from v1:
 - Adds a minimal Hydra/JSON-LD semantic overlay (semantic/context.jsonld + semantic/hydra.jsonld)
 - Upgrades Dataset to reference Asset + Schema + Agreements explicitly (no implicit physical fields)
 
+## Topology position
+
+- **Role:** canonical typed-contract, JSON-LD, and shared vocabulary lane for SourceOS / AgentOS.
+- **Connects to:**
+  - `SociOS-Linux/agentos-spine` — Linux-side integration/workspace spine that consumes and routes these contracts
+  - `SociOS-Linux/workstation-contracts` — workstation/CI specialization and conformance lane
+  - `SociOS-Linux/SourceOS` — immutable substrate that should consume typed policy and artifact semantics
+  - `SociOS-Linux/socios` — opt-in automation layer that should reference, not redefine, these contracts
+  - `SocioProphet/sociosphere` — platform workspace controller that may mirror or reuse shared contract vocabulary
+  - `SocioProphet/socioprophet` and `SociOS-Linux/socioslinux-web` — public documentation surfaces that explain these contracts downstream
+- **Not this repo:**
+  - workspace controller
+  - image builder
+  - public docs site
+  - opt-in automation plane
+- **Semantic direction:** this repo should become the canonical home for shared repo ontology, JSON-LD contexts, and vocabulary definitions that other repos publish by reference.
+
 ## Why this matters
 If a contract bundle does not cover agreements, glossary, and asset connectors, the metadata plane cannot unify governance and meaning end-to-end.
 We now have a closed set of object families that directly correspond to the Open Metadata Types taxonomy areas:
@@ -25,4 +42,3 @@ We now have a closed set of object families that directly correspond to the Open
 ## Compatibility discipline
 - IDs are stable URNs; specVersion is semver.
 - Additive changes should remain backward compatible; breaking changes increment major.
-