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`.
diff --git a/semantic/repo.jsonld b/semantic/repo.jsonld
new file mode 100644
index 0000000..39e0948
--- /dev/null
+++ b/semantic/repo.jsonld
@@ -0,0 +1,27 @@
+{
+  "@context": "https://raw.githubusercontent.com/SourceOS-Linux/sourceos-spec/main/semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:SourceOS",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "SourceOS",
+  "description": "Immutable, local-first operating-system substrate for workstation and edge lanes.",
+  "repositoryFullName": "SociOS-Linux/SourceOS",
+  "repoUrl": "https://github.com/SociOS-Linux/SourceOS",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleOSSubstrate",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "opt-in automation commons",
+    "workspace controller",
+    "public docs site",
+    "canonical typed-contract registry"
+  ]
+}
diff --git a/spec/volumes/volumes.yml b/spec/volumes/volumes.yml
index eeeb755..84216cb 100644
--- a/spec/volumes/volumes.yml
+++ b/spec/volumes/volumes.yml
@@ -1,10 +1,10 @@
 volumes:
   Documents: {path: "~/Documents", policy: {snapshots: true, sync: off, backup: off}}
   Downloads: {path: "~/Downloads", policy: {noexec: true, snapshots: false, sync: off, backup: off}}
-  Desktop:   {path: "~/Desktop",   policy: {snapshots: true, sync: off, backup: off}}
-  Music:     {path: "~/Music",     policy: {snapshots: true, sync: off, backup: off}}
-  Videos:    {path: "~/Videos",    policy: {snapshots: true, sync: off, backup: off}}
-  Public:    {path: "~/Public",    policy: {snapshots: true, sync: off, backup: off}}
-  Pictures:  {path: "~/Pictures",  policy: {snapshots: true, sync: off, backup: off}}
-  Projects:  {path: "~/Projects",  policy: {snapshots: true, sync: off, backup: off}}
-  Secrets:   {path: "~/Secrets",   policy: {encrypted: true, sync: off, backup: off}}
+  Desktop: {path: "~/Desktop", policy: {snapshots: true, sync: off, backup: off}}
+  Music: {path: "~/Music", policy: {snapshots: true, sync: off, backup: off}}
+  Videos: {path: "~/Videos", policy: {snapshots: true, sync: off, backup: off}}
+  Public: {path: "~/Public", policy: {snapshots: true, sync: off, backup: off}}
+  Pictures: {path: "~/Pictures", policy: {snapshots: true, sync: off, backup: off}}
+  Projects: {path: "~/Projects", policy: {snapshots: true, sync: off, backup: off}}
+  Secrets: {path: "~/Secrets", policy: {encrypted: true, sync: off, backup: off}}