fix: align 22 showcases with AkôFlow engine contract

agentic-workflows/bounded-agent/README.md

@@ -1,14 +1,85 @@
 # Bounded Agent
 
-A reproducible AkôFlow showcase. It executes a real Docker image locally, writes deterministic artifacts, captures three browser screenshots, and validates its output contract.
+A reproducible AkôFlow showcase. It executes a real Docker image locally, writes deterministic artifacts, validates its output contract, and includes four versioned screenshots captured from a completed AkôFlow engine run.
 
 ## Run
 
 ```sh
 ./run.sh
 ```
 
-Requires Docker, Node.js, and a Playwright-compatible Chromium installation (the screenshot command provisions it when needed). The workflow graph is in [workflow.yaml](./workflow.yaml); the expected contract is in [expected/manifest.json](./expected/manifest.json).
+Requires Python 3 for the standalone smoke test and Docker for execution through AkôFlow. The workflow graph is in [workflow.yaml](./workflow.yaml); the expected contract is in [expected/manifest.json](./expected/manifest.json).
 
-Published image: `ghcr.io/uffescience/akoflow-showcase-bounded-agent:v1`.
+Published image: `ghcr.io/uffescience/akoflow-examples/showcase-bounded-agent:v1`.
 
+
+## Run locally step by step
+
+### 1. Check the prerequisites
+
+Install Python 3, Docker, and a local AkôFlow server/Desktop. Set the local API connection, then confirm every prerequisite:
+
+```sh
+export AKOFLOW_API_URL=http://127.0.0.1:8080/akoflow-api
+export AKOFLOW_API_TOKEN=akoflow-development-token
+
+python3 --version
+docker version
+curl --fail -H "Authorization: Bearer $AKOFLOW_API_TOKEN" "$AKOFLOW_API_URL/health/"
+```
+
+### 2. Run the deterministic smoke test
+
+From this showcase directory:
+
+```sh
+./run.sh
+```
+
+The command recreates `outputs/`, runs the complete deterministic scenario, and validates every artifact declared in `expected/manifest.json`.
+
+### 3. Build the image used by the workflow
+
+```sh
+IMAGE=$(sed -n 's/^[[:space:]]*image: //p' workflow.yaml | head -n 1)
+docker build -f docker/Dockerfile -t "$IMAGE" .
+```
+
+The workflow command is authoritative. The image intentionally has no competing `ENTRYPOINT`.
+
+### 4. Register the local infrastructure and workflow
+
+```sh
+for item in "environments environment.yaml" "execution-scopes scope.yaml" "network-topologies topology.yaml" "workflow-definitions workflow.yaml"
+do
+  set -- $item
+  curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" -H 'Content-Type: application/yaml' --data-binary "@$2" "$AKOFLOW_API_URL/$1/"
+done
+```
+
+The order matters: the execution scope references the environment version, the topology references the scope, and the workflow references its namespaced local runtime.
+
+### 5. Plan and execute in AkôFlow Desktop
+
+1. Open **Workflows → Definitions** and select this showcase.
+2. Choose **Generate plan**.
+3. Select the execution scope imported from `scope.yaml`.
+4. Run **HEFT** and select its feasible candidate.
+5. Choose **Execute plan** and confirm **Real execution**.
+6. Wait until the run is `completed` and every activity is settled.
+
+### 6. Verify the result
+
+Open the completed run and inspect:
+
+- **Activities** for the engine-rendered DAG and per-activity status;
+- **Workflow** for the observed execution lifecycle and timing decomposition;
+- **Data** for workspace transfers;
+- the final activity's **Generated files** table for file names, sizes, and SHA-256 checksums.
+
+The versioned evidence is stored in `screenshots/`:
+
+- `workflow.png`: completed activity DAG;
+- `execution.png`: observed execution lifecycle and timing decomposition;
+- `outputs.png`: data transfers between activity workspaces;
+- `generated-files.png`: files observed in the final output-producing activity.

agentic-workflows/bounded-agent/docker/Dockerfile

@@ -2,5 +2,4 @@ FROM python:3.12-slim
 WORKDIR /app
 COPY data/input.json scenario.json
 COPY scripts/run_showcase.py /app/run_showcase.py
-ENTRYPOINT ["python", "/app/run_showcase.py"]
 

agentic-workflows/bounded-agent/environment.yaml

@@ -14,14 +14,14 @@ version:
   configurationHash: showcase-bounded-agent-v1
 runtimes:
   - environmentVersionId: showcase-bounded-agent-v1
-    id: local
+    id: showcase-bounded-agent-local
     name: Local Docker host
     driver: local
     mode: execution
     role: compute
     capabilities: {batch: true, container: true}
 resources:
-  - id: local-docker
+  - id: showcase-bounded-agent-local-docker
     environmentVersionId: showcase-bounded-agent-v1
     type: machine
     name: Local Docker host
@@ -39,5 +39,5 @@ storages: []
 connections: []
 activityResourceProfiles: []
 resourceRuntimeBindings:
