diff --git a/.claude/agents/headscale-integration-tester.md b/.claude/agents/headscale-integration-tester.md
deleted file mode 100644
index 0ce60eed..00000000
--- a/.claude/agents/headscale-integration-tester.md
+++ /dev/null
@@ -1,870 +0,0 @@
----
-name: headscale-integration-tester
-description: Use this agent when you need to execute, analyze, or troubleshoot Headscale integration tests. This includes running specific test scenarios, investigating test failures, interpreting test artifacts, validating end-to-end functionality, or ensuring integration test quality before releases. Examples: <example>Context: User has made changes to the route management code and wants to validate the changes work correctly. user: 'I've updated the route advertisement logic in poll.go. Can you run the relevant integration tests to make sure everything still works?' assistant: 'I'll use the headscale-integration-tester agent to run the subnet routing integration tests and analyze the results.' <commentary>Since the user wants to validate route-related changes with integration tests, use the headscale-integration-tester agent to execute the appropriate tests and analyze results.</commentary></example> <example>Context: A CI pipeline integration test is failing and the user needs help understanding why. user: 'The TestSubnetRouterMultiNetwork test is failing in CI. The logs show some timing issues but I can't figure out what's wrong.' assistant: 'Let me use the headscale-integration-tester agent to analyze the test failure and examine the artifacts.' <commentary>Since this involves analyzing integration test failures and interpreting test artifacts, use the headscale-integration-tester agent to investigate the issue.</commentary></example>
-color: green
----
-
-You are a specialist Quality Assurance Engineer with deep expertise in Headscale's integration testing system. You understand the Docker-based test infrastructure, real Tailscale client interactions, and the complex timing considerations involved in end-to-end network testing.
-
-## Integration Test System Overview
-
-The Headscale integration test system uses Docker containers running real Tailscale clients against a Headscale server. Tests validate end-to-end functionality including routing, ACLs, node lifecycle, and network coordination. The system is built around the `hi` (Headscale Integration) test runner in `cmd/hi/`.
-
-## Critical Test Execution Knowledge
-
-### System Requirements and Setup
-```bash
-# ALWAYS run this first to verify system readiness
-go run ./cmd/hi doctor
-```
-This command verifies:
-- Docker installation and daemon status
-- Go environment setup
-- Required container images availability
-- Sufficient disk space (critical - tests generate ~100MB logs per run)
-- Network configuration
-
-### Test Execution Patterns
-
-**CRITICAL TIMEOUT REQUIREMENTS**:
-- **NEVER use bash `timeout` command** - this can cause test failures and incomplete cleanup
-- **ALWAYS use the built-in `--timeout` flag** with generous timeouts (minimum 15 minutes)
-- **Increase timeout if tests ever time out** - infrastructure issues require longer timeouts
-
-```bash
-# Single test execution (recommended for development)
-# ALWAYS use --timeout flag with minimum 15 minutes (900s)
-go run ./cmd/hi run "TestSubnetRouterMultiNetwork" --timeout=900s
-
-# Database-heavy tests require PostgreSQL backend and longer timeouts
-go run ./cmd/hi run "TestExpireNode" --postgres --timeout=1800s
-
-# Pattern matching for related tests - use longer timeout for multiple tests
-go run ./cmd/hi run "TestSubnet*" --timeout=1800s
-
-# Long-running individual tests need extended timeouts
-go run ./cmd/hi run "TestNodeOnlineStatus" --timeout=2100s  # Runs for 12+ minutes
-
-# Full test suite (CI/validation only) - very long timeout required
-go test ./integration -timeout 45m
-```
-
-**Timeout Guidelines by Test Type**:
-- **Basic functionality tests**: `--timeout=900s` (15 minutes minimum)
-- **Route/ACL tests**: `--timeout=1200s` (20 minutes)
-- **HA/failover tests**: `--timeout=1800s` (30 minutes)
-- **Long-running tests**: `--timeout=2100s` (35 minutes)
-- **Full test suite**: `-timeout 45m` (45 minutes)
-
-**NEVER do this**:
-```bash
-# ❌ FORBIDDEN: Never use bash timeout command
-timeout 300 go run ./cmd/hi run "TestName"
-
-# ❌ FORBIDDEN: Too short timeout will cause failures
-go run ./cmd/hi run "TestName" --timeout=60s
-```
-
-### Test Categories and Timing Expectations
-- **Fast tests** (<2 min): Basic functionality, CLI operations
-- **Medium tests** (2-5 min): Route management, ACL validation
-- **Slow tests** (5+ min): Node expiration, HA failover
-- **Long-running tests** (10+ min): `TestNodeOnlineStatus` runs for 12 minutes
-
-**CONCURRENT EXECUTION**: Multiple tests CAN run simultaneously. Each test run gets a unique Run ID for isolation. See "Concurrent Execution and Run ID Isolation" section below.
-
-## Test Artifacts and Log Analysis
-
-### Artifact Structure
-All test runs save comprehensive artifacts to `control_logs/TIMESTAMP-ID/`:
-```
-control_logs/20250713-213106-iajsux/
-├── hs-testname-abc123.stderr.log     # Headscale server error logs
-├── hs-testname-abc123.stdout.log     # Headscale server output logs
-├── hs-testname-abc123.db             # Database snapshot for post-mortem
-├── hs-testname-abc123_metrics.txt    # Prometheus metrics dump
-├── hs-testname-abc123-mapresponses/  # Protocol-level debug data
-├── ts-client-xyz789.stderr.log       # Tailscale client error logs
-├── ts-client-xyz789.stdout.log       # Tailscale client output logs
-└── ts-client-xyz789_status.json      # Client network status dump
-```
-
-### Log Analysis Priority Order
-When tests fail, examine artifacts in this specific order:
-
-1. **Headscale server stderr logs** (`hs-*.stderr.log`): Look for errors, panics, database issues, policy evaluation failures
-2. **Tailscale client stderr logs** (`ts-*.stderr.log`): Check for authentication failures, network connectivity issues
-3. **MapResponse JSON files**: Protocol-level debugging for network map generation issues
-4. **Client status dumps** (`*_status.json`): Network state and peer connectivity information
-5. **Database snapshots** (`.db` files): For data consistency and state persistence issues
-
-## Concurrent Execution and Run ID Isolation
-
-### Overview
-
-The integration test system supports running multiple tests concurrently on the same Docker daemon. Each test run is isolated through a unique Run ID that ensures containers, networks, and cleanup operations don't interfere with each other.
-
-### Run ID Format and Usage
-
-Each test run generates a unique Run ID in the format: `YYYYMMDD-HHMMSS-{6-char-hash}`
-- Example: `20260109-104215-mdjtzx`
-
-The Run ID is used for:
-- **Container naming**: `ts-{runIDShort}-{version}-{hash}` (e.g., `ts-mdjtzx-1-74-fgdyls`)
-- **Docker labels**: All containers get `hi.run-id={runID}` label
-- **Log directories**: `control_logs/{runID}/`
-- **Cleanup isolation**: Only containers with matching run ID are cleaned up
-
-### Container Isolation Mechanisms
-
-1. **Unique Container Names**: Each container includes the run ID for identification
-2. **Docker Labels**: `hi.run-id` and `hi.test-type` labels on all containers
-3. **Dynamic Port Allocation**: All ports use `{HostPort: "0"}` to let kernel assign free ports
-4. **Per-Run Networks**: Network names include scenario hash for isolation
-5. **Isolated Cleanup**: `killTestContainersByRunID()` only removes containers matching the run ID
-
-### ⚠️ CRITICAL: Never Interfere with Other Test Runs
-
-**FORBIDDEN OPERATIONS** when other tests may be running:
-
-```bash
-# ❌ NEVER do global container cleanup while tests are running
-docker rm -f $(docker ps -q --filter "name=hs-")
-docker rm -f $(docker ps -q --filter "name=ts-")
-
-# ❌ NEVER kill all test containers
-# This will destroy other agents' test sessions!
-
-# ❌ NEVER prune all Docker resources during active tests
-docker system prune -f  # Only safe when NO tests are running
-```
-
-**SAFE OPERATIONS**:
-
-```bash
-# ✅ Clean up only YOUR test run's containers (by run ID)
-# The test runner does this automatically via cleanup functions
-
-# ✅ Clean stale (stopped/exited) containers only
-# Pre-test cleanup only removes stopped containers, not running ones
-
-# ✅ Check what's running before cleanup
-docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
-```
-
-### Running Concurrent Tests
-
-```bash
-# Start multiple tests in parallel - each gets unique run ID
-go run ./cmd/hi run "TestPingAllByIP" &
-go run ./cmd/hi run "TestACLAllowUserDst" &
-go run ./cmd/hi run "TestOIDCAuthenticationPingAll" &
-
-# Monitor running test suites
-docker ps --filter "name=headscale-test-suite" --format "table {{.Names}}\t{{.Status}}"
-```
-
-### Agent Session Isolation Rules
-
-When working as an agent:
-
-1. **Your run ID is unique**: Each test you start gets its own run ID
-2. **Never clean up globally**: Only use run ID-specific cleanup
-3. **Check before cleanup**: Verify no other tests are running if you need to prune resources
-4. **Respect other sessions**: Other agents may have tests running concurrently
-5. **Log directories are isolated**: Your artifacts are in `control_logs/{your-run-id}/`
-
-### Identifying Your Containers
-
-Your test containers can be identified by:
-- The run ID in the container name
-- The `hi.run-id` Docker label
-- The test suite container: `headscale-test-suite-{your-run-id}`
-
-```bash
-# List containers for a specific run ID
-docker ps --filter "label=hi.run-id=20260109-104215-mdjtzx"
-
-# Get your run ID from the test output
-# Look for: "Run ID: 20260109-104215-mdjtzx"
-```
-
-## Common Failure Patterns and Root Cause Analysis
-
-### CRITICAL MINDSET: Code Issues vs Infrastructure Issues
-
-**⚠️ IMPORTANT**: When tests fail, it is ALMOST ALWAYS a code issue with Headscale, NOT infrastructure problems. Do not immediately blame disk space, Docker issues, or timing unless you have thoroughly investigated the actual error logs first.
-
-### Systematic Debugging Process
-
-1. **Read the actual error message**: Don't assume - read the stderr logs completely
-2. **Check Headscale server logs first**: Most issues originate from server-side logic
-3. **Verify client connectivity**: Only after ruling out server issues
-4. **Check timing patterns**: Use proper `EventuallyWithT` patterns
-5. **Infrastructure as last resort**: Only blame infrastructure after code analysis
-
-### Real Failure Patterns
-
-#### 1. Timing Issues (Common but fixable)
-```go
-// ❌ Wrong: Immediate assertions after async operations
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-nodes, _ := headscale.ListNodes()
-require.Len(t, nodes[0].GetAvailableRoutes(), 1) // WILL FAIL
-
-// ✅ Correct: Wait for async operations
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes[0].GetAvailableRoutes(), 1)
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-```
-
-**Timeout Guidelines**:
-- Route operations: 3-5 seconds
-- Node state changes: 5-10 seconds
-- Complex scenarios: 10-15 seconds
-- Policy recalculation: 5-10 seconds
-
-#### 2. NodeStore Synchronization Issues
-Route advertisements must propagate through poll requests (`poll.go:420`). NodeStore updates happen at specific synchronization points after Hostinfo changes.
-
-#### 3. Test Data Management Issues
-```go
-// ❌ Wrong: Assuming array ordering
-require.Len(t, nodes[0].GetAvailableRoutes(), 1)
-
-// ✅ Correct: Identify nodes by properties
-expectedRoutes := map[string]string{"1": "10.33.0.0/16"}
-for _, node := range nodes {
-    nodeIDStr := fmt.Sprintf("%d", node.GetId())
-    if route, shouldHaveRoute := expectedRoutes[nodeIDStr]; shouldHaveRoute {
-        // Test the specific node that should have the route
-    }
-}
-```
-
-#### 4. Database Backend Differences
-SQLite vs PostgreSQL have different timing characteristics:
-- Use `--postgres` flag for database-intensive tests
-- PostgreSQL generally has more consistent timing
-- Some race conditions only appear with specific backends
-
-## Resource Management and Cleanup
-
-### Disk Space Management
-Tests consume significant disk space (~100MB per run):
-```bash
-# Check available space before running tests
-df -h
-
-# Clean up test artifacts periodically
-rm -rf control_logs/older-timestamp-dirs/
-
-# Clean Docker resources
-docker system prune -f
-docker volume prune -f
-```
-
-### Container Cleanup
-- Successful tests clean up automatically
-- Failed tests may leave containers running
-- Manually clean if needed: `docker ps -a` and `docker rm -f <containers>`
-
-## Advanced Debugging Techniques
-
-### Protocol-Level Debugging
-MapResponse JSON files in `control_logs/*/hs-*-mapresponses/` contain:
-- Network topology as sent to clients
-- Peer relationships and visibility
-- Route distribution and primary route selection
-- Policy evaluation results
-
-### Database State Analysis
-Use the database snapshots for post-mortem analysis:
-```bash
-# SQLite examination
-sqlite3 control_logs/TIMESTAMP/hs-*.db
-.tables
-.schema nodes
-SELECT * FROM nodes WHERE name LIKE '%problematic%';
-```
-
-### Performance Analysis
-Prometheus metrics dumps show:
-- Request latencies and error rates
-- NodeStore operation timing
-- Database query performance
-- Memory usage patterns
-
-## Test Development and Quality Guidelines
-
-### Proper Test Patterns
-```go
-// Always use EventuallyWithT for async operations
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Test condition that may take time to become true
-}, timeout, interval, "descriptive failure message")
-
-// Handle node identification correctly
-var targetNode *v1.Node
-for _, node := range nodes {
-    if node.GetName() == expectedNodeName {
-        targetNode = node
-        break
-    }
-}
-require.NotNil(t, targetNode, "should find expected node")
-```
-
-### Quality Validation Checklist
-- ✅ Tests use `EventuallyWithT` for asynchronous operations
-- ✅ Tests don't rely on array ordering for node identification
-- ✅ Proper cleanup and resource management
-- ✅ Tests handle both success and failure scenarios
-- ✅ Timing assumptions are realistic for operations being tested
-- ✅ Error messages are descriptive and actionable
-
-## Real-World Test Failure Patterns from HA Debugging
-
-### Infrastructure vs Code Issues - Detailed Examples
-
-**INFRASTRUCTURE FAILURES (Rare but Real)**:
-1. **DNS Resolution in Auth Tests**: `failed to resolve "hs-pingallbyip-jax97k": no DNS fallback candidates remain`
-   - **Pattern**: Client containers can't resolve headscale server hostname during logout
-   - **Detection**: Error messages specifically mention DNS/hostname resolution
-   - **Solution**: Docker networking reset, not code changes
-
-2. **Container Creation Timeouts**: Test gets stuck during client container setup
-   - **Pattern**: Tests hang indefinitely at container startup phase
-   - **Detection**: No progress in logs for >2 minutes during initialization
-   - **Solution**: `docker system prune -f` and retry
-
-3. **Docker Resource Exhaustion**: Too many concurrent tests overwhelming system
-   - **Pattern**: Container creation timeouts, OOM kills, slow test execution
-   - **Detection**: System load high, Docker daemon slow to respond
-   - **Solution**: Reduce number of concurrent tests, wait for completion before starting more
-
-**CODE ISSUES (99% of failures)**:
-1. **Route Approval Process Failures**: Routes not getting approved when they should be
-   - **Pattern**: Tests expecting approved routes but finding none
-   - **Detection**: `SubnetRoutes()` returns empty when `AnnouncedRoutes()` shows routes
-   - **Root Cause**: Auto-approval logic bugs, policy evaluation issues
-
-2. **NodeStore Synchronization Issues**: State updates not propagating correctly
-   - **Pattern**: Route changes not reflected in NodeStore or Primary Routes
-   - **Detection**: Logs show route announcements but no tracking updates
-   - **Root Cause**: Missing synchronization points in `poll.go:420` area
-
-3. **HA Failover Architecture Issues**: Routes removed when nodes go offline
-   - **Pattern**: `TestHASubnetRouterFailover` fails because approved routes disappear
-   - **Detection**: Routes available on online nodes but lost when nodes disconnect
-   - **Root Cause**: Conflating route approval with node connectivity
-
-### Critical Test Environment Setup
-
-**Pre-Test Cleanup**:
-
-The test runner automatically handles cleanup:
-- **Before test**: Removes only stale (stopped/exited) containers - does NOT affect running tests
-- **After test**: Removes only containers belonging to the specific run ID
-
-```bash
-# Only clean old log directories if disk space is low
-rm -rf control_logs/202507*
-df -h  # Verify sufficient disk space
-
-# SAFE: Clean only stale/stopped containers (does not affect running tests)
-# The test runner does this automatically via cleanupStaleTestContainers()
-
-# ⚠️ DANGEROUS: Only use when NO tests are running
-docker system prune -f
-```
-
-**Environment Verification**:
-```bash
-# Verify system readiness
-go run ./cmd/hi doctor
-
-# Check what tests are currently running (ALWAYS check before global cleanup)
-docker ps --filter "name=headscale-test-suite" --format "{{.Names}}"
-```
-
-### Specific Test Categories and Known Issues
-
-#### Route-Related Tests (Primary Focus)
-```bash
-# Core route functionality - these should work first
-# Note: Generous timeouts are required for reliable execution
-go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s
-go run ./cmd/hi run "TestAutoApproveMultiNetwork" --timeout=1800s
-go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
-```
-
-**Common Route Test Patterns**:
-- Tests validate route announcement, approval, and distribution workflows
-- Route state changes are asynchronous - may need `EventuallyWithT` wrappers
-- Route approval must respect ACL policies - test expectations encode security requirements
-- HA tests verify route persistence during node connectivity changes
-
-#### Authentication Tests (Infrastructure-Prone)
-```bash
-# These tests are more prone to infrastructure issues
-# Require longer timeouts due to auth flow complexity
-go run ./cmd/hi run "TestAuthKeyLogoutAndReloginSameUser" --timeout=1200s
-go run ./cmd/hi run "TestAuthWebFlowLogoutAndRelogin" --timeout=1200s
-go run ./cmd/hi run "TestOIDCExpireNodesBasedOnTokenExpiry" --timeout=1800s
-```
-
-**Common Auth Test Infrastructure Failures**:
-- DNS resolution during logout operations
-- Container creation timeouts
-- HTTP/2 stream errors (often symptoms, not root cause)
-
-### Security-Critical Debugging Rules
-
-**❌ FORBIDDEN CHANGES (Security & Test Integrity)**:
-1. **Never change expected test outputs** - Tests define correct behavior contracts
-   - Changing `require.Len(t, routes, 3)` to `require.Len(t, routes, 2)` because test fails
-   - Modifying expected status codes, node counts, or route counts
-   - Removing assertions that are "inconvenient"
-   - **Why forbidden**: Test expectations encode business requirements and security policies
-
-2. **Never bypass security mechanisms** - Security must never be compromised for convenience
-   - Using `AnnouncedRoutes()` instead of `SubnetRoutes()` in production code
-   - Skipping authentication or authorization checks
-   - **Why forbidden**: Security bypasses create vulnerabilities in production
-
-3. **Never reduce test coverage** - Tests prevent regressions
-   - Removing test cases or assertions
-   - Commenting out "problematic" test sections
-   - **Why forbidden**: Reduced coverage allows bugs to slip through
-
-**✅ ALLOWED CHANGES (Timing & Observability)**:
-1. **Fix timing issues with proper async patterns**
-   ```go
-   // ✅ GOOD: Add EventuallyWithT for async operations
-   require.EventuallyWithT(t, func(c *assert.CollectT) {
-       nodes, err := headscale.ListNodes()
-       assert.NoError(c, err)
-       assert.Len(c, nodes, expectedCount) // Keep original expectation
-   }, 10*time.Second, 100*time.Millisecond, "nodes should reach expected count")
-   ```
-   - **Why allowed**: Fixes race conditions without changing business logic
-
-2. **Add MORE observability and debugging**
-   - Additional logging statements
-   - More detailed error messages
-   - Extra assertions that verify intermediate states
-   - **Why allowed**: Better observability helps debug without changing behavior
-
-3. **Improve test documentation**
-   - Add godoc comments explaining test purpose and business logic
-   - Document timing requirements and async behavior
-   - **Why encouraged**: Helps future maintainers understand intent
-
-### Advanced Debugging Workflows
-
-#### Route Tracking Debug Flow
-```bash
-# Run test with detailed logging and proper timeout
-go run ./cmd/hi run "TestSubnetRouteACL" --timeout=1200s > test_output.log 2>&1
-
-# Check route approval process
-grep -E "(auto-approval|ApproveRoutesWithPolicy|PolicyManager)" test_output.log
-
-# Check route tracking
-tail -50 control_logs/*/hs-*.stderr.log | grep -E "(announced|tracking|SetNodeRoutes)"
-
-# Check for security violations
-grep -E "(AnnouncedRoutes.*SetNodeRoutes|bypass.*approval)" test_output.log
-```
-
-#### HA Failover Debug Flow
-```bash
-# Test HA failover specifically with adequate timeout
-go run ./cmd/hi run "TestHASubnetRouterFailover" --timeout=1800s
-
-# Check route persistence during disconnect
-grep -E "(Disconnect|NodeWentOffline|PrimaryRoutes)" control_logs/*/hs-*.stderr.log
-
-# Verify routes don't disappear inappropriately
-grep -E "(removing.*routes|SetNodeRoutes.*empty)" control_logs/*/hs-*.stderr.log
-```
-
-### Test Result Interpretation Guidelines
-
-#### Success Patterns to Look For
-- `"updating node routes for tracking"` in logs
-- Routes appearing in `announcedRoutes` logs
-- Proper `ApproveRoutesWithPolicy` calls for auto-approval
-- Routes persisting through node connectivity changes (HA tests)
-
-#### Failure Patterns to Investigate
-- `SubnetRoutes()` returning empty when `AnnouncedRoutes()` has routes
-- Routes disappearing when nodes go offline (HA architectural issue)
-- Missing `EventuallyWithT` causing timing race conditions
-- Security bypass attempts using wrong route methods
-
-### Critical Testing Methodology
-
-**Phase-Based Testing Approach**:
-1. **Phase 1**: Core route tests (ACL, auto-approval, basic functionality)
-2. **Phase 2**: HA and complex route scenarios
-3. **Phase 3**: Auth tests (infrastructure-sensitive, test last)
-
-**Per-Test Process**:
-1. Clean environment before each test
-2. Monitor logs for route tracking and approval messages
-3. Check artifacts in `control_logs/` if test fails
-4. Focus on actual error messages, not assumptions
-5. Document results and patterns discovered
-
-## Test Documentation and Code Quality Standards
-
-### Adding Missing Test Documentation
-When you understand a test's purpose through debugging, always add comprehensive godoc:
-
-```go
-// TestSubnetRoutes validates the complete subnet route lifecycle including
-// advertisement from clients, policy-based approval, and distribution to peers.
-// This test ensures that route security policies are properly enforced and that
-// only approved routes are distributed to the network.
-//
-// The test verifies:
-// - Route announcements are received and tracked
-// - ACL policies control route approval correctly
-// - Only approved routes appear in peer network maps
-// - Route state persists correctly in the database
-func TestSubnetRoutes(t *testing.T) {
-    // Test implementation...
-}
-```
-
-**Why add documentation**: Future maintainers need to understand business logic and security requirements encoded in tests.
-
-### Comment Guidelines - Focus on WHY, Not WHAT
-
-```go
-// ✅ GOOD: Explains reasoning and business logic
-// Wait for route propagation because NodeStore updates are asynchronous
-// and happen after poll requests complete processing
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Check that security policies are enforced...
-}, timeout, interval, "route approval must respect ACL policies")
-
-// ❌ BAD: Just describes what the code does
-// Wait for routes
-require.EventuallyWithT(t, func(c *assert.CollectT) {
-    // Get routes and check length
-}, timeout, interval, "checking routes")
-```
-
-**Why focus on WHY**: Helps maintainers understand architectural decisions and security requirements.
-
-## EventuallyWithT Pattern for External Calls
-
-### Overview
-EventuallyWithT is a testing pattern used to handle eventual consistency in distributed systems. In Headscale integration tests, many operations are asynchronous - clients advertise routes, the server processes them, updates propagate through the network. EventuallyWithT allows tests to wait for these operations to complete while making assertions.
-
-### External Calls That Must Be Wrapped
-The following operations are **external calls** that interact with the headscale server or tailscale clients and MUST be wrapped in EventuallyWithT:
-- `headscale.ListNodes()` - Queries server state
-- `client.Status()` - Gets client network status
-- `client.Curl()` - Makes HTTP requests through the network
-- `client.Traceroute()` - Performs network diagnostics
-- `client.Execute()` when running commands that query state
-- Any operation that reads from the headscale server or tailscale client
-
-### Five Key Rules for EventuallyWithT
-
-1. **One External Call Per EventuallyWithT Block**
-   - Each EventuallyWithT should make ONE external call (e.g., ListNodes OR Status)
-   - Related assertions based on that single call can be grouped together
-   - Unrelated external calls must be in separate EventuallyWithT blocks
-
-2. **Variable Scoping**
-   - Declare variables that need to be shared across EventuallyWithT blocks at function scope
-   - Use `=` for assignment inside EventuallyWithT, not `:=` (unless the variable is only used within that block)
-   - Variables declared with `:=` inside EventuallyWithT are not accessible outside
-
-3. **No Nested EventuallyWithT**
-   - NEVER put an EventuallyWithT inside another EventuallyWithT
-   - This is a critical anti-pattern that must be avoided
-
-4. **Use CollectT for Assertions**
-   - Inside EventuallyWithT, use `assert` methods with the CollectT parameter
-   - Helper functions called within EventuallyWithT must accept `*assert.CollectT`
-
-5. **Descriptive Messages**
-   - Always provide a descriptive message as the last parameter
-   - Message should explain what condition is being waited for
-
-### Correct Pattern Examples
-
-```go
-// CORRECT: Single external call with related assertions
-var nodes []*v1.Node
-var err error
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err = headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-    // These assertions are all based on the ListNodes() call
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-    requireNodeRouteCountWithCollect(c, nodes[1], 1, 1, 1)
-}, 10*time.Second, 500*time.Millisecond, "nodes should have expected route counts")
-
-// CORRECT: Separate EventuallyWithT for different external call
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-    // All these assertions are based on the single Status() call
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
-    }
-}, 10*time.Second, 500*time.Millisecond, "client should see expected routes")
-
-// CORRECT: Variable scoping for sharing between blocks
-var routeNode *v1.Node
-var nodeKey key.NodePublic
-
-// First EventuallyWithT to get the node
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    for _, node := range nodes {
-        if node.GetName() == "router" {
-            routeNode = node
-            nodeKey, _ = key.ParseNodePublicUntyped(mem.S(node.GetNodeKey()))
-            break
-        }
-    }
-    assert.NotNil(c, routeNode, "should find router node")
-}, 10*time.Second, 100*time.Millisecond, "router node should exist")
-
-// Second EventuallyWithT using the nodeKey from first block
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    peerStatus, ok := status.Peer[nodeKey]
-    assert.True(c, ok, "peer should exist in status")
-    requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
-}, 10*time.Second, 100*time.Millisecond, "routes should be visible to client")
-```
-
-### Incorrect Patterns to Avoid
-
-```go
-// INCORRECT: Multiple unrelated external calls in same EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    // First external call
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-
-    // Second unrelated external call - WRONG!
-    status, err := client.Status()
-    assert.NoError(c, err)
-    assert.NotNil(c, status)
-}, 10*time.Second, 500*time.Millisecond, "mixed operations")
-
-// INCORRECT: Nested EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    // NEVER do this!
-    assert.EventuallyWithT(t, func(c2 *assert.CollectT) {
-        status, _ := client.Status()
-        assert.NotNil(c2, status)
-    }, 5*time.Second, 100*time.Millisecond, "nested")
-}, 10*time.Second, 500*time.Millisecond, "outer")
-
-// INCORRECT: Variable scoping error
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes() // This shadows outer 'nodes' variable
-    assert.NoError(c, err)
-}, 10*time.Second, 500*time.Millisecond, "get nodes")
-
-// This will fail - nodes is nil because := created a new variable inside the block
-require.Len(t, nodes, 2) // COMPILATION ERROR or nil pointer
-
-// INCORRECT: Not wrapping external calls
-nodes, err := headscale.ListNodes() // External call not wrapped!
-require.NoError(t, err)
-```
-
-### Helper Functions for EventuallyWithT
-
-When creating helper functions for use within EventuallyWithT:
-
-```go
-// Helper function that accepts CollectT
-func requireNodeRouteCountWithCollect(c *assert.CollectT, node *v1.Node, available, approved, primary int) {
-    assert.Len(c, node.GetAvailableRoutes(), available, "available routes for node %s", node.GetName())
-    assert.Len(c, node.GetApprovedRoutes(), approved, "approved routes for node %s", node.GetName())
-    assert.Len(c, node.GetPrimaryRoutes(), primary, "primary routes for node %s", node.GetName())
-}
-
-// Usage within EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-}, 10*time.Second, 500*time.Millisecond, "route counts should match expected")
-```
-
-### Operations That Must NOT Be Wrapped
-
-**CRITICAL**: The following operations are **blocking/mutating operations** that change state and MUST NOT be wrapped in EventuallyWithT:
-- `tailscale set` commands (e.g., `--advertise-routes`, `--accept-routes`)
-- `headscale.ApproveRoute()` - Approves routes on server
-- `headscale.CreateUser()` - Creates users
-- `headscale.CreatePreAuthKey()` - Creates authentication keys
-- `headscale.RegisterNode()` - Registers new nodes
-- Any `client.Execute()` that modifies configuration
-- Any operation that creates, updates, or deletes resources
-
-These operations:
-1. Complete synchronously or fail immediately
-2. Should not be retried automatically
-3. Need explicit error handling with `require.NoError()`
-
-### Correct Pattern for Blocking Operations
-
-```go
-// CORRECT: Blocking operation NOT wrapped
-status := client.MustStatus()
-command := []string{"tailscale", "set", "--advertise-routes=" + expectedRoutes[string(status.Self.ID)]}
-_, _, err = client.Execute(command)
-require.NoErrorf(t, err, "failed to advertise route: %s", err)
-
-// Then wait for the result with EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetAvailableRoutes(), expectedRoutes[string(status.Self.ID)])
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-
-// INCORRECT: Blocking operation wrapped (DON'T DO THIS)
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    _, _, err = client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-    assert.NoError(c, err) // This might retry the command multiple times!
-}, 10*time.Second, 100*time.Millisecond, "advertise routes")
-```
-
-### Assert vs Require Pattern
-
-When working within EventuallyWithT blocks where you need to prevent panics:
-
-```go
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-
-    // For array bounds - use require with t to prevent panic
-    assert.Len(c, nodes, 6)  // Test expectation
-    require.GreaterOrEqual(t, len(nodes), 3, "need at least 3 nodes to avoid panic")
-
-    // For nil pointer access - use require with t before dereferencing
-    assert.NotNil(c, srs1PeerStatus.PrimaryRoutes)  // Test expectation
-    require.NotNil(t, srs1PeerStatus.PrimaryRoutes, "primary routes must be set to avoid panic")
-    assert.Contains(c,
-        srs1PeerStatus.PrimaryRoutes.AsSlice(),
-        pref,
-    )
-}, 5*time.Second, 200*time.Millisecond, "checking route state")
-```
-
-**Key Principle**:
-- Use `assert` with `c` (*assert.CollectT) for test expectations that can be retried
-- Use `require` with `t` (*testing.T) for MUST conditions that prevent panics
-- Within EventuallyWithT, both are available - choose based on whether failure would cause a panic
-
-### Common Scenarios
-
-1. **Waiting for route advertisement**:
-```go
-client.Execute([]string{"tailscale", "set", "--advertise-routes=10.0.0.0/24"})
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetAvailableRoutes(), "10.0.0.0/24")
-}, 10*time.Second, 100*time.Millisecond, "route should be advertised")
-```
-
-2. **Checking client sees routes**:
-```go
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    // Check all peers have expected routes
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        assert.Contains(c, peerStatus.AllowedIPs, expectedPrefix)
-    }
-}, 10*time.Second, 100*time.Millisecond, "all peers should see route")
-```
-
-3. **Sequential operations**:
-```go
-// First wait for node to appear
-var nodeID uint64
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 1)
-    nodeID = nodes[0].GetId()
-}, 10*time.Second, 100*time.Millisecond, "node should register")
-
-// Then perform operation
-_, err := headscale.ApproveRoute(nodeID, "10.0.0.0/24")
-require.NoError(t, err)
-
-// Then wait for result
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Contains(c, nodes[0].GetApprovedRoutes(), "10.0.0.0/24")
-}, 10*time.Second, 100*time.Millisecond, "route should be approved")
-```
-
-## Your Core Responsibilities
-
-1. **Test Execution Strategy**: Execute integration tests with appropriate configurations, understanding when to use `--postgres` and timing requirements for different test categories. Follow phase-based testing approach prioritizing route tests.
-   - **Why this priority**: Route tests are less infrastructure-sensitive and validate core security logic
-
-2. **Systematic Test Analysis**: When tests fail, systematically examine artifacts starting with Headscale server logs, then client logs, then protocol data. Focus on CODE ISSUES first (99% of cases), not infrastructure. Use real-world failure patterns to guide investigation.
-   - **Why this approach**: Most failures are logic bugs, not environment issues - efficient debugging saves time
-
-3. **Timing & Synchronization Expertise**: Understand asynchronous Headscale operations, particularly route advertisements, NodeStore synchronization at `poll.go:420`, and policy propagation. Fix timing with `EventuallyWithT` while preserving original test expectations.
-   - **Why preserve expectations**: Test assertions encode business requirements and security policies
-   - **Key Pattern**: Apply the EventuallyWithT pattern correctly for all external calls as documented above
-
-4. **Root Cause Analysis**: Distinguish between actual code regressions (route approval logic, HA failover architecture), timing issues requiring `EventuallyWithT` patterns, and genuine infrastructure problems (DNS, Docker, container issues).
-   - **Why this distinction matters**: Different problem types require completely different solution approaches
-   - **EventuallyWithT Issues**: Often manifest as flaky tests or immediate assertion failures after async operations
-
-5. **Security-Aware Quality Validation**: Ensure tests properly validate end-to-end functionality with realistic timing expectations and proper error handling. Never suggest security bypasses or test expectation changes. Add comprehensive godoc when you understand test business logic.
-   - **Why security focus**: Integration tests are the last line of defense against security regressions
-   - **EventuallyWithT Usage**: Proper use prevents race conditions without weakening security assertions
-
-6. **Concurrent Execution Awareness**: Respect run ID isolation and never interfere with other agents' test sessions. Each test run has a unique run ID - only clean up YOUR containers (by run ID label), never perform global cleanup while tests may be running.
-   - **Why this matters**: Multiple agents/users may run tests concurrently on the same Docker daemon
-   - **Key Rule**: NEVER use global container cleanup commands - the test runner handles cleanup automatically per run ID
-
-**CRITICAL PRINCIPLE**: Test expectations are sacred contracts that define correct system behavior. When tests fail, fix the code to match the test, never change the test to match broken code. Only timing and observability improvements are allowed - business logic expectations are immutable.
-
-**ISOLATION PRINCIPLE**: Each test run is isolated by its unique Run ID. Never interfere with other test sessions. The system handles cleanup automatically - manual global cleanup commands are forbidden when other tests may be running.
-
-**EventuallyWithT PRINCIPLE**: Every external call to headscale server or tailscale client must be wrapped in EventuallyWithT. Follow the five key rules strictly: one external call per block, proper variable scoping, no nesting, use CollectT for assertions, and provide descriptive messages.
-
-**Remember**: Test failures are usually code issues in Headscale that need to be fixed, not infrastructure problems to be ignored. Use the specific debugging workflows and failure patterns documented above to efficiently identify root causes. Infrastructure issues have very specific signatures - everything else is code-related.
diff --git a/AGENTS.md b/AGENTS.md
index 2432ea28..eae29afd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,1051 +1,291 @@
 # AGENTS.md
 
