Align AkôFlow documentation narrative and examples

.github/workflows/docs-checks.yaml

@@ -5,12 +5,18 @@ on:
     paths:
       - "docs/**"
       - "examples/**"
+      - "internal/api/**"
+      - "internal/domain/**"
+      - "internal/provider/**"
       - ".github/workflows/docs-checks.yaml"
   push:
     branches: [main]
     paths:
       - "docs/**"
       - "examples/**"
+      - "internal/api/**"
+      - "internal/domain/**"
+      - "internal/provider/**"
       - ".github/workflows/docs-checks.yaml"
 
 permissions:
@@ -28,6 +34,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -41,6 +49,8 @@ jobs:
         run: npm run build --prefix docs
       - name: Verify repository-owned documentation links
         run: npm run check:links --prefix docs
+      - name: Check documentation shell examples
+        run: npm run check:shell --prefix docs
       - name: Upload GitHub Pages artifact
         if: github.ref == 'refs/heads/main'
         uses: actions/upload-pages-artifact@v3

.github/workflows/gh-akf-new-release.yaml

@@ -243,7 +243,7 @@ jobs:
             AkôFlow Desktop requires Docker Desktop on macOS and Windows, or Docker Engine with the Compose v2 plugin on Linux. Download the matching asset below:
 
             - **macOS:** open the universal `.dmg`, drag AkôFlow Desktop to Applications, and launch it.
-            - **Windows:** run the x64 installer `.exe`, or use the portable `.exe` without installation.
+            - **Windows:** run the x64 portable `.exe` asset without an installation wizard.
             - **Linux:** run the x64 `.AppImage` after `chmod +x`, or install the `.deb` with `sudo apt install ./Akoflow-Desktop-*.deb`.
 
             The matching source is the Git tag `${{ github.ref_name }}`. The runtime Docker archives in this release are loaded locally by Desktop; AkôFlow does not publish daemon or BuildKit packages to a container registry.

docs/docs/concepts.md

@@ -1,50 +1,30 @@
 ---
 id: concepts
-title: System architecture
-sidebar_label: System architecture
-description: How AkôFlow keeps infrastructure, workflow intent, planning decisions, and execution evidence separate.
+title: Core concepts
+sidebar_label: Core concepts
+description: Understand workflows, environments, plans, runs, artifacts, and provenance in AkôFlow.
 ---
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-AkôFlow is a control plane for scientific workflows. It keeps the description of the available infrastructure separate from the workflow definition, the scheduling decision, and the evidence produced by an execution. That separation lets the same immutable workflow version be compared on different infrastructure scopes without rewriting the workflow.
+AkôFlow keeps the workflow you define, the resources available to it, the plan you choose, and the result you observe as separate records. That lets you try a different plan without rewriting the workflow.
 
-This is an explanation of the records and their boundaries. For the exact YAML fields, use the [workflow specification](./internal/workflow-spec) and the [environment reference](./reference/environment-yaml). For an end-to-end task, start with [the first simulated workflow](./guides/workflows/first-run).
+## From workflow to result
 
-<img src={useBaseUrl('/img/architecture/akoflow-control-plane.svg')} alt="AkôFlow control-plane architecture: Desktop and API clients call the daemon; its workflow, planning, and execution services preserve scientific evidence in SQLite and dispatch work through SimGrid, Kubernetes, SSH/Slurm, cloud, and local adapters." />
+<img src={useBaseUrl('/img/architecture/record-chain.svg')} alt="A workflow and an environment lead to candidate plans; executing a selected plan produces a run, artifacts, and provenance." />
 
-*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.
 
-<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." />
+A **plan** assigns activities to resources and predicts timing, transfers, and possibly cost. AkôFlow can produce several candidates, or you can supply a manual plan. Selecting one does not start a run; it records the choice you want to execute.
 
-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.
+A **run** records what happened after the plan was submitted. It tracks activity status and stores timing, transfers, and output evidence when those observations are available. Compare them with the plan's predictions to see where they differ.
 