-  - {resourceId: local-docker, runtimeId: local, enabled: true}
+  - {resourceId: showcase-bounded-agent-local-docker, runtimeId: showcase-bounded-agent-local, enabled: true}
 

agentic-workflows/bounded-agent/run.sh

@@ -1,8 +1,7 @@
 #!/bin/sh
 set -eu
 root=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-rm -rf "$root/outputs" "$root/screenshots"
-mkdir -p "$root/outputs" "$root/screenshots"
+rm -rf "$root/outputs"
+mkdir -p "$root/outputs"
 python3 "$root/scripts/run_showcase.py" --output "$root/outputs"
-node "$root/scripts/capture_screenshots.mjs"
 "$root/validate.sh"

agentic-workflows/bounded-agent/scripts/validate.py

@@ -12,7 +12,7 @@
 missing = [name for name in expected["artifacts"] if not (root / "outputs" / name).is_file()]
 if missing:
     sys.exit("missing artifacts: " + ", ".join(missing))
-missing = [name for name in ("workflow.png", "execution.png", "outputs.png") if not (root / "screenshots" / name).is_file()]
+missing = [name for name in ("workflow.png", "execution.png", "outputs.png", "generated-files.png") if not (root / "screenshots" / name).is_file()]
 if missing:
     sys.exit("missing screenshots: " + ", ".join(missing))
 print("validated " + expected["showcase"])

agentic-workflows/bounded-agent/workflow.yaml

@@ -5,29 +5,26 @@ spec:
   image: ghcr.io/uffescience/akoflow-examples/showcase-bounded-agent:v1
   activities:
     - name: goal
-      runtime: local
+      runtime: showcase-bounded-agent-local
       command:
         entrypoint: python
         arguments: ["/app/run_showcase.py", "--stage", "goal", "--output", "."]
-        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
     - name: agent
-      runtime: local
+      runtime: showcase-bounded-agent-local
       command:
         entrypoint: python
         arguments: ["/app/run_showcase.py", "--stage", "agent", "--output", "."]
-        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:
         - goal
     - name: validator
-      runtime: local
+      runtime: showcase-bounded-agent-local
       command:
         entrypoint: python
         arguments: ["/app/run_showcase.py", "--stage", "validator", "--output", "."]
-        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:

agentic-workflows/multi-agent-review/README.md

@@ -1,14 +1,85 @@
 # Multi-Agent Review
 
-A reproducible AkôFlow showcase. It executes a real Docker image locally, writes deterministic artifacts, captures three browser screenshots, and validates its output contract.
+A reproducible AkôFlow showcase. It executes a real Docker image locally, writes deterministic artifacts, validates its output contract, and includes four versioned screenshots captured from a completed AkôFlow engine run.
 
 ## Run
 
 ```sh
 ./run.sh
 ```
 
-Requires Docker, Node.js, and a Playwright-compatible Chromium installation (the screenshot command provisions it when needed). The workflow graph is in [workflow.yaml](./workflow.yaml); the expected contract is in [expected/manifest.json](./expected/manifest.json).
+Requires Python 3 for the standalone smoke test and Docker for execution through AkôFlow. The workflow graph is in [workflow.yaml](./workflow.yaml); the expected contract is in [expected/manifest.json](./expected/manifest.json).
 
-Published image: `ghcr.io/uffescience/akoflow-showcase-multi-agent-review:v1`.
+Published image: `ghcr.io/uffescience/akoflow-examples/showcase-multi-agent-review:v1`.
 
+
+## Run locally step by step
+
+### 1. Check the prerequisites
+
+Install Python 3, Docker, and a local AkôFlow server/Desktop. Set the local API connection, then confirm every prerequisite:
+
+```sh
+export AKOFLOW_API_URL=http://127.0.0.1:8080/akoflow-api
+export AKOFLOW_API_TOKEN=akoflow-development-token
+
+python3 --version
+docker version
+curl --fail -H "Authorization: Bearer $AKOFLOW_API_TOKEN" "$AKOFLOW_API_URL/health/"
+```
+
+### 2. Run the deterministic smoke test
+
+From this showcase directory:
+
+```sh
+./run.sh
+```
+
+The command recreates `outputs/`, runs the complete deterministic scenario, and validates every artifact declared in `expected/manifest.json`.
+
+### 3. Build the image used by the workflow
+
+```sh
+IMAGE=$(sed -n 's/^[[:space:]]*image: //p' workflow.yaml | head -n 1)
+docker build -f docker/Dockerfile -t "$IMAGE" .
+```
+
+The workflow command is authoritative. The image intentionally has no competing `ENTRYPOINT`.
+
+### 4. Register the local infrastructure and workflow
+
+```sh
+for item in "environments environment.yaml" "execution-scopes scope.yaml" "network-topologies topology.yaml" "workflow-definitions workflow.yaml"
+do
+  set -- $item
+  curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" -H 'Content-Type: application/yaml' --data-binary "@$2" "$AKOFLOW_API_URL/$1/"
+done
+```
+
+The order matters: the execution scope references the environment version, the topology references the scope, and the workflow references its namespaced local runtime.
+
+### 5. Plan and execute in AkôFlow Desktop
+
+1. Open **Workflows → Definitions** and select this showcase.
+2. Choose **Generate plan**.
+3. Select the execution scope imported from `scope.yaml`.
+4. Run **HEFT** and select its feasible candidate.
+5. Choose **Execute plan** and confirm **Real execution**.
+6. Wait until the run is `completed` and every activity is settled.
+
+### 6. Verify the result
+
+Open the completed run and inspect:
+
+- **Activities** for the engine-rendered DAG and per-activity status;
+- **Workflow** for the observed execution lifecycle and timing decomposition;
+- **Data** for workspace transfers;
+- the final activity's **Generated files** table for file names, sizes, and SHA-256 checksums.
+
+The versioned evidence is stored in `screenshots/`:
+
+- `workflow.png`: completed activity DAG;
+- `execution.png`: observed execution lifecycle and timing decomposition;
+- `outputs.png`: data transfers between activity workspaces;
+- `generated-files.png`: files observed in the final output-producing activity.

