[All Hosts] (manifest) Describe required post-conversion editing of manifest (#5456)

* [All Hosts] (manifest) Describe required post-conversion editing

* update ATK article too

* bookmark fix

* metadata date

* bookmark fix

* Apply suggestions from code review

Co-authored-by: Sam Ramon <15154970+samantharamon@users.noreply.github.com>

* renamed bookmark

---------

Co-authored-by: Sam Ramon <15154970+samantharamon@users.noreply.github.com>

Author: Rick-Kirkham

docs/develop/convert-xml-to-json-manifest.md

@@ -2,28 +2,29 @@
 title: Convert an add-in to use the unified manifest for Microsoft 365
 description: Learn the various methods for converting an add-in with an add-in only manifest to the unified manifest for Microsoft 365 and sideload the add-in.
 ms.topic: how-to
-ms.date: 09/16/2025
+ms.date: 11/06/2025
 ms.localizationpriority: medium
 ---
 
 # Convert an add-in to use the unified manifest for Microsoft 365
 
-To add Teams capabilities or a Copilot extension to an add-in that uses the add-in only manifest, or to just future proof the add-in, you need to convert it to use the unified manifest for Microsoft 365.
+To upgrade an add-in that uses the add-in only manifest to a full App for Microsoft 365 to which you can add Teams capabilities or a Copilot extension, you need to convert it to use the unified manifest for Microsoft 365.
 
    [!INCLUDE [Unified manifest support note for Office applications](../includes/unified-manifest-support-note.md)]
 
-There are three basic tasks to converting an add-in project from the add-in only manifest to the unified manifest.
+There are four basic tasks to converting an add-in project from the add-in only manifest to the unified manifest.
 
 - Ensure that your manifest is ready to convert.
 - Convert the XML-formatted add-in only manifest itself to the JSON format of the unified manifest.
-- Package the new manifest and two icon image files (described later) into a zip file for sideloading or deployment. *Depending on how you sideload the converted add-in, this task may be done for you automatically.*
+- Edit the newly created unified manifest.
+- Package the new manifest and two icon image files (described later) into an app package (zip) file for sideloading or deployment. *Depending on how you sideload the converted add-in, this task may be done for you automatically.*
 
 [!INCLUDE [non-unified manifest clients note](../includes/non-unified-manifest-clients.md)]
 
 > [!NOTE]
 >
 > - Add-ins that use the unified manifest can be sideloaded only on Office Version 2304 (Build 16320.20000) or later.
-> - Projects created in Visual Studio, as distinct from Visual Studio Code, can't be converted at this time.
+> - Visual Studio doesn't support the unified manifest for Office Add-ins. Projects that were created in Visual Studio shouldn't be converted.
 > - If you [created the project with Teams Toolkit or Microsoft 365 Agents Toolkit](agents-toolkit-overview.md) or with the "unified manifest" option in the [Office Yeoman Generator](yeoman-generator-overview.md), it already uses the unified manifest.
 
 ## Ensure that your manifest is ready to convert
@@ -86,11 +87,14 @@ Review and change, as needed, manifest values in light of the following effects
 - The first 4000 characters of `<Description>` becomes the value of [`"description.full"`](/microsoft-365/extensibility/schema/root-description#full) in the unified manifest.
 - The first 32 characters of the `<ProviderName>` becomes the value of [`"developer.name"`](/microsoft-365/extensibility/schema/root-developer#name) in the unified manifest.
 
+> [!NOTE]
+> If any of these elements have child `<Override>` elements, be sure to adjust the localized strings as needed.
+
 ### Ensure conformity of custom functions configuration
 
-If your add-in has custom functions, then it includes a JSON configuration file. Some requirements for this file weren't always enforced by Office or Microsoft Marketplace in the past, but they are all enforced when the add-in has a unified manifest. Before you convert the manifest, ensure that this JSON file conforms to all requirements. For more information, see [Custom functions naming and localization](../excel/custom-functions-naming.md) and [Manually create JSON metadata for custom functions](../excel/custom-functions-json.md)
+If your add-in has custom functions, then it includes a JSON configuration file. Some requirements for this file weren't always enforced by Office or Microsoft Marketplace in the past, but they are all enforced when the add-in has a unified manifest. Before you convert the manifest, ensure that this JSON file conforms to all requirements. For more information, see [Custom functions naming and localization](../excel/custom-functions-naming.md) and [Manually create JSON metadata for custom functions](../excel/custom-functions-json.md).
 
-In particualar, note that [all function names and function ids must have at least 3 characters](../excel/custom-functions-naming.md#custom-functions-naming-guidelines) and that [each function object must have a "result" property](../excel/custom-functions-json.md#metadata-reference). 
+In particular, note that [all function names and function ids must have at least 3 characters](../excel/custom-functions-naming.md#custom-functions-naming-guidelines) and that [each function object must have a "result" property](../excel/custom-functions-json.md#metadata-reference). 
 
 ### Verify that the modified add-in only manifest works
 
@@ -108,7 +112,7 @@ There are several ways to carry out the remaining tasks, depending on the IDE an
 - [Convert NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins (Yo Office)](#convert-nodejs-and-npm-projects-that-werent-created-with-the-yeoman-generator-for-office-add-ins-yo-office)
 
 > [!NOTE]
-> Conversion of the manifest is one of the effects of importing the add-in project into Agents Toolkit if you do so using the toolkit's importation feature. For details, see [Import an add-in project to Agents Toolkit](import-teams-toolkit.md) 
+> Conversion of the manifest is one of the effects of importing the add-in project into Agents Toolkit if you do so using the toolkit's importation feature. For details, see [Import an add-in project to Agents Toolkit](import-teams-toolkit.md). 
 
 ### Convert projects created with the Yeoman generator for Office Add-ins (aka "Yo Office")
 
@@ -119,24 +123,40 @@ If the project was created with the Yeoman generator for Office Add-ins, convert
     ```command&nbsp;line
     npx office-addin-project convert -m <relative-path-to-XML-manifest>
     ```
-
-1. Run `npm install`.
-1. To sideload the add-in, see [Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office)](../testing/sideload-add-in-with-unified-manifest.md#sideload-add-ins-created-with-the-yeoman-generator-for-office-add-ins-yo-office).
+1. Carry out the steps in [Edit the new unified manifest](#edit-the-new-unified-manifest).
 
 ### Convert NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins (Yo Office)
 
 If your project wasn't created with Yo Office, use the office-addin-manifest-converter tool.
 
-In the root of the project, open a command prompt or bash shell and run the following command. This command puts the unified manifest in a subfolder with the same name as the filename stem of the original add-in only manifest. For example, if the manifest is named **MyManifest.xml**, the unified manifest is created at **.\MyManifest\MyManifest.json**. For more details about this command, see [Office-Addin-Manifest-Converter](https://www.npmjs.com/package/office-addin-manifest-converter).
+1. In the root of the project, open a command prompt or bash shell and run the following command. This command puts the unified manifest in a subfolder with the same name as the filename stem of the original add-in only manifest. For example, if the manifest is named **MyManifest.xml**, the unified manifest is created at **.\MyManifest\MyManifest.json**. For more details about this command, see [Office-Addin-Manifest-Converter](https://www.npmjs.com/package/office-addin-manifest-converter).
 
-```command&nbsp;line
-npx office-addin-manifest-converter convert <relative-path-to-XML-manifest>
-```
+   ```command&nbsp;line
+   npx office-addin-manifest-converter convert <relative-path-to-XML-manifest>
+   ```
+1. Carry out the steps in [Edit the new unified manifest](#edit-the-new-unified-manifest).
+
+## Edit the new unified manifest
+
+1. Open the unified manifest file.
+1. Navigate to the [`"developer"`](/microsoft-365/extensibility/schema/root-developer) property and ensure there are child `"privacyUrl"` and `"termsOfUseUrl"` properties. These properties must have appropriate values with a localhost domain.
+1. You can now [sideload the add-in](#sideload-the-add-in).
+
+## Sideload the add-in
+
+The sideloading process depends on how the project was created.
+
+### Sideload an add-in that was created with the Yeoman generator for Office Add-ins
+
+1. Run `npm install`.
+1. To sideload the add-in, see [Sideload add-ins created with the Yeoman generator for Office Add-ins (Yo Office)](../testing/sideload-add-in-with-unified-manifest.md#sideload-add-ins-created-with-the-yeoman-generator-for-office-add-ins-yo-office). The app package zip file is created for you as part of this process.
+
+### Sideload NodeJS and npm projects that weren't created with the Yeoman generator for Office Add-ins
 
 Once you have the unified manifest created, there are two ways to create the zip file and sideload it. For more information, see [Sideload other NodeJS and npm projects](../testing/sideload-add-in-with-unified-manifest.md#sideload-other-nodejs-and-npm-projects).
 
 > [!NOTE]
-> If the original add-in only manifest used any `<Override>` elements to localize strings in the manifest, then the conversion process produces JSON string files for each localized language. These files must also be included in the zip file, and they must be at the relative path indicated in the [`"localizationInfo.additionalLanguages.file"`](/microsoft-365/extensibility/schema/root-localization-info-additional-languages#file) property.
+> If the original add-in only manifest used any `<Override>` elements to localize strings in the manifest, then the conversion process produces JSON string files for each localized language. These files must also be included in the app package zip file, and they must be at the relative path indicated in the [`"localizationInfo.additionalLanguages.file"`](/microsoft-365/extensibility/schema/root-localization-info-additional-languages#file) property.
 
 ## Next steps
 

docs/develop/import-teams-toolkit.md

@@ -2,7 +2,7 @@
 title: Import an add-in project to Microsoft 365 Agents Toolkit
 description: Learn how to import an add-in project to Microsoft 365 Agents Toolkit.
 ms.topic: how-to
-ms.date: 10/10/2025
+ms.date: 11/06/2025
 ms.localizationpriority: medium
 ---
 
@@ -38,7 +38,7 @@ There are four tasks to using the importation feature.
 - [Prepare the existing manifest](#prepare-the-existing-manifest)
 - [Import the project](#import-the-project)
 - [Verify that the add-in can be sideloaded](#verify-that-the-add-in-can-be-sideloaded)
-- [Post importation: Adjust the project structure as needed](#post-importation-adjust-the-project-structure-and-settings-as-needed)
+- [Make post-importation adjustments](#make-post-importation-adjustments)
 
 ### Prepare the existing manifest
 
@@ -74,9 +74,18 @@ Sideload the add-in using the instructions at [Sideload with Microsoft 365 Agent
 
 If you encounter problems, as a troubleshooting step, try [sideloading with a system prompt, bash shell, or terminal](../testing/sideload-add-in-with-unified-manifest.md#sideload-with-a-system-prompt-bash-shell-or-terminal). If you can, then the problem is isolated to the toolkit.
 
-It's possible that sideloading problems are the result of a file and folder structure, or configuration settings, that are different from what Agents Toolkit normally expects. See the section [Post importation: Adjust the project structure and settings as needed](#post-importation-adjust-the-project-structure-and-settings-as-needed).
+It's possible that sideloading problems are the result of a file and folder structure, or configuration settings, that are different from what Agents Toolkit normally expects. See [Adjust the project structure and settings as needed](#adjust-the-project-structure-and-settings-as-needed).
 
-### Post importation: Adjust the project structure and settings as needed
+### Make post-importation adjustments
+
+After you import your add-in project, perform the following tasks.
+
+#### Edit the manifest
+
+1. Open the unified manifest file.
+1. Navigate to the [`"developer"`](/microsoft-365/extensibility/schema/root-developer) property. Ensure that there are child `"privacyUrl"` and `"termsOfUseUrl"` properties and that they have appropriate values.
+
+#### Adjust the project structure and settings as needed
 
 The importation process creates some folders and files that Visual Studio Code or Agents Toolkit need, but it doesn't reorganize your source files; such as HTML, JavaScript, and CSS files. It also doesn't change the content of any files in the project, including tool configuration files. We recommend that you change your project to match the pattern of projects that are created in Agents Toolkit. As you work, keep the following points in mind.
 
@@ -105,7 +114,7 @@ The importation process creates some folders and files that Visual Studio Code o
 
 As an alternative to using the toolkit's importation feature, you can create a brand new add-in project in the toolkit and move files from the existing project into it and make changes to other files. The following are the tasks that you need to carry out.
 
-1. If the existing project uses the add-in only manifest, convert it. See [Convert an add-in to use the unified manifest for Microsoft 365](convert-xml-to-json-manifest.md).
+1. If the existing project uses the add-in only manifest, convert it and ensure that the old project sideloads with the new manifest. For detailed guidance, see [Convert an add-in to use the unified manifest for Microsoft 365](convert-xml-to-json-manifest.md).
 1. Create a new add-in project in Agents Toolkit. For each choice the toolkit asks you to make, such as the choice between JavaScript and TypeScript, make the choice that best matches your existing add-in. See [Create Office Add-in projects with Microsoft 365 Agents Toolkit](agents-toolkit-overview.md).
 1. Replace the manifest in the new project's **\appPackage** folder with your converted manifest.