immich-api 0.2.1__tar.gz

immich_api-0.2.1/.bumpversion.cfg

@@ -0,0 +1,12 @@
+[bumpversion]
+current_version = 0.2.1
+commit = True
+tag = True
+
+[bumpversion:file:pyproject.toml]
+search = version = "{current_version}"
+replace = version = "{new_version}"
+
+[bumpversion:file(dockerpin0):docker/Dockerfile]
+search = immich-api[mcp]=={current_version}
+replace = immich-api[mcp]=={new_version}

immich_api-0.2.1/.config/spec-dashboard.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "sources": [{"glob": "specs/*/status.json", "kind": "spec"}]
+}

immich_api-0.2.1/.github/workflows/pages.yml

@@ -0,0 +1,25 @@
+name: Deploy GitHub Pages
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish-pages:
+    uses: Knuckles-Team/pipelines/.github/workflows/pages_pipeline.yml@main
+    with:
+      content_source: docs
+      shared_theme_enabled: true
+      agent_readiness_enabled: true
+      readiness_input: docs/agent-readiness.json
+      readiness_schema: docs/agent-readiness.schema.json
+      spec_dashboard_enabled: true
+      spec_dashboard_config: .config/spec-dashboard.json
+    permissions:
+      contents: read
+      pages: write
+      id-token: write

immich_api-0.2.1/.github/workflows/pipeline.yml

@@ -0,0 +1,27 @@
+name: Build|Upload|Release Python Package
+
+on:
+  push:
+    branches:
+      - 'main'
+
+permissions:
+  contents: read
+
+jobs:
+  publish-pypi:
+    uses: Knuckles-Team/pipelines/.github/workflows/python_pipeline.yml@main
+    permissions:
+      contents: write
+    secrets:
+      PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+  publish-docker:
+    needs: publish-pypi
+    uses: Knuckles-Team/pipelines/.github/workflows/container_pipeline.yml@main
+    permissions:
+      contents: read
+    secrets:
+      DOCKER_REGISTRY: ${{ secrets.DOCKER_REGISTRY }}
+      DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
+      DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}
+      DOCKER_REPOSITORY: ${{ secrets.DOCKER_REPOSITORY }}

immich_api-0.2.1/.github/workflows/scanners.yml

@@ -0,0 +1,42 @@
+name: Connector quality
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  checks:
+    # The runner supplies bootstrap Python, uv, pre-commit and approved scanners.
+    # Prepare project dependencies separately; never build scanners here.
+    runs-on: self-hosted
+    env:
+      MCP_FLEET_REGISTRATION: 'false'
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Capture provisioned hook runner
+        shell: bash
+        run: |
+          hook_runner="$(realpath "$(command -v pre-commit)")"
+          test -x "$hook_runner"
+          echo "CONNECTOR_PRE_COMMIT=$hook_runner" >> "$GITHUB_ENV"
+      - name: Select provisioned Python baseline
+        run: python scripts/select_python.py
+      - name: Prepare frozen project test environment
+        run: '"$CONNECTOR_BOOTSTRAP_PYTHON" scripts/bootstrap_environment.py --github'
+      - name: Validate hooks
+        run: '"$CONNECTOR_PRE_COMMIT" validate-config'
+      - name: Commit checks
+        run: '"$CONNECTOR_PRE_COMMIT" run --all-files --show-diff-on-failure'
+      - name: Push checks and generated connector tests
+        env:
+          PRE_COMMIT_FROM_REF: ${{ github.event.pull_request.base.sha || github.event.before }}
+          PRE_COMMIT_TO_REF: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: '"$CONNECTOR_PRE_COMMIT" run --all-files --hook-stage pre-push --show-diff-on-failure'

immich_api-0.2.1/.github/workflows/windows-ci.yml