agentic-workflows/multi-agent-review/docker/Dockerfile

@@ -2,5 +2,4 @@ FROM python:3.12-slim
 WORKDIR /app
 COPY data/input.json scenario.json
 COPY scripts/run_showcase.py /app/run_showcase.py
-ENTRYPOINT ["python", "/app/run_showcase.py"]
 

agentic-workflows/multi-agent-review/environment.yaml

@@ -14,14 +14,14 @@ version:
   configurationHash: showcase-multi-agent-review-v1
 runtimes:
   - environmentVersionId: showcase-multi-agent-review-v1
-    id: local
+    id: showcase-multi-agent-review-local
     name: Local Docker host
     driver: local
     mode: execution
     role: compute
     capabilities: {batch: true, container: true}
 resources:
-  - id: local-docker
+  - id: showcase-multi-agent-review-local-docker
     environmentVersionId: showcase-multi-agent-review-v1
     type: machine
     name: Local Docker host
@@ -39,5 +39,5 @@ storages: []
 connections: []
 activityResourceProfiles: []
 resourceRuntimeBindings:
-  - {resourceId: local-docker, runtimeId: local, enabled: true}
+  - {resourceId: showcase-multi-agent-review-local-docker, runtimeId: showcase-multi-agent-review-local, enabled: true}
 

agentic-workflows/multi-agent-review/run.sh

@@ -1,8 +1,7 @@
 #!/bin/sh
 set -eu
 root=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
-rm -rf "$root/outputs" "$root/screenshots"
-mkdir -p "$root/outputs" "$root/screenshots"
+rm -rf "$root/outputs"
+mkdir -p "$root/outputs"
 python3 "$root/scripts/run_showcase.py" --output "$root/outputs"
-node "$root/scripts/capture_screenshots.mjs"
 "$root/validate.sh"

agentic-workflows/multi-agent-review/scripts/validate.py

@@ -12,7 +12,7 @@
 missing = [name for name in expected["artifacts"] if not (root / "outputs" / name).is_file()]
 if missing:
     sys.exit("missing artifacts: " + ", ".join(missing))
-missing = [name for name in ("workflow.png", "execution.png", "outputs.png") if not (root / "screenshots" / name).is_file()]
+missing = [name for name in ("workflow.png", "execution.png", "outputs.png", "generated-files.png") if not (root / "screenshots" / name).is_file()]
 if missing:
     sys.exit("missing screenshots: " + ", ".join(missing))
 print("validated " + expected["showcase"])

agentic-workflows/multi-agent-review/workflow.yaml

@@ -5,39 +5,35 @@ spec:
   image: ghcr.io/uffescience/akoflow-examples/showcase-multi-agent-review:v1
   activities:
     - name: researcher
-      runtime: local
+      runtime: showcase-multi-agent-review-local
       command:
         entrypoint: python
         arguments: ["/app/run_showcase.py", "--stage", "researcher", "--output", "."]
-        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
     - name: reviewer
-      runtime: local
+      runtime: showcase-multi-agent-review-local
       command:
         entrypoint: python
         arguments: ["/app/run_showcase.py", "--stage", "reviewer", "--output", "."]
-        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:
         - researcher
     - name: critic
-      runtime: local
+      runtime: showcase-multi-agent-review-local
       command:
         entrypoint: python
         arguments: ["/app/run_showcase.py", "--stage", "critic", "--output", "."]
-        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn:
         - reviewer
     - name: synthesis
-      runtime: local
+      runtime: showcase-multi-agent-review-local
       command:
         entrypoint: python
         arguments: ["/app/run_showcase.py", "--stage", "synthesis", "--output", "."]
-        workingDirectory: /workspace
       cpuLimit: "1"
       memoryLimit: 256Mi
       dependsOn: