feat: update documentation, lib functions, modules, and packages

lib/agents.nix

@@ -26,6 +26,27 @@
     pattern = lib.concatStringsSep ":" (lib.init parts);
   in {inherit pattern action;};
 
+  # ── Shared renderer primitives ──────────────────────────────────
+  # Render agent files from canonical definitions into a directory.
+  # Each agent gets a "<name>.md" file containing mkContent name agent.
+  #
+  # Args:
+  #   pkgs       — Nixpkgs package set with linkFarm
+  #   canonical  — Attribute set of agent definitions (keyed by slug)
+  #   mkContent  — Function: name: agent → string (file content)
+  #   name       — Derivation name (e.g. "opencode-agents")
+  #
+  # Returns:
+  #   A store path containing all agent *.md files.
+  renderAgentFiles = pkgs: canonical: mkContent: name:
+    pkgs.linkFarm name (
+      lib.mapAttrsToList (n: a: {
+        name = "${n}.md";
+        path = pkgs.writeText "${n}.md" (mkContent n a);
+      })
+      canonical
+    );
+
   agentsLib = {
     # ── loadCanonical ─────────────────────────────────────────────
     #
@@ -87,20 +108,8 @@
 
       mkAgentContent = name: agent:
         (mkFrontmatter name agent) + agent.systemPrompt;
-
-      mkAgentFile = name: agent:
-        pkgs.writeText "${name}.md" (mkAgentContent name agent);
-
-      agentFiles = lib.mapAttrs mkAgentFile canonical;
-
-      copyCommands = lib.concatStringsSep "\n" (
-        lib.mapAttrsToList (name: file: "cp ${file} $out/${name}.md") agentFiles
-      );
     in
-      pkgs.runCommand "opencode-agents" {} ''
-        mkdir -p $out
-        ${copyCommands}
-      '';
+      renderAgentFiles pkgs canonical mkAgentContent "opencode-agents";
 
     # ── Claude Code renderer ──────────────────────────────────────
     #
@@ -179,10 +188,7 @@
       mkClaudeAgentContent = name: agent:
         (mkClaudeFrontmatter name agent) + agent.systemPrompt;
 
-      mkClaudeAgentFile = name: agent:
-        pkgs.writeText "${name}.md" (mkClaudeAgentContent name agent);
-
-      agentFiles = lib.mapAttrs mkClaudeAgentFile canonical;
+      agentFiles = renderAgentFiles pkgs canonical mkClaudeAgentContent "claude-code-agent-files";
 
       # Build settings.json with permission rules aggregated from all agents.
       allAllows = lib.flatten (lib.mapAttrsToList (_: agent: renderPermAllow (agent.permissions or {})) canonical);
@@ -196,14 +202,10 @@
       };
 
       settingsFile = pkgs.writeText "claude-settings.json" settingsJson;
-
-      copyAgentCommands = lib.concatStringsSep "\n" (
-        lib.mapAttrsToList (name: file: "cp ${file} $out/.claude/agents/${name}.md") agentFiles
-      );
     in
       pkgs.runCommand "claude-code-agents" {} ''
         mkdir -p $out/.claude/agents
-        ${copyAgentCommands}
+        cp -r ${agentFiles}/* $out/.claude/agents/
         cp ${settingsFile} $out/.claude/settings.json
       '';
 
@@ -226,7 +228,7 @@
       codingRules ? null,
     }: let
       # Import coding-rules lib for concatRulesMd when codingRules is provided
-      codingRulesLib = (import ./coding-rules.nix {inherit lib;});
+      codingRulesLib = import ./coding-rules.nix {inherit lib;};
       # Find the primary agent (there should be exactly one).
       primaryAgents = lib.filterAttrs (_: a: a.mode == "primary") canonical;
       primaryNames = lib.attrNames primaryAgents;
@@ -295,10 +297,7 @@
       mkPiAgentContent = name: agent:
         (mkPiFrontmatter name agent) + agent.systemPrompt;
 
-      mkPiAgentFile = name: agent:
-        pkgs.writeText "${name}.md" (mkPiAgentContent name agent);
-
-      piAgentFiles = lib.mapAttrs mkPiAgentFile canonical;
+      piAgentFiles = renderAgentFiles pkgs canonical mkPiAgentContent "pi-agent-files";
 
       # ── Build AGENTS.md content ───────────────────────────────────
       primaryDn = primary.display_name or primaryName;
@@ -317,7 +316,9 @@
         then let
           section = codingRulesLib.mkRulesMdSection codingRules;
         in
-          if section != "" then "\n" + section else ""
+          if section != ""
+          then "\n" + section
+          else ""
         else "";
 
       agentsMd =
@@ -339,16 +340,12 @@
 
       agentsMdFile = pkgs.writeText "AGENTS.md" agentsMd;
       systemMdFile = pkgs.writeText "SYSTEM.md" primary.systemPrompt;
-
-      copyAgentCommands = lib.concatStringsSep "\n" (
-        lib.mapAttrsToList (name: file: "cp ${file} $out/agents/${name}.md") piAgentFiles
-      );
     in
       pkgs.runCommand "pi-agents" {} ''
         mkdir -p $out/agents
         cp ${agentsMdFile} $out/AGENTS.md
         cp ${systemMdFile} $out/SYSTEM.md
-        ${copyAgentCommands}
+        cp -r ${piAgentFiles}/* $out/agents/
       '';
 
     # ── renderForTool dispatcher ──────────────────────────────────

lib/coding-rules.nix

@@ -188,9 +188,21 @@
     frameworks ? [],
   }: let
     rulePaths =
-      (map (c: {kind = "concerns"; name = c;}) concerns)
-      ++ (map (l: {kind = "languages"; name = l;}) languages)
-      ++ (map (f: {kind = "frameworks"; name = f;}) frameworks);
+      (map (c: {
+          kind = "concerns";
+          name = c;
+        })
+        concerns)
+      ++ (map (l: {
+          kind = "languages";
+          name = l;
+        })
+        languages)
+      ++ (map (f: {
+          kind = "frameworks";
+          name = f;
+        })
+        frameworks);
 
     readRule = rule: builtins.readFile "${agents}/rules/${rule.kind}/${rule.name}.md";
     ruleContents = map readRule rulePaths;
@@ -216,7 +228,6 @@
       ${content}
       <!-- CODING-RULES:END -->
     '';
-
 in {
   inherit mkCodingRules concatRulesMd mkRulesMdSection;
 }

lib/ports.nix

@@ -95,19 +95,4 @@
     #   List of service names (strings)
     listServices = lib.attrNames ports;
   };
-
-  # Simple helper to get a port without host override
-  # Useful when you don't need host-specific ports
-  #
-  # Args:
-  #   portsConfig: Same structure as mkPortHelpers
-  #   service: The service name (string)
-  #
-  # Returns:
-  #   Port number (int) or null if service not found
-  #
-  # Example:
-  #   getDefaultPort myPorts "nginx"  # Returns default port only
-  getDefaultPort = portsConfig: service:
-    portsConfig.ports.${service} or null;
 }