From b6667d81995732024d3912d5c021466d4523d326 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:45:06 -0400
Subject: [PATCH 1/4] feat(runtime): add sourceos-docd service scaffold

---
 modules/nixos/sourceos-shell/default.nix | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/modules/nixos/sourceos-shell/default.nix b/modules/nixos/sourceos-shell/default.nix
index 7ae9e9a..08de019 100644
--- a/modules/nixos/sourceos-shell/default.nix
+++ b/modules/nixos/sourceos-shell/default.nix
@@ -73,5 +73,14 @@ in
         ExecStart = "${pkgs.coreutils}/bin/echo sourceos-pdf-secure placeholder port=${toString cfg.pdfSecurePort}";
       };
     };
+
+    systemd.services.sourceos-docd = {
+      description = "SourceOS shell docd scaffold";
+      wantedBy = [ "multi-user.target" ];
+      serviceConfig = {
+        Type = "simple";
+        ExecStart = "${pkgs.coreutils}/bin/echo sourceos-docd placeholder port=${toString cfg.docdPort}";
+      };
+    };
   };
 }

From a26bd667d6087b5c28d70b067503d572539bed27 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:47:09 -0400
Subject: [PATCH 2/4] feat(runtime): add sourceos-docd systemd unit scaffold

---
 linux/systemd/sourceos-docd.service | 13 +++++++++++++
 1 file changed, 13 insertions(+)
 create mode 100644 linux/systemd/sourceos-docd.service

diff --git a/linux/systemd/sourceos-docd.service b/linux/systemd/sourceos-docd.service
new file mode 100644
index 0000000..b34e30c
--- /dev/null
+++ b/linux/systemd/sourceos-docd.service
@@ -0,0 +1,13 @@
+[Unit]
+Description=SourceOS docd derive service
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=/opt/sourceos-shell/bin/sourceos-docd
+Restart=on-failure
+RestartSec=2s
+
+[Install]
+WantedBy=multi-user.target

From c87a6de041007061d35ad9cfd62d9a5b0656aba7 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:48:12 -0400
Subject: [PATCH 3/4] test(runtime): extend sourceos-shell contract check for
 docd scaffold

---
 tests/sourceos-shell-module-contract.nix | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/sourceos-shell-module-contract.nix b/tests/sourceos-shell-module-contract.nix
index 57ce469..8126ea8 100644
--- a/tests/sourceos-shell-module-contract.nix
+++ b/tests/sourceos-shell-module-contract.nix
@@ -8,8 +8,10 @@ pkgs.runCommand "sourceos-shell-module-contract" {
   test -f ${../linux/systemd/sourceos-shell.service}
   test -f ${../linux/systemd/sourceos-router.service}
   test -f ${../linux/systemd/sourceos-pdf-secure.service}
+  test -f ${../linux/systemd/sourceos-docd.service}
   grep -q '../../modules/nixos/sourceos-shell/default.nix' ${../profiles/linux-dev/sourceos-shell.nix}
   grep -q 'sourceos.shell' ${../modules/nixos/sourceos-shell/default.nix}
+  grep -q 'sourceos-docd' ${../modules/nixos/sourceos-shell/default.nix}
   mkdir -p $out
   echo validated > $out/result.txt
 ''

From 09646f792d93d221b3a7e34c16d412b719deab45 Mon Sep 17 00:00:00 2001
From: mdheller <21163552+mdheller@users.noreply.github.com>
Date: Wed, 22 Apr 2026 14:51:28 -0400
Subject: [PATCH 4/4] docs(runtime): mention docd derive service in shell
 integration note

---
 docs/sourceos-shell-integration.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docs/sourceos-shell-integration.md b/docs/sourceos-shell-integration.md
index b0be40a..9f365a9 100644
--- a/docs/sourceos-shell-integration.md
+++ b/docs/sourceos-shell-integration.md
@@ -11,6 +11,7 @@ This repository, `source-os`, carries the Linux realization surfaces required to
 - Nix/NixOS modules
 - profile wiring
 - machine-level integration hooks
+- derive-service runtime integration such as `docd`
 
 ## What does not belong here