@@ -0,0 +1,78 @@
+name: Cross-platform coverage
+
+# Report-only (continue-on-error on every step) -- does not touch
+# pipeline.yml/pages.yml. scripts/check_import_safety.py auto-detects this
+# package's import name from pyproject.toml's [project].name, so this file
+# needs no per-package templating. See that script's own docstring for
+# exactly what --simulate-windows does and does not model, and its
+# sys.platform-guard false-positive limitation -- if this package
+# legitimately guards a POSIX-only import behind
+# `sys.platform == "win32"`, add `--exclude <dotted.module.name>` to BOTH
+# this file's windows job below and .pre-commit-config.yaml's
+# check-import-safety hook.
+
+on:
+  pull_request:
+    paths:
+      - 'immich_api/**'
+      - 'scripts/**'
+      - 'tests/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/windows-ci.yml'
+  push:
+    branches:
+      - 'main'
+
+permissions:
+  contents: read
+
+jobs:
+  windows:
+    name: Windows coverage (report only, never blocks)
+    runs-on: windows-latest
+    permissions:
+      contents: read
+    defaults:
+      run:
+        shell: bash
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.12'
+
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          version: '0.11.7'
+          enable-cache: true
+          cache-dependency-glob: uv.lock
+
+      - name: Sync test environment
+        id: sync
+        continue-on-error: true
+        run: |
+          uv sync --extra test
+          echo "$PWD/.venv/Scripts" >> "$GITHUB_PATH"
+          echo "$PWD/.venv/bin" >> "$GITHUB_PATH"
+
+      - name: Cross-platform import safety (real Windows interpreter)
+        if: steps.sync.outcome == 'success'
+        continue-on-error: true
+        run: python3 scripts/check_import_safety.py
+
+      - name: Unit tests
+        if: steps.sync.outcome == 'success'
+        continue-on-error: true
+        run: python3 -m pytest tests -q --tb=short --timeout=120
+
+      - name: Windows coverage summary
+        if: always()
+        run: |
+          echo "## Windows coverage ran in report-only mode" >> "$GITHUB_STEP_SUMMARY"
+          echo "Both steps above use continue-on-error: true -- a red step" >> "$GITHUB_STEP_SUMMARY"
+          echo "here is a real Windows regression and never blocks the" >> "$GITHUB_STEP_SUMMARY"
+          echo "publish pipeline." >> "$GITHUB_STEP_SUMMARY"

immich_api-0.2.1/.pipeline-theme/provenance.json

@@ -0,0 +1,32 @@
+{
+  "file_hash_scope": "files records current vendored bytes; repository and revision identify the upstream source before any listed local derivations.",
+  "files": {
+    "scripts/sync_mkdocs_theme.py": "047dbd23cc46f1e8d0842d1518d404b01826a0fbe6cbcb881ca9ab424a5ffc0e",
+    "templates/mkdocs-theme/README.md": "5e0e109a935ce3a0ffc0f425e7086cc60ba69a3611213451556dc851abfb38f3",
+    "templates/mkdocs-theme/assets/brands/agent-connector-sdk-logo-v1.png": "6688810468a77118ee1960ac3872816c6ace4f750a849688d306d7a63132e1b1",
+    "templates/mkdocs-theme/assets/brands/agent-terminal-ui-logo-v1.png": "d5e3c011066e2241c09c885f65d9a07c6ff32f4244b00dbe8e7550a3bab20dc8",
+    "templates/mkdocs-theme/assets/brands/agent-utilities-logo-v1.png": "923319a3b89fa1fbd14ca14c27cf49d2e2d9f85bc45456e05b788692700f0103",
+    "templates/mkdocs-theme/assets/brands/agent-webui-logo-v1.png": "3939a7324f134c520fd544aadd2a37c99abba9db78dd2bf3fd5003ffd62502ff",
+    "templates/mkdocs-theme/assets/brands/epistemic-graph-logo-v1.png": "26671aef2c3b78ecdcca2ad13adfd266cebf8d7e666e614c2d83d166b853d272",
+    "templates/mkdocs-theme/assets/brands/geniusbot-logo-v1.png": "c4a17404f234f677496197ac202ca8fb30b136c5a69243811bbfa6e5d5352b28",
+    "templates/mkdocs-theme/assets/brands/graph-os-logo-v1.png": "bba183368e42927edea91013639311a5d64f5a9910ec2f1bdcc7f4cd32f9d230",
+    "templates/mkdocs-theme/assets/favicon.svg": "aa606f9668a363bfe533f7d835700c246efaed0b8895cce5fe4398f36c35e7ba",
+    "templates/mkdocs-theme/assets/graph-mark.svg": "d0c69cdc06aa51439b6ce04b4c6df4dbf02283329f01122a78e08f286186e25d",
+    "templates/mkdocs-theme/assets/runtime-architecture.mmd": "7fcbaed9a8fa8acbc1c30cccf31035e0d7048db9db45a73467f2e8faef7bc3cc",
+    "templates/mkdocs-theme/assets/runtime-architecture.svg": "2ecd201c6b7a170924195ce5578394f88365d3a539be4ece17aca15a439aef47",
+    "templates/mkdocs-theme/base.mkdocs.yml": "e324b30874e57ebe09a2ee0e7ae4a303e52dce808be1e7075dc3b445ad1e6bad",
+    "templates/mkdocs-theme/extra.css": "2cc17b7610b67c82895312e7e61cf84587a6fe291bbc154d3c83c59fba2ee843",
+    "templates/mkdocs-theme/glossary.md": "0c01322fff633a1d420fa3b0f4ee246124802f6b33bb0d4827b5d12fb9b56e09",
+    "templates/mkdocs-theme/overrides/main.html": "766234b5045a5815805bb2ce5223ddd93729f7854abc4b6cdf4fba9c7e0dab3b"
+  },
+  "local_derivations": {
+    "scripts/sync_mkdocs_theme.py": {
+      "derived_sha256": "047dbd23cc46f1e8d0842d1518d404b01826a0fbe6cbcb881ca9ab424a5ffc0e",
+      "review": "Upstream and derived Python ASTs are identical; no executable behavior change.",
+      "transformation": "Ruff 0.15.12 formatting using the consumer project line length of 88.",
+      "upstream_sha256": "2c48e594035288b14dda106f3cbdc745f9485c84297e3e34db398a41d57c3d60"
+    }
+  },
+  "repository": "https://github.com/Knuckles-Team/pipelines",
+  "revision": "7b3d18d72b5622d455ece3bbe45a9482bc6e8b5e"
+}

