Start adding overview text at top of what-is-kosli file

docs.kosli.com/content/kosli_overview/what_is_kosli.md

@@ -4,28 +4,46 @@ weight: 120
 ---
 # What is Kosli?
 
-Kosli is a connected collection of attested evidence about any business-process. 
+Kosli is a connected collection of attested evidence about any business process.   
 Business processes instrumented with Kosli are Always-Audit-Ready.
-Some examples include:
-
-- How you build, test, and deploy software Artifacts
-- What software Artifacts are actually running in your infrastructure
-- Defining and applying changes to infrastructure
-- Recording real-time access to production servers
-- Changes to feature-flag configurations
-- Required steps when onboarding a new employee
 
 <!--
 {{<figure src="/images/kosli-overview-docs.jpg" alt="Kosli overview" width="1000">}}
+Below you can read about what elements Kosli consists of.
 -->
 
-Below you can read about what elements Kosli consists of.
+## Overview: Organization
+
+A Kosli *Organization* "owns" Environments and Flows - only members of each organization 
+can access the Environments and Flows belonging to that organization.
+By default, when you sign up to Kosli, a personal organization is created for you.
+Its name is your username. Only you can access your personal organization.
 
-## Organization
+## Overview: Environments and Snapshots 
+
+A Kosli *Environment* stores snapshots containing information about
+the software Artifacts you are running in your runtime environment.
+Kosli supports many kinds of runtime environments; (server, Kubernetes cluster, AWS, etc.)  
+
+## Overview: Flows and Trails
+
+A Kosli *Flow* represents a single business-process, about which you want to attest (record) evidence.   
+A Kosli *Trail* is a single instance/run of a Kosli *Flow*.
+Here are some examples:
+
+- Required steps when onboarding a new employee
+  - The name of the Flow could be *employee-onboarding*
+  - Each employee has their own Trail, eg *PeterPan*
+  - Attested evidence might relate to documents they have read, eg *DisasterRecoveryPlan*
+- How you build, test, and deploy a software Artifact
+  - The Flow could be named after the Artifact's git-repository, eg *NeverLand*
+  - Each git-commit could have its own Trail, eg *d65da7464db715e0513c5191a90cb546b9d4696b*
+  - Each Jira-ticket could have its own Trail, eg *JMB-452*
+  - Attested evidence would relate to required SDLC tasks, eg *snyk-scan* 
+- Defining and applying changes to a runtime infrastructure
+- Recording real-time access to production servers
+- Feature-flag changes
 
-An Organization in Kosli "owns" Kosli flows and environments - only members of each organization 
-can access the environments and flows that belong to that organization.
-By default, when you sign up to Kosli, a personal organization is created for you and the name of the organization matches your user name. Only you can access your personal organization.
 
 ## Environments
 
@@ -34,8 +52,9 @@ Environments in Kosli provide a place to track how your software runtime systems
 {{<figure src="/images/envs.png" alt="Environments" width="900">}}
 
 Each runtime environment you'd like to track in Kosli should have its own Kosli environment created. 
-Kosli allows you to define the borders of your environments. For example, if you use a Kubernetes cluster, you can either treat it as one Kosli environment
-or treat one or more namespaces in the cluster as one Kosli environment.
+Kosli allows you to define the borders of your environments. For example, if you use a Kubernetes 
+cluster, you can either treat it as one Kosli environment or treat one or more namespaces in the cluster 
+as one Kosli environment.
 
 Kosli supports different types of runtime environments and the reporting command varies for each:
 * Kubernetes cluster (k8s)
@@ -54,8 +73,10 @@ You can create a Kosli environment using:
 Once the Kosli environment is ready you can start reporting the status of your actual runtime environment using one of the **kosli snapshot ...** commands - check [CLI Reference](/client_reference) for details.
 
 Reporting your environments should be automated via a cron-like schedule. 
-It's up to you to decide how often you want the reports to keep coming, but we recommend high frequency to be able to avoid missing short lived changes. 
-Every time a change in your runtime environment is reported, a new snapshot capturing the current state of the environment will be created. 
+It's up to you to decide how often you want the reports to keep coming, but we recommend 
+high frequency to be able to avoid missing short-lived changes. 
+Every time a change in your runtime environment is reported, a new snapshot capturing the 
+current state of the environment will be created. 
 
 ![Diagram of Environment Reporting](/images/environments-cli-v2.svg)
 
@@ -72,7 +93,8 @@ A Snapshot represents the reported status of your runtime environment at a given
 
 {{<figure src="/images/snapshot-467.png" alt="Snapshot 467" width="900">}}
 
-Using the Kosli UI, you can use the arrow buttons on the right hand side above the running artifacts list to browse older snapshots. 
+Using the Kosli UI, you can use the arrow buttons on the right hand side above the running artifacts 
+list to browse older snapshots. 
 
 Snapshots are append-only immutable objects. That is once a snapshot is created, it can't be modified.
 
