# Top-level, cross-cutting hyperhive options: the master enable
# switch, the hive's identity (domain + display names), and hive-wide
# feature toggles read by several subsystem modules. Imported by the
# ./default.nix aggregator.
{
  lib,
  ...
}:
{
  # Top-level hyperhive enable flag. When true, automatically enables
  # hive-c0re and the on-by-default hyperhive subsystems.
  options.services.hyperhive.enable = lib.mkEnableOption "hyperhive — the agent swarm coordinator";

  # Canonical hive DNS domain shared by every subsystem that needs a
  # stable hostname. Typed nullOr (default null) so the option always
  # exists, but it's REQUIRED whenever hyperhive is enabled — an
  # assertion in hive-network.nix fails eval when it's unset, since
  # matrix bakes it in on first boot and the gateway/forge/agent URLs all
  # derive from it (no safe default). Full identity-surface
  # context (HYPERHIVE_HIVE_DOMAIN / HIVE_NAME / SWARM_NAME env-var
  # chain → identity.rs → claude prompt): docs/conventions.md::
  # Hive identity (label + domain + display names).
  options.services.hyperhive.domain = lib.mkOption {
    type = lib.types.nullOr lib.types.str;
    default = null;
    example = "darkest.space";
    description = ''
      Canonical host domain for hyperhive subsystems that need a
      stable name (currently: `services.hyperhive.matrix.serverName`
      derives from this, defaulting to
      `matrix.''${services.hyperhive.domain}` when `serverName` is
      null). **Required** when `services.hyperhive.enable` — eval fails
      with a helpful message if it's unset (it's baked into matrix on
      first boot and drives the gateway/forge/agent URLs, with no safe
      default; changing it later is destructive). Exposed to agents as
      `HYPERHIVE_HIVE_DOMAIN`; consumed by
      `hive-agent::identity::hive_domain()` for `<name>@<domain>`
      qualified labels.
    '';
  };

  # Human display names for hive + swarm. Distinct from the DNS
  # domain above (machine-readable) — see
  # docs/conventions.md::Hive identity for the
  # domain-vs-name-vs-swarm distinction + the env-var
  # propagation chain.
  options.services.hyperhive.hiveName = lib.mkOption {
    type = lib.types.nullOr lib.types.str;
    default = null;
    example = "pr1ma";
    description = ''
      Human-readable name of this single-host hive instance.
      Distinct from `services.hyperhive.domain` (the machine-
      addressable DNS name): the domain may carry the hive name as
      its leftmost label by convention, but this option is the
      canonical readable identity. Exposed to agents as
      `HYPERHIVE_HIVE_NAME`; surfaced in the dashboard chrome and
      per-agent system prompt when set. Null falls back to the
      default behaviour (chrome shows the domain, prompt doesn't
      mention a hive name).
    '';
  };

  options.services.hyperhive.swarmName = lib.mkOption {
    type = lib.types.nullOr lib.types.str;
    default = null;
    example = "constellat1on";
    description = ''
      Human-readable name of the wider swarm this hive belongs to.
      Hives at different DNS domains can share a swarm name when
      they federate together. Exposed to agents as
      `HYPERHIVE_SWARM_NAME`; surfaced in the dashboard chrome and
      per-agent system prompt when set.
    '';
  };

  # Whether this hive runs "ruthless" — with no root/manager agent at
  # all. Some hives don't want a root agent — see issue tracker
  # "scope concept: special agents".
  options.services.hyperhive.ruthless = lib.mkOption {
    type = lib.types.bool;
    default = false;
    example = true;
    description = ''
      Run this hive "ruthless" — with no root (manager) agent at all (no
      ruth). When `true`, hive-c0re skips the root-agent auto-management
      sweep entirely (it otherwise creates the root agent's container when
      missing and restarts it when present but stopped). Defaults to
      `false` (the root agent is auto-managed as required
      infrastructure). Exposed to hive-c0re as `HYPERHIVE_RUTHLESS`.
    '';
  };

  options.services.hyperhive.github.enable = lib.mkOption {
    type = lib.types.bool;
    default = true;
    example = false;
    description = ''
      Hive-wide switch for the per-agent GitHub integration (the `gh` CLI
      wrapper + git credential helper, per `hyperhive.github.enable`). On by
      default: every agent gets the integration, inert until a PAT is
      provisioned via the dashboard credentials tab or `hivectl github
      set-token`. Set `false` to turn it off for the whole hive --- the
      meta-flake renderer (`hive-c0re/src/meta.rs`) then injects
      `hyperhive.github.enable = false` into every agent. Exposed to hive-c0re
      as `HYPERHIVE_GITHUB_DISABLED` (set only when the integration is off).
    '';
  };
}