-## Infrastructure is a versioned boundary
+**Executable artifacts** are the versioned programs or images used by activities. **Scientific data** includes inputs and outputs associated with the work. **Provenance** links the workflow, plan, run, activities, and data so you can trace how a result was produced. Audit separately records connection checks, resource discovery, and console actions.
 
-An **environment** names an infrastructure boundary: a local host, Kubernetes cluster, SSH/SLURM system, modeled SimGrid platform, or cloud configuration. Its published version can contain runtimes, resources and their hierarchy, runtime bindings, storage, connection observations, and capability observations.
+## Where to go next
 
-A **resource** is capacity that may be assigned by a plan. A **runtime** says how an activity is launched and observed. A binding states which runtime may use which resource. The [runtime adapters explanation](./runtimes) describes that boundary in more detail.
+Start with [the first local workflow in Desktop](/docs/guides/workflows/first-local-run). Then use [Workflow definitions](/docs/guides/workflows/definitions), [Planning](/docs/guides/workflows/planning), and [Execution](/docs/guides/workflows/executions) for the individual tasks. The [SimGrid API tutorial](/docs/guides/workflows/first-run) is a separate simulation example.
 
-An **execution scope** chooses the published environment versions that an algorithm may consider. Its network topology supplies directed links between resources. This means a plan answers a constrained question—"place this workflow on this frozen universe"—rather than a claim about every resource the daemon may ever discover.
-
-## A workflow describes intent, not placement
-
-A workflow definition owns identity and namespace. Its immutable version has activities plus control and data dependencies. Activities carry executable and resource requirements and may carry a simulation profile. They do not name a target resource; that is a planning decision.
-
-Control dependencies establish ordering. Data dependencies identify the producer, consumer, logical data, and byte volume used for movement modeling. In the current portable importer, a data dependency contributes to scheduling only when its producer/consumer pair also has the matching control dependency. This protects the DAG semantics from a data declaration that has no ordering edge.
-
-## A plan is a prediction and a decision
-
-A planning session may produce several **candidates**. They are alternatives, not runnable plans in their own right. Selecting a candidate promotes its placement to a canonical **schedule plan** with assignments and predicted ready, start, finish, runtime, transfer, and cost values. Manual and imported plans use the same plan aggregate after validation.
-
-Planning does not start work. The [planning explanation](./explanations/planning) explains why candidates, objectives, and a selected plan are different records.
-
-## Execution creates observations
-
-An **execution run** binds one selected plan to real, simulation, or interactive mode. The supervisor persists task attempts, runtime handles, transfer routes, logs, artifact manifests, and timing. Those records are observations of a run; they do not retroactively alter the plan prediction.
-
-An executable artifact is immutable runnable input. An artifact manifest is an observed output from an activity. They are deliberately different: an input can be materialized before a task starts, while an output can become a scientific data object only after the activity has been observed.
-
-Read [execution and control-plane behavior](./engine) for orchestration, [network modeling](./explanations/network-modeling) for movement assumptions, and [evidence and provenance](./explanations/evidence-and-provenance) for the records used to compare a plan with a completed run.
+For exact file fields, use the [workflow specification](/docs/internal/workflow-spec) and [environment reference](/docs/reference/environment-yaml). For implementation details, see [Architecture internals](/docs/modules).

docs/docs/contributing/documentation-plan.md

@@ -5,12 +5,26 @@ sidebar_label: Production plan
 description: Source-of-truth, media, and review rules for AkôFlow documentation.
 ---
 
