docs: align documentation with session fixes

Reconcile docs with the end-to-end pipeline fixes:
- upload/download-artifact @v4 -> @v3 (Gitea GHES) in WORKFLOW-AUTHORING
  and workflow-example.yml; add Common Mistakes rows (v4, action ref
  form + DEFAULT_ACTIONS_URL, public action repo).
- BEST-PRACTICES / README / HOST-SETUP: guest credential must live in
  the LocalSystem vault with a host-qualified username; document
  Set-CIGuestCredential.ps1 / Test-CIGuestWinRM.ps1 and auth=ntlm.
- README / AGENTS / HOST-SETUP: production venv install is NON-editable
  (LocalSystem); no CI workflow may install into it.
- HOST-SETUP: add DEFAULT_ACTIONS_URL=github + full-URL uses: + public
  repo + @main requirements discovered during validation.
- Correct stale repo name local-ci-system -> local-ci-cd-system.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/BEST-PRACTICES.md

@@ -4,29 +4,40 @@
 
 ### Do NOT store credentials in scripts or config files
 
-The scripts use `-GuestCredentialTarget` (a Windows Credential Manager target name)
-rather than plaintext username/password parameters. Store credentials once:
+The guest VM credential is referenced by target name (`BuildVMGuest`,
+`GITEA_CI_GUEST_CRED_TARGET`) and read by the Python orchestrator via the
+`keyring` library — never as plaintext parameters.
+
+> **Critical: store it in the LocalSystem vault, not your user vault.**
+> act_runner runs as the `LocalSystem` service account. Windows Credential
+> Manager / keyring vaults are **per-user**. A credential added with
+> `cmdkey` or the Credential Manager UI from an interactive admin session
+> lands in *your* vault and is invisible to the runner, which then fails
+> with `Credential 'BuildVMGuest' not found in keyring`.
+
+> **Username must be host-qualified.** The guest is a workgroup machine;
+> NTLM rejects a bare `ci_build` with `SEC_E_UNKNOWN_CREDENTIALS`. Store
+> it as `WINBUILD-2025\ci_build` (the guest computer name, i.e. the WinRM
+> TLS certificate CN). The WinRM transport forces `auth='ntlm'` for the
+> same reason (Negotiate→Kerberos is meaningless without a domain).
+
+Store (or rotate) the credential with the helper, which writes into the
+SYSTEM vault via the production venv's `keyring` (run elevated):
 
 ```powershell
-# Run on host (once, before first CI job)
-cmdkey /generic:BuildVMGuest /user:MACHINENAME\ci_build /pass:YourStrongPassword
+.\scripts\Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'
 ```
 
-Retrieve in scripts via the `CredentialManager` PowerShell module:
-
-```powershell
-Install-Module CredentialManager -Scope CurrentUser
-$cred = Get-StoredCredential -Target 'BuildVMGuest'
-```
+It prompts for the password securely, writes it to the SYSTEM vault, and
+verifies the read-back as SYSTEM. Diagnose WinRM reachability/auth with
+`.\scripts\Test-CIGuestWinRM.ps1 -IpAddress <guest-ip>`.
 
 ### Rotate credentials quarterly
 
-1. Update password in the template VM (requires rebuilding `BaseClean` snapshot)
-2. Update Windows Credential Manager on the host:
-   ```
-   cmdkey /generic:BuildVMGuest /user:MACHINENAME\ci_build /pass:NewPassword
-   ```
-3. No script changes required — they reference the target name, not the password.
+1. Update the password in the template VM (rebuild the `BaseClean` snapshot).
+2. Re-run `Set-CIGuestCredential.ps1 -UserName 'WINBUILD-2025\ci_build'`
+   with the new password.
+3. No code changes required — the orchestrator references the target name.
 
 ---