Merge pull request #573 from mulesoft/W-21085959-workspaces-improvements

W-21085959 workspaces improvements

Author: Cristian-Venticinque

modules/ROOT/nav.adoc

@@ -12,6 +12,7 @@
 ** xref:start-add-folders.adoc[]
 ** xref:start-open-output-panel.adoc[]
 ** xref:start-scm.adoc[]
+** xref:start-workspaces.adoc[]
 
 // TUTORIALS
 * xref:tutorials.adoc[]

modules/ROOT/pages/af-create-agent-network.adoc

@@ -55,3 +55,4 @@ If you run operations within a CI/CD environment, you can use Anypoint CLI's plu
 == See Also
 
 * xref:af-define-your-agent-network-specification.adoc[]
+* xref:start-workspaces.adoc[]

modules/ROOT/pages/des-create-api-specs.adoc

@@ -283,9 +283,11 @@ If you created an OAS 3.0 (YAML) project, you can replace the initial spec with
 
 == See Also
 
+
 * xref:start-acb.adoc[]
 * xref:tutorials.adoc[]
 * xref:access-management::business-groups.adoc[]
 * xref:start-discover-ui.adoc#use-autocomplete[Use Auto-Complete in the Editors]
 * xref:tut-af-design-am-flights-api.adoc[] Tutorial
-* xref:des-delete-api-projects.adoc[]
+* xref:des-delete-api-projects.adoc[]
+* xref:start-workspaces.adoc[]

modules/ROOT/pages/imp-implement-local-apis.adoc

@@ -36,7 +36,9 @@ For your projects to work properly, the `.code-workspace` file _must not reside_
 
 In addition, Anypoint Code Builder permits only one pair of iterative design and implementation project folders per multi-root workspace.
 
-For more information, see https://code.visualstudio.com/docs/editor/multi-root-workspaces[Multi-root Workspaces^] in the VS Code documentation.
+For general information about using workspaces in Anypoint Code Builder, see xref:start-workspaces.adoc[].
+
+For more information about VS Code workspaces, see https://code.visualstudio.com/docs/editor/multi-root-workspaces[Multi-root Workspaces^] in the VS Code documentation.
 
 
 == Before You Begin 
@@ -120,7 +122,7 @@ which you then implement within a Mule application.
 You can switch between the spec and the implementation project in the Explorer view.
 
 
-To close your multi-root workspace, see <<close-workspace>>. 
+To close or reopen your workspace later, see xref:start-workspaces.adoc[Working with Workspaces]. 
 
 
 [[rescaffold-api-spec]]
@@ -143,42 +145,7 @@ After you see the message that your project was rescaffolded successfully, navig
 //TODO:
 // ADD NOTE ABOUT caveats for rescaffolding AsyncAPI specs?
 
-[[close-workspace]]
-== Close a Multi-Root Workspace
-
-To close the workspace:
-
-// Pointer to Command Palette
-include::partial$acb-reusable-steps.adoc[tags="open-command-palette"]
-. Select the following command:
-+
-[source,command]
-----
-Workspaces: Close Workspace
-----
-
-After closing, you can reopen a synchronized project from the workspace that you created when implementing the API.
-See <<open-workspace>>.
-
-[[open-workspace]]
-== Open a Multi-Root Workspace
-
-To open a multi-root workspace from the `.code-workspace` file: 
-
-// Pointer to Command Palette
-include::partial$acb-reusable-steps.adoc[tags="open-command-palette"]
-. Select the following command:
-+
-[source,command]
-----
-File: Open Workspace from File...
-----
-. Navigate to your home directory and double-click the `.code-workspace` file for the workspace.
-+
-The projects open in the Explorer view, and the folder name for the multi-root workspace includes *(WORKSPACE)*, for example:
-+
-image::imp-local-api-open-workspace.png["A multi-root workspace in Explorer view"]
-
 == See Also
 
+* xref:start-workspaces.adoc[]
 * xref:tut-local-api-specification.adoc[] Tutorial

modules/ROOT/pages/int-create-integrations.adoc

@@ -130,6 +130,7 @@ The file's canvas provides the same options for building your project file that
 
 == See Also
 
+* xref:start-workspaces.adoc[]
 * xref:acb-reference.adoc[]
 * xref:int-work-with-code-snippets.adoc[]
 * xref:debugging-mule-apps.adoc[]

modules/ROOT/pages/int-import-mule-project.adoc

@@ -183,3 +183,8 @@ include::partial$acb-open-packaged-sources.adoc[tags="open-workspace-root"]
 include::partial$acb-open-packaged-sources.adoc[tags="load-project"]
 //step: test project
 include::partial$acb-open-packaged-sources.adoc[tags="test-project"]
+
+== See Also
+
+* xref:start-workspaces.adoc[]
+* xref:int-export-mule-project.adoc[]

modules/ROOT/pages/int-migrate-studio-to-acb.adoc

@@ -20,4 +20,5 @@ include::partial$acb-project-migration.adoc[tag="import-mule-project-into-acb"]
 
 == See Also
 
+* xref:start-workspaces.adoc[]
 * xref:int-import-mule-project.adoc[] 

modules/ROOT/pages/start-workspaces.adoc

@@ -0,0 +1,161 @@
+= Working with Workspaces
+:page-deployment-options: cloud-ide, desktop-ide
+
+include::reuse::partial$beta-banner.adoc[tag="anypoint-code-builder"]
+
+Organize your Mule projects in workspaces to ensure all Anypoint Code Builder features work correctly. Workspaces help you manage multiple related projects and avoid build-time and design-time issues.
+
+[[valid-setups]]
+== Valid Setups for Anypoint Code Builder
+
+Anypoint Code Builder requires one of the following project configurations to function properly:
+
+* A single Mule project open at the root of your directory
+* A multi-root workspace pointing directly to one or more Mule projects
+
+If your directory structure doesn't meet these requirements, Anypoint Code Builder displays a message with steps to resolve the issue, such as opening a Mule project or creating a workspace. See <<fix-nested-project>>.
+
+[[create-project-workspace]]
+== Create a Project in a Workspace
+
+When you create a new project, add it to a workspace. With this setup you can add more projects later without restructuring your environment.
+
+To create a project in a workspace:
+
+. Start the project creation process using one of the following methods:
++
+** From the *Quick Actions* menu, select the project type. 
++
+For example, *Design an API* or *Develop an Integration*.
+** From the Command Palette, run the appropriate command.
++
+For example, `MuleSoft: Design an API`.
+** Ask MuleSoft Vibes to create the project using natural language.
+
+. In the project creation form, select *Create in workspace*.
+. Complete the remaining project configuration options.
+. Click *Create Project*.
++
+Anypoint Code Builder creates the project and adds it to a workspace. If no workspace is open, a new workspace is created.
+
+[[import-studio-workspace]]
+== Import an Anypoint Studio Workspace
+
+If you have existing projects in Anypoint Studio, you can import your Studio workspace into Anypoint Code Builder.
+
+To import a Studio workspace:
+
+// Pointer to Command Palette
+include::partial$acb-reusable-steps.adoc[tags="open-command-palette"]
+. Select the following command:
++
+[source,command]
+----
+MuleSoft: Import Studio Workspace
+----
+. Navigate to the location of your Studio workspace and select it.
+. Choose a location to save the new workspace file.
++
+Anypoint Code Builder creates a workspace that references your existing Studio projects. Changes made to the original Studio workspace are automatically reflected in Anypoint Code Builder.
+
+[[switch-workspaces]]
+== Open and Switch Between Workspaces
+
+You can open or switch between workspaces using the menu, the Command Palette, or MuleSoft Vibes.
+
+=== Open a Workspace Manually
+
+. Open the workspace file using one of these methods:
++
+* From the menu bar, select *File* > *Open Workspace from File...*.
+* From the Command Palette, run the command `File: Open Workspace from File...`.
+. Navigate to the location where you saved the `.code-workspace` file (for example, your home directory or a dedicated workspaces folder), and select it.
++
+The projects open in the Explorer view, and the folder name for the workspace includes *(WORKSPACE)* to indicate that you're working in a multi-root workspace:
++
+image::imp-local-api-open-workspace.png["A multi-root workspace in Explorer view"]
+
+=== Open a Workspace with MuleSoft Vibes
+
+You can ask MuleSoft Vibes to switch workspaces using natural language prompts, such as:
+
+* "Open my American Flights workspace"
+* "Switch to the `<YourWorkspaceName>` workspace"
+
+[[close-workspace]]
+== Close a Workspace
+
+To close the current workspace:
+
+// Pointer to Command Palette
+include::partial$acb-reusable-steps.adoc[tags="open-command-palette"]
+. Select the following command:
++
+[source,command]
+----
+Workspaces: Close Workspace
+----
+
+[[actions-in-workspaces]]
+== Actions in Workspaces
+
+Anypoint Code Builder organizes actions based on their scope:
+
+[cols="1,2"]
+|===
+| Action Type | Location
+
+| *Global actions*
+| Always available from the Command Palette. These actions don't depend on a specific project, such as creating a new project, importing assets from Exchange, or opening Anypoint Code Builder settings.
+
+| *Project-specific actions*
+| Available from the context menu (right-click) in the Explorer view. These actions apply to a specific project, such as running, debugging, deploying, or exporting a project.
+|===
+
+When working with multiple projects in a workspace, select the target project before running project-specific actions. For example, when you run or debug, you must select which project in the workspace to execute.
+
+[[workspace-file]]
+== Workspace File Location
+
+VS Code stores workspace configuration in a file with the `.code-workspace` extension. This file maps the folders for your projects.
+
+[IMPORTANT]
+====
+The `.code-workspace` file must not reside within any of your project folders. Save it in a separate directory, such as your home directory or a dedicated workspaces folder.
+====
+
+[[fix-nested-project]]
+== Fix a Nested Project Error
+
+This error appears when you open a folder that contains your Mule project instead of opening the project directly, and that folder isn't configured as a multi-root workspace.
+
+To fix this issue, open the project folder at the root level or add it to a multi-root workspace.
+
+=== Open the Project at the Root
+
+If you're working with a single project, open it directly so it appears at the top level of the Explorer view.
+
+. From the menu bar, select *File* > *Open Folder...*.
+. Navigate to your Mule project's root folder (the folder containing the `pom.xml` file).
+. Select the folder and click *Open*.
++
+The project now appears at the top level of the Explorer view, and Anypoint Code Builder features are available.
+
+=== Add the Project to a Multi-Root Workspace
+
+If you want to keep your current folder structure or work with multiple projects, create a multi-root workspace that points directly to your Mule project.
+
+. From the menu bar, select *File* > *Add Folder to Workspace...*.
+. Navigate to your Mule project's root folder and select it.
+. When prompted, save the workspace file (`.code-workspace`) to a location outside of your project folders.
++
+The project appears in the Explorer view with the *(WORKSPACE)* indicator, and Anypoint Code Builder features are available.
+
+TIP: If you frequently work with multiple projects, creating a workspace from the start avoids this issue. See <<create-project-workspace>>.
+
+== See Also
+
+* xref:imp-implement-local-apis.adoc[Iteratively Design and Implement APIs]
+* xref:int-create-integrations.adoc[Creating Integrations]
+* xref:des-create-api-specs.adoc[Creating and Importing API Specifications]
+* https://code.visualstudio.com/docs/editor/multi-root-workspaces[Multi-root Workspaces^] in the VS Code documentation

modules/ROOT/pages/troubleshoot-loading-errors.adoc

@@ -63,7 +63,7 @@ File: Open Folder...
 +
 The root is the top-level folder that Anypoint Code Builder generates when it creates a project. Do not navigate to the project's parent or ancestor directory or to one of its child or descendant directories.
 
-See also xref:int-import-mule-project.adoc[].
+See also xref:int-import-mule-project.adoc[] and xref:start-workspaces.adoc[].
 
 [[mule-dx]]
 == Mule DX API Component Was Not Installed

modules/ROOT/pages/vibes-conversation-history.adoc

@@ -1,5 +1,4 @@
 = View Conversation History
-:page-aliases: a4d-mcp-server.adoc
 
 MuleSoft Vibes allows you to return to tasks you have previously started and continue working from where you left off.