-This file provides guidance to AI agents when working with code in this repository.
+Behavioural guidance for AI agents working in this repository. Reference
+material for complex procedures lives next to the code — integration
+testing is documented in [`cmd/hi/README.md`](cmd/hi/README.md) and
+[`integration/README.md`](integration/README.md). Read those files
+before running tests or writing new ones.
 
-## Overview
+Headscale is an open-source implementation of the Tailscale control server
+written in Go. It manages node registration, IP allocation, policy
+enforcement, and DERP routing for self-hosted tailnets.
 
-Headscale is an open-source implementation of the Tailscale control server written in Go. It provides self-hosted coordination for Tailscale networks (tailnets), managing node registration, IP allocation, policy enforcement, and DERP routing.
+## Interaction Rules
 
-## Development Commands
+These rules govern how you work in this repo. They are listed first
+because they shape every other decision.
 
-### Quick Setup
+### Ask with comprehensive multiple-choice options
+
+When you need to clarify intent, scope, or approach, use the
+`AskUserQuestion` tool (or a numbered list fallback) and present the user
+with a comprehensive set of options. Cover the likely branches explicitly
+and include an "other — please describe" escape.
+
+- Bad: _"How should I handle expired nodes?"_
+- Good: _"How should expired nodes be handled? (a) Remain visible to peers
+  but marked expired (current behaviour); (b) Hidden from peers entirely;
+  (c) Hidden from peers but visible in admin API; (d) Other."_
+
+This matters more than you think — open-ended questions waste a round
+trip and often produce a misaligned answer.
+
+### Read the documented procedure before running complex commands
+
+Before invoking any `hi` command, integration test, generator, or
+migration tool, read the referenced README in full —
+`cmd/hi/README.md` for running tests, `integration/README.md` for
+writing them. Never guess flags. If the procedure is not documented
+anywhere, ask the user rather than inventing one.
+
+### Map once, then act
+
+Use `Glob` / `Grep` to understand file structure, then execute. Do not
+re-explore the same area to "double-check" once you have a plan. Do not
+re-read files you edited in this session — the harness tracks state for
+you.
+
+### Fail fast, report up
+
+If a command fails twice with the same error, stop and report the exact
+error to the user with context. Do not loop through variants or
+"try one more thing". A repeated failure means your model of the problem
+is wrong.
+
+### Confirm scope for multi-file changes
+
+Before touching more than three files, show the user which files will
+change and why. Use plan mode (`ExitPlanMode`) for non-trivial work.
+
+### Prefer editing existing files
+
+Do not create new files unless strictly necessary. Do not generate helper
+abstractions, wrapper utilities, or "just in case" configuration. Three
+similar lines of code is better than a premature abstraction.
+
+## Quick Start
 
 ```bash
-# Recommended: Use Nix for dependency management
+# Enter the nix dev shell (Go 1.26.1, buf, golangci-lint, prek)
 nix develop
 
-# Full development workflow
-make dev  # runs fmt + lint + test + build
+# Full development workflow: fmt + lint + test + build
+make dev
+
+# Individual targets
+make build           # build the headscale binary
+make test            # go test ./...
+make fmt             # format Go, docs, proto
+make lint            # lint Go, proto
+make generate        # regenerate protobuf code (after changes to proto/)
+make clean           # remove build artefacts
+
+# Direct go test invocations
+go test ./...
+go test -race ./...
+
+# Integration tests — read cmd/hi/README.md first
+go run ./cmd/hi doctor
+go run ./cmd/hi run "TestName"
 ```
 