immich_api-0.2.1/.pipeline-theme/scripts/sync_mkdocs_theme.py

@@ -0,0 +1,207 @@
+"""Synchronize generated ecosystem MkDocs theme files into a consumer repo."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+
+@dataclass(frozen=True)
+class ThemeFile:
+    """A canonical source file and its generated consumer-relative path."""
+
+    source: str
+    destination: str
+    content_relative: bool = True
+
+
+THEME_FILES = (
+    ThemeFile("extra.css", "stylesheets/extra.css"),
+    ThemeFile("assets/graph-mark.svg", "assets/graph-mark.svg"),
+    ThemeFile("assets/favicon.svg", "assets/favicon.svg"),
+    ThemeFile("assets/runtime-architecture.mmd", "assets/runtime-architecture.mmd"),
+    ThemeFile("assets/runtime-architecture.svg", "assets/runtime-architecture.svg"),
+    ThemeFile(
+        "assets/brands/epistemic-graph-logo-v1.png",
+        "assets/brands/epistemic-graph-logo-v1.png",
+    ),
+    ThemeFile(
+        "assets/brands/agent-utilities-logo-v1.png",
+        "assets/brands/agent-utilities-logo-v1.png",
+    ),
+    ThemeFile(
+        "assets/brands/graph-os-logo-v1.png", "assets/brands/graph-os-logo-v1.png"
+    ),
+    ThemeFile(
+        "assets/brands/agent-connector-sdk-logo-v1.png",
+        "assets/brands/agent-connector-sdk-logo-v1.png",
+    ),
+    ThemeFile(
+        "assets/brands/agent-webui-logo-v1.png",
+        "assets/brands/agent-webui-logo-v1.png",
+    ),
+    ThemeFile(
+        "assets/brands/geniusbot-logo-v1.png", "assets/brands/geniusbot-logo-v1.png"
+    ),
+    ThemeFile(
+        "assets/brands/agent-terminal-ui-logo-v1.png",
+        "assets/brands/agent-terminal-ui-logo-v1.png",
+    ),
+    ThemeFile("glossary.md", "glossary.md"),
+)
+
+
+RUNTIME_PROVENANCE = re.compile(
+    rb"<!-- Generated compatibility copy; do not edit\.\n"
+    rb"Source: https://raw\.githubusercontent\.com/Knuckles-Team/epistemic-graph/"
+    rb"[0-9a-f]{40}/docs/assets/runtime-architecture\.svg\n"
+    rb"SHA-256: (?P<digest>[0-9a-f]{64})\n"
+    rb"Synchronize: https://github\.com/Knuckles-Team/\.github/blob/main/docs/runtime-diagram\.md\n"
+    rb"-->\n(?P<payload>.*)",
+    re.DOTALL,
+)
+
+
+class ThemeSyncError(Exception):
+    """The source, destination, or content-source contract is invalid."""
+
+
+def _safe_relative_path(value: str, label: str) -> Path:
+    path = Path(value)
+    if (
+        path.is_absolute()
+        or not path.parts
+        or any(part in {".", ".."} for part in path.parts)
+    ):
+        raise ThemeSyncError(f"{label} must be a contained relative path")
+    return path
+
+
+def _contained(root: Path, relative: Path, label: str) -> Path:
+    base = root.resolve()
+    result = (base / relative).resolve()
+    if not result.is_relative_to(base):
+        raise ThemeSyncError(f"{label} escapes the repository root")
+    return result
+
+
+def _check_file(destination: Path, expected: bytes, repository: Path) -> str | None:
+    """Describe how ``destination`` diverges from ``expected``, or ``None`` when it matches."""
+    try:
+        actual = destination.read_bytes()
+    except OSError:
+        return f"missing generated file: {destination.relative_to(repository)}"
+    if actual != expected:
+        return f"generated file differs: {destination.relative_to(repository)}"
+    return None
+
+
+def _runtime_diagram_content(destination: Path, expected: bytes) -> bytes:
+    """Keep the canonical sync tool's provenance without accepting SVG drift."""
+    if not destination.is_file():
+        return expected
+    actual = destination.read_bytes()
+    if not actual.startswith(b"<!--"):
+        return expected
+    provenance = RUNTIME_PROVENANCE.fullmatch(actual)
+    if (
+        provenance is None
+        or provenance["digest"] != hashlib.sha256(expected).hexdigest().encode()
+        or provenance["payload"] != expected
+    ):
+        raise ThemeSyncError(
+            "runtime diagram provenance or payload differs; use the canonical "
+            "sync guide: https://github.com/Knuckles-Team/.github/blob/main/docs/runtime-diagram.md"
+        )
+    return actual
+
+
+def _expected_content(item: ThemeFile, source_file: Path, destination: Path) -> bytes:
+    """Resolve exact theme bytes while preserving validated runtime provenance."""
+    expected = source_file.read_bytes()
+    if item.source == "assets/runtime-architecture.svg":
+        return _runtime_diagram_content(destination, expected)
+    return expected
+
+
+def sync_theme(
+    *,
+    source_root: Path,
+    repository_root: Path,
+    content_source: str,
+    mode: Literal["sync", "check"],
+) -> list[str]:
+    """Copy canonical files in ``sync`` mode or return mismatches in ``check`` mode."""
+    content_relative = _safe_relative_path(content_source, "content-source")
+    repository = repository_root.resolve()
+    content_root = _contained(repository, content_relative, "content-source")
+    source = (source_root / "templates" / "mkdocs-theme").resolve()
+    if not source.is_dir():
+        raise ThemeSyncError(f"canonical theme directory does not exist: {source}")
+
+    mismatches: list[str] = []
+    for item in THEME_FILES:
+        source_file = source / item.source
+        if not source_file.is_file():
+            raise ThemeSyncError(f"canonical theme file does not exist: {source_file}")
+        destination_root = content_root if item.content_relative else repository
+        destination = _contained(
+            destination_root, Path(item.destination), item.destination
+        )
+        expected = _expected_content(item, source_file, destination)
+        if mode == "check":
+            mismatch = _check_file(destination, expected, repository)
+            if mismatch:
+                mismatches.append(mismatch)
+            continue
+
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_bytes(expected)
+
+    return mismatches
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("mode", choices=("sync", "check"))
+    parser.add_argument(
+        "--root", type=Path, default=Path.cwd(), help="consumer repository root"
+    )
+    parser.add_argument(
+        "--content-source",
+        default="docs",
+        help="consumer MkDocs content directory (normally docs or pages)",
+    )
+    parser.add_argument(
+        "--source-root",
+        type=Path,
+        default=Path(__file__).resolve().parents[1],
+        help="pipelines checkout containing templates/mkdocs-theme",
+    )
+    args = parser.parse_args(argv)
+    try:
+        mismatches = sync_theme(
+            source_root=args.source_root,
+            repository_root=args.root,
+            content_source=args.content_source,
+            mode=args.mode,
+        )
+    except (OSError, ThemeSyncError) as exc:
+        print(f"shared MkDocs theme: CANNOT RUN: {exc}", file=sys.stderr)
+        return 2
+    if mismatches:
+        print("shared MkDocs theme: generated files are out of sync:", file=sys.stderr)
+        for mismatch in mismatches:
+            print(f"  - {mismatch}", file=sys.stderr)
+        return 1
+    print(f"shared MkDocs theme: {args.mode} complete")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

