@mriekki/project-forge 4.7.0 → 4.8.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "defaultProfile": "greenfield-project",
   "profiles": {
     "greenfield-project": {
@@ -13,7 +13,7 @@
   },
   "components": {
     "core": {
-      "revision": "737dab0636252410c022be057d25c36c1dd5f116",
+      "revision": "a78c2482f4f559ead8efbab6c25b4b05496db735",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -21,7 +21,7 @@
       "canonicalDescriptor": "distributions/greenfield-workspace.json"
     },
     "deployment": {
-      "revision": "f7441081114be94a22d6e1774194dc8bd7a88e18",
+      "revision": "aaf5d24c897b3d89b3d1791c79bed4979414ca40",
       "distribution": "greenfield-project",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/generated/ASSEMBLY.json

@@ -1,10 +1,10 @@
 {
   "schemaVersion": 2,
   "package": "@mriekki/project-forge",
-  "version": "4.7.0",
+  "version": "4.8.0",
   "components": {
     "core": {
-      "revision": "737dab0636252410c022be057d25c36c1dd5f116",
+      "revision": "a78c2482f4f559ead8efbab6c25b4b05496db735",
       "version": "4.0.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -116,12 +116,12 @@
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
-          "sha256": "33be75e856b1b16378bb2a456d8418f8ae0b03edee75fb826d8f7ef3824d2f6a"
+          "sha256": "30202702cc368c872e62ce731e8ffe84a796aae243b287e3e670c8c8e1cd6531"
         },
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "21b8209bc756ef2981f9e44f19ee80e79c1c5c7d5be4c03c9b528fdadd7b8eca"
+          "sha256": "f5d40e549ca958cb51606ced7ca482651d9a436327b6070a9a94171f22401700"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
@@ -326,7 +326,7 @@
       ]
     },
     "deployment": {
-      "revision": "f7441081114be94a22d6e1774194dc8bd7a88e18",
+      "revision": "aaf5d24c897b3d89b3d1791c79bed4979414ca40",
       "distribution": "greenfield-project",
       "files": [
         {
@@ -357,12 +357,12 @@
         {
           "source": "src/project_forge_deployment/app_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_cli.py",
-          "sha256": "9bf8eb7337c5b506311bf718de71b9a2c9ac445eb94cb7dfdeb63a09e5f0f899"
+          "sha256": "f27704c80b1eff45888bf56745bcf8755f2fad88851147600af7056953757825"
         },
         {
           "source": "src/project_forge_deployment/app_deployment.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/app_deployment.py",
-          "sha256": "e58158e48c9fbd51b51f7af90f2dd178987ad3936e44507523cfc41b96fcd9f9"
+          "sha256": "606d6a4793ac8c8a95da4cd4c61792c69f02ad86900be1944d2ed570dd71e73e"
         },
         {
           "source": "src/project_forge_deployment/app_runtime.py",
@@ -502,12 +502,12 @@
         {
           "source": "src/project_forge_deployment/registry_access.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/registry_access.py",
-          "sha256": "5815a1921ecf37dc395f9c68b1ebda2b17dd6a44620b2356d1adff5df44c4382"
+          "sha256": "1f582f1b5da656579625748b13c779f6d67ed6a6049f0ebb104ce8c3f9185a4b"
         },
         {
           "source": "src/project_forge_deployment/registry_cli.py",
           "destination": "tools/project-forge-deployment/project_forge_deployment/registry_cli.py",
-          "sha256": "1936156eb3b6103895795cde3b5f520491e407bf35f311be883a54fbfff635fc"
+          "sha256": "2ce977fa570580407c04a3e59d0a524f128af420b7ee20fd9706e6452378b7b3"
         },
         {
           "source": "src/project_forge_deployment/route_registry.py",

package/assets/generated/core/core/skills/deploy/SKILL.md

@@ -44,7 +44,7 @@ Read only what is needed, including when present:
 - `PROJECT_FORGE_BASELINE.json`;
 - `DEPLOYMENT_BASELINE.json`;
 - project topology and approved deployment/release requirements;
-- `/deployment-readiness` evidence, including deterministic application isolation evidence when supported;
+- `/deployment-readiness` evidence, including first-application outcome assessment and deterministic application isolation evidence when supported;
 - fresh setup-time environment-proof evidence for this workstation;
 - established application deployment facts.
 
@@ -62,7 +62,27 @@ Proof does not establish the real application's image/release, persistence/migra
 
 A prior readiness isolation fingerprint is review evidence only. It does not authorize deployment and does not replace the deterministic deployment planner's current isolation revalidation.
 
-## 3. First real deployment asks only unresolved application questions
+For a first real deployment, do not collapse a target/platform `READY` result into application deployability. Confirm that readiness established an actual artifact build/publication/acquisition path when that path is material. If artifact identity or acquisition is still hypothetical, return to the missing prerequisite rather than requesting the application write gate.
+
+## 3. Preserve execution and credential context
+
+When installed tooling exposes structured capability evidence, preserve its semantics exactly in the deployment assessment and preview. In particular, retain fields equivalent to:
+
+```text
+executionLocation
+credentialContext
+capabilityProved
+capabilityAttempted
+doesNotProve
+```
+
+A registry manifest check executed on a remote target proves only the capability reported for that target/context. Never describe it as workstation registry access. A workstation registry check proves only the workstation capability it reports. Neither implies Actions registry transport or package-metadata API access.
+
+Do not infer provider-specific token scopes or error meaning from generic registry results. Provider-specific package metadata/publication behavior belongs to repository/provider tooling and its own evidence.
+
+When a new credential is genuinely required, explain its purpose, execution context, storage location, retrievability, and rotation impact before asking the developer to create it. Credential values remain in the provider/local secret surface and never enter chat.
+
+## 4. First real deployment asks only unresolved application questions
 
 The first real `/deploy <environment>` after environment proof may need a small application-specific completion step. Ask only material unknowns not already answered by project evidence, such as:
 
@@ -79,7 +99,7 @@ When a bounded choice is useful, follow `INTERACTIVE_SESSION_GUIDE.md`: use host
 
 Once these facts are durably established, later deployments should be routine rather than repeating onboarding.
 
-## 4. Placement determines launcher
+## 5. Placement determines launcher
 
 ### Workstation container
 
@@ -114,7 +134,7 @@ Use only an installed repository/catalog provider adapter. If none exists, stop
 
 Report `DEPLOYMENT NOT BOUND YET` and route to `/setup <environment>` or `/deployment-readiness <environment>`.
 
-## 5. Preserve custom Production classification
+## 6. Preserve custom Production classification
 
 Pass the exact configured environment name to the deterministic launcher.
 
@@ -126,7 +146,7 @@ When resolved purpose/classification is Production, use the installed tool's exp
 
 Inspect installed help/version evidence. If the installed tool cannot preserve Production classification for a custom name, stop rather than downgrading safety.
 
-## 6. Build the deterministic plan
+## 7. Build the deterministic plan
 
 Use repository-provided tooling to construct/inspect the exact application deployment plan. Supported operations may include:
 
@@ -149,7 +169,44 @@ The deterministic deployment tool owns the final current-state recheck immediate
 
 Do not smuggle infrastructure provisioning, target/provider rebinding, destructive restore, or environment tear-down into the application plan.
 
-## 7. Preserve exact authorization contracts
+### Remote runtime + route rollout preview
+
+When the installed Deployment Kit exposes a deterministic read-only `app rollout` capability and the selected remote deployment has an intended route, prefer that capability for the final pre-write preview rather than independently narrating runtime and route consequences.
+
+A current installed contract may expose a command shape similar to:
+
+```text
+project-forge-deploy app rollout <target>
+  --owner-repo <owner/repository>
+  --environment <exact environment>
+  --app-slug <application slug>
+  --container-name <container>
+  --runtime-port <port>
+  --persistence-mode <none|directory>
+  --image <immutable digest>
+  --health-path <path>
+  --run-as <uid[:gid]>
+  [--route-hostname <hostname> ...]
+  [--production]
+  --json
+```
+
+Inspect installed help/version rather than assuming this example exactly matches every package version.
+
+Treat the returned staged rollout as **read-only review evidence**. Preserve:
+
+```text
+runtime plan + isolation evidence
+route plan + route-inventory evidence
+separate stage authorizations
+endpoint state before runtime
+after-runtime / before-route endpoint state
+after-route verification state
+```
+
+If the installed package lacks this composite preview, retain the existing safe runtime and route planners and state their sequence explicitly. Do not invent a combined write command.
+
+## 8. Preserve exact authorization contracts
 
 Core consequence labels do not replace stricter installed-tool phrases.
 
@@ -158,17 +215,20 @@ The standard Deployment Kit may use exact phrases such as:
 ```text
 [APP DEPLOY WRITE]
 [PRODUCTION APP DEPLOY]
+[ROUTE WRITE]
 ```
 
 For Production-class environments also show `[PRODUCTION WRITE]` consequence visibility where Core policy calls for it.
 
-Resolve the exact phrase from the installed tool/version. Do not assume an example phrase when the installed contract differs.
+Resolve the exact phrase from the installed tool/version. For a staged rollout, resolve it separately for each stage. Do not assume an example phrase when the installed contract differs.
+
+Authorization applies only to the exact environment, resolved classification, placement/target/provider, artifact, reviewed plan/stage, current isolation evidence and route evidence, and evidence shown. Material changes require renewed review/authorization.
 
-Authorization applies only to the exact environment, resolved classification, placement/target/provider, artifact, reviewed plan, current isolation evidence, and evidence shown. Material changes require renewed review/authorization.
+A runtime authorization never authorizes the route stage. A route authorization never retroactively authorizes a changed runtime artifact. If the rollout contains both stages, preserve the separate gates even though the Builder reviewed one coherent outcome.
 
-## 8. Preview and execute only the approved contract
+## 9. Preview and execute only the approved contract
 
-Before mutation, show concise non-secret evidence such as exact environment, purpose, placement, target/provider when applicable, proof freshness, immutable application artifact, persistence/migration, exposure/route, application isolation state/fingerprint when exposed, shared failure-domain note when relevant, planned operations, and exact required authorization phrase.
+Before mutation, show concise non-secret evidence such as exact environment, purpose, placement, target/provider when applicable, proof freshness, immutable application artifact, persistence/migration, exposure/route, application isolation state/fingerprint when exposed, shared failure-domain note when relevant, planned stages, endpoint state at each stage, and the exact required authorization phrase for the next consequence only.
 
 After authorization, invoke only the repository-provided deterministic launcher. Never redirect to another environment/host/provider, weaken trust/exposure, force through lock contention, or invent recovery writes.
 
@@ -176,7 +236,37 @@ The deterministic launcher must revalidate current isolation immediately before
 
 Existing per-app/per-environment locks are normal concurrency protection when another workstation is deploying the same environment.
 
-## 9. Validate live evidence
+### Runtime succeeded but route is pending
+
+A healthy application runtime is a valid intermediate outcome. When a requested route has not yet been registered, say this explicitly before showing the route gate:
+
+```text
+APPLICATION RUNTIME READY
+Expected endpoint: <hostname/URL>
+Endpoint state: NOT ACTIVE — ROUTE PENDING
+Do not test this URL yet; the route write has not been authorized/applied.
+```
+
+Then, if the reviewed route plan is still current, present the route consequence directly. Do not require the developer to invoke `/deploy` or another slash command merely to rediscover the already reviewed route stage.
+
+The runtime success does not consume or imply route authorization. If route evidence changed, rebuild/review the route plan first.
+
+## 10. Resume the established outcome without navigation ceremony
+
+Within the same conversation, if a bounded engineering/delivery correction or external prerequisite completes and the developer's requested deployment outcome remains unambiguous, automatically resume safe **read-only** reconstruction of readiness/deployment evidence from the repository, GitHub, installed tools, and runtime state.
+
+Do not require the developer to type `/deliver`, `/deployment-readiness`, or `/deploy` merely as navigation to rediscover known state after that bounded action completes.
+
+This continuation:
+
+- never repeats a completed write;
+- never reuses exhausted registry/Production/route/merge/migration/destructive authority;
+- stops when the artifact, plan, target, consequence, or other material evidence changed;
+- does not create a parallel persistent workflow database.
+
+If `/deploy` is invoked again after an already validated deployment, first reconstruct current deployment evidence. If the same validated artifact/runtime/route remains current and no new deployment outcome is requested, report the existing validated state rather than proposing or performing a redundant redeployment.
+
+## 11. Validate live evidence
 
 After execution, use repository-provided inventory/health/route/smoke/evidence commands when available.
 
@@ -191,10 +281,32 @@ Artifact: <exact immutable identity>
 Artifact delivery: <workstation-transfer|remote-registry|local-runtime|provider>
 Endpoint/Route: READY / LOOPBACK / NOT APPLICABLE
 Application health: READY
+Workstation/browser verification: PASSED / NOT APPLICABLE / PENDING
 Smoke: PASSED / NOT REQUIRED
 Deployment evidence: RECORDED / VERIFIED
 ```
 
-Do not report success merely because a container/process started when stronger health evidence is required.
+Do not report success merely because a container/process started when stronger health evidence is required. Do not report a route as user-accessible merely because registration returned; perform the repository-supported endpoint/workstation/browser verification when the requested outcome depends on it.
 
 A setup-time disposable environment proof is not real application deployment evidence. A successful application deployment never authorizes a later Production write or destructive `/tear-down`.
+
+Keep human access confirmation distinct from automated browser/health evidence. The developer saying they can reach the endpoint is useful observed human evidence; it is not automatically formal work-item acceptance.
+
+## 12. Reconcile the durable outcome without asserting acceptance
+
+After `DEPLOYMENT VALIDATED`, inspect the repository's configured work-item/operating authority. When an existing current-status or deployment-result section is stale and the observed deployment outcome is material, offer a bounded reconciliation containing only supported non-secret facts such as:
+
+```text
+exact environment
+release/source/artifact identity
+artifact delivery method
+runtime health result
+route/endpoint
+workstation/browser validation
+explicit human access confirmation, when actually stated
+known limitations and evidence boundaries
+```
+
+Preserve historical approval records. Do not silently rewrite product requirements, broaden the milestone, mark formal acceptance, close the work item, or infer acceptance from browser accessibility.
+
+If the human authorizes the bounded documentation update, use the repository's normal work-item/delivery workflow for that edit. Documentation reconciliation is not a reason to redeploy and does not create new Production write authority.

package/assets/generated/core/core/skills/deployment-readiness/SKILL.md

@@ -78,7 +78,78 @@ It does not prove final application artifact identity, persistence/migration beh
 
 If topology, target binding, host trust, platform state, or another material fact changes, treat the proof as stale and reverify the affected prerequisite.
 
-## 3. Placement branches
+## 3. First-application outcome assessment
+
+For the first real application deployment to an environment, or whenever the developer's stated goal is a usable endpoint rather than only machine readiness, keep that requested outcome visible and assess the whole material path before declaring the application deploy-ready.
+
+Inspect available non-secret repository, package/tool, workstation, target, and GitHub/CI evidence before asking for facts. Do not require a release workflow to fail merely to discover a prerequisite that can be identified read-only.
+
+Build a compact prerequisite matrix with rows such as:
+
+```text
+requested outcome / expected endpoint
+workstation architecture
+required artifact/target architecture
+immutable artifact or release identity policy
+artifact destination / publication state when relevant
+credential capability + execution location for each required operation
+workstation artifact acquisition capability
+target delivery method
+current application isolation / footprint
+runtime health contract
+route / exposure mechanism
+final workstation/browser verification
+```
+
+For each material row distinguish:
+
+```text
+evidence source
+execution location / credential context
+PROVEN / UNKNOWN / BLOCKED / NOT APPLICABLE
+missing fact or prerequisite
+exact consequential gate, if any
+effect on the requested endpoint
+```
+
+Architecture is a portability fact, not an operating-system stereotype. For example, an ARM64 workstation targeting a Linux/x86-64 environment must surface the required artifact platform explicitly; do not label that generically as a macOS defect.
+
+Do not report `ENVIRONMENT READY TO DEPLOY` for the first real application while its actual artifact build/publication/acquisition path is still hypothetical. Target/platform readiness and application-deployment readiness are different dimensions.
+
+Keep these evidence dimensions separate in status language:
+
+```text
+static/review correctness
+live external-contract confidence
+credential capability in the exact execution context
+immutable artifact provenance
+environment/runtime readiness
+route state
+workstation/browser validation
+human access confirmation
+formal work-item acceptance
+```
+
+A green result in one dimension never proves another.
+
+### Credential capability and lifecycle
+
+Reason from **operation + execution context**, not from the existence of a generic token or successful access somewhere else. When installed tooling exposes structured registry capability evidence, preserve fields such as execution location, credential context, capability proved, and `doesNotProve` rather than paraphrasing a target result as workstation access.
+
+Before asking the developer to create or rotate a credential, explain non-secret lifecycle facts first:
+
+```text
+purpose / capability
+machine, workflow, or process where it is used
+where the credential will be stored
+whether its value can be retrieved again
+rotation/regeneration impact on existing consumers
+value must remain in the local/provider secret surface, never chat
+```
+
+Do not assume registry transport access proves package-metadata API access, that target registry access proves workstation access, or that a workstation login proves an Actions workflow capability. Provider-specific token types, scopes, and error-body strings belong to installed/provider-owned adapters or Project evidence, not generic Core invention.
+
+## 4. Placement branches
 
 ### A. Workstation placement
 
@@ -188,7 +259,7 @@ DEPLOYMENT INTENTIONALLY DEFERRED
 
 Do not mark workspace readiness failed. Route to `/setup <environment>` or `/setup remote` if the developer later wants to bind it.
 
-## 4. Shared failure domains / colocated environments
+## 5. Shared failure domains / colocated environments
 
 Multiple logical environments may share physical failure domains, but they remain independently targetable and independently authorized. If environments share physical failure, state it explicitly.
 
@@ -196,7 +267,7 @@ A clear application isolation preflight means the current Deployment Kit-managed
 
 Colocation does not demonstrate host-level Production isolation. Never infer readiness for one logical environment from another merely because they share hardware.
 
-## 5. State-driven cadence
+## 6. State-driven cadence
 
 Normal cadence is:
 
@@ -205,6 +276,7 @@ select exact project-defined environment
 → read current topology
 → reuse fresh environment-proof evidence when valid
 → rediscover placement-relevant local state
+→ for first real deployment, assess the complete artifact/credential/delivery/route/endpoint path
 → verify current application isolation when the installed adapter supports it
 → verify/repair only missing prerequisites under exact gates
 → ENVIRONMENT READY TO DEPLOY
@@ -213,7 +285,9 @@ select exact project-defined environment
 
 For remote placement, reuse valid existing target access rather than creating duplicate credentials simply because another Project/environment uses the same machine.
 
-## 6. Read-only status
+When a bounded engineering/delivery correction completes in the same conversation and the developer's deployment outcome is still clear, automatically resume safe read-only readiness reconstruction from current repository/tool evidence. Do not require the developer to type `/deployment-readiness` again merely as navigation. This continuation does not reuse an exhausted write authorization and does not authorize a new registry, Production, route, migration, merge, or other consequential write.
+
+## 7. Read-only status
 
 `/deployment-readiness status [environment]` performs no remote writes. Without a specific environment, summarize all known environments from project topology, including Placement and deferred state where evidenced.
 
@@ -229,7 +303,7 @@ Archive       demo         deferred       NOT APPLICABLE           DEFERRED
 
 Do not manufacture target/provider facts for deferred environments.
 
-## 7. Bounded readiness writes
+## 8. Bounded readiness writes
 
 A missing prerequisite is not authorization to change it. Use the repository/tool's exact authorization phrase for key/trust/platform/provider mutations.
 
@@ -237,21 +311,23 @@ Do not hide the real application deployment inside readiness. Readiness may rely
 
 The application isolation preflight itself is read-only and does not authorize later deployment, route, persistence, migration, Production, or destructive writes.
 
-## 8. Pre-deploy versus post-deploy evidence
+## 9. Pre-deploy versus post-deploy evidence
 
 Readiness asks whether `/deploy <name>` can safely perform the real application deployment now.
 
-Pre-deploy evidence may include topology, adapter availability, binding, local/remote identity and access, target platform, fresh proof evidence, artifact policy, deterministic application isolation/collision evidence, route/port availability, persistence/backup/migration prerequisites, lock/recovery capability, and Production-specific safeguards.
+Pre-deploy evidence may include topology, adapter availability, binding, local/remote identity and access, target platform, fresh proof evidence, artifact policy, actual artifact acquisition/publication capability when material, deterministic application isolation/collision evidence, route/port availability, persistence/backup/migration prerequisites, lock/recovery capability, and Production-specific safeguards.
 
 Do not require first-deployment live route, deployed-release identity, application health, or smoke evidence before the application has ever been deployed. Those are post-deploy validation evidence owned by `/deploy`.
 
-## 9. Production policy
+The intended endpoint may still be known before deployment. When the route does not yet exist, label it explicitly `NOT ACTIVE — ROUTE PENDING`; do not invite the developer to test it as though readiness had made it reachable.
+
+## 10. Production policy
 
 Production is logical policy, not hardware count and not the literal name `production`. A named environment such as `prod-east` with purpose `production` must retain Production readiness and later deployment gates.
 
 Readiness never authorizes Production application deployment.
 
-## 10. Final handoff
+## 11. Final handoff
 
 When pre-deploy requirements are satisfied:
 
@@ -263,10 +339,14 @@ Purpose: <purpose>
 Placement: <...>
 Binding: VERIFIED / LOCAL / provider-specific
 This-workstation environment proof: PROVEN / NOT REQUIRED / NOT AVAILABLE
+Artifact path: PROVEN / NOT APPLICABLE
+Credential contexts: PROVEN / NOT APPLICABLE
 Application isolation: CLEAR / NOT APPLICABLE
 Isolation evidence: <evidenceSha256 when exposed by installed tooling>
 Platform prerequisites: READY
 Application-specific prerequisites: READY / <remaining items>
+Expected endpoint: <URL/route when known>
+Endpoint state: NOT ACTIVE — ROUTE PENDING / LOOPBACK PENDING / provider-specific
 Security blockers: NONE
 
 POST-DEPLOY VALIDATION PENDING

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

@@ -12,6 +12,7 @@ from .app_deployment import (
     apply_app_deploy,
     apply_app_deploy_from_workstation,
     plan_app_deploy,
+    plan_app_rollout,
 )
 from .app_runtime import (
     APP_DEPLOY_WRITE_PHRASE,
@@ -85,6 +86,29 @@ def _add_isolation_footprint(parser: argparse.ArgumentParser) -> None:
     )
 
 
+def _add_runtime_contract(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--image", required=True)
+    parser.add_argument("--health-path", required=True)
+    parser.add_argument("--run-as", required=True)
+    parser.add_argument("--data-container-path")
+    parser.add_argument(
+        "--env",
+        action="append",
+        default=[],
+        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
+    )
+    parser.add_argument(
+        "--image-source",
+        choices=("remote-registry", "workstation"),
+        default="remote-registry",
+        help=(
+            "remote-registry preserves the existing target-side pull path; workstation streams an exact local image "
+            "over verified SSH so the target does not need registry credentials"
+        ),
+    )
+    parser.add_argument("--json", action="store_true")
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="project-forge-deploy app")
     sub = parser.add_subparsers(dest="command", required=True)
@@ -108,31 +132,19 @@ def build_parser() -> argparse.ArgumentParser:
     )
     isolation.add_argument("--json", action="store_true")
 
+    rollout = sub.add_parser(
+        "rollout",
+        help="Preview application runtime and owned route as one read-only staged rollout",
+    )
+    _add_isolation_footprint(rollout)
+    _add_runtime_contract(rollout)
+
     deploy = sub.add_parser(
         "deploy",
         help="Deploy one immutable application runtime without modifying routes",
     )
     _add_isolation_footprint(deploy)
-    deploy.add_argument("--image", required=True)
-    deploy.add_argument("--health-path", required=True)
-    deploy.add_argument("--run-as", required=True)
-    deploy.add_argument("--data-container-path")
-    deploy.add_argument(
-        "--env",
-        action="append",
-        default=[],
-        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
-    )
-    deploy.add_argument(
-        "--image-source",
-        choices=("remote-registry", "workstation"),
-        default="remote-registry",
-        help=(
-            "remote-registry preserves the existing target-side pull path; workstation streams an exact local image "
-            "over verified SSH so the target does not need registry credentials"
-        ),
-    )
-    deploy.add_argument("--json", action="store_true")
+    _add_runtime_contract(deploy)
     deploy.add_argument("--yes", action="store_true")
     return parser
 
@@ -175,6 +187,20 @@ def main(argv: list[str] | None = None) -> int:
             environment_variables=_parse_env(args.env),
         )
         assert_app_spec_matches_persistence(args.name, spec)
+
+        if args.command == "rollout":
+            rollout_plan = plan_app_rollout(
+                args.name,
+                spec,
+                production=production_classified,
+                database_file=args.database_file,
+                route_hostnames=args.route_hostname,
+            )
+            rollout_plan["imageSource"] = args.image_source
+            rollout_plan["targetRegistryCredentialRequired"] = args.image_source == "remote-registry"
+            _print(rollout_plan, as_json=args.json)
+            return 0
+
         plan = plan_app_deploy(
             args.name,
             spec,

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

@@ -10,15 +10,19 @@ from __future__ import annotations
 
 from typing import Any, Iterable
 
+from .app_runtime import PRODUCTION_APP_DEPLOY_WRITE_PHRASE
 from .app_runtime import apply_app_deploy as _apply_runtime_deploy
+from .app_runtime import deploy_write_phrase
 from .app_runtime import plan_app_deploy as _plan_runtime_deploy
 from .app_runtime_workstation import apply_app_deploy_with_preloaded_image
 from .environment_isolation import environment_isolation_preflight
 from .errors import DeploymentKitError
 from .image_transfer import transfer_image
+from .route_registry import ROUTE_WRITE_PHRASE, plan_route_registration
 
 
 ISOLATION_REVIEW_KEY = "isolationReview"
+ROLLOUT_SCHEMA_VERSION = 1
 
 
 def app_isolation_check(
@@ -139,6 +143,100 @@ def plan_app_deploy(
     return plan
 
 
+def _endpoint_states(route_plan: dict[str, Any] | None) -> dict[str, str]:
+    if route_plan is None:
+        return {
+            "beforeRuntime": "NO_ROUTE_REQUESTED",
+            "afterRuntimeBeforeRoute": "NO_ROUTE_REQUESTED",
+            "afterRoute": "NO_ROUTE_REQUESTED",
+        }
+    if route_plan["changeType"] == "create":
+        before = "NOT_ACTIVE_ROUTE_ABSENT"
+        after_runtime = "NOT_ACTIVE_ROUTE_PENDING"
+    else:
+        before = "ROUTE_PRESENT_RUNTIME_STATE_NOT_VALIDATED"
+        after_runtime = "ROUTE_PRESENT_ROUTE_CHANGE_PENDING"
+    return {
+        "beforeRuntime": before,
+        "afterRuntimeBeforeRoute": after_runtime,
+        "afterRoute": "ROUTE_REGISTERED_BROWSER_VERIFICATION_PENDING",
+    }
+
+
+def plan_app_rollout(
+    target_name: str,
+    spec: dict[str, Any],
+    *,
+    production: bool = False,
+    database_file: str | None = None,
+    route_hostnames: Iterable[str] | None = None,
+) -> dict[str, Any]:
+    """Compose read-only runtime and route plans into one staged rollout preview."""
+
+    hosts = list(route_hostnames or [])
+    app_plan = plan_app_deploy(
+        target_name,
+        spec,
+        production=production,
+        database_file=database_file,
+        route_hostnames=hosts,
+    )
+    route_plan = None
+    if hosts:
+        route_plan = plan_route_registration(
+            target_name,
+            owner_repo=spec["ownerRepo"],
+            environment=spec["environment"],
+            app_slug=spec["appSlug"],
+            upstream_container=spec["containerName"],
+            upstream_port=spec["runtimePort"],
+            hostnames=hosts,
+        )
+
+    runtime_authorization = (
+        PRODUCTION_APP_DEPLOY_WRITE_PHRASE
+        if production or spec["environment"] == "production"
+        else deploy_write_phrase(app_plan)
+    )
+    stages = [
+        {
+            "stage": "runtime",
+            "action": "deploy-application-runtime",
+            "requiredAuthorization": runtime_authorization,
+            "mutated": False,
+        }
+    ]
+    if route_plan is not None:
+        stages.append(
+            {
+                "stage": "route",
+                "action": "register-application-route",
+                "requiredAuthorization": ROUTE_WRITE_PHRASE,
+                "mutated": False,
+            }
+        )
+
+    runtime_view = {key: value for key, value in app_plan.items() if key != "spec"}
+    return {
+        "schemaVersion": ROLLOUT_SCHEMA_VERSION,
+        "targetName": target_name,
+        "environment": spec["environment"],
+        "production": bool(production or spec["environment"] == "production"),
+        "image": spec["image"],
+        "runtimePlan": runtime_view,
+        "routePlan": route_plan,
+        "stages": stages,
+        "separateAuthorizationsRequired": route_plan is not None,
+        "endpointState": _endpoint_states(route_plan),
+        "postRouteVerification": (
+            ["application-health", "route-http", "workstation-browser"]
+            if route_plan is not None
+            else ["application-health"]
+        ),
+        "mutated": False,
+    }
+
+
 def revalidate_app_isolation(plan: dict[str, Any]) -> dict[str, Any]:
     """Recheck the reviewed application footprint immediately before mutation."""
 
@@ -186,9 +284,11 @@ def apply_app_deploy_from_workstation(plan: dict[str, Any]) -> dict[str, Any]:
 
 __all__ = [
     "ISOLATION_REVIEW_KEY",
+    "ROLLOUT_SCHEMA_VERSION",
     "app_isolation_check",
     "apply_app_deploy",
     "apply_app_deploy_from_workstation",
     "plan_app_deploy",
+    "plan_app_rollout",
     "revalidate_app_isolation",
 ]

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

@@ -1,7 +1,8 @@
-"""Read-only exact-image registry access verification for logical targets."""
+"""Read-only exact-image registry capability verification by execution context."""
 
 from __future__ import annotations
 
+import os
 import re
 import shlex
 import subprocess
@@ -13,6 +14,17 @@ from .ssh import ssh_args, verify_access
 
 
 _IMAGE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/:+-]*@sha256:[0-9a-f]{64}$")
+_REMOTE_DOES_NOT_PROVE = [
+    "workstation-registry-access",
+    "workstation-image-pull",
+    "actions-registry-transport",
+    "package-metadata-api-access",
+]
+_WORKSTATION_DOES_NOT_PROVE = [
+    "remote-target-registry-access",
+    "actions-registry-transport",
+    "package-metadata-api-access",
+]
 
 _REMOTE_SCRIPT = r'''#!/usr/bin/env bash
 set -Eeuo pipefail
@@ -61,6 +73,14 @@ printf 'ACCESS\t%s\n' "$credential_state"
 '''
 
 
+class RegistryCapabilityError(DeploymentKitError):
+    """Fail-closed registry capability error with safe structured evidence."""
+
+    def __init__(self, message: str, result: dict[str, Any]) -> None:
+        super().__init__(message)
+        self.result = result
+
+
 def normalize_registry_image(value: str) -> str:
     if not isinstance(value, str) or _IMAGE_RE.fullmatch(value) is None:
         raise DeploymentKitError(
@@ -83,13 +103,55 @@ def _parse_access(output: str) -> str:
     return parts[1]
 
 
+def _remote_failure_result(
+    *,
+    name: str,
+    image: str,
+    address: str,
+    returncode: int,
+) -> dict[str, Any]:
+    failure_codes = {
+        42: "docker-cli-unavailable",
+        43: "credential-config-unsafe",
+        44: "manifest-access-failed",
+    }
+    return {
+        "status": "failed",
+        "executionLocation": "remote-target",
+        "targetName": name,
+        "verifiedAddress": address,
+        "capabilityAttempted": "registry-manifest-read",
+        "image": image,
+        "failureCode": failure_codes.get(returncode, "remote-command-failed"),
+        "doesNotProve": list(_REMOTE_DOES_NOT_PROVE),
+        "mutated": False,
+    }
+
+
+def _workstation_failure_result(*, image: str, failure_code: str) -> dict[str, Any]:
+    return {
+        "status": "failed",
+        "executionLocation": "workstation",
+        "credentialContext": "workstation-docker-client",
+        "dockerConfigSource": "explicit-environment" if os.environ.get("DOCKER_CONFIG") else "default",
+        "capabilityAttempted": "registry-manifest-read",
+        "image": image,
+        "failureCode": failure_code,
+        "doesNotProve": list(_WORKSTATION_DOES_NOT_PROVE),
+        "mutated": False,
+    }
+
+
 def verify_registry_access(name: str, image: str) -> dict[str, Any]:
+    """Verify exact-image manifest access from the named remote target."""
+
     exact_image = normalize_registry_image(image)
     profile = load_profile(name)
     access = verify_access(profile)
+    address = access["address"]
     command = ssh_args(
         profile,
-        access["address"],
+        address,
         command="bash -s -- " + shlex.quote(exact_image),
     )
     completed = subprocess.run(
@@ -99,16 +161,84 @@ def verify_registry_access(name: str, image: str) -> dict[str, Any]:
         capture_output=True,
     )
     stdout = completed.stdout.decode("utf-8", errors="replace")
-    stderr = completed.stderr.decode("utf-8", errors="replace")
     if completed.returncode != 0:
-        detail = stderr.strip() or stdout.strip() or f"exit {completed.returncode}"
-        raise DeploymentKitError(f"Read-only registry access verification failed: {detail}")
+        result = _remote_failure_result(
+            name=name,
+            image=exact_image,
+            address=address,
+            returncode=completed.returncode,
+        )
+        raise RegistryCapabilityError(
+            f"Remote-target registry capability check failed ({result['failureCode']}).",
+            result,
+        )
 
     credential_state = _parse_access(stdout)
     return {
+        "status": "verified",
+        "executionLocation": "remote-target",
         "targetName": name,
+        "verifiedAddress": address,
+        "credentialContext": (
+            "target-docker-config" if credential_state == "protected" else "target-anonymous"
+        ),
+        "capabilityProved": "registry-manifest-read",
         "image": exact_image,
         "manifestAccess": "verified",
         "credentialConfig": credential_state,
+        "doesNotProve": list(_REMOTE_DOES_NOT_PROVE),
         "mutated": False,
     }
+
+
+def verify_workstation_registry_access(image: str) -> dict[str, Any]:
+    """Verify exact-image manifest access from this workstation without pulling."""
+
+    exact_image = normalize_registry_image(image)
+    command = ["docker", "manifest", "inspect", exact_image]
+    try:
+        completed = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+        )
+    except FileNotFoundError as error:
+        result = _workstation_failure_result(
+            image=exact_image,
+            failure_code="docker-cli-unavailable",
+        )
+        raise RegistryCapabilityError(
+            "Workstation registry capability check failed (docker-cli-unavailable).",
+            result,
+        ) from error
+
+    if completed.returncode != 0:
+        result = _workstation_failure_result(
+            image=exact_image,
+            failure_code="manifest-access-failed",
+        )
+        raise RegistryCapabilityError(
+            "Workstation registry capability check failed (manifest-access-failed).",
+            result,
+        )
+
+    return {
+        "status": "verified",
+        "executionLocation": "workstation",
+        "credentialContext": "workstation-docker-client",
+        "dockerConfigSource": "explicit-environment" if os.environ.get("DOCKER_CONFIG") else "default",
+        "capabilityProved": "registry-manifest-read",
+        "image": exact_image,
+        "manifestAccess": "verified",
+        "doesNotProve": list(_WORKSTATION_DOES_NOT_PROVE),
+        "mutated": False,
+    }
+
+
+__all__ = [
+    "RegistryCapabilityError",
+    "build_remote_script",
+    "normalize_registry_image",
+    "verify_registry_access",
+    "verify_workstation_registry_access",
+]

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

@@ -1,4 +1,4 @@
-"""CLI for read-only registry access verification."""
+"""CLI for read-only registry capability verification."""
 
 from __future__ import annotations
 
@@ -8,7 +8,11 @@ import sys
 from typing import Any
 
 from .errors import DeploymentKitError
-from .registry_access import verify_registry_access
+from .registry_access import (
+    RegistryCapabilityError,
+    verify_registry_access,
+    verify_workstation_registry_access,
+)
 
 
 def _print(value: Any, *, as_json: bool) -> None:
@@ -28,11 +32,24 @@ def build_parser() -> argparse.ArgumentParser:
 
     verify = sub.add_parser(
         "verify",
-        help="Verify exact-image registry manifest access without pulling or modifying target state",
+        help=(
+            "Verify exact-image registry manifest access on the named remote target without pulling "
+            "or modifying target state"
+        ),
     )
-    verify.add_argument("name")
+    verify.add_argument("name", help="Named remote target profile")
     verify.add_argument("--image", required=True)
     verify.add_argument("--json", action="store_true")
+
+    verify_workstation = sub.add_parser(
+        "verify-workstation",
+        help=(
+            "Verify exact-image registry manifest access from this workstation without pulling "
+            "or modifying target state"
+        ),
+    )
+    verify_workstation.add_argument("--image", required=True)
+    verify_workstation.add_argument("--json", action="store_true")
     return parser
 
 
@@ -45,6 +62,18 @@ def main(argv: list[str] | None = None) -> int:
                 as_json=args.json,
             )
             return 0
+        if args.command == "verify-workstation":
+            _print(
+                verify_workstation_registry_access(args.image),
+                as_json=args.json,
+            )
+            return 0
+    except RegistryCapabilityError as error:
+        if getattr(args, "json", False):
+            _print(error.result, as_json=True)
+        else:
+            print(f"ERROR: {error}", file=sys.stderr)
+        return 2
     except DeploymentKitError as error:
         print(f"ERROR: {error}", file=sys.stderr)
         return 2

package/package.json

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