​

Documentation Agent Instructions

​

Conventions

• Pure .md files, no .mdx or Mintlify components
• Frontmatter: only title (required by Mintlify)
• All navigation structure lives in docs.json
• Archive of old docs in docs/archive/ for reference

​

Writing Standards

​

Content

• Write for future-me — these are personal reference docs, not tutorials
• Optimize for evergreen content — things that change frequently belong in the blog, not reference pages
• Wrong docs are worse than no docs — if something’s outdated and can’t be fixed soon, remove it
• When a section accumulates too many caveats, rewrite it from scratch

​

Style

• Be concise — get to the point
• Active voice: “Traefik routes traffic to…” not “Traffic is routed by Traefik…”
• Consistent terminology — pick one name per thing and stick with it
• Specify language on code blocks (yaml, bash, etc.)
• Use mermaid for diagrams with complex relationships or branching logic
• Use nested bullet lists for simple hierarchies and linear flows
• No ASCII art diagrams

​

Structure

• One H1 per page (the title frontmatter handles this — don’t add another # heading)
• Sequential heading hierarchy — don’t skip levels (e.g. ## to ####)
• Keep content scannable: short paragraphs, bullet points, tables for structured data
• Unique heading names within a page

​

Linking

• Root-relative paths for internal links: [hardware](/infrastructure/hardware)
• Descriptive link text — “see backups” not “click here”
• Anchor links auto-generate from headers: ## External Drives → #external-drives

​

Media

• Only add screenshots/diagrams when text alone isn’t clear enough
• Alt text on all images
• Media is supplementary — the text should stand on its own

​

AGENTS.md Per-Service Files

• Keep files concise — if it’s intuitive for an agent to figure out, it shouldn’t be documented
• Never hardcode static info that can be discovered at runtime (env var names, ports, IPs, URLs)
• Agents should read compose files and .env files to discover those values
• No file trees, no how-tos, no method documentation — point to --help instead
• Only document: interface type (CLI/API/config-file), auth pattern, and non-obvious quirks