incorporated feedback on concepts docs

docs/concepts.md

@@ -1,34 +1,33 @@
 # Concepts
 
-The following are brief descriptions of KubeFox constituents. For more details
-and tutorials on their use checkout additional documentation under
+The following are brief descriptions of KubeFox concepts. For more details and
+tutorials on their use, checkout additional documentation under
 [topics](../topics).
 
 ## Event
 
 : KubeFox operates on an event-driven architecture, where all requests and
 responses, including synchronous calls, are conceptualized as Events and
 communicated as messages among Components via Brokers. The KubeFox Event model
-offers a straightforward and versatile interface to encapsulate distinct, and
-optionally typed, state changes.
+offers a straightforward and versatile interface to encapsulate distinct - and
+optionally typed - state changes.
 
 : To illustrate, an HTTP request undergoes conversion by the HTTP Adapter into a
 KubeFox Event, which is subsequently transmitted to a Broker for routing to a
 specific Component. The Component can then utilize the Event in a generic manner
-or, alternatively, inspect its type and access type-specific attributes as
-needed.
+and, optionally, inspect its type and access type-specific attributes as needed.
 
 ## Genesis Event
 
 : A Genesis Event is an originating Event for a request. It is often generated
 in response to an external request, such as an HTTP request. However, an
-internal process, like a CRON trigger, could also give rise to a Genesis Event.
-KubeFox dynamically determines the routing of a Genesis Event by matching it to
-a registered Component Route associated with a Release. Conversely, the App
+internal process, like a CRON trigger, could also yield a Genesis Event. KubeFox
+dynamically determines the routing of a Genesis Event by matching it to a
+registered Component Route associated with a Release. Alternatively, the App
 Deployment and Virtual Environment can be explicitly specified within the
 Genesis Event, allowing for testing of App Deployments before an official
-Release is created. Once a match is established, the request context, including
-the App Deployment and Virtual Environment, is attached to to the Genesis Event
+Release is created. Once a match is established, the request context - including
+the App Deployment and Virtual Environment - is attached to to the Genesis Event
 all subsequent child Events generated by the Components processing the request.
 
 ## Component
@@ -41,80 +40,78 @@ Components.
 
 ## App
 
-: An App is a collections of Components which together provide useful
-capabilities to end users of the software. Apps serve as the deployable unit in
-the context of KubeFox. That means all Components of an App are deployed, and
-optionally versioned, together.
+: An App is an application; a collection of Components which together provide
+useful capabilities to end users of the software. Apps serve as the deployable
+unit in the context of KubeFox. That means all Components of an App are deployed
+(and optionally versioned) together.
 
 ## Repository
 
-: A Repository is a Git repository housing one or more Apps. Components are
-versioned through commits made to Git, enabling KubeFox to track modifications
-to Components between App Deployments.
+: A Repository is a Git repository housing one or more Apps. KubeFox tracks
+modifications to Components by monitoring Git commits, and versions Components
+when Apps are deployed.
 
 ## Route
 
-: A Route matches Events to a handler implemented by a Component. They are
+: A Route matches Events to a handler implemented by a Component. Routes are
 written in a straightforward predicate-based language that supports boolean
-logic. Optionally, a Route can contain logic to extract Event attributes into
+logic. A Route can optionally contain logic to extract Event attributes into
 named parameters, which are then passed to the handler.
 
 ## Broker
 
-: A Broker serves as an Event router, responsible for matching and transporting
-Events between components. It determines the context of an Event and scrutinizes
-the corresponding App Deployment to ensure that the Event is authorized to be
-passed to the matching Component. The Broker also injects Virtual Environment
-variables and Adapter configurations into Events as necessary.
+: Brokers serve as Event routers, and are responsible for matching and
+transporting Events between components. Brokers determine the context of an
+Event and evaluate the corresponding App Deployment to ensure that the Event is
+authorized to be passed to the matching Component. Brokers also inject Virtual
+Environment variables and Adapter configurations into Events as necessary.
 
 ## External Component
 
-: An External Component refers to a third-party service that is not inherent to
-KubeFox. Examples of External Components include PostgreSQL, Amazon S3, and
-Kafka. Adapters provide connectivity with these Components by facilitating the
-translation between the External Component's API and KubeFox Events.
+: An External Component refers to a third-party service. Examples of External
+Components include PostgreSQL, Amazon S3, and Kafka. Adapters provide
+communication between KubeFox Components and External Components.
 
 ## Adapter
 
-: An adapter is a service which bidirectionally converts KubeFox Events to an
-External Component's API. Adapters facilitate the interaction of Components with
-services that are not native to KubeFox. For instance, the HTTP Adapter
-translates both incoming HTTP requests and outgoing HTTP calls to and from
-KubeFox Events.
+: An Adapter is a service which converts KubeFox Events to an External
+Component's API and vice versa. Adapters facilitate the interaction of
+Components with services that are not native to KubeFox. For instance, the HTTP
+Adapter translates both incoming HTTP requests and outgoing HTTP calls to and
+from KubeFox Events.
 
 ## App Deployment
 
 : An App Deployment comprises the definitions of both the App and its
