From d51c60c30e7f67e644db0bc5eadea9f0392481ca Mon Sep 17 00:00:00 2001
From: Martin Fischer <martin@push-f.com>
Date: Wed, 7 Oct 2026 06:59:42 +0200
Subject: feat(workstation): add /doc

---
 nixos/profiles/workstation/default.nix |  1 +
 nixos/profiles/workstation/doc.nix     | 35 ++++++++++++++++++++++++++++++++++
 nixos/profiles/workstation/llm.nix     |  1 +
 user/pi/extensions/doc-list.ts         | 32 +++++++++++++++++++++++++++++++
 4 files changed, 69 insertions(+)
 create mode 100644 nixos/profiles/workstation/doc.nix
 create mode 100644 user/pi/extensions/doc-list.ts

diff --git a/nixos/profiles/workstation/default.nix b/nixos/profiles/workstation/default.nix
index 9332bca..d77d67d 100644
--- a/nixos/profiles/workstation/default.nix
+++ b/nixos/profiles/workstation/default.nix
@@ -19,6 +19,7 @@ in
     ./firefox.nix
     ./dev.nix
     ./create.nix
+    ./doc.nix
     ./llm.nix
   ];
 
diff --git a/nixos/profiles/workstation/doc.nix b/nixos/profiles/workstation/doc.nix
new file mode 100644
index 0000000..1c29ed1
--- /dev/null
+++ b/nixos/profiles/workstation/doc.nix
@@ -0,0 +1,35 @@
+# Many packages include documentation other than man pages.
+# Nixpkgs conventionally installs this under share/doc, which NixOS
+# exposes at /run/current-system/sw/share/doc. Much of it is HTML.
+# This module collects plaintext documentation and exposes it under /doc/,
+# to make it more accessible to terminal users and digestible for LLMs.
+
+{
+  config,
+  pkgs,
+  pkgs-unstable,
+  ...
+}:
+
+let
+  gitDocs = pkgs.runCommand "git-docs" { } ''
+    mkdir -p $out
+    tar --extract --xz --file ${pkgs.git.src} \
+      --strip-components=2 --directory $out \
+      --wildcards '*/Documentation/*.adoc'
+  '';
+  symlinks = {
+    nix = "${config.nix.package.src}/doc/manual/source";
+    git = "${gitDocs}";
+    jj = "${pkgs.jujutsu.src}/docs";
+    pi = "${pkgs-unstable.pi-coding-agent}/lib/node_modules/pi-monorepo/docs";
+  };
+in
+{
+  systemd.tmpfiles.rules = [
+    # /doc is a real directory rather than a symlink so sandbox bind mounts
+    # of /doc keep seeing updated entries when the symlinks inside it change.
+    "d /doc 0555 root root -"
+  ]
+  ++ pkgs.lib.mapAttrsToList (name: target: "L+ /doc/${name} - - - - ${target}") symlinks;
+}
diff --git a/nixos/profiles/workstation/llm.nix b/nixos/profiles/workstation/llm.nix
index 23a3d9a..af1ac85 100644
--- a/nixos/profiles/workstation/llm.nix
+++ b/nixos/profiles/workstation/llm.nix
@@ -19,6 +19,7 @@ let
       --bind-try /nix/var/nix/daemon-socket /nix/var/nix/daemon-socket
       --dir /run
       --ro-bind-try /run/current-system /run/current-system
+      --ro-bind /doc /doc
       # mount git and jj config
       --ro-bind "$HOME/.config" "$HOME/.config"
       --ro-bind "$HOME/repos/config" "$HOME/repos/config"
diff --git a/user/pi/extensions/doc-list.ts b/user/pi/extensions/doc-list.ts
new file mode 100644
index 0000000..5d87352
--- /dev/null
+++ b/user/pi/extensions/doc-list.ts
@@ -0,0 +1,32 @@
+import { existsSync, readdirSync } from "node:fs";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const docRoot = "/doc";
+
+function buildDocList(): string | undefined {
+  if (!existsSync(docRoot)) {
+    return undefined;
+  }
+
+  const entries = readdirSync(docRoot, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+    .map((entry) => entry.name)
+    .sort((a, b) => a.localeCompare(b));
+
+  if (entries.length === 0) {
+    return undefined;
+  }
+
+  return `/doc/ contains documentation for ${entries.join(", ")}. List files with \`find /doc/$name/\` (mind the trailing slash; don't use -type f).`;
+}
+
+export default function docList(pi: ExtensionAPI) {
+  pi.on("before_agent_start", (event) => {
+    const docList = buildDocList();
+    if (docList) {
+      event.systemPromptOptions.sections.documentation = docList;
+    } else {
+      delete event.systemPromptOptions.sections.documentation;
+    }
+  });
+}
-- 
cgit v1.3.1