[DRAFT] TW-1722: Integrate offline Workflow Editor into the docs

docs/bitrise-ci/bitrise-cli/index.md

@@ -1,7 +1,23 @@
 ---
 title: "Bitrise CLI"
+description: "The Bitrise CLI is the open-source runner that powers every build on bitrise.io. Install it locally to run builds, edit your bitrise.yml in the offline Workflow Editor, and develop new Steps."
 sidebar_position: 9
 slug: /bitrise-ci/bitrise-cli
 ---
 
-Bitrise CLI
+The Bitrise CLI is the open-source runner that powers every build on [bitrise.io](https://www.bitrise.io). The same binary runs on your machine, so you can:
+
+- Run a build locally against your project's `bitrise.yml` — same Steps, same Workflow, same outputs as the cloud build.
+- Edit your configuration in the [offline Workflow Editor](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor) — the same graphical UI as bitrise.io, running on your computer.
+- Initialize a new Bitrise project from a local Git repository before adding it to bitrise.io.
+- Develop and test custom Steps before publishing them to the StepLib.
+- Manage Secrets locally for trusted-only access during development.
+
+## What's in this section
+
+- [Installing and updating the Bitrise CLI](/en/bitrise-ci/bitrise-cli/installing-and-updating-the-bitrise-cli) — get the CLI on macOS or Linux.
+- [Adding a new project from a CLI](/en/bitrise-ci/bitrise-cli/adding-a-new-project-from-a-cli) — register a local project on Bitrise without using the web UI.
+- [Initializing a Bitrise project locally](/en/bitrise-ci/bitrise-cli/initializing-a-bitrise-project-locally) — generate a starter `bitrise.yml` for an existing repository.
+- [Offline Workflow Editor](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor) — edit your `bitrise.yml` with the graphical UI, locally and offline.
+- [Managing Secrets locally](/en/bitrise-ci/bitrise-cli/managing-secrets-locally) — keep credentials out of `bitrise.yml`.
+- [Running your first local build with the CLI](/en/bitrise-ci/bitrise-cli/running-your-first-local-build-with-the-cli) — verify changes before pushing.

docs/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor.mdx

@@ -1,7 +1,9 @@
 ---
-title: "Installing and upgrading the offline Workflow Editor"
+title: "Offline Workflow Editor"
+description: "The offline Workflow Editor is the same graphical UI you use on bitrise.io, running on your local machine against your bitrise.yml. Configure your build pipeline without an internet connection."
 sidebar_position: 4
 slug: /bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor
+sidebar_label: Offline Workflow Editor
 ---
 
 import Tabs from '@theme/Tabs';
@@ -11,10 +13,49 @@ import Partial_InstallingTheOfflineWorkflowEditorToYourComputer from '@site/src/
 import Partial_UpgradingWorkflowEditorVersion from '@site/src/partials/upgrading-workflow-editor-version.mdx';
 import Partial_StartingTheOfflineWorkflowEditor from '@site/src/partials/starting-the-offline-workflow-editor.mdx';
 
-Bitrise Workflow Editor is designed in such a way that you can run it offline on your Mac/PC without having to log into [bitrise.io](https://www.bitrise.io/). The Workflow Editor is open source, you can find its repository [here](https://github.com/bitrise-io/bitrise-workflow-editor). You can also join the discussion around Workflow Editor [here](https://discuss.bitrise.io/t/workflow-editor-v2-open-source-offline-workflow-editor/39).
+The offline Workflow Editor gives you the same graphical Workflow Editor you use on [bitrise.io](https://www.bitrise.io/), running locally against your project's `bitrise.yml` file. You don't need an internet connection or a Bitrise login to use it — your configuration stays on your machine until you push it back to the repository.
+
+The Workflow Editor is open source. The code is on [GitHub](https://github.com/bitrise-io/bitrise-workflow-editor), and the design discussion lives on the [Bitrise discussion forum](https://discuss.bitrise.io/t/workflow-editor-v2-open-source-offline-workflow-editor/39).
+
+## What you can do with it
+
+Once it's running, you have access to the parts of the Workflow Editor that operate on your `bitrise.yml`:
+
+- Browse, add, remove, and reorder <GlossTerm baseform="Step">Steps</GlossTerm> from the [Bitrise StepLib](https://github.com/bitrise-io/bitrise-steplib).
+- Edit Step inputs in the UI without touching YAML by hand.
+- Create, rename, and chain <GlossTerm baseform="Workflow">Workflows</GlossTerm>.
+- Define [Step bundles](/en/bitrise-ci/workflows-and-pipelines/steps/step-bundles) and use them across Workflows.
+- Configure [build triggers](/en/bitrise-ci/run-and-analyze-builds/build-triggers/configuring-build-triggers) and [Pipelines](/en/bitrise-ci/workflows-and-pipelines/build-pipelines/configuring-a-bitrise-pipeline).
+- Switch between graphical view and raw `bitrise.yml` view in real time.
+
+## When to use it
+
+The offline Workflow Editor is a good fit when you want to:
+
+- **Iterate on `bitrise.yml` without a network round-trip.** Local edits are instant.
+- **Edit configuration on a developer machine** before committing it to the repository, so the change goes through code review like any other source change.
+- **Work without exposing the configuration to bitrise.io** — useful in air-gapped or restricted-network environments.
+- **Run [local builds with the Bitrise CLI](/en/bitrise-ci/bitrise-cli/running-your-first-local-build-with-the-cli) against the same edited config** without leaving your terminal.
+
+If your project [stores `bitrise.yml` in the repository](/en/bitrise-ci/configure-builds/configuration-yaml/managing-a-projects-configuration-yaml-file/storing-the-bitriseyml-file-in-your-repository), the offline Workflow Editor pairs especially well with that setup: edit locally, commit, push — bitrise.io picks up the new config on the next build.
 
 <Partial_InstallingTheOfflineWorkflowEditorToYourComputer />
 
 <Partial_StartingTheOfflineWorkflowEditor />
 
 <Partial_UpgradingWorkflowEditorVersion />
+
+## Best practices
+
+- **Run it from the project root.** `bitrise :workflow-editor` reads the `bitrise.yml` from the current directory. Always `cd` into the project root before starting it so it edits the right file.
+- **Keep your StepLib refreshed.** Run `bitrise plugin update workflow-editor` periodically — the offline editor caches its Step list, so refreshing keeps you on the latest Step versions.
+- **Commit each change.** Treat the offline editor like any other source modification — add the updated `bitrise.yml` to a branch, run `git diff`, open a pull request. The full configuration history then lives in your repository.
+- **Reach for the YAML view when needed.** The graphical UI covers most cases, but features like [modular YAML configuration](/en/bitrise-ci/configure-builds/configuration-yaml/modular-yaml-configuration) or fine-grained [trigger map](/en/bitrise-ci/run-and-analyze-builds/build-triggers/yaml-syntax-of-build-triggers) edits are easier in raw YAML — switch tabs.
+- **Run a local build to verify.** After saving changes, run [a local build with the Bitrise CLI](/en/bitrise-ci/bitrise-cli/running-your-first-local-build-with-the-cli) before pushing. The offline editor only validates structure; a local build catches Step input mistakes early.
+
+## Related topics
+
+- [Installing and updating the Bitrise CLI](/en/bitrise-ci/bitrise-cli/installing-and-updating-the-bitrise-cli) — prerequisite for the offline Workflow Editor.
+- [Editing an app's bitrise.yml file](/en/bitrise-ci/configure-builds/configuration-yaml/editing-an-app-s-bitrise-yml-file) — the three ways to edit `bitrise.yml`, including locally.
+- [Storing the bitrise.yml file in your repository](/en/bitrise-ci/configure-builds/configuration-yaml/managing-a-projects-configuration-yaml-file/storing-the-bitriseyml-file-in-your-repository) — the natural pairing for offline editing.
+- [Running your first local build with the CLI](/en/bitrise-ci/bitrise-cli/running-your-first-local-build-with-the-cli) — verify your changes locally before pushing.

docs/bitrise-ci/workflows-and-pipelines/steps/adding-steps-to-a-workflow.mdx

@@ -16,6 +16,12 @@ Steps can be added or removed any time from your Workflows. When adding a new ap
 
 You can add any Step to your Workflow - there are absolutely no restrictions. Please note that this means that it’s possible to add a Step specific to, for example, iOS apps to a Workflow of an Android app. Always make sure you only add the relevant Steps to your Workflow!
 
+:::tip[Add Steps offline]
+
+The same Step browser is available in the [offline Workflow Editor](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor). After installing it, run `bitrise :workflow-editor` from your project root and edit `bitrise.yml` against the same StepLib without leaving your machine.
+
+:::
+
 <Partial_AddingStepsInTheWorkflowEditor />
 
 <Partial_AddingStepsFromAlternativeSources />

docs/bitrise-ci/workflows-and-pipelines/steps/steps-overview.mdx

@@ -20,7 +20,7 @@ You can find a list of our Steps in:
 
 - [The Integrations page](https://www.bitrise.io/integrations).
 - [The Bitrise StepLib](https://github.com/bitrise-io/bitrise-steplib).
-- The Workflow Editor.
+- The Workflow Editor (both [online on bitrise.io](https://www.bitrise.io/) and the [offline Workflow Editor](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor) running locally).
 
 You can also create and run any custom script you want as part of your Bitrise build using the [**Script**](https://www.bitrise.io/integrations/steps/script) Step. All you need to do is specify the script runner (the default is bash), add the script, and run a build. For more information on how to set up these custom scripts, check out [Bitrise Script Step - Running (Bash, Python, NodeJS, Ruby, Swift, Kotlin)](https://support.bitrise.io/hc/en-us/articles/8932506599955-Bitrise-Script-Step-Running-Bash-Python-NodeJS-Ruby-Swift-Kotlin-).
 

docs/bitrise-ci/workflows-and-pipelines/workflows/creating-a-workflow.mdx

@@ -16,6 +16,12 @@ This guide is about creating a Workflow in the Workflow Editor. For YAML configu
 
 :::
 
+:::tip[Works offline too]
+
+The same steps work in the [offline Workflow Editor](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor) running on your machine. Helpful when you want to draft a Workflow against a local `bitrise.yml` before committing.
+
+:::
+
 It’s very simple to create your own <GlossTerm baseform="Workflow">Workflow</GlossTerm> with the Workflow Editor. You can create new Workflows based on any of the existing ones, or you can simply create an empty Workflow and add the Steps yourself.
 
 If, for example, you create a Workflow based on your **primary** one, it means that it will be created with the exact same Steps and input values as the **primary** Workflow.

docs/bitrise-ci/workflows-and-pipelines/workflows/workflows-overview.mdx

@@ -11,11 +11,17 @@ import GlossTerm from '@site/src/components/GlossTerm';
 
 A Bitrise Workflow is a collection of Steps. When a build of a <GlossTerm baseform="App">project</GlossTerm> is running, each <GlossTerm baseform="Step">Step</GlossTerm> will be executed in the order that is defined in the Workflow. Workflows can be created, defined and modified in two ways:
 
-- Using the graphical Workflow Editor on [bitrise.io](https://www.bitrise.io), or [the offline version on your own device](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor.html).
+- Using the graphical Workflow Editor on [bitrise.io](https://www.bitrise.io).
 - Directly editing the <GlossTerm baseform="`bitrise.yml`">`bitrise.yml`</GlossTerm> file of your project.
 
 Ultimately, both methods modify the `bitrise.yml` file - the **Workflow Editor** is simply a friendlier way of doing so!
 
+:::tip[Edit your Workflows offline]
+
+The same graphical Workflow Editor runs on your local machine through the [offline Workflow Editor](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor). You get the same UI without an internet connection or a Bitrise login — useful for editing `bitrise.yml` locally and committing it through your normal review process.
+
+:::
+
 By default, a single build is a single Workflow. But you can also chain Workflows together so they run in succession, as well as to trigger multiple Workflow to run simultaneously.
 
 Workflows can also be arranged into [Pipelines](/en/bitrise-ci/workflows-and-pipelines/build-pipelines/pipelines-with-stages.html). A Pipeline consists of multiple Stages and each Stage consists of one or more Workflows which run in parallel.

src/partials/editing-the-bitriseyml-file-locally.mdx

@@ -26,3 +26,9 @@ The following editors support the auto-complete feature:
   ![autocomplete.png](/img/_paligo/uuid-949123a0-1356-b913-0a17-cd7270ba78c3.png)
 
 After editing your file locally, you can either copy its contents to the online `bitrise.yml` file or you can [store it in your own repository](/en/bitrise-ci/configure-builds/configuration-yaml/managing-a-projects-configuration-yaml-file/storing-the-bitriseyml-file-in-your-repository).
+
+:::tip[Prefer a graphical editor?]
+
+The same Workflow Editor you use on bitrise.io also runs locally — see the [offline Workflow Editor](/en/bitrise-ci/bitrise-cli/installing-and-upgrading-the-offline-workflow-editor). It edits the `bitrise.yml` in your project root, so you get a visual UI and can still keep the file under version control.
+
+:::