Agent Docs

The Agent Docs view gives each user or project one reviewed Hive version of its AI coding configuration. Hive replicates that saved version between daemons, while preserving separate content for every tool and every file.

Hive does not flatten Claude Code, Codex, Copilot, Gemini, or other providers into one shared Markdown body. Each tool keeps the file format and path it already reads.

Scopes

Choose a scope at the top of the Agent Docs view:

• User (all nodes) stores one user-level Hive version for the cluster. Its files resolve under the user home directory on each node.
• Project stores one Hive version for the selected project. Its files resolve under that project's working directory and can be rolled out only to the node that owns the project.

The built-in instruction targets are:

Scope	Tool	File
User	Claude Code	.claude/CLAUDE.md
User	Codex	.codex/AGENTS.md
User	Gemini CLI	.gemini/GEMINI.md
User	opencode	.config/opencode/AGENTS.md
Project	Codex	AGENTS.md
Project	Claude Code	CLAUDE.md
Project	Gemini CLI	GEMINI.md
Project	Cursor	.cursorrules
Project	GitHub Copilot	.github/copilot-instructions.md
Project	Windsurf	.windsurfrules
Project	Cline	.clinerules
Project	JetBrains Junie	.junie/guidelines.md

Enable only the instruction files that Hive should manage. A disabled target can remain in the reviewed Hive version, but rollout never writes it to a node.

Review and merge a node

Use this workflow to bring existing node configuration into Hive without silently replacing either version:

1. Choose User (all nodes) or select a Project.
2. Select Review node changes.
3. Choose an online node. Hive discovers the known instruction files for the selected scope and marks each existing file as same or changed. When a path is a symbolic link, Hive also shows its target before you import or apply anything.
4. Select a file. Diff compares Unsaved Hive draft and Node version in the synchronized line view. Choose Edit Hive draft when you want to change the draft directly.
5. Choose Smart merge to preview a three-way merge, or choose Use node version in draft to replace the draft.
6. Repeat with other files or nodes until the draft contains the version you want.
7. Select Save Hive version.

Discovery and editing change only the unsaved draft. They do not change the cluster-saved version or any file on disk. Saving updates the Hive version replicated between daemons, but still does not write files to a node.

Read a line diff

Agent Docs uses the same line diff for instruction review, tracked asset review, rollout divergence, and Smart merge previews. Both sides share one scroll area, so vertical and horizontal scrolling keep the compared lines aligned. Each side keeps its own line numbers.

The summary and row markers distinguish every kind of difference:

• - removed: a line exists only on the left side
• + added: a line exists only on the right side
• ~ changed: a removed line and its replacement are aligned on one row

Changed rows are highlighted separately from pure additions and removals, so rewritten lines remain visible even when both files have the same number of lines. Unchanged lines stay aligned without a change marker.

Check for divergence

In Node rollout or Project-node rollout, select Check for a node. Each target reports one of these states:

• in sync: the on-disk file matches the saved Hive version
• diverged: the file exists but differs from the saved Hive version
• missing: the file does not exist on that node

For a symbolic link, status also reports the link target. A safe link whose final target remains inside the managed user or project root can be applied: Hive preserves the link and writes through it rather than replacing it with a regular file. The confirmation names that behavior before the write.

Hive blocks an apply when the final link is broken, its target is outside the managed root, or any parent directory is a link that escapes the managed root. The affected item is marked non-applicable and includes an apply_blocked_reason; bulk and all-node confirmations exclude it. Fix or remove the unsafe link, then run Check again. Hive revalidates the path at write time so a link changed after review cannot redirect the rollout.

For a diverged file, open diff to compare On disk (current) with Hive would write in the synchronized line view. You can then write only that file or apply the complete saved instruction set to the node.

Status and rollout are disabled while the Hive version has unsaved changes. This prevents a draft from being mistaken for the reviewed version.

Skills, subagents, and commands

Hive tracks provider-specific skills, subagent definitions, and commands as individual files. They are not combined with the base instruction documents.

Select Review node changes in the Skills, subagents & commands section to discover files on an online node. The discovered files are grouped by type (skills, subagents, commands) and can be narrowed with the name search, the per-type filters, and the New or changed filter. Each file is marked new (not tracked in Hive yet), changed, or same.

For a single file:

1. Use Diff to compare Hive draft with the read-only Node version in the synchronized line view, or choose Edit Hive draft to edit the draft.
2. Choose Smart merge to preview a three-way merge that uses the saved Hive copy as the common base. Use node version replaces the draft outright.
3. Select Save file to Hive when it is ready.

Preview and apply a Smart merge

Smart merge never changes the draft immediately. It opens a line diff from Current draft to Merged preview, including the removed, added, and changed markers and line numbers. Review the result, then choose Apply merge to draft or Cancel.

Applying the preview updates the draft and switches the review panel to Edit Hive draft. If both sides rewrote the same hunk, the preview reports the conflict count and the applied draft contains <<<<<<< conflict markers. Edit and resolve those markers before saving. Cancel leaves the draft unchanged.

To import in bulk, tick files (or a whole type header) and select Save from node to Hive. Bulk import saves the node version of every selected file without opening each one.

Tracked assets have their own per-node status and can be applied individually or together. Discovery covers the supported provider directories for Claude Code, Codex, opencode, Cursor, Gemini CLI, Windsurf, and Cline. Binary files and files over the supported size limit are shown but are not synced.

Untracking an asset removes it from the Hive version. It does not delete the existing file from a node.

Apply the reviewed version

Applying is always an explicit action:

• Apply to this node writes every enabled base instruction file to one online node.
• A write action beside a missing or diverged item writes only that file.
• Apply all in the assets section writes all tracked skills, subagents, and commands to that node.
• Apply everything to all nodes is available for user scope. After confirmation, it writes every enabled instruction file and every tracked asset to every currently online node.

The all-node action skips offline nodes. When a node comes back, use Check and apply the reviewed version to that node. Hive keeps the saved version replicated between daemons, but does not silently overwrite a node that was offline or changed locally.

Project scope has no all-node action because project files belong to the project's owning node.

Upgrading legacy Agent Docs

Older Agent Docs records used one Markdown body for every selected tool, with some targets writing a pointer file instead. Hive migrates these records automatically:

• each full target receives the shared body it previously wrote
• each pointer target receives the pointer content it previously generated
• the legacy AGENTS.md target becomes the Codex target

This preserves the resulting content for every tool file while converting the record to independent per-tool bodies. The migration does not write or replace files on disk. Review the converted Hive version and use the normal explicit rollout when you are ready.