docs: replace structural text diagrams with svg

Author: ovvesley

docs/docs/concepts.md

@@ -17,17 +17,7 @@ This is an explanation of the records and their boundaries. For the exact YAML f
 
 ## The record chain
 
-```text
-Environment definition -> published environment version -> execution scope
-                                                        |
-Workflow definition  -> immutable workflow version ----+-> planning session
-                                                               |
-                                                        candidate -> selected plan
-                                                                              |
-                                                                        execution run
-                                                                              |
-                                      task attempts, transfers, artifacts, provenance, audit
-```
+<img src={useBaseUrl('/img/architecture/record-chain.svg')} alt="Environment definitions become published versions and scopes; immutable workflow versions join planning sessions; selected plans lead to execution runs and observed task, transfer, artifact, provenance and audit records." />
 
 The arrows express references, not a single mutable object. A planning session preserves a snapshot of the workflow, scope, inventory, topology, profiles, constraints, and selected algorithms. A later discovery refresh can create new inventory for future sessions, but it does not change that earlier comparison.
 

docs/docs/engine.md

@@ -1,27 +1,20 @@
 ---
+
 id: engine
 title: Execution control plane
 sidebar_label: Execution control plane
 description: How the daemon persists work, dispatches planning and execution, and recovers runtime state.
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 AkôFlow's server is a persistent control-plane daemon. The HTTP API validates and stores requests; a durable event loop dispatches work that may take longer than one request. The daemon is therefore responsible for recording intent and state transitions, while runtime adapters perform provider-specific work.
 
 This is an orchestration explanation, not an API contract. Use the [planning and execution state reference](./reference/planning-and-execution-states) for states and endpoints.
 
 ## From request to durable work
 
-```text
-HTTP request
-   |
-validate + persist
-   |
-typed queue job
-   |
-persistent dispatcher ----> planning handler
-                      \---> execution handler
-                      \---> cloud, transfer, monitoring, and maintenance handlers
-```
+<img src={useBaseUrl('/img/architecture/engine-request-dispatch.svg')} alt="An HTTP request is validated and persisted as a typed queue job, then dispatched to planning, execution, cloud, transfer, monitoring or maintenance handlers." />
 
 The API can acknowledge a request before its job starts. In particular, an execution request is accepted into the durable queue; the workflow execution run is created when the daemon begins processing that job. In read-only instance mode the server serves inspection APIs but does not run mutating background work.
 

docs/docs/explanations/evidence-and-provenance.md

@@ -1,27 +1,20 @@
 ---
+
 id: evidence-and-provenance
 title: Plan-versus-observed evidence and provenance
 sidebar_label: Evidence and provenance
 description: How AkôFlow preserves predictions, runtime observations, artifacts, lineage, and audit history.
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 AkôFlow does not overwrite a plan with a completed run. It preserves the prediction used to choose a placement and records the execution evidence beside it. This makes disagreement inspectable: it can indicate an inaccurate model, an unexpected runtime condition, or a different data-preparation path.
 
 Use [Provenance and audit](../guides/data/provenance-and-audit) to query the records. This explanation describes why they remain separate.
 
 ## Two timelines for one selected plan
 
-```text
-selected plan
-  assignments + predicted metrics + predicted timing
-                         |
-                         v
-                   execution run
-                         |
- task attempts + handles + transfers + logs + artifact manifests
-                         |
-                execution trace and provenance records
-```
+<img src={useBaseUrl('/img/architecture/evidence-provenance-timeline.svg')} alt="A selected plan holds predictions; the execution run produces runtime observations; those observations form the execution trace and provenance records." />
 
 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.
 

docs/docs/explanations/network-modeling.md

@@ -1,23 +1,20 @@
 ---
+
 id: network-modeling
 title: Network modeling and data movement
 sidebar_label: Network modeling
 description: How data dependencies, topology links, routes, and observed transfers relate to a workflow plan.
 ---
 
+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.
 
 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.
 
 ## From dependency to possible flow
 
-```text
-producer activity -- control dependency --> consumer activity
-        |                                      ^
-        +---- data dependency: logical bytes --+
-
-producer resource -- directed topology route --> consumer resource
-```
+<img src={useBaseUrl('/img/architecture/network-flow-model.svg')} alt="A control dependency orders producer and consumer activities, a data dependency declares logical bytes, and a directed topology route is considered when their selected resources differ." />
 
 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.
 

docs/docs/explanations/observed-timing.md

@@ -1,9 +1,12 @@
 ---
+
 title: Interpreting observed timing and cost
 sidebar_label: Observed timing and cost
 description: The difference between flows, queue and stage totals, makespan, and observed execution cost.
 ---
 
+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
@@ -71,14 +74,7 @@ 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.
 
-```text
-Clock time:       0s ----------- 10s
-activity A:        [ runtime 10s ]
-activity B:        [ runtime 10s ]
-
-makespan:          10s
-accumulated compute: 20s
-```
+<img src={useBaseUrl('/img/architecture/accumulated-time.svg')} alt="Two ten-second activities run concurrently. Makespan is ten seconds, while accumulated compute time is twenty seconds." />
 
 The same applies to concurrent transfers and queue waits. Use makespan to answer
 "how long did the workflow take?" Use accumulated values to answer "where did

docs/docs/explanations/planning.md

@@ -1,9 +1,12 @@
 ---
