Update contexts documentation

docs/concepts/configuration/context.md

@@ -1,19 +1,31 @@
 # Context
 
+!!! note
+    For the sake of brevity we'll be using the term _projects_ to refer to both stacks and modules.
+
 ## Introduction
 
+{% if is_self_hosted() %}
 On a high level, context is a bundle of configuration elements ([environment variables](environment.md#environment-variables) and [mounted files](environment.md#mounted-files)) independent of any [stack](../stack/README.md) that can be managed separately and [attached](context.md#attaching-a-context) to as many or as few stacks as necessary. Contexts are only directly accessible to administrators from the account view:
 
 ![](../../assets/screenshots/context.png)
 
 The list of contexts merely shows the name and description of the context. Clicking on the name allows you to [edit it](context.md#editing-a-context).
+{% else %}
+On a high level, context is a bundle of configuration elements ([environment variables](environment.md#environment-variables), [mounted files](environment.md#mounted-files) and [hooks](../stack/stack-settings.md#customizing-workflow)) independent of any [stack](../stack/README.md) that can be managed separately and [attached](context.md#attaching-a-context) to as many or as few projects as necessary. Contexts are only directly accessible to administrators from the account view:
+
+![](../../assets/screenshots/context/contexts_list.png)
+
+The list of contexts merely shows the name, description and labels of the context. You can [edit a context](context.md#editing-a-context) from the list by clicking on the three-dot menu on the right hand side of the context row and selecting the _Edit_ option, you can also [delete a context](context.md#deleting) from the same menu.
+{% endif %}
 
 ## Management
 
 Managing a context is quite straightforward - you can [create](context.md#creating), [edit](context.md#editing), [attach, detach](context.md#attaching-and-detaching) and [delete](context.md#deleting) it. The below paragraphs will focus on doing that through the web GUI but doing it programmatically using [our Terraform provider](../../vendors/terraform/terraform-provider.md) is an attractive alternative.
 
 ### Creating
 
+{% if is_self_hosted() %}
 As an account administrator you can create a new context from the Contexts screen as seen on the above screenshot by pressing the Add context button:
 
 ![](../../assets/screenshots/create_context_button.png)
@@ -30,19 +42,137 @@ The optional _description_ is completely free-form and it supports [Markdown](ht
     Based on the original _name_, Spacelift generates an immutable slug that serves as a unique identifier of this context. If the name and the slug diverge significantly, things may become confusing.
 
     So even though you can change the context name at any point, we strongly discourage all non-trivial changes.
+{% else %}
+As an account administrator you can create a new context from the Contexts screen as seen on the screenshot below by pressing the _{% if is_self_hosted() %}Add{% else %}Create{% endif %} context_ button:
+
+![](../../assets/screenshots/context/create_context_button.png)
+
+This takes you to a creation form where you can configure various aspects of the context.
+
+#### Step 1 - Context details
+
+This is the only mandatory step in the context creation process; the remaining steps are optional.
+
+![](../../assets/screenshots/context/creation_form_step_1.png)
+
+The required _name_ is what you'll see in the context list and in the dropdown when attaching the context to projects. Ensure it's informative enough to immediately convey the purpose of the context, yet short enough to fit neatly in dropdowns without cutting off important information.
+
+The last required field in this step is _space_, allowing you to choose which [space](/concepts/spaces/) the context will belong to.
+
+The optional _description_ is free-form and supports [Markdown](https://daringfireball.net/projects/markdown/){: rel="nofollow"}. This is an ideal place for a thorough explanation of the context's purpose, perhaps with links or a humorous GIF. In the web GUI, this description appears in several places: on the context list, in the context view, and in the list of attached contexts on the stack view.
+
+Lastly you can add _labels_ to the context. Labels are a great way to organize your contexts and make them easier to find. They also provide a powerful feature of [auto-attaching](#auto-attachments) contexts to projects. If you'll be using `autoattach` labels, all projects that would be automatically attached to the context will be listed below in the collapsible section:
+
+![](../../assets/screenshots/context/create_stack_auto_attached_stack.png)
+
+!!! warning
+    Based on the original _name_, Spacelift generates an immutable slug that serves as a unique identifier for this context. If the name and the slug diverge significantly, things may become confusing.
+
+    Even though you can change the context name at any point, we strongly discourage all non-trivial changes.
+
+#### Step 2 - Attach context (optional)
+
+This step enables you to attach the context to projects without navigating to their respective "Contexts" views. Simply select the project from the dropdown and click the _Attach_ button.
+
+![](../../assets/screenshots/context/creation_form_step_2.png)
+
+#### Step 3 - Setup environment (optional)
+
+In this step, you have the option to configure environment variables and mounted files if you already have them ready during the creation of the context.
+
+| Environment variables | Mounted files |
+| - | - |
+| ![](../../assets/screenshots/context/creation_form_step_2a.png) | ![](../../assets/screenshots/context/creation_form_step_2b.png) |
+
+#### Step 4 - Add hooks (optional)
+
+Hooks are optional scripts that can be set up to run before and/or after different project phases, automating tasks at specific points in the project lifecycle.
+
+![](../../assets/screenshots/context/creation_form_step_4.png)
+
+To add a hook simply select the phase at which it should be run and enter the command in the text box inside either "Before" or "After" section, click the _Add_ button and you're done. You can add as many hooks as you like, and they will run in the order they appear.
+
+After adding a hook, you can easily rearrange it within a section or move it to the other section by dragging and dropping:
+
+![](../../assets/screenshots/context/context_hooks_reordering.gif)
+
+That's it! Press the _Create context_ button to save the context and go to its view.
+{% endif %}
 
 ### Editing
 
+{% if is_self_hosted() %}
 Editing the context is only a little more exciting. You can edit the context from its dedicated view by pressing the Edit button:
 
 ![](../../assets/screenshots/context_edit_button.png)
 
 This switches the context into editing mode where you can change the name and description but also manage configuration elements the same way you'd do for the [stack environment](environment.md), only much simpler - without overrides and [computed values](environment.md#computed-values):
 
 ![](../../assets/screenshots/context_edit_mode.png)
+{% else %}
+You can edit various aspects of a context, such as its details, attached projects, environment variables, mounted files and hooks. The only immutable aspect is the context's slug.
+
+#### Editing the details
+
+To edit the details of a context, go to its dedicated view and press the _Edit_ button from the three-dot menu:
+
+![](../../assets/screenshots/context/edit_from_context_view.png)
+
+This will open a drawer with the details form pre-populated with the current values:
+
+![](../../assets/screenshots/context/edit_context_details_drawer.png)
+
+Note: The same form is also accessible from the context list view.
+
+#### Editing environment variables
+
+The first tab in the context view is the _Variables_ tab. Here, you'll find a list of all the environment variables associated with this context. To edit a variable, click the three-dot menu on the right-hand side of the variable row and select the _Edit_ option.
+
+![](../../assets/screenshots/context/edit_env_var_option.png)
+
+This will open a drawer where you can edit the variable's properties such as value, description, and sensitivity.
+
+![](../../assets/screenshots/context/edit_env_var.png)
+
+Remember, changes to environment variables will affect all projects using this context. Be cautious when making changes to avoid unintended side effects.
+
+#### Editing mounted files
+
+To manage mounted files associated with a context, navigate to the second tab in the context view – _Mounted files_.
+
+You can preview the contents of a non-secret mounted file by clicking on the file name. To edit it, click the three-dot menu on the right-hand side of the file row and select the _Edit_ option.
+
+!!!note
+    You can preview and edit the content of a mounted file only if it wasn't saved as a secret. Such files can be overwritten by uploading a new file or entering content directly in the editor.
+
+![](../../assets/screenshots/context/edit_mounted_file.png)
+
+Adding a new mounted file involves two steps:
+
+1. Provide the file's name, description, and specify whether it's a secret.
+    ![](../../assets/screenshots/context/add_mounted_file_a.png)
+
+2. Then, provide the file's content by either uploading a file or entering it manually.
+    ![](../../assets/screenshots/context/add_mounted_file_b.png)
+
+When ready to save the mounted file, click the _Save_ button. To discard it completely, click _Cancel_.
+
+#### Editing hooks
+
+In the context view, navigate to the _Hooks_ tab, the third tab dedicated to managing hooks. Hooks are categorized neatly by different project phases, each represented as a collapsible section with "Before" and "After" lists.
+
+Open the section corresponding to the specific phase you wish to modify by clicking on its name.
+
+![](../../assets/screenshots/context/hooks_list.png)
+
+You can add a new command, adjust its position within the same section, or even move it to the other section using a simple drag-and-drop mechanism. Once you've made the necessary adjustments, click _Save_ to apply the edits.
+
+Remember, the order of hooks matters; they run in the sequence they appear in the list.
+{% endif %}
 
 ### Attaching and detaching
 
+{% if is_self_hosted() %}
 Attaching and detaching contexts actually happens from the [stack](../stack/README.md) management view. To attach a context, select the Contexts tab. This should show you a dropdown with all the contexts available for attaching, and a slider to set the [priority of the attachment](context.md#a-note-on-priority):
 
 ![](../../assets/screenshots/context_attach.png)
@@ -65,19 +195,75 @@ Now this attached context will also contribute to the [stack environment](enviro
 In order to detach the context, you can just press the _Detach_ button and the context will stop contributing to the [stack's environment](environment.md):
 
 ![](../../assets/screenshots/context_detach.png)
+{% else %}
+Attaching and detaching contexts actually happens from the [stack](../stack/README.md) view. To attach a context, go to the _Contexts_ tab. This tab lists all manually and auto-attached contexts to the stack, and allows you to attach new ones:
+
+![](../../assets/screenshots/context/contexts_list_in_stack_view.png)
+
+OK, let's attach the context with priority 0 and see what gives:
+
+![](../../assets/screenshots/context/attach_context_to_stack.png)
+
+![](../../assets/screenshots/context/contexts_list_in_stack_after_attaching.png)
+
+Now this attached context will also contribute to the [stack environment](environment.md)...
+
+![](../../assets/screenshots/context/context_envs_in_stack_view.png)
+
+...and be visible on the list of attached contexts:
+
+![](../../assets/screenshots/context/attached_context_envs.png)
+
+In order to detach a context, go back to the Contexts tab, click on the context's priority picker and select the _Detach_ option which will stop the context from contributing to the [stack's environment](environment.md):
+
+![](../../assets/screenshots/context/detach_context.png)
+{% endif %}
+
+{% if is_saas() %}
+#### Auto-attachments
+
+The `autoattach` label is a powerful tool in contexts and policies that enables automatic attachment of these entities to projects based on shared labels. This comes in handy, especially when multiple projects require the same context.
+
+Instead of manually attaching a context to every stack or module, simply define an `autoattach` label on the context. For example, adding the label `autoattach:XYZ` to a context will cause the system to automatically attach that context to all projects with the matching `XYZ` label.
+
+!!! Note
+    You only need the `autoattach:` prefix for the context label; the projects only need the specific label (`XYZ`) to activate the automatic attachment.
+
+Here's how you can set it up:
+
+1. Navigate to the context view and open the context [details drawer](context.md#editing-the-details).
+
+2. Define an `autoattach` label to the context. For instance, `autoattach:XYZ`.
+   ![](../../assets/screenshots/context/add_autoattachment_label.png)
+
+3. Ensure that your projects have the matching label. In this case, it should be `XYZ`.
+   ![](../../assets/screenshots/context/stack_settings_matching_autoattachment_label.png)
+
+Once complete, Spacelift will automatically link the context to all projects sharing the `XYZ` label.
+{% endif %}
 
 #### A note on priority
 
-You may be wondering what the priority slider is for. A priority is a property of context-stack relationship - in fact, the only property. All the contexts attached to a stack are sorted by priority (lowest first), though values don't need to be unique. This ordering establishes [precedence rules](environment.md#a-note-on-precedence) between contexts should there be a conflict and multiple contexts define the same value.
+You may be wondering what the priority {% if is_self_hosted() %}slider{% else %}picker{% endif %} is for. A priority is a property of context-stack relationship - in fact, the only property. All the contexts attached to a stack are sorted by priority (lowest first), though values don't need to be unique. This ordering establishes [precedence rules](environment.md#a-note-on-precedence) between contexts should there be a conflict and multiple contexts define the same value.
 
 ### Deleting
 
+{% if is_self_hosted() %}
 Deleting a context is straightforward - by pressing the Delete button in the context view you can get rid of an unnecessary context:
 
 ![](../../assets/screenshots/context_delete.png)
+{% else %}
+Deleting a context is straightforward - by selecting the _Delete_ option from the three-dot menu in the context view you can get rid of an unnecessary context:
+
+![](../../assets/screenshots/context/delete_from_context_view_option.png)
+
+As a safety measure, you'll be asked to confirm the deletion:
+
+![](../../assets/screenshots/context/delete_context_confirmation.png)
+{% endif %}
 
 !!! warning
-    Deleting a context will also automatically detach it from all the stacks it was attached to. Make sure you only delete contexts that are no longer useful. For security purposes we do not store historical stuff and actually remove the deleted data from all of our data storage systems.
+    Deleting a context will also automatically detach it from all the projects it was attached to. Make sure you only delete contexts that are no longer useful. For security purposes we do not store historical stuff and actually remove the deleted data from all of our data storage systems.
 
 ## Use cases