docs: update documentation for Linux VM support (Sprint 9)

AGENTS.md (new):
- Environment reference for AI agents: host specs, PS 5.1 constraints,
  dir structure, VM templates, transport layer, style rules
- Lessons #9 (snapshot cold state) and #10 (vmrun list vs getGuestIPAddress)

ARCHITECTURE.md:
- Add SSH/SCP transport section (Linux VMs)
- Update system diagram to include _Transport.psm1, SSH transport path
- Network layout: add SSH port 22 for Linux VMs
- Timeline: Linux readiness check phases documented

CI-FLOW.md:
- Prerequisites table: add Template VM (Linux), SSH key row
- Step 6 (readiness): document Windows vs Linux phases
- Step 7 (build) and Step 8 (artifacts): document Linux/SSH paths
- ci-report-ip guestinfo mechanism referenced

HOST-SETUP.md:
- Directory tree: add LinuxBuild2404 template dir and keys/
- Post-setup checklist: add step 5 (SSH key generation + Linux template)
- Fix duplicate step numbering (56, 67)
- Reference Paths table: add Linux template VMX, snapshot, SSH key

LINUX-TEMPLATE-SETUP.md:
- Rewritten as implementation record (no longer a plan)
- Fase A user-data: minimal (user+SSH key only, no packages/runcmd)
- All phases marked complete with actual paths and snapshot names

WINDOWS-TEMPLATE-SETUP.md: minor updates for consistency

TODO.md:
- Summary: update last-updated to 2026-05-11, Sprint 9 description
- Linux Build VM row: all 5 items complete
- Prossimi passi: Test Plan + §6.6 Tier-2 as next priorities

docs/CI-FLOW.md

@@ -12,8 +12,10 @@ Before any CI job runs, the following must be in place:
 | ------------------ | ----------------------------------------------------------------------- |
 | Gitea server       | Running, accessible on LAN                                              |
 | act_runner         | Registered, running as Windows service on host                          |
-| Template VM        | Provisioned, snapshot "BaseClean" taken, VM powered off                 |
-| WinRM              | Enabled on template VM (inherits to all clones)                         |
+| Template VM (Win)  | Provisioned, snapshot "BaseClean" taken, VM powered off                 |
+| Template VM (Lin)  | Ubuntu 24.04 LTS, snapshot "BaseClean-Linux" taken, VM powered off (optional) |
+| WinRM              | Enabled on Windows template VM (inherits to all clones)                 |
+| SSH key            | `F:\CI\keys\ci_linux` (ed25519) present; public key in Linux template   |
 | vmrun.exe          | Present at `C:\Program Files (x86)\VMware\VMware Workstation\vmrun.exe` |
 | `F:\CI\BuildVMs\`  | Directory exists and writable                                           |
 | `F:\CI\Artifacts\` | Directory exists and writable                                           |
@@ -110,12 +112,19 @@ Wait-VMReady.ps1 -VMPath <clone.vmx> -IPAddress <dynamic-NAT-ip> -TimeoutSeconds
 IP is discovered dynamically via `vmrun getGuestIPAddress` (VMnet8 NAT, subnet 192.168.79.0/24).
 No hardcoded IPs — each clone gets a DHCP-assigned address from VMware NAT.
 
-Three-phase readiness check (retried every 5 seconds, up to 300s timeout):
+Three-phase readiness check (retried every 5 seconds, up to 300s timeout).
+Transport is selected automatically from the VMX `guestOS` field (`-Transport WinRM` for Windows, `-Transport SSH` for Linux):
 
 ```
 Phase 1: vmrun getState → must return "running"
-Phase 2: Test-Connection (ICMP ping) → must succeed
-Phase 3: Test-WSMan → WinRM listener must respond
+
+Windows (-Transport WinRM, default):
+  Phase 2: Test-Connection (ICMP ping) → must succeed
+  Phase 3: Test-WSMan → WinRM listener must respond
+
+Linux (-Transport SSH):
+  Phase 2: Test-NetConnection -Port 22 → must succeed
+  Phase 3: ssh -o ConnectTimeout=5 ... "echo ready" → must return "ready"
 ```
 
 - Total wait is typically **30–90 seconds** after `vmrun start`
@@ -129,9 +138,18 @@ Phase 3: Test-WSMan → WinRM listener must respond
 ```
 Invoke-RemoteBuild.ps1
   -IPAddress   <dynamic-NAT-ip>           # from vmrun getGuestIPAddress
+  -GuestOS     Windows|Linux              # auto-detected from VMX guestOS field
+
+  # Windows path (default):
   -Credential  (from Windows Credential Manager)
   -BuildCommand 'python build_plugin.py --final --dist-dir dist'
   -GuestArtifactSource 'dist'
+
+  # Linux path (-GuestOS Linux):
+  -SshKeyPath  F:\CI\keys\ci_linux
+  -SshUser     ci_build
+  -CloneUrl / -CloneBranch   # always in-VM git clone for Linux
+  -BuildCommand 'make all'
 ```
 
 Sequence inside the PSSession:
@@ -163,14 +181,22 @@ Sequence inside the PSSession:
 ```
 Get-BuildArtifacts.ps1
   -IPAddress       <dynamic-NAT-ip>
-  -Credential      (same as above)
+  -GuestOS         Windows|Linux         # auto-detected from Invoke-CIJob
+
+  # Windows path (default):
+  -Credential      (from Windows Credential Manager)
   -GuestArtifactPath  C:\CI\output\artifacts.zip
+
+  # Linux path (-GuestOS Linux):
+  -SshKeyPath      F:\CI\keys\ci_linux
+  -GuestArtifactPath  /opt/ci/output
+
   -HostArtifactDir    F:\CI\Artifacts\{JobId}\
 ```
 
-- Apre PSSession e copia `C:\CI\output\artifacts.zip` dall'host
-- Valida che il file esista e sia non-vuoto
-- Il zip contiene la struttura `dist/` con tutti gli artifact di build
+- Windows: apre PSSession e copia `C:\CI\output\artifacts.zip` tramite WinRM
+- Linux: `scp -r ci_build@<ip>:/opt/ci/output/. <HostArtifactDir>` tramite `_Transport.psm1`
+- In entrambi i casi valida che almeno un file sia stato trasferito
 
 ---