refactor: nix/host-modules + nix/agent-modules layout, update doc paths

nix/agent-modules/dashboard-links.nix

@@ -0,0 +1,73 @@
+# Extra navigation links surfaced on the hive-c0re dashboard card for
+# this agent: the option and the oneshot that writes them into the
+# state dir where hive-c0re reads them.
+{
+  lib,
+  config,
+  ...
+}:
+{
+  options.hyperhive.dashboardLinks = lib.mkOption {
+    type = lib.types.listOf (
+      lib.types.submodule {
+        options = {
+          label = lib.mkOption {
+            type = lib.types.str;
+            description = "Display label for the link.";
+          };
+          icon = lib.mkOption {
+            type = lib.types.str;
+            default = "";
+            description = "Optional icon emoji or short glyph.";
+          };
+          url = lib.mkOption {
+            type = lib.types.str;
+            description = "Full URL (may include a different port, e.g. http://localhost:9001/stats).";
+          };
+        };
+      }
+    );
+    default = [ ];
+    example = lib.literalExpression ''
+      [
+        { label = "Stats"; icon = "📊"; url = "http://localhost:9001/stats"; }
+      ]
+    '';
+    description = ''
+      Extra navigation links surfaced on the hive-c0re dashboard card for
+      this agent. Declare any additional web UI pages the agent exposes —
+      stats pages, custom UIs, etc. hive-c0re reads the JSON file this
+      option produces at each container-view snapshot and attaches the
+      links to the agent card without any code changes.
+    '';
+  };
+
+  config = {
+    # Write declared dashboardLinks to the state dir so hive-c0re can
+    # read them without accessing the container's /etc/ from the host.
+    # Best-effort oneshot (always exit 0):
+    # docs/conventions.md::Best-effort oneshot services.
+    systemd.services.hive-dashboard-links = lib.mkIf (config.hyperhive.dashboardLinks != [ ]) {
+      description = "write declarative dashboardLinks to agent state dir";
+      wantedBy = [ "multi-user.target" ];
+      serviceConfig = {
+        Type = "oneshot";
+        RemainAfterExit = true;
+        # Pin the journal identity (else it's the `script` store-path wrapper).
+        SyslogIdentifier = "hive-dashboard-links";
+      };
+      environment.LINKS_JSON = builtins.toJSON config.hyperhive.dashboardLinks;
+      script = ''
+        # Sub-agents have their state dir bind-mounted at /agents/<name>/state.
+        # Use a glob — exactly one match per container at runtime.
+        STATE_DIR=$(echo /agents/*/state)
+        if [ ! -d "$STATE_DIR" ]; then
+          echo "hive-dashboard-links: no state dir found at /agents/*/state; skipping"
+          exit 0
+        fi
+        printf '%s' "$LINKS_JSON" > "$STATE_DIR/hyperhive-dashboard-links.json"
+        echo "hive-dashboard-links: wrote $(printf '%s' "$LINKS_JSON" | wc -c) bytes to $STATE_DIR/hyperhive-dashboard-links.json"
+      '';
+    };
+  };
+}