diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index bcf2f5a..8b7383c 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -29,7 +29,11 @@ jobs:
           failed=0
           for schema in schemas/*.json; do
             echo -n "Compiling $schema ... "
-            if ajv compile -s "$schema" --strict=false 2>&1; then
+            cmd=(ajv compile -s "$schema" --strict=false --spec=draft2020)
+            for ref in schemas/*.json; do
+              [ "$ref" != "$schema" ] && cmd+=(-r "$ref")
+            done
+            if "${cmd[@]}" 2>&1; then
               echo "ok"
             else
               echo "FAILED"
@@ -189,6 +193,8 @@ jobs:
                   with open(path) as f:
                       doc = json.load(f)
                   ctx = doc.get('@context', {})
+                  if not isinstance(ctx, dict):
+                      ctx = {}
                   mapped = [k for k, v in ctx.items() if isinstance(v, str) and (v.startswith('srcos:') or v.startswith('prov:'))]
                   print(f"{path}: valid JSON, {len(mapped)} type mappings")
               except Exception as e:
diff --git a/docs/REPO_DESCRIPTOR_GUIDE.md b/docs/REPO_DESCRIPTOR_GUIDE.md
new file mode 100644
index 0000000..81a69bf
--- /dev/null
+++ b/docs/REPO_DESCRIPTOR_GUIDE.md
@@ -0,0 +1,78 @@
+# Repo Descriptor Guide
+
+This repository publishes the starter semantic layer for the broader SourceOS / AgentOS / SocioProphet topology.
+
+## What this starter pack contains
+
+- `semantic/context.jsonld` — JSON-LD context for repository descriptors
+- `semantic/repo-ontology.jsonld` — role vocabulary / concept graph
+- `schemas/repo_descriptor.schema.json` — JSON Schema for machine-readable repo descriptors
+- `examples/repo-descriptor.*.jsonld` — concrete examples for the current topology
+
+## Why this exists
+
+READMEs are for humans. Repo descriptors are for machines.
+
+Every important repository should eventually ship a small machine-readable descriptor so that:
+
+- agents can resolve role and adjacency without scraping prose
+- tooling can build topology maps automatically
+- documentation sites can embed structured metadata
+- policy and orchestration systems can reason over repo classes and relationships directly
+
+## Recommended placement in downstream repos
+
+Each repo should eventually publish:
+
+- `semantic/repo.jsonld`
+
+The descriptor should reference this shared context and vocabulary rather than redefining terms locally.
+
+## Minimal descriptor skeleton
+
+```json
+{
+  "@context": "https://raw.githubusercontent.com/SourceOS-Linux/sourceos-spec/main/semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:ORG:REPO",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "repo-name",
+  "description": "One-sentence role statement.",
+  "repositoryFullName": "ORG/repo-name",
+  "repoUrl": "https://github.com/ORG/repo-name",
+  "organization": "ORG",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleTypedContractRegistry",
+  "connectsTo": [],
+  "notThisRepo": []
+}
+```
+
+## Current canonical role set
+
+- `rolePlatformWorkspaceController`
+- `roleLinuxIntegrationSpine`
+- `roleTypedContractRegistry`
+- `roleWorkstationConformanceLane`
+- `roleAutomationCommons`
+- `roleOSSubstrate`
+- `rolePublicDocsSurface`
+- `roleStarterScaffold`
+
+## Current rule of use
+
+- prefer one primary topology role per repo
+- use `connectsTo` for explicit adjacency
+- use `notThisRepo` to block common category mistakes
+- use `consumesVocabularyFrom` when the repo imports the canonical vocabulary from this repo
+
+## Near-term follow-up
+
+Next we should add one real `semantic/repo.jsonld` file to each core repo:
+
+- `SociOS-Linux/agentos-spine`
+- `SocioProphet/sociosphere`
+- `SociOS-Linux/workstation-contracts`
+- `SociOS-Linux/SourceOS`
+- `SociOS-Linux/socios`
+- `SociOS-Linux/socioslinux-web`
diff --git a/examples/repo-descriptor.SourceOS.jsonld b/examples/repo-descriptor.SourceOS.jsonld
new file mode 100644
index 0000000..84afaa6
--- /dev/null
+++ b/examples/repo-descriptor.SourceOS.jsonld
@@ -0,0 +1,27 @@
+{
+  "@context": "../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/examples/repo-descriptor.agentos-spine.jsonld b/examples/repo-descriptor.agentos-spine.jsonld
new file mode 100644
index 0000000..7aa72b6
--- /dev/null
+++ b/examples/repo-descriptor.agentos-spine.jsonld
@@ -0,0 +1,28 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "agentos-spine",
+  "description": "Current Linux-side integration/workspace spine for AgentOS / SourceOS.",
+  "repositoryFullName": "SociOS-Linux/agentos-spine",
+  "repoUrl": "https://github.com/SociOS-Linux/agentos-spine",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleLinuxIntegrationSpine",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "immutable OS substrate",
+    "final typed-contract registry",
+    "public docs site",
+    "opt-in automation plane"
+  ]
+}
diff --git a/examples/repo-descriptor.socios.jsonld b/examples/repo-descriptor.socios.jsonld
new file mode 100644
index 0000000..979a661
--- /dev/null
+++ b/examples/repo-descriptor.socios.jsonld
@@ -0,0 +1,31 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:socios",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "socios",
+  "description": "Opt-in community automation commons for SourceOS.",
+  "repositoryFullName": "SociOS-Linux/socios",
+  "repoUrl": "https://github.com/SociOS-Linux/socios",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleAutomationCommons",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "optionalLayerFor": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "base OS substrate",
+    "mandatory dependency of SourceOS",
+    "public docs site",
+    "canonical typed-contract registry"
+  ]
+}
diff --git a/examples/repo-descriptor.socioslinux-web.jsonld b/examples/repo-descriptor.socioslinux-web.jsonld
new file mode 100644
index 0000000..de1aa97
--- /dev/null
+++ b/examples/repo-descriptor.socioslinux-web.jsonld
@@ -0,0 +1,33 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:socioslinux-web",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "socioslinux-web",
+  "description": "Linux public web and docs surface for the Socios Linux stack.",
+  "repositoryFullName": "SociOS-Linux/socioslinux-web",
+  "repoUrl": "https://github.com/SociOS-Linux/socioslinux-web",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "rolePublicDocsSurface",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SocioProphet:socioprophet"
+  ],
+  "publicSurfaceFor": [
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SociOS-Linux:socios"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "workspace controller",
+    "image builder",
+    "immutable substrate",
+    "canonical typed-contract registry"
+  ]
+}
diff --git a/examples/repo-descriptor.sociosphere.jsonld b/examples/repo-descriptor.sociosphere.jsonld
new file mode 100644
index 0000000..dc197d2
--- /dev/null
+++ b/examples/repo-descriptor.sociosphere.jsonld
@@ -0,0 +1,29 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SocioProphet:sociosphere",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "sociosphere",
+  "description": "Platform meta-workspace controller for the broader SocioProphet platform.",
+  "repositoryFullName": "SocioProphet/sociosphere",
+  "repoUrl": "https://github.com/SocioProphet/sociosphere",
+  "organization": "SocioProphet",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "rolePlatformWorkspaceController",
+  "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:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:socioprophet",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "Linux image builder",
+    "immutable OS substrate",
+    "canonical typed-contract registry",
+    "public site"
+  ]
+}
diff --git a/examples/repo-descriptor.sourceos-spec.jsonld b/examples/repo-descriptor.sourceos-spec.jsonld
new file mode 100644
index 0000000..7a23f24
--- /dev/null
+++ b/examples/repo-descriptor.sourceos-spec.jsonld
@@ -0,0 +1,28 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "sourceos-spec",
+  "description": "Canonical typed-contract, JSON-LD, and shared vocabulary lane for SourceOS / AgentOS.",
+  "repositoryFullName": "SourceOS-Linux/sourceos-spec",
+  "repoUrl": "https://github.com/SourceOS-Linux/sourceos-spec",
+  "organization": "SourceOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleTypedContractRegistry",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "workspace controller",
+    "image builder",
+    "public docs site",
+    "opt-in automation plane"
+  ]
+}
diff --git a/examples/repo-descriptor.workstation-contracts.jsonld b/examples/repo-descriptor.workstation-contracts.jsonld
new file mode 100644
index 0000000..12d2621
--- /dev/null
+++ b/examples/repo-descriptor.workstation-contracts.jsonld
@@ -0,0 +1,27 @@
+{
+  "@context": "../semantic/context.jsonld",
+  "@id": "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "workstation-contracts",
+  "description": "Workstation and CI contract / conformance lane for Linux-first execution paths.",
+  "repositoryFullName": "SociOS-Linux/workstation-contracts",
+  "repoUrl": "https://github.com/SociOS-Linux/workstation-contracts",
+  "organization": "SociOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleWorkstationConformanceLane",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "runner or workspace controller",
+    "image builder",
+    "public docs site",
+    "opt-in automation commons"
+  ]
+}
diff --git a/schemas/repo_descriptor.schema.json b/schemas/repo_descriptor.schema.json
new file mode 100644
index 0000000..7e23c4f
--- /dev/null
+++ b/schemas/repo_descriptor.schema.json
@@ -0,0 +1,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:sourceos:schema:repo-descriptor:0.1.0",
+  "title": "RepoDescriptor",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "@context",
+    "@id",
+    "@type",
+    "name",
+    "description",
+    "repositoryFullName",
+    "repoUrl",
+    "organization",
+    "defaultBranch",
+    "semanticDescriptorVersion",
+    "topologyRole"
+  ],
+  "properties": {
+    "@context": {
+      "oneOf": [
+        { "type": "string" },
+        { "type": "object" },
+        { "type": "array" }
+      ]
+    },
+    "@id": {
+      "type": "string",
+      "minLength": 1
+    },
+    "@type": {
+      "oneOf": [
+        { "type": "string" },
+        {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      ]
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string",
+      "minLength": 1
+    },
+    "repositoryFullName": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
+    },
+    "repoUrl": {
+      "type": "string",
+      "format": "uri"
+    },
+    "organization": {
+      "type": "string",
+      "minLength": 1
+    },
+    "defaultBranch": {
+      "type": "string",
+      "minLength": 1
+    },
+    "semanticDescriptorVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
+    },
+    "topologyRole": {
+      "oneOf": [
+        { "type": "string", "minLength": 1 },
+        {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "minItems": 1,
+          "uniqueItems": true
+        }
+      ]
+    },
+    "connectsTo": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "dependsOn": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "implements": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "consumesVocabularyFrom": {
+      "type": "string",
+      "minLength": 1
+    },
+    "optionalLayerFor": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "publicSurfaceFor": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    },
+    "notThisRepo": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true
+    }
+  }
+}
diff --git a/semantic/context.jsonld b/semantic/context.jsonld
index 7d86a32..d0e4dee 100644
--- a/semantic/context.jsonld
+++ b/semantic/context.jsonld
@@ -1,70 +1,34 @@
 {
   "@context": {
-    "srcos": "https://schemas.srcos.ai/v2/",
-    "hydra": "http://www.w3.org/ns/hydra/core#",
-    "prov": "http://www.w3.org/ns/prov#",
+    "@version": 1.1,
+    "srcos": "urn:sourceos:repo-ontology:",
     "schema": "https://schema.org/",
     "id": "@id",
     "type": "@type",
-
-    "AgentSession": "srcos:AgentSession",
-    "Agreement": "srcos:Agreement",
-    "AuthorityLink": "srcos:AuthorityLink",
-    "CapabilityToken": "srcos:CapabilityToken",
-    "Comment": "srcos:Comment",
-    "Community": "srcos:Community",
-    "Connector": "srcos:Connector",
-    "DataRef": "srcos:DataRef",
-    "DataSphere": "srcos:DataSphere",
-    "Dataset": "srcos:Dataset",
-    "EntityField": "srcos:EntityField",
-    "EventEnvelope": "srcos:EventEnvelope",
-    "Exception": "srcos:Exception",
-    "ExecutionDecision": "srcos:ExecutionDecision",
-    "ExecutionSurface": "srcos:ExecutionSurface",
-    "ExperimentFlag": "srcos:ExperimentFlag",
-    "Field": "srcos:Field",
-    "FrustrationSignal": "srcos:FrustrationSignal",
-    "GlossaryTerm": "srcos:GlossaryTerm",
-    "Link": "srcos:Link",
-    "MappingEvidence": "srcos:MappingEvidence",
-    "MappingSpec": "srcos:MappingSpec",
-    "MemoryEntry": "srcos:MemoryEntry",
-    "ObjectContext": "srcos:ObjectContext",
-    "ObjectSelector": "srcos:ObjectSelector",
-    "Obligation": "srcos:Obligation",
-    "Party": "srcos:Party",
-    "PhysicalAsset": "srcos:PhysicalAsset",
-    "Policy": "srcos:Policy",
-    "PolicyBinding": "srcos:PolicyBinding",
-    "PolicyCondition": "srcos:PolicyCondition",
-    "PolicyDecision": "srcos:PolicyDecision",
-    "ProfileStats": "srcos:ProfileStats",
-    "ProvenanceRecord": "srcos:ProvenanceRecord",
-    "QualityMetric": "srcos:QualityMetric",
-    "Rating": "srcos:Rating",
-    "ReleaseReceipt": "srcos:ReleaseReceipt",
-    "RolloutPolicy": "srcos:RolloutPolicy",
-    "Rule": "srcos:Rule",
-    "RunRecord": "srcos:RunRecord",
-    "SchemaDefinition": "srcos:SchemaDefinition",
-    "SessionReceipt": "srcos:SessionReceipt",
-    "SessionReview": "srcos:SessionReview",
-    "SkillManifest": "srcos:SkillManifest",
-    "SubjectContext": "srcos:SubjectContext",
-    "SubjectSelector": "srcos:SubjectSelector",
-    "TagAssignment": "srcos:TagAssignment",
-    "TelemetryEvent": "srcos:TelemetryEvent",
-    "Trigger": "srcos:Trigger",
-    "ValidValues": "srcos:ValidValues",
-    "WorkflowEdge": "srcos:WorkflowEdge",
-    "WorkflowNode": "srcos:WorkflowNode",
-    "WorkflowSpec": "srcos:WorkflowSpec",
-    "WorkloadSpec": "srcos:WorkloadSpec",
-
-    "wasGeneratedBy": { "@id": "prov:wasGeneratedBy", "@type": "@id" },
-    "used":           { "@id": "prov:used",           "@type": "@id" },
-    "wasAssociatedWith": { "@id": "prov:wasAssociatedWith", "@type": "@id" },
-    "wasDerivedFrom":    { "@id": "prov:wasDerivedFrom",    "@type": "@id" }
+    "Repository": "srcos:Repository",
+    "RepoDescriptor": "srcos:RepoDescriptor",
+    "name": "schema:name",
+    "description": "schema:description",
+    "repositoryFullName": "srcos:repositoryFullName",
+    "repoUrl": { "@id": "srcos:repoUrl", "@type": "@id" },
+    "organization": "srcos:organization",
+    "defaultBranch": "srcos:defaultBranch",
+    "semanticDescriptorVersion": "srcos:semanticDescriptorVersion",
+    "topologyRole": { "@id": "srcos:topologyRole", "@type": "@id" },
+    "connectsTo": { "@id": "srcos:connectsTo", "@type": "@id" },
+    "dependsOn": { "@id": "srcos:dependsOn", "@type": "@id" },
+    "implements": { "@id": "srcos:implements", "@type": "@id" },
+    "consumesVocabularyFrom": { "@id": "srcos:consumesVocabularyFrom", "@type": "@id" },
+    "optionalLayerFor": { "@id": "srcos:optionalLayerFor", "@type": "@id" },
+    "publicSurfaceFor": { "@id": "srcos:publicSurfaceFor", "@type": "@id" },
+    "notThisRepo": "srcos:notThisRepo",
+    "rolePlatformWorkspaceController": "srcos:role/PlatformWorkspaceController",
+    "roleLinuxIntegrationSpine": "srcos:role/LinuxIntegrationSpine",
+    "roleTypedContractRegistry": "srcos:role/TypedContractRegistry",
+    "roleWorkstationConformanceLane": "srcos:role/WorkstationConformanceLane",
+    "roleAutomationCommons": "srcos:role/AutomationCommons",
+    "roleOSSubstrate": "srcos:role/OSSubstrate",
+    "rolePublicDocsSurface": "srcos:role/PublicDocsSurface",
+    "roleStarterScaffold": "srcos:role/StarterScaffold"
   }
 }
diff --git a/semantic/repo-ontology.jsonld b/semantic/repo-ontology.jsonld
new file mode 100644
index 0000000..55ed947
--- /dev/null
+++ b/semantic/repo-ontology.jsonld
@@ -0,0 +1,53 @@
+{
+  "@context": "./context.jsonld",
+  "@graph": [
+    {
+      "@id": "rolePlatformWorkspaceController",
+      "@type": "TopologyRole",
+      "name": "Platform Workspace Controller",
+      "description": "Meta-workspace controller responsible for manifest, lock, runner semantics, protocol fixtures, and deterministic multi-repo materialization across the broader platform."
+    },
+    {
+      "@id": "roleLinuxIntegrationSpine",
+      "@type": "TopologyRole",
+      "name": "Linux Integration Spine",
+      "description": "Linux-side integration and workspace spine that ties substrate, contracts, execution layers, automation, and public surfaces together without collapsing them into one repo."
+    },
+    {
+      "@id": "roleTypedContractRegistry",
+      "@type": "TopologyRole",
+      "name": "Typed Contract Registry",
+      "description": "Canonical home for typed contracts, JSON-LD contexts, vocabulary definitions, and machine-readable schemas consumed by adjacent repos."
+    },
+    {
+      "@id": "roleWorkstationConformanceLane",
+      "@type": "TopologyRole",
+      "name": "Workstation Conformance Lane",
+      "description": "Contract and conformance lane for workstation and CI execution paths. Defines validation gates but does not implement the runner/controller."
+    },
+    {
+      "@id": "roleAutomationCommons",
+      "@type": "TopologyRole",
+      "name": "Automation Commons",
+      "description": "Opt-in automation layer for CI/CD, update automation, training workflows, catalogs, signatures, and community build workflows."
+    },
+    {
+      "@id": "roleOSSubstrate",
+      "@type": "TopologyRole",
+      "name": "OS Substrate",
+      "description": "Immutable local-first operating-system substrate providing the base workstation and edge environment."
+    },
+    {
+      "@id": "rolePublicDocsSurface",
+      "@type": "TopologyRole",
+      "name": "Public Docs Surface",
+      "description": "Human-facing public website and documentation surface that explains adjacent substrate, controller, spec, and automation layers downstream."
+    },
+    {
+      "@id": "roleStarterScaffold",
+      "@type": "TopologyRole",
+      "name": "Starter Scaffold",
+      "description": "Bootstrap or starter repository for interfaces, policy, integration, or registry scaffolding. Not the canonical controller or spec lane."
+    }
+  ]
+}
diff --git a/semantic/repo.jsonld b/semantic/repo.jsonld
new file mode 100644
index 0000000..947e412
--- /dev/null
+++ b/semantic/repo.jsonld
@@ -0,0 +1,28 @@
+{
+  "@context": "./context.jsonld",
+  "@id": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "@type": ["RepoDescriptor", "Repository"],
+  "name": "sourceos-spec",
+  "description": "Canonical typed-contract, JSON-LD, and shared vocabulary lane for SourceOS / AgentOS.",
+  "repositoryFullName": "SourceOS-Linux/sourceos-spec",
+  "repoUrl": "https://github.com/SourceOS-Linux/sourceos-spec",
+  "organization": "SourceOS-Linux",
+  "defaultBranch": "main",
+  "semanticDescriptorVersion": "0.1.0",
+  "topologyRole": "roleTypedContractRegistry",
+  "connectsTo": [
+    "urn:sourceos:repo:SociOS-Linux:agentos-spine",
+    "urn:sourceos:repo:SociOS-Linux:workstation-contracts",
+    "urn:sourceos:repo:SociOS-Linux:SourceOS",
+    "urn:sourceos:repo:SociOS-Linux:socios",
+    "urn:sourceos:repo:SocioProphet:sociosphere",
+    "urn:sourceos:repo:SociOS-Linux:socioslinux-web"
+  ],
+  "consumesVocabularyFrom": "urn:sourceos:repo:SourceOS-Linux:sourceos-spec",
+  "notThisRepo": [
+    "workspace controller",
+    "image builder",
+    "public docs site",
+    "opt-in automation plane"
+  ]
+}