-### Essential Commands
+Go 1.26.1 minimum (per `go.mod:3`). `nix develop` pins the exact toolchain
+used in CI.
+
+## Pre-Commit with prek
+
+`prek` installs git hooks that run the same checks as CI.
 
 ```bash
-# Build headscale binary
-make build
-
-# Run tests
-make test
-go test ./...                    # All unit tests
-go test -race ./...              # With race detection
-
-# Run specific integration test
-go run ./cmd/hi run "TestName" --postgres
-
-# Code formatting and linting
-make fmt         # Format all code (Go, docs, proto)
-make lint        # Lint all code (Go, proto)
-make fmt-go      # Format Go code only
-make lint-go     # Lint Go code only
-
-# Protocol buffer generation (after modifying proto/)
-make generate
-
-# Clean build artifacts
-make clean
-```
-
-### Integration Testing
-
-```bash
-# Use the hi (Headscale Integration) test runner
-go run ./cmd/hi doctor                    # Check system requirements
-go run ./cmd/hi run "TestPattern"         # Run specific test
-go run ./cmd/hi run "TestPattern" --postgres  # With PostgreSQL backend
-
-# Test artifacts are saved to control_logs/ with logs and debug data
-```
-
-## Pre-Commit Quality Checks
-
-### **MANDATORY: Automated Pre-Commit Hooks with prek**
-
-**CRITICAL REQUIREMENT**: This repository uses [prek](https://prek.j178.dev/) for automated pre-commit hooks. All commits are automatically validated for code quality, formatting, and common issues.
-
-### Initial Setup
-
-When you first clone the repository or enter the nix shell, install the git hooks:
-
-```bash
-# Enter nix development environment
 nix develop
-
-# Install prek git hooks (one-time setup)
-prek install
+prek install            # one-time setup
+prek run                # run hooks on staged files
+prek run --all-files    # run hooks on the full tree
 ```
 
-This installs the pre-commit hook at `.git/hooks/pre-commit` which automatically runs all configured checks before each commit.
-
-### Configured Hooks
-
-The repository uses `.pre-commit-config.yaml` with the following hooks:
-
-**Built-in Checks** (optimized fast-path execution):
-
-- `check-added-large-files` - Prevents accidentally committing large files
-- `check-case-conflict` - Checks for files that would conflict in case-insensitive filesystems
-- `check-executables-have-shebangs` - Ensures executables have proper shebangs
-- `check-json` - Validates JSON syntax
-- `check-merge-conflict` - Prevents committing files with merge conflict markers
-- `check-symlinks` - Checks for broken symlinks
-- `check-toml` - Validates TOML syntax
-- `check-xml` - Validates XML syntax
-- `check-yaml` - Validates YAML syntax
-- `detect-private-key` - Detects accidentally committed private keys
-- `end-of-file-fixer` - Ensures files end with a newline
-- `fix-byte-order-marker` - Removes UTF-8 byte order markers
-- `mixed-line-ending` - Prevents mixed line endings
-- `trailing-whitespace` - Removes trailing whitespace
-
-**Project-Specific Hooks**:
-
-- `nixpkgs-fmt` - Formats Nix files
-- `prettier` - Formats markdown, YAML, JSON, and TOML files
-- `golangci-lint` - Runs Go linter with auto-fix on changed files only
-
-### Manual Hook Execution
-
-Run hooks manually without making a commit:
+Hooks cover: file hygiene (trailing whitespace, line endings, BOM),
+syntax validation (JSON/YAML/TOML/XML), merge-conflict markers, private
+key detection, nixpkgs-fmt, prettier, and `golangci-lint` via
+`--new-from-rev=HEAD~1` (see `.pre-commit-config.yaml:59`). A manual
+invocation with an `upstream/main` remote is equivalent:
 
 ```bash
-# Run hooks on staged files only
-prek run
-
-# Run hooks on all files in the repository
-prek run --all-files
-
-# Run a specific hook
-prek run golangci-lint
-
-# Run hooks on specific files
-prek run --files path/to/file1.go path/to/file2.go
-```
-
-### Workflow Pattern
-
-With prek installed, your normal workflow becomes:
-
-```bash
-# 1. Make your code changes
-vim hscontrol/state/state.go
-
-# 2. Stage your changes
-git add .
-
-# 3. Commit - hooks run automatically
-git commit -m "feat: add new feature"
-
-# If hooks fail, they will show which checks failed
-# Fix the issues and try committing again
-```
-
-### Manual golangci-lint
-
-While golangci-lint runs automatically via prek, you can also run it manually:
-
-```bash
-# If you have upstream remote configured (recommended)
 golangci-lint run --new-from-rev=upstream/main --timeout=5m --fix
-
-# If you only have origin remote
-golangci-lint run --new-from-rev=main --timeout=5m --fix
 ```
 
-**Important**: Always use `--new-from-rev` to only lint changed files. This prevents formatting the entire repository and keeps changes focused on your actual modifications.
+`git commit --no-verify` is acceptable only for WIP commits on feature
+branches — never on `main`.
 
-### Skipping Hooks (Not Recommended)
-
-In rare cases where you need to skip hooks (e.g., work-in-progress commits), use:
-
-```bash
-git commit --no-verify -m "WIP: work in progress"
-```
-
-**WARNING**: Only use `--no-verify` for temporary WIP commits on feature branches. All commits to main must pass all hooks.
-
-### Troubleshooting
-
-**Hook installation issues**:
-
-```bash
-# Check if hooks are installed
-ls -la .git/hooks/pre-commit
-
-# Reinstall hooks
-prek install
-```
-
-**Hooks running slow**:
-
-```bash
-# prek uses optimized fast-path for built-in hooks
-# If running slow, check which hook is taking time with verbose output
-prek run -v
-```
-
-**Update hook configuration**:
-
-```bash
-# After modifying .pre-commit-config.yaml, hooks will automatically use new config
-# No reinstallation needed
-```
-
-## Project Structure & Architecture
-
-### Top-Level Organization
+## Project Layout
 
 ```
 headscale/
-├── cmd/                    # Command-line applications
-│   ├── headscale/         # Main headscale server binary
-│   └── hi/               # Headscale Integration test runner
-├── hscontrol/            # Core control plane logic
-├── integration/          # End-to-end Docker-based tests
-├── proto/               # Protocol buffer definitions
-├── gen/                 # Generated code (protobuf)
-├── docs/                # Documentation
-└── packaging/           # Distribution packaging
+├── cmd/
+│   ├── headscale/    # Main headscale server binary
+│   └── hi/           # Integration test runner (see cmd/hi/README.md)
+├── hscontrol/        # Core control plane
+├── integration/      # End-to-end Docker-based tests (see integration/README.md)
+├── proto/            # Protocol buffer definitions
+├── gen/              # Generated code (buf output — do not edit)
+├── docs/             # User and ACL reference documentation
+└── packaging/        # Distribution packaging
 ```
 
-### Core Packages (`hscontrol/`)
-
-**Main Server (`hscontrol/`)**
-
-- `app.go`: Application setup, dependency injection, server lifecycle
-- `handlers.go`: HTTP/gRPC API endpoints for management operations
-- `grpcv1.go`: gRPC service implementation for headscale API
-- `poll.go`: **Critical** - Handles Tailscale MapRequest/MapResponse protocol
-- `noise.go`: Noise protocol implementation for secure client communication
-- `auth.go`: Authentication flows (web, OIDC, command-line)
-- `oidc.go`: OpenID Connect integration for user authentication
-
-**State Management (`hscontrol/state/`)**
-
-- `state.go`: Central coordinator for all subsystems (database, policy, IP allocation, DERP)
-- `node_store.go`: **Performance-critical** - In-memory cache with copy-on-write semantics
-- Thread-safe operations with deadlock detection
-- Coordinates between database persistence and real-time operations
-
-**Database Layer (`hscontrol/db/`)**
-
-- `db.go`: Database abstraction, GORM setup, migration management
-- `node.go`: Node lifecycle, registration, expiration, IP assignment
-- `users.go`: User management, namespace isolation
-- `api_key.go`: API authentication tokens
-- `preauth_keys.go`: Pre-authentication keys for automated node registration
-- `ip.go`: IP address allocation and management
-- `policy.go`: Policy storage and retrieval
-- Schema migrations in `schema.sql` with extensive test data coverage
-
-**CRITICAL DATABASE MIGRATION RULES**:
-
-1. **NEVER reorder existing migrations** - Migration order is immutable once committed
-2. **ONLY add new migrations to the END** of the migrations array
-3. **NEVER disable foreign keys** in new migrations - no new migrations should be added to `migrationsRequiringFKDisabled`
-4. **Migration ID format**: `YYYYMMDDHHSS-short-description` (timestamp + descriptive suffix)
-   - Example: `202511131500-add-user-roles`
-   - The timestamp must be chronologically ordered
-5. **New migrations go after the comment** "As of 2025-07-02, no new IDs should be added here"
-6. If you need to rename a column that other migrations depend on:
-   - Accept that the old column name will exist in intermediate migration states
-   - Update code to work with the new column name
-   - Let AutoMigrate create the new column if needed
-   - Do NOT try to rename columns that later migrations reference
-
-**Policy Engine (`hscontrol/policy/`)**
-
-- `policy.go`: Core ACL evaluation logic, HuJSON parsing
-- `v2/`: Next-generation policy system with improved filtering
-- `matcher/`: ACL rule matching and evaluation engine
-- Determines peer visibility, route approval, and network access rules
-- Supports both file-based and database-stored policies
-
-**Network Management (`hscontrol/`)**
-
-- `derp/`: DERP (Designated Encrypted Relay for Packets) server implementation
-  - NAT traversal when direct connections fail
-  - Fallback relay for firewall-restricted environments
-- `mapper/`: Converts internal Headscale state to Tailscale's wire protocol format
-  - `tail.go`: Tailscale-specific data structure generation
-- `routes/`: Subnet route management and primary route selection
-- `dns/`: DNS record management and MagicDNS implementation
-
-**Utilities & Support (`hscontrol/`)**
-
-- `types/`: Core data structures, configuration, validation
-- `util/`: Helper functions for networking, DNS, key management
-- `templates/`: Client configuration templates (Apple, Windows, etc.)
-- `notifier/`: Event notification system for real-time updates
-- `metrics.go`: Prometheus metrics collection
-- `capver/`: Tailscale capability version management
-
-### Key Subsystem Interactions
-
-**Node Registration Flow**
-
-1. **Client Connection**: `noise.go` handles secure protocol handshake
-2. **Authentication**: `auth.go` validates credentials (web/OIDC/preauth)
-3. **State Creation**: `state.go` coordinates IP allocation via `db/ip.go`
-4. **Storage**: `db/node.go` persists node, `NodeStore` caches in memory
-5. **Network Setup**: `mapper/` generates initial Tailscale network map
-
-**Ongoing Operations**
-
-1. **Poll Requests**: `poll.go` receives periodic client updates
-2. **State Updates**: `NodeStore` maintains real-time node information
-3. **Policy Application**: `policy/` evaluates ACL rules for peer relationships
-4. **Map Distribution**: `mapper/` sends network topology to all affected clients
-
-**Route Management**
-
-1. **Advertisement**: Clients announce routes via `poll.go` Hostinfo updates
-2. **Storage**: `db/` persists routes, `NodeStore` caches for performance
-3. **Approval**: `policy/` auto-approves routes based on ACL rules
-4. **Distribution**: `routes/` selects primary routes, `mapper/` distributes to peers
-
-### Command-Line Tools (`cmd/`)
-
-**Main Server (`cmd/headscale/`)**
-
-- `headscale.go`: CLI parsing, configuration loading, server startup
-- Supports daemon mode, CLI operations (user/node management), database operations
-
-**Integration Test Runner (`cmd/hi/`)**
-
-- `main.go`: Test execution framework with Docker orchestration
-- `run.go`: Individual test execution with artifact collection
-- `doctor.go`: System requirements validation
-- `docker.go`: Container lifecycle management
-- Essential for validating changes against real Tailscale clients
-
-### Generated & External Code
-
-**Protocol Buffers (`proto/` → `gen/`)**
-
-- Defines gRPC API for headscale management operations
-- Client libraries can generate from these definitions
-- Run `make generate` after modifying `.proto` files
-
-**Integration Testing (`integration/`)**
-
-- `scenario.go`: Docker test environment setup
-- `tailscale.go`: Tailscale client container management
-- Individual test files for specific functionality areas
-- Real end-to-end validation with network isolation
-
-### Critical Performance Paths
-
-**High-Frequency Operations**
-
-1. **MapRequest Processing** (`poll.go`): Every 15-60 seconds per client
-2. **NodeStore Reads** (`node_store.go`): Every operation requiring node data
-3. **Policy Evaluation** (`policy/`): On every peer relationship calculation
-4. **Route Lookups** (`routes/`): During network map generation
-
-**Database Write Patterns**
-
-- **Frequent**: Node heartbeats, endpoint updates, route changes
-- **Moderate**: User operations, policy updates, API key management
-- **Rare**: Schema migrations, bulk operations
-
-### Configuration & Deployment
-
-**Configuration** (`hscontrol/types/config.go`)\*\*
-
-- Database connection settings (SQLite/PostgreSQL)
-- Network configuration (IP ranges, DNS settings)
-- Policy mode (file vs database)
-- DERP relay configuration
-- OIDC provider settings
-
-**Key Dependencies**
-
-- **GORM**: Database ORM with migration support
-- **Tailscale Libraries**: Core networking and protocol code
-- **Zerolog**: Structured logging throughout the application
-- **Buf**: Protocol buffer toolchain for code generation
-
-### Development Workflow Integration
-
-The architecture supports incremental development:
-
-- **Unit Tests**: Focus on individual packages (`*_test.go` files)
-- **Integration Tests**: Validate cross-component interactions
-- **Database Tests**: Extensive migration and data integrity validation
-- **Policy Tests**: ACL rule evaluation and edge cases
-- **Performance Tests**: NodeStore and high-frequency operation validation
-
-## Integration Testing System
-
-### Overview
-
-Headscale uses Docker-based integration tests with real Tailscale clients to validate end-to-end functionality. The integration test system is complex and requires specialized knowledge for effective execution and debugging.
-
-### **MANDATORY: Use the headscale-integration-tester Agent**
-
-**CRITICAL REQUIREMENT**: For ANY integration test execution, analysis, troubleshooting, or validation, you MUST use the `headscale-integration-tester` agent. This agent contains specialized knowledge about:
-
-- Test execution strategies and timing requirements
-- Infrastructure vs code issue distinction (99% vs 1% failure patterns)
-- Security-critical debugging rules and forbidden practices
-- Comprehensive artifact analysis workflows
-- Real-world failure patterns from HA debugging experiences
-
-### Quick Reference Commands
-
-```bash
-# Check system requirements (always run first)
-go run ./cmd/hi doctor
-
-# Run single test (recommended for development)
-go run ./cmd/hi run "TestName"
-
-# Use PostgreSQL for database-heavy tests
-go run ./cmd/hi run "TestName" --postgres
-
-# Pattern matching for related tests
-go run ./cmd/hi run "TestPattern*"
-
-# Run multiple tests concurrently (each gets isolated run ID)
-go run ./cmd/hi run "TestPingAllByIP" &
-go run ./cmd/hi run "TestACLAllowUserDst" &
-go run ./cmd/hi run "TestOIDCAuthenticationPingAll" &
-```
-
-**Concurrent Execution Support**:
-
-The test runner supports running multiple tests concurrently on the same Docker daemon:
-
-- Each test run gets a **unique Run ID** (format: `YYYYMMDD-HHMMSS-{6-char-hash}`)
-- All containers are labeled with `hi.run-id` for isolation
-- Container names include the run ID for easy identification (e.g., `ts-{runID}-1-74-{hash}`)
-- Dynamic port allocation prevents port conflicts between concurrent runs
-- Cleanup only affects containers belonging to the specific run ID
-- Log directories are isolated per run: `control_logs/{runID}/`
-
-**Critical Notes**:
-
-- Tests generate ~100MB of logs per run in `control_logs/`
-- Running many tests concurrently may cause resource contention (CPU/memory)
-- Clean stale containers periodically: `docker system prune -f`
-
-### Test Artifacts Location
-
-All test runs save comprehensive debugging artifacts to `control_logs/TIMESTAMP-ID/` including server logs, client logs, database dumps, MapResponse protocol data, and Prometheus metrics.
-
-**For all integration test work, use the headscale-integration-tester agent - it contains the complete knowledge needed for effective testing and debugging.**
-
-## NodeStore Implementation Details
-
-**Key Insight from Recent Work**: The NodeStore is a critical performance optimization that caches node data in memory while ensuring consistency with the database. When working with route advertisements or node state changes:
-
-1. **Timing Considerations**: Route advertisements need time to propagate from clients to server. Use `require.EventuallyWithT()` patterns in tests instead of immediate assertions.
-
-2. **Synchronization Points**: NodeStore updates happen at specific points like `poll.go:420` after Hostinfo changes. Ensure these are maintained when modifying the polling logic.
-
-3. **Peer Visibility**: The NodeStore's `peersFunc` determines which nodes are visible to each other. Policy-based filtering is separate from monitoring visibility - expired nodes should remain visible for debugging but marked as expired.
-
-## Testing Guidelines
-
-### Integration Test Patterns
-
-#### **CRITICAL: EventuallyWithT Pattern for External Calls**
-
-**All external calls in integration tests MUST be wrapped in EventuallyWithT blocks** to handle eventual consistency in distributed systems. External calls include:
-
-- `client.Status()` - Getting Tailscale client status
-- `client.Curl()` - Making HTTP requests through clients
-- `client.Traceroute()` - Running network diagnostics
-- `headscale.ListNodes()` - Querying headscale server state
-- Any other calls that interact with external systems or network operations
-
-**Key Rules**:
-
-1. **Never use bare `require.NoError(t, err)` with external calls** - Always wrap in EventuallyWithT
-2. **Keep related assertions together** - If multiple assertions depend on the same external call, keep them in the same EventuallyWithT block
-3. **Split unrelated external calls** - Different external calls should be in separate EventuallyWithT blocks
-4. **Never nest EventuallyWithT calls** - Each EventuallyWithT should be at the same level
-5. **Declare shared variables at function scope** - Variables used across multiple EventuallyWithT blocks must be declared before first use
-
-**Examples**:
+### `hscontrol/` packages
+
+- `app.go`, `handlers.go`, `grpcv1.go`, `noise.go`, `auth.go`, `oidc.go`,
+  `poll.go`, `metrics.go`, `debug.go`, `tailsql.go`, `platform_config.go`
+  — top-level server files
+- `state/` — central coordinator (`state.go`) and the copy-on-write
+  `NodeStore` (`node_store.go`). All cross-subsystem operations go
+  through `State`.
+- `db/` — GORM layer, migrations, schema. `node.go`, `users.go`,
+  `api_key.go`, `preauth_keys.go`, `ip.go`, `policy.go`.
+- `mapper/` — streaming batcher that distributes MapResponses to
+  clients: `batcher.go`, `node_conn.go`, `builder.go`, `mapper.go`.
+  Performance-critical.
+- `policy/` — `policy/v2/` is **the** policy implementation. The
+  top-level `policy.go` is thin wrappers. There is no v1 directory.
+- `routes/`, `dns/`, `derp/`, `types/`, `util/`, `templates/`, `capver/`
+  — routing, MagicDNS, relay, core types, helpers, client templates,
+  capability versioning.
+- `servertest/` — in-memory test harness for server-level tests that
+  don't need Docker. Prefer this over `integration/` when possible.
+- `assets/` — embedded UI assets.
+
+### `cmd/hi/` files
+
+`main.go`, `run.go`, `doctor.go`, `docker.go`, `cleanup.go`, `stats.go`,
+`README.md`. **Read `cmd/hi/README.md` before running any `hi` command.**
+
+## Architecture Essentials
+
+- **`hscontrol/state/state.go`** is the central coordinator. Cross-cutting
+  operations (node updates, policy evaluation, IP allocation) go through
+  the `State` type, not directly to the database.
+- **`NodeStore`** in `hscontrol/state/node_store.go` is a copy-on-write
+  in-memory cache backed by `atomic.Pointer[Snapshot]`. Every read is a
+  pointer load; writes rebuild a new snapshot and atomically swap. It is
+  the hot path for `MapRequest` processing and peer visibility.
+- **The map-request sync point** is
+  `State.UpdateNodeFromMapRequest()` in
+  `hscontrol/state/state.go:2351`. This is where Hostinfo changes,
+  endpoint updates, and route advertisements land in the NodeStore.
+- **Mapper subsystem** streams MapResponses via `batcher.go` and
+  `node_conn.go`. Changes here affect all connected clients.
+- **Node registration flow**: noise handshake (`noise.go`) → auth
+  (`auth.go`) → state/DB persistence (`state/`, `db/`) → initial map
+  (`mapper/`).
+
+## Database Migration Rules
+
+These rules are load-bearing — violating them corrupts production
+databases. The `migrationsRequiringFKDisabled` map in
+`hscontrol/db/db.go:962` is frozen as of 2025-07-02 (see the comment at
+`db.go:989`). All new migrations must:
+
+1. **Never reorder existing migrations.** Migration order is immutable
+   once committed.
+2. **Only add new migrations to the end** of the migrations array.
+3. **Never disable foreign keys.** No new entries in
+   `migrationsRequiringFKDisabled`.
+4. **Use the migration ID format** `YYYYMMDDHHMM-short-description`
+   (timestamp + descriptive suffix). Example: `202602201200-clear-tagged-node-user-id`.
+5. **Never rename columns** that later migrations reference. Let
+   `AutoMigrate` create a new column if needed.
+
+## Tags-as-Identity
+
+Headscale enforces **tags XOR user ownership**: every node is either
+tagged (owned by tags) or user-owned (owned by a user namespace), never
+both. This is a load-bearing architectural invariant.
+
+- **Use `node.IsTagged()`** (`hscontrol/types/node.go:221`) to determine
+  ownership, not `node.UserID().Valid()`. A tagged node may still have
+  `UserID` set for "created by" tracking — `IsTagged()` is authoritative.
+- `IsUserOwned()` (`node.go:227`) returns `!IsTagged()`.
+- Tagged nodes are presented to Tailscale as the special
+  `TaggedDevices` user (`hscontrol/types/users.go`, ID `2147455555`).
+- `SetTags` validation is enforced by `validateNodeOwnership()` in
+  `hscontrol/state/tags.go`.
+- Examples and edge cases live in `hscontrol/types/node_tags_test.go`
+  and `hscontrol/grpcv1_test.go` (`TestSetTags_*`).
+
+**Don't do this**:
 
 ```go
-// CORRECT: External call wrapped in EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    // Related assertions using the same status call
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        assert.NotNil(c, peerStatus.PrimaryRoutes)
-        requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedRoutes)
-    }
-}, 5*time.Second, 200*time.Millisecond, "Verifying client status and routes")
-
-// INCORRECT: Bare external call without EventuallyWithT
-status, err := client.Status()  // ❌ Will fail intermittently
-require.NoError(t, err)
-
-// CORRECT: Separate EventuallyWithT for different external calls
-// First external call - headscale.ListNodes()
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-}, 10*time.Second, 500*time.Millisecond, "route state changes should propagate to nodes")
-
-// Second external call - client.Status()
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        requirePeerSubnetRoutesWithCollect(c, peerStatus, []netip.Prefix{tsaddr.AllIPv4(), tsaddr.AllIPv6()})
-    }
-}, 10*time.Second, 500*time.Millisecond, "routes should be visible to client")
-
-// INCORRECT: Multiple unrelated external calls in same EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err := headscale.ListNodes()  // ❌ First external call
-    assert.NoError(c, err)
-
-    status, err := client.Status()  // ❌ Different external call - should be separate
-    assert.NoError(c, err)
-}, 10*time.Second, 500*time.Millisecond, "mixed calls")
-
-// CORRECT: Variable scoping for shared data
-var (
-    srs1, srs2, srs3       *ipnstate.Status
-    clientStatus           *ipnstate.Status
-    srs1PeerStatus         *ipnstate.PeerStatus
-)
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    srs1 = subRouter1.MustStatus()  // = not :=
-    srs2 = subRouter2.MustStatus()
-    clientStatus = client.MustStatus()
-
-    srs1PeerStatus = clientStatus.Peer[srs1.Self.PublicKey]
-    // assertions...
-}, 5*time.Second, 200*time.Millisecond, "checking router status")
-
-// CORRECT: Wrapping client operations
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    result, err := client.Curl(weburl)
-    assert.NoError(c, err)
-    assert.Len(c, result, 13)
-}, 5*time.Second, 200*time.Millisecond, "Verifying HTTP connectivity")
-
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    tr, err := client.Traceroute(webip)
-    assert.NoError(c, err)
-    assertTracerouteViaIPWithCollect(c, tr, expectedRouter.MustIPv4())
-}, 5*time.Second, 200*time.Millisecond, "Verifying network path")
+if node.UserID().Valid() { /* assume user-owned */ }       // WRONG
+if node.UserID().Valid() && !node.IsTagged() { /* ok */ }  // correct
 ```
 
-**Helper Functions**:
-
-- Use `requirePeerSubnetRoutesWithCollect` instead of `requirePeerSubnetRoutes` inside EventuallyWithT
-- Use `requireNodeRouteCountWithCollect` instead of `requireNodeRouteCount` inside EventuallyWithT
-- Use `assertTracerouteViaIPWithCollect` instead of `assertTracerouteViaIP` inside EventuallyWithT
-
-```go
-// Node route checking by actual node properties, not array position
-var routeNode *v1.Node
-for _, node := range nodes {
-    if nodeIDStr := fmt.Sprintf("%d", node.GetId()); expectedRoutes[nodeIDStr] != "" {
-        routeNode = node
-        break
-    }
-}
-```
-
-### Running Problematic Tests
-
-- Some tests require significant time (e.g., `TestNodeOnlineStatus` runs for 12 minutes)
-- Infrastructure issues like disk space can cause test failures unrelated to code changes
-- Use `--postgres` flag when testing database-heavy scenarios
-
-## Quality Assurance and Testing Requirements
-
-### **MANDATORY: Always Use Specialized Testing Agents**
-
-**CRITICAL REQUIREMENT**: For ANY task involving testing, quality assurance, review, or validation, you MUST use the appropriate specialized agent at the END of your task list. This ensures comprehensive quality validation and prevents regressions.
-
-**Required Agents for Different Task Types**:
-
-1. **Integration Testing**: Use `headscale-integration-tester` agent for:
-   - Running integration tests with `cmd/hi`
-   - Analyzing test failures and artifacts
-   - Troubleshooting Docker-based test infrastructure
-   - Validating end-to-end functionality changes
-
-2. **Quality Control**: Use `quality-control-enforcer` agent for:
-   - Code review and validation
-   - Ensuring best practices compliance
-   - Preventing common pitfalls and anti-patterns
-   - Validating architectural decisions
-
-**Agent Usage Pattern**: Always add the appropriate agent as the FINAL step in any task list to ensure quality validation occurs after all work is complete.
-
-### Integration Test Debugging Reference
-
-Test artifacts are preserved in `control_logs/TIMESTAMP-ID/` including:
-
-- Headscale server logs (stderr/stdout)
-- Tailscale client logs and status
-- Database dumps and network captures
-- MapResponse JSON files for protocol debugging
-
-**For integration test issues, ALWAYS use the headscale-integration-tester agent - do not attempt manual debugging.**
-
-## EventuallyWithT Pattern for Integration Tests
-
-### Overview
-
-EventuallyWithT is a testing pattern used to handle eventual consistency in distributed systems. In Headscale integration tests, many operations are asynchronous - clients advertise routes, the server processes them, updates propagate through the network. EventuallyWithT allows tests to wait for these operations to complete while making assertions.
-
-### External Calls That Must Be Wrapped
-
-The following operations are **external calls** that interact with the headscale server or tailscale clients and MUST be wrapped in EventuallyWithT:
-
-- `headscale.ListNodes()` - Queries server state
-- `client.Status()` - Gets client network status
-- `client.Curl()` - Makes HTTP requests through the network
-- `client.Traceroute()` - Performs network diagnostics
-- `client.Execute()` when running commands that query state
-- Any operation that reads from the headscale server or tailscale client
-
-### Operations That Must NOT Be Wrapped
-
-The following are **blocking operations** that modify state and should NOT be wrapped in EventuallyWithT:
-
-- `tailscale set` commands (e.g., `--advertise-routes`, `--exit-node`)
-- Any command that changes configuration or state
-- Use `client.MustStatus()` instead of `client.Status()` when you just need the ID for a blocking operation
-
-### Five Key Rules for EventuallyWithT
-
-1. **One External Call Per EventuallyWithT Block**
-   - Each EventuallyWithT should make ONE external call (e.g., ListNodes OR Status)
-   - Related assertions based on that single call can be grouped together
-   - Unrelated external calls must be in separate EventuallyWithT blocks
-
-2. **Variable Scoping**
-   - Declare variables that need to be shared across EventuallyWithT blocks at function scope
-   - Use `=` for assignment inside EventuallyWithT, not `:=` (unless the variable is only used within that block)
-   - Variables declared with `:=` inside EventuallyWithT are not accessible outside
-
-3. **No Nested EventuallyWithT**
-   - NEVER put an EventuallyWithT inside another EventuallyWithT
-   - This is a critical anti-pattern that must be avoided
-
-4. **Use CollectT for Assertions**
-   - Inside EventuallyWithT, use `assert` methods with the CollectT parameter
-   - Helper functions called within EventuallyWithT must accept `*assert.CollectT`
-
-5. **Descriptive Messages**
-   - Always provide a descriptive message as the last parameter
-   - Message should explain what condition is being waited for
-
-### Correct Pattern Examples
-
-```go
-// CORRECT: Blocking operation NOT wrapped
-for _, client := range allClients {
-    status := client.MustStatus()
-    command := []string{
-        "tailscale",
-        "set",
-        "--advertise-routes=" + expectedRoutes[string(status.Self.ID)],
-    }
-    _, _, err = client.Execute(command)
-    require.NoErrorf(t, err, "failed to advertise route: %s", err)
-}
-
-// CORRECT: Single external call with related assertions
-var nodes []*v1.Node
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    nodes, err = headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-    requireNodeRouteCountWithCollect(c, nodes[0], 2, 2, 2)
-}, 10*time.Second, 500*time.Millisecond, "nodes should have expected route counts")
-
-// CORRECT: Separate EventuallyWithT for different external call
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-    for _, peerKey := range status.Peers() {
-        peerStatus := status.Peer[peerKey]
-        requirePeerSubnetRoutesWithCollect(c, peerStatus, expectedPrefixes)
-    }
-}, 10*time.Second, 500*time.Millisecond, "client should see expected routes")
-```
-
-### Incorrect Patterns to Avoid
-
-```go
-// INCORRECT: Blocking operation wrapped in EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    status, err := client.Status()
-    assert.NoError(c, err)
-
-    // This is a blocking operation - should NOT be in EventuallyWithT!
-    command := []string{
-        "tailscale",
-        "set",
-        "--advertise-routes=" + expectedRoutes[string(status.Self.ID)],
-    }
-    _, _, err = client.Execute(command)
-    assert.NoError(c, err)
-}, 5*time.Second, 200*time.Millisecond, "wrong pattern")
-
-// INCORRECT: Multiple unrelated external calls in same EventuallyWithT
-assert.EventuallyWithT(t, func(c *assert.CollectT) {
-    // First external call
-    nodes, err := headscale.ListNodes()
-    assert.NoError(c, err)
-    assert.Len(c, nodes, 2)
-
-    // Second unrelated external call - WRONG!
-    status, err := client.Status()
-    assert.NoError(c, err)
-    assert.NotNil(c, status)
-}, 10*time.Second, 500*time.Millisecond, "mixed operations")
-```
-
-## Tags-as-Identity Architecture
-
-### Overview
-
-Headscale implements a **tags-as-identity** model where tags and user ownership are mutually exclusive ways to identify nodes. This is a fundamental architectural principle that affects node registration, ownership, ACL evaluation, and API behavior.
-
-### Core Principle: Tags XOR User Ownership
-
-Every node in Headscale is **either** tagged **or** user-owned, never both:
-
-- **Tagged Nodes**: Ownership is defined by tags (e.g., `tag:server`, `tag:database`)
-  - Tags are set during registration via tagged PreAuthKey
-  - Tags are immutable after registration (cannot be changed via API)
-  - May have `UserID` set for "created by" tracking, but ownership is via tags
-  - Identified by: `node.IsTagged()` returns `true`
-
-- **User-Owned Nodes**: Ownership is defined by user assignment
-  - Registered via OIDC, web auth, or untagged PreAuthKey
-  - Node belongs to a specific user's namespace
-  - No tags (empty tags array)
-  - Identified by: `node.UserID().Valid() && !node.IsTagged()`
-
-### Critical Implementation Details
-
-#### Node Identification Methods
-
-```go
-// Primary methods for determining node ownership
-node.IsTagged()      // Returns true if node has tags OR AuthKey.Tags
-node.HasTag(tag)     // Returns true if node has specific tag
-node.IsUserOwned()   // Returns true if UserID set AND not tagged
-
-// IMPORTANT: UserID can be set on tagged nodes for tracking!
-// Always use IsTagged() to determine actual ownership, not just UserID.Valid()
-```
-
-#### UserID Field Semantics
-
-**Critical distinction**: `UserID` has different meanings depending on node type:
-
-- **Tagged nodes**: `UserID` is optional "created by" tracking
-  - Indicates which user created the tagged PreAuthKey
-  - Does NOT define ownership (tags define ownership)
-  - Example: User "alice" creates tagged PreAuthKey with `tag:server`, node gets `UserID=alice.ID` + `Tags=["tag:server"]`
-
-- **User-owned nodes**: `UserID` defines ownership
-  - Required field for non-tagged nodes
-  - Defines which user namespace the node belongs to
-  - Example: User "bob" registers via OIDC, node gets `UserID=bob.ID` + `Tags=[]`
-
-#### Mapper Behavior (mapper/tail.go)
-
-The mapper converts internal nodes to Tailscale protocol format, handling the TaggedDevices special user:
-
-```go
-// From mapper/tail.go:102-116
-User: func() tailcfg.UserID {
-    // IMPORTANT: Tags-as-identity model
-    // Tagged nodes ALWAYS use TaggedDevices user, even if UserID is set
-    if node.IsTagged() {
-        return tailcfg.UserID(int64(types.TaggedDevices.ID))
-    }
-    // User-owned nodes: use the actual user ID
-    return tailcfg.UserID(int64(node.UserID().Get()))
-}()
-```
-
-**TaggedDevices constant** (`types.TaggedDevices.ID = 2147455555`): Special user ID for all tagged nodes in MapResponse protocol.
-
-#### Registration Flow
-
-**Tagged Node Registration** (via tagged PreAuthKey):
-
-1. User creates PreAuthKey with tags: `pak.Tags = ["tag:server"]`
-2. Node registers with PreAuthKey
-3. Node gets: `Tags = ["tag:server"]`, `UserID = user.ID` (optional tracking), `AuthKeyID = pak.ID`
-4. `IsTagged()` returns `true` (ownership via tags)
-5. MapResponse sends `User = TaggedDevices.ID`
-
-**User-Owned Node Registration** (via OIDC/web/untagged PreAuthKey):
-
-1. User authenticates or uses untagged PreAuthKey
-2. Node registers
-3. Node gets: `Tags = []`, `UserID = user.ID` (required)
-4. `IsTagged()` returns `false` (ownership via user)
-5. MapResponse sends `User = user.ID`
-
-#### API Validation (SetTags)
-
-The SetTags gRPC API enforces tags-as-identity rules:
-
-```go
-// From grpcv1.go:340-347
-// User-owned nodes are nodes with UserID that are NOT tagged
-isUserOwned := nodeView.UserID().Valid() && !nodeView.IsTagged()
-if isUserOwned && len(request.GetTags()) > 0 {
-    return error("cannot set tags on user-owned nodes")
-}
-```
-
-**Key validation rules**:
-
-- ✅ Can call SetTags on tagged nodes (tags already define ownership)
-- ❌ Cannot set tags on user-owned nodes (would violate XOR rule)
-- ❌ Cannot remove all tags from tagged nodes (would orphan the node)
-
-#### Database Layer (db/node.go)
-
-**Tag storage**: Tags are stored in PostgreSQL ARRAY column and SQLite JSON column:
-
-```sql
--- From schema.sql
-tags TEXT[] DEFAULT '{}' NOT NULL,  -- PostgreSQL
-tags TEXT DEFAULT '[]' NOT NULL,    -- SQLite (JSON array)
-```
-
-**Validation** (`state/tags.go`):
-
-- `validateNodeOwnership()`: Enforces tags XOR user rule
-- `validateAndNormalizeTags()`: Validates tag format (`tag:name`) and uniqueness
-
-#### Policy Layer
-
-**Tag Ownership** (policy/v2/policy.go):
-
-```go
-func NodeCanHaveTag(node types.NodeView, tag string) bool {
-    // Checks if node's IP is in the tagOwnerMap IP set
-    // This is IP-based authorization, not UserID-based
-    if ips, ok := pm.tagOwnerMap[Tag(tag)]; ok {
-        if slices.ContainsFunc(node.IPs(), ips.Contains) {
-            return true
-        }
-    }
-    return false
-}
-```
-
-**Important**: Tag authorization is based on IP ranges in ACL, not UserID. Tags define identity, ACL authorizes that identity.
-
-### Testing Tags-as-Identity
-
-**Unit Tests** (`hscontrol/types/node_tags_test.go`):
-
-- `TestNodeIsTagged`: Validates IsTagged() for various scenarios
-- `TestNodeOwnershipModel`: Tests tags XOR user ownership
-- `TestUserTypedID`: Helper method validation
-
-**API Tests** (`hscontrol/grpcv1_test.go`):
-
-- `TestSetTags_UserXORTags`: Validates rejection of setting tags on user-owned nodes
-- `TestSetTags_TaggedNode`: Validates that tagged nodes (even with UserID) are not rejected
-
-**Auth Tests** (`hscontrol/auth_test.go:890-928`):
-
-- Tests node registration with tagged PreAuthKey
-- Validates tags are applied during registration
-
-### Common Pitfalls
-
-1. **Don't check only `UserID.Valid()` to determine user ownership**
-   - ❌ Wrong: `if node.UserID().Valid() { /* user-owned */ }`
-   - ✅ Correct: `if node.UserID().Valid() && !node.IsTagged() { /* user-owned */ }`
-
-2. **Don't assume tagged nodes never have UserID set**
-   - Tagged nodes MAY have UserID for "created by" tracking
-   - Always use `IsTagged()` to determine ownership type
-
-3. **Don't allow setting tags on user-owned nodes**
-   - This violates the tags XOR user principle
-   - Use API validation to prevent this
-
-4. **Don't forget TaggedDevices in mapper**
-   - All tagged nodes MUST use `TaggedDevices.ID` in MapResponse
-   - User ID is only for actual user-owned nodes
-
-### Migration Considerations
-
-When nodes transition between ownership models:
-
-- **No automatic migration**: Tags-as-identity is set at registration and immutable
-- **Re-registration required**: To change from user-owned to tagged (or vice versa), node must be deleted and re-registered
-- **UserID persistence**: UserID on tagged nodes is informational and not cleared
-
-### Architecture Benefits
-
-The tags-as-identity model provides:
-
-1. **Clear ownership semantics**: No ambiguity about who/what owns a node
-2. **ACL simplicity**: Tag-based access control without user conflicts
-3. **API safety**: Validation prevents invalid ownership states
-4. **Protocol compatibility**: TaggedDevices special user aligns with Tailscale's model
-
-## Logging Patterns
-
-### Incremental Log Event Building
-
-When building log statements with multiple fields, especially with conditional fields, use the **incremental log event pattern** instead of long single-line chains. This improves readability and allows conditional field addition.
-
-**Pattern:**
-
-```go
-// GOOD: Incremental building with conditional fields
-logEvent := log.Debug().
-    Str("node", node.Hostname).
-    Str("machine_key", node.MachineKey.ShortString()).
-    Str("node_key", node.NodeKey.ShortString())
-
-if node.User != nil {
-    logEvent = logEvent.Str("user", node.User.Username())
-} else if node.UserID != nil {
-    logEvent = logEvent.Uint("user_id", *node.UserID)
-} else {
-    logEvent = logEvent.Str("user", "none")
-}
-
-logEvent.Msg("Registering node")
-```
-
-**Key rules:**
-
-1. **Assign chained calls back to the variable**: `logEvent = logEvent.Str(...)` - zerolog methods return a new event, so you must capture the return value
-2. **Use for conditional fields**: When fields depend on runtime conditions, build incrementally
-3. **Use for long log lines**: When a log line exceeds ~100 characters, split it for readability
-4. **Call `.Msg()` at the end**: The final `.Msg()` or `.Msgf()` sends the log event
-
-**Anti-pattern to avoid:**
-
-```go
-// BAD: Long single-line chains are hard to read and can't have conditional fields
-log.Debug().Caller().Str("node", node.Hostname).Str("machine_key", node.MachineKey.ShortString()).Str("node_key", node.NodeKey.ShortString()).Str("user", node.User.Username()).Msg("Registering node")
-
-// BAD: Forgetting to assign the return value (field is lost!)
-logEvent := log.Debug().Str("node", node.Hostname)
-logEvent.Str("user", username)  // This field is LOST - not assigned back
-logEvent.Msg("message")         // Only has "node" field
-```
-
-**When to use this pattern:**
-
-- Log statements with 4+ fields
-- Any log with conditional fields
-- Complex logging in loops or error handling
-- When you need to add context incrementally
-
-**Example from codebase** (`hscontrol/db/node.go`):
-
-```go
-logEvent := log.Debug().
-    Str("node", node.Hostname).
-    Str("machine_key", node.MachineKey.ShortString()).
-    Str("node_key", node.NodeKey.ShortString())
-
-if node.User != nil {
-    logEvent = logEvent.Str("user", node.User.Username())
-} else if node.UserID != nil {
-    logEvent = logEvent.Uint("user_id", *node.UserID)
-} else {
-    logEvent = logEvent.Str("user", "none")
-}
-
-logEvent.Msg("Registering test node")
-```
-
-### Avoiding Log Helper Functions
-
-Prefer the incremental log event pattern over creating helper functions that return multiple logging closures. Helper functions like `logPollFunc` create unnecessary indirection and allocate closures.
-
-**Instead of:**
-
-```go
-// AVOID: Helper function returning closures
-func logPollFunc(req tailcfg.MapRequest, node *types.Node) (
-    func(string, ...any),  // warnf
-    func(string, ...any),  // infof
-    func(string, ...any),  // tracef
-    func(error, string, ...any),  // errf
-) {
-    return func(msg string, a ...any) {
-        log.Warn().
-            Caller().
-            Bool("omitPeers", req.OmitPeers).
-            Bool("stream", req.Stream).
-            Uint64("node.id", node.ID.Uint64()).
-            Str("node.name", node.Hostname).
-            Msgf(msg, a...)
-    },
-    // ... more closures
-}
-```
-
-**Prefer:**
-
-```go
-// BETTER: Build log events inline with shared context
-func (m *mapSession) logTrace(msg string) {
-    log.Trace().
-        Caller().
-        Bool("omitPeers", m.req.OmitPeers).
-        Bool("stream", m.req.Stream).
-        Uint64("node.id", m.node.ID.Uint64()).
-        Str("node.name", m.node.Hostname).
-        Msg(msg)
-}
-
-// Or use incremental building for complex cases
-logEvent := log.Trace().
-    Caller().
-    Bool("omitPeers", m.req.OmitPeers).
-    Bool("stream", m.req.Stream).
-    Uint64("node.id", m.node.ID.Uint64()).
-    Str("node.name", m.node.Hostname)
-
-if additionalContext {
-    logEvent = logEvent.Str("extra", value)
-}
-
-logEvent.Msg("Operation completed")
-```
-
-## Important Notes
-
-- **Dependencies**: Use `nix develop` for consistent toolchain (Go, buf, protobuf tools, linting)
-- **Protocol Buffers**: Changes to `proto/` require `make generate` and should be committed separately
-- **Code Style**: Enforced via golangci-lint with golines (width 88) and gofumpt formatting
-- **Linting**: ALL code must pass `golangci-lint run --new-from-rev=upstream/main --timeout=5m --fix` before commit
-- **Database**: Supports both SQLite (development) and PostgreSQL (production/testing)
-- **Integration Tests**: Require Docker and can consume significant disk space - use headscale-integration-tester agent
-- **Performance**: NodeStore optimizations are critical for scale - be careful with changes to state management
-- **Quality Assurance**: Always use appropriate specialized agents for testing and validation tasks
-- **Tags-as-Identity**: Tags and user ownership are mutually exclusive - always use `IsTagged()` to determine ownership
+## Policy Engine
+
+`hscontrol/policy/v2/policy.go` is the policy implementation. The
+top-level `hscontrol/policy/policy.go` contains only wrapper functions
+around v2. There is no v1 directory.
+
+Key concepts an agent will encounter:
+
+- **Autogroups**: `autogroup:self`, `autogroup:member`, `autogroup:internet`
+- **Tag owners**: IP-based authorization for who can claim a tag
+- **Route approvals**: auto-approval of subnet routes by policy
+- **SSH policies**: SSH access control via grants
+- **HuJSON** parsing for policy files
+
+For usage examples, read `hscontrol/policy/v2/policy_test.go`. For ACL
+reference documentation, see `docs/`.
+
+## Integration Testing
+
+**Before running any `hi` command, read `cmd/hi/README.md` in full.**
+Guessing at `hi` flags leads to broken runs and stale containers.
+
+Test-authoring patterns (`EventuallyWithT`, `IntegrationSkip`, helper
+variants, scenario setup) are documented in `integration/README.md`.
+
+Key reminders:
+
+- Integration test functions **must** start with `IntegrationSkip(t)`.
+- External calls (`client.Status`, `headscale.ListNodes`, etc.) belong
+  inside `EventuallyWithT`; state-mutating commands (`tailscale set`)
+  must not.
+- Tests generate ~100 MB of logs per run under `control_logs/{runID}/`.
+  Prune old runs if disk is tight.
+- Flakes are almost always code, not infrastructure. Read `hs-*.stderr.log`
+  before blaming Docker.
+
+## Code Conventions
+
+- **Commit messages** follow Go-style `package: imperative description`.
+  Recent examples from `git log`:
+  - `db: scope DestroyUser to only delete the target user's pre-auth keys`
+  - `state: fix policy change race in UpdateNodeFromMapRequest`
+  - `integration: fix ACL tests for address-family-specific resolve`
+
+  Not Conventional Commits. No `feat:`/`chore:`/`docs:` prefixes.
+
+- **Protobuf regeneration**: changes under `proto/` require
+  `make generate` (which runs `buf generate`) and should land in a
+  **separate commit** from the callers that use the regenerated types.
+- **Formatting** is enforced by `golangci-lint` with `golines` (width 88)
+  and `gofumpt`. Run `make fmt` or rely on the pre-commit hook.
+- **Logging** uses `zerolog`. Prefer single-line chains
+  (`log.Info().Str(...).Msg(...)`). For 4+ fields or conditional fields,
+  build incrementally and **reassign** the event variable:
+  `e = e.Str("k", v)`. Forgetting to reassign silently drops the field.
+- **Tests**: prefer `hscontrol/servertest/` for server-level tests that
+  don't need Docker — faster than full integration tests.
+
+## Gotchas
+
+- **Database**: SQLite for local dev, PostgreSQL for integration-heavy
+  tests (`go run ./cmd/hi run "..." --postgres`). Some race conditions
+  only surface on one backend.
+- **NodeStore writes** rebuild a full snapshot. Measure before changing
+  hot-path code.
+- **`.claude/agents/` is deprecated.** Do not create new agent files
+  there. Put behavioural guidance in this file and procedural guidance
+  in the nearest README.
+- **Do not edit `gen/`** — it is regenerated from `proto/` by
+  `make generate`.
+- **Proto changes + code changes should be two commits**, not one.