-This plan keeps the documentation aligned with the shipping daemon and Desktop application. It is also the contract for parallel documentation work.
+This page defines the editorial and verification rules for the documentation. Apply them whenever a page, example, screenshot, API route, or supported capability changes.
+
+## Editorial contract
+
+The documentation should show how AkôFlow simplifies scientific workflow execution, not display the complexity of its implementation.
+
+1. Explain the task and expected result first. Give each page one main job and reveal details only when the reader needs them.
+2. Use workflow, environment, plan, run, artifacts, and provenance in user paths. Put supervisors, handlers, adapters, and persistence in developer architecture pages unless a task requires them.
+3. Make support claims only when code and appropriate evidence support them. Label partial features and distinguish code review, local fixtures, and real-environment validation.
+4. Prefer a concrete example over a list of capabilities. Remove repeated caveats and text that does not help a reader act or decide.
+5. Check whether each page quickly answers what it is for, when to use it, how to use it, and what to expect.
+
+For each editorial pass, classify passages as **KEEP**, **SIMPLIFY**, **MOVE**, **DELETE**, or **VERIFY**. Resolve P0 (false claims and broken instructions), then P1 (confusing paths and misplaced concepts), then P2 (length and repetition), then P3 (presentation). Repeat audit → edit → build → link check → claim check → first-time-reader review until a full pass finds no P0 or P1 issues. A successful build alone is not the finish line.
+
+The completion gate is a new user running a first workflow without undocumented knowledge, support claims matching implementation and validation, implementation details outside the basic path, and no P0/P1 findings in the final audit.
 
 ## Documentation principles
 
 1. Teach complete user tasks instead of listing screens in isolation.
-2. Present **AkôFlow Desktop** and **API** as equivalent paths whenever both exist.
+2. Present **AkôFlow Desktop** and **API** paths only where each procedure is documented and verified; state extra prerequisites instead of calling them equivalent by default.
 3. Derive behavior from code, tests, and checked-in examples; never infer an endpoint or field from a label alone.
 4. Use screenshots to explain spatial relationships and short videos to explain motion or multi-step transitions.
 5. Keep a text equivalent for every visual procedure.
@@ -20,55 +34,23 @@ This plan keeps the documentation aligned with the shipping daemon and Desktop a
 
 | Subject | Primary source |
 |---|---|
-| Desktop navigation | `akoflow-admin/src/App.jsx` and `src/components/AppShell.jsx` |
-| Desktop operations | Page, form, and provider components in `akoflow-admin/src` |
-| HTTP methods and paths | `akoflow/internal/api/httpserver/httpserver.go` |
+| Desktop navigation | `akoflow-desktop/src/App.jsx` and `akoflow-desktop/src/components/AppShell.jsx` in the Desktop repository |
+| Desktop operations | Page, form, and provider components in `akoflow-desktop/src` |
+| HTTP methods and paths | `internal/api/httpserver/httpserver.go` in this repository |
 | Request and response contracts | HTTP handlers, application services, and `internal/domain` |
-| Runnable scenarios | `akoflow/examples` and integration tests |
-| Packaged installation | Root README, `releases/`, Electron bootstrap, and release workflows |
+| Runnable scenarios | `examples/` and integration tests in this repository |
+| Packaged installation | Root README, `releases/`, the Desktop repository's `electron/` bootstrap, and release workflows |
 
 Generated site output and old copied Markdown files are not sources of truth.
 
-## Production waves
-
-### Wave 1 — foundation
-
-- Establish the information architecture and sidebar.
-- Add reusable screenshot, video, and Desktop/API components.
-- Build a feature coverage matrix.
-- Define stable demo data and redact all secrets from captures.
-
-### Wave 2 — task guides
-
-- Infrastructure and execution scopes.
-- Workflow definition, planning, and execution.
-- Artifacts, storage, provenance, and audit.
-- Installation, instance management, and troubleshooting.
+## Review a change
 
