hyperhive/nix/docs/default.nix

{
  pkgs,
  lib,
  self,
  nixosSystem,
}:
# Nix options reference: `pkgs.nixosOptionsDoc` over two evaluated
# module trees, emitted as CommonMark (`host.md` + `agent.md`). The
# HTML + CSS for `/options/` is rendered downstream by the website
# repo, which owns the presentation and shares one stylesheet with the
# prose `/docs/` tree. Full pipeline + subtree-pick / output-tree
# rationale: docs/gotchas.md::Nix options reference.
let
  # Stub host system: every hyperhive subsystem `mkForce false` so
  # heavy build inputs (matrix container, forge, etc.) stay out of
  # the eval — only option *declarations* matter for the doc walk.
  hostEval = nixosSystem {
    system = pkgs.stdenv.hostPlatform.system;
    modules = [
      self.nixosModules.default
      (
        { lib, ... }:
        {
          nixpkgs.overlays = [ self.overlays.default ];
          fileSystems."/" = {
            device = "/dev/null";
            fsType = "tmpfs";
          };
          boot.loader.grub.enable = false;
          system.stateVersion = "25.11";
          services.hyperhive.enable = lib.mkForce false;
          services.hyperhive.matrix.enable = lib.mkForce false;
        }
      )
    ];
  };

  # Reuse the already-evaluated agent-base config — its options tree is
  # identical to what a real agent container sees, no second eval needed.
  agentEval = self.nixosConfigurations.agent-base;

  # Rewrite option declaration paths from nix-store absolute paths to
  # forge URLs so rendered docs link back to source.
  forgeRoot = "https://forge.darkest.space/hyperhive/hyperhive/src/branch/main";
  storePrefix = toString self + "/";
  transformOptions =
    opt:
    opt
    // {
      declarations = map (
        decl:
        let
          declStr = toString decl;
          relPath =
            if lib.hasPrefix storePrefix declStr then
              lib.removePrefix storePrefix declStr
            else
              baseNameOf declStr;
        in
        {
          url = "${forgeRoot}/${relPath}";
          name = relPath;
        }
      ) opt.declarations;
    };

  # Filter to a set of top-level subtree roots — keeps the rendered docs
  # focused on hyperhive's surface instead of NixOS's 10k+ default
  # options. Root choice matters: see docs/gotchas.md::Nix options
  # reference for the services.hyperhive consolidation history.
  pickSubtrees =
    options: roots:
    let
      pick =
        path:
        if lib.hasAttrByPath path options then
          lib.setAttrByPath path (lib.getAttrFromPath path options)
        else
          { };
    in
    lib.foldl' lib.recursiveUpdate { } (map pick roots);

  hostOptions = pickSubtrees hostEval.options [
    [
      "services"
      "hyperhive"
    ]
  ];

  agentOptions = pickSubtrees agentEval.options [
    [ "hyperhive" ]
  ];

  hostDoc = pkgs.nixosOptionsDoc {
    options = hostOptions;
    inherit transformOptions;
  };

  agentDoc = pkgs.nixosOptionsDoc {
    options = agentOptions;
    inherit transformOptions;
  };

  # CommonMark `.md` is the source of truth and the only output. HTML
  # rendering + theming lives in the website repo (it owns the
  # presentation + shares one stylesheet across `/options/` and
  # `/docs/`); this flake just emits the option reference as markdown.
  mkMarkdownPage =
    name: title: doc:
    pkgs.runCommand "hyperhive-${name}.md" { } ''
      {
        echo "# ${title}"
        echo
        echo "<!-- Auto-generated from the hyperhive flake."
        echo "     Source: nix/docs/default.nix · regenerate with"
        echo "     \`nix build .#${name}\` -->"
        echo
        cat ${doc.optionsCommonMark}
      } > $out
    '';

  # Bundle landing page — a short markdown index pointing at the two
  # reference pages.
  indexMD = pkgs.writeText "hyperhive-options-index.md" ''
    # hyperhive — nix options reference

    Auto-generated from the hyperhive flake. Two reading paths:

    - [host options](host.md) — options exposed by
      `hyperhive.nixosModules.default` to operator host configurations
      (`services.hyperhive.{enable,domain,c0re,forge,matrix,gateway}.*`).
    - [per-agent options](agent.md) — options declared in
      `nix/templates/harness-base.nix`, visible from every `agent.nix`
      (`hyperhive.model`, `hyperhive.allowedRecipients`,
      `hyperhive.extraMcpServers`, `hyperhive.frontend.*`,
      `hyperhive.forge.*`, `hyperhive.matrix.*`, `hyperhive.gui.*`).

    Regenerate with `nix build .#docs` (bundle), `.#docs-host`, or
    `.#docs-agent`.
  '';

  hostMD = mkMarkdownPage "docs-host" "hyperhive — host options" hostDoc;
  agentMD = mkMarkdownPage "docs-agent" "hyperhive — per-agent options" agentDoc;
in
{
  host = hostMD;
  agent = agentMD;

  # Bundle of the option reference as markdown. The website renders
  # these `.md` to themed HTML for `/options/`; standalone consumers
  # get the CommonMark source directly.
  bundle = pkgs.runCommand "hyperhive-options-docs" { } ''
    mkdir -p $out
    cp ${indexMD} $out/index.md
    cp ${hostMD} $out/host.md
    cp ${agentMD} $out/agent.md
  '';
}