Merge branch 'MS2026-02-17-ACB' into W-21232676-Replace-Dev-Agent-with-MuleSoft-Vibes-CP

Author: Crispy-Salesforce

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/acb-external-libraries.adoc

@@ -0,0 +1,92 @@
+= Configure External Libraries for Mule Projects
+:page-deployment-options: cloud-ide, desktop-ide
+
+External libraries are project-level dependencies that Mule applications require to support certain connectors and components, such as Database connectors or Spring-based components.
+Anypoint Code Builder provides a guided interface to add, edit, and delete external libraries, and automatically manages the corresponding entries in the project POM file.
+
+External library configurations apply at the project level. Any change to a configured library affects all components in the project that require that library.
+
+== Before You Begin
+
+* xref:start-acb.adoc[].
+* xref:int-create-integrations.adoc[].
+* Add a connector or component that requires an external library, such as a Database or Spring component.
+
+== When You Need to Configure an External Library
+
+Anypoint Code Builder prompts you to configure an external library when you add or configure a component that requires additional dependencies.
+For example, this can occur when you:
+
+* Add a Database connector connection
+* Configure a Spring-based component
+* Use a custom component that depends on external libraries
+
+You can also manage external libraries from the project-level configuration, independent of a specific component.
+
+== Add an External Library
+
+You can add an external library from the component configuration or from the project-level library configuration interface.
+
+Add external libraries from one of these sources:
+
+* Recommended libraries
+* Maven dependencies
+* Local files
+
+Open the library configuration interface from a component:
+
+. In the canvas, select a component that requires an external library.
+. In the component configuration panel, locate the *Required Libraries* list.
+. Click the *Configure library* icon.
++
+Anypoint Code Builder opens the *Library Configuration* page.
+Changes made on this page apply to the entire project.
+
+=== Add a Recommended Library
+
+Some components provide recommended libraries that match the component requirements.
+
+. Open the *Library Configuration* page.
+. Select *Recommended Library*.
++
+The interface shows the library to add to the project.
+. Click *Apply*.
++
+The IDE adds the recommended library to the project POM file and applies it to all components that require it.
+
+=== Add a Maven Dependency
+
+Search Maven Central or manually specify Maven coordinates to add a dependency.
+
+. Open the *Library Configuration* page.
+. Select *Maven Dependency*.
+. In the *Search Maven Central Repository* field, search for a dependency or enter the required Maven fields manually.
+. Specify values for *Group ID*, *Artifact ID*, and *Version*.
+. Optionally, configure additional fields such as *Scope*.
+. Click *Apply*.
+
+Only libraries that meet the required criteria appear in component library fields after configuration.
+
+=== Add a Library from a Local File
+
+Add a dependency from a local file, such as a JAR or an external POM file.
+
+. Open the *Library Configuration* page.
+. Select *Local File*.
+. Select a file from your system.
++
+Anypoint Code Builder automatically populates the Maven fields based on the selected file.
+. Override the populated values if required.
+. Click *Apply*.
+
+If you select an external POM file, it takes precedence over any POM embedded in the artifact file.
+
+== Edit or Delete an External Library
+
+Edit or remove an existing library configuration.
+
+. Open the *Library Configuration* page.
+. Select the configured library.
+. Use the available actions to update or delete the library.
++
+Deleting a library removes it from the project POM file and affects all components that use the library.

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