docs(a5): document Python orchestrator in AGENTS.md, ARCHITECTURE.md, README.md

AGENTS.md: new 'Python development' section (venv paths, install/lint/typecheck/test commands, conventions, full PS->Python sub-command mapping, list of PS scripts that stay PowerShell, link to phase closeouts). README.md: expand 'Python orchestrator' with examples for all 10 sub-commands (wait-ready, vm new/remove/cleanup, build run, artifacts collect, monitor disk/runner, report job, job), local validation gates with 80% coverage gate, link to test_agents_errors.py. docs/ARCHITECTURE.md: new 'Python orchestrator (Phase A)' section with package layout tree, VmBackend Protocol contract, load_backend(config) factory, Phase C ESXi extension recipe, transport selection note, and CI validation gates.

README.md

@@ -150,34 +150,96 @@ Variante **Windows Server 2022**: `*WinBuild2022.ps1` + VMX `F:\CI\Templates\Win
 
 A new Python 3.11+ rewrite of the orchestrator lives under `src/ci_orchestrator/`.
 Phase A (see [implementation-plan-A-B](plans/implementation-plan-A-B.md)) is on
-branch `feature/python-rewrite-phase-a`.
+branch `feature/python-rewrite-phase-a`. As of A5 the Python CLI is the
+production entry point invoked by `gitea/actions/local-ci-build/action.yml`;
+the PowerShell scripts in `scripts/` are 3-line shims that forward to the
+Python sub-commands listed below.
 
-Quick setup on the Windows host:
+### Setup
 
 ```powershell
-# Create venv (one-time)
+# Production venv on the runner host (one-time)
 python -m venv F:\CI\python\venv
 F:\CI\python\venv\Scripts\python.exe -m pip install --upgrade pip
 F:\CI\python\venv\Scripts\python.exe -m pip install -e ".[dev]"
 
-# Sanity checks
-F:\CI\python\venv\Scripts\python.exe -m ci_orchestrator --help
-F:\CI\python\venv\Scripts\python.exe -m pytest tests\python -q
-F:\CI\python\venv\Scripts\python.exe -m ruff check src tests\python
-F:\CI\python\venv\Scripts\python.exe -m mypy --strict src
+# Local dev venv (NOT committed; see .gitignore)
+python -m venv .venv
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
 ```
 
-Configuration: copy `config.example.toml` to `F:\CI\config.toml` (or set
-`$env:CI_CONFIG`). Environment variables (`CI_ROOT`, `CI_TEMPLATES`, …) override
-the file.
+Configuration: copy [config.example.toml](config.example.toml) to
+`F:\CI\config.toml` (or set `$env:CI_CONFIG`). Environment variables
+(`CI_ROOT`, `CI_TEMPLATES`, `CI_BUILD_VMS`, `CI_ARTIFACTS`, `CI_KEYS`)
+override the file. Dependency manifest and tool config (ruff, mypy,
+pytest, coverage) live in [pyproject.toml](pyproject.toml).
 
-In Phase A1 only the `wait-ready` PoC is wired:
+### CLI sub-commands
 
 ```powershell
-F:\CI\python\venv\Scripts\python.exe -m ci_orchestrator wait-ready `
+# Discover commands
+python -m ci_orchestrator --help
+
+# Wait for a VM to become reachable (WinRM 5986 or SSH 22 — auto-detected)
+python -m ci_orchestrator wait-ready `
     --vmx F:\CI\BuildVMs\smoke\smoke.vmx --guest-os windows --timeout 300
+
+# Linked-clone lifecycle
+python -m ci_orchestrator vm new `
+    --template-path F:\CI\Templates\WinBuild2025\WinBuild2025.vmx `
+    --snapshot-name BaseClean `
+    --clone-base-dir F:\CI\BuildVMs `
+    --job-id smoke-001
+python -m ci_orchestrator vm remove --vmx F:\CI\BuildVMs\Clone_smoke-001_*\Clone_smoke-001_*.vmx
+python -m ci_orchestrator vm cleanup --max-age-hours 12
+
+# Build + artifact collection
+python -m ci_orchestrator build run `
+    --vmx F:\CI\BuildVMs\Clone_smoke-001_*\*.vmx `
+    --script .\build.ps1 --workdir C:\build --guest-os windows
+python -m ci_orchestrator artifacts collect `
+    --vmx F:\CI\BuildVMs\Clone_smoke-001_*\*.vmx `
+    --remote-path C:\build\dist --local-dir F:\CI\Artifacts\smoke-001
+
+# Monitoring (driven by Task Scheduler / systemd timers in B5)
+python -m ci_orchestrator monitor disk --min-free-gb 50 --drive-letter F
+python -m ci_orchestrator monitor runner --state-dir F:\CI\act_runner
+
+# Reporting
+python -m ci_orchestrator report job --job-id smoke-001
+
+# End-to-end orchestrator (replaces Invoke-CIJob.ps1)
+python -m ci_orchestrator job `
+    --job-id        smoke-001 `
+    --repo-url      ssh://gitea-ci/Simone/nsis-plugin-nsinnounp.git `
+    --branch        main `
+    --template-path F:\CI\Templates\WinBuild2025\WinBuild2025.vmx `
+    --build-command "python build_plugin.py --final --dist-dir dist" `
+    --guest-artifact-source dist
 ```
 
+The PowerShell wrappers (`scripts\Invoke-CIJob.ps1`,
+`scripts\New-BuildVM.ps1`, `scripts\Wait-VMReady.ps1`,
+`scripts\Remove-BuildVM.ps1`, `scripts\Cleanup-OrphanedBuildVMs.ps1`,
+`scripts\Invoke-RemoteBuild.ps1`, `scripts\Get-BuildArtifacts.ps1`,
+`scripts\Watch-DiskSpace.ps1`, `scripts\Watch-RunnerHealth.ps1`,
+`scripts\Get-CIJobSummary.ps1`) are kept as 3-line shims for Task
+Scheduler and external callers — they translate PascalCase parameters
+to the Python kebab-case CLI and propagate the exit code.
+
+### Local validation gates
+
+```powershell
+.\.venv\Scripts\python.exe -m ruff check src tests\python
+.\.venv\Scripts\python.exe -m mypy --strict src
+.\.venv\Scripts\python.exe -m pytest tests\python -q --cov=ci_orchestrator --cov-fail-under=80
+```
+
+Coverage gate is **80%** as of Phase A5. Regression tests for the
+`AGENTS.md` "Errori frequenti da evitare" #9–#12 live in
+[tests/python/test_agents_errors.py](tests/python/test_agents_errors.py)
+and must stay green.
+
 ---
 
 ## Setup rapido