-Independent guide groups may be authored in parallel after their source inventory is complete. Each group owns separate files.
-
-### Wave 3 — reference
-
-- Replace the legacy workflow specification with the current versioned model.
-- Document API conventions and endpoint groups.
-- Document runtime capabilities, lifecycle states, and compatibility rules.
-
-### Wave 4 — media
-
-- Load a deterministic demonstration instance.
-- Capture a fixed desktop viewport in the light theme.
-- Add numbered callouts and restrained directional arrows.
-- Record one operation per video.
-- Prefer WebM for the site; create an optimized GIF only when a fallback is useful.
-
-### Wave 5 — verification
-
-- Verify every field against the Go contract.
-- Verify every route against the HTTP mux.
-- Run or validate checked-in examples.
-- Build and type-check Docusaurus.
-- Review screenshots for secrets, hostnames, tokens, usernames, and unstable identifiers.
-- Search for removed terminology and stale fixed-port instructions.
+1. Check page purpose, audience, order of concepts, and whether the example solves a concrete task.
+2. Compare affected claims and payloads with current handlers, Desktop behavior, tests, and checked-in examples.
+3. Distinguish local fixtures from real-provider validation, and update support limits when evidence changes.
+4. Check screenshots for secrets, hostnames, tokens, usernames, and unstable identifiers.
+5. Run the documentation type-check, build, and link check; then read the rendered path at desktop and mobile widths.
+6. Record unresolved P0/P1 findings and repeat the pass after corrections.
 
 ## Link verification
 
@@ -77,15 +59,17 @@ Run the repository-owned link check after a documentation build:
 ```bash
 npm run build --prefix docs
 npm run check:links --prefix docs
+npm run check:shell --prefix docs
 ```
 
-The check rejects a missing internal documentation route, a missing file below
-`docs/static/`, and a Showcase download that no longer has its checked-in
-counterpart under `examples/`. It intentionally does not make network requests
-or judge third-party URLs: availability of external services belongs to the
-reader's environment, while these three classes are artifacts maintained in
-this repository. GitHub Actions runs the same type-check, build, and link check
-for documentation or example changes.
+The link check rejects missing documentation routes, files under `docs/static/`,
+and Showcase downloads without a checked-in counterpart under `examples/`.
+It checks repository-owned links, not third-party availability.
+
+The shell check parses fenced Bash/sh examples and Showcase JSX command blocks
+without running them. It requires `curl` examples to fail on HTTP errors, but
+cannot validate named files or API behavior. GitHub Actions runs the type-check,
+build, link check, and shell check for documentation or example changes.
 
 ## Media naming
 
@@ -115,7 +99,7 @@ Use the black, white, and neutral-gray visual system established by [`akoflow-co
 
 ## Definition of done for a guide
 
-- The task has prerequisites, Desktop steps, API steps, expected result, and next steps.
+- The task has prerequisites, a verified procedure for its stated interface, an expected result, and next steps. Add a second interface only when its path has been checked.
 - Screenshot placeholders or final captures cover only moments where the visual adds information.
 - API examples include authentication and use the current `/akoflow-api` prefix.
 - Identifiers in examples are visibly placeholders or come from a documented demo dataset.
@@ -126,7 +110,9 @@ Use the black, white, and neutral-gray visual system established by [`akoflow-co
 
 Run `npm run generate:api` to rebuild the endpoint catalog from `internal/api/httpserver/httpserver.go`. The Docusaurus `prestart` and `prebuild` hooks run this automatically. Generated pages are intentionally ignored by Git; changes to method, path, or handler appear on the next documentation build without copying the router by hand.
 
-Each generated endpoint page includes its HTTP method, registered path, path parameters, authentication example, request-body indication, owning handler, and a copyable cURL command. Domain guides remain responsible for semantic explanations and complete payload examples.
+Each generated endpoint page shows the registered method and path, parameters, owning handler, and request-body indication. HTTP routes include a cURL command or template; the console stream shows a WebSocket connection instead. A template still needs valid IDs and, for a body, a prepared request file.
+
+The generator shows a request body only when it has a checked example. Otherwise, use the handler-checked notes and linked guide to prepare one. Response JSON shapes are illustrative and may omit fields or show placeholder values. Check a route against its handler and a real response before treating a field-level example as verified.
 
 ## Reproducible media capture