@@ -82,42 +104,58 @@ An Environment is **compliant** when the following conditions are met:
 1. All the artifacts running in the environment have provenance (were reported in a Kosli Flow) and are compliant themselves OR they were [allow-listed](#allow-list);
 2. All the artifacts running in the environment are [expected to be deployed](/client_reference/kosli_expect_deployment/) to that environment.
 
-You will see the status of your environment on the environments list. You will also see the compliance status of each snapshot when you browse the snapshots of the environment.
+You will see the status of your environment on the environments list.
+You will also see the compliance status of each snapshot when you browse the snapshots of the environment.
 
-If your environment is not compliant, check the latest snapshot for more detailed info - each unknown or non-compliant artifact will be marked and the reason for the non-compliance will be provided.
+If your environment is not compliant, check the latest snapshot for more detailed info -
+each unknown or non-compliant artifact will be marked and the reason for the non-compliance will be provided.
 
 {{<figure src="/images/non-compliant-env.png" alt="Snapshot 467" width="1000">}}
 
 
 ### Allow list 
 
-Not all artifacts that run in your environment must be built by you - these may be publicly available artifacts, or artifacts provided by external vendors. In such cases, it is likely that those artifacts won't have provenance in Kosli. 
+Not all artifacts that run in your environment must be built by you - these may be publicly 
+available artifacts, or artifacts provided by external vendors. In such cases, it is likely that 
+those artifacts won't have provenance in Kosli. 
 
-These artifacts will -by default- be marked with "No provenance" red label and it will affect the compliance of the whole environment. If you know how and why these artifacts are present in your environment you can add them to the Allow-list by clicking a button on the snapshot page, or using [kosli allow artifact](/client_reference/kosli_allow_artifact/) command
+These artifacts will -by default- be marked with "No provenance" red label and it will 
+affect the compliance of the whole environment. If you know how and why these artifacts 
+are present in your environment you can add them to the Allow-list by clicking a button 
+on the snapshot page, or using [kosli allow artifact](/client_reference/kosli_allow_artifact/) command
 
 ## Flows and Artifacts
 
 ### Flows
 
-Flows in Kosli allow you to track how your value streams produce artifacts. They provide a place to report artifact creation events as well as any evidence produced from your CI pipelines.
+Flows in Kosli allow you to track how your value streams produce artifacts. 
+They provide a place to report artifact creation events as well as any evidence 
+produced from your CI pipelines.
 
 You can create Kosli flow using the **[kosli create flow](/client_reference/kosli_create_flow/)** command. 
 
 When you create a flow, you specify a [template](/kosli_overview/what_is_kosli/#template). The creation of a flow can happen in or out of your CI pipelines.
 The template declares what pieces of evidence are required for an artifact produced from that flow to be compliant.
 
 Best practice is to create Kosli flow for each of your value streams regardless of how your CI pipelines are setup. 
-For example, if your CI pipeline produces 3 separate artifacts, you'd create 3 different Kosli flows to report artifacts and evidence.
+For example, if your CI pipeline produces 3 separate artifacts, you'd create 3 different 
+Kosli flows to report artifacts and evidence.
 
-Once your Kosli flow is in place you can start reporting artifacts and evidence of all the events you want to report (matching declared template) from your CI pipelines. Kosli CLI provides a variety of commands to make it possible: 
+Once your Kosli flow is in place you can start reporting artifacts and evidence of all the 
+events you want to report (matching declared template) from your CI pipelines. Kosli CLI 
+provides a variety of commands to make it possible: 
 
 ![Diagram of Flow Reporting](/images/flows-cli-v2.svg)
 
-A number of required flags may be defaulted to a set of environment variables, depending on the CI system you use. Check [How to use Kosli in CI Systems](/integrations/ci_cd/) for more details. All flags can be represented by [environment variables](/kosli_overview/kosli_tools/#environment-variables).
+A number of required flags may be defaulted to a set of environment variables, depending 
+on the CI system you use. Check [How to use Kosli in CI Systems](/integrations/ci_cd/) for more details. 
+All flags can be represented by [environment variables](/kosli_overview/kosli_tools/#environment-variables).
 
 ### Template
 
-When creating a Kosli flow you need to provide a template - a list of expected evidence you require for your artifact in order for the artifact to become compliant. That could be for example:
+When creating a Kosli flow you need to provide a template - a list of expected evidence you 
+require for your artifact in order for the artifact to become compliant.
+That could be, for example:
 * existing pull request
 * code coverage report
 * integration test
@@ -130,14 +168,19 @@ The template can be changed over time and it won't affect the compliance of arti
 
 {{<figure src="/images/artifact-view.png" alt="Artifact view" width="1000">}}
 
-Whatever you produce during your build process can be an artifact - a binary file, an archive, a folder, a docker image... sometimes you don't produce anything new while "building" and the folder containing your source code can be the artifact.
+Whatever you produce during your build process can be an artifact - a binary file, an archive, a folder, 
+a docker image... sometimes you don't produce anything new while "building" and the folder containing 
+your source code can be the artifact.
 
-An artifact is identified by its [fingerprint](/kosli_overview/what_is_kosli/#fingerprints) which is used to link the artifacts running in an environment back to their provenance in a flow.
+An artifact is identified by its [fingerprint](/kosli_overview/what_is_kosli/#fingerprints) which is used to link the artifacts running 
+in an environment back to their provenance in a flow.
 
 ### Evidence
 
-You can report to Kosli pieces of evidence related to either an artifact or a git commit. This gives you flexibility to report evidence before or after you report an artifact.
-The evidence names have to match the names you declare in your flow [template](/kosli_overview/what_is_kosli/#template) and are then used to evaluate whether an artifact is compliant or not.
+You can report to Kosli pieces of evidence related to either an artifact or a git commit. 
+This gives you flexibility to report evidence before or after you report an artifact.
+The evidence names have to match the names you declare in your flow [template](/kosli_overview/what_is_kosli/#template) and 
+are then used to evaluate whether an artifact is compliant or not.
 
 Evidence that is reported to a git commit is automatically linked to any artifact produced from that commit.
 

docs.kosli.com/content/tutorials/get_familiar_with_Kosli.md

@@ -48,34 +48,21 @@ To follow the tutorial, you will need to:
 ## Step 2: Create a Kosli Flow
 
 <!--
-For now an explanation of what a Kosli Flow is exists here.
-These explanations need to live at the top-level of the docs.
-What a Flow is should not appear in tutorials like this.
--->
-
-A Kosli *Flow* represents a single business-process, about which
-you want to record (attest) evidence. Different kinds of Kosli *flows* include:
-- How you build, test, and deploy software Artifacts for a specific service
-- Defining and applying changes to infrastructure
-- Recording real-time access to production servers
-- Feature-flag changes
-- Required steps when onboarding a new employee
-
 For this tutorial we are using the first kind:
 - the *Flow* corresponds to the git repository
 - the Artifact being built and deployed is an `nginx` docker image
-
 When attesting evidence, the target of the attestation must be named.
 These names are defined in a yml file.
-A prepared yml file already exists in the git repository.
+-->
+
+The Flow's yml template-file exists in the git repository.
 Confirm this yml file exists by catting it:
 
 ```shell {.command}
 cat kosli.yml
 ```
 
-You will see the following output, which specifies the
-existence of an Artifact named `nginx`:
+You will see the following output, specifying the existence of an Artifact named `nginx`:
 
 
 ```plaintext {.light-console}
@@ -86,16 +73,15 @@ trail:
     - name: nginx
 ```
 
-Create a new Kosli *Flow* called `quickstart-nginx`
-naming this yml file:
+Create a Kosli *Flow* called `quickstart-nginx` using this yml template-file:
 
 ```shell {.command}
 kosli create flow2 quickstart-nginx \
     --description "Flow for quickstart nginx image" \
     --template-file kosli.yml
 ```
 
-Confirm the Kosli flow called `quickstart-nginx` was created by running:
+Confirm the Kosli Flow called `quickstart-nginx` was created:
 
 ```shell {.command}
 kosli list flows
@@ -117,12 +103,7 @@ been reported yet.
 
 ## Step 3: Create a Kosli Trail
 
-A Kosli *Trail* is a single instance of a Kosli *Flow*.
-In this tutorial:
-- the *Flow* corresponds to a git repository
-- the *Trail* corresponds to a git-commit in the repository 
-
-Create a Kosli *Trail*, in the `quickstart-nginx` flow, whose 
+Create a Kosli *Trail*, in the `quickstart-nginx` Flow, whose 
 name is the repository's current git-commit:
 
 ```shell {.command}
@@ -131,11 +112,17 @@ kosli begin trail ${GIT_COMMIT} \
     --flow quickstart-nginx
 ```
 
+<!--
+Step to confirm the Trail exists?
+-->
+
 ## Step 4: Create a Kosli environment
 
+<!--
 A Kosli *Environment* stores snapshots containing information about
 the software Artifacts you are running in your runtime environment.
 Kosli supports many kinds of runtime environments; (server, Kubernetes cluster, AWS, etc.)  
+-->
 
 Create a Kosli *Environment* called `quickstart` whose type is `docker`:
 

docs.kosli.com/content/tutorials/simulating_a_devops_system.md

@@ -268,20 +268,6 @@ tab should show what changed in snapshot 1 and snapshot 2.
 
 # Flows
 
-<!--
-For now an explanation of what a Kosli Flow is exists here.
-These explanations need to live at the top-level of the docs.
-What a Flow is should not appear in tutorials like this.
--->
-
-A Kosli *Flow* represents a single business-process, about which
-you want to record (attest) evidence. Different kinds of Kosli *flows* include:
-- How you build, test, and deploy software Artifacts
-- Defining and applying changes to infrastructure
-- Recording real-time access to production servers
-- Feature-flag changes
-- Required steps when onboarding a new employee
-
 For this tutorial we are simulating building and deploying two
 artifacts; a web-server and a db-server.