maintaining-docs
Skill17 starsChanged 12 days agoMITView on GitHub
How to write and structure the Hivemind user guide (guide/, built by site/docs, served at /guide) so it stays short, plain, correct and readable by agents. Covers where a page goes and what kind of page it is, one home per fact, the copy rules, diagrams drawn as code (sizes, contrast, phone layouts, the text list under each), the Markdown and llms.txt output, and the checks before a PR. Use it whenever you add, edit, merge or move a page in guide/, rewrite docs after a code change, draw or change a diagram, or review a docs PR, even if the task only says "update the docs" or "document this".
In this repository11 other files it gives its agents.
- AGENTS.mdAGENTS.md
- guide/AGENTS.mdAGENTS.md
- spec/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- adding-an-agent-providerSkill
- ascii-character-animationSkill
- feature-doneSkill
- hive-browserSkill
- hivemind-custom-viewSkill
- hivemind-live-wallpaperSkill
- test-auditSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. About 0 are common, 8 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 31
If a page needs two types, it is two pages.
- Very specific: line 41
Find the home before you write: Run grep -rn "<the fact's key words>" guide/.
- Distinctive: line 44
Link, don't restate: Write "Your server relays it: see How devices connect." Do not repeat the paragraph.
- Distinctive: line 45
Do not repeat the paragraph.
- Very specific: line 48
Merge overlapping pages: If two pages cover the same ground, keep the one whose type fits.
- Very specific: line 57
When a design note in docs/ disagrees with the code, the code wins.
- Distinctive: line 72
Never lead with "waiting on you" or attention-management framing.
- Distinctive: line 74
No pill or chip badges, no decorative labels, no emoji.
- Distinctive: line 87
No Mermaid, no raster, no hand-written SVG: Every diagram comes from the builder, so one change to the style changes all of them.
- Distinctive: line 92
Contrast: every text colour at least 4.5:1 on every fill it sits on, in both themes.
- Distinctive: line 105
Every page is built twice: as HTML for people, and as Markdown for agents.
- Very specific: line 124
Run these from the repo root, one at a time on a busy machine (nice -n 10).
- Very specific: line 132
After a deploy, node scripts/check-links.mjs --live https://hivemind.griiken.com checks the real site, external links too.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Maintaining the docs
The guide is the pages in guide/, built by the Fumadocs app in site/docs/ and served at
https://hivemind.griiken.com/guide. docs/ at the repo root holds engineering notes. Those notes
are not the guide and are never published.
A good page does three things. It answers one question for a newcomer. It says each fact once. It reads as well to an agent fetching the Markdown as to a person in a browser. Everything below serves those three.
1. Where a page goes
Each folder in brackets is a tab: (get-started), (use), (concepts) (shown as How it
works), (extend), (api), (reference), (help). Its meta.json lists pages in sidebar
order, and ---Name--- starts a group. Pick the tab by the page type:
| Page type | Answers | Tab | Shape |
| Overview | What is this, and how do the parts fit? | first page of a tab or group | one diagram, its list, a few lines, cards to the next pages |
| Component | What does this one part do, and what does it talk to? | (concepts) › Components | diagram, list, then only what the diagram can't show |
| Concept | What is this idea (workspace, agent state, trust)? | (concepts) › Core concepts | definition first, then the rules |
| How-to | How do I get X done? | (use), (extend), (get-started) | <AgentPrompt>, then <Steps>, then what to check |
| Reference | What is every flag, setting, method, field? | (reference), (api) | complete tables, no story |
| Help | Something is wrong, or I need to install or update | (help) | symptom → cause → fix |
If a page needs two types, it is two pages. A how-to that starts explaining internals links to the component page. A component page that starts listing every flag links to the reference.
Mechanics of a new page are in references/writing-pages.md:
file name and address, frontmatter, meta.json, links, components.
2. One home per fact
Each fact lives on exactly one page. Every other page that needs it links there in one line.
- Find the home before you write. Run
grep -rn "<the fact's key words>" guide/. The page type decides who owns it. How it works owns how a part works. Use and Extend own how to do something with it. Reference owns complete lists. Help owns fixes. - Link, don't restate. Write "Your server relays it: see How devices connect." Do not repeat the paragraph. A one-clause reminder is fine; a second explanation is not.
- The list under a diagram is the explanation. The prose on that page adds only what the diagram can't show. It never walks the arrows again.
- Merge overlapping pages. If two pages cover the same ground, keep the one whose type fits.
Move anything unique into it and turn the other into links, or delete it. A deleted page goes
out of
meta.json. Fix every link to it: check-links finds the ones you missed. - Say it in the PR. The PR body lists each duplicate you removed and its single home.
3. Correct before anything else
- Say only what the code on
maindoes today. Check every command, flag, setting, menu label and path in the code before you write it, and keeppath:linenotes for the PR. - When a design note in
docs/disagrees with the code, the code wins. List each disagreement in the PR body, so someone fixes the note or the code. - Something removed leaves no trace: no "was", no "no longer", no "used to".
- A page's own claims about the docs (counts, "every page has…") are facts too. Check them.
4. Copy rules
- Plain words a newcomer reads without help. Use the words the app shows, in bold when they are on screen (Settings ▸ Plugins). No internal names, ticket numbers or abbreviations a user never sees.
- Short sentences, active voice, "you". One idea per sentence. Fewer words wins: cut a sentence the page works without.
- Lead lines (a page's first line, a description, a card) lead with what you get. Hivemind's lead is your agents build the workspace they work in: your own views, tools and widgets, and a workspace that agents and your programs drive.
- Never lead with "waiting on you" or attention-management framing. Never state a count of agents ("run 10 agents").
- No pill or chip badges, no decorative labels, no emoji. A heading or a bold word does the job.
- Each component (
<Note>,<Tip>,<Warning>, tabs, cards) only where it earns its place.<Warning>is for data loss or security.
5. Diagrams
Diagrams are drawn as code in site/scripts/diagrams/ and saved as guide/images/<name>.svg.
A page shows one with <Diagram name="<name>" caption="…" />, inline, so its text is selectable
and its colours follow the light or dark theme. Only a diagram that shows a mechanism earns a
place: parts and what flows between them, a sequence, or states. Never use a decorative one.
The rules (details, numbers and the drawing API in references/diagrams.md):
- No Mermaid, no raster, no hand-written SVG. Every diagram comes from the builder, so one change to the style changes all of them.
- Type size: labels at least 12px, box titles 15px, as rendered on the page. A diagram is at most 800 wide and drawn 1:1, so drawn size is page size. When it doesn't fit, cut words (shorter subtitles and wire labels) or reflow. Never shrink the art.
- Contrast: every text colour at least 4.5:1 on every fill it sits on, in both themes.
- Phones: a wide diagram scrolls inside its frame at full size. An overview that people must
read on a phone gets a
<name>-phonelayout about 320 wide, stacked top to bottom.<Diagram>swaps it in on small screens. - A text list right under every diagram:
- **A** → **B**: what goes, and how.It is what the Markdown copy,llms.txtand screen readers get. It says what the diagram says, not what it looks like. - Every fact in a diagram traces to code, like any other fact on the page.
- Check geometry with diagram-design's
verify-geometry.py: no label over a box, no wire through a label, nothing outside the frame. Then look at the PNGs.
6. Readable by agents
Every page is built twice: as HTML for people, and as Markdown for agents. Keep both working.
/guide/<name>.mdis the page as Markdown.llms.txtlists every page with its description.llms-full.txtis every page in one file. All come fromsite/docs/lib/source.ts. A<Diagram>becomes a link to its SVG plus your text list, which is why the list matters.- Each page's Copy page and Open menu comes free. Don't rebuild it in the page. The agents
that menu and every prompt box offer are one list, in
site/docs/lib/open-in.tsx. - A how-to page gets an
<AgentPrompt>near the top: the instructions a person pastes into their coding agent to do the job. It must work for an agent that never saw the page. The format and rules are in references/writing-pages.md. - An overview that agents act on gets a For agents section with a table: part → the
hive ctlcommands → the API methods (seeguide/(concepts)/architecture.mdx). When a command or method is added, renamed or removed, update that table and the reference page in the same PR. - The description in frontmatter feeds search and
llms.txt. Make it say what the page lets you do, in one line.
7. Before the PR
Run these from the repo root, one at a time on a busy machine (nice -n 10). The commands are in
references/checks.md.
npm run diagramsinsite/, if any diagram changed. Commit the.svgand thehtml/page.verify-geometry.pyonguide/images/*.svg: 0 findings.- The site build: the guide must compile.
node scripts/check-links.mjsinsite/: every link, picture,#heading, Markdown copy, Open menu and prompt-box link,llms.txtentry and redirect on the built site leads somewhere. After a deploy,node scripts/check-links.mjs --live https://hivemind.griiken.comchecks the real site, external links too.- Screenshots of every page you changed at 1440 and 390, light and dark. Look at them. Check the diagram text is readable, nothing scrolls the page sideways, and the dark theme has no unreadable grey.
A PR body lists what it moved or merged (and each fact's home), any code-vs-design disagreements, and the screenshots you looked at. Docs that describe a code change go in the same PR as the code.
Merging to main deploys the site (.github/workflows/site.yml runs on site/** and
guide/**). Do not merge a docs PR yourself unless you were told to.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

