From f78aa099f5d8ef999065b04b417016a1859767ec Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Tue, 7 Apr 2026 00:19:30 -0400
Subject: [PATCH] docs: clarify repo topology and connected surfaces

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

diff --git a/README.md b/README.md
index d4d7b38..85da22b 100644
--- a/README.md
+++ b/README.md
@@ -3,3 +3,20 @@
 Immutable, local-first OS substrate (workstation + edge) with verifiable policy and user-space isolation.
 
 **No community automation dependency.**
+
+## Topology position
+
+- **Role:** immutable OS substrate for workstation and edge lanes.
+- **Connects to:**
+  - `SociOS-Linux/agentos-spine` — current Linux-side integration/workspace spine that assembles or routes adjacent layers around the substrate
+  - `SourceOS-Linux/sourceos-spec` — canonical typed contracts, JSON-LD contexts, and shared vocabulary for policy, assets, and events
+  - `SociOS-Linux/workstation-contracts` — workstation/CI contract and conformance lane
+  - `SociOS-Linux/socios` — opt-in automation commons, never a required dependency
+  - `SociOS-Linux/socioslinux-web` — Linux public web/docs surface that explains the substrate downstream
+  - Linux build and publish surfaces such as image/package lanes may realize this substrate, but this repo is the substrate rather than the builder
+- **Not this repo:**
+  - opt-in automation commons
+  - workspace controller
+  - public docs site
+  - canonical typed-contract registry
+- **Semantic direction:** this repo should eventually publish a substrate-focused repo descriptor that references the shared SourceOS/SociOS vocabulary from `sourceos-spec`.