refactor(#2012): docs in own derivation, ship via claude --add-dir (no ~/.claude clobber)
This commit is contained in:
damocles
mara
parent
e6bc621f59
commit
362d392993
7 changed files with 123 additions and 67 deletions
|
|
@ -70,23 +70,22 @@ let
|
|||
iconPng = pkgs.runCommand "hive-agent-icon.png" { nativeBuildInputs = [ pkgs.librsvg ]; } ''
|
||||
rsvg-convert -f png -w 512 -h 512 ${config.hyperhive.icon} -o $out
|
||||
'';
|
||||
# Generic, agent-agnostic `~/.claude/CLAUDE.md` installed when
|
||||
# `hyperhive.docs.enable` is on (root/manager default-on; see
|
||||
# `manager.nix`). claude auto-loads this user-global memory file every
|
||||
# session, so it's the discovery hook for the docs asset — no
|
||||
# per-agent prompt injection. It references the STABLE `$HIVE_ASSETS_DIR`
|
||||
# env var (not the hashed nix-store path) which the agent resolves at
|
||||
# read time.
|
||||
docsClaudeMd = pkgs.writeText "hive-docs-claude.md" ''
|
||||
# Hyperhive reference docs
|
||||
|
||||
The hyperhive subsystem docs ship read-only inside this container at
|
||||
`$HIVE_ASSETS_DIR/docs/` (resolve the env var, e.g.
|
||||
`ls "$HIVE_ASSETS_DIR/docs"`).
|
||||
|
||||
On a fresh deploy, read `$HIVE_ASSETS_DIR/docs/setup.md` first for the
|
||||
first-run hive bootstrap commands (forge / gateway / matrix
|
||||
provisioning, spawning the first sub-agents).
|
||||
# hyperhive.docs.enable: the in-container directory claude is pointed
|
||||
# at for the hyperhive reference docs (root/manager default-on; see
|
||||
# `manager.nix`). Combines the standalone docs tree
|
||||
# (`pkgs.hyperhive-docs`) under `docs/` with a generic, agent-agnostic
|
||||
# `CLAUDE.md` pointer (`nix/agent-claude.md`) at its root. The harness
|
||||
# adds this dir via `--add-dir` and sets
|
||||
# `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`, so claude loads the
|
||||
# sibling `CLAUDE.md` ADDITIVELY (never replacing the agent's own
|
||||
# `~/.claude/CLAUDE.md` or the project one) and gets read access to
|
||||
# `docs/`. Built as a runCommand (like `iconPng` above) so the tree is
|
||||
# GC-rooted by the system closure — no persistent symlink into the
|
||||
# store to dangle after a content change + GC.
|
||||
agentDocs = pkgs.runCommand "hive-agent-docs" { } ''
|
||||
mkdir -p $out
|
||||
cp ${../agent-claude.md} $out/CLAUDE.md
|
||||
cp -r ${pkgs.hyperhive-docs} $out/docs
|
||||
'';
|
||||
in
|
||||
{
|
||||
|
|
@ -229,16 +228,16 @@ in
|
|||
};
|
||||
|
||||
options.hyperhive.docs.enable = lib.mkEnableOption ''
|
||||
install a generic `~/.claude/CLAUDE.md` pointing this agent at the
|
||||
hyperhive reference docs shipped read-only at `$HIVE_ASSETS_DIR/docs/`
|
||||
(the repo `docs/` tree, packaged into the assets derivation). claude
|
||||
auto-loads the file every session, so the docs are discoverable
|
||||
without any per-agent prompt injection. The docs themselves are
|
||||
always present at `$HIVE_ASSETS_DIR/docs/`; this option only controls
|
||||
the auto-loaded pointer. When enabled the managed symlink clobbers any
|
||||
existing `~/.claude/CLAUDE.md`. Default-on for the root/manager agent
|
||||
(see `manager.nix`), off elsewhere; any agent can flip it from its
|
||||
`agent.nix`.
|
||||
point this agent at the hyperhive reference docs (the repo `docs/`
|
||||
tree, shipped read-only as the standalone `hyperhive-docs`
|
||||
derivation). When enabled the harness adds the in-container docs dir
|
||||
via `claude --add-dir` and turns on additive CLAUDE.md loading
|
||||
(`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1`), so claude loads a
|
||||
generic pointer `CLAUDE.md` from that dir ALONGSIDE — never replacing
|
||||
— the agent's own `~/.claude/CLAUDE.md` and project memory. The docs
|
||||
are readable at `$HIVE_DOCS_DIR/docs/`. Default-on for the
|
||||
root/manager agent (see `manager.nix`), off elsewhere; any agent can
|
||||
flip it from its `agent.nix`.
|
||||
'';
|
||||
|
||||
options.hyperhive.allowedBashPatterns = lib.mkOption {
|
||||
|
|
@ -1042,21 +1041,6 @@ in
|
|||
[ -d "$configDir" ] || continue
|
||||
chown -hR "$userName:$userName" "$configDir" 2>/dev/null || true
|
||||
done
|
||||
${lib.optionalString config.hyperhive.docs.enable ''
|
||||
# hyperhive.docs.enable: point this agent at the hyperhive docs via
|
||||
# a managed `~/.claude/CLAUDE.md` (claude auto-loads it every
|
||||
# session). The link lives in the bind-mounted (persistent) home, so
|
||||
# it must NOT target a bare `/nix/store` path — that path is only
|
||||
# GC-rooted by the current generation, and a content change (new
|
||||
# hash) plus `nix-collect-garbage` would leave the persistent link
|
||||
# dangling. Instead it targets the STABLE `/etc/hyperhive/claude/
|
||||
# CLAUDE.md` path, which the `environment.etc` entry below
|
||||
# regenerates declaratively every rebuild (and which holds the
|
||||
# docs store-path reference that keeps the content GC-rooted). The
|
||||
# chown -h below sets the link's ownership.
|
||||
mkdir -p "$homeDir/.claude"
|
||||
ln -sfn /etc/hyperhive/claude/CLAUDE.md "$homeDir/.claude/CLAUDE.md"
|
||||
''}
|
||||
if [ -d "$homeDir/.claude" ]; then
|
||||
chown -hR "$userName:$userName" "$homeDir/.claude" 2>/dev/null || true
|
||||
# 0755 so hive-core (a different unix user) can list the dir and
|
||||
|
|
@ -1097,16 +1081,6 @@ in
|
|||
|
||||
environment.etc."hyperhive/extra-mcp.json".text = builtins.toJSON config.hyperhive.extraMcpServers;
|
||||
|
||||
# hyperhive.docs.enable: the managed `~/.claude/CLAUDE.md` content,
|
||||
# placed declaratively in /etc so it's regenerated every rebuild and
|
||||
# GC-rooted by the system closure. The activation script above symlinks
|
||||
# the agent's (bind-mounted, persistent) `~/.claude/CLAUDE.md` at this
|
||||
# stable path rather than at the bare `${docsClaudeMd}` store path, so
|
||||
# the persistent link can never dangle after a content change + GC.
|
||||
environment.etc."hyperhive/claude/CLAUDE.md" = lib.mkIf config.hyperhive.docs.enable {
|
||||
source = docsClaudeMd;
|
||||
};
|
||||
|
||||
# Operator-set per-agent icon (hyperhive.icon). When configured, the
|
||||
# SVG lands at /etc/hyperhive/icon.svg; the harness serves it at
|
||||
# GET /icon, falling back to the bundled hyperhive logo when absent.
|
||||
|
|
@ -1295,6 +1269,15 @@ in
|
|||
# (compact-on-overflow) still fires when the session is truly full.
|
||||
HIVE_COMPACT_WATERMARK_TOKENS = "0";
|
||||
}
|
||||
// lib.optionalAttrs config.hyperhive.docs.enable {
|
||||
# hyperhive.docs.enable: the in-container reference-docs dir — the
|
||||
# docs/ tree plus the agent CLAUDE.md pointer (see `agentDocs`
|
||||
# above). The harness reads this and passes it to claude as
|
||||
# `--add-dir` with additive CLAUDE.md loading enabled, so the docs
|
||||
# are discoverable without touching the agent's own memory files.
|
||||
# See hive-ag3nt::turn.
|
||||
HIVE_DOCS_DIR = "${agentDocs}";
|
||||
}
|
||||
// lib.optionalAttrs (config.hyperhive._bashEnvFragments != "") {
|
||||
# Non-interactive bash invocations (claude's `Bash` tool runs
|
||||
# `bash -c`) source $BASH_ENV at startup — drops every active
|
||||
|
|
|
|||
|
|
@ -6,8 +6,9 @@
|
|||
imports = [ ./harness-base.nix ];
|
||||
|
||||
# The root/manager bootstraps a fresh hive, so it gets the hyperhive
|
||||
# reference docs surfaced by default (the `~/.claude/CLAUDE.md` pointer
|
||||
# → `$HIVE_ASSETS_DIR/docs/setup.md`). `mkDefault` so a manager's own
|
||||
# `agent.nix` can still turn it off. Other agents default off.
|
||||
# reference docs surfaced by default (the additive `CLAUDE.md` pointer
|
||||
# → `$HIVE_DOCS_DIR/docs/setup.md`, added via `claude --add-dir`).
|
||||
# `mkDefault` so a manager's own `agent.nix` can still turn it off.
|
||||
# Other agents default off.
|
||||
hyperhive.docs.enable = lib.mkDefault true;
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue