@mriekki/project-forge 4.0.0 → 4.1.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "e20e9b0e7102477a30bc15a771d62ba537efe60c",
+      "commit": "738dca3e03d110da0837d35d45101d2315f13a6f",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "0974f36bcb5062c4becb7c5c4e0fbc3e629ad4a9",
+      "commit": "149812159cafdfeeca04645e129392021b8b9e09",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/deployment/distribution.json

@@ -18,6 +18,7 @@
     {"source": "src/project_forge_deployment/entrypoint.py", "destination": "tools/project-forge-deployment/project_forge_deployment/entrypoint.py"},
     {"source": "src/project_forge_deployment/environment_cli.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_cli.py"},
     {"source": "src/project_forge_deployment/environment_probe.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_probe.py"},
+    {"source": "src/project_forge_deployment/environment_setup.py", "destination": "tools/project-forge-deployment/project_forge_deployment/environment_setup.py"},
     {"source": "src/project_forge_deployment/errors.py", "destination": "tools/project-forge-deployment/project_forge_deployment/errors.py"},
     {"source": "src/project_forge_deployment/home_lab.py", "destination": "tools/project-forge-deployment/project_forge_deployment/home_lab.py"},
     {"source": "src/project_forge_deployment/image_transfer.py", "destination": "tools/project-forge-deployment/project_forge_deployment/image_transfer.py"},

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/project-forge",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "components": {
     "core": {
       "repository": "mriekki/project-forge-core",
-      "commit": "e20e9b0e7102477a30bc15a771d62ba537efe60c",
+      "commit": "738dca3e03d110da0837d35d45101d2315f13a6f",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -102,7 +102,7 @@
         {
           "source": "core/skills/project-forge-update/SKILL.md",
           "destination": ".github/skills/project-forge-update/SKILL.md",
-          "sha256": "3463a68171fa30ef10f1ca514424236317ec364f015c5446f49911a1a3c9bb12"
+          "sha256": "510d60fab8d91e54abbc49dbc963a93b132ac5cdfd97ec87f64128ca138d2b1a"
         },
         {
           "source": "core/skills/upstream-fix/SKILL.md",
@@ -328,7 +328,7 @@
     },
     "deployment": {
       "repository": "mriekki/project-forge-deployment-kit",
-      "commit": "0974f36bcb5062c4becb7c5c4e0fbc3e629ad4a9",
+      "commit": "149812159cafdfeeca04645e129392021b8b9e09",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -364,7 +364,7 @@
         {
           "source": "src/project_forge_deployment/app_runtime_workstation.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_runtime_workstation.py",
-          "sha256": "a176074fc7948b802f22adb03730d53b12aac520ba476604a2a9c1e8e29a52b4"
+          "sha256": "17723294fffce40433343df5fd26817df037a8029d473acefa6b767a56c9f725"
         },
         {
           "source": "src/project_forge_deployment/box_platform.py",
@@ -399,12 +399,17 @@
         {
           "source": "src/project_forge_deployment/environment_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_cli.py",
-          "sha256": "ccb38228bd8bf975f9ca9c9298b172b23bec4af7192da0c1cf3aa39bde4dce2d"
+          "sha256": "3c8a0c67c8b75fed7374d1b7b013f95392f84661b6ea182187d07a2b48f206ae"
         },
         {
           "source": "src/project_forge_deployment/environment_probe.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/environment_probe.py",
-          "sha256": "3971264b425c9eb49845a48a54aea849ef35b36b86b13017c0946d3b90e9d707"
+          "sha256": "5f4bba4a9e01b97eccdf67919d49894c9d264fae0edd63f742baaa18e42f69d0"
+        },
+        {
+          "source": "src/project_forge_deployment/environment_setup.py",
+          "destination": "tools/project-forge-deployment/project_forge_deployment/environment_setup.py",
+          "sha256": "1554c2954a024f8419f44eb2ab3fdc129334de41df6038628bade9cb7a803950"
         },
         {
           "source": "src/project_forge_deployment/errors.py",
@@ -419,7 +424,7 @@
         {
           "source": "src/project_forge_deployment/image_transfer.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/image_transfer.py",
-          "sha256": "de8666d8687e1544603fa259c6b302f2f29ab699e6d01b8795b9fce28821c7ed"
+          "sha256": "dadd1fe7724372a4ca0e04ab2280769b6c2381f0f9ae75a096f6c5a5f5add755"
         },
         {
           "source": "src/project_forge_deployment/keys.py",
@@ -539,7 +544,7 @@
         {
           "source": "docs/DEVELOPER_ENVIRONMENTS.md",
           "destination": "docs/project-forge/DEVELOPER_ENVIRONMENTS.md",
-          "sha256": "e818931055044f6158ffe321303a5cbcd2f58724430d51e87c1688e1f71a8fbc"
+          "sha256": "cac10b7e30db24992225a88b43e16aa55404317c87a2ef136f21a2589ee4dc5f"
         },
         {
           "source": "docs/WORKSPACE_INSTANCES.md",
@@ -549,7 +554,7 @@
         {
           "source": "docs/ENVIRONMENT_PROOF.md",
           "destination": "docs/project-forge/ENVIRONMENT_PROOF.md",
-          "sha256": "d139ec1691d073e845a679edf45cb01c971a40b3ccc31404efb8c1e81e481ea5"
+          "sha256": "f635a87ada6a22deb09a3ac0f1c99f8e32119bb8bff3613d77db2ed876dc2552"
         },
         {
           "source": "docs/images/developer-environment-journey.svg",

package/assets/generated/core/core/skills/project-forge-update/SKILL.md

@@ -49,7 +49,7 @@ Do not synthesize or repair missing umbrella provenance by hand.
 
 If `PROJECT_BOOTSTRAP.json` exists, treat it as approved generated-consumer provenance, not unrelated product data.
 
-Before planning an update, require `generation.projectForge.package`, `generation.projectForge.version`, and `generation.projectForge.profile` to agree exactly with the installed `PROJECT_FORGE_BASELINE.json`. Require `generation.projectForge.integrity` to be a non-empty exact registry integrity value for that installed package/version. Verify that integrity read-only from the registry when registry access is available.
+Before planning an update, require `generation["project-forge"].package`, `generation["project-forge"].version`, and `generation["project-forge"].profile` to agree exactly with the installed `PROJECT_FORGE_BASELINE.json`. Require `generation["project-forge"].integrity` to be a non-empty exact registry integrity value for that installed package/version. Verify that integrity read-only from the registry when registry access is available.
 
 If those values disagree before the update, report `GENERATED PROJECT FORGE METADATA DRIFT` and stop. Do not use `/project-forge-update` to silently reconcile an already-incoherent generated consumer.
 
@@ -117,7 +117,7 @@ A modified retired Core path is different: never auto-add `--accept-retired core
 
 For a Bootstrap-generated consumer, also preview the companion generated-consumer changes:
 
-- `PROJECT_BOOTSTRAP.json` keeps the same package/profile but changes `generation.projectForge.version` and `generation.projectForge.integrity` to the exact reviewed target;
+- `PROJECT_BOOTSTRAP.json` keeps the same package/profile but changes `generation["project-forge"].version` and `generation["project-forge"].integrity` to the exact reviewed target;
 - generated package-verification surfaces should consume `PROJECT_BOOTSTRAP.json` dynamically when the accepted Bootstrap contract supports that form;
 - a recognized older Bootstrap-generated verification block may be migrated only when its embedded old package/version/integrity exactly match the currently approved manifest metadata;
 - an unrecognized or locally modified generated verification surface is a stop condition, not permission to reconstruct Bootstrap output by hand.
@@ -152,7 +152,7 @@ Choosing `Apply the exact Project Forge package update` authorizes only:
 - creation/switch to one repository-appropriate short-lived update branch when needed;
 - exact target package apply;
 - removal of unchanged retired package-managed files that the reviewed preview classified as `REMOVE`;
-- when `PROJECT_BOOTSTRAP.json` is present, update of its exact `generation.projectForge.version` and `generation.projectForge.integrity` to the reviewed target while preserving package/profile;
+- when `PROJECT_BOOTSTRAP.json` is present, update of its exact `generation["project-forge"].version` and `generation["project-forge"].integrity` to the reviewed target while preserving package/profile;
 - migration of a recognized Bootstrap-generated package-verification block from duplicated current literals to the accepted manifest-driven form, only when the existing block still exactly matches the current approved metadata;
 - package/baseline/generated-consumer verification;
 - inspection of the resulting meaningful diff.

package/assets/generated/deployment/docs/DEVELOPER_ENVIRONMENTS.md

@@ -2,7 +2,7 @@
 
 Status: **CORE WORKSTATION/TARGET MECHANICS IMPLEMENTED; AUTOMATED HOST PACKAGE PREPARATION REMAINS INCREMENTAL**
 
-This document is the canonical developer-environment model for Project Forges. It describes the developer-facing progression from a generated repository to local development, optional Staging/Production capability, additional workstations, and additional remote boxes.
+This document is the canonical developer-environment model for Project Forge. It describes the developer-facing progression from a generated repository to local development, optional Staging/Production capability, additional workstations, and additional remote boxes.
 
 The happy path intentionally hides Bootstrap/package/control-plane plumbing. Developers should see meaningful milestones and actionable setup, while the underlying repositories retain exact provenance and safety evidence.
 
@@ -44,6 +44,37 @@ The normal conversational entry point is:
 
 The first local success target is `LOCAL WORKSPACE READY`. Remote access must not block it unless the Project explicitly requires a remote dependency for local development.
 
+For remote onboarding, conversational `/setup remote` or `/setup <environment>` should consume one deterministic read-only setup state machine rather than manually reconstructing low-level steps:
+
+```text
+project-forge-deploy environment setup status <target> --json
+project-forge-deploy environment setup plan <target> --json
+```
+
+When target access and the host platform are ready, proof context can be included without performing a write:
+
+```text
+project-forge-deploy environment setup plan <target> \
+  --owner-repo <owner/repo> \
+  --environment <logical-environment> \
+  --json
+```
+
+Add `--production` only when that logical environment is Production-class. Setup status/plan never authorizes a write; they report the existing authorization phrase and exact next deterministic operation when a write is required.
+
+Readiness is deliberately separated into:
+
+```text
+WORKSPACE READY
+TARGET DEFINITION READY
+TARGET ACCESS READY
+HOST PLATFORM READY
+DEPLOYMENT PATH PROVEN
+APPLICATION DEPLOYED
+```
+
+The last state is not part of setup. A successful disposable proof does not deploy the Project application.
+
 ## Progress and next action
 
 Use `/progress` to answer what is complete, what is blocked/deferred, who owns the next action, and local/Staging/Production capability state.
@@ -101,6 +132,8 @@ An empty profile with `targets: []` is valid. A local-only developer never needs
 
 `profile sync` fetches and validates the GitHub profile, updates the validated local cache, and with `--apply` creates only missing non-conflicting local target definitions. Existing differing local definitions are never overwritten.
 
+Portable identity deliberately excludes workstation-local `addressOverride`, identity-file, and trust-file state. A separately verified temporary IP therefore does not make the same portable host definition a different target.
+
 `profile publish` merges new non-conflicting local target definitions into the private profile and fails on conflicts rather than silently replacing remote definitions.
 
 ### Workstation-local state
@@ -116,6 +149,8 @@ Each workstation owns its own:
 
 Private SSH keys are never synchronized between computers. A Mark Windows key, Mark Mac key, Kyle Mac key, and Daniel Windows key are distinct identities even when they can reach the same remote server.
 
+The deterministic doctor resolves and reports the actual SSH executable selected from the workstation environment; all Deployment Kit SSH operations use that resolved toolchain rather than asking the developer to mix shell-specific SSH clients manually.
+
 ## Home Lab remote onboarding
 
 The implemented Home Lab path is password-assisted bootstrap followed by normal strict key-only operation.
@@ -164,7 +199,7 @@ The first Project on a computer may install/verify required local tools and Dock
 
 ### Remote Ubuntu target
 
-Target access can now be established from the local workstation, but full automatic Ubuntu package preparation is still an incremental capability. The desired host progression remains:
+Target access can be established from the local workstation, but full automatic Ubuntu package preparation is still an incremental capability. The desired host progression remains:
 
 ```text
 Ubuntu/sudo verification
@@ -175,7 +210,7 @@ Ubuntu/sudo verification
 → TARGET READY
 ```
 
-The current platform doctor/install contract still requires host prerequisites to exist before shared-platform installation. Until a reviewed host-package bootstrap is added, `/setup remote` must report missing host packages as an actionable preparation gap rather than pretending they were installed.
+The current platform doctor/install contract still requires host prerequisites to exist before shared-platform installation. Until a reviewed host-package bootstrap is added, `/setup remote` reports missing host packages as an actionable preparation gap rather than pretending they were installed. The deterministic setup plan keeps this as a distinct `HOST PLATFORM READY` blocker.
 
 Healthy existing Docker/Project Forge installations are adopted/verified, not recreated. Ambiguous/incompatible existing state fails closed rather than being overwritten.
 
@@ -188,13 +223,16 @@ The implemented workstation-mediated artifact path is:
 ```text
 local GitHub/GHCR authentication when needed
 → acquire/build exact immutable image locally
-→ verify exact identity/digest
+→ preserve registry RepoDigest as declared/release identity
+→ resolve local Docker config/image ID
 → stream Docker image over verified SSH
 → remote docker load
-→ verify exact image remotely
-→ deploy/health-check using the preloaded image
+→ verify the same config/image ID remotely
+→ deploy/health-check by that verified loaded image ID
 ```
 
+Docker `save`/`load` does not guarantee that a registry RepoDigest remains inspectable as a remote RepoDigest after load. Project Forge therefore uses two explicit identities: registry digest for reviewed release provenance, and Docker config/image ID for transport verification and the preloaded runtime reference.
+
 Remote Home Lab boxes therefore do not need a developer's persistent GitHub PAT for the normal workstation-mediated deployment path.
 
 Application deployment selects this with:
@@ -203,7 +241,7 @@ Application deployment selects this with:
 --image-source workstation
 ```
 
-The legacy `--image-source remote-registry` path remains available during migration/for explicit target-side registry use.
+The legacy `--image-source remote-registry` path remains available for explicit target-side registry use.
 
 A credential needed to acquire a private image is entered only through the local Docker/GitHub credential boundary. Never paste it into chat or put it on a command line.
 
@@ -275,7 +313,7 @@ When GitHub cannot be reached, profile sync can use the validated last-known-goo
 
 ## Migration for existing developers
 
-Existing Mark/Kyle environments should migrate fully to this model rather than remain permanently dual-mode.
+Existing developer environments should migrate fully to this model rather than remain permanently dual-mode.
 
 The migration contract is:
 
@@ -284,8 +322,8 @@ inventory existing workstation/targets
 → ensure private personal project-forge-profile + validated cache
 → adopt healthy existing Docker/SSH/trust where valid
 → establish workstation-mediated artifact delivery
-→ prove Staging end-to-end
-→ verify Production access/readiness without deploying
+→ prove a non-Production environment end-to-end
+→ verify Production access/readiness without deploying when Production is configured
 → remove/archive superseded legacy configuration only after verification
 ```
 
@@ -325,11 +363,13 @@ The intended small human surface is:
 
 ```text
 /setup
+/setup local
+/setup remote
+/setup <environment>
 /progress
 /next-step
-/developer-env-mode status|local|remote
 /deployment-readiness <environment>
 /deploy <environment>
 ```
 
-The first three are the normal guided experience. `project-forge-deploy environment ...` commands are deterministic implementation/fallback surfaces and can be invoked directly when desired.
+`/setup` is the single setup front door; the local/remote/environment forms select its scope rather than introducing a separate developer-environment command. `project-forge-deploy environment ...` commands are deterministic implementation/fallback surfaces and can be invoked directly when desired.

package/assets/generated/deployment/docs/ENVIRONMENT_PROOF.md

@@ -13,15 +13,24 @@ this workstation
 → verified target/profile access
 → ready shared host platform
 → pull small stable probe image locally
-→ resolve exact immutable RepoDigest
-→ transfer exact image over verified SSH
-→ deploy with the managed application runtime
+→ resolve exact immutable registry RepoDigest
+→ resolve local Docker config/image ID
+→ transfer image over verified SSH
+→ verify the same config/image ID after remote docker load
+→ deploy with the managed application runtime using that verified loaded image ID
 → verify HTTP health
 → tear down the reserved probe runtime
-→ verify cleanup evidence
+→ verify cleanup and image-cache evidence
 ```
 
-The current default probe image tag is `nginx:alpine`. The tag is never treated as the deployed identity: Project Forge pulls it locally and resolves an exact `@sha256:` RepoDigest before image transfer or remote runtime mutation.
+The current default probe image tag is `nginx:alpine`. The mutable tag is never treated as deployed identity.
+
+Project Forge deliberately records two exact identities because Docker `save`/`load` does not guarantee that a registry RepoDigest remains inspectable under the same repository reference after load:
+
+- **registry digest** — immutable reviewed artifact/release identity (`repository@sha256:...`);
+- **Docker config/image ID** — content identity used to verify the workstation-to-target transfer and to run the preloaded image (`sha256:...`).
+
+The registry digest remains in the deployment spec and release/proof evidence. The loaded runtime is verified and launched by the matching Docker config/image ID. A target that already has that exact image ID can reuse it without retransferring the image.
 
 The probe uses:
 
@@ -33,6 +42,20 @@ The probe uses:
 - the existing per-app/per-environment deployment lock;
 - automatic cleanup through the existing scoped tear-down machinery.
 
+## Setup orchestration
+
+Before running proof commands directly, the read-only remote setup orchestrator can show whether target access and the host platform are actually ready:
+
+```text
+project-forge-deploy environment setup status <target> --json
+project-forge-deploy environment setup plan <target> \
+  --owner-repo <owner/repo> \
+  --environment <name> \
+  --json
+```
+
+These commands never perform the proof or authorize a write. They make `TARGET ACCESS READY`, `HOST PLATFORM READY`, and `DEPLOYMENT PATH PROVEN` separate states.
+
 ## Commands
 
 Read-only plan:
@@ -78,17 +101,44 @@ Production-class proof:
 
 A successful proof never authorizes the later real application deployment. Production proof never authorizes a Production application deployment.
 
+## Terminal evidence
+
+A proof run returns a terminal result even when the operational path fails after the run begins. The result distinguishes planning from observed execution and includes, when available:
+
+```text
+preflight
+registryDigest
+localImageId
+transferState
+remoteImageId
+runtimeState
+httpHealth
+cleanupState
+imageCacheState
+proof
+mutated
+finalMutationState
+error
+cleanupError
+```
+
+A read-only plan does not claim `mutated: false` as though it were the eventual run result. The run reports whether transfer/runtime mutation actually occurred and whether cleanup completed.
+
+A failed proof exits nonzero even when structured terminal evidence was produced successfully.
+
 ## Cleanup
 
 The proof attempts cleanup even when deployment raises after mutation begins.
 
 Successful completion requires terminal cleanup evidence (`removed` or already `absent`) for the reserved probe runtime. If deployment succeeds but cleanup cannot be verified, the command fails rather than reporting a clean proof.
 
+A loaded Docker image may remain cached after runtime cleanup. That state is reported explicitly (for example `runtime-clean-image-cached`) rather than being presented as an unmodified host. Cached image content is not application runtime or persistent application data.
+
 The probe must not delete another Project, another application, another logical environment, or shared host platform state.
 
 ## Relationship to `/setup` and `/deploy`
 
-`/setup` may run this proof after the developer selects a named remote environment to prepare on the current workstation.
+`/setup remote` or `/setup <environment>` may use deterministic setup status/plan first, then run this proof after the developer selects the named remote environment and the relevant write authorization is granted.
 
 A later first real `/deploy <environment>` can reuse fresh proof evidence for target access/platform/transport mechanics and ask only unresolved application-specific questions such as persistence, health, route/exposure, and immutable application artifact policy.
 

package/assets/generated/deployment/src/project_forge_deployment/app_runtime_workstation.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import subprocess
 from typing import Any
 
@@ -19,48 +20,42 @@ from .profiles import load_profile
 from .ssh import ssh_args, verify_access
 
 
-def _preloaded_script(spec: dict[str, Any]) -> str:
+_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
+def _runtime_image_id(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError("Preloaded runtime image ID must be sha256:<64 lowercase hex>.")
+    return value
+
+
+def _preloaded_script(spec: dict[str, Any], runtime_image_id: str) -> str:
+    runtime_image = _runtime_image_id(runtime_image_id)
     script = build_remote_script(spec)
     registry_block = "    decode_desired\n    configure_registry_auth\n"
     if registry_block not in script:
         raise DeploymentKitError("Application runtime template no longer contains the expected registry-auth hook.")
     script = script.replace(registry_block, "    decode_desired\n", 1)
+
     pull = '    docker pull "$D_IMAGE" >/dev/null\n'
-    replacement = '''    if ! docker image inspect "$D_IMAGE" >/dev/null 2>&1; then
-        echo "Exact application image was not preloaded by the workstation-mediated deployment path." >&2
-        exit 40
-    fi
-'''
+    replacement = (
+        f'    if ! docker image inspect "{runtime_image}" >/dev/null 2>&1; then\n'
+        '        echo "Exact application image ID was not preloaded by the workstation-mediated deployment path." >&2\n'
+        "        exit 40\n"
+        "    fi\n"
+    )
     if pull not in script:
         raise DeploymentKitError("Application runtime template no longer contains the expected image-pull hook.")
-    return script.replace(pull, replacement, 1)
-
+    script = script.replace(pull, replacement, 1)
 
-def _run_preloaded_deploy(
-    profile: dict[str, Any],
-    address: str,
-    spec: dict[str, Any],
-    expected_spec_sha: str,
-) -> None:
-    command = ssh_args(
-        profile,
-        address,
-        command="sudo -n bash -s -- deploy " + (expected_spec_sha or "NONE") + " " + profile["user"],
-    )
-    completed = subprocess.run(
-        command,
-        input=_preloaded_script(spec).encode("utf-8"),
-        check=False,
-        capture_output=True,
-    )
-    if completed.returncode != 0:
-        stdout = completed.stdout.decode("utf-8", errors="replace")
-        stderr = completed.stderr.decode("utf-8", errors="replace")
-        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
-        raise DeploymentKitError(f"Workstation-mediated remote application deployment failed: {detail}")
+    runtime_hook = '    docker_args+=("$D_IMAGE")\n'
+    if runtime_hook not in script:
+        raise DeploymentKitError("Application runtime template no longer contains the expected runtime-image hook.")
+    script = script.replace(runtime_hook, f'    docker_args+=("{runtime_image}")\n', 1)
+    return script
 
 
-def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
+def _validate_plan(plan: dict[str, Any]) -> None:
     required = {
         "targetName",
         "action",
@@ -87,19 +82,67 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
     if not isinstance(plan, dict) or set(plan) != required or plan["action"] != "deploy":
         raise DeploymentKitError("Malformed application deployment plan.")
 
-    current = app_inventory(plan["targetName"])
-    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
-        raise DeploymentKitError(
-            "Application inventory changed after the plan was reviewed; create and authorize a fresh plan."
-        )
-    platform = platform_status(plan["targetName"])
-    if platform["state"] != "ready":
-        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
 
-    transfer_image(plan["targetName"], plan["image"])
+def _validate_transfer(plan: dict[str, Any], transfer: dict[str, Any]) -> str:
+    required = {
+        "targetName",
+        "image",
+        "registryDigest",
+        "localImageId",
+        "remoteImageId",
+        "runtimeImage",
+        "status",
+        "mutated",
+    }
+    if not isinstance(transfer, dict) or set(transfer) != required:
+        raise DeploymentKitError("Malformed workstation image-transfer evidence.")
+    if transfer["targetName"] != plan["targetName"]:
+        raise DeploymentKitError("Image-transfer target does not match the deployment plan.")
+    if transfer["registryDigest"] != plan["image"] or transfer["image"] != plan["image"]:
+        raise DeploymentKitError("Image-transfer registry digest does not match the deployment plan.")
+    local_id = _runtime_image_id(transfer["localImageId"])
+    remote_id = _runtime_image_id(transfer["remoteImageId"])
+    runtime_id = _runtime_image_id(transfer["runtimeImage"])
+    if not (local_id == remote_id == runtime_id):
+        raise DeploymentKitError("Workstation and remote Docker image IDs do not match.")
+    if transfer["status"] not in {"already-present", "transferred"} or not isinstance(transfer["mutated"], bool):
+        raise DeploymentKitError("Image-transfer evidence has an invalid terminal state.")
+    return runtime_id
+
+
+def _run_preloaded_deploy(
+    profile: dict[str, Any],
+    address: str,
+    spec: dict[str, Any],
+    expected_spec_sha: str,
+    runtime_image_id: str,
+) -> None:
+    command = ssh_args(
+        profile,
+        address,
+        command="sudo -n bash -s -- deploy " + (expected_spec_sha or "NONE") + " " + profile["user"],
+    )
+    completed = subprocess.run(
+        command,
+        input=_preloaded_script(spec, runtime_image_id).encode("utf-8"),
+        check=False,
+        capture_output=True,
+    )
+    if completed.returncode != 0:
+        stdout = completed.stdout.decode("utf-8", errors="replace")
+        stderr = completed.stderr.decode("utf-8", errors="replace")
+        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
+        raise DeploymentKitError(f"Workstation-mediated remote application deployment failed: {detail}")
+
+
+def apply_app_deploy_with_preloaded_image(
+    plan: dict[str, Any], transfer: dict[str, Any]
+) -> dict[str, Any]:
+    """Apply a reviewed deployment plan using already-verified transfer evidence."""
+
+    _validate_plan(plan)
+    runtime_image_id = _validate_transfer(plan, transfer)
 
-    # Image transfer can take time. Re-check the material app/platform evidence before
-    # changing runtime state; a changed plan must never ride through on stale approval.
     current = app_inventory(plan["targetName"])
     if _inventory_snapshot(current) != plan["inventorySnapshot"]:
         raise DeploymentKitError(
@@ -116,6 +159,7 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
         evidence["address"],
         plan["spec"],
         plan["expectedSpecSha256"] or "",
+        runtime_image_id,
     )
 
     final = app_inventory(plan["targetName"])
@@ -132,5 +176,22 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
         raise DeploymentKitError("Application deployment completed but runtime readiness is not healthy.")
     final["mutated"] = True
     final["imageSource"] = "workstation-transfer"
+    final["imageTransfer"] = transfer
     final["attachesSharedNetwork"] = NETWORK_NAME
     return final
+
+
+def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
+    _validate_plan(plan)
+
+    current = app_inventory(plan["targetName"])
+    if _inventory_snapshot(current) != plan["inventorySnapshot"]:
+        raise DeploymentKitError(
+            "Application inventory changed after the plan was reviewed; create and authorize a fresh plan."
+        )
+    platform = platform_status(plan["targetName"])
+    if platform["state"] != "ready":
+        raise DeploymentKitError("Shared host platform is no longer ready; application deployment is blocked.")
+
+    transfer = transfer_image(plan["targetName"], plan["image"])
+    return apply_app_deploy_with_preloaded_image(plan, transfer)

package/assets/generated/deployment/src/project_forge_deployment/environment_cli.py

@@ -1,4 +1,4 @@
-"""CLI for portable developer environment definitions and Home Lab onboarding."""
+"""CLI for portable developer environment definitions and remote setup orchestration."""
 
 from __future__ import annotations
 
@@ -15,6 +15,7 @@ from .environment_probe import (
     plan_environment_proof,
     run_environment_proof,
 )
+from .environment_setup import remote_setup_plan, remote_setup_status
 from .errors import DeploymentKitError
 from .home_lab import HOME_LAB_BOOTSTRAP_PHRASE, apply_home_lab_bootstrap, plan_home_lab_bootstrap
 from .image_transfer import transfer_image, verify_local_image
@@ -59,6 +60,25 @@ def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="project-forge-deploy environment")
     groups = parser.add_subparsers(dest="group", required=True)
 
+    setup = groups.add_parser(
+        "setup",
+        help="Read-only remote setup status/plan orchestration across target access, host platform, and proof readiness",
+    )
+    setup_sub = setup.add_subparsers(dest="command", required=True)
+    setup_status = setup_sub.add_parser("status", help="Show one terminal readiness model for a remote target")
+    setup_status.add_argument("name")
+    setup_status.add_argument("--json", action="store_true")
+    setup_plan = setup_sub.add_parser("plan", help="Show the exact next deterministic remote setup action")
+    setup_plan.add_argument("name")
+    setup_plan.add_argument("--owner-repo")
+    setup_plan.add_argument("--environment")
+    setup_plan.add_argument(
+        "--production",
+        action="store_true",
+        help="Classify the optional proof environment as Production",
+    )
+    setup_plan.add_argument("--json", action="store_true")
+
     profile = groups.add_parser("profile", help="Personal/portable non-secret target profile operations")
     profile_sub = profile.add_subparsers(dest="command", required=True)
 
@@ -178,6 +198,20 @@ def _home_lab_plan(args: argparse.Namespace) -> dict[str, Any]:
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     try:
+        if args.group == "setup" and args.command == "status":
+            _print(remote_setup_status(args.name), as_json=args.json)
+            return 0
+        if args.group == "setup" and args.command == "plan":
+            _print(
+                remote_setup_plan(
+                    args.name,
+                    owner_repo=args.owner_repo,
+                    environment=args.environment,
+                    production=args.production,
+                ),
+                as_json=args.json,
+            )
+            return 0
         if args.group == "profile" and args.command == "status":
             _print(repository_status(), as_json=args.json)
             return 0
@@ -243,16 +277,19 @@ def main(argv: list[str] | None = None) -> int:
                 production=args.production,
                 probe_image=args.probe_image,
             )
-            _print(plan, as_json=args.json if args.command == "plan" else False)
             if args.command == "plan":
+                _print(plan, as_json=args.json)
                 return 0
+            if not args.json:
+                _print(plan, as_json=False)
             _confirm(
                 args,
                 plan["requiredAuthorization"],
                 f"run a disposable deployment proof for {plan['environment']} on target {plan['targetName']}",
             )
-            _print(run_environment_proof(plan), as_json=args.json)
-            return 0
+            result = run_environment_proof(plan)
+            _print(result, as_json=args.json)
+            return 0 if result.get("proof") == "passed" else 2
         raise DeploymentKitError("Unsupported environment command.")
     except DeploymentKitError as error:
         print(f"ERROR: {error}", file=sys.stderr)

package/assets/generated/deployment/src/project_forge_deployment/environment_probe.py

@@ -10,9 +10,10 @@ import subprocess
 from typing import Any
 
 from .app_runtime import normalize_app_spec, plan_app_deploy
-from .app_runtime_workstation import apply_app_deploy_from_workstation
+from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .box_platform import platform_status
 from .errors import DeploymentKitError
+from .image_transfer import remote_image_present, transfer_image, verify_local_image
 from .registry_access import normalize_registry_image
 from .teardown import tear_down_project
 
@@ -123,10 +124,66 @@ def plan_environment_proof(
         "requiredAuthorization": (
             PRODUCTION_ENVIRONMENT_PROOF_WRITE_PHRASE if production else ENVIRONMENT_PROOF_WRITE_PHRASE
         ),
+    }
+
+
+def _proof_result(plan: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "targetName": plan["targetName"],
+        "ownerRepo": plan["ownerRepo"],
+        "environment": plan["environment"],
+        "production": plan["production"],
+        "probeAppSlug": plan["probeAppSlug"],
+        "probeImageTag": plan["probeImageTag"],
+        "preflight": {
+            "targetAccess": "verified-by-platform-doctor",
+            "hostPlatform": "ready",
+        },
+        "registryDigest": None,
+        "localImageId": None,
+        "transferState": "not-started",
+        "remoteImageId": None,
+        "runtimeState": "not-started",
+        "httpHealth": "not-run",
+        "cleanupState": "not-run",
+        "imageCacheState": "unknown",
+        "proof": "failed",
         "mutated": False,
+        "finalMutationState": "none",
+        "error": None,
+        "cleanupError": None,
     }
 
 
+def _cleanup_state(cleanup: dict[str, Any] | None, environment: str) -> str:
+    if not isinstance(cleanup, dict):
+        return "unknown"
+    entry = next(
+        (item for item in cleanup.get("environments", []) if item.get("environment") == environment),
+        None,
+    )
+    if not isinstance(entry, dict):
+        return "unknown"
+    state = entry.get("runtimeAndPersistentData", {}).get("state")
+    return state if isinstance(state, str) and state else "unknown"
+
+
+def _final_mutation_state(result: dict[str, Any]) -> str:
+    cleanup = result["cleanupState"]
+    cache = result["imageCacheState"]
+    if cleanup not in {"removed", "absent", "not-run"}:
+        return "cleanup-incomplete"
+    if cache == "present":
+        return "runtime-clean-image-cached"
+    if result["mutated"] and cache == "absent":
+        return "clean"
+    if result["mutated"]:
+        return "runtime-clean-cache-unknown"
+    if result["transferState"] == "attempting" and cache == "unknown":
+        return "mutation-unknown-after-transfer-attempt"
+    return "none"
+
+
 def run_environment_proof(plan: dict[str, Any]) -> dict[str, Any]:
     required = {
         "targetName",
@@ -140,89 +197,105 @@ def run_environment_proof(plan: dict[str, Any]) -> dict[str, Any]:
         "healthPath",
         "cleanup",
         "requiredAuthorization",
-        "mutated",
     }
-    if not isinstance(plan, dict) or set(plan) != required or plan["mutated"] is not False:
+    if not isinstance(plan, dict) or set(plan) != required:
         raise DeploymentKitError("Malformed environment proof plan.")
 
-    exact_image = _resolve_probe_image(plan["probeImageTag"])
-    spec = normalize_app_spec(
-        owner_repo=plan["ownerRepo"],
-        environment=plan["environment"],
-        app_slug=plan["probeAppSlug"],
-        container_name=f"{plan['probeAppSlug']}--{plan['environment']}",
-        image=exact_image,
-        runtime_port=80,
-        health_path=plan["healthPath"],
-        run_as="0",
-        persistence_mode="none",
-        data_container_path=None,
-        environment_variables={},
-    )
-    deploy_plan = plan_app_deploy(plan["targetName"], spec)
-
+    result = _proof_result(plan)
+    deploy_plan: dict[str, Any] | None = None
+    transfer: dict[str, Any] | None = None
     deployment: dict[str, Any] | None = None
     cleanup: dict[str, Any] | None = None
-    deploy_error: Exception | None = None
-    cleanup_error: Exception | None = None
+    operation_error: Exception | None = None
+
     try:
-        deployment = apply_app_deploy_from_workstation(deploy_plan)
-    except Exception as error:  # cleanup must still be attempted after a partially applied proof
-        deploy_error = error
+        exact_image = _resolve_probe_image(plan["probeImageTag"])
+        result["registryDigest"] = exact_image
+        local = verify_local_image(exact_image)
+        result["localImageId"] = local["localImageId"]
+
+        spec = normalize_app_spec(
+            owner_repo=plan["ownerRepo"],
+            environment=plan["environment"],
+            app_slug=plan["probeAppSlug"],
+            container_name=f"{plan['probeAppSlug']}--{plan['environment']}",
+            image=exact_image,
+            runtime_port=80,
+            health_path=plan["healthPath"],
+            run_as="0",
+            persistence_mode="none",
+            data_container_path=None,
+            environment_variables={},
+        )
+        deploy_plan = plan_app_deploy(plan["targetName"], spec)
+
+        result["transferState"] = "attempting"
+        transfer = transfer_image(plan["targetName"], exact_image)
+        result["transferState"] = transfer["status"]
+        result["remoteImageId"] = transfer["remoteImageId"]
+        result["mutated"] = bool(transfer["mutated"])
+
+        result["runtimeState"] = "applying"
+        deployment = apply_app_deploy_with_preloaded_image(deploy_plan, transfer)
+        result["runtimeState"] = "healthy"
+        result["httpHealth"] = "passed"
+        result["mutated"] = True
+    except Exception as error:  # terminal proof evidence must survive operational failure
+        operation_error = error
+        result["error"] = str(error)
+        if result["runtimeState"] == "applying":
+            result["runtimeState"] = "failed-or-partial"
+            result["httpHealth"] = "failed-or-not-reached"
     finally:
-        try:
-            cleanup = tear_down_project(
-                {
-                    "ownerRepo": plan["ownerRepo"],
-                    "appSlug": plan["probeAppSlug"],
-                    "scope": plan["environment"],
-                    "environmentTargets": {plan["environment"]: plan["targetName"]},
-                    "localPackage": None,
-                    "productionEnvironments": [plan["environment"]] if plan["production"] else [],
-                }
-            )
-        except Exception as error:
-            cleanup_error = error
-
-    if deploy_error is not None:
-        detail = str(deploy_error)
-        if cleanup_error is not None:
-            detail += f" Cleanup also failed: {cleanup_error}"
-        raise DeploymentKitError(f"Environment proof deployment failed: {detail}") from deploy_error
-    if cleanup_error is not None:
-        raise DeploymentKitError(
-            f"Environment proof deployment succeeded but cleanup failed: {cleanup_error}"
-        ) from cleanup_error
-    assert deployment is not None and cleanup is not None
-
-    matched = next(
-        (
-            item
-            for item in deployment.get("applications", [])
-            if item.get("appSlug") == plan["probeAppSlug"]
-            and item.get("environment") == plan["environment"]
-        ),
-        None,
-    )
-    if not matched or not matched.get("containerRunning") or not matched.get("httpHealthy"):
-        raise DeploymentKitError("Environment proof returned without healthy disposable runtime evidence.")
-    cleanup_entry = next(
-        (item for item in cleanup.get("environments", []) if item.get("environment") == plan["environment"]),
-        None,
-    )
-    if cleanup_entry is None or cleanup_entry.get("runtimeAndPersistentData", {}).get("state") not in {"removed", "absent"}:
-        raise DeploymentKitError("Environment proof cleanup did not return terminal runtime cleanup evidence.")
+        if deploy_plan is not None:
+            try:
+                cleanup = tear_down_project(
+                    {
+                        "ownerRepo": plan["ownerRepo"],
+                        "appSlug": plan["probeAppSlug"],
+                        "scope": plan["environment"],
+                        "environmentTargets": {plan["environment"]: plan["targetName"]},
+                        "localPackage": None,
+                        "productionEnvironments": [plan["environment"]] if plan["production"] else [],
+                    }
+                )
+                result["cleanupState"] = _cleanup_state(cleanup, plan["environment"])
+                if result["cleanupState"] == "removed":
+                    result["mutated"] = True
+            except Exception as error:
+                result["cleanupState"] = "failed"
+                result["cleanupError"] = str(error)
 
-    return {
-        "targetName": plan["targetName"],
-        "ownerRepo": plan["ownerRepo"],
-        "environment": plan["environment"],
-        "production": plan["production"],
-        "probeAppSlug": plan["probeAppSlug"],
-        "probeImage": exact_image,
-        "artifactDelivery": "workstation-transfer",
-        "runtimeHealthy": True,
-        "cleanupState": cleanup_entry["runtimeAndPersistentData"]["state"],
-        "proof": "passed",
-        "mutated": True,
-    }
+        image_id = result.get("localImageId")
+        if isinstance(image_id, str):
+            try:
+                cached = remote_image_present(plan["targetName"], image_id)
+                result["imageCacheState"] = "present" if cached else "absent"
+                if cached:
+                    result["remoteImageId"] = image_id
+                    if result["transferState"] == "attempting":
+                        result["mutated"] = True
+            except Exception:
+                result["imageCacheState"] = "unknown"
+
+    cleanup_terminal = result["cleanupState"] in {"removed", "absent"}
+    if operation_error is None and result["cleanupError"] is None and cleanup_terminal:
+        assert deployment is not None
+        matched = next(
+            (
+                item
+                for item in deployment.get("applications", [])
+                if item.get("appSlug") == plan["probeAppSlug"]
+                and item.get("environment") == plan["environment"]
+            ),
+            None,
+        )
+        if matched and matched.get("containerRunning") and matched.get("httpHealthy"):
+            result["proof"] = "passed"
+        else:
+            result["error"] = "Environment proof returned without healthy disposable runtime evidence."
+    elif operation_error is None and result["cleanupError"] is None and not cleanup_terminal:
+        result["error"] = "Environment proof cleanup did not return terminal runtime cleanup evidence."
+
+    result["finalMutationState"] = _final_mutation_state(result)
+    return result

package/assets/generated/deployment/src/project_forge_deployment/environment_setup.py

@@ -0,0 +1,241 @@
+"""Read-only orchestration for one remote Project Forge setup target.
+
+This module intentionally composes existing deterministic primitives without applying
+mutations. It gives conversational front ends one state machine to render instead of
+reconstructing profile, SSH, host-platform, and proof readiness themselves.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .box_platform import platform_doctor
+from .doctor import target_doctor, workstation_doctor
+from .environment_probe import plan_environment_proof
+from .errors import DeploymentKitError
+from .profiles import load_profile
+from .ssh import verify_access
+
+
+READINESS_ORDER = (
+    "workspace",
+    "targetDefinition",
+    "targetAccess",
+    "hostPlatform",
+    "deploymentPath",
+    "application",
+)
+
+
+def _phase(label: str, state: str, *, detail: Any = None) -> dict[str, Any]:
+    value: dict[str, Any] = {"label": label, "state": state}
+    if detail is not None:
+        value["detail"] = detail
+    return value
+
+
+def remote_setup_status(name: str) -> dict[str, Any]:
+    """Return one read-only, terminal status model for remote environment setup."""
+
+    workstation = workstation_doctor()
+    target = target_doctor(name)
+
+    phases: dict[str, dict[str, Any]] = {
+        "workspace": _phase(
+            "WORKSPACE READY",
+            "ready" if workstation["state"] in {"configured", "partially-configured"} else workstation["state"],
+            detail=workstation,
+        ),
+        "targetDefinition": _phase(
+            "TARGET DEFINITION READY",
+            "ready" if target["state"] != "needs-profile" else "needs-profile",
+            detail=target,
+        ),
+        "targetAccess": _phase("TARGET ACCESS READY", "blocked"),
+        "hostPlatform": _phase("HOST PLATFORM READY", "blocked"),
+        "deploymentPath": _phase("DEPLOYMENT PATH PROVEN", "not-proven"),
+        "application": _phase("APPLICATION DEPLOYED", "not-part-of-setup"),
+    }
+
+    target_access: dict[str, Any] | None = None
+    host_platform: dict[str, Any] | None = None
+
+    if target["state"] == "ready-to-verify":
+        try:
+            target_access = verify_access(load_profile(name))
+            phases["targetAccess"] = _phase("TARGET ACCESS READY", "ready", detail=target_access)
+        except DeploymentKitError as error:
+            phases["targetAccess"] = _phase(
+                "TARGET ACCESS READY",
+                "verification-failed",
+                detail={"reason": str(error)},
+            )
+    elif target["state"] == "needs-profile":
+        phases["targetAccess"] = _phase("TARGET ACCESS READY", "blocked-by-target-definition")
+    else:
+        phases["targetAccess"] = _phase(
+            "TARGET ACCESS READY",
+            f"blocked-by-{target['state']}",
+            detail={"nextAction": target.get("nextAction")},
+        )
+
+    if phases["targetAccess"]["state"] == "ready":
+        try:
+            host_platform = platform_doctor(name)
+            phases["hostPlatform"] = _phase(
+                "HOST PLATFORM READY",
+                "ready" if host_platform["state"] == "ready" else host_platform["state"],
+                detail=host_platform,
+            )
+        except DeploymentKitError as error:
+            phases["hostPlatform"] = _phase(
+                "HOST PLATFORM READY",
+                "inspection-failed",
+                detail={"reason": str(error)},
+            )
+    else:
+        phases["hostPlatform"] = _phase("HOST PLATFORM READY", "blocked-by-target-access")
+
+    current = next(
+        (key for key in READINESS_ORDER if phases[key]["state"] not in {"ready", "not-part-of-setup"}),
+        "application",
+    )
+    return {
+        "targetName": name,
+        "state": "host-platform-ready" if phases["hostPlatform"]["state"] == "ready" else "needs-setup",
+        "currentPhase": current,
+        "phases": phases,
+        "mutated": False,
+    }
+
+
+def _next_action(status: dict[str, Any]) -> dict[str, Any]:
+    phases = status["phases"]
+    target = phases["targetDefinition"].get("detail") or {}
+
+    if phases["targetDefinition"]["state"] == "needs-profile":
+        return {
+            "kind": "missing-facts",
+            "action": "configure-target-profile",
+            "command": f"project-forge-deploy target configure {status['targetName']} <target facts>",
+            "reason": "A target profile does not exist yet; host/user/SSH facts must come from the developer or portable profile.",
+        }
+
+    target_state = target.get("state")
+    if target_state == "needs-key":
+        return {
+            "kind": "write-gated",
+            "action": "create-or-select-key",
+            "command": f"project-forge-deploy target key-create {status['targetName']}",
+            "authorization": "[LOCAL KEY WRITE]",
+        }
+    if target_state == "needs-trust":
+        return {
+            "kind": "human-verification",
+            "action": "verify-and-enroll-host-trust",
+            "command": f"project-forge-deploy target trust-candidates {status['targetName']}",
+            "reason": "Host-key trust requires an independently observed target-console fingerprint before enrollment.",
+        }
+    if target_state == "needs-address":
+        return {
+            "kind": "missing-facts",
+            "action": "set-verified-address",
+            "command": f"project-forge-deploy target address-set {status['targetName']} --address <verified-address>",
+            "reason": "Stable host identity exists but no usable address resolved; use only a separately verified current address.",
+        }
+    if target_state == "blocked":
+        return {
+            "kind": "blocked",
+            "action": target.get("nextAction", "repair-target-profile"),
+            "reason": target.get("reason", "Target definition is blocked."),
+        }
+
+    if phases["targetAccess"]["state"] != "ready":
+        return {
+            "kind": "read-only",
+            "action": "verify-target-access",
+            "command": f"project-forge-deploy target verify {status['targetName']}",
+            "reason": (phases["targetAccess"].get("detail") or {}).get("reason"),
+        }
+
+    platform = phases["hostPlatform"].get("detail") or {}
+    platform_state = phases["hostPlatform"]["state"]
+    if platform_state == "installable":
+        return {
+            "kind": "write-gated",
+            "action": "install-host-platform",
+            "command": f"project-forge-deploy platform install {status['targetName']}",
+            "authorization": "[HOST PLATFORM WRITE]",
+        }
+    if platform_state == "upgrade-required":
+        return {
+            "kind": "write-gated",
+            "action": "upgrade-host-platform",
+            "command": f"project-forge-deploy platform upgrade {status['targetName']}",
+            "authorization": "[HOST PLATFORM WRITE]",
+        }
+    if platform_state in {"blocked-port-80", "drifted", "blocked", "incompatible", "inspection-failed"}:
+        return {
+            "kind": "blocked",
+            "action": platform.get("nextAction", "inspect-host-platform"),
+            "reason": platform.get("reason", f"Host platform state is {platform_state}."),
+            "safety": "Inspect exact ownership/state first; do not broadly prune or take over unrelated host resources.",
+        }
+    if platform_state != "ready":
+        return {
+            "kind": "blocked",
+            "action": "inspect-host-platform",
+            "reason": f"Host platform state is {platform_state}.",
+        }
+
+    return {
+        "kind": "proof-context-required",
+        "action": "plan-deployment-path-proof",
+        "reason": "Target access and host platform are ready. Owner/repository and logical environment are needed to plan the disposable proof.",
+    }
+
+
+def remote_setup_plan(
+    name: str,
+    *,
+    owner_repo: str | None = None,
+    environment: str | None = None,
+    production: bool = False,
+) -> dict[str, Any]:
+    """Return the exact next deterministic setup action without mutating state."""
+
+    status = remote_setup_status(name)
+    next_action = _next_action(status)
+
+    if (
+        next_action["action"] == "plan-deployment-path-proof"
+        and owner_repo is not None
+        and environment is not None
+    ):
+        proof = plan_environment_proof(
+            name,
+            owner_repo=owner_repo,
+            environment=environment,
+            production=production,
+        )
+        command = (
+            f"project-forge-deploy environment proof plan {name} "
+            f"--owner-repo {proof['ownerRepo']} --environment {proof['environment']}"
+        )
+        if production:
+            command += " --production"
+        next_action = {
+            "kind": "read-only",
+            "action": "review-deployment-path-proof",
+            "command": command,
+            "proofPlan": proof,
+            "runAuthorization": proof["requiredAuthorization"],
+        }
+    elif (owner_repo is None) != (environment is None):
+        raise DeploymentKitError("ownerRepo and environment must be supplied together for setup proof planning.")
+
+    return {
+        **status,
+        "next": next_action,
+        "mutated": False,
+    }

package/assets/generated/deployment/src/project_forge_deployment/image_transfer.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import re
 import shlex
 import shutil
 import subprocess
@@ -13,6 +14,9 @@ from .registry_access import normalize_registry_image
 from .ssh import ssh_args, verify_access
 
 
+_IMAGE_ID_RE = re.compile(r"^sha256:[0-9a-f]{64}$")
+
+
 def _docker() -> str:
     path = shutil.which("docker")
     if path is None:
@@ -20,13 +24,25 @@ def _docker() -> str:
     return path
 
 
+def _image_id(value: str) -> str:
+    if not isinstance(value, str) or _IMAGE_ID_RE.fullmatch(value) is None:
+        raise DeploymentKitError("Docker image ID must be sha256:<64 lowercase hex>.")
+    return value
+
+
 def verify_local_image(image: str) -> dict[str, str]:
+    """Verify the declared immutable registry digest and resolve its local config/image ID.
+
+    Registry RepoDigests are release identity. Docker's image ID is the config digest and is
+    the content identity preserved by ``docker save``/``docker load`` even when RepoTags are
+    absent from the archive.
+    """
+
     exact = normalize_registry_image(image)
     result = subprocess.run(
-        [_docker(), "image", "inspect", exact],
+        [_docker(), "image", "inspect", "--format", "{{.Id}}", exact],
         check=False,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.PIPE,
+        capture_output=True,
         text=True,
         encoding="utf-8",
         errors="replace",
@@ -36,11 +52,17 @@ def verify_local_image(image: str) -> dict[str, str]:
             f"Exact image is not present in the workstation Docker engine: {exact}. "
             "Pull/build it locally before transfer."
         )
-    return {"image": exact, "localImage": "verified"}
+    image_id = _image_id(result.stdout.strip())
+    return {
+        "image": exact,
+        "registryDigest": exact,
+        "localImageId": image_id,
+    }
 
 
-def _remote_has_image(profile: dict[str, Any], address: str, image: str) -> bool:
-    command = "sudo -n docker image inspect " + shlex.quote(image) + " >/dev/null 2>&1"
+def _remote_has_image(profile: dict[str, Any], address: str, image_id: str) -> bool:
+    exact_id = _image_id(image_id)
+    command = "sudo -n docker image inspect " + shlex.quote(exact_id) + " >/dev/null 2>&1"
     result = subprocess.run(
         ssh_args(profile, address, command=command),
         check=False,
@@ -50,17 +72,31 @@ def _remote_has_image(profile: dict[str, Any], address: str, image: str) -> bool
     return result.returncode == 0
 
 
+def remote_image_present(name: str, image_id: str) -> bool:
+    """Read-only check for one exact Docker config/image ID on a verified target."""
+
+    exact_id = _image_id(image_id)
+    profile = load_profile(name)
+    access = verify_access(profile)
+    return _remote_has_image(profile, access["address"], exact_id)
+
+
 def transfer_image(name: str, image: str) -> dict[str, Any]:
-    exact = normalize_registry_image(image)
-    verify_local_image(exact)
+    local = verify_local_image(image)
+    exact = local["registryDigest"]
+    image_id = local["localImageId"]
     profile = load_profile(name)
     access = verify_access(profile)
     address = access["address"]
 
-    if _remote_has_image(profile, address, exact):
+    if _remote_has_image(profile, address, image_id):
         return {
             "targetName": name,
             "image": exact,
+            "registryDigest": exact,
+            "localImageId": image_id,
+            "remoteImageId": image_id,
+            "runtimeImage": image_id,
             "status": "already-present",
             "mutated": False,
         }
@@ -93,13 +129,17 @@ def transfer_image(name: str, image: str) -> dict[str, Any]:
         )
         raise DeploymentKitError(f"Remote Docker image load failed: {detail}")
 
-    if not _remote_has_image(profile, address, exact):
+    if not _remote_has_image(profile, address, image_id):
         raise DeploymentKitError(
-            "Remote docker load completed but the exact immutable image reference is not inspectable on the target."
+            "Remote docker load completed but the exact Docker config/image ID is not inspectable on the target."
         )
     return {
         "targetName": name,
         "image": exact,
+        "registryDigest": exact,
+        "localImageId": image_id,
+        "remoteImageId": image_id,
+        "runtimeImage": image_id,
         "status": "transferred",
         "mutated": True,
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/project-forge",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Public consumer distribution and updater for Project Forge engineering assets.",
   "type": "module",
   "bin": {