diff --git a/.agents/AGENTS.md b/.agents/AGENTS.md
index f8d11e7c69..8cbf42c023 100644
--- a/.agents/AGENTS.md
+++ b/.agents/AGENTS.md
@@ -389,6 +389,7 @@ Orchestration agents can create drafts in `draft/` for reusable parallel process
 | Cloud GPU | `tools/infrastructure/cloud-gpu.md` |
 | Containers | `tools/containers/orbstack.md` |
 | Networking | `services/networking/tailscale.md` |
+| Localhost | `services/hosting/local-hosting.md` (primary — localdev-helper.sh, dnsmasq, Traefik, mkcert, port registry), `services/hosting/localhost.md` (legacy reference) |
 | Personal AI | `tools/ai-assistants/openclaw.md` (deployment tiers, security, channels) |
 | Research | `tools/research/tech-stack-lookup.md`, `tech-stack-helper.sh`, `/tech-stack` (tech stack detection, reverse lookup) |
 | Model routing | `tools/context/model-routing.md`, `model-registry-helper.sh`, `fallback-chain-helper.sh`, `model-availability-helper.sh`, `budget-tracker-helper.sh` |
@@ -483,4 +484,4 @@ Proactively use a browser for: dev server verification, form testing, deployment
 
 ## Localhost Standards
 
-`.local` domains + SSL via Traefik + mkcert. See `services/hosting/localhost.md`.
+`.local` domains + SSL via Traefik + mkcert. See `services/hosting/local-hosting.md` (primary) or `services/hosting/localhost.md` (legacy).
diff --git a/.agents/services/hosting/localhost.md b/.agents/services/hosting/localhost.md
index 27c31a3dec..21d39b9126 100644
--- a/.agents/services/hosting/localhost.md
+++ b/.agents/services/hosting/localhost.md
@@ -1,5 +1,5 @@
 ---
-description: Localhost development environment setup
+description: Localhost development environment setup (legacy — see local-hosting.md)
 mode: subagent
 tools:
   read: true
@@ -11,6 +11,10 @@ tools:
   webfetch: false
 ---
 
+> **Legacy reference**: This file documents the original `localhost-helper.sh` approach.
+> For new projects, use [`local-hosting.md`](local-hosting.md) which covers the current
+> `localdev-helper.sh` system (dnsmasq + Traefik v3.3 + mkcert + port registry).
+
 # Localhost Development Environment Guide
 
 <!-- AI-CONTEXT-START -->
diff --git a/.agents/subagent-index.toon b/.agents/subagent-index.toon
index 0e7aae722d..7baaede48b 100644
--- a/.agents/subagent-index.toon
+++ b/.agents/subagent-index.toon
@@ -62,7 +62,7 @@ tools/wordpress/,WordPress ecosystem - local dev and fleet,wp-dev|wp-admin|local
 tools/containers/,Container runtimes - Docker and Linux VMs on macOS,orbstack
 tools/infrastructure/,Infrastructure - cloud GPU deployment and compute,cloud-gpu
 services/accessibility/,Unified web and email accessibility auditing - WCAG compliance remediation and monitoring,accessibility-audit
-services/hosting/,Hosting providers - DNS and cloud servers,hostinger|hetzner|cloudflare|cloudflare-platform|cloudron|closte
+services/hosting/,Hosting providers - DNS and cloud servers and local dev,local-hosting|localhost|hostinger|hetzner|cloudflare|cloudflare-platform|cloudron|closte
 services/networking/,Networking - mesh VPN and secure device connectivity,tailscale
 services/email/,Email services - transactional email deliverability and testing,ses|email-health-check|email-testing|email-delivery-test|email-design-test|email-delivery-testing|email-design-testing
 services/communications/,Communications - SMS voice and Matrix bot dispatch,twilio|telfon|matrix-bot