Document toolchain propagation and auto-seed tools

Author: joshp123

AGENTS.md

@@ -30,6 +30,12 @@ Maintainer role:
 - Surface priorities and context; do not file issues or modify code unless asked.
 - Track running versions (clawdbot/nix-clawdbot/clawdinators) and note them in `memory/ops.md`.
 
+Toolchain workflow (repo source of truth):
+- Add/remove tools in `nix/tools/clawdinator-tools.nix` (packages + descriptions).
+- Tools list is rendered into `/etc/clawdinator/tools.md` by Nix and appended to workspace `TOOLS.md` at seed time.
+- Keep `clawdinator/workspace/TOOLS.md` aligned with upstream template; do not hardcode tool lists there.
+- When you add a new tool, verify it appears in `/etc/clawdinator/tools.md` and in the workspace `TOOLS.md` after seed.
+
 The Zen of ~~Python~~ Clawdbot, ~~by~~ shamelessly stolen from Tim Peters:
 - Beautiful is better than ugly.
 - Explicit is better than implicit.

clawdinator/workspace/TOOLS.md

@@ -40,21 +40,4 @@ Skills are shared. Your setup is yours. Keeping them apart means you can update
 
 Add whatever helps you do your job. This is your cheat sheet.
 
-## CLAWDINATOR Tooling Audit
-
-Quick checks:
-- Binaries: `ls /run/current-system/sw/bin`
-- Active system profile: `readlink /run/current-system/sw`
-- NixOS package list: `nix-store --query --requisites /run/current-system/sw | sort`
-
-CLAWDINATOR-specific tools:
-- `/usr/local/bin/memory-read`
-- `/usr/local/bin/memory-write`
-- `/usr/local/bin/memory-edit`
-
-Seeded repos:
-- `/var/lib/clawd/repos/clawdbot`
-- `/var/lib/clawd/repos/nix-clawdbot`
-- `/var/lib/clawd/repos/clawdinators`
-- `/var/lib/clawd/repos/clawdhub`
-- `/var/lib/clawd/repos/nix-steipete-tools`
+<!-- Toolchain list is appended at seed time from /etc/clawdinator/tools.md -->

nix/modules/clawdinator.nix

@@ -79,6 +79,10 @@ let
         in
         "${repo.name}\t${repo.url}\t${branch}")
       cfg.repoSeeds);
+  toolchain = import ../tools/clawdinator-tools.nix { inherit pkgs; };
+  toolchainMd = lib.concatMapStringsSep "\n"
+    (tool: "- **${tool.name}** — ${tool.description}")
+    toolchain.docs;
 
   tokenWrapper =
     if cfg.anthropicApiKeyFile != null || cfg.discordTokenFile != null || cfg.githubPatFile != null then
@@ -346,9 +350,7 @@ in
 
     environment.systemPackages =
       [ cfg.package ]
-      ++ lib.optional cfg.memoryEfs.enable pkgs.nfs-utils
-      ++ lib.optional cfg.memoryEfs.enable pkgs.stunnel
-      ++ [ pkgs.util-linux ];
+      ++ toolchain.packages;
 
     environment.etc."clawd/clawdbot.json".source = configSource;
     environment.etc."clawdinator/bin/memory-read" = {
@@ -363,6 +365,33 @@ in
       source = ../../scripts/memory-edit.sh;
       mode = "0755";
     };
+    environment.etc."clawdinator/tools.md" = {
+      mode = "0644";
+      text = ''
+        ## Installed Toolchain (Nix)
+
+        ${toolchainMd}
+
+        ## Local scripts (installed by Nix)
+        - **memory-read** — shared-lock read from `/memory`.
+        - **memory-write** — exclusive-lock write to `/memory`.
+        - **memory-edit** — exclusive-lock in-place edit for `/memory`.
+
+        ## nix-steipete-tools (repo seeded, binaries not installed on Linux yet)
+        Darwin-only upstream; the repo is seeded at `/var/lib/clawd/repos/nix-steipete-tools`.
+        Tools expected once Linux packages exist:
+        - summarize
+        - gogcli
+        - camsnap
+        - sonoscli
+        - bird
+        - peekaboo
+        - poltergeist
+        - sag
+        - imsg
+        - oracle
+      '';
+    };
     environment.etc."stunnel/efs.conf" = lib.mkIf cfg.memoryEfs.enable {
       mode = "0644";
       text = ''

nix/tools/clawdinator-tools.nix

@@ -0,0 +1,31 @@
+{ pkgs }:
+{
+  packages = [
+    pkgs.git
+    pkgs.curl
+    pkgs.jq
+    pkgs.python3
+    pkgs.ffmpeg
+    pkgs.ripgrep
+    pkgs.nodejs_22
+    pkgs.pnpm_10
+    pkgs.util-linux
+    pkgs.nfs-utils
+    pkgs.stunnel
+  ];
+
+  docs = [
+    { name = "clawdbot-gateway"; description = "CLAWDINATOR runtime (Clawdbot gateway)."; }
+    { name = "git"; description = "Repo sync + ops."; }
+    { name = "curl"; description = "HTTP requests."; }
+    { name = "jq"; description = "JSON processing."; }
+    { name = "python3"; description = "Clawdbot dev chain dependency."; }
+    { name = "ffmpeg"; description = "Media processing."; }
+    { name = "ripgrep"; description = "Fast file search."; }
+    { name = "nodejs_22"; description = "Clawdbot dev chain runtime."; }
+    { name = "pnpm_10"; description = "Clawdbot dev chain package manager."; }
+    { name = "util-linux"; description = "Provides flock used by memory wrappers."; }
+    { name = "nfs-utils"; description = "NFS client utilities for EFS."; }
+    { name = "stunnel"; description = "TLS tunnel for EFS in transit."; }
+  ];
+}

scripts/seed-workspace.sh

@@ -15,6 +15,11 @@ shopt -s nullglob
 for file in "$src"/*.md; do
   name="$(basename "$file")"
   install -m 0644 "$file" "$dst/$name"
+
 done
 
+if [ -f "/etc/clawdinator/tools.md" ]; then
+  printf '\n%s\n' "$(cat /etc/clawdinator/tools.md)" >> "$dst/TOOLS.md"
+fi
+
 rm -f "$dst/BOOTSTRAP.md"