+
 title: Planning, candidates, and selected plans
 sidebar_label: Planning and plans
 description: Why planning sessions produce candidates before one placement becomes executable.
 ---
 
+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.
 
 Use [Plan a workflow](../guides/workflows/planning) for the Desktop or API procedure; this explanation covers the model behind it.
@@ -12,22 +15,7 @@ Use [Plan a workflow](../guides/workflows/planning) for the Desktop or API proce
 
 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.
 
-```text
-workflow version + scope + snapshots + constraints
-                         |
-                         v
-                  planning session
-                         |
-          +--------------+--------------+
-          |                             |
-     algorithm run                  algorithm run
-          |                             |
-      candidate(s)                 candidate(s)
-          \                             /
-           \---- select one candidate -/
-                         |
-                    schedule plan
-```
+<img src={useBaseUrl('/img/architecture/planning-session-lifecycle.svg')} alt="Frozen workflow and infrastructure input create a planning session. Independent algorithm runs produce candidate sets, from which one candidate becomes a schedule plan." />
 
 ## Candidates are alternatives, not executions
 

docs/docs/getting-started.md

@@ -6,6 +6,8 @@ slug: /getting-started
 description: Choose the shortest AkôFlow documentation path for installation, a first run, operations, concepts, or API integration.
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 # Choose where to start
 
 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.
@@ -54,19 +56,9 @@ The Desktop and HTTP API operate on the same persisted records. The API is prefe
 
 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.
 
-The central lifecycle is:
-
-```text
-environment + execution scope + network
-                    ↓
-          versioned workflow DAG
-                    ↓
-      candidate plans → selected plan
-                    ↓
-             execution run
-                    ↓
-   observed metrics + data + provenance
-```
+The central lifecycle is shown below.
+
+<img src={useBaseUrl('/img/architecture/lifecycle-overview.svg')} alt="AkôFlow lifecycle: an infrastructure boundary and workflow version produce candidate plans; one selected plan produces an execution run and observed evidence." />
 
 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.
 

docs/docs/guides/interface-tour.mdx

@@ -1,11 +1,13 @@
 ---
+
 id: interface-tour
 title: Tour the AkôFlow interface
 sidebar_label: Interface tour
 description: Learn how the AkôFlow Desktop navigation maps to the control-plane API.
 ---
 
 import AnnotatedScreenshot from '@site/src/components/AnnotatedScreenshot';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 
 AkôFlow Desktop is the visual client for the AkôFlow daemon. The application does not run infrastructure commands from the browser renderer: it requests the daemon API, and the daemon performs discovery, planning, execution, data movement, and infrastructure operations.
 
@@ -40,11 +42,7 @@ AkôFlow pages preserve the relationship between records. An execution belongs t
 
 For example:
 
-```text
-Workflows › Workflow › Plan › Execution › Activity
-
-Environments › Environment › Inventory › Resource › Provisioning › Operation
-```
+<img src={useBaseUrl('/img/architecture/interface-ownership-hierarchy.svg')} alt="Workflow pages lead from workflow to plan, execution and activity. Infrastructure pages lead from environment through inventory and resource to provisioning and operation." />
 
 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.
 

docs/docs/guides/operations/troubleshooting.md

@@ -1,15 +1,16 @@
 ---
+
 title: Troubleshooting
 description: Diagnose daemon access, authentication, connection, discovery, planning, execution, storage, and snapshot problems.
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 # Troubleshooting
 
 Start at the first failing boundary. Desktop is a client of the Engine API; the Engine then talks to Docker/BuildKit, runtimes, remote connections, storage and cloud providers.
 
-```text
-Desktop → Engine API → credential/connection → runtime or provider → workload/data
-```
+<img src={useBaseUrl('/img/architecture/troubleshooting-boundary.svg')} alt="Troubleshoot from the Desktop through the Engine API, credentials and connections, then the runtime or provider and workload or data." />
 
 Set the endpoint and token before using the checks below:
 

docs/docs/modules.md

@@ -1,32 +1,17 @@
 ---
+
 id: modules
 title: AkôFlow components and boundaries
 sidebar_label: Components and boundaries
 ---
 
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
 AkôFlow is a single control-plane daemon with a REST API, a persistent event queue, planning and execution services, and pluggable infrastructure adapters. The Desktop application is the primary client of that API. AkôFlow does **not** deploy a separate Workflow Engine into every environment.
 
 ## At a glance
 
-```text
-AkôFlow Desktop / API clients
-              | authenticated HTTP
-              v
-+-----------------------------------------------------------+
-| AkôFlow daemon                                           |
-| REST API -> application services -> SQLite repositories   |
-|                         |                                 |
-|                persistent event loop                      |
-|                 /        |        \\                      |
-|          planning    execution    cloud lifecycle         |
-|                         |                                 |
-|               data preparation/transfers                  |
-+-------------------------+---------------------------------+
-                          |
-              runtime and connection adapters
-          /---------------+---------------\\
-       Local         Kubernetes        SSH / Slurm      Cloud
-```
+<img src={useBaseUrl('/img/architecture/control-plane-components.svg')} alt="AkôFlow Desktop and API clients call one daemon. The daemon contains API services, a persistent event loop, repositories, planning, execution, cloud lifecycle and data-preparation responsibilities, then uses adapters for local, Kubernetes, SSH or Slurm, and cloud targets." />
 
 The daemon owns orchestration and state. Target environments expose compute, storage, and network capabilities; they do not need an AkôFlow server installed inside each environment.