AI Agent Readiness

AI Agent Readiness

This page is the machine-friendly map for NOX Homelab. It helps browser agents, AI assistants, and automated checks understand how the documentation site is organized and how to operate against it safely.

Start here when an agent needs to audit the site, answer questions from the documentation, or browser-test one of the homelab services.

Machine-readable entry points

  • /llms.txt — compact summary of the site, safety rules, and all published guides.
  • Archives — chronological list of posts.
  • Categories — broad topic grouping.
  • Tags — service and technology index.
  • Contact — correction and issue-reporting guidance.

Agentic browsing checklist

Use this checklist when adding or testing a web UI in the homelab.

  • Each important page should have one clear h1 and predictable section headings.
  • Service documentation should include purpose, route, access model, Compose files, Traefik labels, Authentik notes, backups, updates, troubleshooting, and related documentation.
  • Related posts should be cross-linked so agents can follow dependencies such as Traefik, Authentik, Cloudflare Companion, Headscale, and Pi-hole.
  • Avoid relying on visual card position alone; expose real links, text labels, and headings.

Accessibility tree

  • Buttons, links, form fields, menus, and toggles should have programmatic names.
  • Prefer semantic HTML before custom clickable div elements.
  • Do not hide interactive controls from the accessibility tree.
  • Use valid ARIA roles only when native HTML cannot express the control.

Stability for browser automation

  • Set image dimensions or reserve space for media to reduce layout shift.
  • Avoid injecting banners or cards above the active task after load.
  • Wait for UI state to settle before clicking during browser tests.
  • Prefer stable labels and URLs over fragile CSS selectors.

Machine-readable hints

  • Keep /llms.txt current.
  • Keep post descriptions accurate in front matter.
  • Use clear tags for services and dependencies.
  • Use placeholder domains in code blocks instead of private real domains.
  • Keep secrets, tokens, session cookies, private keys, and real infrastructure details out of public posts.

Service documentation map

Practical Lighthouse usage

The Lighthouse Agentic Browsing category is still emerging, so treat it as a readiness signal rather than a final grade.

Good results generally mean:

  • agents can discover important controls;
  • the accessibility tree describes the page accurately;
  • the layout is stable enough for automation;
  • machine-readable hints such as /llms.txt exist;
  • WebMCP-style integrations can be added later for custom apps.

For NOX Homelab, the first priority is documentation and dashboard reliability. WebMCP can come later for custom services that expose meaningful actions, such as queueing a task, checking a service, or opening a filtered dashboard.