WCube Parking Field Agent 0.5.4-RC3 - Installation and PRESERVATION-SAFE Rollback
=================================================================================
(This file SUPERSEDES the INSTALL-AND-ROLLBACK.txt bundled inside
WCube-Field-Agent-0.5.4-RC3.zip. The RC3 runtime payload itself is UNCHANGED;
only this documentation is corrected. See PROVENANCE.txt.)

WHAT THIS IS
  A release candidate of the Field Agent that adds authenticated (session login)
  gate control for the Fort Victoria Tenet system. It is INERT as shipped:
    - The barrier relay is OFF (no gate-relay.json; the example has enabled:false).
    - The Tenet gate contract is EMPTY/unapproved (status:"empty",
      authentication:null). With no confirmed contract the agent refuses every
      control instruction and sends nothing to Tenet.
  THIS RC IS NOT FOR PRODUCTION USE. Do not deploy it to the live gate. The live
  Field Agent (0.5.3) must be left running and untouched until a separate,
  approved go-live release.

READ THIS FIRST - WHY THE OLD ROLLBACK WAS UNSAFE
  Installing the agent IS pairing: Install.cmd / Install-UserGateway.ps1 /
  Install-Service.ps1 each require a fresh one-time pairing code and WRITE a new
  credential.dpapi - i.e. they create a NEW site identity. The uninstallers
  (Uninstall-Gateway, Uninstall-UserGateway, Uninstall-Service) STOP the agent
  and then DELETE credential.dpapi and tell you to revoke the pairing in WCube.
  Therefore:
    * Do NOT run any Uninstall-* script as a rollback step. It deletes the
      pairing credential and destroys the site identity.
    * Do NOT "reinstall 0.5.3" as a rollback step. Re-running an installer
      re-pairs and mints a NEW identity; it does not restore the old one.
  A correct rollback is a FILE-LEVEL restore that reuses the EXISTING
  credential.dpapi, so the agent reconnects with the SAME identity.

SENSITIVE FILES THAT MUST BE PRESERVED (all live in the agent DataDirectory,
e.g. %LOCALAPPDATA%\WCubeParkingGateway for a user install, or the service data
folder for a service install):
  - credential.dpapi .................. pairing credential / site identity (DPAPI)
  - site-profile.json, site-profile-key.json, site-profile-fort-victoria.json
                                        WCube-signed site profile + verify key
  - config.json, config.key ........... agent configuration and its key
  - approved-devices.json ............. technician device/IP approvals
  - installation.json ................. installation markers
  - relay-ledger.json, tenet-request-ledger.json .. replay-protection state
  - gate-relay.json (if ever present) . relay config / Tenet credentials / signing key reference
  - logs and *.json state (queue-state.json, status.json, state.json, result.*)
  Never delete, overwrite or recursively remove this folder during rollback.

STRONGLY RECOMMENDED: TEST RC3 ON A SEPARATE PC
  Evaluate this RC on a spare/lab PC, NOT over the live 0.5.3 install. Then no
  rollback ever touches the live pairing, identity or signing key. If you do this,
  rollback is simply: stop and remove the agent on the spare PC (there is no live
  identity there to protect), and nothing on the production PC changes.

BEFORE INSTALLING ANYWHERE NEAR THE LIVE PC - BACK UP
  1. Stop the running 0.5.3 agent cleanly (see "Stop the agent" below).
  2. Copy the ENTIRE DataDirectory to a safe backup location (keeps
     credential.dpapi, site profile, config, approvals, ledgers, logs).
  3. Copy the current 0.5.3 PROGRAM FILES (the installed .ps1 / .cmd / .exe and
     the scheduled-task action or service binPath) so you can restore them byte
     for byte.
  Do not proceed without both backups.

STOP THE AGENT (without deleting anything)
  - User (scheduled-task) install:
      Stop-ScheduledTask -TaskName 'WCube Parking Gateway'
    Do NOT run Unregister-ScheduledTask and do NOT run Uninstall-UserGateway.ps1.
  - Service install:
      Stop-Service -Name 'WCubeParkingGateway'
    Do NOT run "sc delete" and do NOT run Uninstall-Service.ps1.
  Confirm the process is gone so two agents never run at once (Get-Process, or
  check the task/service shows Stopped).

CONTROLLED MANUAL ROLLBACK (RC3 -> 0.5.3, identity preserved)
  1. Stop the RC agent as above. Verify it is fully stopped (no second agent).
  2. Restore the 0.5.3 PROGRAM FILES from your backup, over the same install
     folder (overwrite only the agent program files you replaced when testing RC3:
     GateRelay.ps1, Gateway.Common.ps1, Service.Common.ps1, Start-Gateway.ps1, the
     Install/Uninstall/Start scripts and WCubeParkingGateway.Service.exe).
     Do NOT touch any file in the "must be preserved" list above.
  3. Restore the ORIGINAL startup command and file paths: the scheduled-task
     action (or service binPath) must point back at the 0.5.3 Start-Gateway.ps1
     with the same -DataDirectory it used before. If you never changed the task/
     service registration, it already points at the right path - leave it.
  4. Start the restored 0.5.3 agent:
       - user:    Start-ScheduledTask -TaskName 'WCube Parking Gateway'
                  (or run Start-FieldAgent.cmd)
       - service: Start-Service -Name 'WCubeParkingGateway'
     It reuses the existing credential.dpapi, so it reconnects with the SAME
     identity. No new pairing code is used; no new identity is minted.

VERIFY AFTER ROLLBACK
  - Run Get-GatewayStatus.ps1: it should show the agent running and paired with
    the SAME gateway/site identity as before (not "paired - no heartbeat", not a
    new pairing).
  - In WCube Parking, the gateway shows online under its ORIGINAL identity and
    heartbeating; no duplicate/new gateway appeared.
  - The barrier relay is OFF and no Tenet contract is active.

RECOVERY (only if something was lost)
  - If the agent will not start, re-restore the 0.5.3 program files and the
    original task/service registration from your backup and start again.
  - If credential.dpapi was deleted or corrupted (e.g. an uninstaller was run by
    mistake): restore it from your DataDirectory backup. ONLY if no backup exists,
    re-pair as a LAST RESORT: generate a fresh one-time code in WCube, revoke the
    old pairing, and run the normal pairing step. This mints a NEW site identity -
    avoid it unless unavoidable, and tell the owner, because approvals/site
    profile are tied to the pairing.

ENABLING REAL GATE CONTROL IS A SEPARATE, APPROVED STEP
  A reviewed go-live release bumps the agent, installs and pins a signed contract,
  provisions a least-privilege Tenet account, and flips the approval flag. Keep
  hardware control OFF until then.

EXCLUDED FROM THIS PACKAGE (by design)
  Passwords, session cookies, signing keys, and any site-specific Tenet
  credentials or confirmed contract.
