fixup! fixup! Document operation script API

docs/src/references/agent/operation-workflow.md

@@ -10,7 +10,8 @@ import ProposalBanner from '@site/src/components/ProposalBanner'
 
 ## Overview
 
-An agent developer can define application specific [operation workflows](./device-management-api.md#mqtt-driven-workflows).
+An agent developer can define application specific [operation workflows](./device-management-api.md#mqtt-driven-workflows)
+to control how an operation is performed on a device.
 Thin-edge **tedge-agent** provides the tools to:
 
 - override existing workflows
@@ -61,36 +62,37 @@ Observe on the example that:
 - At any state, *one and only one* participant is responsible to move the operation forward.
 - Publishing a state to the MQTT command topic, can be seen as passing the baton from one participant to another.
   The mapper creates the **init** state and then lets the other components work.
-  The plugin tell the download has been successful by publishing the **downloaded** state,
+  The agent tells the download has been successful by publishing the **downloaded** state,
   but do nothing till the domain-specific component has checked the file and move the command state to **install**.
 - Each software component has to know only *some* states of the whole workflow:
   - the states they are responsible for
   - the states they create to pass the control.
-- The compatibility of two participants, one publishing the state owned by the other, is only defined by the message payload:
+- The compatibility of two participants, one advancing to the new state owned by the other, is only defined by the message payload:
   - all the property fields, required to make progress at some state, must be provided by the previous participant.
 
 ### Benefits
 
 The benefits are that:
 - A participant can be substituted by another implementation as long as the substitute implementation
-  is ready to process at least all the state processed by the former implementation.
+  is ready to process at least all the states processed by the former implementation.
   - This is the key principle used by thin-edge to provide extensible operation support.
-  - The **tedge-agent** defines the **init**, **downloaded**, **installed** states
+  - The **tedge-agent** defines the **downloaded** and *installed** states
     with no specific behavior beyond proceeding to the next step;
     so, a domain specific component can be substituted to add extra checks and actions before moving forward.
 - Extra states and participants can be added as long as each state is owned by one participant.
   - For instance, an agent developer can introduce a **rollback** state in the `firmware_update` workflow,
     associated by another software component responsible for these rollbacks.
 
 Furthermore, specific versions of the same workflow can be defined on different targets.
+The main and child devices can each run their own version of a workflow for an operation.
 Indeed, all the status updates for a command on a given thin-edge entity or component
-are published on an MQTT topic which prefix is the entity identifier.
+are published on an MQTT topic with the entity identifier as the prefix.
 - The same executable can be used to handle operations on different targets.
   For instance, the **tedge-agent** can run on the main device `te/device/main//`
   as well as on a child-device identified by `te/device/child-xyz//`.
 - A specific executable can be substituted on a specific target.
   If for some reasons, **tedge-agent** cannot be installed on a child-device,
-  then a specific implementation of the `firmware_update` MQTT API can be used to serve configuration updates
+  then a specific implementation of the `firmware_update` MQTT API can be used to serve firmware updates
   on, say, `te/micro-controller/xyz//`.
 - A workflow can be extended differently for each target.
   As an example, an agent developer can define an extra rollback state on the main device but not on the child devices.
@@ -207,7 +209,7 @@ when a state message is published for a command on a topic matching the global t
 i.e. `te/+/+/+/+/cmd/+/+`.
 - Each running instance of the __tedge_agent__ reacts only on commands targeting its own device.
 - If a user-defined workflow has been defined for this operation, then this workflow is used to determine the required action.
-- If no workflow has been defined for the user for this operation, then the built-in workflow is used.
+- If no workflow has been defined by the user for this operation, then the built-in workflow is used.
 - If there is no workflow or no defined action for the current state, then the __tedge_agent__ fails the command.
 
 ### Built-in Actions