})
+})
-*The diagram groups responsibilities rather than deployment units. AkôFlow is one daemon with application services and adapters; the cards do not imply separately deployable microservices.*
+A **workflow** is a set of activities with dependencies. For example, `prepare → analyze → summarize` means that analysis waits for preparation and the summary waits for analysis. The workflow describes the work and required data; it does not choose a machine.
-## The record chain
+An **environment** describes where work could run: a local host, a modeled simulation platform, a Kubernetes cluster, or an HPC system. Its **resources** are the available machines or capacity. An **execution scope** limits which environment versions and network links a planning experiment can use.
-})
-The plan retains predicted makespan and cost. Each task attempt records its planned and allocated resource, runtime, queue, transfer, interference, and overhead timing where available. The execution trace combines task and transfer observations into observed metrics. A completed trace marks the observed result feasible; it does not certify that the prediction was accurate.
+The plan retains predicted duration and cost. A task attempt can record its planned and actual resource, runtime, queue time, transfers, and startup time, depending on what the runtime reports. The execution trace combines these observations into run metrics. A completed run does not mean the prediction was accurate.
-## Evidence follows the runtime boundary
+## What the run records
-The supervisor persists a runtime handle after starting an activity. The handle can identify a process, Kubernetes Job, Docker container, Slurm job, or simulation event without exposing provider-specific formats to the rest of the control plane. Reinspection uses that saved handle during recovery.
+In real execution, a runtime handle identifies a started process, container, Kubernetes Job, or Slurm job for later status checks. A simulated run records modeled task timing without a provider job to inspect.
-Data preparation and output observation are evidence too. Transfer records can capture the route and actual bytes moved. Artifact manifests capture created or changed workspace files where the adapter supports observation. An observation failure can make a zero-exit task untrustworthy when outputs are required.
+Transfer records can show how data reached a task and how many bytes moved. Where the runtime supports it, artifact records show files created or changed by the task. If required output observation fails, a task's zero exit code alone does not establish a valid result.
## Lineage and audit answer different questions
**Provenance** connects scientific entities, produced data, their locations, and the workflow activity that created them. It answers questions such as "which run produced this file?" or "which input lineage fed this result?"
-**Audit** records operational and security-relevant actions, such as a user or service changing a record or requesting an operation. It answers "who changed this state and when?" It is not a replacement for data lineage.
+**Audit** currently records connection health checks, resource discovery, and console commands or sessions. It helps answer when those actions ran and whether they succeeded. Console events can include an actor ID; connection and discovery events do not identify who initiated them. Credential changes and workflow operations are not recorded here. Their current records and operation details may show status, but a complete change history is not available through Audit.
## Compare before drawing conclusions
-Compare a selected plan with a completed run at the same scope and execution mode. Check assignments, transfer records, activity attempts, and provider conditions before attributing a makespan gap to the scheduling algorithm. The execution trace reports both wall-clock makespan and accumulated activity-stage totals; [interpreting observed timing](./observed-timing) defines the distinction.
+Compare a selected plan with a completed run at the same scope and execution mode. Check assignments, transfer records, activity attempts, and provider conditions before attributing a makespan gap to the scheduling algorithm. The execution trace reports both wall-clock makespan and accumulated activity-stage totals; [interpreting observed timing](/docs/explanations/observed-timing) defines the distinction.
## Related material
-- [Execution control plane](../engine)
-- [Planning and plans](./planning)
-- [Network modeling](./network-modeling)
-- [Planning and execution state reference](../reference/planning-and-execution-states)
+- [Execution control plane](/docs/engine)
+- [Planning and plans](/docs/explanations/planning)
+- [Network modeling](/docs/explanations/network-modeling)
+- [Planning and execution state reference](/docs/reference/planning-and-execution-states)
diff --git a/docs/docs/explanations/network-modeling.md b/docs/docs/explanations/network-modeling.md
index 90591ae6..ba2ac2c2 100644
--- a/docs/docs/explanations/network-modeling.md
+++ b/docs/docs/explanations/network-modeling.md
@@ -8,9 +8,9 @@ description: How data dependencies, topology links, routes, and observed transfe
import useBaseUrl from '@docusaurus/useBaseUrl';
-Network modeling lets planning distinguish a local dependency from data that must cross a resource boundary. It starts with bytes declared by the workflow, but its result depends on the selected resource assignments and the directed topology included in the execution scope.
+Network modeling lets planning distinguish a local dependency from data that must cross a resource boundary. It starts with bytes declared by the workflow, but its result depends on the selected resource assignments and the directed topology chosen for the planning session.
-This is an explanation of the model. Use [SimGrid modeling](../guides/infrastructure/simgrid) to configure bandwidth and latency, or the [topology reference](../reference/execution-scopes-and-topologies) for the exact document fields.
+This is an explanation of the model. Use [SimGrid modeling](/docs/guides/infrastructure/simgrid) to configure bandwidth and latency, or the [topology reference](/docs/reference/execution-scopes-and-topologies) for the exact document fields.
## From dependency to possible flow
@@ -18,28 +18,30 @@ This is an explanation of the model. Use [SimGrid modeling](../guides/infrastruc
The control dependency makes the consumer wait for the producer. The matching data dependency gives the planner a logical byte volume. If a selected plan puts both activities on the same resource, no network transfer time is added for that edge. If they are on different resources, the topology is consulted for a route.
-The portable workflow importer deliberately requires the matching control edge for data bytes to participate in scheduling. A data declaration without that ordering relationship remains data metadata, not an implicit workflow edge.
+The portable workflow importer uses declared bytes in scheduling only when the same pair of activities also has a control dependency. A data declaration alone does not order the activities.
## What a topology models
A `NetworkLink` is directed. It identifies source and target resources and can carry bandwidth in **bits per second**, latency in seconds, byte price, whether the reverse direction is available, a sharing group, and a transfer concurrency limit. A bidirectional link makes the same link available in reverse; it does not create a second independently configured route.
-PRISM precomputes routes from the frozen topology and includes communication in its candidate evaluation. Its shared-network evaluator can account for known overlapping flows on a route. HEFT's baseline scheduling path uses the direct matching link lookup. Neither behavior alone guarantees that one algorithm will produce the better observed run.
+PRISM precomputes routes from the frozen topology and includes communication in its candidate evaluation. The SimGrid platform and PRISM choose a route by summing each link's latency plus the time to transmit one byte. They apply the full byte volume afterward, so the chosen route may not be fastest for a large transfer.
+
+PRISM can model known overlapping flows on the chosen route and rejects a cross-resource data transfer without one. HEFT's baseline uses a direct matching link; when none exists, it currently estimates zero transfer time. Supply the links needed by your placements rather than treating that estimate as evidence of a free transfer. Neither model guarantees the better observed run.
## Planned route versus executed transfer
-The plan predicts transfer time for each assignment. At execution, preparation selects a concrete strategy such as a verified existing copy, shared storage, destination pull, source push, gateway, runtime-local, or direct-runtime transfer. The resulting transfer observation can record source, target, logical and network bytes, timing, cost, strategy, and route.
+The plan predicts transfer time for each assignment. During execution, AkôFlow may use an existing verified copy, shared storage, or a supported transfer route. The transfer record shows how data became available and, when reported, how many bytes moved and how long it took.
That distinction matters: the model describes a possible network penalty for a placement; the observation says how bytes were actually made available. Shared storage or a verified existing copy may satisfy a dependency without a new network transfer.
## Units and a small example
-For a 10 GiB data dependency over a 10 Gbit/s link, the raw serialization time is roughly eight seconds before latency and sharing. `10 GiB` is a byte volume; `10 Gbit/s` is a bit rate, so the rate is divided by eight before comparing it with bytes. The observed elapsed time can be higher because of setup, route selection, sharing, or provider behavior.
+For a 10 GiB data dependency over a 10 Gbit/s link, the raw serialization time is about 8.6 seconds before latency and sharing. `10 GiB` is a byte volume; `10 Gbit/s` is a bit rate. The observed time can be higher because of setup, routing, sharing, or provider behavior.
-Inspect a completed run's transfer records alongside the assignment and plan prediction. The [30 GB network fan-out Showcase](../showcase/network-fanout) provides a checked-in topology and workflow where these effects are intentional.
+Inspect a completed run's transfer records alongside the assignment and plan prediction. The [30 GB network fan-out Showcase](/docs/showcase/network-fanout) provides a checked-in topology and workflow where these effects are intentional.
## Related material
-- [Workflow simulation semantics](../internal/workflow-spec)
-- [Execution scopes and topologies reference](../reference/execution-scopes-and-topologies)
-- [Plan-versus-observed evidence](./evidence-and-provenance)
+- [Workflow simulation semantics](/docs/internal/workflow-spec)
+- [Execution scopes and topologies reference](/docs/reference/execution-scopes-and-topologies)
+- [Plan-versus-observed evidence](/docs/explanations/evidence-and-provenance)
diff --git a/docs/docs/explanations/observed-timing.md b/docs/docs/explanations/observed-timing.md
index 786bbff9..c4202770 100644
--- a/docs/docs/explanations/observed-timing.md
+++ b/docs/docs/explanations/observed-timing.md
@@ -7,43 +7,34 @@ description: The difference between flows, queue and stage totals, makespan, and
import useBaseUrl from '@docusaurus/useBaseUrl';
-Execution evidence contains both a wall-clock result and accumulated activity
-measurements. They answer different questions. A large accumulated transfer or
-queue total does not by itself mean that the workflow took that many seconds on
-the clock, because activities and transfers can overlap.
+Execution evidence has a wall-clock result and accumulated activity times. Use
+makespan for elapsed workflow time; use the accumulated values to see where work
+and waiting occurred. Activities and transfers can overlap, so their totals can
+exceed makespan.
Use this page when reading a run detail, a planning-versus-execution comparison,
or an experiment chart. It explains the current persisted metrics; it does not
-replace [network modeling](./network-modeling) or the [execution state reference](../reference/planning-and-execution-states).
+replace [network modeling](/docs/explanations/network-modeling) or the [execution state reference](/docs/reference/planning-and-execution-states).
## A flow is a scheduled movement of data
-A **network flow** exists when a control dependency also has a data dependency,
-the producer and consumer are assigned to different resources, and the selected
-route requires movement. It has a producer, consumer, source resource, target
-resource, logical byte volume, and a route. During a completed execution,
-AkôFlow persists a `DataTransfer` observation with start/finish time, duration,
-cost, source/target, strategy, route, logical bytes, and network bytes when the
-runtime reports them.
+A **network flow** can occur when a producer and consumer have both an ordering
+and a data dependency and a plan assigns them to different resources. The run
+can record the route, bytes moved, duration, and cost when the runtime reports
+them.
-The link bandwidth is in bits per second while dependency size is in bytes. For
-a single 10 GiB flow over a 10 Gbit/s link, the raw payload time is roughly
-eight seconds before latency. A multi-hop route adds latency for its hops and is
-limited by its effective available bandwidth.
+Link bandwidth is in bits per second while dependency size is in bytes. A
+multi-hop route adds latency for its hops and is limited by its effective
+available bandwidth. [Network modeling](/docs/explanations/network-modeling#units-and-a-small-example)
+works through a concrete transfer estimate.
## Contention means simultaneous users of a bottleneck
-Two flows contend when they overlap and use a shared bottleneck. In the current
-PRISM complete-state evaluator, that can be a shared route hop, a shared source
-resource, or a shared target resource. It divides modeled bandwidth among the
-active users. The model is event-based: a flow begins after route latency, then
-its remaining bytes progress at the current shared rate until another task or
-flow event changes the set of active users.
-
-This is not a claim that every real runtime reports network contention as a
-separate observed number. It is a planning-model effect used by PRISM. Inspect
-the actual transfer records to determine whether a completed run moved the
-expected bytes and how long that movement lasted.
+Two flows contend when they overlap at a shared link or endpoint. PRISM models
+that sharing when predicting transfers. A real runtime may not report a separate
+contention value, so use the run's transfer records to see how many bytes moved
+and how long they took. [Network modeling](/docs/explanations/network-modeling) explains the
+routes behind those predictions.
## Four activity-stage timings
@@ -63,13 +54,13 @@ That is different from PRISM's predicted CPU-interference slowdown.
## Accumulated stage time is not makespan
-For a completed workflow run, the control plane calculates observed makespan as:
+For a completed workflow run, AkôFlow calculates observed makespan as:
```text
last completed task finish − first completed task start
```
-The run feed separately sums per-task runtime, queue, interference, and
+The run summary separately sums per-task runtime, queue, interference, and
overhead, and separately sums observed transfer durations and transferred bytes.
Those sums are **accumulated stage time**. Parallel work is counted once for each
activity that experienced it.
@@ -84,14 +75,14 @@ the activity work and waiting occur across the whole run?"
For completed execution traces, task cost is task runtime multiplied by the
assigned resource's `pricePerSecond`. The trace also includes observed transfer
-cost. For an allocated cloud instance, the control plane adds the idle portion
+cost. For an allocated cloud instance, AkôFlow adds the idle portion
of the resource active window plus persistent-disk price when the resource
metadata has `diskPricePerGiBMonth`.
This is an internal cost model. A provider invoice can differ because it may use
different billing periods, minimum charges, taxes, discounts, network rules, or
unmodeled services. Compare a plan's predicted cost with the run's observed
-modelled cost only when they use the same resource price and scope.
+modeled cost only when they use the same resource price and scope.
## Reading a plan-versus-observed gap
@@ -108,6 +99,6 @@ modelled cost only when they use the same resource price and scope.
## Related material
-- [PRISM and HEFT: search, objectives, and prediction](./prism-and-heft)
-- [Plan-versus-observed evidence and provenance](./evidence-and-provenance)
-- [30 GB network fan-out Showcase](../showcase/network-fanout)
+- [PRISM and HEFT: search, objectives, and prediction](/docs/explanations/prism-and-heft)
+- [Plan-versus-observed evidence and provenance](/docs/explanations/evidence-and-provenance)
+- [30 GB network fan-out Showcase](/docs/showcase/network-fanout)
diff --git a/docs/docs/explanations/planning.md b/docs/docs/explanations/planning.md
index 7d32f76a..f9e4dc91 100644
--- a/docs/docs/explanations/planning.md
+++ b/docs/docs/explanations/planning.md
@@ -2,40 +2,42 @@
title: Planning, candidates, and selected plans
sidebar_label: Planning and plans
-description: Why planning sessions produce candidates before one placement becomes executable.
+description: Why planning sessions produce candidates before one placement becomes a saved plan.
---
import useBaseUrl from '@docusaurus/useBaseUrl';
-Planning answers a bounded placement question: given one workflow version and one execution scope, which feasible assignment should be used for the chosen objective? It is not execution, and it does not reserve or start infrastructure.
+A plan records where a workflow's activities should run within an execution scope. You can make one manually or use a planning session to compare predicted placements and costs. Selecting a plan does not start a run or reserve infrastructure.
-Use [Plan a workflow](../guides/workflows/planning) for the Desktop or API procedure; this explanation covers the model behind it.
+Use [Plan a workflow](/docs/guides/workflows/planning) for the Desktop or API procedure; this explanation covers the model behind it.
## A planning session freezes the question
-The session stores the workflow version, execution scope, network topology, environment snapshots, resources, activity profiles, deadline, budget, interference data, and algorithm selection. Freezing these inputs makes a later comparison meaningful: each algorithm evaluates the same recorded infrastructure universe instead of whatever discovery happens to return later.
+A planning session records the workflow version, available resources, network topology, deadline, budget, and selected algorithms. It also keeps the profiles and environment data used for prediction. This lets you compare candidates against the same inputs, even if the environment changes later.
})
## Candidates are alternatives, not executions
-A candidate has a predicted makespan and cost, feasibility flags, rank and Pareto metadata, and an embedded prospective plan. Several candidates can have the same algorithm and objective. They exist so the user can inspect trade-offs before committing to one placement.
+A candidate contains a possible placement with predicted makespan, cost, and feasibility. After the session completes, it receives rank and Pareto metadata for comparison. Several candidates can come from the same algorithm and objective.
-Only selection promotes a candidate to the canonical schedule plan. The plan contains assignments to a resource/core/slot and prediction fields such as ready, start, finish, runtime, transfer, and cost. It may also contain cloud lifecycle actions. A manually authored placement and an imported placement use the same schedule-plan representation after validation.
+Selecting a candidate saves it as a schedule plan; it does not start a run. The plan records where activities should run and their predicted timing and cost. It can also include cloud setup actions. You can instead supply or import a placement, subject to validation.
+
+Plan validation checks placement and workflow constraints. The runtime binding for each assignment is checked when execution starts, so a saved plan can still fail to start if its assigned resource has no compatible enabled runtime.
## Objectives and constraints answer different questions
-An algorithm objective ranks candidates, while deadline and budget determine whether a candidate is feasible for the request. A candidate can remain visible when it misses a constraint; that preserves the best alternatives discovered even if no candidate meets the SLA. It is not a promise that the option will be recommended for execution.
+An algorithm's objective ranks candidates. Deadline and budget determine whether each candidate meets your constraints. A candidate may remain visible even when it misses a limit, so you can inspect the alternatives the planner found.
-The current built-ins include HEFT, PRISM Time, and PRISM Cost. Their search and objective behavior is intentionally separate from this record model. The selected plan's prediction is also separate from observed timing: a completed run supplies the evidence needed to assess that prediction.
+The built-in schedulers are HEFT, PRISM Time, and PRISM Cost. They rank candidates in different ways; [PRISM and HEFT](/docs/explanations/prism-and-heft) explains those differences. A completed run supplies the evidence needed to assess the selected plan's prediction.
## Why a plan can differ from a completed run
-Planning works from snapshots and models. An actual run adds provider queueing, startup behavior, data preparation, runtime availability, and observed transfer behavior. Those are recorded with the execution rather than silently rewritten into the plan. Read [plan-versus-observed evidence](./evidence-and-provenance) for how to interpret the comparison.
+Planning works from snapshots and models. An actual run adds provider queueing, startup behavior, data preparation, runtime availability, and observed transfer behavior. Those are recorded with the execution rather than silently rewritten into the plan. Read [plan-versus-observed evidence](/docs/explanations/evidence-and-provenance) for how to interpret the comparison.
## Related material
-- [Planning and execution state reference](../reference/planning-and-execution-states)
-- [Execution scopes and topologies](../reference/execution-scopes-and-topologies)
-- [Network modeling](./network-modeling)
-- [Execute and monitor a workflow](../guides/workflows/executions)
+- [Planning and execution state reference](/docs/reference/planning-and-execution-states)
+- [Execution scopes and topologies](/docs/reference/execution-scopes-and-topologies)
+- [Network modeling](/docs/explanations/network-modeling)
+- [Execute and monitor a workflow](/docs/guides/workflows/executions)
diff --git a/docs/docs/explanations/prism-and-heft.md b/docs/docs/explanations/prism-and-heft.md
index 5e26b13c..f209e099 100644
--- a/docs/docs/explanations/prism-and-heft.md
+++ b/docs/docs/explanations/prism-and-heft.md
@@ -4,15 +4,15 @@ sidebar_label: PRISM and HEFT
description: What the built-in schedulers optimize, what each prediction includes, and why neither algorithm is guaranteed to win an observed run.
---
-HEFT, PRISM Time, and PRISM Cost are alternatives for generating schedule-plan candidates. They are not measurements of a completed execution. Their output is useful only in the context of the frozen workflow, resources, topology, profiles, deadline, and budget of one planning session.
+HEFT, PRISM Time, and PRISM Cost propose different placements for a workflow. Each produces predictions from the same planning-session inputs; none measures a completed run.
-This explanation is for readers choosing or interpreting a built-in scheduler. For the procedure, see [Plan a workflow](../guides/workflows/planning). For the meaning of observed timing, see [evidence and provenance](./evidence-and-provenance).
+This explanation is for readers choosing or interpreting a built-in scheduler. For the procedure, see [Plan a workflow](/docs/guides/workflows/planning). For the meaning of observed timing, see [evidence and provenance](/docs/explanations/evidence-and-provenance).
## What is shared
-All three schedulers receive the same `PlanningRequest`: a workflow version, execution scope, schedulable resources, network topology, activity-resource profiles, deadline, budget, and optional interference matrix. They reject a scope with no schedulable resources and only place an activity on a resource that satisfies its CPU and memory requirements. A resource with multiple cores offers multiple scheduling lanes, except for an opaque batch target such as an HPC partition or batch queue, which is treated as one slot.
+All three use the session's workflow, scope, topology, profiles, deadline, and budget. They place activities only where CPU and memory fit. A multicore resource offers several lanes; an HPC partition or batch queue counts as one slot.
-The base duration for a placement is selected from an activity-resource profile when one matches. Otherwise the planner uses the activity's `simulation.durationSeconds` when present, falling back to one second and then dividing by the resource's compute speedup. These inputs need to be credible before any comparison of algorithm quality is meaningful.
+For each placement, a matching activity-resource profile supplies the base duration. Otherwise the planner uses `simulation.durationSeconds`, or one second if absent, then divides by resource speedup. Poor duration inputs make any scheduler comparison unreliable.
## The three schedulers
@@ -22,45 +22,45 @@ The base duration for a placement is selected from an activity-resource profile
| PRISM Time | Beam search over ready activities and feasible resource/core placements; complete states are re-evaluated | Predicted makespan, then transfer time, network cost, used resources, and cost | Routed transfers, active-flow sharing, resource active-window cost, optional CPU interference, queue and frozen overhead metadata |
| PRISM Cost | The same PRISM search and complete-state re-evaluation | Predicted cost, then network cost, transfer time, used resources, makespan, and queue | The same PRISM model, ranked exclusively for cost |
-"Primary" does not mean that later values are ignored. They are deterministic tie-breakers. PRISM also reserves parts of each beam for the other objective and for network-local placements. In a time search, one lane keeps alternatives by concrete earliest finish; this reduces the chance that a tie in the projected critical path discards a low-wait placement too early. It is search diversity, not a promise that every possible placement is retained.
+Later values break ties. PRISM retains some alternatives for the other objective and for network-local placements, but its bounded search cannot keep every placement.
## Ranking work before placement
-HEFT computes an upward rank from average activity duration and the longest successor rank. It then considers every feasible resource and every core for the next ranked activity, choosing the earliest resulting finish; equal makespans are broken by predicted cost.
+HEFT ranks activities by estimated work remaining, then tests feasible resources and cores for each activity. It chooses the earliest predicted finish, using cost to break ties.
-PRISM also constructs a rank, but its rank includes average communication time over routes in the frozen topology. Its ready frontier can branch to several ready activities, and each partial state can place the chosen activity on each feasible resource. The beam width and ready-branch limit bound that exploration; the registered defaults are 120 and 3. Larger values can retain more alternatives but increase planning work. The planning-session estimate reports the expected expanded states and calibrated duration before a PRISM run starts.
+PRISM's rank also includes estimated communication over topology routes. It can explore several ready activities and placements at once. Beam width and ready-branch limit cap the search; their defaults are 120 and 3. Raising them considers more alternatives but takes more planning work. The session estimate reports expected expanded states and duration before PRISM starts.
## Why PRISM has a detailed second evaluation
-The compact PRISM search needs to rank partial schedules quickly. After it reaches complete placement states, it removes duplicate placement signatures and re-evaluates each retained state with an event model. The evaluator starts tasks when their inputs and assigned lane are ready, applies frozen boot and container overhead, models active tasks on a resource with optional pairwise CPU-priority interference, and progresses transfer flows along the cached topology routes.
+PRISM ranks partial schedules quickly. For complete placements, it removes duplicates and runs a more detailed evaluation. Tasks start when their inputs and assigned lane are ready. The model includes startup overhead, optional CPU interference, and transfers along topology routes.
-For a network flow, the evaluator counts active users of each route hop as well as active flows sharing the sending or receiving resource. Bandwidth is shared among the relevant flows, and link latency is paid before payload movement. This is a prediction model, not an invocation of a real SimGrid process while the candidate is being generated.
+Overlapping flows share bandwidth at route links and resource endpoints; each link also adds latency. This predicts transfer behavior without running SimGrid during candidate generation.
-The resulting PRISM plan records evaluator metadata including its prediction confidence, network-path model, network-contention model, active-window cost model, and interference model. Prediction confidence reflects the fraction of activities with a simulation definition or matching activity profile; it does not establish that a future run will match the prediction.
+The plan records the models used and a confidence value. That value reflects how many activities have a simulation definition or matching profile, not how closely a future run will match.
## Cost and makespan are different quantities
-PRISM charges a resource by its active window in the detailed evaluation, then adds modeled transfer byte price. This can differ from HEFT's accumulated per-activity runtime price. Both are estimates derived from the frozen resource prices and assigned placement; neither is an invoice from a cloud provider.
+PRISM estimates resource cost from each active window and adds transfer byte cost. HEFT sums per-activity runtime cost. Both use the session's resource prices; neither is a provider invoice.
-PRISM Time ranks candidates by predicted makespan. PRISM Cost ranks by predicted cost. Neither objective asserts that the candidate is globally optimal, because beam search intentionally bounds the set of partial schedules that survive.
+PRISM Time ranks by predicted makespan; PRISM Cost ranks by predicted cost. Beam search does not guarantee a global optimum.
-## Do not infer a winner from the algorithm name
+## Compare observed runs
-PRISM has a richer current network and interference model, but more modeled inputs do not guarantee a better observed run. A real or simulated execution can differ when activity durations, topology, provider queueing, storage paths, startup overhead, or actual transfer behavior differ from the frozen inputs. HEFT can therefore have a lower observed makespan for a particular scope and workflow. Conversely, PRISM can find a better plan when its additional modeled effects distinguish placements that HEFT treats similarly.
+PRISM models more network and interference effects, but a richer prediction need not lead to a faster run. Durations, queues, storage paths, startup, and transfers can differ from the session's inputs. Either scheduler may perform better for a particular workflow and scope.
-The current implementation does **not** send HEFT and PRISM candidates through one shared post-search evaluator before ranking across algorithms. Compare their stored predictions as algorithm-specific estimates, then execute selected plans under the same scope and inspect their observed traces. The evidence, rather than the algorithm label, establishes which plan performed better in that experiment.
+HEFT and PRISM do **not** pass through one shared evaluator before their predictions are compared. Treat their estimates as algorithm-specific. To compare outcomes, run selected plans under comparable conditions and inspect the observed traces.
-## A disciplined comparison
+## Compare plans in an experiment
1. Use the same workflow version, scope, topology, activity profiles, deadline, and budget for every algorithm in the session.
-2. Inspect candidate assignments and predicted transfer/cost fields before selecting a plan; different placements may explain different outcomes.
+2. Inspect assignments, predicted transfers, and cost before selecting a plan.
3. Run the selected alternatives under comparable runtime conditions.
4. Compare observed makespan, task timing, transfers, and cost with the plan.
-5. Calibrate the workflow profiles or infrastructure model when a recurring prediction gap has a concrete cause; do not treat a single result as proof of algorithm superiority.
+5. Update profiles or infrastructure values when a recurring prediction gap has a known cause.
## Related material
-- [Planning, candidates, and selected plans](./planning)
-- [Network modeling and data movement](./network-modeling)
-- [Execution scopes and topologies reference](../reference/execution-scopes-and-topologies)
-- [Planning and execution state reference](../reference/planning-and-execution-states)
+- [Planning, candidates, and selected plans](/docs/explanations/planning)
+- [Network modeling and data movement](/docs/explanations/network-modeling)
+- [Execution scopes and topologies reference](/docs/reference/execution-scopes-and-topologies)
+- [Planning and execution state reference](/docs/reference/planning-and-execution-states)
diff --git a/docs/docs/getting-started.md b/docs/docs/getting-started.md
index 77d5ac4c..c50834db 100644
--- a/docs/docs/getting-started.md
+++ b/docs/docs/getting-started.md
@@ -1,75 +1,56 @@
---
id: getting-started
-title: Choose where to start
+title: Getting started with AkôFlow
sidebar_label: Getting started
slug: /getting-started
-description: Choose the shortest AkôFlow documentation path for installation, a first run, operations, concepts, or API integration.
+description: Understand AkôFlow, choose a supported path, and find the next workflow task.
---
-import useBaseUrl from '@docusaurus/useBaseUrl';
+# Getting started with AkôFlow
-# Choose where to start
+AkôFlow helps you define a scientific workflow, choose where its activities run, make a plan, and execute it. A workflow describes activities and data dependencies. A run records what happened when you executed the plan. You can compare planning choices after the first run.
-AkôFlow plans and executes scientific workflow DAGs on simulated or connected infrastructure, then preserves the plan, observed execution, data movement, artifacts, audit events, and provenance. This page is a map of the documentation; it does not teach an individual workflow.
+Start with a local environment to learn the interface. Connecting HPC, Kubernetes, or cloud resources requires the access and checks in their own guides.
-You do not need prior AkôFlow experience. Choose the path that matches what you want to accomplish.
+## Start with Desktop
-## I want to run AkôFlow for the first time
+1. [Install AkôFlow Desktop](/docs/installation) and complete its local environment checkup.
+2. [Run your first local workflow](/docs/guides/workflows/first-local-run) and inspect its result in Desktop.
+3. [Tour the interface](/docs/guides/interface-tour) or continue with [Workflow definitions](/docs/guides/workflows/definitions), [Planning](/docs/guides/workflows/planning), and [Execution](/docs/guides/workflows/executions).
-1. [Install AkôFlow](./installation) and verify that its daemon is available.
-2. [Run the first simulated workflow](./guides/workflows/first-run). The tutorial uses checked-in files, requires no cluster or cloud account, and ends with concrete activity and transfer checks.
-3. Use the [interface tour](./guides/interface-tour) when you want to learn where the same records appear in Desktop.
+The [checked-in SimGrid example](/docs/guides/workflows/first-run) verifies three activities and two transfers through a separately managed API endpoint. Use it after the local Desktop run if you want to explore simulation.
-Start with the simulation even if your eventual target is Kubernetes or HPC. It separates installation problems from credentials, network access, scheduler policy, and remote storage.
+## What is supported today
-## Continue after installation
+The local Desktop workflow has a verified run on Linux. The [Showcase](/docs/showcase) also has verified SimGrid and Kubernetes-on-Kind examples. The SLURM example exercises a local scheduler fixture; a run on an institutional cluster remains unverified.
-Follow [installation result checks](./installation#4-installation-result), then
-[register HPC / SLURM](./tutorials/register-hpc) or
-[connect Google Cloud](./tutorials/connect-cloud). Each tutorial includes the
-actual connection form, an API path, and expected results. For automation, start
-with [API connection setup](./tutorials/api-access).
+Google Cloud catalog and worker provisioning are implemented, but a complete live provision-and-destroy cycle has not been verified. AWS EC2 discovery and provisioning are unavailable; S3 transfers have local code tests but no verified AWS-account run. Check [cloud provider support](/docs/guides/infrastructure/cloud-support) before choosing a provider.
-## I already have AkôFlow running
-
-| Goal | Continue with |
-| --- | --- |
-| Define or import an activity DAG | [Workflow definitions](./guides/workflows/definitions) |
-| Generate PRISM or HEFT candidates, or place activities manually | [Plan a workflow](./guides/workflows/planning) |
-| Start a selected plan and inspect observed evidence | [Execute and monitor a workflow](./guides/workflows/executions) |
-| Configure simulated or connected infrastructure | [Environments](./guides/infrastructure/environments) |
-| Limit the resources and network offered to planning | [Execution scopes and network topologies](./guides/infrastructure/execution-scopes) |
-| Reproduce a complete example | [Workflow Showcase](./showcase/) |
-| Query lineage, evidence, or audit records | [Provenance and audit](./guides/data/provenance-and-audit) |
-
-## I am connecting infrastructure
-
-Choose the guide for the actual target. Provider and runtime support are not interchangeable.
-
-- [SimGrid first run](./guides/workflows/first-run): deterministic local simulation.
-- [Kubernetes real execution](./showcase/kubernetes-real-execution): container execution on the checked-in Kind example.
-- [HPC and SLURM](./guides/infrastructure/hpc-slurm): login nodes, partitions, shared storage, SSH proxies, and batch execution.
-- [Google Cloud](./guides/infrastructure/gcp): service-account credentials, catalog discovery, pricing, and Terraform provisioning.
-- [AWS](./guides/infrastructure/aws): S3 and S3-compatible data movement. AkôFlow v1.0 does not discover or provision EC2 capacity.
+## Connect another environment
-Review the [cloud support matrix](./guides/infrastructure/cloud-capacity#provider-support-in-v10) before designing a cloud deployment.
+- [Register HPC / SLURM](/docs/tutorials/register-hpc) after receiving site-approved SSH and scheduler access.
+- [Connect Google Cloud](/docs/tutorials/connect-cloud) with a service account and a project you can inspect.
+- [Configure Kubernetes](/docs/guides/infrastructure/kubernetes) when you have cluster access.
-## I am automating through the API
+For direct API work, complete [API connection setup](/docs/tutorials/api-access) first.
-Read the [API overview](./reference/api-overview) for the base URL, authentication, content types, asynchronous operations, error envelope, and generated endpoint index. Use the [workflow specification](./internal/workflow-spec) for portable YAML authoring.
-
-The Desktop and HTTP API operate on the same persisted records. The API is preferable for repeatable experiments and integrations; Desktop is preferable for inspecting infrastructure, candidate Gantt charts, live activity state, and plan-versus-observed evidence.
-
-## I need to understand the model first
-
-Read [Core concepts](./concepts) for the vocabulary and record relationships. Continue to [Engine](./engine) for control-plane behavior and [Runtimes](./runtimes) for execution-provider boundaries.
+## I already have AkôFlow running
-The central lifecycle is shown below.
+| Goal | Continue with |
+| --- | --- |
+| Define or import an activity DAG | [Workflow definitions](/docs/guides/workflows/definitions) |
+| Generate PRISM or HEFT candidates, or place activities manually | [Plan a workflow](/docs/guides/workflows/planning) |
+| Start a selected plan and inspect observed evidence | [Execute and monitor a workflow](/docs/guides/workflows/executions) |
+| Configure simulated or connected infrastructure | [Environments](/docs/guides/infrastructure/environments) |
+| Limit the resources and network offered to planning | [Execution scopes and network topologies](/docs/guides/infrastructure/execution-scopes) |
+| Reproduce a complete example | [Workflow Showcase](/docs/showcase) |
+| Trace how a result was produced | [Trace a result with provenance](/docs/guides/data/provenance) |
+| Investigate a connection check, resource discovery, or console action | [Inspect audit events](/docs/guides/data/audit-events) |
-})
+## Understand the records
-A plan is not an execution. It predicts an assignment within a frozen workflow and infrastructure boundary. A run records what happened when that plan was dispatched.
+Read [Core concepts](/docs/concepts) for workflow, environment, plan, run, artifacts, and provenance. For implementation details, see [Architecture internals](/docs/modules). The [API overview](/docs/reference/api-overview) and [workflow specification](/docs/internal/workflow-spec) are reference material for automation.
## When something fails
-Use [Troubleshooting](./guides/operations/troubleshooting) for daemon readiness, authentication, Docker and BuildKit checks, connection failures, and diagnostic collection. For remote targets, validate credentials and the environment connection before debugging the workflow itself.
+Use [Troubleshooting](/docs/guides/operations/troubleshooting) for server readiness, authentication, Docker and BuildKit checks, connection failures, and diagnostic collection. For remote targets, validate credentials and the environment connection before debugging the workflow itself.
diff --git a/docs/docs/guides/data/artifact-locations.md b/docs/docs/guides/data/artifact-locations.md
new file mode 100644
index 00000000..5cb9f090
--- /dev/null
+++ b/docs/docs/guides/data/artifact-locations.md
@@ -0,0 +1,26 @@
+---
+title: Inspect artifact locations
+description: Inspect recorded executable locations and preparation status on a resource.
+---
+
+# Inspect artifact locations
+
+Use this guide after registering or building an executable artifact. It shows the catalog locations recorded for its bytes and whether preparation on a run's target resource finished.
+
+For the API commands below, complete [API connection setup](/docs/tutorials/api-access) first.
+
+## Find recorded locations and preparation status
+
+Use **Artifacts** to see executable versions, **Artifact locations** to see their recorded URI, digest, and `available` flag, and **Materializations** to see preparation on target resources. The location list reads saved catalog records; `available: true` does not run a fresh storage or network check.
+
+A materialization identifies a variant and digest, target resource and destination path, plus its lifecycle status: `planned`, `reconciling`, `transferring`, `verifying`, `committed`, or `failed`. For a prepared copy, check both `status: "committed"` and that `verifiedDigest` matches `digest`. These are saved observations; listing them does not recheck the destination bytes.
+
+```bash
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ "$AKOFLOW_API_URL/artifact-locations/"
+
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ "$AKOFLOW_API_URL/artifact-materializations/"
+```
+
+Add `--data-urlencode "runId=.default})
+
+*Each row keeps the event time, its machine-readable type, the persisted target, the outcome, and an operational summary. In this capture, connection health checks show both a failed Kubernetes check and a successful cloud credential check; the colored outcome is a result to investigate, not a diagnosis by itself.*
+
+### Read the Audit screen
+
+| Area | Use it for | Important interpretation |
+| --- | --- | --- |
+| **All events** and category tabs | Narrow the visible list to discovery/resources, connections, console sessions, workflows, or credentials. | The Desktop fetches an audit list and applies these categories in the browser. **All events** removes that local category filter; it does not request a different server-side result set. |
+| **Time** | Correlate an operation with a run, connection check, or terminal session. | The value is displayed in the local browser time zone. Use persisted IDs and API filters when an investigation needs exact cross-system correlation. |
+| **Event** | Identify the operation class, such as `connection.health.checked`. | Event types are machine-readable, dot-separated names. The category tabs match their leading namespace. |
+| **Target** | Locate the connection, environment, resource, session, execution, or system record affected by the event. | This is a persisted target identifier when one is available; it is not necessarily the friendly name shown elsewhere in Desktop. |
+| **Outcome** | Quickly distinguish `started`, `succeeded`, and `failed` records. | A failure tells you that the recorded operation did not complete successfully. Read **Summary** and then inspect the target before changing a configuration. |
+| **Summary** | Read the service-provided context or error associated with the event. | Treat it as operational evidence. It can include a runtime error returned by an external system, so do not copy it into public reports without reviewing it. |
+
+For API queries, complete [API connection setup](/docs/tutorials/api-access) first. This request lists recent failures without requiring an environment ID:
+
+```bash
+curl --fail-with-body -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ --data-urlencode "outcome=failed" \
+ --data-urlencode "limit=100" \
+ "$AKOFLOW_API_URL/audit-events/"
+```
+
+Add `--data-urlencode "environmentId=.default})
-
-*The catalog defines the projections available for exploration. In the **Runs** projection, the row action opens the record details and the lineage action follows its relationship to the selected plan; use the search and export controls only after choosing the record type that answers the question.*
-
-The API exposes the same server-defined catalog and query:
-
-```bash
-curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- "$AKOFLOW_URL/akoflow-api/provenance/entities/"
-
-curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- --data-urlencode "q=completed" \
- --data-urlencode "filterField=status" \
- --data-urlencode "filterValue=completed" \
- --data-urlencode "page=1" \
- --data-urlencode "pageSize=50" \
- --data-urlencode "sortField=created_at" \
- --data-urlencode "sortOrder=desc" \
- "$AKOFLOW_URL/akoflow-api/provenance/entities/runs/"
-```
-
-Entity names and fields are supplied by `/provenance/entities/`; clients should not invent them. Query responses include entity metadata, `items`, `page`, `pageSize`, `total`, and `hasNext`.
-
-## Follow lineage
-
-From an Explore result, choose **Open lineage**, or open the **Lineage** tab and provide an entity and ID. Select `upstream`, `downstream`, or `both`, choose a depth, then inspect nodes and relationships. Any node can become the new root.
-
-.default})
-
-*The fan-out example starts at the completed run. Distance 1 contains its plan, activity executions, and transfers; distance 2 reaches the workflow version, scope, activities, and allocated resources. Select a card to inspect the fields in the detail panel rather than inferring them from its position in the graph.*
-
-### Read the Lineage screen
-
-| Area | Use it for | Important interpretation |
-| --- | --- | --- |
-| **Record type** and **Record ID** | Define the root record. The current root can also come from **Open lineage** in Explore. | Use the stored ID, not a display name. IDs remain stable when a user changes a label. |
-| **Direction** and **Depth** | Choose whether to follow antecedents, descendants, or both, then bound the search. | A larger depth adds relationships; it does not mean a later execution time. Start at 1 or 2 and expand only when the question requires it. |
-| **Lineage graph** | Inspect the nodes grouped by graph distance from the root. | The heading reports the returned node and relationship counts. Grouped columns are distance from the root, not workflow stages or chronological lanes. |
-| **Find a node** and **node-type filter** | Reduce a large graph to a specific record or entity kind such as transfers or activity executions. | Filtering changes the visible graph only. It does not change the lineage query or delete evidence. |
-| **Selected-record panel** | Read the status and persisted fields for the selected card, then use **Open record** for the operational page. | The panel is evidence for that one record. Compare the plan and run IDs deliberately when investigating planned versus observed behavior. |
-| **Export JSON** | Preserve the exact lineage response for an investigation or a report. | The export is a snapshot of the current root, direction, and depth; record those choices with the file. |
-
-```bash
-curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- --data-urlencode "direction=both" \
- --data-urlencode "depth=2" \
- --data-urlencode "maxNodes=300" \
- "$AKOFLOW_URL/akoflow-api/provenance/lineage/runs/$RUN_ID/"
-```
-
-The response contains a `root` key, `nodes`, directed `edges`, and `truncated`. Increase depth deliberately: the graph may expand quickly, and the interface caps a request at 300 nodes.
-
-## Query with read-only SQL
-
-The **SQL** tab presents the queryable schema, templates for common investigations, named JSON parameters, result paging, explain, favorites, and local query history.
-
-.default})
-
-*This query joins completed execution runs to their schedule plans. The result summary reports the returned row count, current page, elapsed query time, and whether more rows are available; the values are evidence from the connected local database, not fixed example values.*
-
-### Read the SQL screen
-
-| Area | Use it for | Important interpretation |
-| --- | --- | --- |
-| **Safe schema** | Discover the tables and columns that the service makes available to read-only queries. Click a field to insert its name into the editor. | This is the current service schema, not a generic SQLite browser. Start here instead of assuming a column exists. |
-| **Query template** | Start a common investigation, then refine it in the editor. | A template is ordinary editable SQL. Review joins, filters, and ordering before relying on its output. |
-| **Query editor** | Write a `SELECT` or `WITH` query, including named parameters. | The interface shows the active timeout and row limit. Statements that modify data are rejected. |
-| **Run query** and **Query result** | Execute the query and inspect typed columns, rows, page controls, and elapsed milliseconds. | Row limits bound one result page. A “more rows available” message means that the result is not the complete matching set yet. |
-| **Explain** | Inspect SQLite's query plan before using a costly investigation repeatedly. | An explanation describes the database's access plan; it does not replace the normal query result or prove a result is scientifically meaningful. |
-| **Export CSV** and **Export JSON** | Save the current result page for analysis or a report. | Record the SQL, parameters, page, and time of export with the file so another investigator can reproduce it. |
-| **Favorite** and **History** | Reuse a query in the same Desktop browser profile. | They are local conveniences, not shared provenance records. |
-
-Only read-only `SELECT` and `WITH` queries are accepted. The Desktop communicates the current service limits as a 10-second execution timeout and 200 rows per page. Fetch the runtime schema instead of assuming table or column names:
-
-```bash
-curl -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- "$AKOFLOW_URL/akoflow-api/provenance/sql/schema/"
-
-curl -X POST -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- -H "Content-Type: application/json" \
- -d '{
- "sql":"SELECT id, status, created_at FROM execution_runs WHERE status = :status ORDER BY created_at DESC",
- "parameters":{"status":"completed"},
- "page":1,
- "pageSize":200
- }' \
- "$AKOFLOW_URL/akoflow-api/provenance/sql/"
-```
-
-Send the same payload to `/provenance/sql/explain/` to inspect the query plan without running the ordinary result path. SQL results contain typed `columns`, `items`, pagination information, a `truncated` flag, and elapsed milliseconds.
-
-:::note Local UI state
-SQL favorites and recent-query history are stored in the browser profile. They are conveniences, not provenance records, and are not synchronized through the API.
-:::
-
-## Inspect the audit trail
-
-Open **Audit** for a chronological record of infrastructure discovery, connections, console access, commands, credentials, and workflow activity. It starts in **All events** and groups the loaded records into discovery/resources, connections, console sessions, workflows, and credentials.
-
-
-
-*Each row keeps the event time, its machine-readable type, the persisted target, the outcome, and an operational summary. In this capture, connection health checks show both a failed Kubernetes check and a successful cloud credential check; the colored outcome is a result to investigate, not a diagnosis by itself.*
-
-### Read the Audit screen
-
-| Area | Use it for | Important interpretation |
-| --- | --- | --- |
-| **All events** and category tabs | Narrow the visible list to discovery/resources, connections, console sessions, workflows, or credentials. | The Desktop fetches an audit list and applies these categories in the browser. **All events** removes that local category filter; it does not request a different server-side result set. |
-| **Time** | Correlate an operation with a run, connection check, or terminal session. | The value is displayed in the local browser time zone. Use persisted IDs and API filters when an investigation needs exact cross-system correlation. |
-| **Event** | Identify the operation class, such as `connection.health.checked`. | Event types are machine-readable, dot-separated names. The category tabs match their leading namespace. |
-| **Target** | Locate the connection, environment, resource, session, execution, or system record affected by the event. | This is a persisted target identifier when one is available; it is not necessarily the friendly name shown elsewhere in Desktop. |
-| **Outcome** | Quickly distinguish `started`, `succeeded`, and `failed` records. | A failure tells you that the recorded operation did not complete successfully. Read **Summary** and then inspect the target before changing a configuration. |
-| **Summary** | Read the service-provided context or error associated with the event. | Treat it as operational evidence. It can include a runtime error returned by an external system, so do not copy it into public reports without reviewing it. |
-
-The API supports server-side filtering:
-
-```bash
-curl -G -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- --data-urlencode "environmentId=$ENVIRONMENT_ID" \
- --data-urlencode "outcome=failed" \
- --data-urlencode "limit=100" \
- "$AKOFLOW_URL/akoflow-api/audit-events/"
-```
-
-Available filter parameters are `eventType`, `environmentId`, `resourceId`, `connectionId`, `sessionId`, `executionId`, `outcome`, and `limit`. Outcomes currently include `started`, `succeeded`, and `failed`. The Desktop currently loads the audit list and applies its category tabs locally; use API filters for precise automation.
-
-## Investigation workflow
-
-For a failed or surprising result:
-
-1. Open the execution and identify the run, activity, plan, and produced data IDs.
-2. Open **Provenance > Explore**, find the record, and open its lineage.
-3. Use **SQL** when the question crosses multiple entities or compares planned and observed values.
-4. Open **Audit** to correlate infrastructure, connection, credential, or console operations around the same time.
-5. Export the relevant Explore page when evidence must be shared; preserve IDs so another investigator can reproduce the query.
-
-Provenance endpoints return `503 Service Unavailable` when the explorer is not configured, `400 Bad Request` for invalid entity, SQL, or lineage requests, and `500 Internal Server Error` if schema discovery fails.
+Have a run ID? Start in Provenance. Open Audit when a connection check, discovery, or console action may explain what happened. Audit is not a complete history of workflow changes. For the relationship between these records, read [Compare a plan with a completed run](/docs/explanations/evidence-and-provenance).
diff --git a/docs/docs/guides/data/provenance.md b/docs/docs/guides/data/provenance.md
new file mode 100644
index 00000000..f5ccdcbe
--- /dev/null
+++ b/docs/docs/guides/data/provenance.md
@@ -0,0 +1,119 @@
+---
+title: Trace a result with provenance
+description: Find saved records, follow lineage, and query run evidence with read-only SQL.
+---
+
+# Trace a result with provenance
+
+Start with a completed run. Use **Provenance** to follow the workflow, activities, and data behind its result.
+
+## Investigate a result
+
+1. Open the execution and copy its run ID and any produced data IDs.
+2. Find the run in **Provenance → Explore**, then open its lineage.
+3. If lineage does not answer the question, use read-only SQL to compare records or planned and observed values.
+4. When sharing an investigation, export the relevant record or query page with its IDs, SQL, parameters, and page number.
+
+For the API commands below, complete [API connection setup](/docs/tutorials/api-access) first.
+
+## Explore provenance in Desktop
+
+Open **Provenance**. The **Explore** tab loads a server-defined entity catalog. Select an entity, search across its safe projection, apply a field filter, sort a column, and page through the result. The current page can be exported as CSV or JSON.
+
+
+
+*Choose a record type first. In **Runs**, open a row for details or follow its lineage.*
+
+The API exposes the same server-defined catalog and query:
+
+```bash
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ "$AKOFLOW_API_URL/provenance/entities/"
+
+curl --fail-with-body -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ --data-urlencode "q=completed" \
+ --data-urlencode "filterField=status" \
+ --data-urlencode "filterValue=completed" \
+ --data-urlencode "page=1" \
+ --data-urlencode "pageSize=50" \
+ --data-urlencode "sortField=created_at" \
+ --data-urlencode "sortOrder=desc" \
+ "$AKOFLOW_API_URL/provenance/entities/runs/"
+```
+
+Entity names and fields are supplied by `/provenance/entities/`; clients should not invent them. Query responses include entity metadata, `items`, `page`, `pageSize`, `total`, and `hasNext`.
+
+## Follow lineage
+
+From an Explore result, choose **Open lineage**, or open the **Lineage** tab and provide an entity and ID. Select `upstream`, `downstream`, or `both`, choose a depth, then inspect nodes and relationships. Any node can become the new root.
+
+
+
+*This completed run links to its plan, activity executions, transfers, workflow version, scope, and resources. Select a card to inspect its fields.*
+
+### Read the Lineage screen
+
+| Area | Use it for | Important interpretation |
+| --- | --- | --- |
+| **Record type** and **Record ID** | Define the root record. The current root can also come from **Open lineage** in Explore. | Use the stored ID, not a display name. IDs remain stable when a user changes a label. |
+| **Direction** and **Depth** | Choose whether to follow antecedents, descendants, or both, then bound the search. | A larger depth adds relationships; it does not mean a later execution time. Start at 1 or 2 and expand only when the question requires it. |
+| **Lineage graph** | Inspect the nodes grouped by graph distance from the root. | The heading reports the returned node and relationship counts. Grouped columns are distance from the root, not workflow stages or chronological lanes. |
+| **Find a node** and **node-type filter** | Reduce a large graph to a specific record or entity kind such as transfers or activity executions. | Filtering changes the visible graph only. It does not change the lineage query or delete evidence. |
+| **Selected-record panel** | Read the status and saved fields for the selected card, then use **Open record** for its page. | Compare the plan and run IDs when investigating planned versus observed behavior. |
+| **Export JSON** | Preserve the exact lineage response for an investigation or a report. | The export is a snapshot of the current root, direction, and depth; record those choices with the file. |
+
+For the API path, copy a run ID from the **Runs** results in Explore and enter it when prompted:
+
+```bash
+read -r -p 'Run ID: ' RUN_ID || exit 1
+[ -n "$RUN_ID" ] || exit 1
+
+curl --fail-with-body -G -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ --data-urlencode "direction=both" \
+ --data-urlencode "depth=2" \
+ --data-urlencode "maxNodes=300" \
+ "$AKOFLOW_API_URL/provenance/lineage/runs/$RUN_ID/"
+```
+
+The response contains a `root` key, `nodes`, directed `edges`, and `truncated`. Start with a small depth: the graph may expand quickly, and the interface caps a request at 300 nodes.
+
+## Query with read-only SQL
+
+The **SQL** tab presents the queryable schema, templates for common investigations, named JSON parameters, result paging, explain, favorites, and local query history.
+
+
+
+*The query compares completed runs with their plans. The displayed values come from the connected local database.*
+
+### Read the SQL screen
+
+| Area | Use it for | Important interpretation |
+| --- | --- | --- |
+| **Safe schema** | Discover the tables and columns that the service makes available to read-only queries. Click a field to insert its name into the editor. | This is the current service schema, not a generic SQLite browser. Start here instead of assuming a column exists. |
+| **Query template** | Start a common investigation, then refine it in the editor. | A template is ordinary editable SQL. Review joins, filters, and ordering before relying on its output. |
+| **Query editor** | Write a `SELECT` or `WITH` query, including named parameters. | The interface shows the active timeout and row limit. Statements that modify data are rejected. |
+| **Run query** and **Query result** | Execute the query and inspect typed columns, rows, page controls, and elapsed milliseconds. | Row limits bound one result page. A “more rows available” message means that the result is not the complete matching set yet. |
+| **Explain** | Inspect SQLite's query plan before using a costly investigation repeatedly. | An explanation describes the database's access plan; it does not replace the normal query result or prove a result is scientifically meaningful. |
+| **Export CSV** and **Export JSON** | Save the current result page for analysis or a report. | Record the SQL, parameters, page, and time of export with the file so another investigator can reproduce it. |
+| **Favorite** and **History** | Reuse a query in the same Desktop browser profile. | They are local conveniences, not shared provenance records. |
+
+Only read-only `SELECT` and `WITH` queries are accepted. The Desktop communicates the current service limits as a 10-second execution timeout and 200 rows per page. Fetch the runtime schema instead of assuming table or column names:
+
+```bash
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ "$AKOFLOW_API_URL/provenance/sql/schema/"
+
+curl --fail-with-body -X POST -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ -H "Content-Type: application/json" \
+ -d '{
+ "sql":"SELECT id, status, created_at FROM execution_runs WHERE status = :status ORDER BY created_at DESC",
+ "parameters":{"status":"completed"},
+ "page":1,
+ "pageSize":200
+ }' \
+ "$AKOFLOW_API_URL/provenance/sql/"
+```
+
+Send the same payload to `/provenance/sql/explain/` to inspect the query plan without running the ordinary result path. SQL results contain typed `columns`, `items`, pagination information, a `truncated` flag, and elapsed milliseconds.
+
+For recorded connection checks, resource discovery, or console actions around the same time, [inspect audit events](/docs/guides/data/audit-events). Provenance endpoints return `503 Service Unavailable` when the explorer is not configured, `400 Bad Request` for invalid entity, SQL, or lineage requests, and `500 Internal Server Error` if schema discovery fails.
diff --git a/docs/docs/guides/infrastructure/aws.md b/docs/docs/guides/infrastructure/aws.md
index c8ee2d1c..9cf4bd1b 100644
--- a/docs/docs/guides/infrastructure/aws.md
+++ b/docs/docs/guides/infrastructure/aws.md
@@ -1,42 +1,22 @@
---
-title: Configure AWS
-description: Configure AWS credentials and S3 data transfer without overstating v1.0 compute support.
+title: AWS and S3 support
+description: What AkôFlow currently implements for S3 transfers and where AWS setup remains incomplete.
---
-# Configure AWS
+# AWS and S3 support
-AkôFlow v1.0 accepts AWS credentials and can move artifacts through Amazon S3 or an S3-compatible service. It does **not** yet discover EC2 machine types or provision EC2 workers. Creating an AWS credential therefore enables storage operations; it does not create schedulable cloud capacity.
+AkôFlow can transfer objects to and from an `s3://bucket/prefix` endpoint when its server has `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`. Temporary credentials also require `AWS_SESSION_TOKEN`. You can set an endpoint and region for an S3-compatible service. Local tests cover the transfer code, but a run against an AWS account or test bucket has not yet been verified.
-## Configure an S3 credential
+This is **partial AWS support**. AkôFlow does not discover or provision EC2 workers. Saving an AWS cloud credential in AkôFlow does not make it available to S3 transfers; the server needs the environment variables above. For a transfer endpoint, omit `configuration.credentialRef` or set it to `env`. Other values fail with the default server credential resolver.
-Create a dedicated IAM principal or short-lived credential for the bucket used by AkôFlow. Grant access only to the required bucket and prefix. Typical operations require listing the bucket prefix and reading, writing, and deleting objects that AkôFlow owns.
+## Before using S3 transfers
-In Desktop, open **Settings → Credentials**, create an AWS cloud credential, and provide the access-key material expected by your deployment. Do not paste credentials into workflow, environment, or plan YAML. For temporary credentials, include the session token and replace the record before it expires.
+1. Ask the operator to provide the approved bucket, prefix, region, and server-side credential setup. Limit permissions to the required objects.
+2. Confirm that the server process receives the credentials. Avoid placing access keys in workflow or environment files.
+3. Use an `s3://bucket/prefix` transfer endpoint and check the resulting transfer and object evidence after a small run. A successful credential save or environment registration alone does not prove that data movement works.
-## Register S3 storage
+The **Infrastructure → Storage** screen browses storage already registered with an environment; it does not create an S3 storage connection. Its current S3 browser sends unsigned requests, even when the storage record has `credentialReference` or the server has AWS environment variables. Use a small transfer to check the separately configured transfer connector; it does not verify Desktop browsing.
-Create storage under **Infrastructure → Storage** and select the S3 adapter. Configure:
+For S3-compatible services, set `endpoint`, `region`, and `secure` in the transfer configuration if needed. The default endpoint is `s3.amazonaws.com`, and `secure` defaults to TLS. See the [environment YAML reference](/docs/reference/environment-yaml#connections-and-transfer-connectors) for the fields and [Storage](/docs/guides/infrastructure/storage) for browsing registered storage.
-- the bucket and optional AkôFlow prefix;
-- the AWS region;
-- the stored credential reference;
-- `s3.amazonaws.com` for AWS, or the explicit endpoint for an S3-compatible service;
-- TLS and path-style addressing according to the selected service.
-
-Test the storage connection before using it in an environment. A successful credential save only verifies the document shape; a storage test verifies endpoint reachability and authorization.
-
-## Common failures
-
-| Symptom | What to inspect |
-| --- | --- |
-| `AccessDenied` | IAM action, bucket policy, KMS permission, and prefix restriction |
-| `SignatureDoesNotMatch` | Region, endpoint, system clock, and access/secret pair |
-| Redirect to another region | Bucket region differs from the configured region |
-| TLS or hostname failure | Custom endpoint and certificate chain |
-| Upload succeeds but execution cannot read | Runtime binding uses a different storage or credential |
-
-## Compute capacity
-
-Do not create a nominal AWS execution environment expecting EC2 capacity to appear. Until the EC2 provider is implemented, connect existing AWS-hosted machines through the same SSH/direct-runtime path used for remote workers, or use Kubernetes when those machines belong to a cluster. The scheduler only sees capacity after a real resource and runtime binding are registered.
-
-See [HPC and SLURM clusters](./hpc-slurm) for the SSH connection pattern and [Storage](./storage) for artifact placement. The cloud support matrix is maintained in [Cloud capacity](./cloud-capacity).
+To run compute on existing AWS-hosted machines, connect them through a supported SSH or Kubernetes runtime. [Cloud capacity](/docs/guides/infrastructure/cloud-capacity) lists the provider limits. An end-to-end S3 tutorial remains pending validation with a disposable bucket and cleanup procedure.
diff --git a/docs/docs/guides/infrastructure/cloud-capacity.md b/docs/docs/guides/infrastructure/cloud-capacity.md
index 6be6cb8e..6c625c5e 100644
--- a/docs/docs/guides/infrastructure/cloud-capacity.md
+++ b/docs/docs/guides/infrastructure/cloud-capacity.md
@@ -1,24 +1,20 @@
---
-title: Cloud capacity and machine configuration
+title: Configure cloud capacity
+description: Choose a Google Cloud worker target, save it for planning, and inspect provisioning.
---
-A cloud environment separates four concerns:
+Use this guide after [connecting Google Cloud](/docs/tutorials/connect-cloud).
+Choose a machine from its catalog, save a capacity target for planning, and
+provision an instance when a run needs it. Google Cloud is the current compute
+provider; check [cloud provider support](/docs/guides/infrastructure/cloud-support) for AWS and object
+storage limits. For optional Ansible setup, create a
+[machine configuration](/docs/guides/infrastructure/machine-configurations) before saving the target.
-1. the cached provider catalog (machines, images, disks, zones, and prices);
-2. capacity targets that planners may select;
-3. versioned machine configurations expressed as Ansible playbooks;
-4. provisioned instances and their asynchronous lifecycle operations.
+For the API commands on this page, complete [API connection setup](/docs/tutorials/api-access) and register `research-gcp` through the [Google Cloud connection tutorial](/docs/tutorials/connect-cloud) first. Run the commands in the same Bash session.
-## Provider support in v1.0
-
-| Capability | Google Cloud | AWS |
-| --- | --- | --- |
-| Store provider credentials | Yes | Yes |
-| Discover compute machines, images, disks, zones, and prices | Yes | Not yet |
-| Provision compute capacity with Terraform | Yes | Not yet |
-| Transfer artifacts through object storage | GCS through configured storage adapters | S3 and S3-compatible endpoints |
-
-For a runnable Google Cloud setup, continue with [Configure Google Cloud](./gcp). For AWS, read [Configure AWS](./aws) before creating an environment: v1.0 can use AWS credentials for S3 data movement, but cannot create or discover EC2 workers. This distinction prevents a stored credential from being mistaken for a working compute provider.
+This procedure has not yet passed a live provision-and-destroy cycle in a
+disposable project. [Configure Google Cloud](/docs/guides/infrastructure/gcp) covers account access and
+the checks to perform before a real worker run.
## Synchronize the provider catalog
@@ -29,11 +25,11 @@ Open a cloud environment and select **Cloud capacity**. If no cached catalog exi
### Using the API
```bash
-curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- -X POST "$AKOFLOW_URL/environments/gcp-lab/cloud-catalog/refresh/"
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ -X POST "$AKOFLOW_API_URL/environments/research-gcp/cloud-catalog/refresh/"
-curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- "$AKOFLOW_URL/environments/gcp-lab/cloud-catalog/"
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ "$AKOFLOW_API_URL/environments/research-gcp/cloud-catalog/"
```
The GET endpoint returns `404` until a catalog has been synchronized. Provider credentials must already be stored and referenced by the cloud environment connection.
@@ -43,67 +39,67 @@ The GET endpoint returns `404` until a catalog has been synchronized. Provider c
### Using AkôFlow Desktop
1. Choose a catalog machine, image, disk, and disk size.
-2. Select a zone policy, provisioning mode, maximum instance count, and lifecycle policy.
+2. Select the region, provisioning mode, maximum instance count, and lifecycle policy.
3. Optionally attach an additional machine-configuration version.
-4. Save the target. It becomes a provisioned cloud resource available to planning.
-
-### Using the API
-
-```bash
-curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- -H 'Content-Type: application/json' -X POST \
- "$AKOFLOW_URL/environments/gcp-lab/cloud-capacity-targets/" \
- -d '{
- "name":"E2 standard worker",
- "provider":"gcp",
- "providerMachineType":"e2-standard-4",
- "region":"us-central1",
- "zonePolicy":"any",
- "imageReference":"projects/debian-cloud/global/images/family/debian-12",
- "architecture":"x86_64",
- "vcpu":4,
- "memoryMiB":16384,
- "provisioningMode":"standard",
- "maximumInstances":2,
- "lifecyclePolicy":"destroy-after-run",
- "configuration":{"diskType":"pd-balanced","diskSizeGiB":30,"network":"default"},
- "machineConfigurations":[{"configurationVersionId":"akoflow-scientific-worker-v4","executionOrder":0,"required":true,"enabled":true}]
- }'
-```
+4. Save the target. It becomes a capacity option available to planning; saving it does not create a VM.
-The server supplies the target ID and environment ID when omitted, enables the target, and creates the corresponding provisioned resource. Machine/image identifiers are provider values from the synchronized catalog.
+If you need a machine configuration, [create its version](/docs/guides/infrastructure/machine-configurations) before saving the target and attach that version's actual ID. Provisioning needs the referenced version.
-## Create and version a machine configuration
-
-### Using AkôFlow Desktop
-
-Open **Infrastructure → Machine configurations**. Create a named configuration, edit its Ansible playbook, validate it, and save a version. Existing capacity targets refer to a specific configuration-version ID, not to mutable editor contents.
+For a required zone, set `fixedZone` through the target API below.
### Using the API
-Validate YAML before saving it:
+Keep the `AKOFLOW_GCP_PROJECT` value from the validated [connection tutorial](/docs/tutorials/connect-cloud). Read a compatible Ubuntu image's `providerImageId` from the synchronized catalog. Confirm that `e2-standard-4` is available in the selected region, or replace the machine type and its CPU/memory values with a catalog match. Enter the approved daemon or bastion CIDR before the request is sent.
```bash
-curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- -H 'Content-Type: application/json' -X POST \
- "$AKOFLOW_URL/machine-configuration-validations/" \
- -d '{"playbookYaml":"---\n- name: Configure worker\n hosts: all\n become: true\n tasks:\n - name: Install curl\n ansible.builtin.package:\n name: curl\n state: present\n"}'
+set -o pipefail
+: "${AKOFLOW_GCP_PROJECT:?Complete the GCP connection tutorial first}"
+read -r -p 'Ubuntu providerImageId from the catalog: ' AKOFLOW_GCP_IMAGE_ID || exit 1
+read -r -p 'Approved SSH source CIDR: ' AKOFLOW_SSH_CIDR || exit 1
+[ -n "$AKOFLOW_GCP_IMAGE_ID" ] && [ -n "$AKOFLOW_SSH_CIDR" ] || exit 1
+
+jq -n --arg project "$AKOFLOW_GCP_PROJECT" \
+ --arg image "$AKOFLOW_GCP_IMAGE_ID" --arg cidr "$AKOFLOW_SSH_CIDR" \
+ --arg configVersion "${AKOFLOW_MACHINE_CONFIGURATION_VERSION_ID:-}" '{
+ name:"E2 standard worker",
+ provider:"gcp",
+ providerMachineType:"e2-standard-4",
+ region:"us-central1",
+ imageReference:$image,
+ architecture:"amd64",
+ vcpu:4,
+ memoryMiB:16384,
+ provisioningMode:"standard",
+ maximumInstances:2,
+ lifecyclePolicy:"destroy-after-run",
+ configuration:{
+ projectId:$project,
+ diskType:"pd-balanced",
+ diskSizeGiB:30,
+ network:"default",
+ sshSourceRanges:[$cidr]
+ }
+ } + (if $configVersion == "" then {} else {
+ machineConfigurations:[{
+ configurationVersionId:$configVersion,
+ executionOrder:1,
+ required:true,
+ enabled:true
+ }]
+ } end)' | curl --fail-with-body \
+ -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+ -H 'Content-Type: application/json' --data-binary @- \
+ "$AKOFLOW_API_URL/environments/research-gcp/cloud-capacity-targets/" \
+ -o cloud-target.json || exit 1
+
+AKOFLOW_CAPACITY_TARGET_ID=$(jq -er '.id' cloud-target.json) || exit 1
```
-Create the configuration and then its first version:
+The project ID is required by the current Terraform target; it is not copied from the environment connection. The built-in worker configuration requires `amd64`, even when Google Cloud labels a machine `X86_64`. If the CIDR is omitted, the Terraform target defaults SSH ingress to `0.0.0.0/0`.
-```bash
-curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- -H 'Content-Type: application/json' -X POST "$AKOFLOW_URL/machine-configurations/" \
- -d '{"id":"analysis-worker","name":"Analysis worker","description":"Packages used by analysis jobs"}'
-
-curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- -H 'Content-Type: application/json' -X POST \
- "$AKOFLOW_URL/machine-configurations/analysis-worker/versions/" \
- -d '{"version":1,"status":"published","playbookYaml":"---\n- name: Configure worker\n hosts: all\n tasks: []\n","compatibility":{"providers":["gcp"]}}'
-```
+Set `fixedZone` in the target if the worker must use a particular zone. Without it, the current Terraform module chooses the first active zone returned for the region. The saved `zonePolicy` field does not currently affect that choice.
-Validation checks playbook structure and returns `valid`, a content hash, and errors when present. It does not provision a machine or execute the playbook.
+The server supplies the target ID and environment ID when omitted, enables the target, and creates a schedulable capacity record; no VM is created yet. The command saves the returned ID for provisioning. The machine type must also come from the synchronized catalog.
## Provision and follow an instance
@@ -114,15 +110,26 @@ Open a cloud resource or the environment **Provisioning** tab and start provisio
### Using the API
```bash
-curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_TOKEN" \
- -H 'Content-Type: application/json' -X POST \
- "$AKOFLOW_URL/environments/gcp-lab/cloud-provisioning/" \
- -d '{"capacityTargetId":"})
-Use the back control below the breadcrumb to return to the logical parent. Its destination remains correct even when the page was opened from search or a notification.
+Use the back control below the breadcrumb to return to the parent record, including when you arrived through search or a notification.
-## Desktop and API are two views of the same operation
+## Find a record
-Most task guides contain two paths:
+Press ⌘+K on macOS, Ctrl+K on Windows or Linux, or select the search field. An empty search shows shortcuts to areas such as **Workflow definitions**, **Planning sessions**, and **Runs**.
-- **AkôFlow Desktop** explains the controls, validation, progress, and resulting detail page.
-- **API** shows the corresponding HTTP request and a minimal payload.
+Enter a name or ID to find records. Select a result or press Enter to open the first one; press Escape to close search. See [Find a record](/docs/guides/operations/find-records) for API search and result limits.
-The API path is useful for automation and reproducible experiments. The Desktop path is useful for exploration, comparison, and live monitoring. Records created through either path appear in the same interface.
-
-## Use global search deliberately
-
-Press ⌘+K on macOS, Ctrl+K on Windows or Linux, or select the search field in the title bar. With an empty field, Desktop lists navigation shortcuts such as **Workflow definitions**, **Planning sessions**, **Runs**, and **Provenance**. This is the fastest route when you know the product area but not its sidebar location.
-
-Once you enter text, the list changes to matching control-plane entities. A result identifies its record by title and ID, and may show a status and type; select it to open the corresponding record. Press Enter to open the first available result, or Escape to close the result list.
-
-Search is a locator, not an investigation surface. It does not replace the filtered lists or the provenance query tools: use the workflow, run, plan, environment, or provenance page after opening a result when you need status history, evidence, or a precise server-side filter. If Desktop says **Search is temporarily unavailable**, the search request failed; retry after confirming that the daemon connection is healthy.
+Open a result's detail page for its status and history. If Desktop says **Search is temporarily unavailable**, check the AkôFlow connection and try again.
## Global terminal
-Interactive commands open in the terminal panel fixed to the bottom of the application. The daemon owns the session and streams its output; closing a page does not make the renderer execute or manage a remote shell itself.
-
-Open an interactive session from a resource or runtime-aware operation, then use the terminal panel to inspect its output. The session detail page provides the durable record and log-export control; the panel is a live view, not a replacement for the persisted session evidence. See [Interactive console](./operations/interactive-console) for prerequisites, connection behavior, and recovery.
-
-## Read-only instances
+Interactive sessions open in the terminal panel at the bottom of the application. Closing a page does not close a remote session; close it from the panel when you finish.
-Some instance modes prevent write operations. The interface displays the active mode and guards creation, update, execution, and destructive actions. Read-only exploration, provenance, and audit remain available according to the daemon configuration.
+Open a session from a compatible resource, then use the panel to inspect its output. Export the log from the session detail page when you need a saved record. See [Interactive console](/docs/guides/operations/interactive-console) for prerequisites and recovery.
## Continue
-Start with [your first end-to-end run](./workflows/first-run), or connect [execution infrastructure](./infrastructure/environments).
+To create and run one workflow in Desktop, follow the [first local run](/docs/guides/workflows/first-local-run). For a simulation through a separately managed API, use the [SimGrid tutorial](/docs/guides/workflows/first-run). To connect another target, see [Environments](/docs/guides/infrastructure/environments).
diff --git a/docs/docs/guides/operations/credentials-and-ssh.md b/docs/docs/guides/operations/credentials-and-ssh.md
index 651c4010..bc98b622 100644
--- a/docs/docs/guides/operations/credentials-and-ssh.md
+++ b/docs/docs/guides/operations/credentials-and-ssh.md
@@ -1,11 +1,15 @@
---
-title: Credentials and SSH service keys
-description: Store credentials in the Engine, assign SSH service keys, and keep private material outside workflow definitions.
+title: Manage SSH service keys
+description: Generate or import an SSH key and assign it to a saved connection.
---
-# Credentials and SSH service keys
+# Manage SSH service keys
-AkôFlow stores secret material in the Engine and places a `credentialRef` in connection definitions. The renderer sends a secret only when it is first saved or imported; list operations return references or public metadata, never the original private key or bearer token.
+Use this guide when an SSH connection needs a key managed by AkôFlow. Generate or import the key, authorize its public half on the remote host, then assign its reference to the saved connection. Keep the private key out of workflow definitions.
+
+For other providers, use [Configure Kubernetes](/docs/guides/infrastructure/kubernetes) to store a cluster token or [Connect Google Cloud](/docs/tutorials/connect-cloud) to validate and store a service-account credential.
+
+AkôFlow returns public metadata and a credential reference when you list managed SSH keys; it does not return the original private key.
## Generate an SSH service key
@@ -16,18 +20,17 @@ AkôFlow stores secret material in the Engine and places a `credentialRef` in co
3. Select **Generate key**.
4. Copy the public key and authorize it on every SSH hop required by the target—for example, both a gateway and its HPC login node.
-The Engine generates an Ed25519 key. IDs must start with an ASCII letter or digit, may then contain letters, digits, `_` or `-`, and may contain at most 64 characters. The private file is stored with mode `0600`.
+The AkôFlow server generates an Ed25519 key. IDs must start with an ASCII letter or digit, may then contain letters, digits, `_` or `-`, and may contain at most 64 characters. The private file is stored with mode `0600`.
### Using the API
-```bash
-export AKOFLOW_URL='http://127.0.0.1:})
+
-Set the endpoint and token before using the checks below:
+For the command-line checks below, complete [API connection setup](/docs/tutorials/api-access) first.
-```bash
-export AKOFLOW_URL='http://127.0.0.1:.default})
*Choose **Generate plans** to compare candidate schedules. The target selector keeps real execution scopes separate from simulation-only scopes; PRISM Cost and PRISM Time are exclusive objectives, while HEFT is a comparison baseline.*
+The server's available algorithms are listed by `GET /planning-algorithms/`. A session may also include a deadline, budget, or directed interference matrix; HEFT does not use that matrix for its placement. See [PRISM and HEFT](/docs/explanations/prism-and-heft) for the prediction models and [planning states](/docs/reference/planning-and-execution-states) for candidate and session fields.
+
### Manual plans
Choose the manual planning mode when placement is known in advance. Select a scope and topology, then assign every activity to a compatible runtime and resource and provide its expected duration. The Desktop computes a dependency-aware schedule and submits the complete plan for validation.
### Imported plans
-The plans API also accepts a complete plan as imported data. Imported IDs must refer to an existing workflow version, execution scope, topology, and resources; the server validates the plan before saving it.
+The plans API also accepts a complete plan as imported data. Imported IDs must refer to an existing workflow version, execution scope, topology, and resources; the server validates the plan before saving it. That validation does not check runtime bindings. Confirm an enabled, mode-compatible binding for every assigned resource before starting execution.
## Using the API
+Complete [API connection setup](/docs/tutorials/api-access) before running the commands below.
+
First discover the algorithms available in the running instance:
```bash
-curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
"$AKOFLOW_API_URL/planning-algorithms/"
```
-Create an automatic planning session. The IDs below match the repository's simulation example:
+Create an automatic planning session. The IDs below refer to the environment, scope, topology, and workflow registered in the [SimGrid first-run sequence](/docs/guides/workflows/first-run). Complete those registration steps first, or replace all four IDs with records from your own instance:
```bash
curl --fail-with-body \
@@ -77,31 +65,69 @@ curl --fail-with-body \
"$AKOFLOW_API_URL/planning-sessions/"
```
-Creation returns `202 Accepted`. Poll the session and list its candidates:
+Creation returns `202 Accepted`. Poll the session until its status is `completed`, then list its candidates. This lets you compare the final ranks:
```bash
-curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
"$AKOFLOW_API_URL/planning-sessions/planning-simulation-example/"
-curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
+curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
"$AKOFLOW_API_URL/planning-sessions/planning-simulation-example/candidates/"
```
-Read a candidate before selecting it, then promote it to a plan:
+List the candidate IDs, choose one after comparing the candidates, and inspect it before selection:
```bash
-curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
- "$AKOFLOW_API_URL/planning-sessions/planning-simulation-example/candidates/})
-A planning request is persisted as a session and publishes a queue job. An execution request first publishes a queue job; a workflow `ExecutionRun` is created only when the daemon starts processing that job. Consequently, an accepted execution request may not yet appear in `GET /execution-runs/`.
+A planning request is persisted as a session and publishes a queue job. An execution request first publishes a queue job; the worker validates it before creating an `ExecutionRun`. An accepted request may not yet appear in `GET /execution-runs/`, and an invalid queued request may never produce a run.
## Planning session
@@ -34,7 +34,9 @@ The cancellation endpoint returns a conflict for a completed or failed session,
Each selected algorithm creates an `AlgorithmRun` within the session. It uses the same status values: `queued`, `running`, `completed`, `failed`, and `cancelled`.
-Algorithm runs execute sequentially under the session's coordinator. A session can therefore be `running` while one algorithm run is `running` and later runs remain `queued`. A failed algorithm run does not automatically fail the session: other selected algorithms continue. The session fails only if there are no valid candidates after all work has finished. `progress` is a fraction between the completed algorithm runs; it is not a count of evaluated schedule states. `estimate` carries a predicted planning duration, search-space metadata, and confidence for that one algorithm run.
+Algorithm runs execute sequentially. A session can be `running` while one algorithm run is `running` and later runs remain `queued`. If one algorithm fails, the others continue. The session fails only when none produces a valid candidate.
+
+`progress` is a fraction based on completed algorithm runs, not a count of evaluated schedules. `estimate` carries a predicted planning duration, search-space metadata, and confidence for one algorithm run.
## Candidates are not state machines
@@ -42,7 +44,7 @@ A `PlanCandidate` has no `status` field. It is an immutable generated option ass
| Field | Meaning |
| --- | --- |
-| `feasible` | The candidate passed plan validation and may be selected. Infeasible candidates cannot be promoted. |
+| `feasible` | The candidate passed plan validation and may be selected. It does not confirm a runtime binding for execution. Infeasible candidates cannot be promoted. |
| `rank` | Comparison order after session completion. Lower rank is preferred by the common ranking step. |
| `paretoOptimal` | The candidate is on the non-dominated time/cost frontier. |
| `dominated` | Another feasible candidate is no worse in both predicted metrics and better in at least one. |
@@ -52,7 +54,7 @@ Candidates may appear while an algorithm run and its parent session are still `r
## Selecting a candidate and schedule plans
-A `SchedulePlan` does **not** have a lifecycle status. It is the canonical persisted plan containing assignments, predicted metrics, algorithm/source information, and lifecycle actions. It can originate from a manual plan, an import, or a selected candidate.
+A `SchedulePlan` does **not** have a lifecycle status. It is the saved plan containing assignments, predicted metrics, algorithm/source information, and lifecycle actions. It can originate from a manual plan, an import, or a selected candidate.
`POST /planning-sessions/{sessionId}/candidates/{candidateId}/select/` promotes a feasible candidate. The API verifies that the candidate belongs to the session and is feasible, stores its embedded plan if it is new, and records `selectedCandidateId` and `selectedPlanId` on the session. It currently does not require the session to be `completed`, so clients should normally wait for completed ranking before selecting unless they deliberately choose an early candidate.
@@ -60,7 +62,7 @@ Selecting another feasible candidate updates the session's selected IDs; it does
## Workflow execution runs
-Workflow execution uses a distinct `ExecutionRun` lifecycle. Submit `POST /execution-runs/`; it returns an accepted queue job. Once the daemon consumes that job, the supervisor creates the run and begins execution.
+Workflow execution uses a distinct `ExecutionRun` lifecycle. `POST /execution-runs/` returns an accepted queue job. Once the worker validates that job, the supervisor creates the run and begins execution. If worker validation fails, no run record is created.
| State | How it is reached | Meaning | Terminal? |
| --- | --- | --- | --- |
@@ -77,7 +79,7 @@ Task records offer finer-grained evidence than the workflow-run badge:
| Record | States | Notes |
| --- | --- | --- |
-| `TaskExecution` | `blocked`, `ready`, `preparing`, `running`, `completed`, `failed`, `cancelled` | The domain supports all values. The current supervisor persists running and completed task records for normal execution; failure/cancellation can be recorded from runtime outcomes. |
+| `TaskExecution` | `blocked`, `ready`, `preparing`, `running`, `completed`, `failed`, `cancelled` | The domain supports all values. The current workflow supervisor persists `running`, `completed`, and `failed`; a stopped or failed runtime handle produces a failed task. The other values are not a normal workflow-run progression today. |
| `ActivityHandle` | `starting`, `running`, `completed`, `failed`, `stopped` | Runtime adapter identity, such as a Kubernetes Job, Slurm Job, PID, or simulation event. `stopped` is surfaced as a failed task with the handle failure reason in task reads. |
Task-stage totals such as `queueSeconds`, `transferSeconds`, and `runtimeSeconds` are accumulated over all tasks. They are diagnostic totals, not wall-clock makespan. Use the run's `makespanSeconds` and task timestamps to understand elapsed time.
@@ -92,4 +94,4 @@ Task-stage totals such as `queueSeconds`, `transferSeconds`, and `runtimeSeconds
| Wait for execution | `GET /execution-runs/{runId}/` after the daemon creates the run | Run is `completed` or `failed`. |
| Explain an observed result | Run projection tasks, transfers, events, and Plan vs execution view | Task/transfer records account for the observed critical path. |
-Related material: [planning a workflow](../guides/workflows/planning), [execution evidence](../guides/workflows/executions), [execution scopes and topologies](./execution-scopes-and-topologies), and [provenance and audit](../guides/data/provenance-and-audit).
+Related material: [planning a workflow](/docs/guides/workflows/planning), [execution evidence](/docs/guides/workflows/executions), [execution scopes and topologies](/docs/reference/execution-scopes-and-topologies), and [provenance and audit](/docs/guides/data/provenance-and-audit).
diff --git a/docs/docs/runtimes.md b/docs/docs/runtimes.md
index 06d1432f..e3559aea 100644
--- a/docs/docs/runtimes.md
+++ b/docs/docs/runtimes.md
@@ -2,15 +2,18 @@
id: runtimes
title: Runtime adapters
sidebar_label: Runtime adapters
+description: How AkôFlow maps planned activities to local, HPC, Kubernetes, cloud, and simulated runtimes.
---
-A runtime adapter translates an assigned activity into operations on an execution technology. Runtimes belong to an environment version and connect to resources through bindings. Workflows do not select a runtime through a legacy top-level YAML `runtime` field; a selected plan assigns resources and execution resolves their bindings.
+A runtime adapter translates an assigned activity into operations on an execution technology. Runtimes belong to an environment version and connect to resources through bindings. Execution resolves the binding for each planned assignment.
-This explanation focuses on the adapter boundary. Read [system architecture](./concepts) for the surrounding records and [execution control plane](./engine) for how the supervisor uses adapters.
+This explanation focuses on runtime adapters. Read [Architecture internals](/docs/modules) for the surrounding services and [Execution control plane](/docs/engine) for how the server uses adapters.
## Runtime model
-Each runtime declares `id`, name, driver, `execution` or `simulation` mode, optional role/configuration, and capabilities such as batch, interactive, container, GPU, MPI, shared storage, staging, cancellation, log streaming, and simulation.
+Each runtime has an ID, driver, and `execution` or `simulation` mode. Its configuration and declared capabilities describe what the driver can do. For example, a batch runtime may declare container and shared-storage support; these declarations do not verify a particular cluster or account. The [environment reference](/docs/reference/environment-yaml) lists the fields.
+
+The portable workflow document does not select a runtime through a top-level YAML `runtime` field. A plan assigns resources; execution resolves their runtime bindings.
Adapters implement `Modes`, `Start`, `Inspect`, and `Stop`. A common handle keeps provider identifiers out of orchestration code.
@@ -24,9 +27,9 @@ Adapters implement `Modes`, `Start`, `Inspect`, and `Stop`. A common handle keep
| `slurm` | Batch submission or explicit direct target | real |
| `simgrid` | Plan/activity simulation | simulation |
| `cloud` | Capacity resolved to a concrete runtime allocation | real via lifecycle binding |
-| `serverless` | Reserved domain capability | depends on registered provider |
+| `serverless` | Schema value only; no built-in adapter | unavailable |
-A driver value in the domain model does not prove that its provider is configured in a particular instance.
+A driver value in the domain model does not prove that its provider is implemented or configured in a particular instance. The current server has no serverless runtime adapter.
## Local
@@ -46,7 +49,7 @@ Slurm renders an `sbatch` script from activity, resource, and preparation contex
## SimGrid
-Simulation is a mode, not a fake infrastructure connection. It uses frozen inventory, profiles, topology, transfer costs, and optional interference data to produce a trace without starting jobs. Participating activities declare the `simulation` capability and simulation definition.
+Simulation uses frozen inventory, profiles, topology, transfer costs, and optional interference data to produce a trace without starting jobs. Participating activities declare the `simulation` capability and simulation definition.
## Cloud
@@ -63,21 +66,12 @@ Inventory refresh must not mutate the frozen inputs of an existing planning sess
## Data access
-Execution is preceded by preparation. Routes may use an existing verified location, shared storage, destination pull, source push, gateway, runtime-local, or direct-runtime transfer. Implementations include artifact store, filesystem, rsync/SSH, Kubernetes exec, HTTP, S3-compatible storage, and GCS. An adapter must reject an uncommitted preparation gate.
-
-## Choose a target
-
-In Desktop:
+Execution is preceded by preparation. Routes may use an existing verified location, shared storage, destination pull, source push, gateway, runtime-local, or direct-runtime transfer. Implemented connectors include artifact store, filesystem, rsync/SSH, Kubernetes exec, HTTP download, and S3-compatible transfer. Direct `gs://` transfer is unavailable in the current server; the GCS connector returns an error until a deployment supplies a working transfer agent.
-1. create an environment and connection;
-2. validate it and run discovery;
-3. review resources, bindings, storage, and capabilities in the inventory;
-4. include the published version in an execution scope;
-5. plan the workflow and inspect candidate assignments;
-6. select a plan and start the required execution mode.
+## User procedures
-API clients perform the equivalent environment, check, discovery, scope, planning, selection, and execution operations. Use the generated API Reference for exact current routes.
+To connect infrastructure, use [Create and inspect environments](/docs/guides/infrastructure/environments). For the task flow after registration, follow [Define execution scopes](/docs/guides/infrastructure/execution-scopes), [Plan a workflow](/docs/guides/workflows/planning), and [Execute and monitor a workflow](/docs/guides/workflows/executions). Those guides keep the user steps separate from adapter details here.
## Provider extension boundary
-A complete provider generally needs an adapter, resolver/factory registration, probing and discovery for external infrastructure, endpoint/transfer integration, capability declarations, and tests for start, inspect, stop, failures, and artifact observation. Provider behavior stays behind ports; workflow, planning, and execution domain objects remain provider-neutral.
+Adding a provider starts with an adapter registered for its driver and mode. External infrastructure also needs a connection check and discovery. Data access may need a transfer route. Test activity start, inspection, stop, failures, and output observation before documenting the provider as supported. Keep these provider details behind the runtime interface so workflow and plan records remain provider-neutral.
diff --git a/docs/docs/showcase/edge-cloud-simulation.mdx b/docs/docs/showcase/edge-cloud-simulation.mdx
index 4e885bf3..892c9a47 100644
--- a/docs/docs/showcase/edge-cloud-simulation.mdx
+++ b/docs/docs/showcase/edge-cloud-simulation.mdx
@@ -10,9 +10,9 @@ import {FileList, WorkflowDiagram} from '@site/src/components/WorkflowShowcase';
Run with AkôFlow Desktop
+Inspect the API run in Desktop
+Submit the versioned bundle through the API path below. Desktop can inspect its records only when connected to that same server. The packaged Desktop manages a separate local server by default.
-
-
- Open Infrastructure → Environments and create a simulation environment matching
environment.yaml. Add the SimGrid runtime, then bind it to the edge and cloud resources. Set cores, speedup, price, boot, and container values before planning.
- - Open Infrastructure → Execution scopes and create the scope from
scope.yaml. Attach a topology matchingtopology.yaml: it must include both directions of the 100 Mbit/s link. A scope without this link cannot predict the cross-resource transfers in this example.
- - Open Workflows → Definitions and import
workflow.yaml. Open the imported workflow and check the Definition graph: it must contain three activities and the two arrowsprepare → analyze → summarize. Select an activity to confirm that it is simulatable and has its own duration profile.
- - To reproduce the documented placement, choose Generate plan, select Create manually, choose the simulation scope, then place
prepareandsummarizeon the edge andanalyzeon cloud. The portableplan-request.yamlis the API equivalent of this choice.
- - To compare algorithms instead, choose Generate plans, select the same scope, and run the desired candidates. Expand a candidate to inspect its Gantt chart before selecting it. -
- Start the selected simulation. On the completed run, use Data for the two data flows and Plan vs execution for predicted versus observed makespan and cost. +
- Open Infrastructure → Environments and inspect the saved edge and cloud resources. +
- Open Workflows → Definitions and confirm the three-activity graph. +
- Open the completed run. Use Data to inspect two transfers and Plan vs execution to compare prediction with observation.
A Desktop-only submission of this complete bundle has not been verified. The current Desktop navigation does not expose link creation; the verified API path registers the network model supplied here.
} api={Run through the API
-Run this in a fresh AkôFlow instance, or change every ID in the six YAML files first. The API treats these identifiers as persistent objects and rejects duplicate IDs. From the repository root, set the daemon address and token, then submit the complete bundle:
-{`export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api"
-export AKOFLOW_API_TOKEN=""
-
-post_yaml() {
- curl --fail-with-body \\
- -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \\
- -H 'Content-Type: application/yaml' \\
- --data-binary "@$2" "$AKOFLOW_API_URL/$1/"
-}
-
-post_yaml environments examples/simulation/environment.yaml
-post_yaml execution-scopes examples/simulation/scope.yaml
-post_yaml network-topologies examples/simulation/topology.yaml
-post_yaml workflow-definitions examples/simulation/workflow.yaml
-post_yaml schedule-plans examples/simulation/plan-request.yaml
-post_yaml execution-runs examples/simulation/execution-request.yaml`} Complete API connection setup. Run this in a fresh AkôFlow instance, or change every ID in the six YAML files first. Clone the v1.0.8 files, or use an existing matching checkout, then submit the bundle:
+{`git clone --branch v1.0.8 --depth 1 https://github.com/UFFeScience/akoflow.git akoflow-showcase
+cd akoflow-showcase
+sh examples/simulation/run.sh`}Submitting execution-runs acknowledges the request; it does not mean the execution has completed. Poll the immutable run projection until status is completed:
{`curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \\
+ {`curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \\
"$AKOFLOW_API_URL/execution-runs/simulation-example-run-v1/"`}
Run with AkôFlow Desktop
+Inspect the API run in Desktop
+Use the verified Kind and API procedure below. Desktop can inspect the run when it connects to that same server; the packaged Desktop uses a separate local server by default.
-
-
- Create the Kind cluster and apply
akoflow-access.yamlandstorage.yaml.
- - Generate a short-lived ServiceAccount token. In Infrastructure → Environments, create the Kubernetes connection and store the token through the credential flow; do not paste it into the workflow. -
- Test the connection and run discovery. Confirm that the Kind worker appears as a schedulable resource. -
- Create a scope and topology matching the supplied YAML, then import
dag.yamlunder Workflows → Definitions.
- - Create a manual plan or generate candidates, select the Kind resource, and start a Real execution. -
- Inspect activity logs, generated files, artifacts, timeline, events, and provenance after completion. +
- Open the Kubernetes environment and confirm the discovered Kind worker. +
- Open the imported two-activity workflow and its saved plan. +
- Open the completed run to inspect Job logs, transferred data, output files, and events. Follow provenance when its explorer is configured.
A complete Desktop-only Kind submission has not been verified.
} api={Run through the API
-After creating the cluster and token as described in the complete Kind README, submit the same objects:
-{`export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api"
-export AKOFLOW_API_TOKEN=""
-
-for pair in \\
+ Complete API connection setup and clone v1.0.8, or use an existing matching checkout:
+ {`git clone --branch v1.0.8 --depth 1 https://github.com/UFFeScience/akoflow.git akoflow-showcase
+cd akoflow-showcase`}
+ From that checkout, follow the Kind README to create the cluster and token. Then use a fresh instance and submit:
+ {`for pair in \\
"environments examples/kind/environment.yaml" \\
"execution-scopes examples/kind/scope.yaml" \\
"network-topologies examples/kind/topology.yaml" \\
@@ -71,4 +70,4 @@ A successful run produces two Kubernetes Jobs, a workspace PVC for each activity
The checked-in bundle was executed from a clean Kind cluster on 2026-09-11 as `kind-dag-run-v8`: both activities completed, 9 bytes were transferred, and both files had checksum `sha256:cb064c1339ffa3d7777bcb0459de3dceddb9146156dde58065a4ac826b029aa7`. Its observed makespan was 17.776 s. Kubernetes scheduling and Pod startup are included in that wall-clock result.
-If the consumer Job remains `Pending`, use `kubectl describe pod ` to inspect PVC/node affinity. The full setup, verification, and cleanup procedure is in the [Kind README](https://github.com/UFFeScience/akoflow/tree/main/examples/kind).
+If the consumer Job remains `Pending`, use `kubectl describe pod ` to inspect PVC/node affinity. The full setup, verification, and cleanup procedure is in the [Kind README](https://github.com/UFFeScience/akoflow/tree/v1.0.8/examples/kind).
diff --git a/docs/docs/showcase/local-direct-execution.mdx b/docs/docs/showcase/local-direct-execution.mdx
index 76bae307..607c49d8 100644
--- a/docs/docs/showcase/local-direct-execution.mdx
+++ b/docs/docs/showcase/local-direct-execution.mdx
@@ -1,6 +1,6 @@
---
title: Local direct execution
-description: Run a verified host-local workflow and inspect its output artifact through AkôFlow Desktop or the API.
+description: Run a verified host-local workflow through the API and inspect its output artifact.
---
import InterfaceApiTabs from '@site/src/components/InterfaceApiTabs';
@@ -10,58 +10,59 @@ import {FileList, WorkflowDiagram} from '@site/src/components/WorkflowShowcase';
- Environment YAML ↓
- Execution scope YAML ↓
- Network topology YAML ↓
- Workflow YAML ↓
- Manual plan envelope ↓
- Execution envelope ↓
- Submission script ↓
+ Environment YAML ↓
+ Execution scope YAML ↓
+ Network topology YAML ↓
+ Workflow YAML ↓
+ Manual plan envelope ↓
+ Execution envelope ↓
+ Submission script ↓
- Run with AkôFlow Desktop
+ Inspect the API run in Desktop
+ Submit the versioned bundle through the API path below, then open Desktop connected to the same server.
- - In Infrastructure → Environments, create the local environment and its
local-host resource from environment.yaml. Keep its execution target as Direct.
- - Create the scope and topology from the supplied YAML. This one-host Showcase deliberately has no network links.
- - In Workflows → Definitions, import
workflow.yaml. Open its definition and confirm that write-report is a real activity assigned to the local runtime.
- - Create a manual plan with
write-report on local-host, or import plan.yaml through the plan API. Start a Real execution.
- - When the run is complete, open its activity details and artifacts. Verify that
result.txt is listed as a created file.
+ - Open the local environment and confirm that
local-host is the assigned resource.
+ - Open the completed run and inspect the activity's artifacts. Confirm that
result.txt is listed as a created file.
- The host that runs Desktop is not necessarily the execution host; the daemon's host is. Check that distinction before starting a direct run.
+ The command runs on the server host, which may differ from the Desktop host. Desktop-only submission of this bundle has not been verified.
Run through the API
-From the repository root, submit the versioned files in their required order:
-{`export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api"
-# Set AKOFLOW_API_TOKEN too when this daemon requires authentication.
+ Complete API connection setup. Clone v1.0.8, or use an existing matching checkout, then run the script from its root:
+ {`git clone --branch v1.0.8 --depth 1 https://github.com/UFFeScience/akoflow.git akoflow-showcase
+cd akoflow-showcase
sh examples/local/direct-hello/run.sh
curl --fail-with-body \
+ -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \
"$AKOFLOW_API_URL/execution-runs/local-direct-hello-run-v1/"`}
- When the daemon requires a token, set AKOFLOW_API_TOKEN; the supplied script adds the matching bearer header to each request.
+ The supplied script adds a bearer header when AKOFLOW_API_TOKEN is set.
Explore with AkôFlow Desktop
+Inspect the API run in Desktop
+Run the versioned API script below, then open Desktop connected to that same server. The packaged Desktop uses its own local server by default.
-
-
- Create a simulation environment with M1 (one core), M2 (three cores), and M3 (one core), and bind SimGrid to each resource. -
- Create the scope and attach the two shared, bidirectional 80 Gbit/s links from
topology.yaml.
- - Import
workflow.yaml. In its Definition graph, confirm thatt1fans out to three activities and that all three converge ont5.
- - Choose Generate plan. Use Create manually to reproduce the checked-in M1 → M2 → M3 assignment, or use Generate plans to compare PRISM Cost, PRISM Time, and HEFT on the same scope. -
- Expand a candidate Gantt. Verify that `t2`, `t3`, and `t4` occupy different M2 cores; then select the plan and start the simulation. -
- On the completed run, open Data to inspect six transfers and Plan vs execution to compare the 36-second estimate with the observed trace. +
- Open the workflow definition and confirm that
t1fans out tot2,t3, andt4, which converge ont5.
+ - Open the saved plan and check that the three middle activities use different M2 cores. +
- Open the completed run. Use Data for the six transfers and Plan vs execution for timing.
The API script registers the two network links used by this result. The current Desktop navigation does not expose link creation, and a full Desktop-only submission has not been verified.
} api={Register, plan, and execute through the API
-From a fresh instance, run the versioned script. It submits the environment, scope, topology, workflow, manual plan, and execution envelope in dependency order:
-{`export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api"
-export AKOFLOW_API_TOKEN=""
+ Complete API connection setup and use a fresh AkôFlow instance. Clone v1.0.8, then run the script from that checkout. It submits the environment, scope, topology, workflow, manual plan, and execution envelope in order:
+ {`git clone --branch v1.0.8 --depth 1 https://github.com/UFFeScience/akoflow.git akoflow-showcase
+cd akoflow-showcase
bash examples/simulation/30gb-fanout/run.sh`}
Poll the run until it reports completed:
- {`curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \\
+ {`curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \\
"$AKOFLOW_API_URL/execution-runs/simgrid-30gb-fanout-run-v1/"`}
Run with AkôFlow Desktop
+Inspect the API run in Desktop
+Submit the bundle with the versioned API script below, then use Desktop connected to that server to inspect it.
-
-
- Open Infrastructure → Environments and create a simulation environment that matches
environment.yaml. Add the SimGrid runtime and bind it to M1, M2, and M3. M2 must have 50 schedulable cores.
- - Open Infrastructure → Execution scopes, create the scope and topology from the supplied YAML, then attach the environment version. The links are present for consistency with the other examples but carry no data in this workflow. -
- Open Workflows → Definitions and import
workflow.yaml. Its Definition view must contain 100 unconnected worker nodes, each with a 10-second simulation duration.
- - Choose Generate plan, then Create manually. Select the simulation scope and assign workers 001–050 to M2 cores 0–49. Assign workers 051–100 to the same cores after the first wave. The checked-in plan is the API representation of that placement. -
- Expand the plan Gantt chart before starting it. It should show 50 used M2 core lanes, with two adjacent 10-second bars per lane. Start the simulation and compare its plan with the completed run. +
- Open the workflow definition and confirm that it has 100 independent workers with 10-second simulation profiles. +
- Open the saved plan and check for 50 M2 core lanes with two waves of activities. +
- Open the completed run and compare its 20-second makespan with the accumulated activity time.
Desktop-only creation and submission of this 100-activity bundle have not been verified.
} api={Run through the API
-The checked-in script submits the objects in dependency order and stops on the first HTTP error. Run it against a fresh instance, or change every persistent ID in the bundle:
-{`export AKOFLOW_API_URL="http://127.0.0.1:8080/akoflow-api"
-export AKOFLOW_API_TOKEN=""
+ Complete API connection setup. The script submits objects in dependency order and stops on the first HTTP error. Use a fresh instance or change every persistent ID in the bundle, then run it from a v1.0.8 checkout:
+ {`git clone --branch v1.0.8 --depth 1 https://github.com/UFFeScience/akoflow.git akoflow-showcase
+cd akoflow-showcase
bash examples/simulation/50core-fanout/run.sh`}
Poll the run projection until its status is completed:
- {`curl -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \\
+ {`curl --fail-with-body -H "Authorization: Bearer $AKOFLOW_API_TOKEN" \\
"$AKOFLOW_API_URL/execution-runs/simgrid-50core-workers-run-v2/"`}
Inspect it with AkôFlow Desktop
--
-
- Start the fixture daemon as described below, then configure Desktop to use
http://127.0.0.1:18082/akoflow-api.
- - Under Infrastructure → Environments, import or recreate
environment.yaml. Confirm theslurmruntime is bound to the batch partition.
- - Create the scope and empty topology, then import
workflow.yamlunder Workflows → Definitions.
- - Import the manual plan or create the same one-activity assignment to
slurm-fixture-partition. Start a Real execution.
- - Open the completed run. The activity's artifacts must list the created
result.txtfile.
-
Desktop is optional for this fixture. The API path below submits the same versioned files and is the reproducible verification route.
+Inspect the API run in a connected client
+Run the fixture through the API path below. If a development Desktop client is configured for that same fixture server, open the completed run and verify that its activity artifacts include result.txt.
The packaged Desktop does not automatically connect to the fixture server on port 18082. A Desktop-only fixture submission has not been verified.
Run the fixture through the API
-In one terminal, start the isolated daemon from the repository root:
-{`sh examples/slurm/local-fixture/start-fixture.sh`}Wait until it is listening, then use a second terminal:
+Clone v1.0.8, or use an existing matching checkout. In one terminal, start the isolated daemon from its root:
+{`git clone --branch v1.0.8 --depth 1 https://github.com/UFFeScience/akoflow.git akoflow-showcase
+cd akoflow-showcase
+sh examples/slurm/local-fixture/start-fixture.sh`}Wait until it is listening, then open a second terminal at the root of the same checkout:
{`export AKOFLOW_API_URL="http://127.0.0.1:18082/akoflow-api"
sh examples/slurm/local-fixture/run.sh
curl --fail-with-body \\
+ -H "Authorization: Bearer \${AKOFLOW_API_TOKEN}" \\
"$AKOFLOW_API_URL/execution-runs/slurm-fixture-run-v1/" \\
| jq -r '.run.status'`}The daemon uses no token by default. If your local configuration requires one, set AKOFLOW_API_TOKEN before running the supplied script.