immich_api-0.2.1/.pipeline-theme/templates/mkdocs-theme/README.md

@@ -0,0 +1,23 @@
+# Shared MkDocs theme
+
+This folder is the canonical source for the five ecosystem documentation sites. `scripts/sync_mkdocs_theme.py` copies its generated files into a consuming repository and checks that committed copies are byte-identical.
+
+## Generated files
+
+| Source | Consumer path |
+| --- | --- |
+| `extra.css` | `<content-source>/stylesheets/extra.css` |
+| `overrides/main.html` | not synced: `custom_dir` serves it from the theme checkout (`.pipeline-theme/templates/mkdocs-theme/overrides`) |
+| `assets/*` | `<content-source>/assets/*` |
+| `glossary.md` | `<content-source>/glossary.md` |
+| `base.mkdocs.yml` | inherited directly from the pinned pipelines checkout |
+
+`<content-source>` is the explicitly declared `docs` or `pages` directory. Run `python scripts/sync_mkdocs_theme.py sync --root REPOSITORY --content-source docs` to update files, and the same command with `check` to check exact equality without writing. The Pages workflow checks the committed assets against its immutable workflow checkout before building.
+
+## MkDocs configuration
+
+The repository's `mkdocs.yml` inherits `templates/mkdocs-theme/base.mkdocs.yml` and supplies `extra.ecosystem.current` with its own slug (`agent-webui`, `graph-os`, `agent-utilities`, `epistemic-graph`, or `agent-connector-sdk`). It continues to own its site name, URL, content directory, and navigation. For local builds, check out the exact pinned `pipelines` revision into `.pipeline-theme`, run the `sync` command above, then run `mkdocs build --strict`.
+
+Use `.site-hero`, `.site-card-grid` / `.site-card`, `.site-ownership__grid` / `.site-ownership__item`, and the ordered `.site-flow` components for landing-page structure. Prefer semantic HTML and retain visible keyboard focus. The common theme uses native `<details>` for the site switcher and does not require custom JavaScript.
+
+The root `README.md` remains the short entry point. It keeps its exact ordered headings: Overview, Key capabilities, Documentation, Architecture, Quick start, Contributing, License. Deep reference material belongs in Pages. Public home pages describe the current bundled ecosystem in present tense. They contain no planning, migration, worktree, or future-release status.

immich_api-0.2.1/.pipeline-theme/templates/mkdocs-theme/assets/favicon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <rect width="64" height="64" rx="14" fill="#f1f5fb"/>
+  <g fill="none" stroke="#2a5ca8" stroke-linecap="round" stroke-width="5">
+    <path d="M16 18 32 10l16 9v26l-16 9-16-9z"/>
+    <path d="m16 18 16 9 16-8M32 27v27M16 45l16-18 16 18"/>
+  </g>
+  <g fill="#e6a23a" stroke="#f1f5fb" stroke-width="2">
+    <circle cx="16" cy="18" r="6"/><circle cx="32" cy="10" r="6"/>
+    <circle cx="48" cy="19" r="6"/><circle cx="16" cy="45" r="6"/>
+    <circle cx="32" cy="54" r="6"/><circle cx="48" cy="45" r="6"/>
+    <circle cx="32" cy="27" r="6"/>
+  </g>
+</svg>

immich_api-0.2.1/.pipeline-theme/templates/mkdocs-theme/assets/graph-mark.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" role="img" aria-labelledby="title">
+  <title id="title">Knuckles-Team graph mark</title>
+  <g fill="none" stroke="#2a5ca8" stroke-linecap="round" stroke-width="5">
+    <path d="M16 18 32 10l16 9v26l-16 9-16-9z"/>
+    <path d="m16 18 16 9 16-8M32 27v27M16 45l16-18 16 18"/>
+  </g>
+  <g fill="#e6a23a" stroke="#fff" stroke-width="2">
+    <circle cx="16" cy="18" r="6"/><circle cx="32" cy="10" r="6"/>
+    <circle cx="48" cy="19" r="6"/><circle cx="16" cy="45" r="6"/>
+    <circle cx="32" cy="54" r="6"/><circle cx="48" cy="45" r="6"/>
+    <circle cx="32" cy="27" r="6"/>
+  </g>
+</svg>

immich_api-0.2.1/.pipeline-theme/templates/mkdocs-theme/assets/runtime-architecture.mmd

@@ -0,0 +1,26 @@
+flowchart LR
+  People["People"]
+  WebUI["Graph OS web UI<br/>browser experience"]
+  TUI["Agent Terminal UI<br/>REST capabilities"]
+  Genius["Geniusbot<br/>desktop cockpit"]
+  Messaging["Messaging channels<br/>chat and voice"]
+  Clients["MCP / REST / A2A clients"]
+  GraphOS["Graph OS<br/>governed runtime gateway and composition host"]
+  AU["Agent Utilities<br/>agent control plane"]
+  EG["Epistemic Graph<br/>durable multimodal knowledge and reasoning engine"]
+  Sources["Source systems"]
+  SDK["Agent Connector SDK<br/>typed source integration"]
+
+  People --> WebUI
+  People --> TUI
+  People --> Genius
+  People --> Messaging
+  Clients --> GraphOS
+  WebUI --> GraphOS
+  TUI -->|REST| GraphOS
+  Genius --> GraphOS
+  Messaging -->|hosted co-service| GraphOS
+  GraphOS --> AU
+  AU --> EG
+  Sources --> SDK
+  SDK --> EG

immich_api-0.2.1/.pipeline-theme/templates/mkdocs-theme/assets/runtime-architecture.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1320 700" role="img" aria-labelledby="diagram-title diagram-description">
+  <title id="diagram-title">Knuckles-Team agent ecosystem runtime architecture</title>
+  <desc id="diagram-description">People use Graph OS web UI, Agent Terminal UI, Geniusbot, or messaging channels. MCP, REST, and A2A clients also enter through Graph OS. Graph OS is the governed gateway and composition host, Agent Utilities is the agent control plane, and Epistemic Graph is the durable multimodal knowledge and reasoning engine. Source systems connect through Agent Connector SDK.</desc>
+  <defs>
+    <linearGradient id="gateway-light" x1="0" x2="1"><stop stop-color="#e5f4ff"/><stop offset="1" stop-color="#e7fff5"/></linearGradient>
+    <linearGradient id="core-light" x1="0" x2="1"><stop stop-color="#eef0ff"/><stop offset="1" stop-color="#f3eaff"/></linearGradient>
+    <linearGradient id="gateway-dark" x1="0" x2="1"><stop stop-color="#173344"/><stop offset="1" stop-color="#153b36"/></linearGradient>
+    <linearGradient id="core-dark" x1="0" x2="1"><stop stop-color="#242c4b"/><stop offset="1" stop-color="#332646"/></linearGradient>
+    <marker id="arrow" markerWidth="10" markerHeight="10" refX="10" refY="5" orient="auto" markerUnits="strokeWidth"><path class="arrowhead" d="M0 0 10 5 0 10z"/></marker>
+    <style>
+      .bg{fill:none}.box{fill:#f5f8fc;stroke:#58769b;stroke-width:2}.entry{fill:#f7fbff;stroke:#2f75b5;stroke-width:2}.gateway{fill:url(#gateway-light);stroke:#087f6d;stroke-width:3}.core{fill:url(#core-light);stroke:#5b4cc4;stroke-width:2.5}.label{font:700 18px system-ui,-apple-system,Segoe UI,sans-serif;fill:#14243b;text-anchor:middle}.role{font:14px system-ui,-apple-system,Segoe UI,sans-serif;fill:#435773;text-anchor:middle}.small{font:13px system-ui,-apple-system,Segoe UI,sans-serif;fill:#526780;text-anchor:middle}.arrow,.bus{fill:none;stroke:#58769b;stroke-width:2.5}.arrow{marker-end:url(#arrow)}.arrowhead{fill:#365f93}
+      @media (prefers-color-scheme: light){.bg{fill:none}.box{fill:#f5f8fc;stroke:#58769b}.entry{fill:#f7fbff;stroke:#2f75b5}.gateway{fill:url(#gateway-light);stroke:#087f6d}.core{fill:url(#core-light);stroke:#5b4cc4}.label{fill:#14243b}.role{fill:#435773}.small{fill:#526780}.arrow,.bus{stroke:#58769b}.arrowhead{fill:#365f93}}
+      @media (prefers-color-scheme: dark){.bg{fill:none}.box{fill:#172338;stroke:#778ca9}.entry{fill:#192b43;stroke:#76aee9}.gateway{fill:url(#gateway-dark);stroke:#63d8b5}.core{fill:url(#core-dark);stroke:#b5a5ff}.label{fill:#f3f7ff}.role{fill:#d1dced}.small{fill:#b7c6dc}.arrow,.bus{stroke:#c2cee2}.arrowhead{fill:#d8e2f1}}
+    </style>
+  </defs>
+  <rect class="bg" width="1320" height="700" rx="24" fill="none"/>
+  <g>
+    <rect class="box" x="35" y="35" width="170" height="55" rx="14"/><text class="label" x="120" y="69">People</text>
+    <rect class="entry" x="35" y="135" width="170" height="90" rx="16"/><text class="label" x="120" y="172">Graph OS web UI</text><text class="role" x="120" y="198">browser experience</text>
+    <rect class="entry" x="225" y="135" width="170" height="90" rx="16"/><text class="label" x="310" y="169">Agent Terminal UI</text><text class="role" x="310" y="198">REST operations</text>
+    <rect class="entry" x="415" y="135" width="170" height="90" rx="16"/><text class="label" x="500" y="172">Geniusbot</text><text class="role" x="500" y="198">desktop cockpit</text>
+    <rect class="entry" x="605" y="135" width="175" height="90" rx="16"/><text class="label" x="692" y="169">Messaging</text><text class="role" x="692" y="194">chat + voice channels</text><text class="small" x="692" y="214">hosted by Graph OS</text>
+    <rect class="box" x="415" y="245" width="365" height="80" rx="16"/><text class="label" x="597.5" y="280">MCP / REST / A2A clients</text><text class="role" x="597.5" y="305">external agents and applications</text>
+    <rect class="gateway" x="825" y="135" width="450" height="170" rx="22"/><text class="label" x="1050" y="198">Graph OS</text><text class="role" x="1050" y="230">governed runtime gateway</text><text class="role" x="1050" y="255">and composition host</text>
+    <rect class="core" x="825" y="335" width="450" height="100" rx="18"/><text class="label" x="1050" y="376">Agent Utilities</text><text class="role" x="1050" y="405">agent control plane</text>
+    <rect class="core" x="825" y="485" width="450" height="125" rx="18"/><text class="label" x="1050" y="528">Epistemic Graph</text><text class="role" x="1050" y="558">durable multimodal knowledge, evidence,</text><text class="role" x="1050" y="582">provenance, and reasoning engine</text>
+    <rect class="box" x="35" y="520" width="220" height="90" rx="16"/><text class="label" x="145" y="557">Source systems</text><text class="role" x="145" y="583">governed external data</text>
+    <rect class="box" x="445" y="520" width="260" height="90" rx="16"/><text class="label" x="575" y="557">Agent Connector SDK</text><text class="role" x="575" y="583">typed source integration</text>
+  </g>
+  <g class="connections">
+    <path class="bus" d="M120 90V100H692"/>
+    <path class="arrow" d="M120 100V135"/><path class="arrow" d="M310 100V135"/><path class="arrow" d="M500 100V135"/><path class="arrow" d="M692 100V135"/>
+    <path class="arrow" d="M780 180H825"/><path class="arrow" d="M780 285H825"/>
+    <path class="arrow" d="M1050 305V335"/><path class="arrow" d="M1050 435V485"/>
+    <path class="arrow" d="M255 565H445"/><path class="arrow" d="M705 565H825"/>
+  </g>
+</svg>