docs: clarify repo topology and connected surfaces

.markdownlint.json

@@ -0,0 +1,4 @@
+{
+  "default": true,
+  "MD013": false
+}

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-## Contributing
+# Contributing
 
 - Spec-first: changes that affect behavior must update spec/.
 - Keep SourceOS independent of socios by default.

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`.

SECURITY.md

@@ -1,4 +1,4 @@
-## Security
+# Security
 
 Report vulnerabilities privately.
 

caps/semantic-search-bi/docs/README.md

@@ -4,20 +4,25 @@ Canonical upstream for this contract package now lives in `SocioProphet/sherlock
 This SourceOS copy is retained as a mirror/reference so local docs and tooling do not break, but changes should land upstream first.
 
 This package defines contracts for a semantic search capability:
+
 - triRPC service surface (rpc/semantic.search.v0.yaml)
 - topic taxonomy for event bus integration (topics/*.yaml)
 - JSON Schemas for payload validation (schemas/*.json)
 - a local validator (tools/validate_package.py)
 
 ## Non-goals
+
 This package does **not** ship any runtime implementation.
 Implementations live in separate packages and MUST:
+
 1) enforce a policy guard (default deny)
 2) emit governance evidence events
 3) speak triRPC for all method surfaces
 
 ## Optional backends
+
 Implementations MAY provide:
+
 - Lexical inverted index (e.g., Xapian)
 - Vector ANN index (e.g., FAISS/HNSW)
 - Symbolic graph store (e.g., AtomSpace)

docs/BOUNDARIES.md

@@ -1,4 +1,4 @@
-## Boundaries
+# Boundaries
 
 - SourceOS: OS + local policy/attestations.
 - socios: opt-in community automation layer (updates/CI/CD/training).

docs/adr/0001-silverblue-toolbx-flatpak-podman.md

@@ -3,15 +3,18 @@
 Status: proposed
 
 Decision:
+
 - Use Fedora Silverblue (GNOME) as workstation base.
 - Use Toolbx for dev environments.
 - Use Flatpak for GUI apps.
 - Use rootless Podman for services.
 
 Why:
+
 - Immutable base reduces drift.
 - User-space isolation avoids breaking system environments (PEP 668-style issues).
 - Sandboxed GUI reduces app-level blast radius.
 
 Consequences:
+
 - We must provide first-class tooling to make user-space ergonomics excellent.

docs/compression-commons/v0/README.md

@@ -1 +1,9 @@
-# Compression Commons (v0)\n\nUnifies:\n- Vanity Press Economy metrics (subsidy gradient, seigniorage, paper-mill equilibrium)\n- Lawful Learning constraints (projection to feasibility + replay evidence)\n- SourceOS enforcement (CapD + Triune RPC + policy guards + evidence ledger)\n\nThis module defines contracts first; reference implementations are optional.\n
+# Compression Commons (v0)
+
+Unifies:
+
+- Vanity Press Economy metrics (subsidy gradient, seigniorage, paper-mill equilibrium)
+- Lawful Learning constraints (projection to feasibility + replay evidence)
+- SourceOS enforcement (CapD + Triune RPC + policy guards + evidence ledger)
+
+This module defines contracts first; reference implementations are optional.

docs/semantic-search/README.md

@@ -7,18 +7,22 @@ When updating the semantic-search contract, update `sherlock-search` first and t
 This directory explains the **Semantic Search** capability contract in plain English.
 
 ## What this is
+
 This package defines a **contract-only capability**: it specifies *interfaces* (schemas, RPC surface, topics, governance hooks),
 but **does not ship an implementation**. It’s like a “power outlet standard” — vendors can build compatible devices, but the
 contract itself isn’t the device.
 
 ## Why we do it this way
+
 We want capabilities that are:
+
 - **Composable**: other capabilities can depend on this one without importing a specific engine.
 - **Auditable**: every call can be policy-guarded and emits evidence events.
 - **Replaceable**: Xapian/FAISS/AtomSpace/etc. are optional implementations behind the same stable interface.
 - **Linux-first** and open-source-only.
 
 ## What’s in the contract package
+
 The capability contract is defined by these folders:
 
 - `capd/` (if present): Capability descriptor (identity, version, requirements, compatibility rules).
@@ -28,19 +32,24 @@ The capability contract is defined by these folders:
 - `tools/validate_package.py`: A local validator that ensures the contract package is structurally sane.
 
 ## Governance requirements (non-negotiable)
+
 Every implementation of this contract MUST:
+
 1) Enforce **policy guards** (default deny) for ingest/query/delete.
 2) Emit **evidence events** for every meaningful action (ingest accepted/rejected, query executed, results delivered, deletes).
 3) Support **quota + identity hooks** (caller identity / tenant / namespace).
 4) Be compatible with triRPC request/response schema validation.
 
 ## How to read the contract
+
 Start at:
+
 - `rpc/semantic.search.v0.yaml` — the canonical RPC surface
 - `schemas/query_request.schema.json` and `schemas/query_response.schema.json`
 - `schemas/evidence_event.schema.json` — what we log as auditable evidence
 - `topics/semantic.search.topics.v0.yaml` — pubsub surfaces
 
 ## “BI” naming note
+
 If the folder is `caps/semantic-search-bi`, “bi” should mean *behavioral indexing* (or whatever we intended),
 not “business intelligence”. If that’s not what we mean, we should rename now while it’s early.

docs/semantic-search/UPSTREAM.md

@@ -3,9 +3,11 @@
 Canonical repository: `SocioProphet/sherlock-search`
 
 Canonical PR that moved ownership upstream:
+
 - `SocioProphet/sherlock-search#1`
 
 Policy for updates:
+
 1. Change the contract in `sherlock-search` first.
 2. Validate there.
 3. Mirror here only if SourceOS needs a local reference copy.

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"
+  ]
+}

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}}