-Components. This encompasses the Component's Routes, OCI image name, and any
-associated Virtual Environment variables or Adapters it depends on. Initiating
-the creation of an App Deployment prompts the KubeFox operator to verify a
-Kubernetes Pod exists for each specified Component.
+Components. This includes the Component's Routes, OCI image name, and any
+associated Virtual Environment variables or Adapters on which it depends.
+Initiating the creation of an App Deployment prompts the KubeFox operator to
+verify a Kubernetes Pod exists for each specified Component.
 
-: Optionally, an App Deployment can be assigned a version with semantic
-significance. Once versioned, an App Deployment becomes immutable, guaranteeing
-a static App definition. This facilitates releasing the App Deployment while
-preserving a consistent and unchanging configuration for the specified version
-of the App.
+: An App Deployment can optionally be assigned a version, e.g., a semantic
+version. Once versioned, an App Deployment becomes immutable, guaranteeing a
+stable, point-in-time App definition. Versioning the App facilitates Release and
+preserves a consistent and unchanging configuration for the specified version,
+enabling a return to the version at any point in the future.
 
 ## Virtual Environment
 
-: A Virtual Environment is an object encompassing a collection of variables and
-Adapter configurations. A Component can specify dependencies on both Virtual
-Environment variables and Adapters. During runtime, the Broker extracts the
-necessary variables from the Virtual Environment and attaches them to any Event
-routed to the Component. Simultaneously, the Broker attaches the requisite
-configuration to Events directed to an Adapter.
+: A Virtual Environment is a collection of variables and Adapter configurations.
+Virtual Environments enable capabilities like dynamic (at runtime) traffic
+shaping, and the modification of App behavior without requiring new deployments.
 
-: As Components explicitly define their dependencies, a Virtual Environment can
-undergo validation at Release creation time. This ensures that the necessary
-elements are in place for the proper functioning of Components within the
-Virtual Environment.
+: A Component can specify dependencies on Virtual Environment variables and
+Adapters.  At runtime, the Broker extracts required variables from the Virtual
+Environment, attaches them to Events destined for the Component, and routes the
+Event.  Similarly, the Broker attaches required configuration for Events
+directed to Adapters.
+
+: Because Components can explicitly define their dependencies, Virtual
+Environments can be validated when Releases are created.  Validation guarantees
+that the required elements are present, thereby ensuring proper functioning of
+the App Components within the context of that Virtual Environment.
 
 ## Release
 
-: A Release binds an App Deployment and Virtual Environment together and
-indicates to the Broker that Events matching the Component Routes of App
-Deployment should be automatically routed to the matching Component. Once a
-match is established, the request context, including the App Deployment and
-Virtual Environment, is attached to all subsequent child Events generated by the
-Components processing the request.
+: A Release binds a versioned App Deployment and Virtual Environment together,
+and defaults Genesis Events to the Routes specified in the App Deployment.

docs/fox/fox.md

@@ -33,4 +33,4 @@ and release your KubeFox Apps.
 * [fox release](fox_release.md)	 - Release specified AppDeployment and VirtualEnvironment
 * [fox version](fox_version.md)	 - Show version information of 🦊 Fox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_build.md

@@ -45,4 +45,4 @@ fox build (NAME) [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_completion.md

@@ -32,4 +32,4 @@ See each sub-command's help for details on how to use the generated script.
 * [fox completion powershell](fox_completion_powershell.md)	 - Generate the autocompletion script for powershell
 * [fox completion zsh](fox_completion_zsh.md)	 - Generate the autocompletion script for zsh
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_completion_bash.md

@@ -51,4 +51,4 @@ fox completion bash
 
 * [fox completion](fox_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_completion_fish.md

@@ -42,4 +42,4 @@ fox completion fish [flags]
 
 * [fox completion](fox_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_completion_powershell.md

@@ -39,4 +39,4 @@ fox completion powershell [flags]
 
 * [fox completion](fox_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_completion_zsh.md

@@ -53,4 +53,4 @@ fox completion zsh [flags]
 
 * [fox completion](fox_completion.md)	 - Generate the autocompletion script for the specified shell
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_config.md

@@ -30,4 +30,4 @@ Use the config subcommand to help setup your local environment.
 * [fox config setup](fox_config_setup.md)	 - Run setup to configure 🦊 Fox
 * [fox config show](fox_config_show.md)	 - Show the current configuration
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_config_setup.md

@@ -26,4 +26,4 @@ fox config setup [flags]
 
 * [fox config](fox_config.md)	 - Configure 🦊 Fox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_config_show.md

@@ -26,4 +26,4 @@ fox config show [flags]
 
 * [fox config](fox_config.md)	 - Configure 🦊 Fox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_deploy.md

@@ -32,4 +32,4 @@ fox deploy [NAME] [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_docs.md

@@ -33,4 +33,4 @@ fox docs [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_init.md

@@ -35,4 +35,4 @@ fox init [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_proxy.md

@@ -58,4 +58,4 @@ fox proxy (PORT) [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_publish.md

@@ -37,4 +37,4 @@ fox publish [NAME] [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_release.md

@@ -55,4 +55,4 @@ fox release (NAME | COMMIT | SHORT COMMIT | VERSION | TAG | BRANCH) [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023

docs/fox/fox_version.md

@@ -26,4 +26,4 @@ fox version [flags]
 
 * [fox](fox.md)	 - CLI for interacting with KubeFox
 
-###### Auto generated by spf13/cobra on 5-Dec-2023
+###### Auto generated by spf13/cobra on 6-Dec-2023